Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/egarpor/sphunif

Implementation of uniformity tests on the circle and (hyper)sphere, with a C++ core. The package allows the replication of the data application in "On a projection-based class of uniformity tests on the hypersphere"
https://github.com/egarpor/sphunif

circular-statistics directional-statistics r uniformity uniformity-tests

Last synced: 2 months ago
JSON representation

Implementation of uniformity tests on the circle and (hyper)sphere, with a C++ core. The package allows the replication of the data application in "On a projection-based class of uniformity tests on the hypersphere"

Awesome Lists containing this project

README 

        
---

output:

  md_document:

    variant: gfm

---



```{r, setup, echo = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE, comment = "#>", fig.path = "README/README-",

  message = FALSE, warning = FALSE, fig.asp = 1, fig.align = 'center'

)

```



sphunif

=======



```{r, badges, echo = FALSE, results = 'asis'}

cat(

  badger::badge_license(license = "GPLv3", color = "blue",

                        url = "https://www.gnu.org/licenses/gpl-3.0"),

  badger::badge_github_actions(action = "R-CMD-check"),

  badger::badge_github_actions(action = "test-coverage"),

  badger::badge_codecov(),

  badger::badge_cran_release(color = "green"),

  badger::badge_cran_download(pkg = NULL, type = "grand-total"),

  badger::badge_cran_download(pkg = NULL, type = "last-month")

)

```



## Overview



Implementation of more than 35 tests of uniformity on the circle, sphere, and hypersphere. Software companion for the (evolving) review *An overview of uniformity tests on the hypersphere* (García-Portugués and Verdebout, 2018) and the paper *On a projection-based class of uniformity tests on the hypersphere* (García-Portugués, Navarro-Esteban and Cuesta-Albertos, 2023).



## Installation



Get the latest version from GitHub:



```{r, install-devtools, eval = FALSE}

# Install the package and the vignettes

library(devtools)

install_github("egarpor/sphunif", build_vignettes = TRUE)



# Load package

library(sphunif)



# See main vignette

vignette("sphunif")

```



```{r, load, echo = FALSE}

# Load package

library(sphunif)

```



## Usage



### Circular data



You want to test if a sample of *circular* data is uniformly distributed. For example, the following circular uniform sample in *radians*:



```{r, cir_data}

set.seed(987202226)

cir_data <- runif(n = 10, min = 0, max = 2 * pi)

```



Call the main function in the `sphunif` package, `unif_test`, specifying the `type` of test to be performed. For example, the `"Watson"` test:



```{r, unif_test_cir}

library(sphunif)

unif_test(data = cir_data, type = "Watson") # An htest object

```



By default, the calibration of the test statistic is done by Monte Carlo. This can be changed with `p_value = "asymp"` to employ asymptotic distributions (faster, but not available for all tests):



```{r, asymp}

unif_test(data = cir_data, type = "Watson", p_value = "MC") # Monte Carlo

unif_test(data = cir_data, type = "Watson", p_value = "asymp") # Asymp. distr.

```



You can perform *several* tests with a *single* call to `unif_test`. Choose the available circular uniformity tests from



```{r, avail_cir}

avail_cir_tests

```



For example:



```{r, unif_test_avail_cir}

# A *list* of htest objects

unif_test(data = cir_data, type = c("Watson", "PAD", "Ajne"))

```



### Spherical data



You want to test if a sample of *spherical* data is uniformly distributed. Consider a *non*-uniformly-generated sample of directions in **Cartesian coordinates**:



```{r, sph_data}

# Sample data on S^2

set.seed(987202226)

theta <- runif(n = 50, min = 0, max = 2 * pi)

phi <- runif(n = 50, min = 0, max = pi)

sph_data <- cbind(cos(theta) * sin(phi), sin(theta) * sin(phi), cos(phi))

```



The available spherical uniformity tests:



```{r, avail_sph}

avail_sph_tests

```



The default `type = "all"` equals `type = avail_sph_tests`:



```{r, unif_test_avail_sph}

head(unif_test(data = sph_data, type = "all", p_value = "MC"))

unif_test(data = sph_data, type = "Rayleigh", p_value = "asymp")

```



### Higher dimensions



The *hyperspherical* setting is treated analogously to the spherical setting, and the available tests are exactly the same (`avail_sph_tests`). An example of testing uniformity with a sample of size `100` on the $9$-sphere:



