circle_bundles.viz

Visualization utilities for circle_bundles.

Notes

Some visualizations depend on optional third-party libraries (plotly, dash, scikit-learn). Those imports are guarded so that importing this module does not fail if optional deps are missing.

circle_bundles.viz.base_vis(base_data, center_index, radius, dist_mat, *, figsize=(8, 6), dpi=150, use_pca=True, save_path=None, ax=None, clear_ax=True, show=True, other_alpha=0.5, other_s=10.0, neigh_alpha=0.8, neigh_s=25.0, center_s=60.0)[source]
Static 3D visualization of base points, highlighting:

  • the center point (red)

  • all points within radius (blue)

  • all other points (light gray)

Subplot usage

If ax is provided, it must be a 3D axis (projection=’3d’). The function draws into that axis and will not create a new figure.

Parameters:
circle_bundles.viz.fiber_vis(data, vis_func=None, *, vis_data=None, selected_indices=None, max_images=12, zoom=0.2, figsize=(10, 8), dpi=150, save_path=None, random_state=None, ax=None, clear_ax=True, show=True, scatter_alpha=0.15, scatter_s=10.0)[source]

Visualize up to max_images items from data by embedding them to 3D (PCA).

  • If vis_func is provided: overlay thumbnails rendered by vis_func.

  • If vis_func is None: just show the embedded points.

Parameters:

  • data ((N, d) array)

  • vis_func (optional callable(datum) -> (Figure | ndarray image)) – Something render_to_rgba can handle after vis_func returns. If None, no thumbnails are rendered; points only.

  • vis_data (optional data source for vis_func (same length N)) – If provided, thumbnails are rendered from vis_data[idx] while embedding uses data[idx].

  • selected_indices (optional explicit indices to visualize)

  • max_images (cap on number of items/points shown (and thumbnails if vis_func given))

  • random_state (RNG seed used when selected_indices is None)

  • usage (Subplot)

  • -------------

  • provided (If ax is)

  • case (it must be a 3D axis (projection='3d'). In that)

  • zoom (float)

  • dpi (int)

  • save_path (str | None)

  • clear_ax (bool)

  • show (bool)

  • scatter_alpha (float)

  • scatter_s (float)

:param : :param this function draws into ax and will not create a new figure.:

circle_bundles.viz.lattice_vis(data, coords, vis_func, *, per_row=7, per_col=7, padding=0.05, figsize=10, thumb_px=200, dpi=200, save_path=None, transparent_border=True, white_thresh=250, ax=None, clear_ax=True)[source]

Visualize a dataset by placing rendered thumbnails at 2D coordinates, using a lattice-based nearest-neighbor selection to pick representative examples.

The input coordinates are first affine-rescaled to the unit square [0, 1]^2. A regular lattice of target points (per_row × per_col) is created inside the unit square (inset from the border by padding). For each lattice target, the nearest unused datum is selected (greedy, without replacement). The selected thumbnails are then placed at their true rescaled positions, but mapped into a “safe center region” so that each thumbnail remains fully visible and is not clipped by the axes boundary.

Thumbnails are drawn by creating inset axes positioned in figure-fraction coordinates corresponding to the provided axis’ rectangle. This allows consistent pixel-sized thumbnails (thumb_px) regardless of axis data limits.

