allensdk.brain_observatory.ecephys.ecephys_session module

class allensdk.brain_observatory.ecephys.ecephys_session.EcephysSession(api: allensdk.brain_observatory.ecephys.ecephys_session_api.ecephys_session_api.EcephysSessionApi, test: bool = False, **kwargs)

Bases: allensdk.core.lazy_property.lazy_property_mixin.LazyPropertyMixin

Represents data from a single EcephysSession

Attributes:

units : pd.Dataframe

A table whose rows are sorted units (putative neurons) and whose columns are characteristics of those units. Index is:

unit_id : int

Unique integer identifier for this unit.

Columns are:

firing_rate : float

This unit’s firing rate (spikes / s) calculated over the window of that unit’s activity (the time from its first detected spike to its last).

isi_violations : float

Estamate of this unit’s contamination rate (larger means that more of the spikes assigned to this unit probably originated from other neurons). Calculated as a ratio of the firing rate of the unit over periods where spikes would be isi-violating vs the total firing rate of the unit.

peak_channel_id : int

Unique integer identifier for this unit’s peak channel. A unit’s peak channel is the channel on which its peak-to-trough amplitude difference is maximized. This is assessed using the kilosort 2 templates rather than the mean waveforms for a unit.

snr : float

Signal to noise ratio for this unit.

probe_horizontal_position : numeric

The horizontal (short-axis) position of this unit’s peak channel in microns.

probe_vertical_position : numeric

The vertical (long-axis, lower values are closer to the probe base) position of this unit’s peak channel in microns.

probe_id : int

Unique integer identifier for this unit’s probe.

probe_description : str

Human-readable description carrying miscellaneous information about this unit’s probe.

location : str

Gross-scale location of this unit’s probe.

spike_times : dict

Maps integer unit ids to arrays of spike times (float) for those units.

running_speed : RunningSpeed

NamedTuple with two fields

timestamps : numpy.ndarray

Timestamps of running speed data samples

values : np.ndarray

Running speed of the experimental subject (in cm / s).

mean_waveforms : dict

Maps integer unit ids to xarray.DataArrays containing mean spike waveforms for that unit.

stimulus_presentations : pd.DataFrame

Table whose rows are stimulus presentations and whose columns are presentation characteristics. A stimulus presentation is the smallest unit of distinct stimulus presentation and lasts for (usually) 1 60hz frame. Since not all parameters are relevant to all stimuli, this table contains many ‘null’ values. Index is

stimulus_presentation_id : int

Unique identifier for this stimulus presentation

Columns are

start_time : float

Time (s) at which this presentation began

stop_time : float

Time (s) at which this presentation ended

duration : float

stop_time - start_time (s). Included for convenience.

stimulus_name : str

Identifies the stimulus family (e.g. “drifting_gratings” or “natural_movie_3”) used for this presentation. The stimulus family, along with relevant parameter values, provides the information required to reconstruct the stimulus presented during this presentation. The empty string indicates a blank period.

stimulus_block : numeric

A stimulus block is made by sequentially presenting presentations from the same stimulus family. This value is the index of the block which contains this presentation. During a blank period, this is ‘null’.

TF : float

Temporal frequency, or ‘null’ when not appropriate.

SF : float

Spatial frequency, or ‘null’ when not appropriate

Ori : float

Orientation (in degrees) or ‘null’ when not appropriate

Contrast : float Pos_x : float Pos_y : float Color : numeric Image : numeric Phase : float stimulus_condition_id : integer

identifies the session-unique stimulus condition (permutation of parameters) to which this presentation belongs

stimulus_conditions : pd.DataFrame

Each row is a unique permutation (within this session) of stimulus parameters presented during this experiment. Columns are as stimulus presentations, sans start_time, end_time, stimulus_block, and duration.

inter_presentation_intervals : pd.DataFrame

The elapsed time between each immediately sequential pair of stimulus presentations. This is a dataframe with a two-level multiindex (levels are ‘from_presentation_id’ and ‘to_presentation_id’). It has a single column, ‘interval’, which reports the elapsed time between the two presentations in seconds on the experiment’s master clock.

