placecell.analysis

Spatial analysis functions for place cells.

Functions

compute_coverage_curve(unit_results, valid_mask)	Compute cumulative coverage curve: fraction of environment covered vs number of cells.
compute_coverage_map(unit_results[, ...])	Compute combined place field coverage across all units.
compute_occupancy_map(trajectory_df, bins, ...)	Compute occupancy map from speed-filtered trajectory.
compute_place_field_mask(rate_map, ...[, ...])	Compute a binary mask of the place field from a rate map.
compute_rate_map(unit_events, ...[, ...])	Compute smoothed and normalized rate map for a unit.
compute_raw_rate_map(unit_events, ...)	Compute unsmoothed binned spatial activity rate.
compute_shuffled_rate_percentile(...[, ...])	Compute per-bin percentile of shuffled smoothed rate maps.
compute_spatial_information(unit_events, ...)	Compute spatial information and significance via shuffling.
compute_stability_score(unit_events, ...[, ...])	Compute stability score by comparing rate maps from split data.
compute_unit_analysis(unit_id, df_filtered, ...)	Compute rate map, spatial information, stability, and thresholded events for a unit.
gaussian_filter_normalized(data, sigma)	Apply Gaussian smoothing with adaptive normalization at boundaries.

placecell.analysis.gaussian_filter_normalized(data: ndarray, sigma: float) → ndarray

Apply Gaussian smoothing with adaptive normalization at boundaries.

Uses zero-padding and normalizes by the kernel weight sum so that edge bins are not penalized. This is the standard approach for place cell rate map smoothing.

Parameters:

• data (ndarray) – Input 2D array to smooth.

• sigma (float) – Gaussian smoothing sigma in bins.

Returns:

Smoothed array with normalized edges.

Return type:

np.ndarray

placecell.analysis.compute_occupancy_map(trajectory_df: DataFrame, bins: int, behavior_fps: float, occupancy_sigma: float = 1.0, min_occupancy: float = 0.1) → tuple[ndarray, ndarray, ndarray, ndarray]

Compute occupancy map from speed-filtered trajectory.

Parameters:

• trajectory_df (DataFrame) – Speed-filtered trajectory with x, y columns.

• bins (int) – Number of spatial bins.

• behavior_fps (float) – Behavior sampling rate.

• occupancy_sigma (float) – Gaussian smoothing sigma for occupancy map.

• min_occupancy (float) – Minimum occupancy time in seconds.

Returns:

(occupancy_time, valid_mask, x_edges, y_edges)

Return type:

tuple

placecell.analysis.compute_rate_map(unit_events: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray, activity_sigma: float = 1.0) → ndarray

Compute smoothed and normalized rate map for a unit.

Parameters:

• unit_events (DataFrame) – DataFrame with x, y, s columns for a single unit.

• occupancy_time (ndarray) – Occupancy time map.

• valid_mask (ndarray) – Valid occupancy mask.

• x_edges (ndarray) – Spatial bin edges.

• y_edges (ndarray) – Spatial bin edges.

• activity_sigma (float) – Gaussian smoothing sigma for rate map.

Returns:

Smoothed rate map normalized to 0-1 range.

Return type:

np.ndarray

placecell.analysis.compute_spatial_information(unit_events: DataFrame, trajectory_df: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray, n_shuffles: int = 100, random_seed: int | None = None, min_shift_seconds: float = 0.0, behavior_fps: float = 20.0, si_weight_mode: str = 'amplitude', activity_sigma: float = 0.0) → tuple[float, float, ndarray]

Compute spatial information and significance via shuffling.

Parameters:

• unit_events (DataFrame) – DataFrame with x, y, s, beh_frame_index columns for a single unit.

• trajectory_df (DataFrame) – Speed-filtered trajectory with beh_frame_index column.

• occupancy_time (ndarray) – Occupancy time map.

• valid_mask (ndarray) – Valid occupancy mask.

• x_edges (ndarray) – Spatial bin edges.

• y_edges (ndarray) – Spatial bin edges.

• n_shuffles (int) – Number of shuffles for significance test.

• random_seed (int | None) – Random seed for reproducibility.

• min_shift_seconds (float) – Minimum circular shift in seconds. Shifts smaller than this are re-drawn to ensure the temporal-spatial association is broken. Default 0.0 (no minimum).

• behavior_fps (float) – Behavior sampling rate, used to convert min_shift_seconds to frames.

• si_weight_mode (str) – "amplitude" weights events by their s value; "binary" counts each event as 1 regardless of amplitude, which is more robust to bursty firing patterns.

• activity_sigma (float) – Gaussian smoothing sigma (in bins) applied to rate maps before SI calculation. Matches the smoothing used for rate map display and stability tests. Default 0.0 (no smoothing).

Returns:

(spatial_info, p_value, shuffled_sis)

Return type:

tuple

