Skip to content

cortexlab_fusi_utils.behavior

behavior

Computation functions for behavioral data.

Modules:

  • eye –

    Computation functions for eye tracking behavioral data.

  • whisking –

    Computation functions for whisking behavioral data.

Functions:

compute_eye_movement 

compute_eye_movement(
    eye_position: NDArray[floating], dt: float
) -> NDArray[float64]

Compute eye movement speed from position data.

Parameters:

  • eye_position

    ((n_timepoints, 2) numpy.ndarray) –

    Eye position as (x, y) coordinates in pixels.

  • dt

    (float) –

    Time step between samples in seconds.

Returns:

  • (n_timepoints,) numpy.ndarray –

    Eye movement speed in pixels per second.

Notes

Movement speed is computed as the Euclidean norm of position differences divided by the time step: speed[i] = ||pos[i] - pos[i-1]|| / dt. The first value is set to 0.

Examples:

>>> times, eye_pos = load_eye_position(...)
>>> sampling_rate = 3.33  # Hz
>>> dt = 1 / sampling_rate
>>> eye_mvt = compute_eye_movement(eye_pos, dt)

compute_whisking 

compute_whisking(
    motion_svd: NDArray[floating],
    wheel_velocity: NDArray[floating] | None = None,
    sampling_rate: float | None = None,
    verify_sign: bool = True,
) -> NDArray[float64]

Compute whisking intensity from motion SVD data.

This function extracts whisking behavior from the first component of motion SVD by finding the rest point (mode of the distribution) and computing deviation from it.

Parameters:

  • motion_svd

    ((n_timepoints,) or (n_timepoints, n_components) numpy.ndarray) –

    Motion SVD coefficients. If 2D, only the first component is used.

  • wheel_velocity

    ((n_timepoints,) numpy.ndarray, default: None ) –

    Wheel velocity data for sign verification. If provided and verify_sign=True, the whisking sign is flipped if negatively correlated with wheel at slow timescales.

  • sampling_rate

    (float, default: None ) –

    Sampling rate in Hertz. Used for filtering during sign verification. If not provided, sign verification is skipped even when wheel_velocity is supplied.

  • verify_sign

    (bool, default: True ) –

    Whether to verify and correct whisking sign against wheel velocity.

Returns:

  • (n_timepoints,) numpy.ndarray –

    Whisking intensity normalized to [0, 1] range.

Notes

The whisking computation follows these steps:

  1. Extract first SVD component (if 2D input).
  2. Find rest point as the mode of the distribution using histogram.
  3. Compute absolute deviation from rest point.
  4. If wheel velocity provided and verify_sign=True: compute slow correlation and flip sign if negatively correlated.
  5. Normalize to [0, 1] range using percentiles (1st to 100th).

Examples:

>>> times, motion_svd = load_motion_svd(..., svd_type="motion_tc", apply_zscore=False)
>>> times, wheel = load_wheel_velocity(...)
>>> whisking = compute_whisking(motion_svd, wheel_velocity=wheel)