Parameters:

  • data (Sequence) – Sequence of N objects to visualize (one per coordinate).

  • coords (ndarray) – Array of shape (N, 2) giving 2D coordinates for each datum.

  • vis_func (Callable[[object], ndarray | Figure]) – Callable mapping a single datum to either an image array or a Matplotlib Figure. The output is converted to an RGBA image via render_to_rgba.

  • per_row (int) – Number of lattice targets in the x- and y-directions used for selecting representative points.

  • per_col (int) – Number of lattice targets in the x- and y-directions used for selecting representative points.

  • padding (float) – Inset margin (in [0, 0.49]) used when constructing lattice targets in the rescaled coordinate system.

  • figsize (float | Tuple[float, float]) – Figure size in inches if ax is None. If a single number is given, a square figure is created.

  • thumb_px (int) – Desired thumbnail size in pixels (square). This is enforced in figure pixel space; if too large relative to the figure/axis size, an error is raised.

  • dpi (int) – Dots-per-inch used when creating a new figure (ax is None) and when saving to disk.

  • save_path (str | None) – Optional path to save the resulting figure.

  • transparent_border (bool) – Passed to render_to_rgba. If True, attempts to make background whitespace transparent when trimming.

  • white_thresh (int) – Passed to render_to_rgba. Pixel intensity threshold for detecting near-white background when trimming/making transparent.

  • ax – Optional Matplotlib axis to draw into. If provided, thumbnails are placed within this axis’ rectangle in figure coordinates.

  • clear_ax (bool) – If True, clears ax before drawing and turns the axis off.

Returns:

  • fig (matplotlib.figure.Figure) – The figure containing the visualization.

  • ax (matplotlib.axes.Axes) – The base axis used as the placement region (turned off).

Raises:

ValueError – If coords is not shape (N, 2), if len(data) != N or N == 0, if per_row/per_col are non-positive, or if thumb_px is too large to fit within the figure or provided axis region.

Notes

Selection vs placement: lattice targets are used only to choose which data points to show; thumbnails are placed at the selected points’ actual rescaled coordinates (subject to the safe-center remapping that prevents clipping).

The selection procedure is greedy without replacement and may not produce a globally optimal assignment between lattice targets and points.

circle_bundles.viz.scatter_lattice_vis(data, coords, vis_func, *, selected_indices=None, per_row=7, per_col=7, padding=0.05, point_size=3.0, point_alpha=0.1, highlight_size=50.0, highlight_lw=1.5, thumb_px=30, thumb_offset_px=5, leader_line=False, leader_lw=0.8, figsize=10, dpi=200, save_path=None, transparent_border=True, white_thresh=250, ax=None, clear_ax=True)[source]

Scatter all points, highlight selected points, and draw each selected point’s thumbnail just to the left of its dot.

Selection:

  • If selected_indices is provided, use it.

  • Otherwise, select representatives via the same lattice-nearest-neighbor scheme used by lattice_vis (per_row x per_col, no reuse).

Placement:

  • All dots are plotted at their scaled coordinates in [0,1]^2.

  • Each selected thumbnail is placed in pixel space using Matplotlib’s offsetbox machinery, so the thumbnail is consistently sized and sits ‘thumb_offset_px’ pixels left of the dot.

Return type:

fig, ax, selected_indices

Parameters:
circle_bundles.viz.nerve_vis(landmarks, *, U=None, vertices=None, edges=None, triangles=None, cochains=None, base_colors=None, cochain_cmaps=None, max_dim=1, opacity=0.5, node_size=40, line_width=2, node_labels=None, fontsize=12, font_color='black', vis_func=None, data=None, image_zoom=0.2, save_path=None, title=None, draw_all_vertices=True, show=True, ax=None)[source]

Visualize (a subcomplex of) the witnessed Čech nerve.

Parameters:

  • landmarks (ndarray) – (M,2) or (M,3) coordinates of the nerve vertices (these are the plotting coords).

  • U (ndarray | None) – Optional (M, n_samples) boolean membership matrix. Used only to infer edges/triangles when they are not explicitly provided.

  • triangles (Iterable[Tuple[int, int, int]] | None) – Optional explicit simplices to draw. If provided, they take precedence over U.

  • Rules

  • -----

  • max_dim>=1 (- If edges is None and)

  • max_dim>=2 (- If triangles is None and)

  • set (- Vertex) –

    • If vertices is provided: use exactly those.

    • Else if draw_all_vertices: draw all 0..M-1.

    • Else: draw vertices that appear in edges/triangles (after they are determined).

  • vertices (Iterable[int] | None)

  • edges (Iterable[Tuple[int, int]] | None)

  • triangles

  • cochains (Dict[int, Dict[Any, Any]] | None)

  • base_colors (dict | None)

  • cochain_cmaps (dict | None)

  • max_dim (int)

  • opacity (float)

  • node_size (float)

  • line_width (float)

  • fontsize (int)

  • font_color (str)

  • image_zoom (float)

  • save_path (str | None)

  • title (str | None)

  • draw_all_vertices (bool)

  • show (bool)

