brainbox.behavior.wheel
Set of functions to handle wheel data
Functions
Convert wheel position to degrees turned. |
|
Convert wheel position to radians. |
|
|
Find the direction changes for the given movement intervals. |
Return linearly interpolated wheel position. |
|
Find the time at which movement started, given an event timestamp that occurred during the movement. |
|
Detect wheel movements. |
|
Convert wheel position samples to cm linear displacement. |
|
Returns list of tuples of positions and velocity for samples between stimulus onset and feedback. |
|
|
Compute wheel velocity from non-uniformly sampled wheel data. |
|
Compute wheel velocity from uniformly sampled wheel data |
Compute wheel velocity from uniformly sampled wheel data |
- cm_to_deg(positions, wheel_diameter=6.2)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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