Learn R Programming

⚠️There's a newer version (1.6.9) of this package.Take me there.

distr6

https://img.shields.io/badge/lifecycle-stable-brightgreen.svg

What is distr6?

distr6 is a unified and clean interface to organise the probability distributions implemented in R into one R6 object oriented package, as well as adding distributions yet to implemented in R, currently we have 36 probability distributions as well as 11 kernels. Building the package from the ground up and making use of tried and tested design patterns (as per Gamma et al. 1994), distr6 aims to make probability distributions easy to use, understand and analyse.

distr6 extends the work of Peter Ruckdeschel, Matthias Kohl et al. who created the first object-oriented (OO) interface for distributions using S4. Their distr package is currently the gold-standard in R for OO distribution handling. Using R6 we aim to take this even further and to create a scalable interface that can continue to grow with the community. Full details of the API and class structure can be seen in the distr6 website.

Main Features

distr6 is not intended to replace the base R distributions function but instead to give an alternative that focuses on distributions as objects that can be manipulated and accessed as required. The main features therefore centre on OOP practices, design patterns and API design. Of particular note:

All distributions in base R introduced as objects with methods for common statistical functions including pdf, cdf, inverse cdf, simulation, mean, variance, skewness and kurtosis

B <- Binomial$new(prob = 0.5, size = 10)
B$pdf(1:10)
#>  [1] 0.0097656250 0.0439453125 0.1171875000 0.2050781250 0.2460937500
#>  [6] 0.2050781250 0.1171875000 0.0439453125 0.0097656250 0.0009765625
B$kurtosis()
#> [1] -0.2
B$rand(5)
#> [1] 5 5 7 3 8
summary(B)
#> Binomial Probability Distribution. Parameterised with:
#>   prob = 0.5, size = 10
#> 
#>   Quick Statistics 
#>  Mean:       5
#>  Variance:   2.5
#>  Skewness:   0
#>  Ex. Kurtosis:   -0.2
#> 
#>  Support: {0,...,10}     Scientific Type: ℕ0 
#> 
#>  Traits: discrete; univariate
#>  Properties: symmetric; platykurtic; no skew

Flexible construction of distributions for common parameterisations

Exponential$new(rate = 2)
#> Exp(rate = 2)
Exponential$new(scale = 2)
#> Exp(scale = 2)
Normal$new(mean = 0, prec = 2)
#> Norm(mean = 0, prec = 2)
Normal$new(mean = 0, sd = 3)$parameters()
#>      id     value support                                 description
#> 1: mean         0       ℝ                   Mean - Location Parameter
#> 2:  var         9      ℝ+          Variance - Squared Scale Parameter
#> 3:   sd         3      ℝ+        Standard Deviation - Scale Parameter
#> 4: prec 0.1111111      ℝ+ Precision - Inverse Squared Scale Parameter

Decorators for extending functionality of distributions to more complex modelling methods

B <- Binomial$new()
decorate(B, ExoticStatistics)
#> B is now decorated with ExoticStatistics
#> Binom(prob = 0.5, size = 10)
B$survival(2)
#> [1] 0.9453125
decorate(B, CoreStatistics)
#> B is now decorated with CoreStatistics
#> Binom(prob = 0.5, size = 10)
B$kthmoment(6)
#> Results from numeric calculations are approximate only. Better results may be available.
#> [1] 190

S3 compatibility to make the interface more flexible for users who are less familiar with OOP

B <- Binomial$new()
mean(B) # B$mean()
#> [1] 5
variance(B) # B$variance()
#> [1] 2.5
cdf(B, 2:5) # B$cdf(2:5)
#> [1] 0.0546875 0.1718750 0.3769531 0.6230469

Wrappers including truncation, huberization and product distributions for manipulation and composition of distributions.

