allensdk.brain_observatory.behavior.behavior_ophys_experiment module

class allensdk.brain_observatory.behavior.behavior_ophys_experiment.BehaviorOphysExperiment(behavior_session: BehaviorSession, projections: Projections, ophys_timestamps: OphysTimestamps, cell_specimens: CellSpecimens, metadata: BehaviorOphysMetadata, motion_correction: MotionCorrection, date_of_acquisition: DateOfAcquisition)

Bases: BehaviorSession

Represents data from a single Visual Behavior Ophys imaging session. Initialize by using class methods from_lims or from_nwb_path.

property average_projection: Image

2D image of the microscope field of view, averaged across the experiment :rtype: allensdk.brain_observatory.behavior.image_api.Image

property cell_specimen_table: DataFrame

Cell information organized into a dataframe. Table only contains roi_valid = True entries, as invalid ROIs/ non cell segmented objects have been filtered out

Returns:

pd.DataFrame

dataframe columns:

cell_specimen_id [index]: (int)

unified id of segmented cell across experiments (assigned after cell matching)

cell_roi_id: (int)

experiment specific id of segmented roi (assigned before cell matching)

height: (int)

height of ROI/cell in pixels

mask_image_plane: (int)

which image plane an ROI resides on. Overlapping ROIs are stored on different mask image planes

max_corretion_down: (float)

max motion correction in down direction in pixels. Defines the motion border at the top of the image.

max_correction_left: (float)

max motion correction in left direction in pixels. Defines the motion border at the right of the image.

max_correction_right: (float)

max motion correction in right direction in pixels. Defines the motion border at the left of the image.

max_correction_up: (float)

max motion correction in up direction in pixels. Defines the motion border at the bottom of the image.

roi_mask: (array of bool)

an image array that displays the location of the roi mask in the field of view

valid_roi: (bool)

indicates if cell classification found the segmented ROI to be a cell or not (True = cell, False = not cell).

width: (int)

width of ROI in pixels

x: (float)

x position of ROI in field of view in pixels (top left corner)

y: (float)

y position of ROI in field of view in pixels (top left corner)

property corrected_fluorescence_traces: DataFrame

Corrected fluorescence traces which are neuropil corrected and demixed. Sampling rate can be found in metadata ‘ophys_frame_rate’

Returns:

pd.DataFrame

Dataframe that contains the corrected fluorescence traces for all valid cells.

dataframe columns:

cell_specimen_id [index]: (int)

unified id of segmented cell across experiments (assigned after cell matching)

cell_roi_id: (int)

experiment specific id of segmented roi (assigned before cell matching)

corrected_fluorescence: (list of float)

fluorescence values (arbitrary units)

RMSE: (float)

error values (arbitrary units)

r:

r values (arbitrary units)

property demixed_traces: DataFrame

Demixed traces are traces that are demixed from overlapping ROIs. Sampling rate can be found in metadata ‘ophys_frame_rate’

Returns:

pd.DataFrame

Dataframe that contains the corrected fluorescence traces for all valid cells.

dataframe columns:

cell_specimen_id [index]: (int)

unified id of segmented cell across experiments (assigned after cell matching)

cell_roi_id: (int)

experiment specific id of segmented roi (assigned before cell matching)

demixed_trace: (list of float)

fluorescence values (arbitrary units)

property dff_traces: DataFrame

traces of change in fluoescence / fluorescence

Returns:

pd.DataFrame

dataframe of traces of dff (change in fluorescence / fluorescence)

dataframe columns:

cell_specimen_id [index]: (int)

unified id of segmented cell across experiments assigned after cell matching

cell_roi_id: (int)

experiment specific id of segmented roi, assigned before cell matching

dff: (list of float)

fluorescence fractional values relative to baseline (arbitrary units)

property events: DataFrame

A dataframe containing spiking events in traces derived from the two photon movies, organized by cell specimen id. For more information on event detection processing please see the event detection portion of the white paper.

Returns:

pd.DataFrame

cell_specimen_id [index]: (int)

unified id of segmented cell across experiments (assigned after cell matching)

cell_roi_id: (int)

experiment specific id of segmented roi (assigned before cell matching)

events: (np.array of float)

event trace where events correspond to the rise time of a calcium transient in the dF/F trace, with a magnitude roughly proportional the magnitude of the increase in dF/F.

filtered_events: (np.array of float)

Events array with a 1d causal half-gaussian filter to smooth it for visualization. Uses a halfnorm distribution as weights to the filter

lambdas: (float64)

regularization value selected to make the minimum event size be close to N * noise_std

noise_stds: (float64)

estimated noise standard deviation for the events trace

classmethod from_json(session_data: dict, eye_tracking_z_threshold: float = 3.0, eye_tracking_dilation_frames: int = 2, events_filter_scale_seconds: float = 0.06451612903225806, events_filter_n_time_steps: int = 20, exclude_invalid_rois=True) → BehaviorOphysExperiment

Parameters:

session_data

eye_tracking_z_threshold

See BehaviorOphysExperiment.from_nwb

eye_tracking_dilation_frames

See BehaviorOphysExperiment.from_nwb

events_filter_scale_seconds

See BehaviorOphysExperiment.from_nwb

events_filter_n_time_steps

See BehaviorOphysExperiment.from_nwb

exclude_invalid_rois

