Movatterモバイル変換

Title:	Calculate Persistent Homology with Ripser-Based Engines
Version:	1.0.0
Description:	Ports the Ripser <doi:10.48550/arXiv.1908.02518> and Cubical Ripser <doi:10.48550/arXiv.2005.12692> persistent homology calculation engines from C++. Can be used as a rapid calculation tool in topological data analysis pipelines.
License:	GPL-3
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.2
URL:	https://github.com/tdaverse/ripserr/
BugReports:	https://github.com/tdaverse/ripserr/issues
LinkingTo:	Rcpp
Depends:	R (≥ 3.5.0)
Imports:	Rcpp (≥ 1.0), stats (≥ 3.0), utils (≥ 3.0)
Suggests:	covr (≥ 3.5), knitr (≥ 1.29), rmarkdown (≥ 2.3), testthat(≥ 2.3), lmtest
VignetteBuilder:	knitr
NeedsCompilation:	yes
Packaged:	2025-06-27 18:58:43 UTC; jasoncorybrunson
Author:	Raoul R. Wadhwa [aut], Matt Piekenbrock [aut], Jason Cory Brunson [aut, cre], Xinyi Zhang [aut], Alice Zhang [aut], Kent Phipps [aut], Sean Hershkowitz [aut], Emily Noble [ctb], Aymeric Stamm [ctb], Aidan Bryant [ctb], James Golabek [ctb], Jacob G. Scott [ldr], Ulrich Bauer [cph, ctb] (Ripser; MIT license), Takeki Sudo [cph, ctb] (Cubical Ripser; GPL-3 license), Kazushi Ahara [cph, ctb] (Cubical Ripser; GPL-3 license)
Maintainer:	Jason Cory Brunson <cornelioid@gmail.com>
Repository:	CRAN
Date/Publication:	2025-06-27 19:10:02 UTC

Calculate Persistent Homology with Ripser-Based Engines

Description

Ports Ripser-based persistent homology calculation enginesfrom C++ to R using the Rcpp package.

Author(s)

Maintainer: Jason Cory Brunsoncornelioid@gmail.com (ORCID)

Authors:

• Raoul Wadhwaraoulwadhwa@gmail.com (ORCID)

• Matt Piekenbrockmatt.piekenbrock@gmail.com

• Xinyi Zhangezhang0927@gmail.com

• Alice Zhangaliscezhang@gmail.com (ORCID)

• Kent Phipps

• Sean HershkowitzSea7777.hers@gmail.com

Other contributors:

• Emily Noble [contributor]

• Aymeric Stammaymeric.stamm@cnrs.fr (ORCID) [contributor]

• Aidan Bryantbryant.aidan15@gmail.com [contributor]

• James Golabekjamesgolabek@gmail.com [contributor]

• Jacob Scott (ORCID) [laboratory director]

• Ulrich Bauer (Ripser; MIT license) [copyright holder, contributor]

• Takeki Sudo (Cubical Ripser; GPL-3 license) [copyright holder, contributor]

• Kazushi Ahara (Cubical Ripser; GPL-3 license) [copyright holder, contributor]

See Also

Useful links:

• https://github.com/tdaverse/ripserr/

• Report bugs athttps://github.com/tdaverse/ripserr/issues

Persistence Data Container

Description

PHom() creates instances ofPHom objects, which are convenient containersfor persistence data. Generally, data frame (or similar) objects are usedto createPHom instances with users specifying which columns containdimension, birth, and death details for each feature.

Usage

PHom(x, dim_col = 1, birth_col = 2, death_col = 3)

Arguments

Value

PHom instance

Examples

# construct data frame with valid persistence datadf <- data.frame(dimension = c(0, 0, 1, 1, 1, 2),                 birth = rnorm(6),                 death = rnorm(6, mean = 15))# create `PHom` instance and printdf_phom <- PHom(df)df_phom# print feature details to confirm accuracyprint.data.frame(df_phom)

Aedes aegypti occurrences in Brazil in 2013

Description

A geographic dataset of known occurrences ofAedes aegyptimosquitoes in Brazil, derived from peer-reviewed and unpublished literatureand reverse-geocoded to states.

Usage

aegypti

Format

Atibble of 4411 observations and 13 variables:

vector

species identification (aegypti versusalbopictus)

occurrence_id

unique occurrence identifier

source_type

published versus unpublished, with reference identifier

location_type

point or polygon location

polygon_admin

admin level or polygon size; -999 for point locations

y

latitudinal coordinate of point or polygon centroid

x

longitudinal coordinate of point or polygon centroid

status

established versus transient population

state_name

name of reverse-geolocated state

state_code

two-letter state code

Source

doi:10.5061/dryad.47v3c

Examples