B <- Binomial$new()
TruncatedDistribution$new(B, lower = 2, upper = 5) #Or: truncate(B,2,5)
#> TruncBinom(Binom_prob = 0.5, Binom_size = 10)
N <- Normal$new()
MixtureDistribution$new(list(B,N), weights = c(0.1, 0.9))
#> BinomMixNorm(Binom_prob = 0.5, Binom_size = 10, Norm_mean = 0, Norm_var = 1)
ProductDistribution$new(list(B,N))
#> BinomXNorm(Binom_prob = 0.5, Binom_size = 10, Norm_mean = 0, Norm_var = 1)

Additionally we introduce a SetSymbol class for a purely symbolic representation of sets for Distribution typing

Binomial$new()$type()
#> [1] "ℕ0"
Binomial$new()$support()
#> [1] "{0,...,10}"
Set$new(1:5)
#> [1] "{1,...,5}"
Interval$new(1,5)
#> [1] "[1,5]"
PosReals$new()
#> [1] "ℝ+"

Usage

distr6 has three primary use-cases:

  1. Upgrading base Extend the R distributions functions to classes so that each distribution additionally has basic statistical methods including expectation and variance and properties/traits including discrete/continuous, univariate/multivariate, etc.
  2. Statistics Implementing decorators and adaptors to manipulate distributions including distribution composition. Additionally functionality for numeric calculations based on any arbitrary distribution.
  3. Modelling Probabilistic modelling using distr6 objects as the modelling targets. Objects as targets is an understood ML paradigm and introducing distributions as classes is the first step to implementing probabilistic modelling.

Installation

Before publication to CRAN, the latest stable release is available via:

remotes::install_github("alan-turing-institute/distr6")

Future Plans

The v1.0 release focuses on the core features of the SDistribution class as well as analytic methods in wrappers including but not limit to truncation, huberization, product distributions and mixture distributions. In our next release we plan to include

  • A plot method for Distributions
  • A generalised qqplot for comparing any distributions
  • A finalised FunctionImputation decorator with different imputation strategies
  • Discrete distribution subtraction (negative convolution)
  • A wrapper for scaling distributions to a given mean and variance
  • More probability distributions
  • Any other good suggestions made between now and then!

Package Development and Contributing

distr6 is released under the MIT licence with acknowledgements to the LGPL-3 licence of distr. Therefore any contributions to distr6 will also be accepted under the MIT licence. We welcome all bug reports, issues, questions and suggestions which can be raised here but please read through our contributing guidelines for details including our code of conduct.

Acknowledgements

distr6 is the result of a collaboration between many people, universities and institutions across the world, without whom the speed and performance of the package would not be up to the standard it is. Firstly we acknowledge all the work of Prof. Dr. Peter Ruckdeschel and Prof. Dr. Matthias Kohl in developing the original distr family of packages. Secondly their significant contributions to the planning and design of distr6 including the distribution and probability family class structures. A team of undergraduates at University College London implemented many of the probability distributions and are designing the plotting interface. The team consists of Shen Chen (@ShenSeanChen), Jordan Deenichin (@jdeenichin), Chengyang Gao (@garoc371), Chloe Zhaoyuan Gu (@gzy823), Yunjie He (@RoyaHe), Xiaowen Huang (@w090613), Shuhan Liu (@shliu99), Runlong Yu (@Edwinyrl), Chijing Zeng (@britneyzeng) and Qian Zhou (@yumizhou47). We also want to thank Prof. Dr. Bernd Bischl for discussions about design choices and useful features, particularly advice on the ParameterSet class. Finally University College London and The Alan Turing Institute for hosting workshops, meetings and providing coffee whenever needed.

Copy Link

Version

Install

install.packages('distr6')

Monthly Downloads

332

Version

1.0.0

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Maintainer

Raphael Sonabend

Last Published

July 19th, 2019

Functions in distr6 (1.0.0)

Binomial

Binomial Distribution Class
Cauchy

Cauchy Distribution Class
ArrayDistribution

Product Array Distribution
Arcsine

Arcsine Distribution Class
Bernoulli

Bernoulli Distribution Class
Convolution

Distribution Convolution Wrapper
Complex

Set of Complex Numbers
Categorical

Categorical Distribution Class
ChiSquared

Chi-Squared Distribution Class
Beta