Whether to exclude invalid rois

classmethod from_lims(ophys_experiment_id: int, eye_tracking_z_threshold: float = 3.0, eye_tracking_dilation_frames: int = 2, events_filter_scale_seconds: float = 0.06451612903225806, events_filter_n_time_steps: int = 20, exclude_invalid_rois: bool = True) → BehaviorOphysExperiment

Parameters:

ophys_experiment_idint

Id of experiment to load.

eye_tracking_z_thresholdfloat

See BehaviorOphysExperiment.from_nwb

eye_tracking_dilation_framesint

See BehaviorOphysExperiment.from_nwb

events_filter_scale_secondsfloat

See BehaviorOphysExperiment.from_nwb

events_filter_n_time_stepsint

See BehaviorOphysExperiment.from_nwb

exclude_invalid_roisbool

Whether to exclude invalid rois

Returns:

BehaviorOphysExperiment instance

classmethod from_nwb(nwbfile: NWBFile, eye_tracking_z_threshold: float = 3.0, eye_tracking_dilation_frames: int = 2, events_filter_scale_seconds: float = 0.06451612903225806, events_filter_n_time_steps: int = 20, exclude_invalid_rois=True) → BehaviorOphysExperiment

Parameters:

nwbfile

eye_tracking_z_thresholdfloat, optional

The z-threshold when determining which frames likely contain outliers for eye or pupil areas. Influences which frames are considered ‘likely blinks’. By default 3.0

eye_tracking_dilation_framesint, optional

Determines the number of adjacent frames that will be marked as ‘likely_blink’ when performing blink detection for eye_tracking data, by default 2

events_filter_scale_secondsfloat, optional

Stdev of halfnorm distribution used to convolve ophys events with a 1d causal half-gaussian filter to smooth it for visualization, in seconds (by default 2.0/31.0; this value has been found to perform well on Allen Institute data across multiple platforms).

events_filter_n_time_stepsint, optional

Number of time steps to use for convolution of ophys events

exclude_invalid_rois

Whether to exclude invalid rois

get_cell_specimen_ids()

get_cell_specimen_indices(cell_specimen_ids)

get_dff_traces(cell_specimen_ids=None)

get_segmentation_mask_image() → Image

a 2D binary image of all valid cell masks

Returns:

allensdk.brain_observatory.behavior.image_api.Image:

array-like interface to segmentation_mask image data and metadata

property max_projection: Image

2D max projection image. :rtype: allensdk.brain_observatory.behavior.image_api.Image

property metadata

metadata for a given session

Returns:

Dict

A dictionary containing behavior session specific metadata dictionary keys:

age_in_days: (int)

age of mouse in days

behavior_session_uuid: (int)

unique identifier for a behavior session

behavior_session_id: (int)

unique identifier for a behavior session

cre_line: (string)

cre driver line for a transgenic mouse

date_of_acquisition: (date time object)

date and time of experiment acquisition, yyyy-mm-dd hh:mm:ss

driver_line: (list of string)

all driver lines for a transgenic mouse

equipment_name: (string)

identifier for equipment data was collected on

full_genotype: (string)

full genotype of transgenic mouse

mouse_id: (int)

unique identifier for a mouse

project_code: (string)

String of project session is associated with.

reporter_line: (string)

reporter line for a transgenic mouse

session_type: (string)

visual stimulus type displayed during behavior session

sex: (string)

sex of the mouse

stimulus_frame_rate: (float)

frame rate (Hz) at which the visual stimulus is displayed

property motion_correction: DataFrame

a dataframe containing the x and y offsets applied during motion correction

Returns:

pd.DataFrame

dataframe columns:

x: (int)

frame shift along x axis

y: (int)

frame shift along y axis

property neuropil_traces: DataFrame

neuropil traces are the fluorescent signal measured from the neuropil_masks. Sampling rate can be found in metadata ‘ophys_frame_rate’

Returns:

pd.DataFrame

Dataframe that contains the corrected fluorescence traces for all valid cells.

dataframe columns:

cell_specimen_id [index]: (int)

unified id of segmented cell across experiments (assigned after cell matching)

cell_roi_id: (int)

experiment specific id of segmented roi (assigned before cell matching)

neuropil_trace: (list of float)

fluorescence values (arbitrary units)

property ophys_experiment_id: int

Unique identifier for this experimental session. :rtype: int

property ophys_session_id: int

Unique identifier for this ophys session. :rtype: int

property ophys_timestamps: ndarray

Timestamps associated with frames captured by the microscope :rtype: numpy.ndarray

property roi_masks: DataFrame

property segmentation_mask_image: Image

A 2d binary image of all valid cell masks :rtype: allensdk.brain_observatory.behavior.image_api.Image

to_nwb() → NWBFile

Parameters:

add_metadata

Set this to False to prevent adding metadata to the nwb instance.

include_experiment_description: Whether to include a description of the

experiment in the nwbfile

stimulus_presentations_stimulus_column_name: Name of the column

denoting the stimulus name in the presentations table

update_targeted_imaging_depth(ophys_experiment_ids: List[int])

Update the value for targeted imaging depth given a set of experiments to be published.

Compute the targeted_imaging_depth (average over experiments in a container) only for those experiments input.

Parameters:

ophys_experiment_idslist of ints

Subset of experiments sharing the same container as the experiment being loaded in this object.