camap.dataset.base

camap.dataset.base#

Base classes for place cell analysis datasets.

Functions

unique_bundle_path(bundle_dir, stem)

Return a bundle path, appending _1, _2, .

Classes

`BaseCaMAPDataset`(cfg, *[, neural_path, ...])	Base class for place cell analysis datasets.
`StabilitySplitResult`(n_split_blocks, corr, ...)	Result of one stability shuffle test at a given `n_split_blocks`.
`UnitResult`(rate_map_smoothed, rate_map_raw, ...)	Analysis results for a single unit.

camap.dataset.base.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

class camap.dataset.base.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.base.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

class camap.dataset.base.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)

traces: DataArray | None#

good_unit_ids: list[int]#

S_list: list[ndarray]#

event_index: DataFrame | None#

event_place: DataFrame | None#

trajectory_raw: DataFrame | None#

trajectory: DataFrame | None#

trajectory_filtered: DataFrame | None#

canonical: DataFrame | None#

occupancy_time: ndarray | None#

valid_mask: ndarray | None#

x_edges: ndarray | None#

y_edges: ndarray | None#

max_proj: ndarray | None#

footprints: DataArray | None#

behavior_video_frame: ndarray | None#

unit_results: dict[int, UnitResult]#

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

camap.dataset.base

On this page

camap.dataset.base#