iblutil.spacer

Tools to generate and identify spacers.

Spacers are sequences of up and down pulses with a specific, identifiable pattern. They are generated with a chirp coding to reduce cross-correlaation sidelobes. They are used to mark the beginning of a behaviour sequence within a session.

Example

>>> spacer = Spacer()
>>> spacer.add_spacer_states(sma, t, next_state='first_state')
>>> for i in range(ntrials):
... sma.add_state(
...     state_name='first_state',
...     state_timer=tup,
...     state_change_conditions={'Tup': f'spacer_low_{i:02d}'},
...     output_actions=[('BNC1', 255)],  # To FPGA
... )

Classes

Spacer

class Spacer(dt_start=0.02, dt_end=0.4, n_pulses=8, tup=0.05)[source]

Bases: object

property times

Computes spacer up times using a chirp up and down pattern.

Each time corresponds to an up time of the BNC1 signal.

Returns:: Numpy arrays of spacer times.
Return type:: numpy.array

generate_template(fs=1000)[source]

Generates a spacer voltage template to cross-correlate with a voltage trace from a DAQ to detect a voltage trace.

Parameters:: fs (int) – DAQ sampling frequency.
Returns:: The template spacer signal.
Return type:: numpy.array

add_spacer_states(sma=None, next_state='exit')[source]

Add spacer states to a state machine.

Parameters:

sma (pybpodapi.state_machine.StateMachine) – A Bpod state machine instance.
next_state (str) – The name of the state to follow the spacer state.

find_spacers_from_fronts(fronts, fs=1000)[source]

Given the timestamps and polarities of a digital signal, returns the timestamps of each signal. This method first finds the locations where there are n consecutive pulses of the correct width then convolves this part of the signal with the template signal.

This method may be relaxed in order to make it robust to noise in the signal.

Parameters:

fronts (dict[str, numpy.array]) – Dictionary with keys (‘times’, ‘polarities’) containing the timestamps and polarities of the signal fronts, respectively.
fs (int) – The sampling frequency of the DAQ signal.

Returns:

The times of the protocol spacer signals.

Return type:

numpy.array

find_spacers(signal, threshold=0.9, fs=1000)[source]

Find spacers in a voltage time series. Assumes that the signal is a digital signal between 0 and 1.

Parameters:

signal (numpy.ndarray) – The signal in which to find the spacer.
threshold (float) – The cross-correlation detection threshold.
fs (int) – The sampling frequency of the DAQ signal.

Returns:

An array containing the times of each spacer signal relative to the first sample.

Return type:

numpy.ndarray

find_spacers_from_timestamps(timestamps: ndarray, atol: float64 = 0.0001) → ndarray[source]

finds spacers in a series of timestamps. Returns the indices of the first spacer front

Parameters:

timestamps (np.ndarray) – an array of the timestamps to check
atol (np.float64, optional) – absolute tolerance for the squared sum of the residuals

Returns:

an array of the indices of the first front of a spacer

Return type:

np.ndarray

find_spacers_from_positive_fronts(timestamps, fs=1000, prominence=4)[source]

finds spacers in timestamps that consist of only the positive fronts.

Parameters:

timestamps (np.ndarray) – the positive fronts
fs (int, optional) – sampling frequency used for resampling, by default 1000
prominence (int, optional) – prominence for peak detection after convolution, passed to signal.find_peaks, by default 4