API reference

MapperExplorer

Return value of mapper_explorer. Wraps the interactive Figure together with the selected_node observable.

Fields

• figure::Figure: the two-panel figure (mapper graph + data scatter).
• selected_node::Observable{Union{Nothing,Int}}: the currently selected node id (nothing when no node is selected).

Displaying a MapperExplorer displays its figure, so you can return it from a REPL/notebook cell directly. You may also access result.figure explicitly.

_data_positions(M; data, dims)

Compute the right-panel data positions. If data is given (a vector of points or tuples with 2 or 3 coordinates) it is used directly; otherwise the first 2–3 coordinates of M.X are taken, honoring dims like metricspace_plot.

Returns (positions, ndims).

_diagram_limits(diags, infinity=nothing)

Compute axis limits and infinity value for a collection of persistence diagrams. Returns (t_lo, t_hi, infinity).

_dim_str(diag)

Format the dimension of a PersistenceDiagram as a subscript string (e.g. H₀, H₁).

Find the most common string in a collection. In case of ties, join up to max_ties values with "/".

_node_geometry(M; node_positions, node_size, node_values, layout_function)

Compute the shared node geometry used by both mapper_plot and mapper_explorer: node positions (via layout_function unless given), node sizes (∝ cover-element size, rescaled, unless given) and node values (via node_colors unless given). Returns (node_positions, node_size, node_values, dim).

barcode_plot(diags; infinity=nothing)

Plot a persistence barcode using Makie.

Accepts a single PersistenceDiagram or a Vector{PersistenceDiagram}. Bars are colored by homology dimension.

Keyword Arguments

• infinity: value at which to clamp infinite intervals. Auto-detected if nothing.

centroid(M::AbstractMapper)

Compute the centroid of each cover element, returning a dim × n_clusters matrix.

Each column is the mean of the points belonging to that cover element.

colorscale(v)

Map a numeric vector v to a color vector using the :inferno color scheme.

Values are min-max normalized to [0, 1] before mapping.

layout_diffmap(M::AbstractMapper; dim=2, kwargs...)

Diffusion Maps layout of mapper nodes.

layout_fa(M::AbstractMapper; dim=2, kwargs...)

Factor Analysis layout of mapper nodes.

layout_generic(M::AbstractMapper, f::Function)

Apply a dimensionality reduction function f to the centroids of the mapper cover elements.

f should accept a dim × n matrix and return a outdim × n matrix. Returns a vector of Point{outdim} suitable for plotting.

layout_hlle(M::AbstractMapper; dim=2, kwargs...)

Hessian Locally Linear Embedding layout of mapper nodes.

layout_ica(M::AbstractMapper; dim=2, kwargs...)

ICA (Independent Component Analysis) layout of mapper nodes.

Note: ICA uses a positional k argument rather than maxoutdim.

layout_isomap(M::AbstractMapper; dim=2, kwargs...)

Isomap layout of mapper nodes.

layout_kpca(M::AbstractMapper; dim=2, kwargs...)

Kernel PCA layout of mapper nodes.

layout_landmarks(M::AbstractMapper; dim=2)

Position each mapper node at the centroid of its cover element, projected to dim dimensions.

This uses the mean of each node's member points, including for Ball Mapper; the centroid need not coincide with the sampled landmark. No dimensionality reduction is fitted. For 2D/3D point clouds, set dim to match the ambient dimension; higher-dimensional inputs use the first dim coordinates.

layout_lem(M::AbstractMapper; dim=2, kwargs...)

Laplacian Eigenmaps layout of mapper nodes.

layout_lle(M::AbstractMapper; dim=2, kwargs...)

Locally Linear Embedding layout of mapper nodes.

layout_ltsa(M::AbstractMapper; dim=2, kwargs...)

Local Tangent Space Alignment layout of mapper nodes.

layout_mds(M::AbstractMapper; dim=2, kwargs...)

MDS (Multidimensional Scaling) layout of mapper nodes using cover element centroids.

layout_pca(M::AbstractMapper; dim=2, kwargs...)

PCA (Principal Component Analysis) layout of mapper nodes.

layout_ppca(M::AbstractMapper; dim=2, kwargs...)

Probabilistic PCA layout of mapper nodes.

layout_sfdp(M::AbstractMapper; dim=2, kwargs...)

SFDP (Scalable Force-Directed Placement) layout using the mapper graph topology.

layout_shell(M::AbstractMapper)

Shell layout using the mapper graph topology. Always 2D.

layout_spectral_graph(M::AbstractMapper; dim=2, kwargs...)

Spectral graph layout using the mapper graph topology.

layout_spring(M::AbstractMapper; dim=2, kwargs...)

Spring (force-directed) layout using the mapper graph topology.

layout_stress(M::AbstractMapper; dim=2, kwargs...)

Stress majorization layout using the mapper graph topology.

layout_tsne(M::AbstractMapper; dim=2, kwargs...)

t-SNE layout of mapper nodes.

layout_umap(M::AbstractMapper; dim=2, kwargs...)

UMAP layout of mapper nodes.

mapper_explorer(M::AbstractMapper; data=nothing, node_values=nothing,
    node_size=nothing, colormap=:viridis, edge_size=1,
    layout_function=NetworkLayout.Spring(dim=2), markersize=6,
    dims=nothing, inspector=false)

Build an interactive two-panel exploration figure for a mapper result.

The left panel renders the mapper graph using the same rules as mapper_plot (nodes sized ∝ cover-element size, colored by node_values). The right panel scatters the original data points. Selecting a node — by clicking it, or by setting the returned observable — highlights that node's member points on the right (full opacity) while dimming the rest, and outlines the selected node on the left.

