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.
interpolate_position	Return linearly interpolated wheel position.
last_movement_onset	Find the time at which movement started, given an event timestamp that occurred during the movement.
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	Compute wheel velocity from non-uniformly sampled wheel data.
velocity_filtered	Compute wheel velocity from uniformly sampled wheel data
velocity_smoothed	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

last_movement_onset(t, vel, event_time)

Find the time at which movement started, given an event timestamp that occurred during the movement. Movement start is defined as the first sample after the velocity has been zero for at least 50ms. Wheel inputs should be evenly sampled.

Parameters

• t – numpy array of wheel timestamps in seconds

• vel – numpy array of wheel velocities

• event_time – timestamp anywhere during movement of interest, e.g. peak velocity

Returns

timestamp of movement onset

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_smoothed(pos, freq, smooth_size=0.03)

Compute wheel velocity from uniformly sampled wheel data

Parameters

• pos (array_like) – Array of wheel positions

• smooth_size (float) – Size of Gaussian smoothing window in seconds

• freq (float) – Sampling frequency of the data

Returns

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

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