brainbox.behavior.wheel

Set of functions to handle wheel data.

Functions

cm_to_deg	Convert wheel position to degrees turned.
cm_to_rad	Convert wheel position to radians.
direction_changes	Find the direction changes for the given movement intervals.
get_movement_onset	Find the time at which movement started, given an event timestamp that occurred during the movement.
interpolate_position	Return linearly interpolated wheel position.
movements	Detect wheel movements.
samples_to_cm	Convert wheel position samples to cm linear displacement.
traces_by_trial	Returns list of tuples of positions and velocity for samples between stimulus onset and feedback.
velocity_filtered	Compute wheel velocity from uniformly sampled wheel data.

cm_to_deg(positions, wheel_diameter=6.2)

Convert wheel position to degrees turned. This may be useful for e.g. calculating velocity in revolutions per second

Parameters:

• positions – array of wheel positions in cm

• wheel_diameter – the diameter of the wheel in cm

Returns:

array of wheel positions in degrees turned

# Example: Convert linear cm to degrees >>> cm_to_deg(3.142 * WHEEL_DIAMETER) 360.04667846020925

# Example: Get positions in deg from cm for 5cm diameter wheel >>> import numpy as np >>> cm_to_deg(np.array([0.0270526 , 0.04057891, 0.05410521, 0.06763151]), wheel_diameter=5) array([0.61999992, 0.93000011, 1.24000007, 1.55000003])

cm_to_rad(positions, wheel_diameter=6.2)

Convert wheel position to radians. This may be useful for e.g. calculating angular velocity.

Parameters:

• positions – array of wheel positions in cm

• wheel_diameter – the diameter of the wheel in cm

Returns:

array of wheel angle in radians

# Example: Convert linear cm to radians >>> cm_to_rad(1) 0.3225806451612903

# Example: Get positions in rad from cm for 5cm diameter wheel >>> import numpy as np >>> cm_to_rad(np.array([0.0270526 , 0.04057891, 0.05410521, 0.06763151]), wheel_diameter=5) array([0.01082104, 0.01623156, 0.02164208, 0.0270526 ])

interpolate_position(re_ts, re_pos, freq=1000, kind='linear', fill_gaps=None)

Return linearly interpolated wheel position.

Parameters:

• re_ts (array_like) – Array of timestamps

• re_pos (array_like) – Array of unwrapped wheel positions

• freq (float) – frequency in Hz of the interpolation

• kind ({'linear', 'cubic'}) – Type of interpolation. Defaults to linear interpolation.

• fill_gaps (float) – Minimum gap length to fill. For gaps over this time (seconds), forward fill values before interpolation

Returns:

• yinterp (array) – Interpolated position

• t (array) – Timestamps of interpolated positions

get_movement_onset(intervals, event_times)

Find the time at which movement started, given an event timestamp that occurred during the movement.

Parameters:

• intervals (numpy.array) – The wheel movement intervals.

• event_times (numpy.array) – Sorted event timestamps anywhere during movement of interest, e.g. peak velocity, feedback time.

Returns:

An array the length of event_time of intervals.

Return type:

numpy.array

Examples

Find the last movement onset before each trial response time

>>> trials = one.load_object(eid, 'trials')
>>> wheelMoves = one.load_object(eid, 'wheelMoves')
>>> onsets = last_movement_onset(wheelMoves.intervals, trials.response_times)

movements(t, pos, freq=1000, pos_thresh=8, t_thresh=0.2, min_gap=0.1, pos_thresh_onset=1.5, min_dur=0.05, make_plots=False)

Detect wheel movements.

Parameters:

• t (array_like) – An array of evenly sampled wheel timestamps in absolute seconds

• pos (array_like) – An array of evenly sampled wheel positions

• freq (int) – The sampling rate of the wheel data

• pos_thresh (float) – The minimum required movement during the t_thresh window to be considered part of a movement

• t_thresh (float) – The time window over which to check whether the pos_thresh has been crossed

• min_gap (float) – The minimum time between one movement’s offset and another movement’s onset in order to be considered separate. Movements with a gap smaller than this are ‘stictched together’

• pos_thresh_onset (float) – A lower threshold for finding precise onset times. The first position of each movement transition that is this much bigger than the starting position is considered the onset

• min_dur (float) – The minimum duration of a valid movement. Detected movements shorter than this are ignored

• make_plots (boolean) – Plot trace of position and velocity, showing detected onsets and offsets

Returns:

• onsets (np.ndarray) – Timestamps of detected movement onsets

• offsets (np.ndarray) – Timestamps of detected movement offsets

• peak_amps (np.ndarray) – The absolute maximum amplitude of each detected movement, relative to onset position

• peak_vel_times (np.ndarray) – Timestamps of peak velocity for each detected movement

samples_to_cm(positions, wheel_diameter=6.2, resolution=4096)

Convert wheel position samples to cm linear displacement. This may be useful for inter-converting threshold units

Parameters:

• positions – array of wheel positions in sample counts

• wheel_diameter – the diameter of the wheel in cm

• resolution – resolution of the rotary encoder

Returns:

array of wheel angle in radians

# Example: Get resolution in linear cm >>> samples_to_cm(1) 0.004755340442445488

# Example: Get positions in linear cm for 4X, 360 ppr encoder >>> import numpy as np >>> samples_to_cm(np.array([2, 3, 4, 5, 6, 7, 6, 5, 4]), resolution=360*4) array([0.0270526 , 0.04057891, 0.05410521, 0.06763151, 0.08115781,

0.09468411, 0.08115781, 0.06763151, 0.05410521])

traces_by_trial(t, *args, start=None, end=None, separate=True)

Returns list of tuples of positions and velocity for samples between stimulus onset and feedback.

Parameters:

• t – numpy array of timestamps

• args – optional numpy arrays of the same length as timestamps, such as positions,

velocities or accelerations :param start: start timestamp or array thereof :param end: end timestamp or array thereof :param separate: when True, the output is returned as tuples list of the form [(t, args[0], args[1]), …], when False, the output is a list of n-by-m ndarrays where n = number of positional args and m = len(t) :return: list of sliced arrays where length == len(start)

velocity_filtered(pos, fs, corner_frequency=20, order=8)

Compute wheel velocity from uniformly sampled wheel data.

pos: array_like

Vector of uniformly sampled wheel positions.

fsfloat

Frequency in Hz of the sampling frequency.

corner_frequencyfloat

Corner frequency of low-pass filter.

orderint

Order of Butterworth filter.

Returns:

• vel (np.ndarray) – Array of velocity values.

• acc (np.ndarray) – Array of acceleration values.