truncatedstudentst

Create a Truncated Student’s T Distribution

Description

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

Usage

TruncatedStudentsT(df, location = 0, scale = 1, left = -Inf, right = Inf)

Arguments

`df`	numeric. The degrees of freedom of the underlying untruncated t distribution. Can be any positive number, with `df = Inf` corresponding to the normal distribution.
`location`	numeric. The location parameter of the underlying untruncated t distribution, typically written \(\mu\) in textbooks. Can be any real number, defaults to `0`.
`scale`	numeric. The scale parameter (standard deviation) of the underlying untruncated t distribution, typically written \(\sigma\) in textbooks. Can be any positive number, defaults to `1`.
`left`	numeric. The left truncation point. Can be any real number, defaults to `-Inf` (untruncated). If set to a finite value, the distribution has a point mass at `left` whose probability corresponds to the cumulative probability function of the untruncated t distribution at this point.
`right`	numeric. The right truncation point. Can be any real number, defaults to `Inf` (untruncated). If set to a finite value, the distribution has a point mass at `right` whose probability corresponds to 1 minus the cumulative probability function of the untruncated t distribution at this point.

Details

The constructor function TruncatedStudentsT sets up a distribution object, representing the truncated t probability distribution by the corresponding parameters: the degrees of freedom df, the latent mean location = \(\mu\) and latent scale parameter scale = \(\sigma\) (i.e., the parameters of the underlying untruncated t variable), the left truncation point (with -Inf corresponding to untruncated), and the right truncation point (with Inf corresponding to untruncated).

The truncated t distribution has probability density function (PDF) \(f(x)\):

\(f(x) = 1/\sigma \tau((x - \mu)/\sigma) / (T((right - \mu)/\sigma) - T((left - \mu)/\sigma))\)

for \(left \le x \le right\), and 0 otherwise, where \(T\) and \(\tau\) are the cumulative distribution function and probability density function of the standard t distribution with df degrees of freedom, respectively.

All parameters can also be vectors, so that it is possible to define a vector of truncated t 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 TruncatedStudentsT 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 t distributions in the crch package, see dtt, and the crps_tt 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.

Value

A TruncatedStudentsT distribution object.

Examples

library("crch")


## package and random seed
library("distributions3")
set.seed(6020)

## three truncated t distributions:
## - untruncated standard t with 5 degrees of freedom
## - left-truncated at zero with 5 df, latent location = 1 and scale = 1
## - interval-truncated in [0, 5] with 5 df, latent location = 2 and scale = 2
X <- TruncatedStudentsT(
  df       = c(   5,   5, 5),
  location = c(   0,   1, 2),
  scale    = c(   1,   1, 2),
  left     = c(-Inf,   0, 0),
  right    = c( Inf, Inf, 5)
)

X

[1] "TruncatedStudentsT distribution (df = 5, location = 0, scale = 1, left = -Inf, right = Inf)"
[2] "TruncatedStudentsT distribution (df = 5, location = 1, scale = 1, left =    0, right = Inf)"
[3] "TruncatedStudentsT distribution (df = 5, location = 2, scale = 2, left =    0, right =   5)"

## compute mean of the truncated distribution
mean(X)

[1] 0.000000 1.402643 2.287847

## higher moments (variance, skewness, kurtosis) are not implemented yet

## support interval (minimum and maximum)
support(X)

      min max
[1,] -Inf Inf
[2,]    0 Inf
[3,]    0   5

## simulate random variables
random(X, 5)

            r_1       r_2        r_3         r_4         r_5
[1,] -0.3618879 0.4694046 -0.6565922 -0.06169882 -2.18313389
[2,]  0.9166752 1.8390221  1.8795242  0.88274478  0.02392676
[3,]  2.9245453 0.6966685  0.5923259  1.49145953  1.00217689

## 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)

[1] 0.3796067 0.2684288 0.2272668

pdf(X, x, log = TRUE)

[1] -0.9686196 -1.3151695 -1.4816304

log_pdf(X, x)

[1] -0.9686196 -1.3151695 -1.4816304

## cumulative distribution function (CDF)
cdf(X, x)

[1] 0.5000000 0.0000000 0.1906476

## quantiles
quantile(X, 0.5)

[1] 0.000000 1.242002 2.223569

## cdf() and quantile() are inverses (except at truncation points)
cdf(X, quantile(X, 0.5))

[1] 0.5 0.5 0.5

quantile(X, cdf(X, 1))

[1] 1 1 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)

         q_0.05    q_0.5   q_0.95
[1,] -2.0150484 0.000000 2.015048
[2,]  0.1713748 1.242002 3.172937
[3,]  0.3048628 2.223569 4.503390

quantile(X, p, elementwise = TRUE)

[1] -2.015048  1.242002  4.503390

quantile(X, p, elementwise = TRUE, drop = FALSE)

      quantile
[1,] -2.015048
[2,]  1.242002
[3,]  4.503390

## compare theoretical and empirical mean from 1,000 simulated observations
cbind(
  "theoretical" = mean(X),
  "empirical" = rowMeans(random(X, 1000))
)

     theoretical   empirical
[1,]    0.000000 -0.02414368
[2,]    1.402643  1.37202824
[3,]    2.287847  2.29976419

## evaluate continuous ranked probability score (CRPS) using scoringRules

library("scoringRules")
crps(X, x)

[1] 0.2570254 0.8819173 0.7283174