Input Data

RIVET accepts as input a text file that describes a data set, called a raw data file in the previous section. A raw data file must have one of the following formats listed below.

Note that RIVET ignores blank lines and lines that begin with a # symbol. In particular, lines beginning with a # symbol may be used for human-readable comments rather than machine-readable data. All lines specifying labels may contain spaces, though leading and trailing white space is trimmed.

I. Point Cloud

The point cloud format specifies the coordinates of a set of points in Euclidean $n$-space, as well as the value of a function $f$ on each point.

Given a point cloud input file, RIVET builds a Vietoris-Rips complex whose vertices are the specified points, with edges constructed between any two points such that the distance between the points is not greater than some specified distance $d$. The Vietoris-Rips complex is endowed with a bifiltration by assigning a bigrade to each simplex $\Delta$ as follows: if $\Delta$ is a 0-simplex, then its bigrade is $(f(\Delta), 0)$; otherwise, the bigrade of $\Delta$ is $(x, y)$, where $x$ is the minimum value of $f$ over all vertices of $\Delta$ and $y$ is the minimum length of all edges of $\Delta$.

A file in the point cloud format must be written as follows:

  1. The first (non-empty, uncommented) line contains the word “points” and no other characters.
  2. The second line specifies the dimension $n$ of Euclidean space in which the point cloud is embedded.
  3. The third line specifies the maximum distance $d$ of edges constructed in the Vietoris-Rips complex. This may be an integer or decimal number.
  4. The fourth line gives the label for the axis along which the values of $f$ appear.
  5. The remaining lines of the file specify the points, one point per line. Each line must specify the coordinates of a point ($n$ decimal numbers specified by white space), followed by the value of $f$ on the point.

A sample point cloud file appears below.

points
2
3.2
birth time
0 0 3
1.1 2 0.5
-2 3 4

II. Finite Metric Space

This input specifies a finite metric space $P$, together with a real-valued function $f:P\to \mathbb R$. Given such input, RIVET constructs the Vietoris-Rips complex with scale parameter some specified distance $d$, i.e., the clique complex on the $d$-neighborhood graph of the metric space. This Vietoris-Rips complex is endowed with a bifiltration by assigning a bigrade to each simplex $\Delta$ as follows: if $\Delta$ is a 0-simplex, then its bigrade is $(f(\Delta), 0)$; otherwise, the bigrade of $\Delta$ is $(x, y)$, where $x$ is the maximum value of $f$ over all vertices of $\Delta$ and $y$ is the maximum length of all edges of $\Delta$.

(Note that this construction also makes sense even if the given distances do not satisfy the triangle inequality, and RIVET handles such input as well.)

A file in the discrete metric space format must be written as follows:

  1. The first (non-empty, uncommented) line contains the word the word “metric” and no other printed characters.
  2. The second line gives the label for the axis along which the values of $f$ appear.
  3. The third line gives the values of $f$ on each of the $n$ points. This line consists of $n$ decimal numbers, separated by white space.
  4. The fourth line gives the label for the “distance” axis, allowing the user to specify the metric used.
  5. The fifth line specifies the maximum distance $d$ of edges constructed in the Vietoris-Rips complex. This must be a positive number (integer or decimal).
  6. The remaining line(s) of the file specify the distances between pairs of points. These distances appear as $\frac{n(n-1)}{2}$ numbers (integer or decimal), separated by white space or line breaks. Let the points be denoted $p_1, p_2, \ldots, p_n$. The first $n-1$ numbers give the distances from $p_1$ to $p_2, \ldots, p_n$. The next $n-2$ numbers give the distances from $p_2$ to $p_3, \ldots, p_n$, and so on. The last number gives the distance from $p_{n-1}$ to $p_n$.

A sample distance matrix file appears below.

metric
birth time
1 1.1 -2
geodesic distance
2.5
2 3.2
1.25

III. Bifiltration

The bifiltration format allows RIVET to input an abstract bifiltration. Currently, RIVET only supports bifiltrations where each simplex has a unique bigrade of appearance in $\mathbb{R}^2$, i.e., 1-critical bifiltrations.

Let $v_1, v_2, \ldots, v_n$ denote the vertices (0-simplices) of the bifiltration. Specifying the bifiltration requires specifying each simplex (given as a subset of $v_1, v_2, \ldots, v_n$) and its birth index. Simplices are specified, one simplex per line, in the bifiltration input file.

However, if a face $\alpha$ of a simplex $\Delta$ in the bifiltration has the same bigrade of appearance as $\sigma$, it is not necessary to specify $\alpha$ explicitly in the input file; if when processing line specifying $\Delta$, $\alpha$ has not already been specified on an earlier line, RIVET automatically assigns $\alpha$ the same bigrade as $\Delta$.

We require that if $\alpha$ is specified explicitly in the input file, then $\alpha$ is specified before $\Delta$.

