boostmath/README.Rmd at main · andrjohns/boostmath · GitHub

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

# boostmath

<!-- badges: start -->
[![R-CMD-check](https://github.com/andrjohns/boostmath/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/andrjohns/boostmath/actions/workflows/R-CMD-check.yaml)
[![CRAN status](https://www.r-pkg.org/badges/version/boostmath)](https://CRAN.R-project.org/package=boostmath)
[![Downloads](https://cranlogs.r-pkg.org/badges/boostmath?color=blue)](https://CRAN.R-project.org/package=boostmath)
[![boostmath status badge](https://andrjohns.r-universe.dev/badges/boostmath)](https://andrjohns.r-universe.dev/boostmath)
<!-- badges: end -->

Providing simple access to Boost's Math functions in R, no compilation required.

## Installation

You can install the development version of boostmath from [GitHub](https://github.com/) with:

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

Or you can install pre-built binaries from R-Universe:

```{r, eval=FALSE}
install.packages("boostmath", repos = c("https://andrjohns.r-universe.dev",
                                        "https://cran.r-project.org"))
```

## Usage

Functions can be used directly after loading the package:

```{r example}
library(boostmath)

hypergeometric_pFq(c(1, 2.5), c(0.5, 2), 1)
ibeta_inv(2.1, 5.2, 0.7)
owens_t(2.1, 4.2)
```

Any Boost Math functions that share the same name as R functions are sufffixed with `_boost` to avoid conflicts:

```{r}
beta_boost(3, 2)
lgamma_boost(5)
```

## Quadrature and Differentiation

Boost's integration routines are also available for use with R functions:

```{r}
trapezoidal(function(x) { 1/(5 - 4*cos(x)) }, a = 0, b = 2*pi)

gauss_legendre(function(x) { x * x * atan(x) }, a = 0, b = 1, points = 20)

gauss_kronrod(function(x) { exp(-x * x / 2) }, a = 0, b = Inf, points = 15)
```

As well as numerical differentiation by finite-differencing or the complex-step method:

```{r}
finite_difference_derivative(exp, 1.7)

complex_step_derivative(exp, 1.7)
```


## Distribution Functions

`boostmath` implements Boost's approach of creating a distribution 'object' which the various distribution functions (e.g., `pdf`, `quantile`) can be applied:

```{r}
# Normal distribution with mean = 0, sd = 1
dist <- normal_distribution(0, 1)
# Apply generic functions
cdf(dist, 0.5)
logcdf(dist, 0.5)
pdf(dist, 0.5)
logpdf(dist, 0.5)
hazard(dist, 0.5)
chf(dist, 0.5)
mean(dist)
median(dist)
mode(dist)
range(dist)
quantile(dist, 0.2)
standard_deviation(dist)
support(dist)
variance(dist)
skewness(dist)
kurtosis(dist)
kurtosis_excess(dist)
```
Alternatively, the PDF, CDF, log-PDF, log-CDF, and quantile functions for statistical distributions can just be called directly:

```{r}
beta_pdf(0.1, 1.2, 2.1)

beta_lpdf(0.1, 1.2, 2.1)

beta_cdf(0.1, 1.2, 2.1)

beta_lcdf(0.1, 1.2, 2.1)

beta_quantile(0.5, 1.2, 2.1)
```