Return value

A MapperExplorer which behaves like the NamedTuple (figure, selected_node):

• result.figure::Figure — the figure (also displayed automatically if you return result from a REPL/notebook cell).
• result.selected_node::Observable{Union{Nothing,Int}} — the selected node id, or nothing. Set it (result.selected_node[] = i) to drive the highlight programmatically; this is what tests exercise.

Keyword Arguments

• data: a vector of points/tuples with 2 or 3 coordinates for the right panel. Defaults to the first 2–3 coordinates of M.X (honoring dims).
• node_values: numeric values for coloring nodes (default: node_colors). Only numeric node_values are supported here (categorical coloring is not — use mapper_plot for that).
• node_size: sizes for each node (default: ∝ cover-element size, rescaled).
• colormap: Makie colormap for node_values (default: :viridis).
• edge_size: line width for graph edges (default: 1).
• layout_function: a NetworkLayout algorithm for node positions (default: NetworkLayout.Spring(dim=2)).
• markersize: marker size for the right-panel data points (default: 6).
• dims: which dimensions of M.X to plot when data is not given (e.g. [1, 3]). Defaults to the first 2 or 3 dimensions.
• inspector: if true, instantiate a DataInspector so hovering a node shows a tooltip (default: false). Hover tooltips require an interactive backend (e.g. GLMakie/WGLMakie); on non-interactive backends this is a no-op. The node scatter always carries an inspector_label, so enabling a DataInspector yourself works too.

Example

using GLMakie, TDAplots
using MetricSpaces.Datasets: sphere

X = sphere(200, dim=2)
fv = first.(X)
ic = TDAmapper.ImageCovers.R1Cover(fv, TDAmapper.IntervalCovers.Uniform(length=5, expansion=0.3))
M = classical_mapper(X, ic, TDAmapper.Refiners.DBscan(radius=0.2))

res = mapper_explorer(M; inspector=true)
res.figure                      # the figure (hover a node, or click it)
res.selected_node[] = 3         # programmatically select node 3
res.selected_node[] = nothing   # clear the selection

mapper_plot(M::AbstractMapper; kwargs...)

Plot a mapper graph using Makie.

Keyword Arguments

• node_positions: positions for each node (default: Spring layout)
• node_size: sizes for each node (default: proportional to cover element size)
• node_values: values for coloring nodes (default: mean of first coordinate per cover element). Can be a Vector{<:Number} (colorscale) or Vector{<:AbstractString} (categorical legend).
• colormap: Makie colormap for numeric node_values (default: :viridis)
• edge_size: line width for edges (default: 1)
• show_node_ids: if true, overlay each node's integer index (default: false)
• layout_function: a NetworkLayout algorithm (default: NetworkLayout.Spring(dim=2))

metricspace_plot(X::EuclideanSpace; dims=nothing, color=nothing, colormap=:viridis, markersize=10)

Plot a EuclideanSpace as a scatter plot using Makie.

Keyword Arguments

• dims: which dimensions to plot (e.g., [1, 3, 5]). Defaults to the first 2 or 3 dimensions.
• color: a Vector{<:Number} (mapped to a colorscale with colorbar) or a Vector{<:AbstractString} (categorical, with legend). If nothing, uses a default color.
• colormap: Makie colormap used when color is numeric (default: :viridis).
• markersize: marker size (default: 10).

node_colors(M::AbstractMapper, v::Vector{<:Number}; f::Function=mean)

Compute a summary value for each node (cover element) in the mapper graph.

For each cover element, applies f to the subset of v indexed by that element. If v is not provided, defaults to the first coordinate of each point.

node_colors(M::AbstractMapper, v::Vector{<:AbstractString}; f::Function=_mode_string)

Compute a categorical label for each node by finding the most common string in each cover element.

persistence_plot(diags; persistence=false, infinity=nothing, markersize=10)

Plot a persistence diagram using Makie.

Accepts a single PersistenceDiagram or a Vector{PersistenceDiagram} (e.g. from TDARipserer). Points are colored by homology dimension.

Keyword Arguments

• persistence: if true, plot (birth, persistence) instead of (birth, death). Default: false.
• infinity: value at which to clamp infinite intervals. Auto-detected if nothing.
• markersize: marker size for scatter points. Default: 10.

rescale(x; min=0, max=1)

Rescale a numeric vector x to lie within [min, max].

rescale(; min=0, max=1)

Return a curried version of rescale.

tomato_graph_plot(X::EuclideanSpace, g, values)

Given a nonempty Euclidean space X with at least 2 coordinates, a graph g whose vertices match point IDs, and a numeric vector values (one per point), plot graph edges and observations colored by values. Inputs with more than 3 coordinates use their first 3 coordinates without fitting an embedding.

The plot uses a continuous colorbar. For a categorical cluster legend, use metricspace_plot with color=string.(labels) instead. Returns a Makie Figure.

tomato_persistence_plot(births_and_deaths; max_value_multiplier=1.3)

Plot the nonempty ToMATo dictionary peak_point_id => [birth_density, death_density] as (birth_density, birth_density - death_density). To inspect recorded finite mode prominences before selecting a threshold, use a ToMATo run with τ=Inf; that run allows merging without a finite prominence cutoff.

death_density=Inf denotes an unmerged mode. Its resulting -Inf ordinate is displayed at max_value_multiplier times the largest finite prominence, or times the largest birth if no finite prominences exist. This is a display surrogate, not a measured finite lifetime; the helper does not specially mark these points. Returns a Makie FigureAxisPlot, whose .axis can be labelled.