family_extensions

Extend Distribution Families

Description

Extends an existing distribution family by transforming, conditioning, coarsening, or adding point masses. The resulting “gamlss2.family” objects can be used directly in gamlss2 models, and family extensions can be nested to compose several operations.

Usage

transform_family(family = NO, transform, inverse, log_jacobian,
  increasing = TRUE, support = c(-Inf, Inf), valid.response = NULL,
  name = NULL)

logit_family(family = NO)

truncate_family(family = NO, lower = -Inf, upper = Inf,
  include = c(FALSE, TRUE))

censor_family(family = NO, lower = -Inf, upper = Inf)

inflate_family(family = NO, at = 0)

hurdle_family(family = PO, at = 0)

round_family(family = NO, digits = 0L)

Arguments

family

A distribution family accepted by the gamlss2 family infrastructure, such as NO or PO, or another modified family.

transform

A fixed monotone function mapping observations from the base scale to the response scale.

inverse

The inverse function of transform.

log_jacobian

A function returning the logarithm of the absolute derivative of inverse, evaluated on the response scale.

increasing

Logical. Is transform increasing?

support

Numeric vector with the two response-scale support bounds. These bounds are also used when evaluating the CDF outside the transformed support.

valid.response

Optional function returning logical values that indicate whether observations lie in the transformed support.

name

Optional character string used as the extended family label.

lower, upper

Fixed scalar lower and upper truncation or censoring boundaries. For censor_family(), leaving both at their infinite defaults constructs an observation-specific right-censored family for a Surv response.

include

Logical vector of length two indicating whether the lower and upper truncation boundaries are retained. The default interval is \((lower, upper]\).

at

One or more fixed inflation points, or one fixed hurdle point.

digits

Integer number of decimal places retained by rounding.

Details

For a fixed monotone transformation \(Y = g(X)\), transform_family uses

\(\log f_Y(y) = \log f_X(g^{-1}(y)) + \log |d g^{-1}(y) / dy|.\)

Increasing and decreasing transformations are supported. The convenience function logit_family constructs the logistic push-forward, which has strict support \(0 < Y < 1\). Exact zeros and ones are not valid observations for this continuous transformation.

The function truncate_family conditions the base distribution on the interval selected by lower, upper, and include. Its density or probability mass is divided by the probability of the retained interval. With at least one finite boundary, censor_family observes

\(Y = \min(\max(X, lower), upper)\)

and consequently creates point masses at finite censoring boundaries. With both boundaries left infinite, it instead accepts a right-censored survival::Surv(time, status) response. An observed event contributes the base density or mass at time; a censored observation contributes the base survival probability beyond time.

For inflation points \(c_j\), inflate_family constructs

\(F(y) = \pi_0 F_0(y) + \sum_j \pi_j I(c_j \le y).\)

Natural base-distribution mass at an inflation point is retained. The appended parameters pi1, pi2, and so on have log links and represent positive odds \(w_j\) relative to the base component, not probabilities. Thus,

\(\pi_0 = \frac{1}{1 + \sum_j w_j}, \qquad \pi_j = \frac{w_j}{1 + \sum_\ell w_\ell}.\)

This is the baseline-odds parameterization also used by mixture_family. Quantiles account for every probability jump.

The function hurdle_family instead constructs

\(F(y) = \pi_1 I(c \le y) + \pi_0 F_0(y \mid X \ne c).\)

Here pi1 is also the odds \(w_1\), so the hurdle probability is \(w_1/(1 + w_1)\). This is the complete mass at \(c\), including when the base distribution already assigns positive mass to that point.

The function round_family uses intervals centered on a decimal grid and is restricted to continuous base distributions. Its quantile and random-number functions follow R’s round() convention. For fixed, user-defined intervals, see discretize_family.

Inflated, hurdle, and fixed-bin families provide exact means and variances when the required base-family moments are available. Censored and rounded moments requiring unavailable partial moments report an error.

Continuous distributions with added point masses provide randomized quantile residuals. Bounds, atom locations, breaks, and transformations are fixed when the family is constructed. Other extensions requiring numerical normalization or derivatives during fitting are not provided.

Value

An object of class “gamlss2.family”. Existing base-family parameters retain their names, order, and links. Inflation and hurdle families append positive-odds parameters named pi1, pi2, and so on.

Examples

library("gamlss2")

set.seed(6020)
n <- 300
x <- sort(runif(n, -3, 3))

## logistic transformation of a normal distribution
fam <- logit_family(NO)
y <- fam$random(list(mu = sin(x), sigma = exp(-1 + cos(x))), n)
hist(y)
m <- gamlss2(y ~ s(x) | s(x), family = fam)
plot(m)

## zero-truncated Poisson distribution
fam <- truncate_family(PO, lower = 0)
y <- fam$random(list(mu = exp(1/2 + sin(x))), n)
m <- gamlss2(y ~ s(x), family = fam)
plot(x, y)

## small helper for plotting fitted quantiles
fq <- function(model) {
  matlines(x,
    quantile(model, probs = c(0.05, 0.5, 0.95)),
      lty = 1, lwd = 2, col = 4
  )
}

fq(m)

## normal distribution censored at both boundaries
fam <- censor_family(NO, lower = -1, upper = 1)
y <- fam$random(list(mu = sin(x), sigma = exp(-1 + cos(x))), n)
hist(y)
m <- gamlss2(y ~ s(x) | s(x), family = fam)
plot(m)
plot(x, y)
fq(m)

## zero-inflated Poisson distribution
fam <- inflate_family(PO, at = 0)
## pi1 is the added-mass odds; its mixture probability is plogis(cos(x))
y <- fam$random(list(mu = exp(1/2 + sin(x)), pi1 = exp(-1 + cos(x))), n)
barplot(table(y))
m <- gamlss2(y ~ s(x) | s(x), family = fam)
plot(m)
plot(x, y)
fq(m)

## zero-hurdle Poisson distribution
fam <- hurdle_family(PO, at = 0)
## pi1 is the hurdle odds; the probability of zero is plogis(cos(x))
y <- fam$random(list(mu = exp(1/2 + sin(x)), pi1 = exp(cos(x))), n)
barplot(table(y))
m <- gamlss2(y ~ s(x) | s(x), family = fam)
plot(m)
plot(x, y)
fq(m)

## decimal rounding
fam <- round_family(NO, digits = 1)
y <- fam$random(list(mu = sin(x), sigma = exp(-1 + cos(x))), n)
m <- gamlss2(y ~ s(x) | s(x), family = fam)
plot(m)
plot(m, which = "resid")