placecell.dataset.base

On this page

placecell.dataset.base#

Base classes for place cell analysis datasets.

Functions

unique_bundle_path(bundle_dir, stem)

Return a bundle path, appending _1, _2, .

Classes

BasePlaceCellDataset(cfg, *[, neural_path, ...])

Base class for place cell analysis datasets.

UnitResult(rate_map, rate_map_raw, si, ...)

Analysis results for a single unit.
placecell.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.pcellbundle (or stem_1, stem_2, …).

Return type:

Path

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

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) → 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

On this page