placecell.dataset

On this page

placecell.dataset#

Dataset classes for place cell analysis.

class placecell.dataset.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]

class placecell.dataset.BasePlaceCellDataset(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: ABC

Base class for place cell analysis datasets.

Shared pipeline (each step populates attributes for the next):

ds = BasePlaceCellDataset.from_yaml(config_path, data_path)
ds.load()                            # traces, trajectory, footprints
ds.preprocess_behavior()             # corrections + speed filter
ds.deconvolve(progress_bar=tqdm)     # good_unit_ids, S_list
ds.match_events()                    # event_place
ds.compute_occupancy()               # occupancy_time, valid_mask, edges
ds.analyze_units(progress_bar=tqdm)  # unit_results
Parameters:

  • cfg (AnalysisConfig) – Merged analysis config (pipeline + data-specific overrides).

  • neural_path (Path) – Directory containing neural zarr files.

  • neural_timestamp_path (Path) – Path to neural timestamp CSV.

  • behavior_position_path (Path) – Path to behavior position CSV.

  • behavior_timestamp_path (Path) – Path to behavior timestamp CSV.

  • behavior_video_path (Path | None)

  • behavior_graph_path (Path | None)

  • zone_tracking_path (Path | None)

  • data_cfg (BaseDataConfig | None)

classmethod from_yaml(config: str | Path, data_path: str | Path) → BasePlaceCellDataset#

Create dataset from analysis config and data paths file.

Parameters:

  • config (str | Path) – Path to analysis config YAML, or a stem name matching a bundled config in placecell/config/ (e.g. "example_arena_config").

  • data_path (str | Path) – Path to the per-session data paths YAML file.

Return type:

BasePlaceCellDataset

abstract property p_value_threshold: float#

P-value threshold from the appropriate spatial config.

property neural_fps: float#

Neural sampling rate in Hz.

abstractmethod load() → None#

Load neural traces, behavior data, and visualization assets.

Return type:

None

subset(n_units: int | None = None, n_frames: int | None = None) → None#

Trim loaded data to the first n_units units and n_frames frames.

Must be called after load() and before preprocess_behavior().

Parameters:

  • n_units (int | None)

  • n_frames (int | None)

Return type:

None

abstractmethod preprocess_behavior() → None#

Preprocess behavior data. Subclass-specific pipelines.

Return type:

None

deconvolve(progress_bar: Any = None) → None#

Run OASIS deconvolution on calcium traces.

Parameters:

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

Return type:

None

abstractmethod match_events() → None#

Match neural events to behavior positions.

Return type:

None

abstractmethod compute_occupancy() → None#

Compute occupancy map from speed-filtered trajectory.

Return type:

None

abstractmethod analyze_units(progress_bar: Any = None) → None#

Run spatial analysis for all deconvolved units.

Parameters:

progress_bar (Any)

Return type:

None

place_cells() → dict[int, UnitResult]#

Return units passing both significance and stability tests.

Return type:

dict[int, UnitResult]

summary() → dict#

Compute summary counts and percentages of significant and stable units.

Returns:

Keys: n_total, n_sig, n_stable, n_place_cells, pct_sig, pct_stable, pct_place_cells.

Return type:

dict

save_bundle(path: str | Path, *, save_figures: bool = True) → Path#

Save all analysis results to a portable .pcellbundle directory.

The bundle is self-contained: it stores config, behavior, neural, and per-unit analysis results so that visualizations can be recreated without access to the original raw data.

Parameters:

  • path (str | Path) – Output directory. .pcellbundle is appended if not present.

  • save_figures (bool)

Returns:

The bundle directory that was created.

Return type:

Path

classmethod load_bundle(path: str | Path) → BasePlaceCellDataset#

Load a previously saved .pcellbundle directory.

Parameters:

path (str | Path) – Path to the .pcellbundle directory.

Returns:

Dataset with all attributes restored. Recomputation methods (load, deconvolve, etc.) are unavailable since the original raw data paths are not preserved.

Return type:

BasePlaceCellDataset

class placecell.dataset.MazeDataset(*args: Any, **kwargs: Any)#

Bases: BasePlaceCellDataset

Dataset for 1D arm/maze place cell analysis.

Overrides the behavior preprocessing, occupancy computation, and unit analysis steps to work on a concatenated 1D axis.

Parameters:

  • args (Any)

  • kwargs (Any)

property spatial_1d: SpatialMap1DConfig#

Shortcut to 1D spatial map config.

property p_value_threshold: float#

P-value threshold from 1D spatial map config.

load(*, force_redetect: bool = False) → None#

Load neural traces, behavior from zone_tracking CSV, and vis assets.

MazeDataset reads the zone-detected zone_tracking CSV directly. If the CSV is missing, _run_zone_detection() is invoked first to project the raw behavior_position CSV onto the maze graph.

Parameters:

force_redetect (bool) – If True, re-run detect_zones_from_csv() even when zone_tracking_path already exists. Useful when zone-detection parameters have changed and the cached output is stale.

Return type:

None

preprocess_behavior() → None#

Serialize to 1D, compute speed, and filter.

Zone and arm_position columns are already in self.trajectory from load(), so no extra CSV loading is needed.

Return type:

None

match_events() → None#

Build the canonical neural-rate table for the maze pipeline.

After this call:

  • self.canonical holds one row per neural frame with columns frame_index, neural_time, x, y, pos_1d, arm_index, [direction], speed_1d, s_unit_*.

  • self.trajectory_1d_filtered is the speed-filtered canonical view restricted to arm frames, with frame_index aliased to frame_index.

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

Return type:

None

compute_occupancy() → None#

Compute 1D occupancy from speed-filtered arm trajectory.

Return type:

None

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

Run 1D spatial analysis for all deconvolved units.

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

save_bundle(path: str | Path, *, save_figures: bool = True) → Path#

Save bundle, including 1D trajectory and maze metadata.

Parameters:

  • path (str | Path)

  • save_figures (bool)

Return type:

Path

classmethod load_bundle(path: str | Path) → MazeDataset#

Load a saved .pcellbundle that contains 1D maze data.

Restores all base attributes via the parent loader, then adds 1D-specific state (trajectories, arm boundaries, etc.).

Parameters:

path (str | Path)

Return type:

MazeDataset

class placecell.dataset.UnitResult(rate_map: ndarray, rate_map_raw: ndarray, si: float, p_val: float, shuffled_sis: ndarray, shuffled_rate_p95: ndarray, stability_corr: float, stability_z: float, stability_p_val: float, shuffled_stability: ndarray, rate_map_first: ndarray, rate_map_second: ndarray, vis_data_above: DataFrame, unit_data: DataFrame, overall_rate: float, event_count_rate: float, trace_data: ndarray | None, trace_times: ndarray | None)#

Bases: object

Analysis results for a single unit.

Parameters:

  • rate_map (numpy.ndarray) – Smoothed rate map (e.g. 2D array for arena dataset, or 1D array for maze dataset).

  • rate_map_raw (numpy.ndarray) – Raw (unsmoothed) rate map.

  • si (float) – Spatial information (bits/spike).

  • p_val (float) – P-value from spatial information significance test.

  • shuffled_sis (numpy.ndarray) – Spatial information values from shuffled data (for significance test).

  • shuffled_rate_p95 (numpy.ndarray) – 95th percentile of shuffled rate maps (for place field thresholding).

  • stability_corr (float) – Correlation between rate maps from first vs. second half of session.

  • stability_z (float) – Fisher z-score corresponding to stability_corr.

  • stability_p_val (float) – P-value from stability significance test.

  • shuffled_stability (numpy.ndarray) – Stability correlations from shuffled data (for significance test).

  • rate_map_first (numpy.ndarray) – Rate map for first half of session.

  • rate_map_second (numpy.ndarray) – Rate map for second half of session.

  • vis_data_above (pandas.DataFrame) – Subset of unit_data where event amplitude exceeds the threshold (used for plotting event dots on rate maps).

  • unit_data (pandas.DataFrame) – Speed-filtered deconvolved events for this unit (subset of event_place).

  • overall_rate (float) – Activity rate in a.u./s (sum of deconvolved amplitudes / total time).

  • event_count_rate (float) – Event count rate in 1/s (number of events / total time).

  • trace_data (numpy.ndarray | None) – Neural trace for this unit (None if traces unavailable).

  • trace_times (numpy.ndarray | None) – Time axis in seconds corresponding to trace_data.

rate_map: ndarray#
rate_map_raw: ndarray#
si: float#
p_val: float#
shuffled_sis: ndarray#
shuffled_rate_p95: ndarray#
stability_corr: float#
stability_z: float#
stability_p_val: float#
shuffled_stability: ndarray#
rate_map_first: ndarray#
rate_map_second: ndarray#
vis_data_above: DataFrame#
unit_data: DataFrame#
overall_rate: float#
event_count_rate: float#
trace_data: ndarray | None#
trace_times: ndarray | None#
placecell.dataset.unique_bundle_path(bundle_dir: str | Path, stem: str) → Path#

Return a bundle path, appending _1, _2, … if it already exists.

Parameters:

  • bundle_dir (str | Path) – Directory where bundles are stored.

  • stem (str) – Base name for the bundle (without extension).

Returns:

A path like bundle_dir/stem.pcellbundle (or stem_1, stem_2, …).

Return type:

Path

Modules

arena

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

base

Base classes for place cell analysis datasets.

maze

Dataset class for maze/arm 1D place cell analysis.
On this page