placecell.behavior

placecell.behavior#

Behavior data spatial corrections and DLC loading.

Functions

clip_to_arena(positions, arena_bounds)

Clip positions to arena boundaries.

correct_perspective(positions, arena_bounds, ...)

Correct perspective distortion from overhead camera parallax.

remove_position_jumps(positions[, ...])

Replace implausible position jumps with linear interpolation (Hampel filter).
placecell.behavior.remove_position_jumps(positions: DataFrame, window_frames: int = 7, n_sigmas: float = 3.0) → tuple[DataFrame, int]#

Replace implausible position jumps with linear interpolation (Hampel filter).

For each frame the local centroid is the (median x, median y) over a centered window of window_frames frames. The deviation is the Euclidean distance from the frame to its centroid; the local scale is the rolling median of those deviations. A frame is flagged when its deviation exceeds n_sigmas * 1.4826 * scale — the standard Hampel rule (Hampel 1974) generalized to 2D via the spatial median.

Flagged frames have their x/y replaced by linear interpolation from the surrounding good frames.

Parameters:

  • positions (DataFrame) – DataFrame with columns x, y (and any others, preserved).

  • window_frames (int) – Window size for the rolling median centroid and MAD. Should be odd and large enough to span typical glitch durations.

  • n_sigmas (float) – Number of (MAD-based) standard deviations beyond which a frame is treated as an outlier. 3.0 corresponds to a ~99.7% Gaussian band.

Return type:

tuple of (DataFrame with jumps interpolated, number of frames fixed).

placecell.behavior.correct_perspective(positions: DataFrame, arena_bounds: tuple[float, float, float, float], camera_height_mm: float, tracking_height_mm: float) → DataFrame#

Correct perspective distortion from overhead camera parallax.

An LED at height h above the floor appears shifted radially outward from the optical axis. The corrected position is:

x_corrected = cx + (x - cx) * (H - h) / H

where cx, cy is the arena center (midpoint of arena_bounds), H is the camera height, and h is the tracking height.

Parameters:

  • positions (DataFrame) – DataFrame with columns x, y.

  • arena_bounds (tuple[float, float, float, float]) – (x_min, x_max, y_min, y_max) in pixels.

  • camera_height_mm (float) – Camera height above floor in mm.

  • tracking_height_mm (float) – Tracked point height above floor in mm.

Return type:

DataFrame with corrected x, y.

placecell.behavior.clip_to_arena(positions: DataFrame, arena_bounds: tuple[float, float, float, float]) → DataFrame#

Clip positions to arena boundaries.

Points outside the arena (from detection errors) are clamped to the nearest boundary edge.

Parameters:

  • positions (DataFrame) – DataFrame with columns x, y.

  • arena_bounds (tuple[float, float, float, float]) – (x_min, x_max, y_min, y_max) in pixels.

Return type:

DataFrame with x, y clipped to arena bounds.