Beta Distribution Class
DistributionDecorator

Abstract DistributionDecorator Class
CoreStatistics

Core Statistical Methods for Distributions
Cosine

Cosine Kernel
Epanechnikov

Epanechnikov Kernel
Empty

Empty Set
Degenerate

Degenerate Distribution Class
Dirichlet

Dirichlet Distribution Class
Distribution

Generalised Distribution Object
DiscreteUniform

Discrete Uniform Distribution Class
DistributionWrapper

Abstract DistributionWrapper Class
Gompertz

Gompertz Distribution Class
Exponential

Exponential Distribution Class
Frechet

Frechet Distribution Class
ExtendedReals

Set of Extended Reals
ExoticStatistics

Exotic Statistical Methods for Distributions
Gumbel

Gumbel Distribution Class
Gamma

Gamma Distribution Class
Geometric

Geometric Distribution Class
FDistribution

'F' Distribution Class
FunctionImputation

Imputed Pdf/Cdf/Quantile/Rand Functions
Integers

Set of Integers
Laplace

Laplace Distribution Class
Logarithmic

Logarithmic Distribution Class
LogisticKernel

Logistic Kernel
Logistic

Logistic Distribution Class
InverseGamma

Inverse Gamma Distribution Class
Kernel

Abstract Kernel Class
Interval

R6 Generalised Class for Symbolic Intervals
Hypergeometric

Hypergeometric Distribution Class
HuberizedDistribution

Distribution Huberization Wrapper
Loglogistic

Log-Logistic Distribution Class
MixtureDistribution

Mixture Distribution Wrapper
NegRationals

Set of Negative Rationals
NegIntegers

Set of Negative Integers
NegReals

Set of Negative Reals
Naturals

Set of Natural Numbers
MultivariateNormal

Multivariate Normal Distribution Class
Multinomial

Multinomial Distribution Class
NegativeBinomial

Negative Binomial Distribution Class
Lognormal

Log-Normal Distribution Class
NormalKernel

Normal Kernel
Normal

Normal Distribution Class
PosNaturals

Set of Positive Natural Numbers
PosRationals

Set of Positive Rationals
ProductDistribution

Product Distribution
PosReals

Set of Positive Reals
Poisson

Poisson Distribution Class
Rationals

Set of Rationals
PosIntegers

Set of Positive Integers
Quartic

Quartic Kernel
Pareto

Pareto Distribution Class
ParameterSet

Make an R6 Parameter Set for Distributions
Sigmoid

Sigmoid Kernel
SetInterval

R6 Generalised Class for Symbolic Sets and Intervals
Reals

Set of Reals
Rayleigh

Rayleigh Distribution Class
SDistribution

Abstract Special Distribution Class
Silverman

Silverman Kernel
SpecialSet

Special Mathematical Sets
Set

R6 Generalised Class for Symbolic Sets
Tricube

Tricube Kernel
Triangular

Triangular Distribution Class
StudentT

Student's T Distribution Class
TriangularKernel

Triangular Kernel
VectorDistribution

Vectorise Distributions
Wald

Wald Distribution Class
TruncatedDistribution

Distribution Truncation Wrapper
Triweight

Triweight Kernel
UniformKernel

Uniform Kernel
Uniform

Uniform Distribution Class
cdf

Cumulative Distribution Function
cdfAntiDeriv

Cumulative Distribution Function Anti-Derivative
distr6-package

distr6: Object Oriented Distributions in R
dimension.SetInterval

SetInterval Dimension Accessor
as.data.table

Coerce ParameterSet to data.table
as.numeric.Interval

Coerces Interval to Numeric
cumHazard

Cumulative Hazard Function
complement.SetInterval

Symbolic Complement for SetInterval
inf.SetInterval

SetInterval Infimum Accessor
class.SetInterval

SetInterval Minimum Accessor
correlation

Distribution Correlation
inf

Infimum Accessor
kurtosis

Distribution Kurtosis
dmax

Distribution Maximum Accessor
Weibull

Weibull Distribution Class
dmin

