Getting Started

This tutorial walks through a complete Brain Street View workflow: finding experiments, downloading data, and producing publication-ready figures of projection patterns to the striatum.

Prerequisites

Install the package (Python 3.9–3.12). A fresh conda environment is recommended:

conda create -n bsv python=3.11
conda activate bsv
pip install brain-street-view

Set your paths once and reuse them throughout the workflow:

allen_atlas_path = '/path/to/allenCCF'  # atlas files are auto-downloaded here on first use (~2.4 GB)
save_location = '/path/to/cache'        # where Allen API projection data will be cached

The Allen CCF atlas files are downloaded automatically the first time a plotting function is called. You can also download them manually from figshare.

Step 1: Find experiments

Query the Allen API for anterograde tracing experiments injected in one or more brain regions. Here we search for injections in primary visual cortex (VISp) and lateral visual cortex (VISl):

import bsv

experiment_ids = bsv.find_connectivity_experiments(
    regions=['VISp', 'VISl'],
    mouse_line='',            # '' = all transgenic lines
    primary_injection=True)   # only primary injection sites

print(f'Found {len(experiment_ids)} experiments')

To restrict to wild-type mice only, pass mouse_line='0'.

Step 2: Download and cache projection data

Fetch the projection density volumes for every experiment. Data is downloaded once from the Allen API and cached locally for future runs:

(experiment_imgs,       # ndarray (AP x DV x ML x groups): averaged projection fluorescence volumes
 injection_summary,     # dict of lists: injection metadata per experiment (coordinates, volumes, etc.)
 _,                     # ndarray or None: per-experiment volumes (only if load_all=True)
 _                      # dict: per-experiment region and group metadata
) = bsv.fetch_connectivity_data(
    experiment_ids=experiment_ids,
    save_location=save_location,
    file_name='visual_cortex_query',  # base name for cached metadata CSV
    normalization_method='injectionIntensity',  # 'none' or 'injectionIntensity' (divide by injection volume)
    subtract_other_hemisphere=False,            # subtract contralateral hemisphere signal
    allen_atlas_path=allen_atlas_path)

Step 3: Visualize projections in 2D

Plot the mean projection density to the caudate putamen (CP) across 10 evenly spaced coronal slices:

(proj_array,    # ndarray (n_slices x n_bins x n_bins x groups): binned projection density per slice
 proj_coords    # list of bin edge arrays: spatial coordinates of each slice panel
) = bsv.plot_connectivity(
    experiment_data=experiment_imgs,
    allen_atlas_path=allen_atlas_path,
    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 bins (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')

Each panel shows the mean projection density within the CP boundary, with darker values indicating stronger projections. Change plane='sagittal' for a sagittal view.

Step 4: 3D rendering

Overlay injection sites on a transparent isosurface of the target region:

bsv.plot_connectivity_3d(
    injection_summary=injection_summary,
    allen_atlas_path=allen_atlas_path,
    region_to_plot='CP',
    plot_patch=True,
    animate=True)

In a Jupyter notebook this returns a rotating HTML animation. Set animate=False to get a static matplotlib figure instead.

Step 5: Threshold significant projections

Identify voxels with strong projection signal using a percentile threshold:

bsv.threshold_connectivity(
    experiment_data=experiment_imgs,
    allen_atlas_path=allen_atlas_path,
    input_region='CP',
    number_of_chunks=10,
    number_of_pixels=15,
    plane='coronal',
    region_only=True,
    smoothing=2,
    color_limits='global',
    color=None,
    threshold=90,
    threshold_method='percentile')

Other methods: 'absolute' (raw density cutoff), 'zscore', or 'relative' (fraction of maximum).

Step 6: Compare grouped regions

Group source regions and visualise one row per group:

grouped_regions = ['VISp', 'VISl', 'VISal', 'VISam', 'VISpl', 'VISpm']
region_groups = [1, 2, 2, 3, 3, 3]

experiment_ids = bsv.find_connectivity_experiments(regions=grouped_regions)
experiment_imgs, _, _, region_info = bsv.fetch_connectivity_data(
    experiment_ids=experiment_ids,
    save_location=save_location,
    file_name='',
    normalization_method='injectionIntensity',
    subtract_other_hemisphere=False,
    allen_atlas_path=allen_atlas_path,
    input_regions=grouped_regions,
    region_groups=region_groups)

bsv.plot_connectivity(
    experiment_data=experiment_imgs,
    allen_atlas_path=allen_atlas_path,
    output_region='CP',
    number_of_chunks=10,
    number_of_pixels=15,
    plane='coronal',
    region_only=True,
    smoothing=2,
    color_limits='global',
    color=None,
    normalization_info='injectionIntensity',
    input_regions=grouped_regions,
    region_groups=region_groups,
    experiment_region_info=region_info)

Next steps