View source: R/TruncatedNormal.R

TruncatedNormal | R Documentation |

Class and methods for left-, right-, and interval-truncated normal distributions using the workflow from the distributions3 package.

```
TruncatedNormal(mu = 0, sigma = 1, left = -Inf, right = Inf)
```

`mu` |
numeric. The location parameter of the underlying |

`sigma` |
numeric. The scale parameter (standard deviation) of
the underlying |

`left` |
numeric. The left truncation point. Can be any real number,
defaults to |

`right` |
numeric. The right truncation point. Can be any real number,
defaults to |

The constructor function `TruncatedNormal`

sets up a distribution
object, representing the truncated normal probability distribution by the
corresponding parameters: the latent mean `mu`

= `\mu`

and
latent standard deviation `sigma`

= `\sigma`

(i.e., the parameters
of the underlying *untruncated* normal variable), the `left`

truncation
point (with `-Inf`

corresponding to untruncated), and the
`right`

truncation point (with `Inf`

corresponding to untruncated).

The truncated normal distribution has probability density function (PDF):

`f(x) = 1/\sigma \phi((x - \mu)/\sigma) / (\Phi((right - \mu)/\sigma) - \Phi((left - \mu)/\sigma))`

for `left \le x \le right`

, and 0 otherwise,
where `\Phi`

and `\phi`

are the cumulative distribution function
and probability density function of the standard normal distribution
respectively.

All parameters can also be vectors, so that it is possible to define a vector of truncated normal distributions with potentially different parameters. All parameters need to have the same length or must be scalars (i.e., of length 1) which are then recycled to the length of the other parameters.

For the `TruncatedNormal`

distribution objects there is a wide range
of standard methods available to the generics provided in the distributions3
package: `pdf`

and `log_pdf`

for the (log-)density (PDF), `cdf`

for the probability
from the cumulative distribution function (CDF), `quantile`

for quantiles,
`random`

for simulating random variables,
`crps`

for the continuous ranked probability score
(CRPS), and `support`

for the support interval
(minimum and maximum). Internally, these methods rely on the usual d/p/q/r
functions provided for the truncated normal distributions in the crch
package, see `dtnorm`

, and the `crps_tnorm`

function from the scoringRules package.
The methods `is_discrete`

and `is_continuous`

can be used to query whether the distributions are discrete on the entire support
(always `FALSE`

) or continuous on the entire support (always `TRUE`

).

See the examples below for an illustration of the workflow for the class and methods.

A `TruncatedNormal`

distribution object.

`dtnorm`

, `Normal`

, `CensoredNormal`

,
`TruncatedLogistic`

, `TruncatedStudentsT`

```
## package and random seed
library("distributions3")
set.seed(6020)
## three truncated normal distributions:
## - untruncated standard normal
## - left-truncated at zero with latent mu = 1 and sigma = 1
## - interval-truncated in [0, 5] with latent mu = 1 and sigma = 2
X <- TruncatedNormal(
mu = c( 0, 1, 1),
sigma = c( 1, 1, 2),
left = c(-Inf, 0, 0),
right = c( Inf, Inf, 5)
)
X
## compute mean and variance of the truncated distribution
mean(X)
variance(X)
## higher moments (skewness, kurtosis) are not implemented yet
## support interval (minimum and maximum)
support(X)
## simulate random variables
random(X, 5)
## histograms of 1,000 simulated observations
x <- random(X, 1000)
hist(x[1, ], main = "untruncated")
hist(x[2, ], main = "left-truncated at zero")
hist(x[3, ], main = "interval-truncated in [0, 5]")
## probability density function (PDF) and log-density (or log-likelihood)
x <- c(0, 0, 1)
pdf(X, x)
pdf(X, x, log = TRUE)
log_pdf(X, x)
## cumulative distribution function (CDF)
cdf(X, x)
## quantiles
quantile(X, 0.5)
## cdf() and quantile() are inverses
cdf(X, quantile(X, 0.5))
quantile(X, cdf(X, 1))
## all methods above can either be applied elementwise or for
## all combinations of X and x, if length(X) = length(x),
## also the result can be assured to be a matrix via drop = FALSE
p <- c(0.05, 0.5, 0.95)
quantile(X, p, elementwise = FALSE)
quantile(X, p, elementwise = TRUE)
quantile(X, p, elementwise = TRUE, drop = FALSE)
## compare theoretical and empirical mean from 1,000 simulated observations
cbind(
"theoretical" = mean(X),
"empirical" = rowMeans(random(X, 1000))
)
## evaluate continuous ranked probability score (CRPS) using scoringRules
library("scoringRules")
crps(X, x)
```

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.