allensdk.core.mouse_connectivity_cache module

class allensdk.core.mouse_connectivity_cache.MouseConnectivityCache(resolution=None, cache=True, manifest_file='mouse_connectivity_manifest.json', ccf_version=None, base_uri=None, version=None)

Bases: allensdk.core.reference_space_cache.ReferenceSpaceCache

Cache class for storing and accessing data related to the adult mouse Connectivity Atlas. By default, this class will cache any downloaded metadata or files in well known locations defined in a manifest file. This behavior can be disabled.

Parameters:

resolution: int

Resolution of grid data to be downloaded when accessing projection volume, the annotation volume, and the annotation volume. Must be one of (10, 25, 50, 100). Default is 25.

ccf_version: string

Desired version of the Common Coordinate Framework. This affects the annotation volume (get_annotation_volume) and structure masks (get_structure_mask). Must be one of (MouseConnectivityApi.CCF_2015, MouseConnectivityApi.CCF_2016). Default: MouseConnectivityApi.CCF_2016

cache: boolean

Whether the class should save results of API queries to locations specified in the manifest file. Queries for files (as opposed to metadata) must have a file location. If caching is disabled, those locations must be specified in the function call (e.g. get_projection_density(file_name=’file.nrrd’)).

manifest_file: string

File name of the manifest to be read. Default is “mouse_connectivity_manifest.json”.

Attributes:

resolution: int

Resolution of grid data to be downloaded when accessing projection volume, the annotation volume, and the annotation volume. Must be one of (10, 25, 50, 100). Default is 25.

api: MouseConnectivityApi instance

Used internally to make API queries.

DATA_MASK_KEY = 'DATA_MASK'

DEFAULT_STRUCTURE_SET_IDS = (167587189,)

EXPERIMENTS_KEY = 'EXPERIMENTS'

INJECTION_DENSITY_KEY = 'INJECTION_DENSITY'

INJECTION_FRACTION_KEY = 'INJECTION_FRACTION'

MANIFEST_VERSION = 1.3

PROJECTION_DENSITY_KEY = 'PROJECTION_DENSITY'

STRUCTURE_UNIONIZES_KEY = 'STRUCTURE_UNIONIZES'

SUMMARY_STRUCTURE_SET_ID = 167587189

add_manifest_paths(manifest_builder)

Construct a manifest for this Cache class and save it in a file.

Parameters:

file_name: string

File location to save the manifest.

default_structure_ids

filter_experiments(experiments, cre=None, injection_structure_ids=None)

Take a list of experiments and filter them by cre status and injection structure.

Parameters:

cre: boolean or list

If True, return only cre-positive experiments. If False, return only cre-negative experiments. If None, return all experients. If list, return all experiments with cre line names in the supplied list. Default None.

injection_structure_ids: list

Only return experiments that were injected in the structures provided here. If None, return all experiments. Default None.

filter_structure_unionizes(unionizes, is_injection=None, structure_ids=None, include_descendants=False, hemisphere_ids=None)

Take a list of unionzes and return a subset of records filtered by injection status, structure, and hemisphere.

Parameters:

is_injection: boolean

If True, only return unionize records that disregard non-injection pixels. If False, only return unionize records that disregard injection pixels. If None, return all records. Default None.

structure_ids: list

Only return unionize records for a set of structures. If None, return all records. Default None.

include_descendants: boolean

Include all descendant records for specified structures. Default False.

hemisphere_ids: list

Only return unionize records that disregard pixels outside of a hemisphere. or set of hemispheres. Left = 1, Right = 2, Both = 3. If None, include all records [1, 2, 3]. Default None.

get_data_mask(experiment_id, file_name=None)

Read a data mask volume for a single experiment. Download it first if it doesn’t exist. Data mask is a binary mask of voxels that have valid data. Only use valid data in analysis!

Parameters:

experiment_id: int

ID of the experiment to download/read. This corresponds to section_data_set_id in the API.

file_name: string

File name to store the template volume. If it already exists, it will be read from this file. If file_name is None, the file_name will be pulled out of the manifest. Default is None.

get_experiment_structure_unionizes(experiment_id, file_name=None, is_injection=None, structure_ids=None, include_descendants=False, hemisphere_ids=None)

Retrieve the structure unionize data for a specific experiment. Filter by structure, injection status, and hemisphere.

Parameters:

experiment_id: int

ID of the experiment of interest. Corresponds to section_data_set_id in the API.

file_name: string

File name to save/read the experiments list. If file_name is None, the file_name will be pulled out of the manifest. If caching is disabled, no file will be saved. Default is None.

is_injection: boolean

If True, only return unionize records that disregard non-injection pixels. If False, only return unionize records that disregard injection pixels. If None, return all records. Default None.

structure_ids: list

Only return unionize records for a specific set of structures. If None, return all records. Default None.

