A hole appears and disappears
Download the executed notebook · Build and environment record
Imagine nine squares arranged in a grid. The eight outer squares appear together, leaving a hole where the center will be; when the center arrives, that hole fills. We can predict the whole sequence from two numbers, then ask how the computation records it.
We will follow this growing shape, learn to read its answer as an interval, and change when the central square appears. The example introduces the spaces and maps that persistence keeps track of, beginning with a single parameter we can increase along a line. No previous knowledge of homology is needed.
To run the cells, use Julia 1.12 with TamerOp and CairoMakie in your active environment; the installation guide explains the setup.
Give each square an appearance grade
Import TamerOp as OP, so that a name such as OP.cubical_persistence identifies an operation supplied by this package. We also load CairoMakie to draw static figures. These imports use the packages already installed in the active environment.
import TamerOp as OP
import CairoMakie
CairoMakie.activate!(type="png", px_per_unit=1);An entry of the following matrix gives the appearance grade of one square: the parameter value at which we add it to the shape. The eight outer squares all have grade 0, while the central square has grade 5. Julia separates entries in a row by spaces and rows by semicolons.
We pass these values to ImageNd, which gives them an image representation, and then to visualize. With CairoMakie loaded, the latter draws a static figure. A notebook displays the final expression in a cell automatically, so the next plotting cell ends with that call. The colour bar tells us that the displayed values are appearance grades.
values = [0 0 0;
0 5 0;
0 0 0]3×3 Matrix{Int64}:
0 0 0
0 5 0
0 0 0image = OP.ImageNd(values)
OP.visualize(image; colorbar_label="appearance grade")
The horizontal axis is the matrix's column index; the vertical axis is its row index, increasing upward. Each tile represents one closed square, whose edges and vertices enter with it. Opposite sides of the array remain separate, so the resulting shape has an outside boundary. This is what nonperiodic means here.
Watch the hole appear and fill
At parameter $t$, include every square whose grade is at most $t$, together with its edges and vertices. As $t$ increases, the shape can gain squares without losing any. Such a growing family is a filtration; because we select values at or below $t$, this one is called a sublevel filtration. In symbols,
\[K_t = \bigcup_{\mathrm{values}[i,j]\leq t} \text{square}_{i,j}.\]
Here $K_t$ is the entire selected shape, including the boundaries of its squares. To draw it, values .<= t compares every array entry with t, and Int.(...) converts the resulting true/false entries into an image. The value 0 means an absent square and 1 means a present square. These masks display the squares chosen by this particular cubical construction.
Begin at $t=-1$. Every snapshot keeps the same coordinates and colorrange=(0, 1), so the colours retain their meaning even when the image is entirely empty or entirely full.
before = values .<= -1
@assert count(before) == 0
before_image = OP.ImageNd(Int.(before))
OP.visualize(before_image; colorrange=(0, 1),
colorbar_label="present (1) / absent (0)")
No square has appeared at −1. Before moving to the next snapshot, look back at the grades and predict which squares will be present at 0.
ring = values .<= 0
@assert count(ring) == 8 && !ring[2, 2]
ring_image = OP.ImageNd(Int.(ring))
OP.visualize(ring_image; colorrange=(0, 1),
colorbar_label="present (1) / absent (0)")
The boundary squares form one connected ring surrounding a hole. It stays this way for every parameter from 0 up to, but not including, 5.
filled = values .<= 5
@assert count(filled) == 9
filled_image = OP.ImageNd(Int.(filled))
OP.visualize(filled_image; colorrange=(0, 1),
colorbar_label="present (1) / absent (0)")
At 5 the center is present, and the hole has filled. The loop that went around it is still there as a curve along square edges, but now that loop is the boundary of a filled region. This change is what the homology calculation will record.
Compute and read the answer
Homology describes features of a shape using vector spaces. In degree zero, it records connected components. In degree one, we take linear combinations of loops and identify two combinations when their difference bounds a filled region. A vector in the resulting space is called a homology class. The ring has one independent class in degree one, represented by a loop around its hole; when the center fills, that loop bounds a region and its class becomes zero.
The coefficients in these combinations belong to a field. For this computation we use the default field $\mathbb{F}_2$, whose elements are 0 and 1 and whose addition is modulo 2. The call to cubical_persistence follows classes through the filtration, with square input (input=:top_cells), sublevels and nonperiodic boundaries stated explicitly. Its PersistenceDiagram stores the resulting intervals. This direct calculation of ordinary persistence does not construct a finite encoding (EncodingResult).
diagram = OP.cubical_persistence(values;
input=:top_cells, order=:sublevel, periodic=false)
holes = OP.finite_intervals(diagram; dim=1)
@assert holes == [(0, 5)]
@assert isempty(OP.essential_births(diagram; dim=1))
holes1-element Vector{Tuple{Int64, Int64}}:
(0, 5)The pair (0, 5) records the interval $[0,5)$: the class is present at its birth, 0, and absent at its death, 5. This agrees with our snapshots. The keyword dim=1 selects homological degree one, where this calculation records loop classes.
A barcode draws each interval along the parameter axis. We request it with kind=:barcode and keep dim=1 to look at the hole. In the figure, a filled circle includes the birth and an open circle excludes the death; the axis limits leave room around both endpoints.
OP.visualize(diagram; kind=:barcode, dim=1)
A persistence diagram draws the same interval as a point with coordinates (birth, death) = (0, 5). We can read both thresholds from that point, while its position tells us nothing about the geometric size of the hole. On the diagonal, birth and death would be equal, giving no nonzero interval in this filtration.
OP.visualize(diagram; kind=:persistence_diagram, dim=1)
The connected component appears at 0 too, but it remains after the hole fills. Since the array stops changing at 5, the final filled square stays connected at every later parameter. Its interval has no finite death and is called essential. We can see it by asking for degree zero.
components = OP.persistence_intervals(diagram; dim=0)
@assert OP.essential_births(diagram; dim=0) == [0]
@assert isempty(OP.finite_intervals(diagram; dim=0))
components1-element Vector{Tuple{Int64, Union{Float64, Int64}}}:
(0, Inf)OP.visualize(diagram; kind=:barcode, dim=0)
The mark at the right end of this barcode indicates continuation to $+\infty$. Although the drawing must end somewhere, that edge is not a death threshold. The hole's interval has a different endpoint: it ends at 5 because the center really does fill there.
Predict a change, then compare
Suppose the central square appears at 3 instead of 5. Before computing, write down the new interval for the hole and consider whether the connected component changes.
The next cell checks the prediction. We use copy to keep the original array available, so we can compare the two results afterward.
earlier_values = copy(values)
earlier_values[2, 2] = 3
earlier_diagram = OP.cubical_persistence(earlier_values;
input=:top_cells, order=:sublevel, periodic=false)
@assert values[2, 2] == 5
@assert OP.finite_intervals(earlier_diagram; dim=1) == [(0, 3)]
@assert isempty(OP.essential_births(earlier_diagram; dim=1))
@assert OP.essential_births(earlier_diagram; dim=0) == [0]
@assert isempty(OP.finite_intervals(earlier_diagram; dim=0))
(; original=holes, changed=OP.finite_intervals(earlier_diagram; dim=1))(original = [(0, 5)], changed = [(0, 3)])The hole still appears at 0, but now fills at 3, giving $[0,3)$. The connected component begins at 0 and remains essential. We can compare the original barcode with the changed one on the common parameter window −1 to 6; keeping the axis fixed lets us read the shorter lifetime directly.
This is where window=(-1, 6) becomes useful. We pass it to both plotting calls and use display for each, since this cell shows two figures.
display(OP.visualize(diagram; kind=:barcode, dim=1, window=(-1, 6)))
display(OP.visualize(earlier_diagram; kind=:barcode, dim=1, window=(-1, 6)));

