allensdk.core.brain_observatory_cache module

class allensdk.core.brain_observatory_cache.BrainObservatoryCache(cache=True, manifest_file=None, base_uri=None, api=None)

Bases: Cache

Cache class for storing and accessing data from the Brain Observatory. 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:

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_ophys_experiment_data(file_name=’file.nwb’)).

manifest_file: string

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

Attributes:

api: BrainObservatoryApi instance

The object used for making API queries related to the Brain Observatory.

ANALYSIS_DATA_KEY = 'ANALYSIS_DATA'

CELL_SPECIMENS_KEY = 'CELL_SPECIMENS'

EVENTS_DATA_KEY = 'EVENTS_DATA'

EXPERIMENTS_KEY = 'EXPERIMENTS'

EXPERIMENT_CONTAINERS_KEY = 'EXPERIMENT_CONTAINERS'

EXPERIMENT_DATA_KEY = 'EXPERIMENT_DATA'

EYE_GAZE_DATA_KEY = 'EYE_GAZE_DATA'

MANIFEST_VERSION = '1.3'

STIMULUS_MAPPINGS_KEY = 'STIMULUS_MAPPINGS'

build_manifest(file_name)

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

Parameters:

file_name: string

File location to save the manifest.

get_all_cre_lines()

Return a list of all cre driver lines in the data set.

get_all_imaging_depths()

Return a list of all imaging depths in the data set.

get_all_reporter_lines()

Return a list of all reporter lines in the data set.

get_all_session_types()

Return a list of all stimulus sessions in the data set.

get_all_stimuli()

Return a list of all stimuli in the data set.

get_all_targeted_structures()

Return a list of all targeted structures in the data set.

get_cell_specimens(file_name=None, ids=None, experiment_container_ids=None, include_failed=False, simple=True, filters=None)

Return cell specimens that have certain properies.

Parameters:

file_name: string

File name to save/read the cell specimens. 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.

ids: list

List of cell specimen ids.

experiment_container_ids: list

List of experiment container ids.

include_failed: bool

Whether to include cells from failed experiment containers

simple: boolean

Whether or not to simplify the dictionary properties returned by this method to a more concise subset.

filters: list of dicts

List of filter dictionaries. The Allen Brain Observatory web site can generate filters in this format to reproduce a filtered set of cells found there. To see what these look like, visit http://observatory.brain-map.org/visualcoding, perform a cell search and apply some filters (e.g. find cells in a particular area), then click the “view these cells in the AllenSDK” link on the bottom-left of the search results page. This will take you to a page that contains a code sample you can use to apply those same filters via this argument. For more detail on the filter syntax, see BrainObservatoryApi.dataframe_query.

Returns:

list of dictionaries

get_experiment_containers(file_name=None, ids=None, targeted_structures=None, imaging_depths=None, cre_lines=None, reporter_lines=None, transgenic_lines=None, include_failed=False, simple=True)

Get a list of experiment containers matching certain criteria.

Parameters:

file_name: string

File name to save/read the experiment containers. 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.

ids: list

List of experiment container ids.

targeted_structures: list

List of structure acronyms. Must be in the list returned by BrainObservatoryCache.get_all_targeted_structures().

imaging_depths: list

List of imaging depths. Must be in the list returned by BrainObservatoryCache.get_all_imaging_depths().

cre_lines: list

List of cre lines. Must be in the list returned by BrainObservatoryCache.get_all_cre_lines().

reporter_lines: list

List of reporter lines. Must be in the list returned by BrainObservatoryCache.get_all_reporter_lines().

transgenic_lines: list

List of transgenic lines. Must be in the list returned by BrainObservatoryCache.get_all_cre_lines() or. BrainObservatoryCache.get_all_reporter_lines().

include_failed: boolean

Whether or not to include failed experiment containers.

simple: boolean

Whether or not to simplify the dictionary properties returned by this method to a more concise subset.

Returns:

list of dictionaries

get_eye_tracking(ophys_experiment_id) → ndarray

Download the eye tracking data for an ophys_experiment if it hasn’t already been downloaded and return it.

Parameters:

ophys_experiment_id

Returns:

numpy.ndarray

