mcmodels.core.VoxelModelCache¶

class mcmodels.core.VoxelModelCache(resolution=100, cache=True, manifest_file='voxel_model_manifest.json', ccf_version=None, base_uri=None, version=None)[source]¶

Cache class extending MouseConnectivityCache to cache voxel model data.

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”.

Examples

>>> from mcmodels.core import VoxelModelCache
>>> cache = VoxelModelCache(manifest_file='connectivity/voxel_model_manifest.json')
>>> # download the fitted voxel-scale model
>>> voxel_array, source_mask, target_mask = cache.get_voxel_connectivity_array()
>>> # get regionalized adjacency matrix
>>> regional_ncd = cache.get_normalized_connection_density()
>>> # get VoxelData object to use in model building
>>> cortex_voxel_data = cache.get_experiment_data(injection_structure_ids=[315])
>>> # JSON serialize input parameters so that cache can be reinstantiated later
>>> cache.to_json()
'{
        "resolution": 100,
        "cache": true,
        "manifest_file": "voxel_model_manifest.json",
        "ccf_version": "annotation/ccf_2017",
        "base_uri": null,
        "version": 1.2
}'

Attributes:	`default_structure_ids` Default structure ids.

Methods

`add_manifest_paths`(self, manifest_builder)	Construct a manifest for this Cache class and save it in a file.
`build_manifest`(self, file_name)	Creation of default path specifications.
`cacher`(fn, \args, \\*kwargs)	make an rma query, save it and return the dataframe.
`filter_experiments`(self, experiments[, cre, …])	Take a list of experiments and filter them by cre status and injection structure.
`filter_structure_unionizes`(self, unionizes)	Take a list of unionzes and return a subset of records filtered by injection status, structure, and hemisphere.
`from_json`(file_name)	Construct object from JSON serialized parameter file.
`get_affine_parameters`(self, section_data_set_id)	Extract the parameters of the 3D affine tranformation mapping this section data set’s image-space stack to CCF-space (or vice-versa).
`get_annotation_volume`(self[, file_name])	Read the annotation volume.
`get_cache_path`(self, file_name, …)	Helper method for accessing path specs from manifest keys.
`get_connection_density`(self[, file_name, …])	Get regionalized voxel-model weights as connection density.
`get_connection_strength`(self[, file_name, …])	Get regionalized voxel-model weights as connection strength.
`get_data_mask`(self, experiment_id[, file_name])	Read a data mask volume for a single experiment.
`get_deformation_field`(self, section_data_set_id)	Extract the local alignment parameters for this dataset.
`get_experiment_data`(self[, cre, …])	Pulls voxel-scale grid data for experiments.
`get_experiment_structure_unionizes`(self, …)	Retrieve the structure unionize data for a specific experiment.
`get_experiments`(self[, dataframe, …])	Read a list of experiments that match certain criteria.
`get_injection_density`(self, experiment_id[, …])	Read an injection density volume for a single experiment.
`get_injection_fraction`(self, experiment_id)	Read an injection fraction volume for a single experiment.
`get_nodes`(self[, file_name])	Get nodes for voxel-scale model from cache.
`get_normalized_connection_density`(self[, …])	Get regionalized voxel-model weights as normalized connection density.
`get_normalized_connection_strength`(self[, …])	Get regionalized voxel-model weights as normalized connection strength.
`get_projection_density`(self, experiment_id)	Read a projection density volume for a single experiment.
`get_reference_space`(self[, …])	Build a ReferenceSpace from this cache’s annotation volume and structure tree.
`get_source_mask`(self[, file_name])	Get source mask for voxel-scale model from cache.
`get_structure_mask`(self, structure_id[, …])	Read a 3D numpy array shaped like the annotation volume that has non-zero values where voxels belong to a particular structure.
`get_structure_mesh`(self, structure_id[, …])	Obtain a 3D mesh specifying the surface of an annotated structure.
`get_structure_tree`(self[, file_name, …])	Read the list of adult mouse structures and return an StructureTree instance.
`get_structure_unionizes`(self, experiment_ids)	Get structure unionizes for a set of experiment IDs.
`get_target_mask`(self[, file_name])	Get target mask for voxel-scale model from cache.
`get_template_volume`(self[, file_name])	Read the template volume.
`get_voxel_connectivity_array`(self[, …])	Get voxel-scale model from cache, returning VoxelConnectivityArray.
`get_weights`(self[, file_name])	Get weights for voxel-scale model from cache.
`json_rename_columns`(data[, new_old_name_tuples])	Convenience method to rename columns in a pandas dataframe.
`load_csv`(self, path[, rename, index])	Read a csv file as a pandas dataframe.
`load_json`(self, path[, rename, index])	Read a json file as a pandas dataframe.
`load_manifest`(self, file_name[, version])	Read a keyed collection of path specifications.
`manifest_dataframe`(self)	Convenience method to view manifest as a pandas dataframe.
`pathfinder`(file_name_position[, …])	helper method to find path argument in legacy methods written
`rank_structures`(self, experiment_ids, …[, …])	Produces one or more (per experiment) ranked lists of brain structures, using a specified data field.
`remove_keys`(data[, keys])	DataFrame version
`rename_columns`(data[, new_old_name_tuples])	Convenience method to rename columns in a pandas dataframe.
`to_json`(self[, file_name])	JSON serialize object parameters to file or string.
`wrap`(self, fn, path, cache[, save_as_json, …])	make an rma query, save it and return the dataframe.

