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.

For any line specifying a label, putting the characters [-] at the beginning of the line before the label tells RIVET to interpret the corresponding filtration direction to be descending rather than ascending, if this makes sense.

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. Point Cloud / Finite Metric Space without function (Degree-Rips Construction)

Given either a point cloud in Euclidean space or a finite metric space, RIVET can construct a version of the Vietoris-Rips bifiltration without the additional information of a function on points as input. We call this construction the degree-Rips bifiltration; it is denoted BRips in the RIVET paper. Degree-Rips bifiltrations are multi-critical, except in very degenerate examples.

We specify by example the input format for the Degree-Rips bifiltration on a point cloud:

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.

The input format for the Degree-Rips bifiltration on a finite metric space is shown in the following example:

metric
no function
3
Rips scale
2.5
2 3.2
1.25

As above, this format is mostly self-explanatory. However, the 3 appearing on the third line requires 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.)

IV. Bifiltration

The bifiltration format allows RIVET to input an arbitrary bifiltration. RIVET now supports multicritical bifiltrations, i.e., ones where each simplex has multiple incomparable bigrades of appearance in $\mathbb{R}^2$.

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 indices. Simplices are specified, one simplex per line, in the bifiltration input file.

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 each specify a simplex and its bigrades of appearance. A line specifying a $j$-simplex with $n$ grades of appearance, must have $j+1$ non-negative integers (separated by white space), followed by a semicolon, followed by $2n$ numbers (which may be integers or decimals. The semicolon must be surrounded by spaces. The first $j+1$ integers give the vertices of the simplex. The remaining numbers specify the bigrades at which the simplex appears.

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

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

It is also valid to take the seventh of the above input file to be

0 1 2 ; 1 0 0 1

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 currently not ignored when performing coarsening.)

V. 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.

RIVET 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 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