-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.Rmd
138 lines (97 loc) · 7.11 KB
/
README.Rmd
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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
---
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 = "man/figures/README-",
out.width = "100%"
)
```
# mcmcr <img src="man/figures/logo.png" align="right" />
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
[](https://github.com/poissonconsulting/mcmcr/actions/workflows/R-CMD-check.yaml)
[](https://codecov.io/gh/poissonconsulting/mcmcr?branch=master)
[](https://opensource.org/license/mit)
[](https://cran.r-project.org/package=mcmcr)
<!-- badges: end -->
`mcmcr` is an R package to manipulate Monte Carlo Markov Chain (MCMC) samples.
## Introduction
For the purposes of this discussion, an MCMC *sample* represents the value of a *term* from a single *iteration* of a single *chain*.
While a simple *parameter* such as an intercept corresponds to a single term, more complex parameters such as an interaction between two factors consists of multiple terms with their own inherent dimensionality - in this case a matrix.
A set of MCMC samples can be stored in different ways.
### Existing Classes
The three most common S3 classes store MCMC samples as follows:
- `coda::mcmc` stores the MCMC samples from a single chain as a matrix where each each row represents an iteration and each column represents a variable
- `coda::mcmc.list` stores multiple `mcmc` objects (with identical dimensions) as a list where each object represents a parallel chain
- `rjags::mcarray` stores the samples from a single parameter where the initial dimensions are the parameter dimensions, the second to last dimension is iterations and the last dimension is chains.
In the first two cases the terms/parameters are represented by a single dimension which means that the dimensionality inherent in the parameters is stored in the labelling of the variables, ie, `"bIntercept", "bInteraction[1,2]", "bInteraction[2,1]", ...`.
The structure of the `mcmc` and `mcmc.list` objects emphasizes the time-series nature of MCMC samples and is optimized for thining.
In contrast `mcarray` objects preserve the dimensionality of the parameters.
### New Classes
The `mcmcr` package defines three related S3 classes which also preserve the dimensionality of
the parameters:
- `mcmcr::mcmcarray` is very similar to `rjags::mcarray` except that the first dimension is the chains, the second dimension is iterations and the subsequent dimensions represent the dimensionality of the parameter (it is called `mcmcarray` to emphasize that the MCMC dimensions ie the chains and iterations come first);
- `mcmcr::mcmcr` stores multiple uniquely named `mcmcarray` objects with the same number of chains and iterations.
- `mcmcr::mcmcrs` stores multiple `mcmcr` objects with the same parameters, chains and iterations.
All five classes (`mcmc`, `mcmc.list`, `mcarray`, `mcmcarray`, `mcmcr` and `mcmcrs`) are collectively referred to as MCMC objects.
## Why mcmcr?
`mcmcarray` objects were developed to facilitate manipulation of the MCMC samples.
`mcmcr` objects were developed to allow a set of dimensionality preserving parameters from a single analysis to be manipulated as a whole.
`mcmcrs` objects were developed to allow the results of multiple analyses using the same model to be manipulated together.
The `mcmcr` package (together with the [term](https://github.com/poissonconsulting/term) and [nlist](https://github.com/poissonconsulting/nlist) packages) introduces a variety of (often) generic functions to manipulate and query `mcmcarray`, `mcmcr` and `mcmcrs` objects (and `term` and `nlist` and `nlists` objects).
In particular it provides functions to
- coerce from and to `mcarray`, `mcmc` and `mcmc.list` objects;
- extract an objects `coef` table (as a tibble);
- query an object's `nchains`, `niters`, `term::npars`, `term::nterms`, `nlist::nsims` and `nlist::nsams` as well as it's parameter dimensions (`term::pdims`) and term indices (`term::tindex`);
- `subset` objects by chains, iterations and/or parameters;
- `bind_xx` a pair of objects by their `xx_chains`, `xx_iterations`, `xx_parameters` or (parameter) `xx_dimensions`;
- combine the samples of two (or more) MCMC objects using `combine_samples` (or `combine_samples_n`) or combine the samples of a single MCMC object by reducing its dimensions using `combine_dimensions`;
- `collapse_chains` or `split_chains` an object's chains;
- `mcmc_map` over an objects values;
- transpose an objects parameter dimensions using `mcmc_aperm`;
- assess if an object has `converged` using `rhat` and `esr` (effectively sampling rate);
- and of course `thin`, `rhat`, `ess` (effective sample size), `print`, `plot` etc said objects.
The code is opinionated which has the advantage of providing a small set of stream-lined functions.
For example the only 'convergence' metric is the uncorrected, untransformed, univariate split R-hat (potential scale reduction factor).
If you can convince me that additional features are important I will add them or accept a pull request (see below).
Alternatively you might want to use the `mcmcr` package to manipulate your samples before coercing them to an `mcmc.list` to take advantage of all the summary functions in packages such as `coda`.
## Demonstration
```{r}
library(mcmcr)
mcmcr_example
coef(mcmcr_example, simplify = TRUE)
rhat(mcmcr_example, by = "term")
plot(mcmcr_example[["alpha"]])
```
## Installation
### Release
To install the release version from [CRAN](https://CRAN.R-project.org/package=mcmcr).
```r
install.packages("mcmcr")
```
The website for the release version is at <https://poissonconsulting.github.io/mcmcr/>.
### Development
To install the development version from [GitHub](https://github.com/poissonconsulting/mcmcr)
```r
# install.packages("remotes")
remotes::install_github("poissonconsulting/mcmcr")
```
or from [r-universe](https://poissonconsulting.r-universe.dev/mcmcr).
```r
install.packages("mcmcr", repos = c("https://poissonconsulting.r-universe.dev", "https://cloud.r-project.org"))
```
## Inspiration
[coda](https://github.com/cran/coda) and [rjags](https://github.com/cran/rjags)
## Contribution
Please report any [issues](https://github.com/poissonconsulting/mcmcr/issues).
[Pull requests](https://github.com/poissonconsulting/mcmcr/pulls) are always welcome.
## Code of Conduct
Please note that the mcmcr project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.
## References
Brooks, S., Gelman, A., Jones, G.L., and Meng, X.-L. (Editors). 2011. Handbook for Markov Chain Monte Carlo. Taylor & Francis, Boca Raton. ISBN: 978-1-4200-7941-8.