Choose a threshold in the prepared viewer to place the selected squares beside their barcode. Compare the two versions at $t=3$: the original ring still has its hole, while the version whose center enters at 3 is already filled. The dashed arrow marks the selected threshold; the barcode shows the whole lifetime, so it stays in place as the shape changes.
The interpretation of the array is part of the mathematical example. With input=:top_cells, each entry grades a square, as in our pictures. Choosing input=:vertices would instead grade vertices and construct a different filtration from the same numbers. Identifying opposite boundaries through a periodic construction would change the space too.
Optional: Prepare a figure for sharing
If you want to use the barcode in a slide or report, you can adjust the text and canvas before saving it. VisualStyle sets the text size here, while size gives the canvas width and height in pixels. We keep the same dim and comparison window, so the mathematical view stays the same.
Preview the style once before exporting. It applies only to calls where we pass it and leaves other figures unchanged. You can skip this whole section and continue to the question about a second parameter below.
style = OP.VisualStyle(fontsize=18)
OP.visualize(diagram; kind=:barcode, dim=1, window=(-1, 6),
style=style, size=(760, 360))
The notebook retains the figures it displays. To save a separate PNG image, use save_visual with the same view, style and size. The files go in tamerop_outputs/ring under the current working directory, and export_path returns the saved file's location.
png = OP.save_visual(joinpath("tamerop_outputs", "ring"), "ring-barcode", diagram;
kind=:barcode, dim=1, window=(-1, 6),
style=style, size=(760, 360), format=:png)
@assert isfile(OP.export_path(png))
OP.export_path(png)"tamerop_outputs/ring/ring-barcode.png"Download the ring barcode as PNG
An SVG file stores the drawing as geometric instructions, allowing it to stay sharp when resized. Change only the format to save this version with the same mathematical view and styling.
svg = OP.save_visual(joinpath("tamerop_outputs", "ring"), "ring-barcode", diagram;
kind=:barcode, dim=1, window=(-1, 6),
style=style, size=(760, 360), format=:svg)
@assert isfile(OP.export_path(svg))
OP.export_path(svg)"tamerop_outputs/ring/ring-barcode.svg"Download the ring barcode as SVG
To share the prepared viewer, pair each threshold mask with its computed barcode. visual_panel selects the drawings, and compose_visuals keeps them in one figure. The arrow is an authored annotation marking the chosen threshold; it does not identify a particular geometric representative of the class. We keep the mask colours and barcode window fixed across every state.
The loop below prepares four thresholds for each center grade. The readable state names become the choices in the browser. save_visual_session stores these figures together in one HTML file, which you can open after closing Julia.
ring_views = Pair{Symbol,Any}[]
for (center_grade, sample_values, sample_diagram) in
((5, values, diagram), (3, earlier_values, earlier_diagram))
for threshold in (-1, 0, 3, 5)
mask = OP.ImageNd(Int.(sample_values .<= threshold))
active_holes = count(pair -> pair[1] <= threshold < pair[2],
OP.finite_intervals(sample_diagram; dim=1))
shape_panel = OP.visual_panel(mask;
colorrange=(0, 1), colorbar_label="present (1) / absent (0)",
title="Selected squares at t = $threshold")
barcode_panel = OP.visual_panel(sample_diagram;
kind=:barcode, dim=1, window=(-1, 6), title="The hole's interval")
threshold_note = OP.VisualAnnotation(
OP.VisualAnchor(:barcode; point=(threshold, 0.55)),
OP.VisualAnchor(:barcode; point=(threshold, 1.0));
label="Selected threshold t = $threshold")
selected_figure = OP.compose_visuals(
(shape=shape_panel, barcode=barcode_panel);
columns=1, annotations=(threshold_note,),
title="Center grade $center_grade; t = $threshold",
subtitle="The first homology space has dimension $active_holes")
name = Symbol("Center at $center_grade: t = $threshold")
push!(ring_views, name => selected_figure)
end
end
ring_viewer_path = joinpath("tamerop_outputs", "ring", "states.html")
OP.save_visual_session(ring_viewer_path, (; ring_views...);
selected=Symbol("Center at 5: t = 0"),
title="Follow the ring through its filtration",
caption="Each state pairs the included squares with the computed degree-one barcode over F₂. Choose a center grade and threshold to compare the two filtrations. The dashed arrow marks the threshold.",
style=OP.VisualStyle(fontsize=18), size=(760, 720))
@assert isfile(ring_viewer_path)
ring_viewer_path
"tamerop_outputs/ring/states.html"What changes with a second parameter?
Our interval records when the loop class exists and how it continues as the shape grows. Moving the center's appearance from 5 to 3 shortened that interval exactly as the geometry suggested. The barcode retains this continuation information, although it does not choose a unique geometric loop representing the class.
Suppose we now select squares using two measurements, each with its own threshold. Raising one threshold while lowering the other can add some squares and remove others, so the resulting shapes need not be nested. To follow classes through this family, we first need to work out which parameter pairs give inclusions, then retain the spaces and maps for those comparisons. A finite encoding lets us describe that information using finite data.
Continue with why two parameters change the problem to develop these comparisons. The ordinary persistence guide gives further details about the input and endpoint conventions of the computation we have just made.