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

occupancy_coverage() → dict#

Spatial coverage of the occupancy map, reported two ways.

The two are exported separately so the distinction is explicit and the choice of which to cite is left to the writing, not baked into the data.

Returns:: coverage_visited_pct: percentage of spatial bins the animal entered (raw occupancy > 0). coverage_criterion_pct: percentage of bins meeting the min_occupancy criterion (i.e. in valid_mask — the bins actually used for rate maps and place fields). Depends on min_occupancy and occupancy_mask.
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#