placecell.visualization

placecell.visualization#

Visualization functions for place cell analysis.

Functions

plot_arena_calibration(trajectory, arena_bounds)

Plot arena calibration overlay on trajectory and optional video frame.

plot_behavior_preview(trajectory, ...[, ...])

Raw vs filtered trajectory and speed histogram.

plot_coverage(coverage_map, x_edges, ...)

Place field coverage heatmap.

plot_diagnostics(unit_results[, ...])

Event count histogram across all units.

plot_footprints(max_proj, footprints)

Max projection, cell footprint contours, and overlay.

plot_footprints_filled(max_proj, footprints)

Max projection and filled spatial footprints side by side.

plot_graph_overlay(graph_polylines, ...[, ...])

Overlay behavior graph polylines on a video frame.

plot_occupancy_preview(trajectory_filtered, ...)

Filtered trajectory, full occupancy, and split-half occupancy maps.

plot_occupancy_preview_1d(...[, ...])

1D position time series and occupancy bar chart.

plot_position_and_traces_1d(trajectory_1d, ...)

Time-synced 1D position trace and example place cell calcium traces.

plot_position_and_traces_2d(trajectory, ...)

Time-synced 2D speed trace and example place cell calcium traces.

plot_preprocess_steps(steps, arena_size_mm)

Plot trajectory at each behavior preprocessing stage.

plot_rate_map_1d(rate_map, edges[, ...])

Plot a 1D rate map as a filled line plot with arm boundaries.

plot_session_summary(summary_df)

Across-session counts and proportions of place cell classifications.

plot_shuffle_test_1d(unit_results, edges[, ...])

Population rate map heatmap for all place cells (Guo et al. 2023 style).

plot_speed_histogram(speeds, speed_threshold)

Speed distribution histogram with threshold line.

plot_summary_scatter(unit_results[, ...])

Summary scatter plots: p-value, SI vs Z, and density contour.

plot_timestamp_diagnostics(trajectory_raw, ...)

Plot data index vs. unix timestamp for behavior and neural streams.
placecell.visualization.plot_session_summary(summary_df: pd.DataFrame) → Figure#

Across-session counts and proportions of place cell classifications.

Parameters:

summary_df (pd.DataFrame) – DataFrame with columns dataset, n_total, n_sig, n_stable, n_place_cells. One row per session.

Return type:

Figure

placecell.visualization.plot_timestamp_diagnostics(trajectory_raw: pd.DataFrame | None, canonical: pd.DataFrame | None) → Figure#

Plot data index vs. unix timestamp for behavior and neural streams.

A healthy recording produces a near-linear ramp with no flat segments (duplicate timestamps), no backward jumps (non-monotonic), and similar slopes (sample rates) between the two panels. Deviations here can explain downstream alignment artefacts.

Parameters:

  • trajectory_raw (pd.DataFrame | None)

  • canonical (pd.DataFrame | None)

Return type:

Figure

placecell.visualization.plot_summary_scatter(unit_results: dict, p_value_threshold: float = 0.05, n_shuffles: int | None = None, min_shift_seconds: float | None = None) → Figure#

Summary scatter plots: p-value, SI vs Z, and density contour.

Panel 1: SI p-value vs stability p-value scatter. Panel 2: SI vs Fisher Z scatter. Panel 3: SI vs stability density contour (Guo et al. style) with

place cells vs non-place cells as separate contour groups and marginal KDE histograms.

Parameters:

  • unit_results (dict) – Dictionary mapping unit_id to analysis results.

  • p_value_threshold (float) – Threshold for significance test.

  • n_shuffles (int | None) – Number of shuffles used for the SI significance test.

  • min_shift_seconds (float | None) – Minimum circular shift in seconds used for shuffling.

Return type:

Figure

placecell.visualization.plot_diagnostics(unit_results: dict, p_value_threshold: float = 0.05) → Figure#

Event count histogram across all units.

Parameters:

  • unit_results (dict) – Dictionary mapping unit_id to analysis results.

  • p_value_threshold (float) – Threshold for significance test (used for logging only).

Return type:

Figure

