placecell.analysis.spatial_1d

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

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

Compute smoothed and normalized 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.
placecell.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

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

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.

  • min_occupancy (float) – Minimum occupancy in seconds.

  • 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) – all 1D arrays.

Return type:

tuple

placecell.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) → ndarray#

Compute smoothed and normalized 1D rate map.

Returns:

1D rate map normalized to 0-1 range. Invalid bins = NaN.

Return type:

np.ndarray

Parameters:

  • unit_events (DataFrame)

  • occupancy_time (ndarray)

  • valid_mask (ndarray)

  • edges (ndarray)

  • spatial_sigma (float)

  • pos_column (str)

  • segment_bins (list[int] | None)

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

placecell.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)

placecell.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 interleaved block-splitting approach as 2D, with 1D rate maps.

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)

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

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