ibllib.io.extractors.mesoscope

Mesoscope (timeline) data extraction.

Functions

patch_imaging_meta

Patch imaging metadata for compatibility across versions.

plot_timeline

Plot the timeline data.

Classes

MesoscopeSyncTimeline

Extraction of mesoscope imaging times.

TimelineTrials

Similar extraction to the FPGA, however counter and position channels are treated differently.

patch_imaging_meta(meta: dict) dict[source]

Patch imaging metadata for compatibility across versions.

A copy of the dict is NOT returned.

Parameters:

meta (dict) – A folder path that contains a rawImagingData.meta file.

Returns:

The loaded metadata file, updated to the most recent version.

Return type:

dict

plot_timeline(timeline, channels=None, raw=True)[source]

Plot the timeline data.

Parameters:
  • timeline (one.alf.io.AlfBunch) – The timeline data object.

  • channels (list of str) – An iterable of channel names to plot.

  • raw (bool) – If true, plot the raw DAQ samples; if false, apply TTL thresholds and plot changes.

Returns:

  • matplotlib.pyplot.Figure – The figure containing timeline subplots.

  • list of matplotlib.pyplot.Axes – The axes for each timeline channel plotted.

class TimelineTrials(*args, sync_collection='raw_sync_data', **kwargs)[source]

Bases: FpgaTrials

Similar extraction to the FPGA, however counter and position channels are treated differently.

sync_field = 'itiIn_times'

The trial event to synchronize (must be present in extracted trials).

Type:

str

timeline = None

The timeline data object.

Type:

one.alf.io.AlfBunch

load_sync(sync_collection='raw_sync_data', chmap=None, **_)[source]

Load the DAQ sync and channel map data.

Parameters:
  • sync_collection (str) – The session subdirectory where the sync data are located.

  • chmap (dict) – A map of channel names and their corresponding indices. If None, the channel map is loaded using the ibllib.io.raw_daq_loaders.timeline_meta2chmap() method.

Returns:

  • one.alf.io.AlfBunch – A dictionary with keys (‘times’, ‘polarities’, ‘channels’), containing the sync pulses and the corresponding channel numbers.

  • dict – A map of channel names and their corresponding indices.

get_bpod_event_times(sync, chmap, bpod_event_ttls=None, display=False, **kwargs)[source]

Extract Bpod times from sync.

Unlike the superclass method. This one doesn’t reassign the first trial pulse.

Parameters:
  • sync (dict) – A dictionary with keys (‘times’, ‘polarities’, ‘channels’), containing the sync pulses and the corresponding channel numbers. Must contain a ‘bpod’ key.

  • chmap (dict) – A map of channel names and their corresponding indices.

  • bpod_event_ttls (dict of tuple) – A map of event names to (min, max) TTL length.

Returns:

  • dict – A dictionary with keys {‘times’, ‘polarities’} containing Bpod TTL fronts.

  • dict – A dictionary of events (from bpod_event_ttls) and their intervals as an Nx2 array.

build_trials(sync=None, chmap=None, **kwargs)[source]

Extract task related event times from the sync.

The two major differences are that the sampling rate is lower for imaging so the short Bpod trial start TTLs are often absent. For this reason, the sync happens using the ITI_in TTL.

Second, the valve used at the mesoscope has a way to record the raw voltage across the solenoid, giving a more accurate readout of the valve’s activity. If the reward_valve channel is present on the DAQ, this is used to extract the valve open times.

Parameters:
  • sync (dict) – ‘polarities’ of fronts detected on sync trace for all 16 chans and their ‘times’

  • chmap (dict) – Map of channel names and their corresponding index. Default to constant.

Returns:

A map of trial event timestamps.

Return type:

dict

extract_wheel_sync(ticks=1024, radius=1, coding='x4', tmin=None, tmax=None)[source]

Gets the wheel position from Timeline counter channel.

