Title: Probability Distributions and Parameter Estimation
Version: 0.14.2
Description: Implements an S4 distribution system and estimation methods for parameters of common distribution families. The common d, p, q, r function family for each distribution is enriched with the ll, e, and v counterparts, computing the log-likelihood, performing estimation, and calculating the asymptotic variance - covariance matrix, respectively. Parameter estimation is performed analytically whenever possible.
License: GPL (≥ 3)
URL: https://thechibo.github.io/joker/
BugReports: https://github.com/thechibo/joker/issues/
Depends: R (≥ 4.0.0)
Imports: ggh4x, ggplot2, grDevices, Matrix, methods, stats, utils
Suggests: covr, knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
Encoding: UTF-8
Language: en-US
RoxygenNote: 7.3.2
NeedsCompilation: no
Packaged: 2025-04-25 16:36:53 UTC; John
Author: Ioannis Oikonomidis ORCID iD [aut, cre], Samis Trevezas ORCID iD [aut, ths]
Maintainer: Ioannis Oikonomidis <goikon@math.uoa.gr>
Repository: CRAN
Date/Publication: 2025-04-28 12:40:01 UTC

joker: Probability Distributions and Parameter Estimation

Description

logo

Implements an S4 distribution system and estimation methods for parameters of common distribution families. The common d, p, q, r function family for each distribution is enriched with the ll, e, and v counterparts, computing the log-likelihood, performing estimation, and calculating the asymptotic variance - covariance matrix, respectively. Parameter estimation is performed analytically whenever possible.

Author(s)

Maintainer: Ioannis Oikonomidis goikon@math.uoa.gr (ORCID)

Authors:

See Also

Useful links:

Bern Distribution

Description

The Bernoulli distribution is a discrete probability distribution which takes the value 1 with probability p and the value 0 with probability 1 - p, where 0 \leq p \leq 1.

Usage

Bern(prob = 0.5)

dbern(x, prob, log = FALSE)

pbern(q, prob, lower.tail = TRUE, log.p = FALSE)

qbern(p, prob, lower.tail = TRUE, log.p = FALSE)

rbern(n, prob)

## S4 method for signature 'Bern,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Bern,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Bern,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Bern,numeric'
r(distr, n)

## S4 method for signature 'Bern'
mean(x)

## S4 method for signature 'Bern'
median(x)

## S4 method for signature 'Bern'
mode(x)

## S4 method for signature 'Bern'
var(x)

## S4 method for signature 'Bern'
sd(x)

## S4 method for signature 'Bern'
skew(x)

## S4 method for signature 'Bern'
kurt(x)

## S4 method for signature 'Bern'
entro(x)

## S4 method for signature 'Bern'
finf(x)

llbern(x, prob)

## S4 method for signature 'Bern,numeric'
ll(distr, x)

ebern(x, type = "mle", ...)

## S4 method for signature 'Bern,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Bern,numeric'
me(distr, x, na.rm = FALSE)

vbern(prob, type = "mle")

## S4 method for signature 'Bern'
avar_mle(distr)

## S4 method for signature 'Bern'
avar_me(distr)

Arguments

prob

numeric. Probability of success.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Bern. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

distr

an object of class Bern.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability mass function (PMF) of the Bernoulli distribution is given by:

f(x; p) = p^x (1 - p)^{1 - x}, \quad p \in (0, 1), \quad x \in \{0, 1\}.

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dbinom(), pbinom(), qbinom(), rbinom()

Examples

# -----------------------------------------------------
# Bernoulli Distribution Example
# -----------------------------------------------------