```{r, hyp_data}

# Sample data on S^9

set.seed(987202226)

hyp_data <- r_unif_sph(n = 50, p = 10)



# Test

unif_test(data = hyp_data, type = "Rayleigh", p_value = "asymp")

```



## Replicability



### *On a projection-based class of uniformity tests on the hypersphere*



The data application in García-Portugués, Navarro-Esteban, and Cuesta-Albertos (2023) regarding the testing of uniformity of locations for craters in Rhea can be reproduced through the script [data-application-ecdf.R](https://github.com/egarpor/sphunif/blob/master/applications/data-application-ecdf.R). The code snippet below is a simplified version.



```{r, rhea}

# Load data

data(rhea)



# Add Cartesian coordinates

rhea$X <- cbind(cos(rhea$theta) * cos(rhea$phi),

                sin(rhea$theta) * cos(rhea$phi),

                sin(rhea$phi))



# Distribution of diameter

quantile(rhea$diameter)



# Subsets of craters, according to diameter

ind_15_20 <- rhea$diameter > 15 & rhea$diameter < 20

ind_20 <- rhea$diameter > 20



# Sample sizes

nrow(rhea)

sum(ind_15_20)

sum(ind_20)



# Tests to be performed

type_tests <- c("PCvM", "PAD", "PRt")



# Tests

tests_rhea_15_20 <- unif_test(data = rhea$X[ind_15_20, ], type = type_tests,

                              p_value = "asymp", K_max = 5e4)

tests_rhea_20 <- unif_test(data = rhea$X[ind_20, ], type = type_tests,

                           p_value = "asymp", K_max = 5e4)

tests_rhea_15_20

tests_rhea_20

```



### *A Cramér–von Mises test of uniformity on the hypersphere*



The data application in García-Portugués, Navarro-Esteban, and Cuesta-Albertos (2021) regarding the testing of the uniformity of locations for craters in Venus can be reproduced through the script [data-application-cvm.R](https://github.com/egarpor/sphunif/blob/master/applications/data-application-cvm.R).



### *On a class of Sobolev tests for symmetry of directions, their detection thresholds, and asymptotic powers*



The data application in García-Portugués, Paindaveine, and Verdebout (2024) regarding the symmetry of comet orbits can be reproduced through the script [data-application-sobolev.R](https://github.com/egarpor/sphunif/blob/master/applications/data-application-sobolev.R).



### *A stereographic test of spherical uniformity*



The script [simulations-stereo.R](https://github.com/egarpor/sphunif/blob/master/simulations/simulations-stereo.R) contains some of the numerical experiments in Fernández-de-Marcos and García-Portugués (2024).



## References



Fernández-de-Marcos, A. and García-Portugués, E. (2024). A stereographic test of spherical uniformity. *arXiv:2405.13531*. [doi:10.48550/arXiv.2405.13531](https://doi.org/10.48550/arXiv.2405.13531).



García-Portugués, E., Navarro-Esteban, P., and Cuesta-Albertos, J. A. (2023). On a projection-based class of uniformity tests on the hypersphere. *Bernoulli*, 29(1):181--204. [doi:10.1007/978-3-030-69944-4_12](https://doi.org/10.3150/21-BEJ1454).



García-Portugués, E., Navarro-Esteban, P., and Cuesta-Albertos, J. A. (2021). A Cramér–von Mises test of uniformity on the hypersphere. In Balzano, S., Porzio, G. C., Salvatore, R., Vistocco, D., and Vichi, M. (Eds.), *Statistical Learning and Modeling in Data Analysis*, Studies in Classification, Data Analysis and Knowledge Organization, pp. 107--116. Springer, Cham. [doi:10.1007/978-3-030-69944-4_12](https://doi.org/10.1007/978-3-030-69944-4_12).



García-Portugués, E., Paindaveine, D., and Verdebout, T. (2024). On a class of Sobolev tests for symmetry of directions, their detection thresholds, and asymptotic powers. *arXiv:2108.09874v2*. [doi:10.48550/arXiv.2108.09874](https://doi.org/10.48550/arXiv.2108.09874).



García-Portugués, E. and Verdebout, T. (2018). An overview of uniformity tests on the hypersphere. *arXiv:1804.00286*. [doi:10.48550/arXiv.1804.00286](https://doi.org/10.48550/arXiv.1804.00286).