camap.analysis.spatial_2d

camap.analysis.spatial_2d#

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 raw 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 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.

camap.analysis.spatial_2d.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

camap.analysis.spatial_2d.compute_occupancy_map(trajectory_df: DataFrame, bins: int, behavior_fps: float, spatial_sigma: float = 1.0, min_occupancy: float = 0.1) → tuple[ndarray, ndarray, ndarray, ndarray]#

Compute raw 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.
spatial_sigma (float) – Gaussian smoothing sigma (bins). Used only to compute valid_mask robustly at the edges; occupancy_time itself is returned unsmoothed so downstream smoothing in compute_rate_map() etc. doesn’t compound to sigma·sqrt(2).
min_occupancy (float) – Minimum occupancy time in seconds (checked against the smoothed occupancy for the mask).

Returns:

(occupancy_time, valid_mask, x_edges, y_edges) — occupancy_time is raw (seconds per bin); valid_mask comes from the smoothed copy.

Return type:

tuple

camap.analysis.spatial_2d.compute_rate_map(unit_events: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray, spatial_sigma: float = 1.0, normalize: bool = True) → ndarray#

Compute smoothed 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.
spatial_sigma (float) – Gaussian smoothing sigma for rate map.
normalize (bool) – If True (default), divide by the peak so the map spans 0-1 (convenient for display and for the place-field algorithm, which expects normalized maps). Set to False to keep firing-rate units (events·s⁻¹ per bin) for quantitative analyses such as population-vector overlap.

Returns:

Smoothed rate map. Invalid bins are NaN.

Return type:

np.ndarray

camap.analysis.spatial_2d.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', spatial_sigma: float = 0.0) → tuple[float, float, ndarray]#

Compute spatial information and significance via shuffling.

Parameters:

unit_events (DataFrame) – DataFrame with x, y, s, frame_index columns for a single unit.
trajectory_df (DataFrame) – Speed-filtered trajectory with 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.
spatial_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

camap.analysis.spatial_2d.compute_shuffled_rate_percentile(unit_events: DataFrame, trajectory_df: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray, spatial_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 place-field algorithm. For each shuffle iteration, circularly shifts event times relative to the trajectory and computes a smoothed rate map in firing-rate units (events·s⁻¹ per bin), then returns the requested percentile across shuffles at each spatial bin.

Output is in the same units as rate_map_smoothed so they can be compared bin-for-bin in compute_place_field_mask.

Parameters:

unit_events (DataFrame) – DataFrame with x, y, s, frame_index columns for a single unit.
trajectory_df (DataFrame) – Speed-filtered trajectory with 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.
spatial_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 rate maps in firing-rate units.

Return type:

np.ndarray

camap.analysis.spatial_2d.compute_stability_score(unit_events: DataFrame, trajectory_df: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray, spatial_sigma: float = 1.0, behavior_fps: float = 20.0, min_occupancy: float = 0.1, 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 contiguous temporal blocks, assigns odd/even blocks to each half, computes rate maps, and returns the Pearson correlation between them.

Note: n_split_blocks=2 is equivalent to a classic first-half/second-half split, which is sensitive to session-long drift (baseline, motivation, photobleaching). n_split_blocks>=4 interleaves the halves so within-session drift averages out; it tests stability at a finer timescale. Passing both (e.g. stability_splits=[2, 10]) lets a unit be called stable only if it passes at both timescales.

Optionally runs a shuffle significance test: circularly shifts events and computes the split-half correlation for each shuffle to build a null distribution. Degenerate iterations (no overlapping valid bins, or fewer than 3 jointly-finite bins) are skipped rather than counted as 0; the p-value uses the count of valid shuffles in its denominator (Phipson & Smyth 2010).

Parameters:

unit_events (DataFrame) – DataFrame with x, y, s, frame_index columns for a single unit.
trajectory_df (DataFrame) – Speed-filtered trajectory with 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.
spatial_sigma (float) – Gaussian smoothing sigma (in bins) for occupancy and rate maps.
behavior_fps (float) – Behavior sampling rate.
min_occupancy (float) – Minimum occupancy time in seconds for a bin to be valid.
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

camap.analysis.spatial_2d.compute_unit_analysis(unit_id: int, df_filtered: DataFrame, trajectory_df: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray, scfg: SpatialMap2DConfig, behavior_fps: float, random_seed: int | None = None) → dict#

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

Units with fewer than scfg.min_events events skip the shuffle tests and return p_val=1.0: with very few events the shuffle null is narrow enough that a single well-placed event can clear p<0.05 by chance. Set min_events=0 to disable the gate. Rate maps are still returned for these units.

Parameters:

unit_id (int) – Unit identifier.
df_filtered (DataFrame) – Speed-filtered event data with columns unit_id, x, y, s, frame_index.
trajectory_df (DataFrame) – Speed-filtered trajectory with 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.
scfg (SpatialMap2DConfig) – Spatial map configuration (smoothing, shuffle, stability parameters).
behavior_fps (float) – Behavior sampling rate.
random_seed (int | None) – Random seed for reproducibility.

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

camap.analysis.spatial_2d.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

camap.analysis.spatial_2d.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.

Two-step seed-and-extend algorithm:

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.
Extension: from each seed region, extend to all contiguous bins whose rate >= threshold × (seed region’s peak rate).

Parameters:

rate_map (ndarray) – Smoothed rate map. Must be in the same units as shuffled_rate_p95 — either both in firing-rate units (preferred; pass UnitResult.rate_map_smoothed) or both peak-normalized. NaN bins are treated as outside the field.
threshold (float) – Fraction of peak rate for field extension (step 2). Dimensionless and scale-invariant, so it works for either rate-map convention.
min_bins (int) – Minimum number of contiguous bins for a seed region (step 1).
shuffled_rate_p95 (ndarray) – Per-bin 95th percentile of shuffled rate maps, in the same units as rate_map.

Returns:

Boolean mask where True indicates the place field.

Return type:

np.ndarray

camap.analysis.spatial_2d.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

camap.analysis.spatial_2d.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

camap.analysis.spatial_2d

On this page

camap.analysis.spatial_2d#