Distribution Minimum Accessor
cdfPNorm

Cumulative Distribution Function P-Norm
median.Distribution

Median of a Distribution
kthmoment

Kth Moment
iqr

Distribution Interquartile Range
mean.Distribution

Distribution Mean
pdfPNorm

Probability Density Function P-Norm
kurtosisType

Type of Kurtosis Accessor
genExp

Generalised Expectation of a Distribution
exkurtosisType

Kurtosis Type
liesInSetInterval

Test if Data Lies in SetInterval.
liesInSupport

Test if Data Lies in Distribution Support
cf

Characteristic Function
getParameterSupport

Parameter Support Accessor
length.Interval

Length of Interval
generalPNorm

Generalised P-Norm
pgf

Probability Generating Function
listSpecialSets

Lists Implemented R6 Special Sets
entropy

Distribution Entropy
getSymbol.SetInterval

SetInterval Symbol Accessor
elements

Set Elements Accessor
getParameterValue

Parameter Value Accessor
makeUniqueDistributions

De-Duplicate Distribution Names
length.Set

Length of Set
quantile.Distribution

Inverse Cumulative Distribution Function
survival

Survival Function
properties

Properties Accessor
listWrappers

Lists Implemented Distribution Wrappers
listDistributions

Lists Implemented Distributions
rand

Random Simulation Function
product.SetInterval

Symbolic Cartesian Product for SetInterval
setOperation

Symbolic Operations for SetInterval
print.ParameterSet

Print a ParameterSet
max.SetInterval

SetInterval Maximum Accessor
as.ParameterSet

Coerce to a ParameterSet
testContinuous

assert/check/test/Continuous
truncate

Truncate a Distribution
testDiscrete

assert/check/test/Discrete
listKernels

Lists Implemented Kernels
power.SetInterval

Symbolic Exponentiation for SetInterval
pdf

Probability Density/Mass Function
parameters

Parameters Accessor
skewnessType

Type of Skewness Accessor
type

Type Accessor
min.SetInterval

SetInterval Minimum Accessor
sup.SetInterval

SetInterval Supremum Accessor
support

Support Accessor
squared2Norm

Squared Probability Density Function 2-Norm
variance

Distribution Variance
survivalAntiDeriv

Survival Function Anti-Derivative
union.SetInterval

Symbolic Unions for SetInterval
testMatrixvariate

assert/check/test/Matrixvariate
testLeptokurtic

assert/check/test/Leptokurtic
type.SetInterval

SetInterval Type Accessor
prec

Precision of a Distribution
setParameterValue

Parameter Value Setter
decorate

Decorate Distributions
decorators

Decorators Accessor
hazard

Hazard Function
variateForm

Variate Form Accessor
stdev

Standard Deviation of a Distribution
mode

Mode of a Distribution
huberize

Huberize a Distribution
listDecorators

Lists Implemented Distribution Decorators
mgf

Moment Generating Function
merge.ParameterSet

Combine ParameterSets
liesInType

Test if Data Lies in Distribution Type
strprint

String Representation of Print
setSymbol

Unicode Symbol of Special Sets
testDistributionList

assert/check/test/DistributionList
testDistribution

assert/check/test/Distribution
wrappedModels

Gets Internally Wrapped Models
skewness

Distribution Skewness
skewType

Skewness Type
sup

Supremum Accessor
summary.Distribution

Distribution Summary
testMultivariate

assert/check/test/Multivariate
testUnivariate

assert/check/test/Univariate
traits

Traits Accessor
testNegativeSkew

assert/check/test/NegativeSkew
testNoSkew

assert/check/test/NoSkew
symmetry

Symmetry Accessor
testSymmetric

assert/check/test/Symmetric
valueSupport

Value Support Accessor
testMixture

assert/check/test/Mixture
testPositiveSkew

assert/check/test/PositiveSkew
update.ParameterSet

Updates a ParameterSet
survivalPNorm

Survival Function P-Norm
testMesokurtic

assert/check/test/Mesokurtic
testPlatykurtic

assert/check/test/Platykurtic