distionary

Create and Evaluate Probability Distributions

https://github.com/probaverse/distionary

Keywords

Repository

Create and Evaluate Probability Distributions

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# distionary 


[![CRAN status](https://www.r-pkg.org/badges/version/distionary)](https://CRAN.R-project.org/package=distionary)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://cran.r-project.org/web/licenses/MIT)
[![R-CMD-check](https://github.com/probaverse/distionary/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/probaverse/distionary/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/probaverse/distionary/graph/badge.svg)](https://app.codecov.io/gh/probaverse/distionary)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/688_status.svg)](https://github.com/ropensci/software-review/issues/688)


With `distionary`, you can:

1. [Specify](./articles/specify.html) a probability distribution, and
2. [Evaluate](./articles/evaluate.html) the probability distribution.

The main purpose of `distionary` is to implement a distribution object, and to make distribution calculations available even if they are not specified in the distribution. `distionary` powers the wider [`probaverse` ecosystem](https://probaverse.com) for making probability distributions that are representative of your data, not just out-of-the-bag distributions like the Normal, Poisson, etc.

`distionary` makes reference to common terms regarding probability distributions. If you're uneasy with these terms and concepts, most intro books in probability will be a good resource to learn from. As `distionary` develops, more documentation will be made available so that it's more self-contained.

The name "distionary" is a portmanteau of "distribution" and "dictionary". While a dictionary lists and defines words, `distionary` defines distributions and makes a list of common distribution families available. The built-in distributions act as building blocks for the wider probaverse.

## Installation

`distionary` is not on CRAN yet. You can download the development version from GitHub with:

``` r
# install.packages("devtools")
devtools::install_github("probaverse/distionary")
```

## Example

```{r}
library(distionary)
```

**Specify** a distribution like a Poisson distribution and a Generalised Extreme Value (GEV) distribution using the `dst_*()` family of functions.

```{r}
# Create a Poisson distribution
poisson <- dst_pois(1.5)
# Inspect
poisson
```

```{r}
# Create a GEV distribution
gev <- dst_gev(-1, 1, 0.2)
# Inspect
gev
```

Here is what the distributions look like, via their probability mass (PMF) and density functions.

```{r}
plot(poisson)
plot(gev)
```

**Evaluate** various distributional representations (functions that fully describe the distribution), such as the PMF or quantiles. The `eval_*()` functions simply evaluate the representation, whereas the `enframe_*()` functions place the output alongside the input in a data frame or tibble.

```{r}
eval_pmf(poisson, at = 0:4)
enframe_quantile(gev, at = c(0.2, 0.5, 0.9))
```

Evaluate properties such as mean, skewness, and range of valid values.

```{r}
mean(gev)
skewness(poisson)
range(gev)
```

You can make your own distribution, too. 

```{r}
# Make a distribution.
linear <- distribution(
  density = function(x) {
    d <- 2 * (1 - x)
    d[x < 0 | x > 1] <- 0
    d
  },
  cdf = function(x) {
    p <- 2 * x * (1 - x / 2)
    p[x < 0] <- 0
    p[x > 1] <- 1
    p
  },
  .vtype = "continuous",
  .name = "My Linear"
)
# Inspect
linear
```

Here is what it looks like (density function).

```{r}
plot(linear)
```

Even though only the density and CDF are defining the distribution, other properties can be evaluated, like its mean and quantiles

```{r}
mean(linear)
enframe_quantile(linear, at = c(0.2, 0.5, 0.9))
```

## `distionary` in the context of other packages

Other R packages exist that turn probability distributions into objects and allow their evaluation. `distionary` is unique in that provides the distribution framework needed to power the wider [`probaverse` ecosystem](https://probaverse.com), which provides a natural API for making probability distributions that are representative of the system being modelled.

## Acknowledgements

The creation of `distionary` would not have been possible without the support of the R Consortium, The Natural Science and Engineering Research Council of Canada (NSERC), The University of British Columbia, and BGC Engineering Inc.

## Citation

To cite package `distionary` in publications use:

  Coia V (2025). _distionary: Create and Evaluate Probability Distributions_. R
  package version 0.1.0, https://github.com/probaverse/distionary,
  .

## Code of Conduct

Please note that the distionary project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.

Owner

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "distionary",
  "description": "Create probability distribution objects from a list of common distribution families, or make your own distribution. Evaluate distribution properties, even if it is not specified in the distribution's definition.",
  "name": "distionary: Create and Evaluate Probability Distributions",
  "relatedLink": "https://distionary.probaverse.com/",
  "codeRepository": "https://github.com/probaverse/distionary",
  "issueTracker": "https://github.com/probaverse/distionary/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "0.0.2.9000",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.4.2 (2024-10-31)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Vincenzo",
      "familyName": "Coia",
      "email": "vincenzo.coia@gmail.com"
    },
    {
      "@type": "Person",
      "givenName": "Amogh",
      "familyName": "Joshi"
    },
    {
      "@type": "Person",
      "givenName": "Shuyi",
      "familyName": "Tan"
    },
    {
      "@type": "Person",
      "givenName": "Zhipeng",
      "familyName": "Zhu"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Vincenzo",
      "familyName": "Coia",
      "email": "vincenzo.coia@gmail.com"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "covr",
      "name": "covr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=covr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 3.0.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "tibble",
      "name": "tibble",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=tibble"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "ellipsis",
      "name": "ellipsis",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ellipsis"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "rlang",
      "name": "rlang",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rlang"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "stats",
      "name": "stats"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "vctrs",
      "name": "vctrs",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=vctrs"
    },
    "SystemRequirements": null
  },
  "fileSize": "645.888KB",
  "readme": "https://github.com/probaverse/distionary/blob/main/README.md",
  "contIntegration": [
    "https://github.com/probaverse/distionary/actions/workflows/R-CMD-check.yaml",
    "https://app.codecov.io/gh/probaverse/distionary"
  ],
  "developmentStatus": "https://lifecycle.r-lib.org/articles/stages.html#stable",
  "keywords": [
    "r",
    "r-package",
    "rstats"
  ]
}

GitHub Events

Issues and Pull Requests

Last synced: 11 months ago