placecell.analysis.compute_shuffled_rate_percentile(unit_events: DataFrame, trajectory_df: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray, activity_sigma: float = 1.0, n_shuffles: int = 100, min_shift_seconds: float = 0.0, behavior_fps: float = 20.0, si_weight_mode: str = 'amplitude', random_seed: int | None = None, percentile: float = 95.0) → ndarray

Compute per-bin percentile of shuffled smoothed rate maps.

Used for the seed detection step of the Guo et al. 2023 place field algorithm. For each shuffle iteration, circularly shifts event times relative to the trajectory, computes a smoothed and normalized (0-1) rate map, then returns the requested percentile across shuffles at each spatial bin.

Parameters:

• unit_events (DataFrame) – DataFrame with x, y, s, beh_frame_index columns for a single unit.

• trajectory_df (DataFrame) – Speed-filtered trajectory with beh_frame_index column.

• occupancy_time (ndarray) – Occupancy time map.

• valid_mask (ndarray) – Valid occupancy mask.

• x_edges (ndarray) – Spatial bin edges.

• y_edges (ndarray) – Spatial bin edges.

• activity_sigma (float) – Gaussian smoothing sigma for rate maps.

• n_shuffles (int) – Number of shuffle iterations.

• min_shift_seconds (float) – Minimum circular shift in seconds.

• behavior_fps (float) – Behavior sampling rate.

• si_weight_mode (str) – "amplitude" or "binary".

• random_seed (int | None) – Random seed for reproducibility.

• percentile (float) – Percentile to compute (default 95).

Returns:

Per-bin percentile of the shuffled normalized rate maps.

Return type:

np.ndarray

placecell.analysis.compute_stability_score(unit_events: DataFrame, trajectory_df: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray, activity_sigma: float = 1.0, behavior_fps: float = 20.0, min_occupancy: float = 0.1, occupancy_sigma: float = 0.0, n_split_blocks: int = 10, block_shift: float = 0.0, n_shuffles: int = 0, random_seed: int | None = None, min_shift_seconds: float = 0.0, si_weight_mode: str = 'amplitude') → tuple[float, float, float, ndarray, ndarray, ndarray]

Compute stability score by comparing rate maps from split data.

Divides the session into n_split_blocks interleaved temporal blocks, assigns odd/even blocks to each half, computes rate maps, and returns the Pearson correlation between them.

Optionally runs a shuffle significance test (Shuman et al. 2020): circularly shifts events and computes the split-half correlation for each shuffle to build a null distribution.

Parameters:

• unit_events (DataFrame) – DataFrame with x, y, s, beh_frame_index columns for a single unit.

• trajectory_df (DataFrame) – Speed-filtered trajectory with beh_frame_index column.

• occupancy_time (ndarray) – Occupancy time map (full session, for reference).

• valid_mask (ndarray) – Valid occupancy mask (full session).

• x_edges (ndarray) – Spatial bin edges.

• y_edges (ndarray) – Spatial bin edges.

• activity_sigma (float) – Gaussian smoothing sigma for rate maps.

• behavior_fps (float) – Behavior sampling rate.

• min_occupancy (float) – Minimum occupancy time in seconds for a bin to be valid.

• occupancy_sigma (float) – Gaussian smoothing sigma for occupancy maps (default 0.0 = no smoothing).

• n_split_blocks (int) – Number of temporal blocks for interleaved splitting.

• block_shift (float) – Fraction of one block width (0.0 to <1.0) to shift block boundaries. Shifts are circular with period 1.0.

• n_shuffles (int) – Number of shuffles for stability significance test. 0 means no shuffle test (return NaN for p-value).

• random_seed (int | None) – Random seed for reproducibility.

• min_shift_seconds (float) – Minimum circular shift in seconds for shuffle test.

• si_weight_mode (str) – "amplitude" weights events by their s value; "binary" counts each event as 1.

Returns:

(correlation, fisher_z, stability_p_val, rate_map_first, rate_map_second, shuffled_corrs)

correlation: Pearson correlation between the two rate maps fisher_z: Fisher z-transformed correlation stability_p_val: Shuffle-based p-value (NaN if n_shuffles=0) rate_map_first: Rate map from first half rate_map_second: Rate map from second half shuffled_corrs: Array of shuffled correlations (empty if n_shuffles=0)

Return type:

tuple

placecell.analysis.compute_unit_analysis(unit_id: int, df_filtered: DataFrame, trajectory_df: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray, activity_sigma: float = 1.0, event_threshold_sigma: float = 2.0, n_shuffles: int = 100, random_seed: int | None = None, behavior_fps: float = 20.0, min_occupancy: float = 0.1, occupancy_sigma: float = 0.0, min_shift_seconds: float = 0.0, si_weight_mode: str = 'amplitude', place_field_seed_percentile: float = 95.0, n_split_blocks: int = 10, block_shifts: list[float] | None = None) → dict

Compute rate map, spatial information, stability, and thresholded events for a unit.

Parameters:

• unit_id (int) – Unit identifier.