include_descendants: boolean

Include all descendant records for specified structures. Default False.

hemisphere_ids: list

Only return unionize records that disregard pixels outside of a hemisphere. or set of hemispheres. Left = 1, Right = 2, Both = 3. If None, include all records [1, 2, 3]. Default None.

get_experiments(dataframe=False, file_name=None, cre=None, injection_structure_ids=None)

Read a list of experiments that match certain criteria. If caching is enabled, this will save the whole (unfiltered) list of experiments to a file.

Parameters:

dataframe: boolean

Return the list of experiments as a Pandas DataFrame. If False, return a list of dictionaries. Default False.

file_name: string

File name to save/read the structures table. If file_name is None, the file_name will be pulled out of the manifest. If caching is disabled, no file will be saved. Default is None.

cre: boolean or list

If True, return only cre-positive experiments. If False, return only cre-negative experiments. If None, return all experients. If list, return all experiments with cre line names in the supplied list. Default None.

injection_structure_ids: list

Only return experiments that were injected in the structures provided here. If None, return all experiments. Default None.

get_injection_density(experiment_id, file_name=None)

Read an injection density volume for a single experiment. Download it first if it doesn’t exist. Injection density is the proportion of projecting pixels in a grid voxel only including pixels that are part of the injection site in [0,1].

Parameters:

experiment_id: int

ID of the experiment to download/read. This corresponds to section_data_set_id in the API.

file_name: string

File name to store the template volume. If it already exists, it will be read from this file. If file_name is None, the file_name will be pulled out of the manifest. Default is None.

get_injection_fraction(experiment_id, file_name=None)

Read an injection fraction volume for a single experiment. Download it first if it doesn’t exist. Injection fraction is the proportion of pixels in the injection site in a grid voxel in [0,1].

Parameters:

experiment_id: int

ID of the experiment to download/read. This corresponds to section_data_set_id in the API.

file_name: string

File name to store the template volume. If it already exists, it will be read from this file. If file_name is None, the file_name will be pulled out of the manifest. Default is None.

get_projection_density(experiment_id, file_name=None)

Read a projection density volume for a single experiment. Download it first if it doesn’t exist. Projection density is the proportion of of projecting pixels in a grid voxel in [0,1].

Parameters:

experiment_id: int

ID of the experiment to download/read. This corresponds to section_data_set_id in the API.

file_name: string

File name to store the template volume. If it already exists, it will be read from this file. If file_name is None, the file_name will be pulled out of the manifest. Default is None.

get_projection_matrix(experiment_ids, projection_structure_ids=None, hemisphere_ids=None, parameter='projection_volume', dataframe=False)

get_structure_unionizes(experiment_ids, is_injection=None, structure_ids=None, include_descendants=False, hemisphere_ids=None)

Get structure unionizes for a set of experiment IDs. Filter the results by injection status, structure, and hemisphere.

Parameters:

experiment_ids: list

List of experiment IDs. Corresponds to section_data_set_id in the API.

is_injection: boolean

If True, only return unionize records that disregard non-injection pixels. If False, only return unionize records that disregard injection pixels. If None, return all records. Default None.

structure_ids: list

Only return unionize records for a specific set of structures. If None, return all records. Default None.

include_descendants: boolean

Include all descendant records for specified structures. Default False.

hemisphere_ids: list

Only return unionize records that disregard pixels outside of a hemisphere. or set of hemispheres. Left = 1, Right = 2, Both = 3. If None, include all records [1, 2, 3]. Default None.

rank_structures(experiment_ids, is_injection, structure_ids=None, hemisphere_ids=None, rank_on='normalized_projection_volume', n=5, threshold=0.01)

Produces one or more (per experiment) ranked lists of brain structures, using a specified data field.

Parameters:

experiment_ids : list of int

Obtain injection_structures for these experiments.

is_injection : boolean

Use data from only injection (or non-injection) unionizes.

structure_ids : list of int, optional

Consider only these structures. It is a good idea to make sure that these structures are not spatially overlapping; otherwise your results will contain redundant information. Defaults to the summary structures - a brain-wide list of nonoverlapping mid-level structures.

hemisphere_ids : list of int, optional

Consider only these hemispheres (1: left, 2: right, 3: both). Like with structures, you might get redundant results if you select overlapping options. Defaults to [1, 2].

rank_on : str, optional

Rank unionize data using this field (descending). Defaults to normalized_projection_volume.

n : int, optional

Return only the top n structures.

threshold : float, optional

Consider only records whose data value - specified by the rank_on parameter - exceeds this value.

Returns:

list :

Each element (1 for each input experiment) is a list of dictionaries. The dictionaries describe the top injection structures in descending order. They are specified by their structure and hemisphere id fields and additionally report the value specified by the rank_on parameter.