ibllib.io.certification_protocol

Extract stimulus timing info from ttl pulses and metadata.

Functions

export_to_alf

Export extracted stimuli and their presentation times to the session alf directory.

extract_stimulus_info_to_alf

Extract the stimulus information stored in metadata and export to alf files. Also checks to make sure ttl pulses were extracted properly. Expected files/structure: - session metadata: session_path/raw_behavior_data/_iblrig_taskSettings.raw.*.json - task stimulus info: session_path/raw_behavior_data/_iblrig_codeFiles.raw.*.zip - rf mapping stim info: session_path/raw_behavior_data/_iblrig_RFMapStim.raw.*.bin - spikeglx sync data: session_path/raw_ephys_data/probe_[right/left]/_spikeglx_sync.[channels/polarities/times].* .npy.

get_contrast_reversal_stimulus

Extract contrast reversal stimulus info

get_expected_ttl_pulses

Get expected number of ttl pulses for each stimulus

get_rf_ttl_pulses

Find where ttl_signal increases or decreases

get_session_path

Return local session path given a local path of any file from the session (assumes Subjects directory is present)

get_spacer_times

param spacer_template

list of indices where ttl signal changes

get_stim_num_from_name

“VISUAL_STIMULI”: { “0”: “SPACER”, “1”: “receptive_field_mapping”, “2”: “orientation-direction_selectivity”, “3”: “contrast_reversal”, “4”: “task_stimuli”, “5”: “spontaneous_activity”}

get_task_stimulus

Extract contrast selectivity stimulus info

interpolate_rf_mapping_stimulus

Interpolate stimulus presentation times to screen refresh rate to match frames

load_rf_mapping_stimulus

extract frames of rf mapping stimulus

load_session_metadata

param session_path

absolute path of a session, i.e. /mnt/data/Subjects/ZM_1887/2019-07-10/001

load_ttl_pulses

Extract ttl pulses from sync signals

get_session_path(path)[source]

Return local session path given a local path of any file from the session (assumes Subjects directory is present)

Parameters

path (str) – absolute path of any file in session e.g. /mnt/data/cortexlab/Subjects/CSHL050/2019-10-29/001/alf/spikes.times.npy

Example usage:

one = ONE() eid = one.search(subject=subject, date=date, number=number) files_paths = one.load(eid[0], download_only=True) session_path = get_session_path(files_paths)

load_session_metadata(session_path)[source]
Parameters

session_path (str) – absolute path of a session, i.e. /mnt/data/Subjects/ZM_1887/2019-07-10/001

Returns

dictionary of metadata

Return type

dict

load_ttl_pulses(session_path)[source]

Extract ttl pulses from sync signals

Parameters

session_path (str) – absolute path of a session, i.e. /mnt/data/Subjects/ZM_1887/2019-07-10/001

Returns

ttl pulse times

Return type

np.ndarray

load_rf_mapping_stimulus(session_path, stim_metadata)[source]

extract frames of rf mapping stimulus

Parameters
  • session_path (str) – absolute path of a session, i.e. /mnt/data/Subjects/ZM_1887/2019-07-10/001

  • stim_metadata (dict) – dictionary of stimulus/task metadata

Returns

stimulus frames

Return type

np.ndarray of shape (y_pix, x_pix, n_frames)

get_stim_num_from_name(stim_ids, stim_name)[source]

“VISUAL_STIMULI”: { “0”: “SPACER”, “1”: “receptive_field_mapping”, “2”: “orientation-direction_selectivity”, “3”: “contrast_reversal”, “4”: “task_stimuli”, “5”: “spontaneous_activity”}

Parameters
  • stim_ids (dict) – map from number (as string) to stimulus name

  • stim_name (str) – name of stimulus type

Returns

the number associated with the stimulus type

Return type

int

get_contrast_reversal_stimulus(stim_metadata)[source]

Extract contrast reversal stimulus info

Parameters

stim_metadata (dict) – dictionary of stimulus metadata loaded from task json file

Returns

np array of shape (n_stims,)

Return type

np.ndarray

get_task_stimulus(session_path)[source]

Extract contrast selectivity stimulus info

Parameters

session_path (str) – absolute path of a session, i.e. /mnt/data/Subjects/ZM_1887/2019-07-10/001

Returns

np array of shape (n_stims, 2); col 0 contains stim azimuth, col 1 contains contrast

Return type

np.ndarray

get_rf_ttl_pulses(ttl_signal)[source]

Find where ttl_signal increases or decreases

Parameters

ttl_signal (array-like) –

Returns

where signal increases/decreases

Return type

