placecell.dataset.arena

placecell.dataset.arena#

Dataset class for 2D open-field arena place cell analysis.

Classes

ArenaDataset(cfg, *[, neural_path, ...])

Dataset for 2D open-field arena place cell analysis.
class placecell.dataset.arena.ArenaDataset(cfg: AnalysisConfig, *, neural_path: Path | None = None, neural_timestamp_path: Path | None = None, behavior_position_path: Path | None = None, behavior_timestamp_path: Path | None = None, behavior_video_path: Path | None = None, behavior_graph_path: Path | None = None, zone_tracking_path: Path | None = None, data_cfg: BaseDataConfig | None = None)#

Bases: BasePlaceCellDataset

Dataset for 2D open-field arena place cell analysis.

Adds arena-specific functionality: perspective correction scale properties, 2D occupancy computation, and 2D spatial analysis.

Parameters:

  • cfg (AnalysisConfig)

  • neural_path (Path | None)

  • neural_timestamp_path (Path | None)

  • behavior_position_path (Path | None)

  • behavior_timestamp_path (Path | None)

  • behavior_video_path (Path | None)

  • behavior_graph_path (Path | None)

  • zone_tracking_path (Path | None)

  • data_cfg (BaseDataConfig | None)

property spatial: BaseSpatialMapConfig#

Shortcut to 2D spatial map config.

property p_value_threshold: float#

P-value threshold from 2D spatial map config.

load() → None#

Load neural traces, arena behavior data, and visualization assets.

Return type:

None

property mm_per_px: float | None#

Averaged mm-per-pixel scale, or None if arena is not calibrated.

property mm_per_px_xy: tuple[float, float] | None#

Per-axis (scale_x, scale_y) mm-per-pixel, or None if not calibrated.

preprocess_behavior() → None#

Apply geometric corrections to the behavior trajectory.

When arena_bounds is configured:

jump removal → perspective correction → boundary clipping → unit conversion (px → mm).

When arena_bounds is not configured:

warnings are logged and the trajectory remains in pixels.

Speed is computed later at the neural sample rate inside match_events(). Requires load() to have been called.

Return type:

None

match_events() → None#

Build the canonical neural-rate table and derive analysis views.

After this call:

  • self.canonical — one row per neural frame with columns frame_index, neural_time, x, y, speed, s_unit_*.

  • self.trajectory_filtered — speed-filtered view of canonical for occupancy and spatial analysis.

  • self.event_place — long-format event table derived from the speed-filtered view.

Return type:

None

apply_time_window(start_s: float, end_s: float) → None#

Restrict the canonical table to [start_s, end_s) relative to the first neural frame.

Call after match_events(). The first call snapshots the full canonical table; subsequent calls always re-slice from that snapshot, so iterating windows is idempotent. Re-runs the view derivations but not deconvolution — the caller should rerun compute_occupancy() and analyze_units() to complete the analysis for the new window.

Parameters:

  • start_s (float)

  • end_s (float)

Return type:

None

compute_occupancy() → None#

Compute 2D occupancy map from speed-filtered trajectory.

Return type:

None

analyze_units(progress_bar: Any = None, n_workers: int = 1) → None#

Run 2D spatial analysis for all deconvolved units with events.

Parameters:

  • progress_bar (Any) – Progress bar wrapper, e.g. tqdm.

  • n_workers (int) – Number of parallel worker processes. 1 (default) runs sequentially with no multiprocessing overhead.

Return type:

None

coverage() → tuple[ndarray, ndarray, ndarray]#

Compute place field coverage map and curve.

Returns (coverage_map, n_cells_array, coverage_fraction_array).

Return type:

tuple[ndarray, ndarray, ndarray]