Parameters:
  • ticks (int) – Number of ticks corresponding to a full revolution (1024 for IBL rotary encoder).

  • radius (float) – Radius of the wheel. Defaults to 1 for an output in radians.

  • coding (str {'x1', 'x2', 'x4'}) – Rotary encoder encoding (IBL default is x4).

  • tmin (float) – The minimum time from which to extract the sync pulses.

  • tmax (float) – The maximum time up to which we extract the sync pulses.

Returns:

  • np.array – Wheel timestamps in seconds.

  • np.array – Wheel positions in radians.

get_wheel_positions(ticks=1024, radius=1, coding='x4', tmin=None, tmax=None, display=False, **kwargs)[source]

Gets the wheel position and detected movements from Timeline counter channel.

Called by the super class extractor (FPGATrials._extract).

Parameters:
  • ticks (int) – Number of ticks corresponding to a full revolution (1024 for IBL rotary encoder).

  • radius (float) – Radius of the wheel. Defaults to 1 for an output in radians.

  • coding (str {'x1', 'x2', 'x4'}) – Rotary encoder encoding (IBL default is x4).

  • tmin (float) – The minimum time from which to extract the sync pulses.

  • tmax (float) – The maximum time up to which we extract the sync pulses.

  • display (bool) – If true, plot the wheel positions from bpod and the DAQ.

Returns:

  • dict – wheel object with keys (‘timestamps’, ‘position’).

  • dict – wheelMoves object with keys (‘intervals’ ‘peakAmplitude’).

get_valve_open_times(display=False, threshold=100, driver_ttls=None)[source]

Get the valve open times from the raw timeline voltage trace.

Parameters:
  • display (bool) – Plot detected times on the raw voltage trace.

  • threshold (float) – The threshold of voltage change to apply. The default was set by eye; units should be Volts per sample but doesn’t appear to be.

  • driver_ttls (numpy.array) – An optional array of driver TTLs to use for assigning with the valve times.

Returns:

  • numpy.array – The detected valve open intervals.

  • numpy.array – If driver_ttls is not None, returns an array of open times that occurred directly after the driver TTLs.

class MesoscopeSyncTimeline(session_path, n_FOVs)[source]

Bases: BaseExtractor

Extraction of mesoscope imaging times.

rawImagingData = None
var_names = ('mpci_times', 'mpciStack_timeshift')

A list of names for the extracted variables. These become the returned output keys.

Type:

tuple of str

save_names = ('mpci.times.npy', 'mpciStack.timeshift.npy')

The raw imaging meta data and frame times

Type:

one.alf.io.AlfBunch

get_bout_edges(frame_times, collections=None, events=None, min_gap=1.0, display=False)[source]

Return an array of edge times for each imaging bout corresponding to a raw_imaging_data collection.

Parameters:
  • frame_times (numpy.array) – An array of all neural frame count times.

  • collections (iterable of str) – A set of raw_imaging_data collections, used to extract selected imaging periods.

  • events (pandas.DataFrame) – A table of UDP event times, corresponding to times when recordings start and end.

  • min_gap (float) – If start or end events not present, split bouts by finding gaps larger than this value.

  • display (bool) – If true, plot the detected bout edges and raw frame times.

Returns:

An array of imaging bout intervals.

Return type:

numpy.array

static get_timeshifts(raw_imaging_meta)[source]

Calculate the time shifts for each field of view (FOV) and the relative offsets for each scan line.

For a 2 scan field, 2 depth recording (so 4 FOVs):

Frame 1, lines 1-512 correspond to FOV_00 Frame 1, lines 551-1062 correspond to FOV_01 Frame 2, lines 1-512 correspond to FOV_02 Frame 2, lines 551-1062 correspond to FOV_03 Frame 3, lines 1-512 correspond to FOV_00 …

Parameters:

raw_imaging_meta (dict) – Extracted ScanImage meta data (_ibl_rawImagingData.meta.json).

Returns:

  • list of numpy.array – A list of arrays, one per FOV, containing indices of each image scan line.

  • numpy.array – An array of FOV time offsets (one value per FOV) relative to each frame acquisition time.

  • list of numpy.array – A list of arrays, one per FOV, containing the time offsets for each scan line, relative to each FOV offset.