tuple (np.ndarray, np.ndarray) of ttl (rise, fall) indices

get_expected_ttl_pulses(stim_order, stim_meta, ttl_signal_rf_map)[source]

Get expected number of ttl pulses for each stimulus

Parameters
  • stim_order (array-like) – list of stimulus ids throughout protocol

  • stim_meta (dict) – dictionary containing stim metadata; from _iblrig_taskSettings json

  • ttl_signal_rf_map (array-like) – ttl signal during receptive field mapping with locally sparse noise

Returns

list of ttl pulses for each stimulus class

Return type

list

get_spacer_times(spacer_template, jitter, ttl_signal, t_quiet)[source]
Parameters
  • spacer_template (array-like) – list of indices where ttl signal changes

  • jitter (float) – jitter (in seconds) for matching ttl_signal with spacer_template

  • ttl_signal (array-like) –

  • t_quiet (float) – seconds between spacer and next stim

Returns

times of spacer onset/offset

Return type

n_spacer x 2 np.ndarray; first col onset times, second col offset

interpolate_rf_mapping_stimulus(ttl_signal, times, frames, t_bin)[source]

Interpolate stimulus presentation times to screen refresh rate to match frames

Parameters
  • ttl_signal (array-like) –

  • times (array-like) – array of stimulus switch times

  • frames (array-like) – (time, y_pix, x_pix) array of stim frames

  • t_bin (float) – screen refresh rate

Returns

tuple of (stim_times, stim_frames)

export_to_alf(session_path, stim_ts, stim_datas, stim_names)[source]

Export extracted stimuli and their presentation times to the session alf directory.

Parameters
  • session_path – absolute path of a session, i.e. /mnt/data/Subjects/ZM_1887/2019-07-10/001

  • stim_ts

  • stim_datas

  • stim_names

Returns

None; instead, saves the following files into session_path/alf; the ‘xx’ part of the following filenames will be ‘00’, ‘01’, etc., one for each time the specific protocol is run

orientation/direction selectivity _iblcertif_.odsgratings.times.xx.npy: shape (n_stims, 2); columns are

(stim on time, stim off time)

_iblcertif_.odsgratings.stims.xx.npy: shape (n_stims,); value is grating angle

contrast reversal _iblcertif_.reversal.times.xx.npy: shape (n_stims,); stim presentation times _iblcertif_.reversal.stims.xx.npy: shape (n_stims,); stim identity - these values map

into the matrices defined in _iblrig_taskSettings.raw.json files, ‘VISUAL_STIM_3’ -> ‘stim_patch_contrasts’

receptive field mapping (sparse noise) _iblcertif_.rfmap.times.xx.npy: shape (n_stims,); stim presentation times _iblcertif_.rfmap.stims.xx.npy: shape (n_stims, y_pix, x_pix); sparse noise stim frames

spontaneous activity: _iblcertif_.spontaneous.times.xx.npy: shape (2,); start and end times of spont activity

task stimuli (gratings of varying locations/contrast) _iblcertif_.task.times.xx.npy: shape (n_stims, 2); columns are

(stim on time, stim off time)

_iblcertif_.task.stims.xx.npy: shape (n_stims, 2); columns are

(azimuth in degrees [i.e. left or right], contrast)

extract_stimulus_info_to_alf(session_path, t_bin=0.016666666666666666, bin_jitter=3, save=True)[source]

Extract the stimulus information stored in metadata and export to alf files. Also checks to make sure ttl pulses were extracted properly. Expected files/structure: - session metadata:

session_path/raw_behavior_data/_iblrig_taskSettings.raw.*.json

  • task stimulus info:

    session_path/raw_behavior_data/_iblrig_codeFiles.raw.*.zip

  • rf mapping stim info:

    session_path/raw_behavior_data/_iblrig_RFMapStim.raw.*.bin

  • spikeglx sync data:
    session_path/raw_ephys_data/probe_[right/left]/_spikeglx_sync.[channels/polarities/times].*

    .npy

Parameters
  • session_path (str) – absolute path of a session, i.e. /mnt/data/Subjects/ZM_1887/2019-07-10/001

  • t_bin (float) – screen refresh rate

  • bin_jitter (int) – fudge factor in spacer template matching (units of time bins)

  • save (bool) – export stimulus info to alf directory

Returns

None; instead stimulus info is stored in the following alf files:

_iblcertification_.stimtype.times.00.npy _iblcertification_.stimtype.frames.00.npy

where stimtype are odsgratings, sparsenoise, contrastreversal, and taskstimulus; see export_to_alf function documentation for more info on file structure