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, n_cells_arr, ...)

Place field coverage map and cumulative coverage curve.

plot_diagnostics(unit_results[, ...])

Event count diagnostics: histogram, SI vs events, p-value vs events.

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 alongside occupancy heatmap.

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_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 tube 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_summary_scatter(unit_results[, ...])

Summary scatter plots: p-value, SI vs Z, and density contour.
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_summary_scatter(unit_results: dict, p_value_threshold: float = 0.05) → Figure#

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

Panel 1: Significance 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.

Return type:

Figure

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

Event count diagnostics: histogram, SI vs events, p-value vs events.

Parameters:

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

  • p_value_threshold (float) – Threshold for significance test.

Return type:

Figure

placecell.visualization.plot_behavior_preview(trajectory: DataFrame, trajectory_filtered: DataFrame, speed_threshold: float, speed_unit: str = 'mm/s') → Figure#

Raw vs filtered trajectory and speed histogram.

Parameters:

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

  • 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’).

Return type:

Figure

placecell.visualization.plot_occupancy_preview(trajectory_filtered: DataFrame, occupancy_time: ndarray, valid_mask: ndarray, x_edges: ndarray, y_edges: ndarray) → Figure#

Filtered trajectory alongside occupancy heatmap.

Parameters:

  • trajectory_filtered (DataFrame) – Speed-filtered trajectory.

  • occupancy_time (ndarray) – Occupancy time map (bins x bins).

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

  • x_edges (ndarray) – Spatial bin edges.

  • y_edges (ndarray) – Spatial bin edges.

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, n_cells_arr: ndarray, coverage_frac: ndarray, x_edges: ndarray, y_edges: ndarray, valid_mask: ndarray, n_place_cells: int) → Figure#

Place field coverage map and cumulative coverage curve.

Parameters:

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

  • n_cells_arr (ndarray) – Number of place cells at each step of the cumulative curve.

  • coverage_frac (ndarray) – Fraction of environment covered at each step.

  • 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, tube_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. Tubes in tube_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).

  • tube_order (list[str]) – Ordered list of tube 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, tube_boundaries: list[float] | None = None, tube_labels: list[str] | None = None, title: str = '', ax: Axes | None = None) → Figure#

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

Parameters:

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

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

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

  • tube_labels (list[str] | None) – Labels for each tube 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, tube_boundaries: list[float] | None = None, tube_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.

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

  • tube_labels (list[str] | None) – Labels for each tube 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, tube_boundaries: list[float] | None = None, tube_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 (before speed filter). If provided, plotted as a light background layer under the filtered trajectory.

  • tube_boundaries (list[float] | None) – Position values at tube boundaries.

  • tube_labels (list[str] | None) – Labels for each tube 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, tube_boundaries: list[float] | None = None, tube_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.

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

  • tube_labels (list[str] | None) – Labels for each tube segment.

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

  • trace_height (float)

  • time_unit (str)

Return type:

Figure

On this page