camap.dataset.base

On this page

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

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

On this page