allensdk.brain_observatory.ecephys.ecephys_session module

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

Bases: LazyPropertyMixin

Represents data from a single EcephysSession

Attributes:

unitspd.Dataframe

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

unit_idint

Unique integer identifier for this unit.

Columns are:

firing_ratefloat

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_violationsfloat

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_idint

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.

snrfloat

Signal to noise ratio for this unit.

probe_horizontal_positionnumeric

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

probe_vertical_positionnumeric

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

probe_idint

Unique integer identifier for this unit’s probe.

probe_descriptionstr

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

locationstr

Gross-scale location of this unit’s probe.

spike_timesdict

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

running_speedRunningSpeed

NamedTuple with two fields

timestampsnumpy.ndarray

Timestamps of running speed data samples

valuesnp.ndarray

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

mean_waveformsdict

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

stimulus_presentationspd.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 60 Hz frame. Since not all parameters are relevant to all stimuli, this table contains many ‘null’ values. Index is

stimulus_presentation_idint

Unique identifier for this stimulus presentation

Columns are

start_timefloat

Time (s) at which this presentation began

stop_timefloat

Time (s) at which this presentation ended

durationfloat

stop_time - start_time (s). Included for convenience.

stimulus_namestr

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_blocknumeric

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

TFfloat

Temporal frequency, or ‘null’ when not appropriate.

SFfloat

Spatial frequency, or ‘null’ when not appropriate

Orifloat

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_conditionspd.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_intervalspd.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')

property age_in_days

channel_structure_intervals(channel_ids)

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

Parameters:

channel_idslist

A list of channel ids

structure_id_keystr

use this column for numerically identifying structures

structure_label_keystr

use this column for human-readable structure identification

Returns:

labelsnp.ndarray

for each detected interval, the label associated with that interval

intervalsnp.ndarray

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

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

Produce summary statistics for each distinct stimulus condition

Parameters:

stimulus_presentation_idsarray-like

identifies stimulus presentations from which spikes will be considered

unit_idsarray-like

identifies units whose spikes will be considered

use_ratesbool, 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)

property full_genotype

get_current_source_density(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_idint

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(stimulus_names)

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

Parameters:

stimulus_namesarray-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()

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(probe_id, mask_invalid_intervals=True)

Load an xarray DataArray with LFP data from channels on a

single probe

Parameters:

probe_idint

identify the probe whose LFP data ought to be loaded

mask_invalid_intervalsbool

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(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_namestr

filter to presentations of this stimulus

Returns:

dict

maps parameters (column names) to their unique values.

get_pupil_data() → DataFrame | None

Return a dataframe with eye tracking ellipse fit data

Returns:

pd.DataFrame

Contains eye, pupil and corneal reflection (cr) ellipse fits:

*_center_x *_center_y *_height *_width *_phi

get_screen_gaze_data(include_filtered_data=False) → DataFrame | None

Return a dataframe with estimated gaze position on screen.

Parameters:

include_filtered_databool, optional

Whether to include filtered version of data (where filtered values are replaced by NaN), by default False.

Returns:

pd.DataFrame

Contains columns for estimated gaze position:

*_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(duration_thresholds=None)

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

Parameters

duration_thresholdsdict, 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(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_idsarray-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(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_namesarray-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

property metadata

property num_channels

property num_probes

property num_stimulus_presentations

property num_units

presentationwise_spike_counts(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.

Parameters

bin_edgesnumpy.ndarray

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

stimulus_presentation_idsarray-like

Filter to these stimulus presentations

unit_idsarray-like

Filter to these units

binarizebool, 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_thresholdfloat, optional

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

time_domain_callbackcallable, 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(stimulus_presentation_ids=None, unit_ids=None)

Produce a table associating spike times with units and stimulus presentations

Parameters:

stimulus_presentation_idsarray-like

Filter to these stimulus presentations

unit_idsarray-like

Filter to these units

Returns:

pandas.DataFrame

Index is

spike_timefloat

On the session’s master clock.

Columns are

stimulus_presentation_idint

The stimulus presentation on which this spike occurred.

unit_idint

The unit that emitted this spike.

property rig_equipment_name

property rig_geometry_data

property session_type

property sex

property specimen_name

property spike_times

property stimulus_conditions

property stimulus_names

property stimulus_presentations

property structure_acronyms

property structurewise_unit_counts

property units

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

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

Parameters:

arraynp.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:

arraynp.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)