ripserr/README.Rmd at main · tdaverse/ripserr · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# ripserr: Calculate Persistent Homology of Vietoris-Rips and Cubical Complexes using Ripser in R

[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![CRAN version](http://www.r-pkg.org/badges/version/ripserr)](https://CRAN.R-project.org/package=ripserr)
[![CRAN Downloads](http://cranlogs.r-pkg.org/badges/grand-total/ripserr)](https://CRAN.R-project.org/package=ripserr)

## Overview

ripserr ports the [Ripser](https://arxiv.org/abs/1908.02518) and [Cubical Ripser](https://arxiv.org/abs/2005.12692) persistent homology calculation engines from C++ via [Rcpp](https://CRAN.R-project.org/package=Rcpp).
It can be used as a convenient and rapid calculation tool in topological data analysis pipelines.

## Installation

```{r install, eval=FALSE}
# install development version
devtools::install_github("tdaverse/ripserr")

# install from CRAN
install.packages("ripserr")
```

## Sample code

Ripser (Vietoris-Rips filtration) can be used as follows for data with dimension greater than or equal to 2.

```{r sample-vr}
# load ripserr
library("ripserr")

set.seed(42)
SIZE <- 100

# 2-dimensional example
dataset2 <- rnorm(SIZE * 2)
dim(dataset2) <- c(SIZE, 2)
vr_phom2 <- vietoris_rips(dataset2)
head(vr_phom2)
tail(vr_phom2)

# 3-dimensional example
dataset3 <- rnorm(SIZE * 3)
dim(dataset3) <- c(SIZE, 3)
vr_phom3 <- vietoris_rips(dataset3, max_dim = 2) # default: max_dim = 1
head(vr_phom3)
tail(vr_phom3)
```

Cubical Ripser (cubical filtration) can be used as follows for data with dimension equal to 2, 3, or 4.

```{r sample-cub}
# load ripserr
library("ripserr")

set.seed(42)
SIZE <- 10

# 2-dimensional example
dataset2 <- rnorm(SIZE ^ 2)
dim(dataset2) <- rep(SIZE, 2)
cub_phom2 <- cubical(dataset2)
head(cub_phom2)
tail(cub_phom2)

# 3-dimensional example
dataset3 <- rnorm(SIZE ^ 3)
dim(dataset3) <- rep(SIZE, 3)
cub_phom3 <- cubical(dataset3)
head(cub_phom3)
tail(cub_phom3)

# 4-dimensional example
dataset4 <- rnorm(SIZE ^ 4)
dim(dataset4) <- rep(SIZE, 4)
cub_phom4 <- cubical(dataset4)
head(cub_phom4)
tail(cub_phom4)
```

## Functionality

1. Calculation of persistent homology of Vietoris-Rips filtrations using Ripser (function named `vietoris_rips`).
1. Calculation of persistent homology of cubical filtrations using Cubical Ripser (function named `cubical`).

## Citation

If you use the ripserr package in your work, please consider citing the following (based on use):

* **General use of ripserr:** Wadhwa RR, Piekenbrock M, Brunson JC, Zhang X, Zhang A, Phipps K, Hershkowitz S (2025). ripserr: Calculate Persistent Homology with Ripser-Based Engines. R package version 1.0.0, <https://github.com/tdaverse/ripserr/>.
* **Calculation using Vietoris-Rips filtrations:** Bauer U (2021). Ripser: Efficient computation of Vietoris-Rips persistence barcodes. arXiv: 1908.02518.
* **Calculation using cubical filtrations:** Kaji S, Sudo T, Ahara K. Cubical (2020). Ripser: Software for computing persistent homology of image and volume data. arXiv: 2005.12692.

## Contribute

To contribute to ripserr, you can create issues for any bugs/suggestions on the [issues page](https://github.com/tdaverse/ripserr/issues).
You can also fork the ripserr repository and create pull requests to add useful features.

## Acknowledgments

The upgrade to Ripser version 1.2.1 (ripserr version 1.0.0) was funded by [an ISC grant from the R
Consortium](https://r-consortium.org/all-projects/2024-group-1.html#modular-interoperable-and-extensible-topological-data-analysis-in-r).
It was done based on preliminary work by and in collaboration with Sean Hershkowitz, Alice Zhang, and Kent Phipps, in coordination with Aymeric Stamm and with guidance from
Bertrand Michel and Paul Rosen.