placecell.visualization.plot_speed_histogram(speeds: ndarray, speed_threshold: float, speed_unit: str = 'mm/s', n_filtered: int | None = None, n_total: int | None = None) → Figure#

Speed distribution histogram with threshold line.

Parameters:

  • speeds (ndarray) – All speed values (before filtering).

  • speed_threshold (float) – Minimum speed for inclusion.

  • speed_unit (str) – Label for the x-axis.

  • n_filtered (int | None) – Frame counts for the title annotation.

  • n_total (int | None) – Frame counts for the title annotation.

Return type:

Figure

placecell.visualization.plot_behavior_preview(trajectory: DataFrame, trajectory_filtered: DataFrame, speed_threshold: float, speed_unit: str = 'mm/s', speed_column: str = 'speed', trajectory_alpha: float = 0.1, trajectory_lw: float = 0.3) → Figure#

Raw vs filtered trajectory and speed histogram.

Parameters:

  • trajectory (DataFrame) – Full trajectory with columns x, y, and a speed column.

  • trajectory_filtered (DataFrame) – Speed-filtered trajectory.

  • speed_threshold (float) – Speed cutoff used for filtering.

  • speed_unit (str) – Label for speed axis (e.g. ‘mm/s’ or ‘px/s’).

  • speed_column (str) – Name of the speed column (default ‘speed’, use ‘speed_1d’ for maze).

  • trajectory_alpha (float) – Per-segment alpha for trajectory lines.

  • trajectory_lw (float) – Line width for trajectory lines.

Return type:

Figure

placecell.visualization.plot_occupancy_preview(trajectory_filtered: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray, behavior_fps: float = 20.0, n_split_blocks: int = 10, block_shift: float = 0.0, trajectory_alpha: float = 0.1, trajectory_lw: float = 0.3) → Figure#

Filtered trajectory, full occupancy, and split-half occupancy maps.

The trajectory panel uses low alpha so that repeatedly visited areas appear darker, showing occupancy density directly.

Parameters:

  • trajectory_filtered (DataFrame) – Speed-filtered trajectory with x, y, frame_index.

  • occupancy_time (ndarray) – Full-session occupancy time map (bins × bins).

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

  • x_edges (ndarray) – Spatial bin edges.

  • y_edges (ndarray) – Spatial bin edges.

  • behavior_fps (float) – Sampling rate for the trajectory (used for split-half time).

  • n_split_blocks (int) – Number of interleaved blocks for the split (same as stability).

  • block_shift (float) – Block boundary shift fraction (same as stability).

  • trajectory_alpha (float) – Per-segment alpha for the trajectory line. Low values (~0.03) let overlap accumulate to show density.

  • trajectory_lw (float) – Line width for the trajectory.

Return type:

Figure

placecell.visualization.plot_footprints(max_proj: ndarray, footprints: DataArray) → Figure#

Max projection, cell footprint contours, and overlay.

Parameters:

  • max_proj (ndarray) – Max-projection image.

  • footprints (DataArray) – Spatial footprints DataArray with unit_id coordinate.

Return type:

Figure

placecell.visualization.plot_footprints_filled(max_proj: ndarray, footprints: xr.DataArray, unit_ids: np.ndarray | list | None = None) → Figure#

Max projection and filled spatial footprints side by side.

Parameters:

  • max_proj (ndarray) – Max-projection image (H, W).

  • footprints (xr.DataArray) – Spatial footprints DataArray with unit_id coordinate.

  • unit_ids (np.ndarray | list | None) – Subset of unit IDs to show. If None, all units are shown.

Return type:

Figure

placecell.visualization.plot_coverage(coverage_map: ndarray, x_edges: ndarray, y_edges: ndarray, valid_mask: ndarray, n_place_cells: int) → Figure#

Place field coverage heatmap.

Each bin shows the fraction of place cells whose place field overlaps that location (overlapping fields / total place cells).

Parameters:

  • coverage_map (ndarray) – Overlap count per spatial bin.

  • x_edges (ndarray) – Spatial bin edges.

  • y_edges (ndarray) – Spatial bin edges.

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

  • n_place_cells (int) – Total number of place cells.

