Skip to content

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  0
image = OP.ImageNd(values)
OP.visualize(image; colorbar_label="appearance grade")
Nine squares: the central square has appearance grade five; the eight surrounding squares have grade zero.

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)")
At parameter minus one all nine squares are absent. The complex is empty.

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)")
At parameter zero the eight boundary squares are present and the central square is absent, leaving one hole.

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 parameter five all nine squares are present. The center fills the hole, while the shape remains connected.

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))
holes
1-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)
Degree-one barcode: one interval starts at zero with an included endpoint and ends at five with an excluded endpoint.

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)
Degree-one persistence diagram: the point at birth zero and death five lies above the birth-equals-death diagonal.

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))
components
1-element Vector{Tuple{Int64, Union{Float64, Int64}}}:
 (0, Inf)
OP.visualize(diagram; kind=:barcode, dim=0)
Degree-zero barcode: one component is born at zero and continues to positive infinity. The edge of the drawing is not a death event.

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)));
Original degree-one barcode: the hole lives from zero to five.Changed degree-one barcode on the same scale: the hole lives from zero to three.

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 original degree-one interval from zero to five, prepared for sharing with larger text and the same comparison window.

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.