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.
See also
-
get_nodes
(self, file_name=None)[source]¶ Get nodes for voxel-scale model from cache.
Parameters: - file_name: string, optional (default=None)
File name to store the voxel model nodes. 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.
Returns: - nodes (type=numpy.ndarray)
-
get_normalized_connection_density
(self, file_name=None, dataframe=True)[source]¶ Get regionalized voxel-model weights as normalized 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_normalized_connection_strength
(self, file_name=None, dataframe=True)[source]¶ Get regionalized voxel-model weights as normalized 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_source_mask
(self, file_name=None)[source]¶ Get source mask for voxel-scale model from cache.
Parameters: - file_name: string, optional (default=None)
File name to store the voxel model source_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.
Returns: - Mask object.
-
get_target_mask
(self, file_name=None)[source]¶ Get target mask for voxel-scale model from cache.
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.
Returns: - Mask object.
-
get_voxel_connectivity_array
(self, nodes_file_name=None, weights_file_name=None, source_mask_file_name=None, target_mask_file_name=None)[source]¶ Get voxel-scale model from cache, returning VoxelConnectivityArray.
Parameters: - nodes_file_name : string, optional (default=None)
File name to store the voxel model nodes. See
get_nodes
- weights_file_name : string, optional (default=None)
File name to store the voxel model weights. See
get_weights
- source_mask_file_name : string, optional (default=None)
File name to store the source_mask. See
get_source_mask
- target_mask_file_name : string, optional (default=None)
File name to store the target_mask. See
get_target_mask
Returns: - tuple : (VoxelConnectivityArray, Mask, Mask)
(get_voxel_connectivity_array, source_mask, target_mask)
-
get_weights
(self, file_name=None)[source]¶ Get weights for voxel-scale model from cache.
Parameters: - file_name: string, optional (default=None)
File name to store the voxel model weights. 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.
Returns: - weights (type=numpy.ndarray)
-
to_json
(self, file_name=None)[source]¶ JSON serialize object parameters to file or string.
Parameters: - file_name : string, optional (default None)
Path to .json file containing VoxelModelCache parameters. If None, a string will be returned.
Returns: - string
If file_name == None, a string of the JSON serialization is returned.