NAME

#

rips - Compute a persistence diagram from a Vietoris-Rips filtration of a distance matrix

SYNOPSIS

#

homcloud-rips
    [-h] [-V] -d UPPER_DEGREE [-u UPPER_VALUE]
    [--vertex-symbols VERTEX_SYMBOLS] [-M SAVE_BOUNDARY_MAP]
    [--algorithm ALGORITHM] [--parallels PARALLELS] [--license]
    input output

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

ALIAS

#

homcloud-rips

DESCRIPTION

#

This program computes a persistence diagram from the Vietoris-Rips filtration of a full distance matrix, and writes it as a .pdgm file.

-M off (the default) uses ripser internally, which is fast but does not record the boundary map (so the output cannot be used with homcloud-optvol). -M on instead builds the simplicial complex explicitly and reduces its boundary matrix with PHAT, which is slower and uses much more memory for the same UPPER_DEGREE/UPPER_VALUE, but the output can then be used with homcloud-optvol.

OPTIONS

#

-h, --help            show this help message and exit
-V, --version         show program's version number and exit
-d UPPER_DEGREE, --upper-degree UPPER_DEGREE
                      Maximum computed degree
-u UPPER_VALUE, --upper-value UPPER_VALUE
                      Maximum distance (default: +inf)
--vertex-symbols VERTEX_SYMBOLS
                      vertex symbols file
-M SAVE_BOUNDARY_MAP, --save-boundary-map SAVE_BOUNDARY_MAP
                      save boundary map into output file(only available
                      with phat-* algorithms, on/*off*)
--algorithm ALGORITHM
                      algorithm (ripser)
--parallels PARALLELS
                      number of threads (default: 1)
--license             show license and exit

--algorithm only accepts ripser (or is left unset) when -M is off. When -M on is given, --algorithm instead selects the PHAT reduction algorithm (e.g. phat-twist, phat-chunk-parallel), the same as for homcloud-pc-alpha.

INPUT FILE FORMAT

#

input is a plain-text n×n distance matrix (loaded with numpy.loadtxt), i.e. n whitespace-separated rows of n numbers, where entry (i, j) is the distance between point i and point j. The matrix should be symmetric with a zero diagonal.

--vertex-symbols optionally names a text file with one symbol (name) per line, one line per point, in the same order as the distance matrix rows; these symbols are used for -s yes output of homcloud-dump-diagram and in optimal-volume output.

OUTPUT FORMAT

#

output is always a .pdgm file (rips filtration type when -M is off, simplicial filtration type when -M is on).

NOTES

#

--parallels is accepted by the argument parser but is currently not actually used by the implementation (it is not passed through to the underlying computation); it has no effect regardless of the value given.