Brain Image Library#

In this example we will show you how to fetch data from the Brain Image Library.

The Brain Image Library (https://www.brainimagelibrary.org, BIL) is a public repository hosted at the Pittsburgh Supercomputing Center. It is primarily known for its (very large) microscopy data but it also hosts thousands of single neuron reconstructions - for example the fMOST-based mouse reconstructions produced by the BRAIN Initiative Cell Census Network (BICCN).

NAVis provides an interface that wraps BIL's metadata API and its download server:

import navis

# Import the Brain Image Library interface
import navis.interfaces.brain_image_library as bil

Searching for datasets#

Datasets are identified by a "bildid" - a little word triplet such as ace-boo-van. To find datasets, use search. Any number of fields can be combined: across fields they are combined with AND, and within a field multiple values are combined with OR.

Note that BIL matches values exactly - there is no substring or fuzzy matching. Use search(text=...) for a free-text search.

ds = bil.search(species="mouse", generalmodality="cell morphology", technique="fMOST", limit=5)
ds[["bildid", "title", "species", "technique", "number_of_files"]]

	bildid	title	species	technique	number_of_files
0	ace-ace	Mouse data from sample: 190366, modality: cell...	mouse	fMOST	14.0
1	ace-ace-fog	Mouse data from sample: 732664811, modality: c...	mouse	fMOST	NaN
2	ace-ace-foo	Mouse data from sample: 732702664, modality: c...	mouse	fMOST	NaN
3	ace-ace-fox	Mouse data from sample: 732707727, modality: c...	mouse	fMOST	NaN
4	ace-ace-fry	Mouse data from sample: 732706821, modality: c...	mouse	fMOST	NaN

See bil.FIELDS for all available search fields. If you need a field that isn't in there, you can drop down to the raw API via bil.query(division, element, value).

Inspecting a dataset#

Let's look at one dataset in more detail. get_metadata flattens BIL's rather deeply nested metadata into a single row per dataset:

meta = bil.get_metadata("ace-boo-van")
meta[["title", "species", "genotype", "dataset_size_gb", "number_of_files", "rights"]]

	title	species	genotype	dataset_size_gb	number_of_files	rights
0	Single neuron reconstruction from fMOST images	mouse	PlxnD1-2A-CreER	0.447271	117	Creative Commons Attribution-ShareAlike 4.0 In...

Datasets can be huge

BIL hosts datasets of hundreds of terabytes and millions of files. list_files and download_files therefore refuse to crawl or download very large datasets unless you explicitly override their guardrails. For bulk transfers you should use Globus instead.

It's good practice to look at a dataset's files before pulling anything. list_files crawls the dataset's directory listing and tells you exactly what is there (and how big it is):

files = bil.list_files("ace-boo-van", pattern="*.swc")
files[["name", "directory", "size"]].head()

	name	directory	size
0	mouseID_212083_01.swc	212083-19/	5245516
1	mouseID_212083_02.swc	212083-19/	3954899
2	mouseID_212083_03.swc	212083-19/	7104504
3	mouseID_212083_04.swc	212083-19/	3744416
4	mouseID_212083_05.swc	212083-19/	4818901

Fetching neurons#

Now we can load the reconstructions. Passing the file table (rather than the dataset ID) means we fetch exactly the files we just looked at:

nl = bil.get_neurons(files, max_neurons=3)
nl

<class 'navis.core.neuronlist.NeuronList'> containing 3 neurons (6.8MiB)

	type	name	id	n_nodes	n_connectors	n_branches	n_leafs	cable_length	soma	units	created_at	origin	file
0	navis.TreeNeuron	mouseID_212083_01	ace-boo-van/mouseID_212083_01	95778	None	312	321	93083.523438	1	1 dimensionless	2026-07-23 08:52:53.852152	https://download.brainimagelibrary.org/22/5c/2...	mouseID_212083_01.swc
1	navis.TreeNeuron	mouseID_212083_02	ace-boo-van/mouseID_212083_02	72312	None	218	228	71353.765625	1	1 dimensionless	2026-07-23 08:52:54.006340	https://download.brainimagelibrary.org/22/5c/2...	mouseID_212083_02.swc
2	navis.TreeNeuron	mouseID_212083_03	ace-boo-van/mouseID_212083_03	128540	None	300	311	113636.234375	1	1 dimensionless	2026-07-23 08:52:55.366178	https://download.brainimagelibrary.org/22/5c/2...	mouseID_212083_03.swc

A word on units

BIL does not reliably record the units of its reconstructions. If you know them, pass e.g. units='um' straight through to navis.read_swc. The image.stepsizex field in the metadata (here "0.35 micron/pixel") tells you the voxel size if the coordinates happen to be in voxels.

If you want the files themselves rather than the neurons, use download_files:

# bil.download_files(files, "~/bil_data")

Do note that datasets carry their own licenses - check the rights and dataset.rightsuri fields before you re-use any data.

Let's plot the neurons we fetched:

navis.plot2d(nl, view=("x", "-z"), method="2d", color_by="id", palette="tab10", lw=1.5)

Out:

(<Figure size 640x480 with 1 Axes>, <Axes: xlabel='x', ylabel='z'>)