cache_csv
cache_csv_dataframe
cache_csv_json
cache_json
cache_json_dataframe
csv_writer
get_projection_matrix
json_remove_keys
nocache_dataframe
nocache_json
validate_structure_id
validate_structure_ids

__init__(self, resolution=100, cache=True, manifest_file='voxel_model_manifest.json', ccf_version=None, base_uri=None, version=None)[source]¶

Methods

`__init__`(self[, resolution, cache, …])
`add_manifest_paths`(self, manifest_builder)	Construct a manifest for this Cache class and save it in a file.
`build_manifest`(self, file_name)	Creation of default path specifications.
`cache_csv`()
`cache_csv_dataframe`()
`cache_csv_json`()
`cache_json`()
`cache_json_dataframe`()
`cacher`(fn, \args, \\*kwargs)	make an rma query, save it and return the dataframe.
`csv_writer`(pth, gen)
`filter_experiments`(self, experiments[, cre, …])	Take a list of experiments and filter them by cre status and injection structure.
`filter_structure_unionizes`(self, unionizes)	Take a list of unionzes and return a subset of records filtered by injection status, structure, and hemisphere.
`from_json`(file_name)	Construct object from JSON serialized parameter file.
`get_affine_parameters`(self, section_data_set_id)	Extract the parameters of the 3D affine tranformation mapping this section data set’s image-space stack to CCF-space (or vice-versa).
`get_annotation_volume`(self[, file_name])	Read the annotation volume.
`get_cache_path`(self, file_name, …)	Helper method for accessing path specs from manifest keys.
`get_connection_density`(self[, file_name, …])	Get regionalized voxel-model weights as connection density.
`get_connection_strength`(self[, file_name, …])	Get regionalized voxel-model weights as connection strength.
`get_data_mask`(self, experiment_id[, file_name])	Read a data mask volume for a single experiment.
`get_deformation_field`(self, section_data_set_id)	Extract the local alignment parameters for this dataset.
`get_experiment_data`(self[, cre, …])	Pulls voxel-scale grid data for experiments.
`get_experiment_structure_unionizes`(self, …)	Retrieve the structure unionize data for a specific experiment.
`get_experiments`(self[, dataframe, …])	Read a list of experiments that match certain criteria.
`get_injection_density`(self, experiment_id[, …])	Read an injection density volume for a single experiment.
`get_injection_fraction`(self, experiment_id)	Read an injection fraction volume for a single experiment.
`get_nodes`(self[, file_name])	Get nodes for voxel-scale model from cache.
`get_normalized_connection_density`(self[, …])	Get regionalized voxel-model weights as normalized connection density.
`get_normalized_connection_strength`(self[, …])	Get regionalized voxel-model weights as normalized connection strength.
`get_projection_density`(self, experiment_id)	Read a projection density volume for a single experiment.
`get_projection_matrix`(self, experiment_ids)
`get_reference_space`(self[, …])	Build a ReferenceSpace from this cache’s annotation volume and structure tree.
`get_source_mask`(self[, file_name])	Get source mask for voxel-scale model from cache.
`get_structure_mask`(self, structure_id[, …])	Read a 3D numpy array shaped like the annotation volume that has non-zero values where voxels belong to a particular structure.
`get_structure_mesh`(self, structure_id[, …])	Obtain a 3D mesh specifying the surface of an annotated structure.
`get_structure_tree`(self[, file_name, …])	Read the list of adult mouse structures and return an StructureTree instance.
`get_structure_unionizes`(self, experiment_ids)	Get structure unionizes for a set of experiment IDs.
`get_target_mask`(self[, file_name])	Get target mask for voxel-scale model from cache.
`get_template_volume`(self[, file_name])	Read the template volume.
`get_voxel_connectivity_array`(self[, …])	Get voxel-scale model from cache, returning VoxelConnectivityArray.
`get_weights`(self[, file_name])	Get weights for voxel-scale model from cache.
`json_remove_keys`(data, keys)
`json_rename_columns`(data[, new_old_name_tuples])	Convenience method to rename columns in a pandas dataframe.
`load_csv`(self, path[, rename, index])	Read a csv file as a pandas dataframe.
`load_json`(self, path[, rename, index])	Read a json file as a pandas dataframe.
`load_manifest`(self, file_name[, version])	Read a keyed collection of path specifications.
`manifest_dataframe`(self)	Convenience method to view manifest as a pandas dataframe.
`nocache_dataframe`()
`nocache_json`()
`pathfinder`(file_name_position[, …])	helper method to find path argument in legacy methods written
`rank_structures`(self, experiment_ids, …[, …])	Produces one or more (per experiment) ranked lists of brain structures, using a specified data field.
`remove_keys`(data[, keys])	DataFrame version
`rename_columns`(data[, new_old_name_tuples])	Convenience method to rename columns in a pandas dataframe.
`to_json`(self[, file_name])	JSON serialize object parameters to file or string.
`validate_structure_id`(structure_id)
`validate_structure_ids`(structure_ids)
`wrap`(self, fn, path, cache[, save_as_json, …])	make an rma query, save it and return the dataframe.

