↓ Skip to main content
HomCloud

NAME
#

abstract_filtration - Compute a persistence diagram from an explicit description of a filtered boundary map

SYNOPSIS
#

homcloud-abstract-filtration
    [-h] [-V] [-M SAVE_BOUNDARY_MAP] [--license]
    input output

This program can also be invoked as python3 -m homcloud.cli.abstract_filtration.

ALIAS
#

homcloud-abstract-filtration

DESCRIPTION
#

This program reads a text description of a filtered cell complex — each cell’s dimension, filtration time, and explicit boundary — and computes a persistence diagram, written as a .pdgm file (abstract filtration type). This is the most general/low-level way to feed a filtration into HomCloud when your data does not fit the point-cloud (homcloud-pc-alpha, homcloud-rips) or picture (homcloud-pict-binarize-nd, …) tools.

OPTIONS
#

-h, --help            show this help message and exit
-V, --version         show program's version number and exit
-M SAVE_BOUNDARY_MAP, --save-boundary-map SAVE_BOUNDARY_MAP
                      save boundary map (yes/no, *default:yes*)
--license             show license and exit

Unlike most other homcloud-* commands, -M/--save-boundary-map defaults to on here, so the output is ready for homcloud-optvol unless you explicitly pass -M off.

INPUT FILE FORMAT
#

The input is a plain-text file, one cell per non-blank, non-comment, non-option line, in filtration order (cell ids are assigned 0, 1, 2, … in the order they appear). A line starting with # is a comment and is ignored.

Each cell line has the form:

id dim time = indices : coefficients
  • id — the cell’s index; must equal its 0-based position among cell lines (i.e. cells must be listed in id order starting at 0).
  • dim — the dimension of the cell (0 for a vertex, 1 for an edge, …).
  • time — the filtration (birth) time of the cell; times must be non-decreasing from one line to the next.
  • indices — a whitespace-separated list of the ids of the cells that make up this cell’s boundary.
  • coefficients — a whitespace-separated list, the same length as indices, of the (mod 2) boundary coefficients for each of those cells. A coefficient is treated as 1 (included in the boundary) if it is odd, 0 (excluded) if it is even.

The overall filtration dimension is the maximum dim over all cells.

Two option lines may appear before any cell line:

autoid: yes|no
autosymbol: yes|no

  • autoid (default no): when yes, the id field is omitted from every cell line (ids are assigned automatically in order):

    dim time = indices : coefficients

  • autosymbol (default yes): when no, every cell line must additionally give an explicit symbol (name), right after id (or first, if autoid is also yes):

    id symbol dim time = indices : coefficients

    A symbol must match [a-zA-Z0-9_]+. When autosymbol is yes (the default), each cell’s symbol is just its id as a string.

Example (3 vertices and 2 edges forming a path, default autoid:no, autosymbol:yes):

# vertices
0 0 0.0 = :
1 0 0.0 = :
2 0 0.0 = :
# edges
3 1 1.0 = 0 1 : 1 1
4 1 1.0 = 1 2 : 1 1

OUTPUT FORMAT
#

output is always a .pdgm file (abstract filtration type).