Contents of array unknown. Assumed to be [n_frames, 5] where the meaning of the values in each column are unknown. Ask Saskia De Vries saskiad@alleninstitute.org

get_nwb_filepath(ophys_experiment_id=None)

get_ophys_experiment_analysis(ophys_experiment_id, stimulus_type, file_name=None)

Download the h5 analysis file for a stimulus set, for a particular ophys_experiment (if it hasn’t already been downloaded) and return a data accessor object.

Parameters:

file_name: string

File name to save/read the data set. 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.

ophys_experiment_id: int

id of the ophys_experiment to retrieve

stimulus_name: str

stimulus type; should be an element of self.list_stimuli()

Returns:

BrainObservatoryNwbDataSet

get_ophys_experiment_data(ophys_experiment_id, file_name=None)

Download the NWB file for an ophys_experiment (if it hasn’t already been downloaded) and return a data accessor object.

Parameters:

file_name: string

File name to save/read the data set. 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.

ophys_experiment_id: integer

id of the ophys_experiment to retrieve

Returns:

BrainObservatoryNwbDataSet

get_ophys_experiment_events(ophys_experiment_id, file_name=None)

Download the npz events file for an ophys_experiment if it hasn’t already been downloaded and return the events array.

Parameters:

file_name: string

File name to save/read the data set. 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.

ophys_experiment_id: int

id of the ophys_experiment to retrieve events for

Returns

——-

events: numpy.ndarray

[N_cells,N_times] array of events.

get_ophys_experiment_stimuli(experiment_id)

For a single experiment, return the list of stimuli present in that experiment.

get_ophys_experiments(file_name=None, ids=None, experiment_container_ids=None, targeted_structures=None, imaging_depths=None, cre_lines=None, reporter_lines=None, transgenic_lines=None, stimuli=None, session_types=None, cell_specimen_ids=None, include_failed=False, require_eye_tracking=False, simple=True)

Get a list of ophys experiments matching certain criteria.

Parameters:

file_name: string

File name to save/read the ophys experiments. 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.

ids: list

List of ophys experiment ids.

experiment_container_ids: list

List of experiment container ids.

targeted_structures: list

List of structure acronyms. Must be in the list returned by BrainObservatoryCache.get_all_targeted_structures().

imaging_depths: list

List of imaging depths. Must be in the list returned by BrainObservatoryCache.get_all_imaging_depths().

cre_lines: list

List of cre lines. Must be in the list returned by BrainObservatoryCache.get_all_cre_lines().

reporter_lines: list

List of reporter lines. Must be in the list returned by BrainObservatoryCache.get_all_reporter_lines().

transgenic_lines: list

List of transgenic lines. Must be in the list returned by BrainObservatoryCache.get_all_cre_lines() or. BrainObservatoryCache.get_all_reporter_lines().

stimuli: list

List of stimulus names. Must be in the list returned by BrainObservatoryCache.get_all_stimuli().

session_types: list

List of stimulus session type names. Must be in the list returned by BrainObservatoryCache.get_all_session_types().

cell_specimen_ids: list

Only include experiments that contain cells with these ids.

include_failed: boolean

Whether or not to include experiments from failed experiment containers.

simple: boolean

Whether or not to simplify the dictionary properties returned by this method to a more concise subset.

require_eye_tracking: boolean

If True, only return experiments that have eye tracking results. Default: False.

Returns:

list of dictionaries

get_ophys_pupil_data(ophys_experiment_id: int, file_name: str = None, suppress_pupil_data: bool = True) → DataFrame

Download the h5 eye gaze mapping file for an ophys_experiment if it hasn’t already been downloaded and return it as a pandas.DataFrame.

Parameters:

file_name: string

File name to save/read the data set. 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.

ophys_experiment_id: int

id of the ophys_experiment to retrieve pupil data for.

suppress_pupil_data: bool

Whether or not to suppress pupil data from dataset. Default is True.

Returns:

pd.DataFrame

If ‘suppress_eye_gaze_data’ is set to ‘False’:

Contains raw/filtered columns for gaze mapping:

*_eye_area *_pupil_area *_screen_coordinates_x_cm *_screen_coordinates_y_cm *_screen_coordinates_spherical_x_deg *_screen_coorindates_spherical_y_deg

Otherwise:

An empty pandas DataFrame