README.Rmd

---
bibliography: man/references/ref.bib
always_allow_html: yes
output:
  github_document:
    df_print: kable
---

```{r, setup, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE, comment = "#>",
    fig.path = "man/figures/README",
    fig.align = "center", out.width = "100%",
    asciicast_theme = if (Sys.getenv("IN_PKGDOWN") == "true") "pkgdown" else "readme"
)
asciicast::init_knitr_engine(
    echo = TRUE, echo_input = FALSE,
    startup = quote(library(LearnNonparam))
)
options(
    asciicast_at = "all",
    asciicast_cursor = FALSE,
    asciicast_knitr_svg = TRUE,
    asciicast_padding_y = 0,
    asciicast_start_wait = 0,
    asciicast_end_wait = 1
)
```

# LearnNonparam <img src="man/figures/logo.svg" alt="logo" width="15%" align="right"/>

[![License](https://img.shields.io/cran/l/LearnNonparam?color=orange)](https://cran.r-project.org/web/licenses/GPL-2)
[![CRAN status](https://www.r-pkg.org/badges/version/LearnNonparam)](https://cran.r-project.org/package=LearnNonparam)
[![Dependencies](https://tinyverse.netlify.app/badge/LearnNonparam)](https://cran.r-project.org/package=LearnNonparam)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/LearnNonparam)](https://r-pkg.org/pkg/LearnNonparam)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/grand-total/LearnNonparam)](https://r-pkg.org/pkg/LearnNonparam)

## Overview

This R package implements several non-parametric tests in chapters 1-5 of [@higgins2004](#references), including tests for one sample, two samples, k samples, paired comparisons, blocked designs, trends and association. Built with [Rcpp](https://CRAN.R-project.org/package=Rcpp) for efficiency and [R6](https://CRAN.R-project.org/package=R6) for flexible, object-oriented design, it provides a unified framework for performing or creating custom permutation tests.

## Installation

Install the stable version from [CRAN](https://CRAN.R-project.org/package=LearnNonparam):

```{r, install_cran, eval = FALSE}
install.packages("LearnNonparam")
```

Install the development version from [Github](https://github.com/qddyy/LearnNonparam):

```{r, install_github, eval = FALSE}
# install.packages("remotes")
remotes::install_github("qddyy/LearnNonparam")
```

## Usage

```{r, library, eval = FALSE}
library(LearnNonparam)
options(LearnNonparam.pmt_progress = TRUE)
```

- Construct a test object
    - from some R6 class directly
    ```{r, create_R6, eval = FALSE}
    t <- Wilcoxon$new(n_permu = 1e6)
    ```

    - using the `pmt` (**p**er**m**utation **t**est) wrapper
    ```{r, create_pmt, eval = FALSE}
    # recommended for a unified API
    t <- pmt("twosample.wilcoxon", n_permu = 1e6)
    ```

    ```{asciicast, create, include = FALSE}
    t <- pmt("twosample.wilcoxon", n_permu = 1e6)
    ```

- Provide it with samples

    ```{asciicast, test}
    set.seed(-1)

    t$test(rnorm(10, 1), rnorm(10, 0))
    ```

- Check the results
    ```{asciicast, statistic}
    t$statistic
    ```

    ```{asciicast, p_value}
    t$p_value
    ```

    ```{asciicast, print}
    options(digits = 3)

    t$print()
    ```

    ```{asciicast, plot}
    ggplot2::theme_set(ggplot2::theme_minimal())

    t$plot(style = "ggplot2", binwidth = 1)
    ```

    ```{asciicast, save_plot, include = FALSE}
    ggplot2::ggsave(
        "./man/figures/README/histogram.svg",
        width = 12, height = 9, device = "svg"
    )
    ```

    ```{r, include_plot, echo = FALSE}
    knitr::include_graphics("./man/figures/README/histogram.svg")
    ```

- Modify some settings and observe the change
    ```{asciicast, modify}
    t$type <- "asymp"
    t$p_value
    ```

<details><summary>
See <code>pmts()</code> for tests implemented in this package.</summary>
```{r, echo = FALSE}
LearnNonparam::pmts()
```
</details>

`define_pmt` allows users to define new permutation tests. Take the two-sample Cramér-Von Mises test as an example:

```{asciicast, define}
t <- define_pmt(
    # this is a two-sample permutation test
    inherit = "twosample",
    statistic = function(x, y) {
        # (optional) pre-calculate certain constants that remain invariant during permutation
        n_x <- length(x)
        n_y <- length(y)
        F_x <- seq_len(n_x) / n_x
        G_y <- seq_len(n_y) / n_y
        # return a closure to calculate the test statistic
        function(x, y) {
            x <- sort.int(x)
            y <- sort.int(y)
            F <- approxfun(x, F_x, "constant", 0, 1)
            G <- approxfun(y, G_y, "constant", 0, 1)
            sum(c(F_x - G(x), G_y - F(y))^2)
        }
    },
    # reject the null hypothesis when the test statistic is large
    rejection = "r",
    name = "Two-Sample Cramér-Von Mises Test",
    alternative = "samples are from different continuous distributions"
)

t$test(rnorm(10), runif(10))$print()
```

## References