-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathREADME.Rmd
More file actions
129 lines (90 loc) · 5.31 KB
/
Copy pathREADME.Rmd
File metadata and controls
129 lines (90 loc) · 5.31 KB
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
---
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%"
)
```
# distspec: probability distributions with certain or uncertain parameters <img src="man/figures/logo.png" align="right" height="139" alt="distspec hex logo" />
<!-- badges: start -->
[](https://lifecycle.r-lib.org/articles/stages.html#experimental) [](https://github.com/epiforecasts/distspec/actions/workflows/R-CMD-check.yaml) [](https://app.codecov.io/gh/epiforecasts/distspec) [](https://CRAN.R-project.org/package=distspec)
[](https://github.com/epiforecasts/distspec/blob/main/LICENSE.md) [](https://github.com/epiforecasts/distspec/graphs/contributors) [](https://epiforecasts.r-universe.dev/distspec)
<!-- badges: end -->
distspec represents a probability distribution as a single object, a
`<dist_spec>`, whose parameters can be either fixed or uncertain. It grew out of
[EpiNow2](https://epiforecasts.io/EpiNow2/) and is aimed at the delay
distributions common in infectious disease modelling, such as generation times,
incubation periods and reporting delays, while staying independent of any
particular model.
With distspec you can:
- define a distribution with a named constructor (`Gamma()`, `LogNormal()`,
`Normal()`, `Exponential()`, `Weibull()`, `Beta()`, `Fixed()` or
`NonParametric()`),
by its natural parameters or by its mean and standard deviation;
- give any parameter an uncertain prior (for example
`Gamma(shape = Normal(2, 0.5), rate = 1)`), or leave a nonparametric mass
function uncertain via a `Dirichlet()` prior;
- discretise a continuous distribution to a probability mass function
(`discretise()`), convolve distributions (`+`, `collapse()`), draw samples
(`sample_dist()`), and query means, standard deviations, bounds and PMFs.
## Installation
Install the development version from GitHub:
```r
# install.packages("remotes")
remotes::install_github("epiforecasts/distspec")
```
## Quick start
```{r example}
library(distspec)
# A gamma delay with mean 4 and standard deviation 2, truncated at 20
delay <- Gamma(mean = 4, sd = 2, max = 20)
delay
# Discretise it to a probability mass function
get_pmf(discretise(delay))
# A parameter can itself be a distribution, expressing uncertainty
Gamma(shape = Normal(2, 0.5), rate = 1)
```
`plot()` shows the probability mass and cumulative distribution functions:
```{r plot, fig.alt = "PMF and CDF of a gamma delay with mean 4 and standard deviation 2."}
library(ggplot2)
plot(delay)
```
See `vignette("distspec")` to get started, and the
[reference index](https://epiforecasts.io/distspec/reference/) for the full list
of functions.
## Related work
distspec discretises using
[primarycensored](https://primarycensored.epinowcast.org/), which implements the
double-censoring calculation. In Julia, the same censoring maths lives in
[CensoredDistributions.jl](https://github.com/EpiAware/CensoredDistributions.jl),
and
[ComposedDistributions.jl](https://github.com/EpiAware/ComposedDistributions.jl)
covers similar ground to the `<dist_spec>` combination interface, with
`compose()` / `sequential()` in place of `+` and `observed_distribution` in
place of `collapse()`. Both distspec and ComposedDistributions.jl carry
parameter uncertainty in the object. The Julia packages build on
[Distributions.jl](https://juliastats.org/Distributions.jl/) and represent
richer event trees, while distspec keeps a flatter, R-native representation.
Contributors
---
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
All contributions to this project are gratefully acknowledged using the [`allcontributors` package](https://github.com/ropensci/allcontributors) following the [allcontributors](https://allcontributors.org) specification. Contributions of any kind are welcome!
### Code
<a href="https://github.com/epiforecasts/distspec/commits?author=sbfnk">sbfnk</a>,
<a href="https://github.com/epiforecasts/distspec/commits?author=dependabot[bot]">dependabot[bot]</a>,
<a href="https://github.com/epiforecasts/distspec/commits?author=github-actions[bot]">github-actions[bot]</a>,
<a href="https://github.com/epiforecasts/distspec/commits?author=github-merge-queue[bot]">github-merge-queue[bot]</a>,
<a href="https://github.com/epiforecasts/distspec/commits?author=seabbs">seabbs</a>
### Issues
<a href="https://github.com/epiforecasts/distspec/issues?q=is%3Aissue+author%3Ajamesmbaazam">jamesmbaazam</a>,
<a href="https://github.com/epiforecasts/distspec/issues?q=is%3Aissue+author%3Aepiforecasts-workflows">epiforecasts-workflows</a>
<!-- markdownlint-enable -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->