Return type:

Figure

placecell.visualization.plot_arena_calibration(trajectory: pd.DataFrame, arena_bounds: tuple[float, float, float, float], arena_size_mm: tuple[float, float] | None = None, mm_per_px: float | None = None, video_frame: np.ndarray | None = None) → Figure#

Plot arena calibration overlay on trajectory and optional video frame.

Shows the arena bounding box overlaid on the raw trajectory. If a video frame is provided, a second panel shows it with the same overlay.

Parameters:

  • trajectory (pd.DataFrame) – DataFrame with columns x, y.

  • arena_bounds (tuple[float, float, float, float]) – (x_min, x_max, y_min, y_max) in pixels.

  • arena_size_mm (tuple[float, float] | None) – (width, height) in mm. Used for the title only.

  • mm_per_px (float | None) – mm-per-pixel scale. Used for the title only.

  • video_frame (np.ndarray | None) – RGB image array (H, W, 3) from the behavior video. If provided, shown alongside the trajectory.

Return type:

Figure

placecell.visualization.plot_preprocess_steps(steps: dict[str, pd.DataFrame], arena_size_mm: tuple[float, float]) → Figure#

Plot trajectory at each behavior preprocessing stage.

All snapshots are expected to be in mm coordinates.

Parameters:

  • steps (dict[str, pd.DataFrame]) – Ordered dict mapping step name → DataFrame with x, y in mm. Typically from ds._preprocess_steps.

  • arena_size_mm (tuple[float, float]) – (width, height) in mm.

Return type:

Figure

placecell.visualization.plot_graph_overlay(graph_polylines: dict[str, list[list[float]]], mm_per_pixel: float, arm_order: list[str], video_frame: np.ndarray | None = None) → Figure#

Overlay behavior graph polylines on a video frame.

Each zone’s polyline is drawn in pixel coordinates on the video frame. Arms in arm_order are drawn with distinct colors; other zones (rooms, etc.) are drawn in gray.

Parameters:

  • graph_polylines (dict[str, list[list[float]]]) – Dict mapping zone name to list of [x, y] waypoints in pixels.

  • mm_per_pixel (float) – Scale factor (for title annotation).

  • arm_order (list[str]) – Ordered list of arm zone names (drawn with distinct colors).

  • video_frame (np.ndarray | None) – RGB image (H, W, 3). If None, polylines are drawn on a white background.

Return type:

Figure

placecell.visualization.plot_rate_map_1d(rate_map: ndarray, edges: ndarray, arm_boundaries: list[float] | None = None, arm_labels: list[str] | None = None, title: str = '', ax: Axes | None = None) → Figure#

Plot a 1D rate map as a filled line plot with arm boundaries.

Parameters:

  • rate_map (ndarray) – 1D rate map array (n_bins,).

  • edges (ndarray) – Bin edges (n_bins + 1,).

  • arm_boundaries (list[float] | None) – Position values at arm boundaries (vertical lines).

  • arm_labels (list[str] | None) – Labels for each arm segment.

  • title (str) – Plot title.

  • ax (Axes | None) – Optional axes to plot on.

Return type:

Figure

placecell.visualization.plot_shuffle_test_1d(unit_results: dict, edges: ndarray, p_value_threshold: float = 0.05, arm_boundaries: list[float] | None = None, arm_labels: list[str] | None = None) → Figure#

Population rate map heatmap for all place cells (Guo et al. 2023 style).

Each row is a place cell sorted by peak position, columns are spatial bins. Invalid (low-occupancy) bins are excluded so there are no gaps.

Parameters:

  • unit_results (dict) – Dictionary mapping unit_id to UnitResult.

  • edges (ndarray) – 1D bin edges array.

  • p_value_threshold (float) – Threshold for classifying place cells.

  • arm_boundaries (list[float] | None) – Arm boundary positions for vertical markers.

  • arm_labels (list[str] | None) – Labels for each arm segment.

Return type:

Figure