DETAILED_STIMULUS_PARAMETERS = ('colorSpace', 'flipHoriz', 'flipVert', 'depth', 'interpolate', 'mask', 'opacity', 'rgbPedestal', 'tex', 'texRes', 'units', 'rgb', 'signalDots', 'noiseDots', 'fieldSize', 'fieldShape', 'fieldPos', 'nDots', 'dotSize', 'dotLife', 'color_triplet')

age_in_days

channel_structure_intervals(self, channel_ids)

find on a list of channels the intervals of channels inserted into particular structures

Parameters:

channel_ids : list

A list of channel ids

structure_id_key : str

use this column for numerically identifying structures

structure_label_key : str

use this column for human-readable structure identification

Returns:

labels : np.ndarray

for each detected interval, the label associated with that interval

intervals : np.ndarray

one element longer than labels. Start and end indices for intervals.

conditionwise_spike_statistics(self, stimulus_presentation_ids=None, unit_ids=None, use_rates=False)

Produce summary statistics for each distinct stimulus condition

Parameters:

stimulus_presentation_ids : array-like

identifies stimulus presentations from which spikes will be considered

unit_ids : array-like

identifies units whose spikes will be considered

use_rates : bool, optional

If True, use firing rates. If False, use spike counts.

Returns:

pd.DataFrame :

Rows are indexed by unit id and stimulus condition id. Values are summary statistics describing spikes emitted by a specific unit across presentations within a specific condition.

classmethod from_nwb_path(path, nwb_version=2, api_kwargs=None, **kwargs)

full_genotype

get_current_source_density(self, probe_id)

Obtain current source density (CSD) of trial-averaged response to a flash stimuli for this probe. See allensdk.brain_observatory.ecephys.current_source_density for details of CSD calculation.

CSD is computed with a 1D method (second spatial derivative) without prior spatial smoothing User should apply spatial smoothing of their choice (e.g., Gaussian filter) to the computed CSD

Parameters:

probe_id : int

identify the probe whose CSD data ought to be loaded

Returns:

xr.DataArray :

dimensions are channel (id) and time (seconds, relative to stimulus onset). Values are current source density assessed on that channel at that time (V/m^2)

get_inter_presentation_intervals_for_stimulus(self, stimulus_names)

Get a subset of this session’s inter-presentation intervals, filtered by stimulus name.

Parameters:

stimulus_names : array-like of str

The names of stimuli to include in the output.

Returns:

pd.DataFrame :

inter-presentation intervals, filtered to the requested stimulus names.

get_invalid_times(self)

Report invalid time intervals with tags describing the scope of invalid data

The tags format: [scope,scope_id,label]

scope:

‘EcephysSession’: data is invalid across session ‘EcephysProbe’: data is invalid for a single probe

label:

‘all_probes’: gain fluctuations on the Neuropixels probe result in missed spikes and LFP saturation events ‘stimulus’ : very long frames (>3x the normal frame length) make any stimulus-locked analysis invalid ‘probe#’: probe # stopped sending data during this interval (spikes and LFP samples will be missing) ‘optotagging’: missing optotagging data

Returns:

pd.DataFrame :

Rows are invalid intervals, columns are ‘start_time’ (s), ‘stop_time’ (s), ‘tags’

get_lfp(self, probe_id, mask_invalid_intervals=True)

Load an xarray DataArray with LFP data from channels on a single probe

Parameters:

probe_id : int

identify the probe whose LFP data ought to be loaded

mask_invalid_intervals : bool

if True (default) will mask data in the invalid intervals with np.nan

Returns

——-

xr.DataArray :

dimensions are channel (id) and time (seconds). Values are sampled LFP data.

Notes

Unlike many other data access methods on this class. This one does not cache the loaded data in memory due to the large size of the LFP data.

get_parameter_values_for_stimulus(self, stimulus_name, drop_nulls=True)

For each stimulus parameter, report the unique values taken on by that parameter while a named stimulus was presented.

Parameters:

stimulus_name : str

filter to presentations of this stimulus

Returns:

dict :

maps parameters (column names) to their unique values.

get_pupil_data(self, suppress_pupil_data: bool = True) → pandas.core.frame.DataFrame

Return a dataframe with eye tracking data

Parameters:

suppress_pupil_data : bool, optional

Whether or not to suppress eye gaze mapping data in output dataframe, by default True.

Returns:

pd.DataFrame

Contains columns for eye, pupil and cr ellipse fits:

