rust/README.Rmd at master · paulnorthrop/rust · 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
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

# rust <a href="https://paulnorthrop.github.io/rust/"><img src="tools/rust_logo.png" align="right" style="float:right; height:150px;" alt="rust logo"/></a>

[![R-CMD-check](https://github.com/paulnorthrop/rust/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/paulnorthrop/rust/actions/workflows/R-CMD-check.yaml)
[![Coverage Status](https://codecov.io/github/paulnorthrop/rust/coverage.svg?branch=master)](https://app.codecov.io/github/paulnorthrop/rust?branch=master)
[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/rust)](https://cran.r-project.org/package=rust)
[![Downloads (monthly)](https://cranlogs.r-pkg.org/badges/rust?color=brightgreen)](https://cran.r-project.org/package=rust)
[![Downloads (total)](https://cranlogs.r-pkg.org/badges/grand-total/rust?color=brightgreen)](https://cran.r-project.org/package=rust)

See also [RUSampling](https://pypi.org/project/rusampling/) for a translation of `rust` into Python, courtesy of Lynne Jewson.

## Ratio-of-uniforms simulation with transformation

### What does rust do?

The `rust` package implements the multivariate generalized ratio-of-uniforms method of simulating random variates from a d-dimensional continuous distribution.  The user specifies (the log of) a positive target function `f` that is proportional to the density function of the distribution.

### A simple example

We use the function `ru` to simulate a sample of size 1000 from a two-dimensional standard normal distribution with strong positive correlation between the components.  Of course, this particular example is purely illustrative: there are better ways to simulate from a multivariate normal distribution.

```{r, eval = FALSE}
rho <- 0.9
covmat <- matrix(c(1, rho, rho, 1), 2, 2)
log_dmvnorm <- function(x, mean = rep(0, d), sigma = diag(d)) {
  x <- matrix(x, ncol = length(x))
  d <- ncol(x)
  - 0.5 * (x - mean) %*% solve(sigma) %*% t(x - mean)
}
x <- ru(logf = log_dmvnorm, sigma = covmat, d = 2, n = 1000, init = c(0, 0))
```

From version 1.2.0 onwards the faster function `ru_rcpp` can be used.  See the vignette "Rusting Faster: Simulation using Rcpp" for details.

```{r, eval = FALSE}
# Create an external pointer to a C++ function to evaluate the log-density.
ptr_bvn <- create_xptr("logdnorm2")
# Pass the external pointer to `ru_rcpp`.
x <- ru_rcpp(logf = ptr_bvn, rho = rho, d = 2, n = 1000, init = c(0, 0))
```

### Installation

To get the current released version from CRAN:

```{r installation, eval = FALSE}
install.packages("rust")
```

### Vignettes

See `vignette("rust-a-vignette", package = "rust")` for an overview of the package,
`vignette("rust-b-when-to-use-vignette", package = "rust")` for guidance on when `rust` can be used and `vignette("rust-c-using-rcpp-vignette", package = "rust")` for information on how to take advantage of the Rcpp package.