camap.analysis.spatial_1d

camap.analysis.spatial_1d#

1D spatial analysis functions for place cells in linear tracks / arms.

Functions

compute_occupancy_map_1d(trajectory_df, ...)

Compute 1D occupancy histogram (raw).

compute_rate_map_1d(unit_events, ...[, ...])

Compute smoothed 1D rate map.

compute_raw_rate_map_1d(unit_events, ...[, ...])

Compute unsmoothed 1D rate map.

compute_spatial_information_1d(unit_events, ...)

Compute 1D spatial information with shuffle significance test.

compute_stability_score_1d(unit_events, ...)

Compute 1D split-half stability test.

compute_unit_analysis_1d(unit_id, ...[, ...])

Compute 1D rate map, SI, stability, and place field for a unit.

gaussian_filter_normalized_1d(data, sigma[, ...])

Apply 1D Gaussian smoothing with boundary normalization.
camap.analysis.spatial_1d.gaussian_filter_normalized_1d(data: ndarray, sigma: float, segment_bins: list[int] | None = None) → ndarray#

Apply 1D Gaussian smoothing with boundary normalization.

Uses zero-padding and normalizes by the kernel weight sum so that edge bins are not penalized.

Parameters:

  • data (ndarray) – 1D array to smooth.

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

  • segment_bins (list[int] | None) – Bin boundary indices for independent segments (e.g. [0, 50, 100, 200, 300] for 4 segments of varying length). Each segment [segment_bins[i]:segment_bins[i+1]] is smoothed independently. When None the whole array is smoothed as one.

Return type:

ndarray

camap.analysis.spatial_1d.compute_occupancy_map_1d(trajectory_df: DataFrame, n_bins: int, pos_range: tuple[float, float], behavior_fps: float, spatial_sigma: float = 1.0, min_occupancy: float = 0.1, pos_column: str = 'pos_1d', segment_bins: list[int] | None = None) → tuple[ndarray, ndarray, ndarray]#

Compute 1D occupancy histogram (raw).

Parameters:

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

  • n_bins (int) – Total number of spatial bins across all arms.

  • pos_range (tuple[float, float]) – (min, max) of the 1D position axis.

  • behavior_fps (float) – Behavior sampling rate.

  • spatial_sigma (float) – Gaussian smoothing sigma in bins. Used only to compute valid_mask; occupancy_time is returned unsmoothed so downstream smoothing in the rate-map/SI path doesn’t compound to sigma·sqrt(2).

  • min_occupancy (float) – Minimum occupancy in seconds (checked against the smoothed occupancy for the mask).

  • pos_column (str) – Column name for position values.

  • segment_bins (list[int] | None) – Bin boundary indices for per-segment smoothing.

Returns:

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

Return type:

tuple

camap.analysis.spatial_1d.compute_rate_map_1d(unit_events: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, edges: ndarray, spatial_sigma: float = 1.0, pos_column: str = 'pos_1d', segment_bins: list[int] | None = None, normalize: bool = True) → ndarray#

Compute smoothed 1D rate map.

When normalize is True (default) the map is divided by its peak so values span 0-1 (for display). Set normalize=False to keep firing-rate units (events·s⁻¹ per bin) for quantitative analyses such as population-vector overlap.

Parameters:

  • unit_events (DataFrame)

  • occupancy_time (ndarray)

  • valid_mask (ndarray)

  • edges (ndarray)

  • spatial_sigma (float)

  • pos_column (str)

  • segment_bins (list[int] | None)

  • normalize (bool)

Return type:

ndarray

camap.analysis.spatial_1d.compute_raw_rate_map_1d(unit_events: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, edges: ndarray, pos_column: str = 'pos_1d') → ndarray#

Compute unsmoothed 1D rate map.

Parameters:

  • unit_events (DataFrame)

  • occupancy_time (ndarray)

  • valid_mask (ndarray)

  • edges (ndarray)

  • pos_column (str)

Return type:

ndarray

camap.analysis.spatial_1d.compute_spatial_information_1d(unit_events: DataFrame, trajectory_df: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, 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, pos_column: str = 'pos_1d', segment_bins: list[int] | None = None) → tuple[float, float, ndarray]#

Compute 1D spatial information with shuffle significance test.

Same SI formula as 2D, applied to 1D bins. Circular shift shuffle.

Returns:

tuple

Return type:

(spatial_info, p_value, shuffled_sis)

Parameters:

  • unit_events (DataFrame)

  • trajectory_df (DataFrame)

  • occupancy_time (ndarray)

  • valid_mask (ndarray)

  • edges (ndarray)

  • n_shuffles (int)

  • random_seed (int | None)

  • min_shift_seconds (float)

  • behavior_fps (float)

  • si_weight_mode (str)

  • spatial_sigma (float)

  • pos_column (str)

  • segment_bins (list[int] | None)

camap.analysis.spatial_1d.compute_stability_score_1d(unit_events: DataFrame, trajectory_df: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, 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', pos_column: str = 'pos_1d', segment_bins: list[int] | None = None) → tuple[float, float, float, ndarray, ndarray, ndarray]#

Compute 1D split-half stability test.

Same block-splitting approach as 2D, with 1D rate maps. n_split_blocks=2 reduces to a first-half/second-half split (sensitive to session-long drift); n_split_blocks>=4 interleaves the halves so within-session drift averages out. Combining both (e.g. stability_splits=[2, 10]) tests stability at two different timescales. Degenerate shuffle iterations are skipped rather than counted as 0 (Phipson & Smyth 2010); see compute_stability_score().

Returns:

tuple – rate_map_first, rate_map_second, shuffled_corrs)

Return type:

(correlation, fisher_z, stability_p_val,

Parameters:

  • unit_events (DataFrame)

  • trajectory_df (DataFrame)

  • occupancy_time (ndarray)

  • valid_mask (ndarray)

  • edges (ndarray)

  • spatial_sigma (float)

  • behavior_fps (float)

  • min_occupancy (float)

  • n_split_blocks (int)

  • block_shift (float)

  • n_shuffles (int)

  • random_seed (int | None)

  • min_shift_seconds (float)

  • si_weight_mode (str)

  • pos_column (str)

  • segment_bins (list[int] | None)

camap.analysis.spatial_1d.compute_unit_analysis_1d(unit_id: int, df_filtered: DataFrame, trajectory_df: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, edges: ndarray, scfg: SpatialMap1DConfig, behavior_fps: float, random_seed: int | None = None, pos_column: str = 'pos_1d', segment_bins: list[int] | None = None) → dict#

Compute 1D rate map, SI, stability, and place field for a unit.

Returns same dict keys as the 2D compute_unit_analysis; see that function for the min_events gate semantics.

Parameters:

  • unit_id (int)

  • df_filtered (DataFrame)

  • trajectory_df (DataFrame)

  • occupancy_time (ndarray)

  • valid_mask (ndarray)

  • edges (ndarray)

  • scfg (SpatialMap1DConfig)

  • behavior_fps (float)

  • random_seed (int | None)

  • pos_column (str)

  • segment_bins (list[int] | None)

Return type:

dict