• df_filtered (DataFrame) – Speed-filtered event data with columns unit_id, x, y, s, beh_frame_index.

• trajectory_df (DataFrame) – Speed-filtered trajectory with beh_frame_index column.

• occupancy_time (ndarray) – Occupancy time map.

• valid_mask (ndarray) – Valid occupancy mask.

• x_edges (ndarray) – Spatial bin edges.

• y_edges (ndarray) – Spatial bin edges.

• activity_sigma (float) – Gaussian smoothing sigma for rate map.

• event_threshold_sigma (float) – Sigma multiplier for event amplitude threshold.

• n_shuffles (int) – Number of shuffles for significance test.

• random_seed (int | None) – Random seed for reproducibility.

• behavior_fps (float) – Behavior sampling rate for stability computation.

• min_occupancy (float) – Minimum occupancy time for stability computation.

• occupancy_sigma (float) – Gaussian smoothing sigma for occupancy maps in stability computation.

• min_shift_seconds (float) – Minimum circular shift in seconds for shuffle significance test.

• si_weight_mode (str) – Weight mode for SI: "amplitude" or "binary".

• place_field_seed_percentile (float) – Percentile of shuffled rate maps for seed detection (Guo et al. 2023).

• n_split_blocks (int) – Number of temporal blocks for interleaved stability splitting.

• block_shifts (list[float] | None) – List of block boundary shifts as fractions of one block width. Each produces an independent split; results are Fisher z-averaged. Defaults to [0.0] (single split, no shift).

Returns:

Analysis results with keys: rate_map, si, p_val, shuffled_sis, events_above_threshold, vis_threshold, stability_corr, stability_z, rate_map_first, rate_map_second.

Return type:

dict

placecell.analysis.compute_raw_rate_map(unit_events: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray) → ndarray

Compute unsmoothed binned spatial activity rate.

This is the raw event-weight / occupancy-time rate without Gaussian smoothing or min-max normalization. It is used for place field boundary detection where smoothing would artificially widen the field.

Parameters:

• unit_events (DataFrame) – DataFrame with x, y, s columns for a single unit.

• occupancy_time (ndarray) – Occupancy time map.

• valid_mask (ndarray) – Valid occupancy mask.

• x_edges (ndarray) – Spatial bin edges.

• y_edges (ndarray) – Spatial bin edges.

Returns:

Unsmoothed rate map. Invalid bins are set to NaN.

Return type:

np.ndarray

placecell.analysis.compute_place_field_mask(rate_map: ndarray, shuffled_rate_p95: ndarray, threshold: float = 0.05, min_bins: int = 5) → ndarray

Compute a binary mask of the place field from a rate map.

Implements the place field detection algorithm from Guo et al. 2023 (Science Advances, Supplementary Methods lines 1013-1020):

1. Seed detection: find bins where the actual rate exceeds the 95th percentile of the shuffled rate (shuffled_rate_p95). Only contiguous seed regions with >= min_bins bins are kept.

2. Extension: from each seed region, extend to all contiguous bins whose rate >= threshold × (seed region’s peak rate).

Parameters:

• rate_map (ndarray) – Smoothed, normalized (0-1) rate map. NaN bins are treated as outside the field.

• threshold (float) – Fraction of peak rate for field extension (step 2).

• min_bins (int) – Minimum number of contiguous bins for a seed region (step 1).

• shuffled_rate_p95 (ndarray) – Per-bin 95th percentile of shuffled normalized rate maps.

Returns:

Boolean mask where True indicates the place field.

Return type:

np.ndarray

placecell.analysis.compute_coverage_map(unit_results: dict, threshold: float = 0.05, min_bins: int = 5) → ndarray

Compute combined place field coverage across all units.

For each unit, thresholds the smoothed rate map to define the place field, then sums all binary masks to get the number of overlapping fields at each spatial bin.

Parameters:

• unit_results (dict) – Dictionary mapping unit_id to analysis results (must contain ‘rate_map’).

• threshold (float) – Fraction of peak rate to define place field boundary.

• min_bins (int) – Minimum contiguous bins for a connected component to count.

Returns:

Integer array of place field overlap counts at each bin.

Return type:

np.ndarray

placecell.analysis.compute_coverage_curve(unit_results: dict, valid_mask: ndarray, threshold: float = 0.05, min_bins: int = 5) → tuple[ndarray, ndarray]

Compute cumulative coverage curve: fraction of environment covered vs number of cells.

Cells are added one at a time (largest field first). At each step, the fraction of valid bins covered by at least one place field is recorded.

Parameters:

• unit_results (dict) – Dictionary mapping unit_id to analysis results (must contain ‘rate_map’).

• valid_mask (ndarray) – Boolean mask of valid spatial bins.

• threshold (float) – Fraction of peak rate to define place field boundary.

• min_bins (int) – Minimum contiguous bins for a connected component to count.

Returns:

(n_cells_array, coverage_fraction_array) where n_cells goes from 0 to N.

Return type:

tuple