Load and plot Allen Connectivity Data (Oh et al., Nature, 2014)
Available in both MATLAB and Python. Documentation
Scroll through the brain to see projections into a target region from several source areas at once, each in its own colour (interactive slice viewer).
Python:
pip install brain-street-viewThen open example.ipynb or run example.py. The first run downloads images from the Allen API and caches them locally. Subsequent runs load from cache.
MATLAB:
See the script gettingStarted.mlx. Requires MATLAB>=2019a.
Brain Street View supports Python 3.9–3.12. We recommend installing into a fresh conda environment to avoid dependency conflicts:
conda create -n bsv python=3.11
conda activate bsv
pip install brain-street-view(A venv works just as well: python -m venv bsv && source bsv/bin/activate.)
If you prefer not to use an environment, pip install brain-street-view on its own
is fine too.
Or from source:
conda create -n bsv python=3.11
conda activate bsv
git clone https://github.com/Julie-Fabre/brain_street_view.git
cd brain_street_view
pip install -e .The Allen CCF atlas files (~2.4 GB) are downloaded automatically the first time a plotting function is called. They are saved to the allen_atlas_path you specify. You can also download them manually from figshare and place them in your allen_atlas_path.
- Clone the repository and the dependencies below.
- Add BrainStreetView's and the dependencies' folders to MATLAB's path.
MATLAB dependencies:
- allenCCF, to get Allen Atlas files (annotation volumes on figshare)
- npy-matlab, to read in .npy files
- brewermap, to generate colormaps
- prettify-matlab, to make plots pretty.
import bsv
# 1. Find experiments by injected region (source search)
# Checkout region acronyms here: https://connectivity.brain-map.org/
experiment_ids = bsv.find_connectivity_experiments(
regions=['VISp', 'VISl']) # list of injection region acronyms to search for
# 2. Fetch fluorescence data
(imgs, # ndarray (AP x DV x ML x groups): averaged projection fluorescence volumes
inj_summary, # dict of lists: injection metadata per experiment (coordinates, volumes, etc.)
individual_projections, # ndarray or None: per-experiment volumes (only populated if load_all=True)
experiment_region_info # dict: per-experiment region and group metadata
) = bsv.fetch_connectivity_data(
experiment_ids=experiment_ids,
save_location='/path/to/cache', # local directory for caching downloaded data
file_name='', # base name for the cached metadata CSV ('' to skip)
normalization_method='injectionIntensity', # 'none' or 'injectionIntensity' (divide by injection volume)
subtract_other_hemisphere=False, # subtract contralateral hemisphere signal
allen_atlas_path='/path/to/allenCCF') # path to the Allen CCF atlas directory
# 3. Plot projections to striatum
bsv.plot_connectivity(
experiment_data=imgs,
allen_atlas_path='/path/to/allenCCF', # path to the Allen CCF atlas directory
output_region='CP', # target region acronym to visualize
number_of_chunks=10, # number of evenly spaced slices to display
number_of_pixels=15, # number of 2D histogram bins per axis per slice (bin size adapts to region extent)
plane='coronal', # 'coronal' or 'sagittal'
region_only=True, # mask display to target region boundary
smoothing=2, # Gaussian smoothing sigma in pixels (0 for none)
color_limits='global', # 'global', 'per_slice', or [min, max]
color=None, # RGB colour(s) for region groups, or None for default
normalization_info='injectionIntensity')
# 4. 3D visualization
bsv.plot_connectivity_3d(
injection_summary=inj_summary,
allen_atlas_path='/path/to/allenCCF', # path to the Allen CCF atlas directory
region_to_plot='CP', # target region acronym
plot_patch=True) # render region as solid isosurface (False for grid)See example.ipynb for the full workflow including region grouping, thresholding, and CP subregion analysis.
% 1. Find experiments
experimentIDs = bsv.findConnectivityExperiments({'VISp', 'VISl'}); % list of injection region acronyms
% 2. Fetch data
[experimentImgs, ... % ndarray (AP x DV x ML x groups): averaged projection fluorescence volumes
injectionSummary, ... % struct: injection metadata per experiment (coordinates, volumes, etc.)
individualProjections, ... % ndarray or []: per-experiment volumes (only populated if loadAll=true)
experimentRegionInfo ... % struct: per-experiment region and group metadata
] = bsv.fetchConnectivityData( ...
experimentIDs, ... % experiment IDs from findConnectivityExperiments
saveLocation, ... % local directory for caching downloaded data
fileName, ... % base name for cached metadata CSV ('' to skip)
'injectionIntensity', ... % normalization: 'none' or 'injectionIntensity'
false, ... % subtract contralateral hemisphere signal
'', ... % grouping method: 'AP', 'ML', 'DV', or '' for none
allenAtlasPath); % path to the Allen CCF atlas directory
% 3. Plot
bsv.plotConnectivity( ...
experimentImgs, ... % projection density array from fetchConnectivityData
allenAtlasPath, ... % path to the Allen CCF atlas directory
'CP', ... % target region acronym to visualize
10, ... % number of evenly spaced slices to display
15, ... % number of 2D histogram bins per axis per slice (bin size adapts to region extent)
'coronal', ... % plane: 'coronal' or 'sagittal'
true, ... % region_only: mask display to target region boundary
2, ... % smoothing: Gaussian sigma in pixels (0 for none)
'global', ... % color_limits: 'global', 'per_slice', or [min, max]
[], ... % color: RGB colour(s) for region groups, or [] for default
'injectionIntensity') % normalization method used during fetchSee +bsv/example.m for the full MATLAB workflow.
- projections from visual cortices to striatum: injection sites and striatum plotted in 3D
- example injections in primary visual cortex (VISp)
- example injections in antero-lateral visual cortex (VISal)
- projections from visual cortices (VIS) to striatum (CP)
If you run into any issues or if you have any suggestions, please raise a github issue, create a pull request or email me: juliemfabre[at]gmail[dot]com.