ibllib.io.extractors.camera

Camera extractor functions.

This module handles extraction of camera timestamps for both Bpod and DAQ.

Functions

`align_with_gpio`	Groom the raw DAQ or Bpod camera timestamps using the frame embedded GPIO and frame counter.
`attribute_times`	Returns the values of the first array that correspond to those of the second.
`extract_all`	For the IBL ephys task, reads ephys binary file and extract:
`extract_camera_sync`	Extract camera timestamps from the sync matrix.
`get_video_length`	Returns video length.
`groom_pin_state`	Align the GPIO pin state to the DAQ sync TTLs.

Classes

`CameraTimestampsBpod`	Get the camera timestamps from the Bpod
`CameraTimestampsCamlog`
`CameraTimestampsFPGA`	Extractor for videos using DAQ sync and channel map.

extract_camera_sync(sync, chmap=None)[source]

Extract camera timestamps from the sync matrix.

Parameters:

sync – dictionary ‘times’, ‘polarities’ of fronts detected on sync trace
chmap – dictionary containing channel indices. Default to constant.

Returns:

dictionary containing camera timestamps

get_video_length(video_path)[source]

Returns video length.

Parameters:: video_path – A path to the video
Returns:

class CameraTimestampsFPGA(label, session_path=None)[source]

Bases: BaseExtractor

Extractor for videos using DAQ sync and channel map.

class CameraTimestampsCamlog(label, session_path=None)[source]: Bases: BaseExtractor

class CameraTimestampsBpod(*args, **kwargs)[source]

Bases: BaseBpodTrialsExtractor

Get the camera timestamps from the Bpod

The camera events are logged only during the events not in between, so the times need to be interpolated

save_names = '_ibl_leftCamera.times.npy'

The filenames of each extracted dataset, or None if array should not be saved.

Type:: tuple of str

var_names = 'left_camera_timestamps'

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

Type:: tuple of str

align_with_gpio(timestamps, ttl, pin_state, count, extrapolate_missing=True, display=False)[source]

Groom the raw DAQ or Bpod camera timestamps using the frame embedded GPIO and frame counter.

Parameters:

timestamps (numpy.array) – An array of raw DAQ or Bpod camera timestamps.
ttl (dict) – A dictionary of DAQ sync TTLs, with keys {‘times’, ‘polarities’}.
pin_state (dict) – A dictionary containing GPIO pin state values, with keys {‘indices’, ‘polarities’}.
count (numpy.array) – An array of frame numbers.
extrapolate_missing (bool) – If true and the number of timestamps is fewer than the number of frame counts, the remaining timestamps are extrapolated based on the frame rate, otherwise they are NaNs.
display (bool) – Plot the resulting timestamps.

Returns:

The corrected frame timestamps.

Return type:

numpy.array

attribute_times(arr, events, tol=0.1, injective=True, take='first')[source]

Returns the values of the first array that correspond to those of the second.

Given two arrays of timestamps, the function will return the values of the first array that most likely correspond to the values of the second. For each of the values in the second array, the absolute difference is taken and the index of either the first sufficiently close value, or simply the closest one, is assigned.

If injective is True, once a value has been assigned to an event it can’t be assigned to another. In other words there is a one-to-one mapping between the two arrays.

Parameters:

arr (numpy.array) – An array of event times to attribute to those in events.
events (numpy.array) – An array of event times considered a subset of arr.
tol (float) – The max absolute difference between values in order to be considered a match.
injective (bool) – If true, once a value has been assigned it will not be assigned again.
take ({'first', 'nearest', 'after'}) – If ‘first’ the first value within tolerance is assigned; if ‘nearest’ the closest value is assigned; if ‘after’ assign the first event after.

Returns:

An array the same length as events containing indices of arr corresponding to each event.

Return type:

numpy.array

groom_pin_state(gpio, ttl, ts, tolerance=2.0, display=False, take='first', min_diff=0.0)[source]

Align the GPIO pin state to the DAQ sync TTLs. Any sync TTLs not reflected in the pin state are removed from the dict and the times of the detected fronts are converted to DAQ time. At the end of this the number of GPIO fronts should equal the number of TTLs.

Note

This function is ultra safe: we probably don’t need assign all the ups and down fronts.

separately and could potentially even align the timestamps without removing the missed fronts - The input gpio and TTL dicts may be modified by this function. - For training sessions the frame rate is only 30Hz and the TTLs tend to be broken up by small gaps. Setting the min_diff to 5ms helps the timestamp assignment accuracy.

Parameters:

gpio (dict) – A dictionary containing GPIO pin state values, with keys {‘indices’, ‘polarities’}.
ttl (dict) – A dictionary of DAQ sync TTLs, with keys {‘times’, ‘polarities’}.
ts (numpy.array) – The camera frame times (the camera frame TTLs acquired by the main DAQ).
tolerance (float) – Two pulses need to be within this many seconds to be considered related.
display (bool) – If true, the resulting timestamps are plotted against the raw audio signal.
take ({'first', 'nearest'}) – If ‘first’ the first value within tolerance is assigned; if ‘nearest’ the closest value is assigned.
min_diff (float) – Sync TTL fronts less than min_diff seconds apart will be removed.

Returns:

dict – Dictionary of GPIO DAQ front indices, polarities and DAQ aligned times.
dict – Sync TTL times and polarities sans the TTLs not detected in the frame data.
numpy.array – Frame times in DAQ time.