# CensoredStudentsT: Create a Censored Student's T Distribution In crch: Censored Regression with Conditional Heteroscedasticity

 CensoredStudentsT R Documentation

## Create a Censored Student's T Distribution

### Description

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

### Usage

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

### Arguments

 `df` numeric. The degrees of freedom of the underlying uncensored t distribution. Can be any positive number, with `df = Inf` corresponding to the normal distribution. `location` numeric. The location parameter of the underlying uncensored t distribution, typically written μ in textbooks. Can be any real number, defaults to `0`. `scale` numeric. The scale parameter (standard deviation) of the underlying uncensored t distribution, typically written σ in textbooks. Can be any positive number, defaults to `1`. `left` numeric. The left censoring point. Can be any real number, defaults to `-Inf` (uncensored). If set to a finite value, the distribution has a point mass at `left` whose probability corresponds to the cumulative probability function of the uncensored t distribution at this point. `right` numeric. The right censoring point. Can be any real number, defaults to `Inf` (uncensored). 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 uncensored t distribution at this point.

### Details

The constructor function `CensoredStudentsT` sets up a distribution object, representing the censored t probability distribution by the corresponding parameters: the degrees of freedom `df`, the latent mean `location` = μ and latent scale parameter `scale` = σ (i.e., the parameters of the underlying uncensored t variable), the `left` censoring point (with `-Inf` corresponding to uncensored), and the `right` censoring point (with `Inf` corresponding to uncensored).

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

 T((left - μ)/σ) if x ≤ left 1 - T((right - μ)/σ) if x ≥ right τ((x - μ)/σ)/σ if left < x < right

where T and τ 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 censored 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 `CensoredStudentsT` 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 censored t distributions in the crch package, see `dct`, and the `crps_ct` 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 (only `TRUE` if there is no censoring, i.e., if both `left` and `right` are infinite).

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

### Value

A `CensoredStudentsT` distribution object.

`dct`, `StudentsT`, `TruncatedStudentsT`, `CensoredNormal`, `CensoredLogistic`

### Examples

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

## three censored t distributions:
## - uncensored standard t with 5 degrees of freedom
## - left-censored at zero with 5 df, latent location = 1 and scale = 1
## - interval-censored in [0, 5] with 5 df, latent location = 2 and scale = 2
X <- CensoredStudentsT(
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

## compute mean of the censored distribution
mean(X)
## higher moments (variance, 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 = "uncensored")
hist(x[2, ], main = "left-censored at zero")
hist(x[3, ], main = "interval-censored 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 (except at censoring points)
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)
```

crch documentation built on Sept. 10, 2022, 1:06 a.m.