Weibull Distribution

Parametrization

The Weibull distribution for a random vector \(\pmb{y} = (y_1, y_2, \ldots, y_n)\), where each \(y_i > 0\), has two parameterization variants.

Variant 0 (default):

\[f(y_i) = \alpha y_i^{\alpha - 1} \lambda_i \exp(-\lambda_i y_i^{\alpha}), \quad y_i > 0, \; \alpha > 0, \; \lambda_i > 0\]

Variant 1:

\[f(y_i) = \alpha y_i^{\alpha - 1} \lambda_i^{\alpha} \exp(-(\lambda_i y_i)^{\alpha}), \quad y_i > 0, \; \alpha > 0, \; \lambda_i > 0\]

where:

\(\pmb{y} = (y_1, y_2, \ldots, y_n)\) represents the observed positive continuous response values (e.g., survival times).
\(\alpha > 0\) is the shape parameter, controlling the tail behavior and hazard function shape.
\(\lambda_i > 0\) is the scale parameter for observation \(y_i\), linked to the linear predictor.

Figure 1 demonstrates how the Weibull PDF changes when we vary its shape \(\alpha\) and scale \(\lambda\).

Weibull PDFs for various \((\alpha, \lambda)\) pairs. Smaller \(\alpha\) produces an exponential-like distribution, while larger \(\alpha\) produces a more bell-shaped form. Changing \(\lambda\) stretches or compresses the distribution horizontally.

Mean and Variance

The mean and variance depend on the variant parameterization:

Variant 0:

\[\text{E}(y_i) = \lambda_i^{-1/\alpha} \Gamma(1 + 1/\alpha)\]

Variant 1:

\[\text{E}(y_i) = \lambda_i^{-1} \Gamma(1 + 1/\alpha)\]

where \(\Gamma(\cdot)\) is the gamma function. The variance involves the second moment and depends on \(\Gamma(1 + 2/\alpha)\).

Link Function

The scale parameter \(\lambda_i\) is linked to the linear predictor \(\eta_i\) using the log link (default):

\[\lambda_i = \exp(\eta_i), \quad i = 1, 2, \ldots, n\]

In vector form:

\[\pmb{\lambda} = \exp(\pmb{\eta})\]

Available link functions: default, log, neglog, quantile.

Hyperparameters

The Weibull likelihood has one hyperparameter controlling the shape \(\alpha\). This hyperparameter uses a scaled log-transformation to improve numerical stability during optimization.

Hyperparameter \(\theta\) (shape)

Key: alpha

The shape parameter \(\alpha\) is represented internally as:

\[\alpha = \exp(S \cdot \theta)\]

where \(S = 0.1\) is a scaling factor to mitigate numerical instabilities, as small changes in \(\alpha\) can significantly affect the likelihood. The prior is defined on \(\theta\).

The default configuration uses a PC prior (pc.alphaw) with parameter 5, starting at \(\theta = -2\) (corresponding to \(\alpha = \exp(-0.2) \approx 0.82\)).

When translated into control['family']['hyper'], the default entry looks like:

control = {
    'family': {
        'variant': 0,  # or 1
        'hyper': [
            {
                'id': 'alpha',
                'prior': 'pc.alphaw',
                'param': [5],
                'initial': -2,
                'fixed': False,
            },
        ]
    }
}

Each entry in control['family']['hyper'] may contain these keys:

id - Hyperparameter identifier (alpha; positional aliases theta and theta1 also accepted).
prior - Prior distribution name
param - Prior parameters (list)
initial - Initial value on the internal scale (\(\theta = \log(\alpha)/S\) with \(S = 0.1\))
fixed - Whether to fix the hyperparameter (True/False)

The alpha slot accepts any prior from the prior registry. The most commonly useful choices are:

Slot	Prior	Param shape	Use when
`alpha`	`pc.alphaw` (default)	`[lambda]`	Penalised-complexity prior on Weibull shape; recommended.
	`normal` / `gaussian`	`[mean, precision]` on \(\theta\)	Soft Gaussian on the scaled log-shape.
	`loggamma`	`[shape, rate]`, both positive	Conjugate-style prior on the scaled log-shape.
	`logtnormal`	`[location, scale]`	Truncated-normal on \(\theta\).
	`flat`	`[]`	Improper flat.
	Any unknown prior name raises `pyinla safety check: unknown prior '...'` before the engine runs.

The hyperparameter can be pinned at a known value by setting fixed=True (no prior required). Note that some prior/data combinations may pass the safety layer but fail to converge in the INLA C engine.

Validation Rules

pyINLA enforces several validation rules for Weibull models to ensure correct specification:

Not Allowed Arguments

The following arguments are not allowed for weibull and will raise PyINLAError:

E (exposure) - Only allowed for poisson/nbinomial
scale - Only allowed for gaussian/nbinomial/xbinomial/gamma/beta/logistic/t
Ntrials - Only allowed for binomial/xbinomial/betabinomial/nbinomial2

Variant

Key: control['family']['variant']

The variant parameter is allowed and must be:

0 (default)
1

Any other value raises pyinla safety check: control['family']['variant'] must be one of [0, 1].

Allowed Link Functions

Key: control['family']['link']

For both weibull and weibullsurv, the top-level link key accepts:

default
log
neglog

For quantile-based regression, do not use the top-level link key (R-INLA marks it obsolete and pyINLA rejects mixing). Instead, configure the modern control.link block directly:

control = {
    'family': {
        'control.link': {'model': 'quantile', 'quantile': 0.5},
    }
}

The quantile value must lie in (0, 1). Omitting either 'model': 'quantile' or the numeric 'quantile' entry trips a pyinla safety check before the engine runs.

Response Values

Response variable \(\pmb{y}\) must be strictly positive (\(y_i > 0\)). pyINLA will raise PyINLAError if any response value is zero or negative.

Survival Response

When using weibullsurv, the response must be created using inla_surv():

from pyinla import inla_surv

# Create survival response
y_surv = inla_surv(time=df["time"], event=df["event"])
result = pyinla(model={'response': y_surv, 'fixed': ['1', 'x']},
                family="weibullsurv", data=df)

Specification

family="weibull" for regression models.
family="weibullsurv" for survival models with censoring.
Required arguments:
- For regression: \(\pmb{y}\) where \(y_i > 0\).
- For survival: inla_surv(time, event) object.
Optional: variant (0 or 1, default = 0).

Notes

Two variant parameterizations are available:
- Variant 0: Scale in scipy/numpy is \(\lambda^{-1/\alpha}\)
- Variant 1: Scale in scipy/numpy is \(1/\lambda\)
The hazard function shape depends on \(\alpha\):
- \(\alpha < 1\): Decreasing hazard (infant mortality)
- \(\alpha = 1\): Constant hazard (exponential distribution)
- \(\alpha > 1\): Increasing hazard (aging/wear-out)
The survival model (weibullsurv) supports right censored, left censored, and interval censored data through the inla_surv object.
weibullsurv additionally exposes up to 10 cure-model regression coefficients (beta1, ..., beta10; positional aliases theta2, ..., theta11). These default to a \(\text{Normal}(-4, 100)\) prior on the first coefficient and \(\text{Normal}(0, 100)\) on the rest, and are only active when a cure structure is configured via R-INLA's cure control block. Most survival-only users only need to configure the alpha slot.
For large observation times, consider scaling the data to avoid numerical overflow.
The internal scaling factor \(S = 0.1\) means that \(\theta\) values have 10x the effect on \(\log(\alpha)\).

Worked examples