-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathREADME.Rmd
More file actions
152 lines (117 loc) · 6.94 KB
/
Copy pathREADME.Rmd
File metadata and controls
152 lines (117 loc) · 6.94 KB
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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
---
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%"
)
```
# inphr
<!-- badges: start -->
[](https://app.codecov.io/gh/tdaverse/inphr)
[](https://github.com/tdaverse/inphr/actions/workflows/R-CMD-check.yaml)
[](https://CRAN.R-project.org/package=inphr)
<!-- badges: end -->
The goal of [{inphr}](https://tdaverse.github.io/inphr/) is to provide a set of
functions for performing null hypothesis testing on samples of persistence
diagrams using the theory of permutations. Currently, only two-sample testing is
implemented. Inputs can be either samples of persistence diagrams themselves or
vectorizations. In the former case, they are embedded in a metric space using
either the Bottleneck or Wasserstein distance. In the former case, persistence
data becomes functional data and inference is performed using tools available in
the [{fdatest}](https://permaverse.github.io/fdatest/) package.
## Installation
You can install the development version of inphr from
[GitHub](https://github.com/) with:
``` r
# install.packages("pak")
pak::pak("tdaverse/inphr")
```
## Usage
Let us start by loading the package:
```{r}
library(inphr)
```
### Toy data
The package contains three toy data sets of persistence diagrams, which can be used for
testing. They are available in the package as `trefoils1`, `trefoils2`, and
`archspirals`. The first two sets contain persistence diagrams computed from
noisy samples of trefoil knots, while the third set contains persistence
diagrams computed from noisy samples of 2-armed Archimedean spirals. Each set
contains 24 persistence diagrams, each computed from a sample of 120 points
sampled from the respective shape, with Gaussian noise added (standard deviation
= 0.05). The persistence diagrams were computed using the
[`TDA::ripsDiag()`](https://www.rdocumentation.org/packages/TDA/versions/1.9.1/topics/ripsDiag)
function with a maximum scale of 6 and up to dimension 2.
### Test in the space of diagrams
You can use the
[`two_sample_diagram_test()`](https://tdaverse.github.io/inphr/reference/two_sample_diagram_test.html)
function to perform a two-sample test on these persistence diagrams in the space of diagrams themselves. For
example, to test whether the persistence diagrams from `trefoils1` are
significantly different from the persistence diagrams from `trefoils2`, you can run:
```{r}
two_sample_diagram_test(trefoils1, trefoils2, B = 100L)
```
To test whether the persistence diagrams from `trefoils1` are
significantly different from the persistence diagrams from `archspirals`, you can run:
```{r}
two_sample_diagram_test(trefoils1, archspirals, B = 100L)
```
Optionnally, the `two_sample_diagram_test()` function can also output the distribution of the test statistic under the null hypothesis as estimated by the permutation scheme. To do that, you can use the optional argument `keep_null_distribution = TRUE`. It is also possible to ask for the permutations themselves to be saved as part of the output. To do that, you can use the optional argument `keep_permutations = TRUE`.
Test in the space of diagrams themselves is performed using test statistics that only rely on distances between sampled diagrams. By default, two such statistics that mimic Student's t-statistic and Fisher's F-statistic are used as proposed in Lovato, I., Pini, A., Stamm, A., & Vantini, S. (2020), *Model-free two-sample test for network-valued data*. Computational Statistics & Data Analysis, **144**, 106896.
### Test in functional spaces
You can use the [`two_sample_functional_test()`](https://tdaverse.github.io/inphr/reference/two_sample_functional_test.html) function to perform a two-sample test on these persistence diagrams in functional spaces using one of five functional representations of persistence diagrams, namely: (i) Betti, (ii) Euler characteristic, (iii) normalized life, (iv) silhouette and (v) entropy curves. Computation of these functional representations is powered by the [{TDAvec}](https://cran.r-project.org/package=TDAvec) package. For
example, to test whether the persistence diagrams from `trefoils1` are
significantly different from the persistence diagrams from `archspirals`, you can use the Betti curve representation and run:
```{r, eval = FALSE}
out <- two_sample_functional_test(
trefoils1,
archspirals,
representation = "betti",
B = 100L
)
```
```{r, include = FALSE}
out <- two_sample_functional_test(
trefoils1,
archspirals,
representation = "betti",
B = 100L
)
```
The output is a length-4 list. The first two elements are `xfd` and `yfd` which are numeric matrices storing evaluations of the functional representation of the diagrams on a grid stored as the third element `scale_seq`. You can therefore have a look at the functional data that the function produced using something like:
```{r}
matplot(
out$scale_seq[-1],
t(rbind(out$xfd, out$yfd)),
type = "l",
col = c(rep(1, length(trefoils1)), rep(2, length(archspirals)))
)
```
In the case of testing in functional spaces, {inphr} uses the interval-wise testing (IWT) procedure powered by the [{fdatest}](https://cran.r-project.org/package=fdatest) package which has been proposed in Pini, A., & Vantini, S. (2017), *Interval-wise testing for functional data*. Journal of Nonparametric Statistics, **29**(2), 407-424.
The output indicates on which portions of the scale sequence does the difference between the two samples occur, providing strong control of the familywise error rate:
```{r}
plot(out$iwt, xrange = range(out$scale_seq))
```
## Contributions
### Code of Conduct
Contributions are welcome! Please feel free to open an issue or a pull request
if you have any suggestions or improvements. The package is still in its early
stages, so any feedback is appreciated.
Please note that the {inphr} project is released with a [Contributor Code of
Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By
contributing to this project, you agree to abide by its terms.
### Acknowledgements
This project 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)
and done in coordination with Jason Cory Brunson and with guidance from Bertrand
Michel and Paul Rosen. It builds upon conversations with Mathieu Carrière and
Vincent Rouvreau who are among the authors of the
[GUDHI](https://gudhi.inria.fr) library. Package development also benefited
from the support of colleagues at the [Department of Mathematics Jean
Leray](https://www.math.sciences.univ-nantes.fr) and the use of equipment at
[Nantes University](https://english.univ-nantes.fr).