placecell.visualization.plot_occupancy_preview_1d(trajectory_1d_filtered: pd.DataFrame, occupancy_time: ndarray, valid_mask: ndarray, edges: ndarray, trajectory_1d: pd.DataFrame | None = None, trajectory_1d_all: pd.DataFrame | None = None, arm_boundaries: list[float] | None = None, arm_labels: list[str] | None = None) → Figure#

1D position time series and occupancy bar chart.

Parameters:

  • trajectory_1d_filtered (pd.DataFrame) – Speed-filtered 1D trajectory with pos_1d and unix_time columns.

  • occupancy_time (ndarray) – 1D occupancy histogram.

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

  • edges (ndarray) – Bin edges.

  • trajectory_1d (pd.DataFrame | None) – Unfiltered 1D trajectory (after complete-traversal filter but before speed filter). Plotted as a layer under the speed-filtered.

  • trajectory_1d_all (pd.DataFrame | None) – All traversals including incomplete ones (before complete-traversal filter). If provided, incomplete traversals are shown as a distinct background layer.

  • arm_boundaries (list[float] | None) – Position values at arm boundaries.

  • arm_labels (list[str] | None) – Labels for each arm segment.

Return type:

Figure

placecell.visualization.plot_position_and_traces_1d(trajectory_1d: pd.DataFrame, unit_results: dict, edges: ndarray, behavior_fps: float, speed_threshold: float = 0.0, trajectory_1d_filtered: pd.DataFrame | None = None, arm_boundaries: list[float] | None = None, arm_labels: list[str] | None = None, n_units: int = 20, trace_height: float = 0.5, time_unit: str = 'min') → Figure#

Time-synced 1D position trace and example place cell calcium traces.

Top panel shows serialized 1D position over time. Bottom panel shows n_units calcium traces (from place cells, sorted by peak position) stacked vertically with a shared time axis.

Parameters:

  • trajectory_1d (pd.DataFrame) – Unfiltered 1D trajectory with pos_1d and frame_index columns.

  • unit_results (dict) – Dict of unit_id -> UnitResult. Only units whose trace_data is not None are plotted.

  • edges (ndarray) – 1D bin edges (for computing peak position to sort cells).

  • behavior_fps (float) – Behavior sampling rate (Hz).

  • speed_threshold (float) – Speed threshold used for filtering (shown in legend).

  • trajectory_1d_filtered (pd.DataFrame | None) – Speed-filtered trajectory. If provided, overlaid on top of the unfiltered trace.

  • arm_boundaries (list[float] | None) – Position values at arm segment boundaries.

  • arm_labels (list[str] | None) – Labels for each arm segment.

  • n_units (int) – Maximum number of traces to show (default 25).

  • trace_height (float)

  • time_unit (str)

Return type:

Figure

placecell.visualization.plot_position_and_traces_2d(trajectory: pd.DataFrame, unit_results: dict, behavior_fps: float, speed_threshold: float = 0.0, trajectory_filtered: pd.DataFrame | None = None, n_units: int = 20, trace_height: float = 0.5, time_unit: str = 'min', speed_unit: str = 'mm/s') → Figure#

Time-synced 2D speed trace and example place cell calcium traces.

Top panel shows animal speed over time with the speed threshold. Bottom panel shows n_units calcium traces (from place cells, sorted by spatial information) stacked vertically with a shared time axis.

Parameters:

  • trajectory (pd.DataFrame) – Unfiltered trajectory with speed and frame_index columns.

  • unit_results (dict) – Dict of unit_id -> UnitResult. Only units whose trace_data is not None are plotted.

  • behavior_fps (float) – Behavior sampling rate (Hz).

  • speed_threshold (float) – Speed threshold used for filtering (shown as dashed line).

  • trajectory_filtered (pd.DataFrame | None) – Speed-filtered trajectory. If provided, filtered count is shown in the legend.

  • n_units (int) – Maximum number of traces to show (default 20).

  • trace_height (float) – Vertical extent of each normalized trace (controls density).

  • time_unit (str) – "min" (default) or "s" for x-axis labels.

  • speed_unit (str) – Label for speed axis (e.g. "mm/s" or "px/s").

Return type:

Figure