circle_bundles.viz.compare_trivs(cover, f, *, edges=None, ncols='auto', title_size=14, align=False, s=1.0, save_path=None, show=True, max_pairs=25, metric='mean', return_selected=False)[source]

Backwards-compatible wrapper: accepts cover and calls compare_trivs_from_U(U=cover.U,…).

Parameters:
circle_bundles.viz.show_pca(data, *, colors=None, U=None, size=2.0, titles=None, max_points=2000, max_components=50, use_randomized=False, n_iter=4, jitter_eps=0.001, tol_flat_z=1e-06, random_state=0, set_cmap='viridis', set_cmap_range=(0.1, 0.9), elev=20, azim=35, interactive=False, show=True, return_figs=False, plotly_scroll_zoom=True, plotly_double_click='reset')[source]

PCA visualization (3D scatter + cumulative explained variance), side-by-side.

  • Fits PCA on the full dataset (up to max_components).

  • Plots first 3 PCs (subsampled to max_points).

  • Plots cumulative explained variance (CEV) vs k.

  • No printing.

Parameters:

  • interactive (bool) – If True, uses Plotly and returns a Plotly Figure (single combined figure). If False, uses Matplotlib for BOTH panels and returns a Matplotlib Figure.

  • plotly_scroll_zoom (bool) – If interactive, enables scroll zoom.

  • plotly_double_click (Union[bool, str]) – Plotly double-click behavior. Use “reset” (default), “autosize”, False, etc.

  • data (np.ndarray)

  • colors (Optional[Sequence])

  • U (Optional[np.ndarray])

  • size (float)

  • titles (Optional[List[str]])

  • max_points (int)

  • max_components (int)

  • use_randomized (bool)

  • n_iter (int)

  • jitter_eps (float)

  • tol_flat_z (float)

  • random_state (int)

  • set_cmap (str)

  • set_cmap_range (Tuple[float, float])

  • show (bool)

  • return_figs (bool)

Returns:

  • If return_figs=True –

    • interactive=True -> plotly.graph_objects.Figure

    • interactive=False -> matplotlib.figure.Figure

  • Else – None (but displays if show=True).

Return type:

Union[‘go.Figure’, ‘plt.Figure’, None]

circle_bundles.viz.show_data_vis(data, vis_func, *, angles=None, max_samples=100, n_cols=10, seed=None, save_path=None, label_func=None, label_position='below', sampling_method='angle', font_size=15, transparent_border=True, white_thresh=250, wspace=0.25, hspace=0.1, figsize_per_cell=2.0, dpi=150, pad_frac=0.1, show=True)[source]

Show a thumbnail grid of rendered data.

IMPORTANT: - data is treated as a Sequence. We do NOT coerce it to np.asarray(data),

because that can break for object-like payloads (meshes, images with varying shape, etc.)

Parameters:
Return type:

Tuple[Figure, ndarray]

circle_bundles.viz.show_bundle_vis(*, base_points, data, get_dist_mat=None, full_dist_mat=None, base_metric=None, same_metric=False, initial_r=0.1, r_max=2.0, colors=None, densities=None, data_landmark_inds=None, landmarks=None, max_samples=10000, rng=None, port=None, debug=False)[source]

General interactive viewer for (data, base_points) where base_points live in some metric space.

  • Neighborhoods come from dist_mat computed on base_points (via get_dist_mat/base_metric).

  • “Fiber Data” shows PCA of data restricted to the selected neighborhood.

Snapshots

The save button downloads a combined PDF (side-by-side) containing ONLY the two Plotly figures (no sliders, no UI).

Parameters: