camap.dataset

camap.dataset#

Dataset classes for place cell analysis.

class camap.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: DataConfig | None = None)#

Bases: BaseCaMAPDataset

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 (DataConfig | 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.

Each side is loaded only when its config block is present, so neural-only and behavior-only sessions are valid.

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:: perspective correction → Hampel jump removal → boundary clipping → unit conversion (px → mm).

Hampel runs after perspective so its threshold reflects the post-correction trajectory; it stays before clipping so genuine out-of-bounds outliers remain visible to the filter.

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.

Requires both neural and behavior to be configured.

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 camap.dataset.BaseCaMAPDataset(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: DataConfig | None = None)#

Bases: ABC

Base class for place cell analysis datasets.

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

ds = BaseCaMAPDataset.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 (DataConfig | None)

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

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 camap/config/ (e.g. "example_arena_config").
data_path (str | Path) – Path to the per-session data paths YAML file.

Return type:

BaseCaMAPDataset

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.

No-op for behavior-only sessions (no neural data configured).

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 all 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 .camap 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. .camap is appended if not present.
save_figures (bool)

Returns:

The bundle directory that was created.

Return type:

Path

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

Load a previously saved .camap directory.

Parameters:: path (str | Path) – Path to the .camap 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:: BaseCaMAPDataset

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

Bases: BaseCaMAPDataset

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.
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 .camap 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 camap.dataset.StabilitySplitResult(n_split_blocks: int, corr: float, fisher_z: float, p_val: float, shuffled_corrs: ndarray, rate_map_first: ndarray, rate_map_second: ndarray)#

Bases: object

Result of one stability shuffle test at a given n_split_blocks.

Parameters:

n_split_blocks (int) – Number of interleaved temporal blocks used to split the session (2 = classic first/second half).
corr (float) – Pearson correlation between first-half and second-half rate maps.
fisher_z (float) – Fisher z-transform of corr.
p_val (float) – Shuffle-based p-value (NaN if n_shuffles == 0).
shuffled_corrs (numpy.ndarray) – Correlations from shuffled data (used for significance).
rate_map_first (numpy.ndarray) – Smoothed rate map for the first half of the split, in firing-rate units (same scale as UnitResult.rate_map_smoothed).
rate_map_second (numpy.ndarray) – Smoothed rate map for the second half of the split, in firing-rate units (same scale as UnitResult.rate_map_smoothed).

n_split_blocks: int#

corr: float#

fisher_z: float#

p_val: float#

shuffled_corrs: ndarray#

rate_map_first: ndarray#

rate_map_second: ndarray#

class camap.dataset.UnitResult(rate_map_smoothed: ndarray, rate_map_raw: ndarray, si: float, p_val: float, shuffled_sis: ndarray, shuffled_rate_p95: ndarray, stability_splits: list[StabilitySplitResult], 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_smoothed (numpy.ndarray) – Smoothed rate map in firing-rate units (events·s⁻¹ per bin). This is the authoritative rate map for quantitative analyses.
rate_map_raw (numpy.ndarray) – Unsmoothed rate map in firing-rate units (events·s⁻¹ per bin).
rate_map_peak_normalized – (Property, derived) Smoothed rate map divided by its peak so values span 0-1. Used for display-friendly colorbars. Computed on demand from rate_map_smoothed.
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) – Per-bin 95th percentile of smoothed shuffled rate maps, in the same firing-rate units as rate_map_smoothed (used for place-field seed detection).
stability_splits (list[camap.dataset.base.StabilitySplitResult]) – One StabilitySplitResult per entry in spatial_map.stability_splits. A cell is considered stable only if every split’s p_val is below the threshold.
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_smoothed: ndarray#

rate_map_raw: ndarray#

si: float#

p_val: float#

shuffled_sis: ndarray#

shuffled_rate_p95: ndarray#

stability_splits: list[StabilitySplitResult]#

vis_data_above: DataFrame#

unit_data: DataFrame#

overall_rate: float#

event_count_rate: float#

trace_data: ndarray | None#

trace_times: ndarray | None#

property rate_map_peak_normalized: ndarray#

Smoothed rate map divided by its peak (0-1 range, for display).

NaN bins pass through; zero-peak maps are returned unchanged (all zeros/NaN).

is_stable(p_threshold: float) → bool#

True iff every stability split’s p-value is below p_threshold.

Parameters:: p_threshold (float)
Return type:: bool

camap.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.camap (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.

camap.dataset

On this page

camap.dataset#