add_manifest_paths(self, manifest_builder)[source]¶: Construct a manifest for this Cache class and save it in a file.

default_structure_ids¶: Default structure ids.

classmethod from_json(file_name)[source]¶

Construct object from JSON serialized parameter file.

Parameters:	file_name : string Path to .json file containing VoxelModelCache parameters.
Returns:	A VoxelModelCache object

get_connection_density(self, file_name=None, dataframe=True)[source]¶

Get regionalized voxel-model weights as connection density.

Parameters:	file_name: string, optional (default = None) File name to store the voxel model target_mask. 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. dataframe: boolean, optional (default = True) Return the regionalized weights as a Pandas DataFrame. If False, return an unlabeled numpy.ndarray.

get_connection_strength(self, file_name=None, dataframe=True)[source]¶

Get regionalized voxel-model weights as connection strength.

Parameters:	file_name: string, optional (default = None) File name to store the voxel model target_mask. 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. dataframe: boolean, optional (default = True) Return the regionalized weights as a Pandas DataFrame. If False, return an unlabeled numpy.ndarray.

get_experiment_data(self, cre=None, injection_structure_ids=None, **kwargs)[source]¶

Pulls voxel-scale grid data for experiments.

Parameters:

cre: boolean or list: If True, return only cre-positive experiments. If False, return only cre-negative experiments. If None, return all experiments. If list, return all experiments with cre line names in the supplied list. Default None.
cache - VoxelModelCache or MouseConnectivityCache object: Provides way to pull experiment grid-data from Allen Brain Atlas
injection_structure_ids : list, optional, default None: List of structure_ids to which the injection mask will be constrained.
projection_structure_ids : list, optional, default None: List of structure_ids to which the projection mask will be constrained.
injection_hemisphere_id : int, optional, default 3: Hemisphere (1:left, 2:right, 3:both) to which the injection mask will be constrained.
projection_hemisphere_id : int, optional, default 3: Hemisphere (1:left, 2:right, 3:both) to which the projection mask will be constrained.
normalized_injection : boolean, optional, default True: If True, the injection density will be normalized by the total injection density for each experiment.
normalized_projection : boolean, optional, default True: If True, the projection density will be normalized by the total injection density for each experiment.
flip_experiments : boolean, optional, default True: If True, experiment grid-data will be reflected across the midline. Useful if you wish to include L hemisphere injections into a R hemisphere model.
data_mask_tolerance : float, optional, default 0.0: Tolerance with which to include data in voxels informatically labeled as having error. The data_mask for each experiment is an array with values between (0, 1), where 1 indicates the voxel fully contains an error, whereas 0 indicates the voxel does not contain any error. A value of 0.0 thus indicates the highest threshold for data, whereas a value of 1.0 indicates that data will be included from all voxels.
injection_volume_bounds : float, optional, default (0.0, np.inf): Includes experiments with total injection volume (mm^3) within bounds.
projection_volume_bounds : float, optional, default (0.0, np.inf): Includes experiments with total projection volume (mm^3) within bounds.
min_contained_injection_ratio : float, optional, default 0.0: Includes experiments with total injection volume ratio within injection mask.

Returns:

A VoxelData object with attributes centroids, injections, projections.