The user must ensure that the input file specifies a valid bifiltration, in the sense that if $\alpha$ is born at $(x_\alpha, y_\alpha)$ and $\Delta$ is born at $(x_\Delta, y_\Delta)$, then $x_\alpha \le x_\Delta$ and $y_\alpha \le y_\Delta$.

A file in the bifiltration format must have the following format:

  1. The first (non-empty, uncommented) line contains the word “bifiltration” and no other printed characters.
  2. The second line gives a label for the first filtration parameter.
  3. The third line gives alabel for the second filtration parameter.
  4. The remaining lines of the file specify simplices. To specify an $j$-simplex, $j+3$ numbers are required (separated by white space). The first $j+1$ numbers, which must be non-negative integers, give the vertices of the simplex. The remaining two numbers (which may be integers or decimals) give the bigrade at which the simplex appears.

A sample bifiltration file appears below. This consists of: the boundary of a triangle born at $(0,0)$; the interior of the triangle born at $(0,1)$; two edges that complete the boundary of a second triangle adjacent to the first, born at $(1,0)$.

bifiltration
time of appearance
network distance
0 1 0 0
0 2 0 0
1 2 0 0
0 1 2 0 1
1 3 1 0
2 3 1 0

IV. Algebraic Input

As explained in the RIVET paper, RIVET works with modules represented implicitly as the homology of a short chain chain complex of free 2-D persistence modules \[C_2\xrightarrow{f}C_1\xrightarrow{g}C_0.\] Taking $C_0=0$, this includes the special case of a presentation.

Roy Zhao’s fork of RIVET (not yet merged and still being debugged) allows us to input such algebraic input directly into RIVET.

  1. The first (non-empty, uncommented) line says “firep”
  2. The second line is the x-label.
  3. The third line is the y-label.
  4. The fourth line is of the form “t s r”, where t, s, and r are, repsectively, the number of generators in a bases for $C_2$, $C_1$, and $C_0$.
  5. Each of the next t lines specifies the bigrade of appearance of a basis element for $C_2$, together with the corresponding column of the matrix representing f: the format for such a line is: “x y ; b1 b2 b3”, where the bi are the row indices of nonzero column entries. (Recall that we work with $\mathbb{Z}/2\mathbb{Z}$ coefficients.)
  6. Each of the next s lines specifies the bigrade of appearance of a basis element for $C_1$, together with the corresponding column of the matrix representing $g$.

An example algebraic input is shown below

firep
parameter 1
parameter 2
2 3 3
1 0 ; 1 1 1
0 1 ; 1 1 1
0 0 ; 1 2
0 0 ; 0 2
0 0 ; 0 1

V. Multicritical Input (Provisional Section)

Recently, Roy has also implemented multicritical functionality in a fork of RIVET, including the ability to handle the BRips bifiltration construction described in the RIVET paper.

This documentation has not yet been updated to account for the multicritical extension. In the meantime, we specify by example the new input conventions for building the BRips bifiltrations:

For building a BRips bifiltration from a point set in euclidean space, the format is this:

points
2
3.2
no function
0 0
1.1 2
-2 3

Given the input specification for the 1-critical “points” format, this variant should be self-explanatory.

For building a BRips bifiltration from a distance matrix, the format is:

metric
no function
3
ylabel
2.5
2 3.2
1.25

(ylabel can be anything the user likes, for example “Rips scale.”) As above, this format is mostly self-explanatory. However, the 3 appearing on the third line requires some explanation. This is the number of points in the finite metric space. (This input convention is redundant: the of the third line value is always one greater than the number of entries on sixth line. The reason for this choice of input convention was that including the including the number of points explicitly made it much simpler to adapt the parser.)

We note that Roy’s code still also handles the old 1-critical points and metric format.

Roy’s fork also supports arbitrary multi-critical bifiltrations. The new format for this separates the indices of vertices in a simple from the list of grades of appearance by a semicolon, so e.g., in the new format the bifiltration input above is given as follows:

bifiltration
time of appearance
network distance
0 1 ; 0 0
0 2 ; 0 0
1 2 ; 0 0
0 1 2 ; 0 1
1 3 ; 1 0
2 3 ; 1 0

(Note that this is NOT backwards compatible with the format described above. Note also that at this time, RIVET IS sensitive to the spacing around the semicolon.) If the simplex [0 1] appeared at both (0,0) and (-1,1), the fourth line of the above input file would instead read either:

0 1; 0 0 -1 1

or

0 1; -1 1 0 0

Thus, the minimal grades of appearance of a given simplex may be given in arbitrary order. Moreover, the code can handle non-minimial bigrades of appearance; it simply removes them. (However, in the current code, non-minimal bigrades of appearance may change the coarsening behavior, as the x- and y-grades of such bigrades are not currently ignored when performing coarsening.)