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)[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

get_movement_onset(intervals, event_times)[source]

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)[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_filtered(pos, fs, corner_frequency=20, order=8)[source]

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.