*_center_x *_center_y *_height *_width *_phi

May also contain raw/filtered columns for gaze mapping if suppress_pupil_data is set to False:

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

get_stimulus_epochs(self, duration_thresholds=None)

Reports continuous periods of time during which a single kind of stimulus was presented flipVert

duration_thresholds : dict, optional

keys are stimulus names, values are floating point durations in seconds. All epochs with

• a given stimulus name
• a duration shorter than the associated threshold

will be removed from the results

get_stimulus_parameter_values(self, stimulus_presentation_ids=None, drop_nulls=True)

For each stimulus parameter, report the unique values taken on by that parameter throughout the course of the session.

Parameters:

stimulus_presentation_ids : array-like, optional

If provided, only parameter values from these stimulus presentations will be considered.

Returns:

dict :

maps parameters (column names) to their unique values.

get_stimulus_table(self, stimulus_names=None, include_detailed_parameters=False, include_unused_parameters=False)

Get a subset of stimulus presentations by name, with irrelevant parameters filtered off

Parameters:

stimulus_names : array-like of str

The names of stimuli to include in the output.

Returns:

pd.DataFrame :

Rows are filtered presentations, columns are the relevant subset of stimulus parameters

metadata

num_channels

num_probes

num_stimulus_presentations

num_units

presentationwise_spike_counts(self, bin_edges, stimulus_presentation_ids, unit_ids, binarize=False, dtype=None, large_bin_size_threshold=0.001, time_domain_callback=None)

Build an array of spike counts surrounding stimulus onset per unit and stimulus frame.

bin_edges : numpy.ndarray

Spikes will be counted into the bins defined by these edges. Values are in seconds, relative to stimulus onset.

stimulus_presentation_ids : array-like

Filter to these stimulus presentations

unit_ids : array-like

Filter to these units

binarize : bool, optional

If true, all counts greater than 0 will be treated as 1. This results in lower storage overhead, but is only reasonable if bin sizes are fine (<= 1 millisecond).

large_bin_size_threshold : float, optional

If binarize is True and the largest bin width is greater than this value, a warning will be emitted.

time_domain_callback : callable, optional

The time domain is a numpy array whose values are trial-aligned bin edges (each row is aligned to a different trial). This optional function will be applied to the time domain before counting spikes.

Returns:

xarray.DataArray :

Data array whose dimensions are stimulus presentation, unit, and time bin and whose values are spike counts.

presentationwise_spike_times(self, stimulus_presentation_ids=None, unit_ids=None)

Produce a table associating spike times with units and stimulus presentations

Parameters:

stimulus_presentation_ids : array-like

Filter to these stimulus presentations

unit_ids : array-like

Filter to these units

Returns:

pandas.DataFrame :

Index is

spike_time : float

On the session’s master clock.

Columns are

stimulus_presentation_id : int

The stimulus presentation on which this spike occurred.

unit_id : int

The unit that emitted this spike.

rig_equipment_name

rig_geometry_data

session_type

sex

specimen_name

spike_times

stimulus_conditions

stimulus_names

stimulus_presentations

structure_acronyms

structurewise_unit_counts

units

allensdk.brain_observatory.ecephys.ecephys_session.array_intervals(array)

find interval bounds (bounding consecutive identical values) in an array

Parameters:

array : np.ndarray

Returns:

np.ndarray :

start and end indices of detected intervals (one longer than the number of intervals)

allensdk.brain_observatory.ecephys.ecephys_session.build_spike_histogram(time_domain, spike_times, unit_ids, dtype=None, binarize=False)

allensdk.brain_observatory.ecephys.ecephys_session.build_time_window_domain(bin_edges, offsets, callback=None)

allensdk.brain_observatory.ecephys.ecephys_session.coerce_scalar(value, message, warn=False)

allensdk.brain_observatory.ecephys.ecephys_session.is_distinct_from(left, right)

allensdk.brain_observatory.ecephys.ecephys_session.nan_intervals(array, nan_like=['null'])

find interval bounds (bounding consecutive identical values) in an array, which may contain nans

Parameters:

array : np.ndarray

Returns:

np.ndarray :

start and end indices of detected intervals (one longer than the number of intervals)

allensdk.brain_observatory.ecephys.ecephys_session.removed_unused_stimulus_presentation_columns(stimulus_presentations)