---
output:
  md_document:
    variant: gfm
---

```{r, 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, 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")
)
```

<!-- <img src="" alt="sphunif hexlogo" align="right" width="200" style="padding: 0 15px; float: right;"/> -->

## Overview

Implementation of more than 30 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, 2020).

## 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")
```

## Data application in astronomy

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

```{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
```

## References

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., Navarro-Esteban, P., and Cuesta-Albertos, J. A. (2020). On a projection-based class of uniformity tests on the hypersphere. *arXiv:2008.09897*. <https://arxiv.org/abs/2008.09897>.

García-Portugués, E. and Verdebout, T. (2018). An overview of uniformity tests on the hypersphere. *arXiv:1804.00286*. <https://arxiv.org/abs/1804.00286>.

García-Portugués, E., Paindaveine, D., and Verdebout, T. (2021). On the power of Sobolev tests for isotropy under local rotationally symmetric alternatives. *arXiv:2108.09874*. <https://arxiv.org/abs/2108.09874>.