# calculate persistence data for occurrences in Acreacre_coord <- aegypti[aegypti$state_code == "AC", c("x", "y"), drop = FALSE]acre_rips <- vietoris_rips(acre_coord)plot.new()xymax <- max(setdiff(acre_rips$death, Inf))plot.window(  xlim = c(0, xymax),  ylim = c(0, xymax),  asp = 1)axis(1L)axis(2L)abline(a = 0, b = 1)points(acre_rips[acre_rips$dim == 0L, c("birth", "death")], pch = 16L)points(acre_rips[acre_rips$dim == 1L, c("birth", "death")], pch = 17L)

Convert to PHom Object

Description

Converts valid objects toPHom instances.

Usage

as.PHom(x, dim_col = 1, birth_col = 2, death_col = 3)

Arguments

Value

PHom instance

Examples

# construct data frame with valid persistence datadf <- data.frame(dimension = c(0, 0, 1, 1, 1, 2),                 birth = rnorm(6),                 death = rnorm(6, mean = 15))# convert to `PHom` instance and printdf_phom <- as.PHom(df)df_phom# print feature details to confirm accuracyprint.data.frame(df_phom)

Images of black holes: Sagettarius A* and Pōwehi

Description

These data sets contain grayscale bitmaps of black holesSagettarius A* and Pōwehi (the unoffical name of Messier 87's black hole).sagAstar contains a 240x240 matrix with a spatial scale of approximately 1.3 millonkm per cell (calculated by dividing the length of the shadow by the number ofcells it covers in the image: 50 million km / 38).powehi contains a 250x250 matrix of Pōwehi with a spatial scale ofapproximately 800 million km per cell (calculated the same way as above:40 billion km / 50).

Format

A 240x240 and 250x250 matrix containing cells evaluated between 0 and 1.

Source

https://commons.wikimedia.org/wiki/File:Black_hole_-_Messier_87_crop_max_res.jpghttps://commons.wikimedia.org/wiki/File:EHT_Saggitarius_A_black_hole.tifhttps://mtsch.github.io/Ripserer.jl/v0.10/generated/sublevelset/

Image Processing Details

For both images we used the same proccess as follows.First, we obtained our images fromWikimedia Commons: Sagittarius A*Wikimedia Commons: Pōwehi.We then utilizemagick toconvert the images from RGB to grayscale using the default"perceptually-weighted" conversion. Next we acquired the raw 3D arrays,converted the data type to numerical, and dropped the singleton channeldimension. We then transposed the matrices and vertically flipped it to alignwith howgraphics reads matrices.

Examples

image(powehi,   col = hcl.colors(256, palette = "inferno", alpha = NULL, rev = FALSE,   fixup = TRUE), axes = FALSE, asp = 1)title(main = "Messier 87's Black Hole: Powehi")# based on the image, we expect one especially prominent # persistent feature in 1Dph <- cubical(powehi)plot.new()plot.window(  xlim = c(0, max(ph$death)),  ylim = c(0, max(ph$death)),  asp = 1)axis(1L)axis(2L)abline(a = 0, b = 1)points(ph[ph$dim == 1L, c("birth", "death")], pch = 17L, col = "orange")

State-level predictors of mosquito-borne illness in Brazil

Description

A data set of numbers of cases of Dengue in each state of Brazilin 2013 and three state-level variables used in a predictive model.

Usage

case_predictors

Format

A data frame of 27 observations and 4 variables:

POP

state population in 2013

TEMP

average temperature across state municipalities

PRECIP

average precipitation across state municipalities

CASE

number of state Dengue cases in 2013

Source

https://web.archive.org/web/20210209122713/https://www.gov.br/saude/pt-br/assuntos/boletins-epidemiologicos-1/por-assunto,http://www.ipeadata.gov.br/Default.aspx,https://ftp.ibge.gov.br/Estimativas_de_Populacao/,⁠https://www.ibge.Goiasv.br/geociencias/organizacao-do-territorio/estrutura-territorial/15761-areas-dos-municipios.html?edicao=30133&t=acesso-ao-produto⁠

Data pre-processing:After acquiring data from above links, we converted any datasetembedded in PDF format to CSV. Using carried functionalities in the CSVfile, we sorted all datasets alphabetically based on state names to makelater iterations more convenient. Also, we calculated the annual averagetemperature and added to the original dataset where it was documented byquarter.

Calculating Persistent Homology via a Cubical Complex

Description

This function is an R wrapper for the CubicalRipser C++ library to calculatepersistent homology. For more information on the C++ library, seehttps://github.com/CubicalRipser. For more information on how objects ofdifferent classes are evaluated bycubical, read the Details sectionbelow.

Usage

cubical(dataset, ...)## S3 method for class 'array'cubical(dataset, threshold = 9999, method = "lj", ...)## S3 method for class 'matrix'cubical(dataset, ...)

Arguments

Details

cubical.array assumesdataset is a lattice, with each element containingthe value of the lattice at the point represented by the indices of theelement in thearray.

cubical.matrix is redundant for versions ofR at or after 4.0. Forprevious versions ofR, in which objects with classmatrix do notnecessarily also have classarray,dataset is converted to anarrayand persistent homology is then calculated usingcubical.array.

Value

PHom object

Examples

# 2-dim exampledataset <- rnorm(10 ^ 2)dim(dataset) <- rep(10, 2)cubical_hom2 <- cubical(dataset)# 3-dim exampledataset <- rnorm(8 ^ 3)dim(dataset) <- rep(8, 3)cubical_hom3 <- cubical(dataset)# 4-dim exampledataset <- rnorm(5 ^ 4)dim(dataset) <- rep(5, 4)

First Part of PHom Object

Description

Returns the first part of aPHom instance.

Usage

## S3 method for class 'PHom'head(x, ...)

Arguments

Examples

# create sample persistence datadf <- data.frame(dimension = c(0, 0, 1, 1, 1, 2),                 birth = rnorm(6),                 death = rnorm(6, mean = 15))df_phom <- as.PHom(df)# look at first 3 featureshead(df_phom)# look at last 3 featurestail(df_phom)

Check PHom Object

Description

Tests if objects are validPHom instances.

Usage

is.PHom(x)

Arguments

Value

TRUE ifx is a validPHom object;FALSE otherwise

Examples

# create sample persistence datadf <- data.frame(dimension = c(0, 0, 1, 1, 1, 2),                 birth = rnorm(6),                 death = rnorm(6, mean = 15))df <- as.PHom(df)# confirm that persistence data is validis.PHom(df)# mess up df object (feature birth cannot be after death)df$birth[1] <- rnorm(1, mean = 50)# confirm that persistence data is NOT validis.PHom(df)

Printing Persistence Data

Description

Print a PHom object.

Usage

## S3 method for class 'PHom'print(x, ...)

Arguments

Examples

# create circle datasetangles <- runif(25, 0, 2 * pi)circle <- cbind(cos(angles), sin(angles))# calculate persistent homologycircle_phom <- vietoris_rips(circle)# print persistence dataprint(circle_phom)

Last Part of PHom Object

Description

Returns the last part of aPHom instance.

Usage

## S3 method for class 'PHom'tail(x, ...)

Arguments

Examples

# create sample persistence datadf <- data.frame(dimension = c(0, 0, 1, 1, 1, 2),                 birth = rnorm(6),                 death = rnorm(6, mean = 15))df_phom <- as.PHom(df)# look at first 3 featureshead(df_phom)# look at last 3 featurestail(df_phom)

Calculate Persistent Homology via a Vietoris-Rips Complex

Description

This function is an R wrapper for the Ripser C++ library tocalculate persistent homology. For more information on the C++ library, seehttps://github.com/Ripser/ripser. For more information on how objects ofdifferent classes are evaluated byvietoris_rips, read the Detailssection below.

Usage

vietoris_rips(dataset, ...)## S3 method for class 'data.frame'vietoris_rips(dataset, ...)## S3 method for class 'matrix'vietoris_rips(dataset, max_dim = 1L, threshold = -1, p = 2L, dim = NULL, ...)## S3 method for class 'dist'vietoris_rips(dataset, max_dim = 1L, threshold = -1, p = 2L, dim = NULL, ...)## S3 method for class 'numeric'vietoris_rips(  dataset,  data_dim = 2L,  dim_lag = 1L,  sample_lag = 1L,  method = "qa",  ...)## S3 method for class 'ts'vietoris_rips(dataset, ...)## Default S3 method:vietoris_rips(dataset, ...)

Arguments

Details

vietoris_rips.data.frame assumesdataset is a point cloud, with each rowrepresenting a point and each column representing a dimension.

vietoris_rips.matrix currently assumesdataset is a point cloud (similartovietoris_rips.data.frame). Currently in the process of adding networkrepresentation to this method.

vietoris_rips.dist takes adist object and calculates persistent homologybased on pairwise distances. Thedist object could have been calculatedfrom a point cloud, network, or any object containing elements from a finitemetric space.

vietoris_rips.numeric andvietoris_rips.ts both calculate persistenthomology of a time series object. The time series object is converted to amatrix using the quasi-attractor method detailed in Umeda (2017)doi:10.1527/tjsai.D-G72. Persistent homology of the resulting matrix isthen calculated.

Value

PHom object

Examples

# create a 2-d point cloud of a circle (100 points)num.pts <- 100rand.angle <- runif(num.pts, 0, 2*pi)pt.cloud <- cbind(cos(rand.angle), sin(rand.angle))# calculate persistent homology (num.pts by 3 numeric matrix)pers.hom <- vietoris_rips(pt.cloud)