# Create the distribution
p <- 0.7
D <- Bern(p)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0, 1)) # density function
p(D, c(0, 1)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llbern(x, p)

ebern(x, type = "mle")
ebern(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("bern", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vbern(p, type = "mle")
vbern(p, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Beta Distribution

Description

The Beta distribution is an absolute continuous probability distribution with support S = [0,1], parameterized by two shape parameters, \alpha > 0 and \beta > 0.

Usage

Beta(shape1 = 1, shape2 = 1)

## S4 method for signature 'Beta,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Beta,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Beta,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Beta,numeric'
r(distr, n)

## S4 method for signature 'Beta'
mean(x)

## S4 method for signature 'Beta'
median(x)

## S4 method for signature 'Beta'
mode(x)

## S4 method for signature 'Beta'
var(x)

## S4 method for signature 'Beta'
sd(x)

## S4 method for signature 'Beta'
skew(x)

## S4 method for signature 'Beta'
kurt(x)

## S4 method for signature 'Beta'
entro(x)

## S4 method for signature 'Beta'
finf(x)

llbeta(x, shape1, shape2)

## S4 method for signature 'Beta,numeric'
ll(distr, x)

ebeta(x, type = "mle", ...)

## S4 method for signature 'Beta,numeric'
mle(
  distr,
  x,
  par0 = "same",
  method = "L-BFGS-B",
  lower = 1e-05,
  upper = Inf,
  na.rm = FALSE
)

## S4 method for signature 'Beta,numeric'
me(distr, x, na.rm = FALSE)

## S4 method for signature 'Beta,numeric'
same(distr, x, na.rm = FALSE)

vbeta(shape1, shape2, type = "mle")

## S4 method for signature 'Beta'
avar_mle(distr)

## S4 method for signature 'Beta'
avar_me(distr)

## S4 method for signature 'Beta'
avar_same(distr)

Arguments

shape1, shape2

numeric. The non-negative distribution parameters.

distr

an object of class Beta.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Beta. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle, me, or same).

...

extra arguments.

par0, method, lower, upper

arguments passed to optim for the mle optimization. See Details.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Beta distribution is given by:

f(x; \alpha, \beta) = \frac{x^{\alpha - 1} (1 - x)^{\beta - 1}}{B(\alpha, \beta)}, \quad \alpha\in\mathbb{R}_+, \, \beta\in\mathbb{R}_+,

for x \in S = [0, 1], where B(\alpha, \beta) is the Beta function:

B(\alpha, \beta) = \int_0^1 t^{\alpha - 1} (1 - t)^{\beta - 1} dt.

The MLE of the beta distribution parameters is not available in closed form and has to be approximated numerically. This is done with optim(). Specifically, instead of solving a bivariate optimization problem w.r.t (\alpha, \beta), the optimization can be performed on the parameter sum \alpha_0:=\alpha + \beta \in(0,+\infty). The default method used is the L-BFGS-B method with lower bound 1e-5 and upper bound Inf. The par0 argument can either be a numeric (satisfying ⁠lower <= par0 <= upper⁠) or a character specifying the closed-form estimator to be used as initialization for the algorithm ("me" or "same" - the default value).

Value

Each type of function returns a different type of object:

References

See Also

Functions from the stats package: dbeta(), pbeta(), qbeta(), rbeta()

Examples

# -----------------------------------------------------
# Beta Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- 3
b <- 5
D <- Beta(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 0.8, 0.5)) # density function
p(D, c(0.3, 0.8, 0.5)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llbeta(x, a, b)

ebeta(x, type = "mle")
ebeta(x, type = "me")
ebeta(x, type = "same")

mle(D, x)
me(D, x)
same(D, x)
e(D, x, type = "mle")

mle("beta", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vbeta(a, b, type = "mle")
vbeta(a, b, type = "me")
vbeta(a, b, type = "same")

avar_mle(D)
avar_me(D)
avar_same(D)

v(D, type = "mle")

Binom Distribution

Description

The binomial distribution is a discrete probability distribution which models the probability of having x successes in n independent Bernoulli trials with success probability p.

Usage

Binom(size = 1, prob = 0.5)

## S4 method for signature 'Binom,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Binom,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Binom,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Binom,numeric'
r(distr, n)

## S4 method for signature 'Binom'
mean(x)

## S4 method for signature 'Binom'
var(x)

## S4 method for signature 'Binom'
sd(x)

## S4 method for signature 'Binom'
skew(x)

## S4 method for signature 'Binom'
kurt(x)

## S4 method for signature 'Binom'
entro(x)

## S4 method for signature 'Binom'
finf(x)

llbinom(x, size, prob)

## S4 method for signature 'Binom,numeric'
ll(distr, x)

ebinom(x, size, type = "mle", ...)

## S4 method for signature 'Binom,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Binom,numeric'
me(distr, x, na.rm = FALSE)

vbinom(size, prob, type = "mle")

## S4 method for signature 'Binom'
avar_mle(distr)

## S4 method for signature 'Binom'
avar_me(distr)

Arguments

size

number of trials (zero or more).

prob

numeric. Probability of success on each trial.

distr

an object of class Binom.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Binom. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability mass function (PMF) of the binomial distribution is given by:

f(x; n, p) = \binom{n}{x} p^x (1 - p)^{n - x}, \quad N \in \mathbb{N}, \quad p \in (0, 1),

with x \in \{0, 1, \dots, N\}.

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dbinom(), pbinom(), qbinom(), rbinom()

Examples

# -----------------------------------------------------
# Binomial Distribution Example
# -----------------------------------------------------

# Create the distribution
N <- 10 ; p <- 0.7
D <- Binom(N, p)

# ------------------
# dpqr Functions
# ------------------

d(D, 0:N) # density function
p(D, 0:N) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llbinom(x, N, p)

ebinom(x, size = N, type = "mle")
ebinom(x, size = N, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

# ------------------
# Estimator Variance
# ------------------

vbinom(N, p, type = "mle")
vbinom(N, p, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Cat Distribution

Description

The Categorical distribution is a discrete probability distribution that describes the probability of a single trial resulting in one of k possible categories. It is a generalization of the Bernoulli distribution and a special case of the multinomial distribution with n = 1.

Usage

Cat(prob = c(0.5, 0.5))

dcat(x, prob, log = FALSE)

rcat(n, prob)

## S4 method for signature 'Cat,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Cat,numeric'
r(distr, n)

## S4 method for signature 'Cat'
mean(x)

## S4 method for signature 'Cat'
mode(x)

## S4 method for signature 'Cat'
var(x)

## S4 method for signature 'Cat'
entro(x)

## S4 method for signature 'Cat'
finf(x)

llcat(x, prob)

## S4 method for signature 'Cat,numeric'
ll(distr, x)

ecat(x, type = "mle", ...)

## S4 method for signature 'Cat,numeric'
mle(distr, x, dim = NULL, na.rm = FALSE)

## S4 method for signature 'Cat,numeric'
me(distr, x, dim = NULL, na.rm = FALSE)

vcat(prob, type = "mle")

## S4 method for signature 'Cat'
avar_mle(distr)

## S4 method for signature 'Cat'
avar_me(distr)

Arguments

prob

numeric. Probability vector of success for each category.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Cat. For the log-likelihood and the estimation functions, x is the sample of observations.

log

logical. Should the logarithm of the probability be returned?

n

number of observations. If length(n) > 1, the length is taken to be the number required.

distr

an object of class Cat.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

dim

numeric. The probability vector dimension. See Details.

na.rm

logical. Should the NA values be removed?

Details

The probability mass function (PMF) of the categorical distribution is given by:

f(x; p) = \prod_{i=1}^k p_i^{x_i},

subject to \sum_{i=1}^{k} x_i = n .

The estimation of prob from a sample would by default return a vector of probabilities corresponding to the categories that appeared in the sample and 0 for the rest. However, the parameter dimension cannot be uncovered by the sample, it has to be provided separately. This can be done with the argument dim. If dim is not supplied, the dimension will be retrieved from the distr argument. Categories that did not appear in the sample will have 0 probabilities appended to the end of the prob vector.

Note that the actual dimension of the probability parameter vector is k-1, therefore the Fisher information matrix and the asymptotic variance - covariance matrix of the estimators is of dimension ⁠(k-1)x(k-1)⁠.

Value

Each type of function returns a different type of object:

See Also

dmultinom(), rmultinom()

Examples

# -----------------------------------------------------
# Categorical Distribution Example
# -----------------------------------------------------

# Create the distribution
p <- c(0.1, 0.2, 0.7)
D <- Cat(p)

# ------------------
# dpqr Functions
# ------------------

d(D, 2) # density function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
mode(D) # Mode
var(D) # Variance
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llcat(x, p)

ecat(x, dim = 3, type = "mle")
ecat(x, dim = 3, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("cat", dim = 3, x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vcat(p, type = "mle")
vcat(p, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Cauchy Distribution

Description

The Cauchy distribution is an absolute continuous probability distribution characterized by its location parameter x_0 and scale parameter \gamma > 0.

Usage

Cauchy(location = 0, scale = 1)

## S4 method for signature 'Cauchy,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Cauchy,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Cauchy,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Cauchy,numeric'
r(distr, n)

## S4 method for signature 'Cauchy'
mean(x)

## S4 method for signature 'Cauchy'
median(x)

## S4 method for signature 'Cauchy'
mode(x)

## S4 method for signature 'Cauchy'
var(x)

## S4 method for signature 'Cauchy'
sd(x)

## S4 method for signature 'Cauchy'
skew(x)

## S4 method for signature 'Cauchy'
kurt(x)

## S4 method for signature 'Cauchy'
entro(x)

## S4 method for signature 'Cauchy'
finf(x)

llcauchy(x, location, scale)

## S4 method for signature 'Cauchy,numeric'
ll(distr, x)

ecauchy(x, type = "mle", ...)

## S4 method for signature 'Cauchy,numeric'
mle(
  distr,
  x,
  par0 = "me",
  method = "L-BFGS-B",
  lower = c(-Inf, 1e-05),
  upper = c(Inf, Inf),
  na.rm = FALSE
)

## S4 method for signature 'Cauchy,numeric'
me(distr, x, na.rm = FALSE)

vcauchy(location, scale, type = "mle")

## S4 method for signature 'Cauchy'
avar_mle(distr)

Arguments

location, scale

numeric. Location and scale parameters.

distr

an object of class Cauchy.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Cauchy. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

par0, method, lower, upper

arguments passed to optim for the mle optimization.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Cauchy distribution is given by:

f(x; x_0, \gamma) = \frac{1}{\pi \gamma \left[1 + \left(\frac{x - x_0}{\gamma}\right)^2\right]}.

The MLE of the Cauchy distribution parameters is not available in closed form and has to be approximated numerically. This is done with optim(). The default method used is the L-BFGS-B method with lower bounds c(-Inf, 1e-5) and upper bounds c(Inf, Inf). The par0 argument can either be a numeric (both elements satisfying ⁠lower <= par0 <= upper⁠) or a character specifying the closed-form estimator to be used as initialization for the algorithm ("me" - the default value).

Note that the me() estimator for the Cauchy distribution is not a moment estimator; it utilizes the sample median instead of the sample mean.

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dcauchy(), pcauchy(), qcauchy(), rcauchy()

Examples

# -----------------------------------------------------
# Cauchy Distribution Example
# -----------------------------------------------------

# Create the distribution
x0 <- 3 ; scale <- 5
D <- Cauchy(x0, scale)

# ------------------
# dpqr Functions
# ------------------

d(D, c(-5, 3, 10)) # density function
p(D, c(-5, 3, 10)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

median(D) # Median
mode(D) # Mode
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llcauchy(x, x0, scale)

ecauchy(x, type = "mle")
ecauchy(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("cauchy", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vcauchy(x0, scale, type = "mle")
avar_mle(D)
v(D, type = "mle")

Chi-Square Distribution

Description

The Chi-Square distribution is a continuous probability distribution commonly used in statistical inference, particularly in hypothesis testing and confidence interval estimation. It is defined by the degrees of freedom parameter k > 0.

Usage

Chisq(df = 1)

## S4 method for signature 'Chisq,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Chisq,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Chisq,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Chisq,numeric'
r(distr, n)

## S4 method for signature 'Chisq'
mean(x)

## S4 method for signature 'Chisq'
median(x)

## S4 method for signature 'Chisq'
mode(x)

## S4 method for signature 'Chisq'
var(x)

## S4 method for signature 'Chisq'
sd(x)

## S4 method for signature 'Chisq'
skew(x)

## S4 method for signature 'Chisq'
kurt(x)

## S4 method for signature 'Chisq'
entro(x)

## S4 method for signature 'Chisq'
finf(x)

llchisq(x, df)

## S4 method for signature 'Chisq,numeric'
ll(distr, x)

echisq(x, type = "mle", ...)

## S4 method for signature 'Chisq,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Chisq,numeric'
me(distr, x, na.rm = FALSE)

vchisq(df, type = "mle")

## S4 method for signature 'Chisq'
avar_mle(distr)

## S4 method for signature 'Chisq'
avar_me(distr)

Arguments

df

numeric. The distribution degrees of freedom parameter.

distr

an object of class Chisq.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Chisq. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Chi-Square distribution is given by:

f(x; k) = \frac{1}{2^{k/2}\Gamma(k/2)} x^{k/2 - 1} e^{-x/2}, \quad x > 0.

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dchisq(), pchisq(), qchisq(), rchisq()

Examples

# -----------------------------------------------------
# Chi-Square Distribution Example
# -----------------------------------------------------

# Create the distribution
df <- 4
D <- Chisq(df)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 2, 20)) # density function
p(D, c(0.3, 2, 20)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
den <- d(D) ; den(x) # den is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llchisq(x, df)

echisq(x, type = "mle")
echisq(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("chisq", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vchisq(df, type = "mle")
vchisq(df, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Dirichlet Distribution

Description

The Dirichlet distribution is an absolute continuous probability, specifically a multivariate generalization of the beta distribution, parameterized by a vector \boldsymbol{\alpha} = (\alpha_1, \alpha_2, ..., \alpha_k) with \alpha_i > 0.

Usage

Dir(alpha = c(1, 1))

ddir(x, alpha, log = FALSE)

rdir(n, alpha)

## S4 method for signature 'Dir,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Dir,matrix'
d(distr, x)

## S4 method for signature 'Dir,numeric'
r(distr, n)

## S4 method for signature 'Dir'
mean(x)

## S4 method for signature 'Dir'
mode(x)

## S4 method for signature 'Dir'
var(x)

## S4 method for signature 'Dir'
entro(x)

## S4 method for signature 'Dir'
finf(x)

lldir(x, alpha)

## S4 method for signature 'Dir,matrix'
ll(distr, x)

edir(x, type = "mle", ...)

## S4 method for signature 'Dir,matrix'
mle(
  distr,
  x,
  par0 = "same",
  method = "L-BFGS-B",
  lower = 1e-05,
  upper = Inf,
  na.rm = FALSE
)

## S4 method for signature 'Dir,matrix'
me(distr, x, na.rm = FALSE)

## S4 method for signature 'Dir,matrix'
same(distr, x, na.rm = FALSE)

vdir(alpha, type = "mle")

## S4 method for signature 'Dir'
avar_mle(distr)

## S4 method for signature 'Dir'
avar_me(distr)

## S4 method for signature 'Dir'
avar_same(distr)

Arguments

alpha

numeric. The non-negative distribution parameter vector.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Dir. For the log-likelihood and the estimation functions, x is the sample of observations.

log

logical. Should the logarithm of the probability be returned?

n

number of observations. If length(n) > 1, the length is taken to be the number required.

distr

an object of class Dir.

type

character, case ignored. The estimator type (mle, me, or same).

...

extra arguments.

par0, method, lower, upper

arguments passed to optim for the mle optimization.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Dirichlet distribution is given by:

f(x_1, ..., x_k; \alpha_1, ..., \alpha_k) = \frac{1}{B(\boldsymbol{\alpha})} \prod_{i=1}^k x_i^{\alpha_i - 1},

where B(\boldsymbol{\alpha}) is the multivariate Beta function:

B(\boldsymbol{\alpha}) = \frac{\prod_{i=1}^k \Gamma(\alpha_i)}{\Gamma\left(\sum_{i=1}^k \alpha_i\right)}

and \sum_{i=1}^k x_i = 1, x_i > 0.

Value

Each type of function returns a different type of object:

References

Examples

# -----------------------------------------------------
# Dir Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- c(0.5, 2, 5)
D <- Dir(a)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 0.2, 0.5)) # density function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
mode(D) # Mode
var(D) # Variance
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
lldir(x, a)

edir(x, type = "mle")
edir(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("dir", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vdir(a, type = "mle")
vdir(a, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Exponential Distribution

Description

The Exponential distribution is a continuous probability distribution often used to model the time between independent events that occur at a constant average rate. It is defined by the rate parameter \lambda > 0.

Usage

Exp(rate = 1)

## S4 method for signature 'Exp,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Exp,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Exp,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Exp,numeric'
r(distr, n)

## S4 method for signature 'Exp'
mean(x)

## S4 method for signature 'Exp'
median(x)

## S4 method for signature 'Exp'
mode(x)

## S4 method for signature 'Exp'
var(x)

## S4 method for signature 'Exp'
sd(x)

## S4 method for signature 'Exp'
skew(x)

## S4 method for signature 'Exp'
kurt(x)

## S4 method for signature 'Exp'
entro(x)

## S4 method for signature 'Exp'
finf(x)

llexp(x, rate)

## S4 method for signature 'Exp,numeric'
ll(distr, x)

eexp(x, type = "mle", ...)

## S4 method for signature 'Exp,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Exp,numeric'
me(distr, x, na.rm = FALSE)

vexp(rate, type = "mle")

## S4 method for signature 'Exp'
avar_mle(distr)

## S4 method for signature 'Exp'
avar_me(distr)

Arguments

rate

numeric. The distribution parameter.

distr

an object of class Exp.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Exp. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Exponential distribution is given by:

f(x; \lambda) = \lambda e^{-\lambda x}, \quad x \geq 0 .

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dexp(), pexp(), qexp(), rexp()

Examples

# -----------------------------------------------------
# Exp Distribution Example
# -----------------------------------------------------

# Create the distribution
rate <- 5
D <- Exp(rate)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 2, 10)) # density function
p(D, c(0.3, 2, 10)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llexp(x, rate)

eexp(x, type = "mle")
eexp(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("exp", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vexp(rate, type = "mle")
vexp(rate, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Fisher Distribution

Description

The Fisher (F) distribution is an absolute continuous probability distribution that arises frequently in the analysis of variance (ANOVA) and in hypothesis testing. It is defined by two degrees of freedom parameters d_1 > 0 and d_2 > 0.

Usage

Fisher(df1 = 1, df2 = 1)

## S4 method for signature 'Fisher,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Fisher,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Fisher,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Fisher,numeric'
r(distr, n)

## S4 method for signature 'Fisher'
mean(x)

## S4 method for signature 'Fisher'
median(x)

## S4 method for signature 'Fisher'
mode(x)

## S4 method for signature 'Fisher'
var(x)

## S4 method for signature 'Fisher'
sd(x)

## S4 method for signature 'Fisher'
skew(x)

## S4 method for signature 'Fisher'
kurt(x)

## S4 method for signature 'Fisher'
entro(x)

llf(x, df1, df2)

## S4 method for signature 'Fisher,numeric'
ll(distr, x)

Arguments

df1, df2

numeric. The distribution degrees of freedom parameters.

distr

an object of class Fisher.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Fisher. For the log-likelihood functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

Details

The probability density function (PDF) of the F-distribution is given by:

f(x; d_1, d_2) = \frac{\sqrt{\left(\frac{d_1 x}{d_1 x + d_2}\right)^{d_1} \left(\frac{d_2}{d_1 x + d_2}\right)^{d_2}}}{x B(d_1/2, d_2/2)}, \quad x > 0 .

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: df(), pf(), qf(), rf()

Examples

# -----------------------------------------------------
# Fisher Distribution Example
# -----------------------------------------------------

# Create the distribution
df1 <- 14 ; df2 <- 20
D <- Fisher(df1, df2)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 2, 10)) # density function
p(D, c(0.3, 2, 10)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llf(x, df1, df2)

Gamma Distribution

Description

The Gamma distribution is an absolute continuous probability distribution with two parameters: shape \alpha > 0 and scale \beta > 0.

Usage

Gam(shape = 1, scale = 1)

## S4 method for signature 'Gam,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Gam,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Gam,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Gam,numeric'
r(distr, n)

## S4 method for signature 'Gam'
mean(x)

## S4 method for signature 'Gam'
median(x)

## S4 method for signature 'Gam'
mode(x)

## S4 method for signature 'Gam'
var(x)

## S4 method for signature 'Gam'
sd(x)

## S4 method for signature 'Gam'
skew(x)

## S4 method for signature 'Gam'
kurt(x)

## S4 method for signature 'Gam'
entro(x)

## S4 method for signature 'Gam'
finf(x)

llgamma(x, shape, scale)

## S4 method for signature 'Gam,numeric'
ll(distr, x)

egamma(x, type = "mle", ...)

## S4 method for signature 'Gam,numeric'
mle(
  distr,
  x,
  par0 = "same",
  method = "L-BFGS-B",
  lower = 1e-05,
  upper = Inf,
  na.rm = FALSE
)

## S4 method for signature 'Gam,numeric'
me(distr, x, na.rm = FALSE)

## S4 method for signature 'Gam,numeric'
same(distr, x, na.rm = FALSE)

vgamma(shape, scale, type = "mle")

## S4 method for signature 'Gam'
avar_mle(distr)

## S4 method for signature 'Gam'
avar_me(distr)

## S4 method for signature 'Gam'
avar_same(distr)

Arguments

shape, scale

numeric. The non-negative distribution parameters.

distr

an object of class Gam.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Gam. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle, me, or same).

...

extra arguments.

par0, method, lower, upper

arguments passed to optim for the mle optimization. See Details.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Gamma distribution is given by:

f(x; \alpha, \beta) = \frac{\beta^{-\alpha} x^{\alpha-1} e^{-x/\beta}}{\Gamma(\alpha)}, \quad x > 0.

The MLE of the gamma distribution parameters is not available in closed form and has to be approximated numerically. This is done with optim(). The optimization can be performed on the shape parameter \alpha\in(0,+\infty). The default method used is the L-BFGS-B method with lower bound 1e-5 and upper bound Inf. The par0 argument can either be a numeric (satisfying ⁠lower <= par0 <= upper⁠) or a character specifying the closed-form estimator to be used as initialization for the algorithm ("me" or "same" - the default value).

Value

Each type of function returns a different type of object:

References

See Also

Functions from the stats package: dgamma(), pgamma(), qgamma(), rgamma()

Examples

# -----------------------------------------------------
# Gamma Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- 3 ; b <- 5
D <- Gam(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 2, 10)) # density function
p(D, c(0.3, 2, 10)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llgamma(x, a, b)

egamma(x, type = "mle")
egamma(x, type = "me")
egamma(x, type = "same")

mle(D, x)
me(D, x)
same(D, x)
e(D, x, type = "mle")

mle("gam", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vgamma(a, b, type = "mle")
vgamma(a, b, type = "me")
vgamma(a, b, type = "same")

avar_mle(D)
avar_me(D)
avar_same(D)

v(D, type = "mle")

Geometric Distribution

Description

The Geometric distribution is a discrete probability distribution that models the number of failures before the first success in a sequence of independent Bernoulli trials, each with success probability 0 < p \leq 1.

Usage

Geom(prob = 0.5)

## S4 method for signature 'Geom,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Geom,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Geom,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Geom,numeric'
r(distr, n)

## S4 method for signature 'Geom'
mean(x)

## S4 method for signature 'Geom'
median(x)

## S4 method for signature 'Geom'
mode(x)

## S4 method for signature 'Geom'
var(x)

## S4 method for signature 'Geom'
sd(x)

## S4 method for signature 'Geom'
skew(x)

## S4 method for signature 'Geom'
kurt(x)

## S4 method for signature 'Geom'
entro(x)

## S4 method for signature 'Geom'
finf(x)

llgeom(x, prob)

## S4 method for signature 'Geom,numeric'
ll(distr, x)

egeom(x, type = "mle", ...)

## S4 method for signature 'Geom,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Geom,numeric'
me(distr, x, na.rm = FALSE)

vgeom(prob, type = "mle")

## S4 method for signature 'Geom'
avar_mle(distr)

## S4 method for signature 'Geom'
avar_me(distr)

Arguments

prob

numeric. Probability of success.

distr

an object of class Geom.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Geom. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability mass function (PMF) of the Geometric distribution is:

P(X = k) = (1 - p)^k p, \quad k \in \mathbb{N}_0.

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dgeom(), pgeom(), qgeom(), rgeom()

Examples

# -----------------------------------------------------
# Geom Distribution Example
# -----------------------------------------------------

# Create the distribution
p <- 0.4
D <- Geom(p)

# ------------------
# dpqr Functions
# ------------------

d(D, 0:4) # density function
p(D, 0:4) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llgeom(x, p)

egeom(x, type = "mle")
egeom(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("geom", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vgeom(p, type = "mle")
vgeom(p, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Laplace Distribution

Description

The Laplace distribution, also known as the double exponential distribution, is a continuous probability distribution that is often used to model data with sharp peaks and heavy tails. It is parameterized by a location parameter \mu and a scale parameter b > 0.

Usage

Laplace(mu = 0, sigma = 1)

dlaplace(x, mu, sigma, log = FALSE)

plaplace(q, mu, sigma, lower.tail = TRUE, log.p = FALSE)

qlaplace(p, mu, sigma, lower.tail = TRUE, log.p = FALSE)

rlaplace(n, mu, sigma)

## S4 method for signature 'Laplace,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Laplace,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Laplace,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Laplace,numeric'
r(distr, n)

## S4 method for signature 'Laplace'
mean(x)

## S4 method for signature 'Laplace'
median(x)

## S4 method for signature 'Laplace'
mode(x)

## S4 method for signature 'Laplace'
var(x)

## S4 method for signature 'Laplace'
sd(x)

## S4 method for signature 'Laplace'
skew(x)

## S4 method for signature 'Laplace'
kurt(x)

## S4 method for signature 'Laplace'
entro(x)

## S4 method for signature 'Laplace'
finf(x)

lllaplace(x, mu, sigma)

## S4 method for signature 'Laplace,numeric'
ll(distr, x)

elaplace(x, type = "mle", ...)

## S4 method for signature 'Laplace,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Laplace,numeric'
me(distr, x, na.rm = FALSE)

vlaplace(mu, sigma, type = "mle")

## S4 method for signature 'Laplace'
avar_mle(distr)

## S4 method for signature 'Laplace'
avar_me(distr)

Arguments

mu, sigma

numeric. The distribution parameters.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Laplace. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

distr

an object of class Laplace.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Laplace distribution is:

f(x; \mu, b) = \frac{1}{2b} \exp\left(-\frac{|x - \mu|}{b}\right) .

Value

Each type of function returns a different type of object:

Examples

# -----------------------------------------------------
# Laplace Distribution Example
# -----------------------------------------------------

# Create the distribution
m <- 3 ; s <- 5
D <- Laplace(m, s)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 2, 10)) # density function
p(D, c(0.3, 2, 10)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

elaplace(x, type = "mle")
elaplace(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("laplace", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vlaplace(m, s, type = "mle")
vlaplace(m, s, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Large Sample Metrics

Description

This function calculates the asymptotic variance - covariance matrix characterizing the large sample (asymptotic) behavior of an estimator. The function evaluates the metrics as a function of a single parameter, keeping the other ones constant. See Details.

Usage

LargeMetrics(D, est, df)

large_metrics(D, prm, est = c("same", "me", "mle"), ...)

Arguments

D

A subclass of Distribution. The distribution family of interest.

est

character. The estimator of interest. Can be a vector.

df

data.frame. a data.frame with columns named "Row", "Col", "Parameter", "Estimator", and "Value".

prm

A list containing three elements (name, pos, val). See Details.

...

extra arguments.

Details

The distribution D is used to specify an initial distribution. The list prm contains details concerning a single parameter that is allowed to change values. The quantity of interest is evaluated as a function of this parameter.

The prm list includes two elements named "name" and "val". The first one specifies the parameter that changes, and the second one is a numeric vector holding the values it takes.

In case the parameter of interest is a vector, a third element named "pos" can be specified to indicate the exact parameter that changes. In the example shown below, the evaluation will be performed for the Dirichlet distributions with shape parameters ⁠(0.5, 1)⁠, ⁠(0.6, 1)⁠, ..., ⁠(2, 1)⁠. Notice that the initial shape parameter value (1) is not utilized in the function.

Value

An object of class LargeMetrics with slots D, est, and df.

See Also

SmallMetrics, PlotMetrics

Examples


# -----------------------------------------------------
# Beta Distribution Example
# -----------------------------------------------------

D <- Beta(shape1 = 1, shape2 = 2)

prm <- list(name = "shape1",
            val = seq(0.5, 2, by = 0.1))

x <- large_metrics(D, prm,
                   est = c("mle", "me", "same"))

plot(x)

# -----------------------------------------------------
# Dirichlet Distribution Example
# -----------------------------------------------------

D <- Dir(alpha = 1:2)

prm <- list(name = "alpha",
            pos = 1,
            val = seq(0.5, 2, by = 0.1))

x <- large_metrics(D, prm,
                   est = c("mle", "me", "same"))

plot(x)

Log-Normal Distribution

Description

The Lognormal distribution is an absolute continuous probability distribution of a random variable whose logarithm is normally distributed. It is defined by parameters \mu and \sigma > 0, which are the mean and standard deviation of the underlying normal distribution.

Usage

Lnorm(meanlog = 0, sdlog = 1)

## S4 method for signature 'Lnorm,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Lnorm,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Lnorm,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Lnorm,numeric'
r(distr, n)

## S4 method for signature 'Lnorm'
mean(x)

## S4 method for signature 'Lnorm'
median(x)

## S4 method for signature 'Lnorm'
mode(x)

## S4 method for signature 'Lnorm'
var(x)

## S4 method for signature 'Lnorm'
sd(x)

## S4 method for signature 'Lnorm'
skew(x)

## S4 method for signature 'Lnorm'
kurt(x)

## S4 method for signature 'Lnorm'
entro(x)

## S4 method for signature 'Lnorm'
finf(x)

lllnorm(x, meanlog, sdlog)

## S4 method for signature 'Lnorm,numeric'
ll(distr, x)

elnorm(x, type = "mle", ...)

## S4 method for signature 'Lnorm,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Lnorm,numeric'
me(distr, x, na.rm = FALSE)

vlnorm(meanlog, sdlog, type = "mle")

## S4 method for signature 'Lnorm'
avar_mle(distr)

## S4 method for signature 'Lnorm'
avar_me(distr)

Arguments

meanlog, sdlog

numeric. The distribution parameters.

distr

an object of class Lnorm.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Lnorm. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Lognormal distribution is:

f(x; \mu, \sigma) = \frac{1}{x \sigma \sqrt{2\pi}} e^{-\frac{(\log x - \mu)^2}{2 \sigma^2}}, \quad x > 0 .

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dlnorm(), plnorm(), qlnorm(), rlnorm()

Examples

# -----------------------------------------------------
# Lnorm Distribution Example
# -----------------------------------------------------

# Create the distribution
m <- 3 ; s <- 5
D <- Lnorm(m, s)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 2, 10)) # density function
p(D, c(0.3, 2, 10)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

elnorm(x, type = "mle")
elnorm(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("lnorm", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vlnorm(m, s, type = "mle")
vlnorm(m, s, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Matrix Wrappers

Description

Simple wrappers of functions from the Matrix package.

Usage

Matrix(...)

nearPD(x)

Arguments

...

extra arguments passed to Matrix::Matrix().

x

matrix

Value

matrix

Multivariate Gamma Distribution

Description

The multivariate gamma distribution is a multivariate absolute continuous probability distribution, defined as the cumulative sum of independent gamma random variables with possibly different shape parameters \alpha_i > 0, i\in\{1, \dots, k\} and the same scale \beta > 0.

Usage

Multigam(shape = 1, scale = 1)

dmultigam(x, shape, scale, log = FALSE)

rmultigam(n, shape, scale)

## S4 method for signature 'Multigam,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Multigam,matrix'
d(distr, x, log = FALSE)

## S4 method for signature 'Multigam,numeric'
r(distr, n)

## S4 method for signature 'Multigam'
mean(x)

## S4 method for signature 'Multigam'
var(x)

## S4 method for signature 'Multigam'
finf(x)

llmultigam(x, shape, scale)

## S4 method for signature 'Multigam,matrix'
ll(distr, x)

emultigam(x, type = "mle", ...)

## S4 method for signature 'Multigam,matrix'
mle(
  distr,
  x,
  par0 = "same",
  method = "L-BFGS-B",
  lower = 1e-05,
  upper = Inf,
  na.rm = FALSE
)

## S4 method for signature 'Multigam,matrix'
me(distr, x, na.rm = FALSE)

## S4 method for signature 'Multigam,matrix'
same(distr, x, na.rm = FALSE)

vmultigam(shape, scale, type = "mle")

## S4 method for signature 'Multigam'
avar_mle(distr)

## S4 method for signature 'Multigam'
avar_me(distr)

## S4 method for signature 'Multigam'
avar_same(distr)

Arguments

shape, scale

numeric. The non-negative distribution parameters.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Multigam. For the log-likelihood and the estimation functions, x is the sample of observations.

log

logical. Should the logarithm of the probability be returned?

n

number of observations. If length(n) > 1, the length is taken to be the number required.

distr

an object of class Multigam.

type

character, case ignored. The estimator type (mle, me, or same).

...

extra arguments.

par0, method, lower, upper

arguments passed to optim for the mle optimization. See Details.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the multivariate gamma distribution is given by:

f(x; \alpha, \beta) = \frac{\beta^{-\alpha_0}}{\prod_{i=1}^k\Gamma(\alpha_i)}, e^{-x_k/\beta} x_1^{\alpha_1-1}\prod_{i=1}^k (x_i - x_{i-1})^{(\alpha_i-1)} \quad x > 0.

The MLE of the multigamma distribution parameters is not available in closed form and has to be approximated numerically. This is done with optim(). Specifically, instead of solving a (k+1) optimization problem w.r.t \alpha, \beta, the optimization can be performed on the shape parameter sum \alpha_0:=\sum_{i=1}^k\alpha \in(0,+\infty)^k. The default method used is the L-BFGS-B method with lower bound 1e-5 and upper bound Inf. The par0 argument can either be a numeric (satisfying ⁠lower <= par0 <= upper⁠) or a character specifying the closed-form estimator to be used as initialization for the algorithm ("me" or "same" - the default value).

Value

Each type of function returns a different type of object:

References

Examples

# -----------------------------------------------------
# Multivariate Gamma Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- c(0.5, 3, 5) ; b <- 5
D <- Multigam(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 2, 10)) # density function

# alternative way to use the function
df <- d(D) ; df(c(0.3, 2, 10)) # df is a function itself

x <- r(D, 100) # random generator function

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llmultigam(x, a, b)

emultigam(x, type = "mle")
emultigam(x, type = "me")
emultigam(x, type = "same")

mle(D, x)
me(D, x)
same(D, x)
e(D, x, type = "mle")

mle("multigam", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vmultigam(a, b, type = "mle")
vmultigam(a, b, type = "me")
vmultigam(a, b, type = "same")

avar_mle(D)
avar_me(D)
avar_same(D)

v(D, type = "mle")

Multinomial Distribution

Description

The multinomial distribution is a discrete probability distribution which models the probability of having x successes in n independent categorical trials with success probability vector p.

Usage

Multinom(size = 1, prob = c(0.5, 0.5))

## S4 method for signature 'Multinom,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Multinom,numeric'
r(distr, n)

## S4 method for signature 'Multinom'
mean(x)

## S4 method for signature 'Multinom'
mode(x)

## S4 method for signature 'Multinom'
var(x)

## S4 method for signature 'Multinom'
entro(x)

## S4 method for signature 'Multinom'
finf(x)

llmultinom(x, size, prob)

## S4 method for signature 'Multinom,matrix'
ll(distr, x)

emultinom(x, type = "mle", ...)

## S4 method for signature 'Multinom,matrix'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Multinom,matrix'
me(distr, x, na.rm = FALSE)

vmultinom(size, prob, type = "mle")

## S4 method for signature 'Multinom'
avar_mle(distr)

## S4 method for signature 'Multinom'
avar_me(distr)

Arguments

size

number of trials (zero or more).

prob

numeric. Probability of success on each trial.

distr

an object of class Multinom.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Multinom. For the log-likelihood and the estimation functions, x is the sample of observations.

log

logical. Should the logarithm of the probability be returned?

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability mass function (PMF) of the Multinomial distribution is:

P(X_1 = x_1, ..., X_k = x_k) = \frac{n!}{x_1! x_2! ... x_k!} \prod_{i=1}^k p_i^{x_i},

subject to \sum_{i=1}^{k} x_i = n .

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dmultinom(), rmultinom()

Examples

# -----------------------------------------------------
# Multinomial Distribution Example
# -----------------------------------------------------

# Create the distribution
N <- 10 ; p <- c(0.1, 0.2, 0.7)
D <- Multinom(N, p)

# ------------------
# dpqr Functions
# ------------------

d(D, c(2, 3, 5)) # density function

# alternative way to use the function
df <- d(D) ; df(c(2, 3, 5)) # df is a function itself

x <- r(D, 100) # random generator function

# ------------------
# Moments
# ------------------

mean(D) # Expectation
mode(D) # Mode
var(D) # Variance
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llmultinom(x, N, p)

emultinom(x, type = "mle")
emultinom(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("multinom", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vmultinom(N, p, type = "mle")
vmultinom(N, p, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Negative Binomial Distribution

Description

The Negative Binomial distribution is a discrete probability distribution that models the number of failures before a specified number of successes occurs in a sequence of independent Bernoulli trials. It is defined by parameters r > 0 (number of successes) and 0 < p \leq 1 (probability of success).

Usage

Nbinom(size = 1, prob = 0.5)

## S4 method for signature 'Nbinom,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Nbinom,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Nbinom,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Nbinom,numeric'
r(distr, n)

## S4 method for signature 'Nbinom'
mean(x)

## S4 method for signature 'Nbinom'
median(x)

## S4 method for signature 'Nbinom'
mode(x)

## S4 method for signature 'Nbinom'
var(x)

## S4 method for signature 'Nbinom'
sd(x)

## S4 method for signature 'Nbinom'
skew(x)

## S4 method for signature 'Nbinom'
kurt(x)

## S4 method for signature 'Nbinom'
entro(x)

## S4 method for signature 'Nbinom'
finf(x)

llnbinom(x, size, prob)

## S4 method for signature 'Nbinom,numeric'
ll(distr, x)

enbinom(x, size, type = "mle", ...)

## S4 method for signature 'Nbinom,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Nbinom,numeric'
me(distr, x, na.rm = FALSE)

vnbinom(size, prob, type = "mle")

## S4 method for signature 'Nbinom'
avar_mle(distr)

## S4 method for signature 'Nbinom'
avar_me(distr)

Arguments

size

number of trials (zero or more).

prob

numeric. Probability of success on each trial.

distr

an object of class Nbinom.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Nbinom. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability mass function (PMF) of the negative binomial distribution is:

P(X = k) = \binom{k + r - 1}{k} (1 - p)^k p^r, \quad k \in \mathbb{N}_0.

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dnbinom(), pnbinom(), qnbinom(), rnbinom()

Examples

# -----------------------------------------------------
# Negative Binomial Distribution Example
# -----------------------------------------------------

# Create the distribution
N <- 10 ; p <- 0.4
D <- Nbinom(N, p)

# ------------------
# dpqr Functions
# ------------------

d(D, 0:4) # density function
p(D, 0:4) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llnbinom(x, N, p)

enbinom(x, N, type = "mle")
enbinom(x, N, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

# ------------------
# Estimator Variance
# ------------------

vnbinom(N, p, type = "mle")
vnbinom(N, p, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Normal Distribution

Description

The Normal or Gaussian distribution, is an absolute continuous probability distribution characterized by two parameters: the mean \mu and the standard deviation \sigma > 0.

Usage

Norm(mean = 0, sd = 1)

## S4 method for signature 'Norm,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Norm,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Norm,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Norm,numeric'
r(distr, n)

## S4 method for signature 'Norm'
mean(x)

## S4 method for signature 'Norm'
median(x)

## S4 method for signature 'Norm'
mode(x)

## S4 method for signature 'Norm'
var(x)

## S4 method for signature 'Norm'
sd(x)

## S4 method for signature 'Norm'
skew(x)

## S4 method for signature 'Norm'
kurt(x)

## S4 method for signature 'Norm'
entro(x)

## S4 method for signature 'Norm'
finf(x)

llnorm(x, mean, sd)

## S4 method for signature 'Norm,numeric'
ll(distr, x)

enorm(x, type = "mle", ...)

## S4 method for signature 'Norm,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Norm,numeric'
me(distr, x, na.rm = FALSE)

vnorm(mean, sd, type = "mle")

## S4 method for signature 'Norm'
avar_mle(distr)

## S4 method for signature 'Norm'
avar_me(distr)

Arguments

mean, sd

numeric. The distribution parameters.

distr

an object of class Norm.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Norm. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Normal distribution is:

f(x; \mu, \sigma) = \frac{1}{\sigma \sqrt{2\pi}} e^{-\frac{1}{2} \left(\frac{x - \mu}{\sigma}\right)^2} .

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dnorm(), pnorm(), qnorm(), rnorm()

Examples

# -----------------------------------------------------
# Normal Distribution Example
# -----------------------------------------------------

# Create the distribution
m <- 3 ; s <- 5
D <- Norm(m, s)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 2, 10)) # density function
p(D, c(0.3, 2, 10)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

enorm(x, type = "mle")
enorm(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("norm", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vnorm(m, s, type = "mle")
vnorm(m, s, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Poisson Distribution

Description

The Poisson distribution is a discrete probability distribution that models the number of events occurring in a fixed interval of time or space, given that the events occur with a constant rate \lambda > 0 and independently of the time since the last event.

Usage

Pois(lambda = 1)

## S4 method for signature 'Pois,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Pois,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Pois,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Pois,numeric'
r(distr, n)

## S4 method for signature 'Pois'
mean(x)

## S4 method for signature 'Pois'
median(x)

## S4 method for signature 'Pois'
mode(x)

## S4 method for signature 'Pois'
var(x)

## S4 method for signature 'Pois'
sd(x)

## S4 method for signature 'Pois'
skew(x)

## S4 method for signature 'Pois'
kurt(x)

## S4 method for signature 'Pois'
entro(x)

## S4 method for signature 'Pois'
finf(x)

llpois(x, lambda)

## S4 method for signature 'Pois,numeric'
ll(distr, x)

epois(x, type = "mle", ...)

## S4 method for signature 'Pois,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Pois,numeric'
me(distr, x, na.rm = FALSE)

vpois(lambda, type = "mle")

## S4 method for signature 'Pois'
avar_mle(distr)

## S4 method for signature 'Pois'
avar_me(distr)

Arguments

lambda

numeric. The distribution parameter.

distr

an object of class Pois.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Pois. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability mass function (PMF) of the Poisson distribution is:

P(X = k) = \frac{\lambda^k e^{-\lambda}}{k!}, \quad k \in \mathbb{N}_0.

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dpois(), ppois(), qpois(), rpois()

Examples

# -----------------------------------------------------
# Pois Distribution Example
# -----------------------------------------------------

# Create the distribution
lambda <- 5
D <- Pois(lambda)

# ------------------
# dpqr Functions
# ------------------

d(D, 0:10) # density function
p(D, 0:10) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llpois(x, lambda)

epois(x, type = "mle")
epois(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("pois", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vpois(lambda, type = "mle")
vpois(lambda, type = "me")

avar_mle(D)
avar_me(D)

v(D, type = "mle")

Small Sample Metrics

Description

This function performs Monte Carlo simulations to estimate the main metrics (bias, variance, and RMSE) characterizing the small (finite) sample behavior of an estimator. The function evaluates the metrics as a function of a single parameter, keeping the other ones constant. See Details.

Usage

SmallMetrics(D, est, df)

small_metrics(
  D,
  prm,
  est = c("same", "me", "mle"),
  obs = c(20, 50, 100),
  sam = 10000,
  seed = 1,
  bar = TRUE,
  ...
)

Arguments

D

A subclass of Distribution. The distribution family of interest.

est

character. The estimator of interest. Can be a vector.

df

data.frame. a data.frame with columns named "Row", "Col", "Parameter", "Estimator", and "Value".

prm

A list containing three elements (name, pos, val). See Details.

obs

numeric. The size of each sample. Can be a vector.

sam

numeric. The number of Monte Carlo samples used to estimate the metrics.

seed

numeric. Passed to set.seed() for reproducibility.

bar

logical. Should a progress bar be printed?

...

extra arguments.

Details

The distribution D is used to specify an initial distribution. The list prm contains details concerning a single parameter that is allowed to change values. The quantity of interest is evaluated as a function of this parameter.

The prm list includes two elements named "name" and "val". The first one specifies the parameter that changes, and the second one is a numeric vector holding the values it takes.

In case the parameter of interest is a vector, a third element named "pos" can be specified to indicate the exact parameter that changes. In the example shown below, the evaluation will be performed for the Dirichlet distributions with shape parameters ⁠(0.5, 1)⁠, ⁠(0.6, 1)⁠, ..., ⁠(2, 1)⁠. Notice that the initial shape parameter value (1) is not utilized in the function.

Value

An object of class SmallMetrics with slots D, est, and df.

See Also

LargeMetrics, PlotMetrics

Examples


# -----------------------------------------------------
# Beta Distribution Example
# -----------------------------------------------------

D <- Beta(shape1 = 1, shape2 = 2)

prm <- list(name = "shape1",
            val = seq(0.5, 2, by = 0.1))

x <- small_metrics(D, prm,
                   est = c("mle", "me", "same"),
                   obs = c(20, 50),
                   sam = 1e2,
                   seed = 1)

plot(x)

# -----------------------------------------------------
# Dirichlet Distribution Example
# -----------------------------------------------------

D <- Dir(alpha = 1:2)

prm <- list(name = "alpha",
            pos = 1,
            val = seq(0.5, 2, by = 0.1))

x <- small_metrics(D, prm,
                   est = c("mle", "me", "same"),
                   obs = c(20, 50),
                   sam = 1e2,
                   seed = 1)

plot(x)

Student Distribution

Description

The Student's t-distribution is a continuous probability distribution used primarily in hypothesis testing and in constructing confidence intervals for small sample sizes. It is defined by one parameter: the degrees of freedom \nu > 0.

Usage

Stud(df = 1)

## S4 method for signature 'Stud,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Stud,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Stud,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Stud,numeric'
r(distr, n)

## S4 method for signature 'Stud'
mean(x)

## S4 method for signature 'Stud'
median(x)

## S4 method for signature 'Stud'
mode(x)

## S4 method for signature 'Stud'
var(x)

## S4 method for signature 'Stud'
sd(x)

## S4 method for signature 'Stud'
skew(x)

## S4 method for signature 'Stud'
kurt(x)

## S4 method for signature 'Stud'
entro(x)

llt(x, df)

## S4 method for signature 'Stud,numeric'
ll(distr, x)

Arguments

df

numeric. The distribution degrees of freedom parameter.

distr

an object of class Stud.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Stud. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

Details

The probability density function (PDF) of the Student's t-distribution is:

f(x; \nu) = \frac{\Gamma\left(\frac{\nu + 1}{2}\right)}{\sqrt{\nu\pi}\ \Gamma\left(\frac{\nu}{2}\right)}\left(1 + \frac{x^2}{\nu}\right)^{-\frac{\nu + 1}{2}} .

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dt(), pt(), qt(), rt()

Examples

# -----------------------------------------------------
# Student Distribution Example
# -----------------------------------------------------

# Create the distribution
df <- 12
D <- Stud(df)

# ------------------
# dpqr Functions
# ------------------

d(D, c(-3, 0, 3)) # density function
p(D, c(-3, 0, 3)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
d1 <- d(D) ; d1(x) # d1 is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llt(x, df)

Uniform Distribution

Description

The Uniform distribution is an absolute continuous probability distribution where all intervals of the same length within the distribution's support are equally probable. It is defined by two parameters: the lower bound a and the upper bound b, with a < b.

Usage

Unif(min = 0, max = 1)

## S4 method for signature 'Unif,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Unif,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Unif,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Unif,numeric'
r(distr, n)

## S4 method for signature 'Unif'
mean(x)

## S4 method for signature 'Unif'
median(x)

## S4 method for signature 'Unif'
mode(x)

## S4 method for signature 'Unif'
var(x)

## S4 method for signature 'Unif'
sd(x)

## S4 method for signature 'Unif'
skew(x)

## S4 method for signature 'Unif'
kurt(x)

## S4 method for signature 'Unif'
entro(x)

llunif(x, min, max)

## S4 method for signature 'Unif,numeric'
ll(distr, x)

eunif(x, type = "mle", ...)

## S4 method for signature 'Unif,numeric'
mle(distr, x, na.rm = FALSE)

## S4 method for signature 'Unif,numeric'
me(distr, x, na.rm = FALSE)

Arguments

min, max

numeric. The distribution parameters.

distr

an object of class Unif.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Unif. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle or me).

...

extra arguments.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Uniform distribution is:

f(x; a, b) = \frac{1}{b - a}, \quad a \le x \le b .

Value

Each type of function returns a different type of object:

See Also

Functions from the stats package: dunif(), punif(), qunif(), runif()

Examples

# -----------------------------------------------------
# Uniform Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- 3 ; b <- 5
D <- Unif(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 0.8, 0.5)) # density function
p(D, c(0.3, 0.8, 0.5)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llunif(x, a, b)

eunif(x, type = "mle")
eunif(x, type = "me")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("unif", x) # the distr argument can be a character

Weibull Distribution

Description

The Weibull distribution is an absolute continuous probability distribution, parameterized by a shape parameter k > 0 and a scale parameter \lambda > 0.

Usage

Weib(shape = 1, scale = 1)

## S4 method for signature 'Weib,numeric'
d(distr, x, log = FALSE)

## S4 method for signature 'Weib,numeric'
p(distr, q, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Weib,numeric'
qn(distr, p, lower.tail = TRUE, log.p = FALSE)

## S4 method for signature 'Weib,numeric'
r(distr, n)

## S4 method for signature 'Weib'
mean(x)

## S4 method for signature 'Weib'
median(x)

## S4 method for signature 'Weib'
mode(x)

## S4 method for signature 'Weib'
var(x)

## S4 method for signature 'Weib'
sd(x)

## S4 method for signature 'Weib'
skew(x)

## S4 method for signature 'Weib'
kurt(x)

## S4 method for signature 'Weib'
entro(x)

llweibull(x, shape, scale)

## S4 method for signature 'Weib,numeric'
ll(distr, x)

eweibull(x, type = "mle", ...)

## S4 method for signature 'Weib,numeric'
mle(
  distr,
  x,
  par0 = "lme",
  method = "L-BFGS-B",
  lower = 1e-05,
  upper = Inf,
  na.rm = FALSE
)

## S4 method for signature 'Weib,numeric'
me(distr, x, par0 = "lme", lower = 0.5, upper = Inf, na.rm = FALSE)

Arguments

shape, scale

numeric. The non-negative distribution parameters.

distr

an object of class Weib.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Weib. For the log-likelihood and the estimation functions, x is the sample of observations.

log, log.p

logical. Should the logarithm of the probability be returned?

q

numeric. Vector of quantiles.

lower.tail

logical. If TRUE (default), probabilities are P(X \leq x), otherwise P(X > x).

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

type

character, case ignored. The estimator type (mle, me or lme).

...

extra arguments.

par0, method, lower, upper

arguments passed to optim for the mle and me optimization. See Details.

na.rm

logical. Should the NA values be removed?

Details

The probability density function (PDF) of the Weibull distribution is:

f(x; k, \lambda) = \frac{k}{\lambda}\left(\frac{x}{\lambda} \right)^{k - 1} \exp\left[-\left(\frac{x}{\lambda}\right)^k\right], \quad x \geq 0 .

For the parameter estimation, both the MLE and the ME cannot be explicitly derived. However, the L-moment estimator (type = "lme") is available, and is used as initialization for the numerical approximation of the MLE and the ME.

The MLE and ME of the Weibull distribution parameters is not available in closed form and has to be approximated numerically. The optimization can be performed on the shape parameter k\in(0,+\infty).

For the MLE, this is done with optim(). The default method used is the L-BFGS-B method with lower bound 1e-5 and upper bound Inf. The par0 argument can either be a numeric (satisfying ⁠lower <= par0 <= upper⁠) or a character specifying the closed-form estimator to be used as initialization for the algorithm ("lme" - the default value).

For the ME, this is done with uniroot(). Again, the par0 argument can either be a numeric (satisfying ⁠lower <= par0 <= upper⁠) or a character specifying the closed-form estimator to be used as initialization for the algorithm ("mle" or "lme" - the default value). The lower and upper bounds are set by default to 0.5 and Inf, respectively. Note that the ME equations involve the \Gamma(1 + 1 \ k), which can become unreliable for small values of k, hence the 0.5 lower bound. Specifying a lower bound below 0.5 will result in a warning and be ignored.

Value

Each type of function returns a different type of object:

References

Kim, H. M., Jang, Y. H., Arnold, B. C., & Zhao, J. (2024). New efficient estimators for the Weibull distribution. Communications in Statistics-Theory and Methods, 53(13), 4576-4601.

See Also

Functions from the stats package: dweibull(), pweibull(), qweibull(), rweibull()

Examples

# -----------------------------------------------------
# Weibull Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- 3 ; b <- 5
D <- Weib(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 2, 10)) # density function
p(D, c(0.3, 2, 10)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
median(D) # Median
mode(D) # Mode
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llweibull(x, a, b)

eweibull(x, type = "mle")
eweibull(x, type = "me")
eweibull(x, type = "lme")

mle(D, x)
me(D, x)
e(D, x, type = "mle")

mle("weib", x) # the distr argument can be a character

Turn an array to a data.frame

Description

This function turns an array to a data.frame. It is used by the small_metrics() and large_metrics() functions.

Usage

array_to_df(x)

Arguments

x

array.

Value

data.frame.

Distributional Calculus

Description

Arithmetic operators and functions for probability distribution objects. These methods define how standard operations like +, -, *, and / behave when applied to random variables, returning the resulting distribution based on known properties of common distribution families.

Usage

## S4 method for signature 'Norm,Norm'
e1 + e2

## S4 method for signature 'numeric,Norm'
e1 + e2

## S4 method for signature 'Norm,numeric'
e1 + e2

## S4 method for signature 'Norm,Norm'
e1 - e2

## S4 method for signature 'numeric,Norm'
e1 - e2

## S4 method for signature 'Norm,numeric'
e1 - e2

## S4 method for signature 'numeric,Norm'
e1 * e2

## S4 method for signature 'Norm,numeric'
e1 * e2

## S4 method for signature 'Norm,numeric'
e1 / e2

## S4 method for signature 'Norm,logical'
sum(x, ..., na.rm = FALSE)

## S4 method for signature 'Norm'
exp(x)

Arguments

x, e1, e2

objects of subclass Distribution.

...

extra arguments.

na.rm

logical. Should missing values be removed?

Value

All calculations return Distribution objects (specifically, objects of a class that is a subclass of Distribution), according to the property at hand.

Examples

# -----------------------------------------------------
# Distribution Calculus Example
# -----------------------------------------------------

# Normal location - scale transformation
x <- Norm(2, 3)
y <- 3 * x + 1 # Norm(7, 9)

# Addition of two independent Normal random variables
x1 <- Norm(1, 3)
x2 <- Norm(2, 4)
x3 <- x1 + x2 # Norm(3, 5)

Check the Data

Description

This function checks that the data argument supplied by the user for parameter estimation are of the appropriate type.

Usage

check_data(x, na.rm = FALSE)

Arguments

x

an object to be checked. Should be vector, matrix, or array.

na.rm

logical. Should the NA values be removed?

Value

The object x, possibly without NA values if x is a vector containing NA values and na.rm = TRUE.

Check Optim Arguments

Description

Checks that the arguments supplied by the user are appropriate to be passed to optim(). Used internally in parameter estimation.

Usage

check_optim(par0, method, lower, upper, choices = NULL, len = 1)

Arguments

par0

numeric or character. If numeric, it is passed to optim as the initial estimation, i.e. the par argument. If character, the corresponding estimation method is called and the result is passed to optim instead.

method, lower, upper

arguments passed to optim.

choices

character. A vector of available estimation methods for the par0 argument

len

integer. The appropriate length of the lower and upper argument, as well as par if it is numeric.

Value

par0, possibly altered via match.arg() if it is a character.

Distribution Handling Helpers

Description

This set of functions help handle the distribution classes. See Details.

Usage

get_moment_methods(x)

get_class_abbr(distr)

get_distr_class(distr)

s4_to_list(distr)

get_params(distr, list = TRUE)

get_unknown_params(distr, list = TRUE)

update_params(distr, prm, i)

Arguments

x, distr

an object of class Distribution.

list

logical. Should a list be returned? If FALSE, the return object is wrapped in unlist().

prm, i

A list containing three elements (name, pos, val) and the i-th element of val to be updated as the new parameter. See small_metrics().

Value

Depends on the function. See Details.

Functions

See Also

small_metrics(), large_metrics()

Distribution S4 Classes

Description

A collection of S4 classes that provide a flexible and structured way to work with probability distributions.

Usage

d(distr, x, ...)

p(distr, q, ...)

qn(distr, p, ...)

r(distr, n, ...)

Arguments

distr

an object of class Distribution or one of its subclasses.

x

For the density function, x is a numeric vector of quantiles. For the moments functions, x is an object of class Distribution or one of its subclasses. For the log-likelihood and the estimation functions, x is the sample of observations.

...

extra arguments.

q

numeric. Vector of quantiles.

p

numeric. Vector of probabilities.

n

number of observations. If length(n) > 1, the length is taken to be the number required.

Details

These S4 generic methods can work both as functions and as functionals (functions that return functions). The available distribution families are coded as S4 classes, specifically subclasses of the Distribution superclass. The methods can be used in two ways:

Option 1: If both the distr argument and x or n are supplied, then the function is evaluated directly, as usual.

Option 2: If only the distr argument is supplied, the method returns a function that takes as input the missing argument x or n, allowing the user to work with the function object itself. See examples.

Looking for a specific distribution family? This help page is general. Use the help page of each distribution to see the available methods for the class, details, and examples. Check the See Also section.

Value

Each type of function returns a different type of object:

Functions

See Also

moments, loglikelihood, estimation, Bern, Beta, Binom, Cat, Cauchy, Chisq, Dir, Exp, Fisher, Gam, Geom, Laplace, Lnorm, Multigam, Multinom, Nbinom, Norm, Pois, Stud, Unif, Weib

Examples

# -----------------------------------------------------
# Beta Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- 3
b <- 5
D <- Beta(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 0.8, 0.5)) # density function
p(D, c(0.3, 0.8, 0.5)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llbeta(x, a, b)

ebeta(x, type = "mle")
ebeta(x, type = "me")
ebeta(x, type = "same")

mle(D, x)
me(D, x)
same(D, x)
e(D, x, type = "mle")

mle("beta", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vbeta(a, b, type = "mle")
vbeta(a, b, type = "me")
vbeta(a, b, type = "same")

avar_mle(D)
avar_me(D)
avar_same(D)

v(D, type = "mle")

Parameter Estimation

Description

This set of functions estimates the parameters of a random sample according to a specified family of distributions. See details.

Usage

e(distr, x, type = "mle", ...)

mle(distr, x, ...)

## S4 method for signature 'character,ANY'
mle(distr, x, ...)

me(distr, x, ...)

## S4 method for signature 'character,ANY'
me(distr, x, ...)

same(distr, x, ...)

## S4 method for signature 'character,ANY'
same(distr, x, ...)

Arguments

distr

A Distribution object or a character. The distribution family assumed.

x

numeric. A sample under estimation.

type

character, case ignored. The estimator type.

...

extra arguments.

Details

The package covers three major estimation methods: maximum likelihood estimation (MLE), moment estimation (ME), and score-adjusted estimation (SAME).

In order to perform parameter estimation, a new ⁠e<name>()⁠ member is added to the d(), p(), q(), r() family, following the standard stats name convention. These functions take two arguments, the observations x (an atomic vector for univariate or a matrix for multivariate distributions) and the type of estimation method to use (a character with possible values "mle", "me", and "same".)

Point estimation functions are available in two versions, the distribution specific one, e.g. ebeta(), and the S4 generic ones, namely mle(), me(), and same(). A general function called e() is also implemented, covering all distributions and estimators.

Value

list. The estimator of the unknown parameters. Note that in distribution families like the binomial, multinomial, and negative binomial, the size is not returned, since it is considered known.

Functions

References

General Textbooks

Beta and gamma distribution families

See Also

mle, me, same

Examples

# -----------------------------------------------------
# Beta Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- 3
b <- 5
D <- Beta(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 0.8, 0.5)) # density function
p(D, c(0.3, 0.8, 0.5)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llbeta(x, a, b)

ebeta(x, type = "mle")
ebeta(x, type = "me")
ebeta(x, type = "same")

mle(D, x)
me(D, x)
same(D, x)
e(D, x, type = "mle")

mle("beta", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vbeta(a, b, type = "mle")
vbeta(a, b, type = "me")
vbeta(a, b, type = "same")

avar_mle(D)
avar_me(D)
avar_same(D)

v(D, type = "mle")

Forward Difference

Description

Calculates the forward difference of a vector or matrix.

Usage

fd(x)

Arguments

x

numeric vector or matrix.

Details

The function is used internally in the Multigam distribution.

Value

an atomic vector or matrix of the same dimensions as x.

Distribution Functionals

Description

A collection of S4 classes that provide a flexible and structured way to work with probability distributions.

Usage

## S4 method for signature 'Distribution,missing'
d(distr, x, ...)

## S4 method for signature 'Distribution,missing'
p(distr, q, ...)

## S4 method for signature 'Distribution,missing'
qn(distr, p, ...)

## S4 method for signature 'Distribution,missing'
r(distr, n, ...)

## S4 method for signature 'Distribution,missing'
ll(distr, x, ...)

## S4 method for signature 'Distribution,missing'
mle(distr, x, ...)

## S4 method for signature 'Distribution,missing'
me(distr, x, ...)

## S4 method for signature 'Distribution,missing'
same(distr, x, ...)

Arguments

distr

a Distribution object.

x, q, p, n

missing. Arguments not supplied.

...

extra arguments.

Details

When x, q, p, or n are missing, the methods return a function that takes as input the missing argument, allowing the user to work with the function object itself. See examples.

Value

When supplied with one argument, the d(), p(), q(), r() ll() functions return the density, cumulative probability, quantile, random sample generator, and log-likelihood functions, respectively.

See Also

moments, loglikelihood, estimation, Bern, Beta, Binom, Cat, Cauchy, Chisq, Dir, Exp, Fisher, Gam, Geom, Laplace, Lnorm, Multigam, Multinom, Nbinom, Norm, Pois, Stud, Unif, Weib

Examples

# -----------------------------------------------------
# Beta Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- 3
b <- 5
D <- Beta(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 0.8, 0.5)) # density function
p(D, c(0.3, 0.8, 0.5)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llbeta(x, a, b)

ebeta(x, type = "mle")
ebeta(x, type = "me")
ebeta(x, type = "same")

mle(D, x)
me(D, x)
same(D, x)
e(D, x, type = "mle")

mle("beta", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vbeta(a, b, type = "mle")
vbeta(a, b, type = "me")
vbeta(a, b, type = "same")

avar_mle(D)
avar_me(D)
avar_same(D)

v(D, type = "mle")

Inverse Digamma Function

Description

The inverse of the digamma function, i.e. the derivative of the log-gamma function.

Usage

idigamma(x, ...)

Arguments

x

numeric. The point to evaluate the function.

...

extra arguments passed to optim().

Details

The idigamma() function implements the inverse of the digamma function \psi. It is a numerical approximation based on the Brent optimization algorithm. Specifically, idigamma() makes a call to optim() in order to solve the equation \psi(x) = y; more accurately, to find the minimum of f(x) = \log\Gamma(x) - xy, whose derivative is f'(x) = \psi(x) - y. The optimization is restricted within the tight bounds derived by Batir (2017). The function is vectorized.

Value

numeric. The evaluated function.

References

Necdet Batir (2017), INEQUALITIES FOR THE INVERSES OF THE POLYGAMMA FUNCTIONS https://arxiv.org/pdf/1705.06547

Oikonomidis, I. & Trevezas, S. (2023), Moment-Type Estimators for the Dirichlet and the Multivariate Gamma Distributions, arXiv, https://arxiv.org/abs/2311.15025

See Also

optim()

Examples


idigamma(2)

2x2 Inverse Matrix

Description

Calculates the inverse of a 2x2 matrix.

Usage

inv2x2(x)

Arguments

x

A 2x2 matrix.

Value

A 2x2 matrix, the inverse of x

Is it?

Description

A set of functions that check whether an object has the desired characteristics.

Usage

is_whole(x, tol = .Machine$double.eps^0.5)

is_atvec(x)

is_numatvec(x)

is_nummat(x)

is_numarray(x)

is_symmetric(x)

is_pd(x)

is_pos(x)

is_integer(x)

is_natural(x)

Arguments

x

numeric vector or matrix.

tol

numeric. The tolerance for a numeric to be considered a whole number.

Value

logical. TRUE or FALSE, depending on whether the object satisfies the checks that define the characteristic.

Functions

Log-Likelihood Function

Description

This function calculates the log-likelihood of an independent and identically distributed (iid) sample from a distribution. See Details.

Usage

ll(distr, x, ...)

Arguments

distr

A Distribution object

x

numeric. A sample under estimation.

...

extra arguments.

Details

The log-likelihood functions are provided in two forms: the ⁠ll<name>⁠ distribution-specific version that follows the stats package conventions, and the S4 generic ll. Examples for the ⁠ll<name>⁠ version are included in the distribution-specific help pages, e.g. ?Beta (all distributions can be found in the See Also section of the Distributions help page).

As with the d(), p(), q(), r() methods, ll() can be supplied only with distr to return the log-likelihood function (i.e. it can be used as a functional), or with both distr and x to be evaluated directly.

In some distribution families like beta and gamma, the MLE cannot be explicitly derived and numerical optimization algorithms have to be employed. Even in “good" scenarios, with plenty of observations and a smooth optimization function, extra care should be taken to ensure a fast and right convergence if possible. Two important steps are taken in package in this direction:

  1. The log-likelihood function is analytically calculated for each distribution family, so that constant terms with respect to the parameters can be removed, leaving only the sufficient statistics as a requirement for the function evaluation.

  2. Multidimensional problems are reduced to unidimensional ones by utilizing the score equations.

The resulting function that is inserted in the optimization algorithm is called lloptim(), and is not to be confused with the actual log-likelihood function ll(). The corresponding derivative is called dlloptim(). These functions are used internally and are not exported.

Therefore, whenever numerical computation of the MLE is required, optim() is called to optimize lloptim(), using the ME or SAME as the starting point (user's choice), and the L-BFGS-U optimization algorithm, with lower and upper limits defined by default as the parameter space boundary. Illustrative examples can be found in the package vignette.

Value

If only the distr argument is supplied, ll() returns a function. If both distr and x are supplied, ll() returns a numeric, the value of the log-likelihood function.

See Also

distributions, moments, estimation

Examples

# -----------------------------------------------------
# Beta Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- 3
b <- 5
D <- Beta(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 0.8, 0.5)) # density function
p(D, c(0.3, 0.8, 0.5)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llbeta(x, a, b)

ebeta(x, type = "mle")
ebeta(x, type = "me")
ebeta(x, type = "same")

mle(D, x)
me(D, x)
same(D, x)
e(D, x, type = "mle")

mle("beta", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vbeta(a, b, type = "mle")
vbeta(a, b, type = "me")
vbeta(a, b, type = "same")

avar_mle(D)
avar_me(D)
avar_same(D)

v(D, type = "mle")

Moments - Parametric Quantities of Interest

Description

A set of functions that calculate the theoretical moments (expectation, variance, skewness, excess kurtosis) and other important parametric functions (median, mode, entropy, Fisher information) of a distribution.

Usage

moments(x)

mean(x, ...)

median(x, na.rm = FALSE, ...)

mode(x)

var(x, y = NULL, na.rm = FALSE, use)

sd(x, na.rm = FALSE)

skew(x, ...)

kurt(x, ...)

entro(x, ...)

finf(x, ...)

Arguments

x

a Distribution object.

...

extra arguments.

y, use, na.rm

arguments in mean and var standard methods from the stats package not used here.

Details

Given a distribution, these functions calculate the theoretical moments and other parametric quantities of interest. Some distribution-function combinations are not available; for example, the sd() function is available only for univariate distributions.

The moments() function automatically finds the available methods for a given distribution and results all of the results in a list.

Technical Note: The argument of the moment functions does not follow the naming convention of the package, i.e. the Distribution object is names x rather than distr. This is due to the fact that most of the generics are already defined in the stats package (mean, median, mode, var, sd), therefore the first argument was already named x and could not change.

Value

Numeric, either vector or matrix depending on the moment and the distribution. The moments() function returns a list with all the available methods.

Functions

See Also

distributions, loglikelihood, estimation

Examples

# -----------------------------------------------------
# Beta Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- 3
b <- 5
D <- Beta(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 0.8, 0.5)) # density function
p(D, c(0.3, 0.8, 0.5)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llbeta(x, a, b)

ebeta(x, type = "mle")
ebeta(x, type = "me")
ebeta(x, type = "same")

mle(D, x)
me(D, x)
same(D, x)
e(D, x, type = "mle")

mle("beta", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vbeta(a, b, type = "mle")
vbeta(a, b, type = "me")
vbeta(a, b, type = "same")

avar_mle(D)
avar_me(D)
avar_same(D)

v(D, type = "mle")

Plot Metrics

Description

This function provides an easy way to illustrate objects of class SmallMetrics and LargeMetrics, using the ggplot2 package. See details.

Usage

plot(x, y, ...)

## S4 method for signature 'SmallMetrics,missing'
plot(
  x,
  y = NULL,
  colors = NULL,
  title = NULL,
  save = FALSE,
  path = NULL,
  name = "myplot.pdf",
  width = 15,
  height = 8
)

## S4 method for signature 'LargeMetrics,missing'
plot(
  x,
  y = NULL,
  colors = NULL,
  title = NULL,
  save = FALSE,
  path = NULL,
  name = "myplot.pdf",
  width = 15,
  height = 8
)

Arguments

x

An object of class SmallMetrics or LargeMetrics.

y

NULL.

...

extra arguments.

colors

character. The colors to be used in the plot.

title

character. The plot title.

save

logical. Should the plot be saved?

path

A path to the directory in which the plot will be saved.

name

character. The name of the output pdf file.

width

numeric. The plot width in inches.

height

numeric. The plot height in inches.

Details

Objects of class SmallMetrics and LargeMetrics are returned by the small_metrics() and large_metrics() functions, respectively.

For the SmallMetrics, a grid of line charts is created for each metric and sample size. For the LargeMetrics, a grid of line charts is created for each element of the asymptotic variance - covariance matrix.

Each estimator is plotted with a different color and line type. The plot can be saved in pdf format.

Value

The plot is returned invisibly in the form of a ggplot object.

See Also

SmallMetrics, LargeMetrics

Examples


# -----------------------------------------------------
# Beta Distribution Example
# -----------------------------------------------------

D <- Beta(shape1 = 1, shape2 = 2)

prm <- list(name = "shape1",
            val = seq(0.5, 2, by = 0.1))

x <- small_metrics(D, prm,
                   est = c("mle", "me", "same"),
                   obs = c(20, 50),
                   sam = 1e2,
                   seed = 1)

plot(x)

# -----------------------------------------------------
# Dirichlet Distribution Example
# -----------------------------------------------------

D <- Dir(alpha = 1:2)

prm <- list(name = "alpha",
            pos = 1,
            val = seq(0.5, 2, by = 0.1))

x <- small_metrics(D, prm,
                   est = c("mle", "me", "same"),
                   obs = c(20, 50),
                   sam = 1e2,
                   seed = 1)

plot(x)

Progress Bar

Description

Create a progress bar to be used with for loops that can possibly take a lot of time.

Usage

progress_bar(iter, total, start, message = NULL, width = 20)

format_hms(seconds)

Arguments

iter

integer. The current iteration step of the for loop.

total

integer. The total number of iterations.

start

POSIXct. The start time, as returned by Sys.time().

message

character. A message appearing before the progress bar.

width

integer. The length of the progress bar.

seconds

integer. Seconds to be converted into hh:mm:ss format.

Value

format_hms() returns a character in the hh:mm:ss format. progress_bar() prints the progress bar on the console, calling cat(), therefore as returns an invisible NULL.

Sequence Functions for Matrices

Description

This set of functions extent the seq_along() functions for matrix objects.

Usage

seqcol(x)

seqrow(x)

Arguments

x

matrix.

Value

A sequence of integers from 1 to the number of rows or columns of the matrix.

Indexing Functions

Description

A set of functions that allow to index a matrix or array. These functions are used internally when the dimension length of an object can vary.

Usage

set1of1(x, i)

set1of2(x, i)

set1of3(x, i)

set2of3(x, i)

Arguments

x

atomic vector, matrix, or array. An object to be indexed.

i

integer. The index.

Value

A vector or matrix, subset of the original object.

Statistical Functions

Description

A set of statistics that extend the ones made available in the stats package.

Usage

bvar(x)

bsd(x)

rowVar(x)

colVar(x)

## S4 method for signature 'numeric'
skew(x)

## S4 method for signature 'numeric'
kurt(x)

Arguments

x

numeric for bvar() and bsd(), matrix for rowVar() and colVar().

Value

bvar() and bsd() return a single numeric, rowVar() and colVar() return a numeric vector.

Functions

Estimation and Variance Tests

Description

This set of functions employs Monte Carlo simulations to check the consistency of the estimators (i.e. that the estimators are coded correctly) and their asymptotic normality (i.e. that their asymptotic variance is coded correctly).

Usage

test_consistency(est, D0, n = 10000, seed = 1, ...)

test_avar(est, D0, n = 10000, m = 1000, seed = 1, bar = FALSE, ...)

Arguments

est

character. The estimator to be tested.

D0

An object of class Distribution.

n

integer. The sample size to be simulated.

seed

integer. Passed to set.seed().

...

extra arguments passed to the estimator.

m

integer. The number of samples to be simulated.

bar

logical. Should a progress bar be printed?

Value

A list with the simulation and the expected results so that they can be compared in tests.

Examples

## Not run: 
D <- Beta(2, 3)
test1 <- test_consistency("me", D)
test2 <- test_avar("mle", D)

## End(Not run)

Estimator Variance

Description

These functions calculate the variance (or variance - covariance matrix in the multidimensional case) of an estimator, given a specified family of distributions and the true parameter values.

Usage

v(distr, type, ...)

avar_mle(distr, ...)

avar_me(distr, ...)

avar_same(distr, ...)

Arguments

distr

A Distribution object.

type

character, case ignored. The estimator type.

...

extra arguments.

Value

numeric, or matrix for multidimensional cases.

Functions

References

General Textbooks

Beta and gamma distribution families

See Also

avar_mle, avar_me, avar_same

Examples

# -----------------------------------------------------
# Beta Distribution Example
# -----------------------------------------------------

# Create the distribution
a <- 3
b <- 5
D <- Beta(a, b)

# ------------------
# dpqr Functions
# ------------------

d(D, c(0.3, 0.8, 0.5)) # density function
p(D, c(0.3, 0.8, 0.5)) # distribution function
qn(D, c(0.4, 0.8)) # inverse distribution function
x <- r(D, 100) # random generator function

# alternative way to use the function
df <- d(D) ; df(x) # df is a function itself

# ------------------
# Moments
# ------------------

mean(D) # Expectation
var(D) # Variance
sd(D) # Standard Deviation
skew(D) # Skewness
kurt(D) # Excess Kurtosis
entro(D) # Entropy
finf(D) # Fisher Information Matrix

# List of all available moments
mom <- moments(D)
mom$mean # expectation

# ------------------
# Point Estimation
# ------------------

ll(D, x)
llbeta(x, a, b)

ebeta(x, type = "mle")
ebeta(x, type = "me")
ebeta(x, type = "same")

mle(D, x)
me(D, x)
same(D, x)
e(D, x, type = "mle")

mle("beta", x) # the distr argument can be a character

# ------------------
# Estimator Variance
# ------------------

vbeta(a, b, type = "mle")
vbeta(a, b, type = "me")
vbeta(a, b, type = "same")

avar_mle(D)
avar_me(D)
avar_same(D)

v(D, type = "mle")