Likelihood Hyperparameters

Likelihood Hyperpriors

Configure priors for likelihood hyperparameters such as precision, overdispersion, and shape parameters via control['family']['hyper'].

Overview

Many likelihood families have hyperparameters that control dispersion, precision, or shape. These are configured via control['family']['hyper'] as a list of dictionaries, one per hyperparameter the user wants to override.

Routing: Each hyperparameter has a slot tag (e.g., prec, phi, rho) that identifies it. Entries are routed to the schema by their id field (case-insensitive, matching the slot's short_name). Position-based routing is not supported. The id may be omitted only when the family has exactly one hyperparameter; for families with two or more hypers, every entry must specify id.

General Syntax

control = {
    'family': {
        'hyper': [
            {
                'id': 'prec',             # slot tag (required for multi-hyper families)
                'prior': 'loggamma',      # prior distribution name
                'param': [1.0, 0.01],     # prior parameters
                'initial': 4.0,           # starting value for theta
                'fixed': False            # whether to estimate (False) or fix (True)
            }
        ]
    }
}
result = pyinla(model=model, data=df, family='gaussian', control=control)

Each entry uses exactly five keys: id, prior, param, initial, fixed. Any other key triggers a pyinla safety check: unsupported keys error. Omitted keys fall back to the schema default. A pinned entry (fixed: True) may omit prior and param.

Quick Reference Table

Family	Key	Parameter	Internal Scale	Default Prior	Default Params
`gaussian`	prec	Precision τ	θ = log(τ)	loggamma	[1, 5e-5]
`gaussian`	precoffset	Precision offset	θ = log(κ)	none (fixed)	[]
`gamma`	prec	Precision φ	θ = log(φ)	loggamma	[1, 0.01]
`beta`	phi	Precision φ	θ = log(φ)	loggamma	[1, 0.1]
`betabinomial`	rho	Overdispersion ρ	θ = logit(ρ)	gaussian	[0, 0.4]
`nbinomial`	size	Size n	θ = log(n)	pcmgamma	[7]
`t`	prec	Precision τ	θ₁ = log(τ)	loggamma	[1, 5e-5]
`t`	dof	Degrees of freedom ν	θ₂ = log(ν-2)	pcdof	[15, 0.5]
`sn`	prec	Precision τ	θ₁ = log(τ)	loggamma	[1, 5e-5]
`sn`	skew	Skewness γ	θ₂ = logit-scaled	pc.sn	10 (scalar)
`weibull`	alpha	Shape α	θ = log(α)/0.1	pc.alphaw	[5]
`logistic`	prec	Precision τ	θ = log(τ)	loggamma	[1, 5e-5]
`loglogistic`	alpha	Shape α	θ = log(α)	loggamma	[25, 25]
`lognormal`	prec	Precision τ	θ = log(τ)	loggamma	[1, 5e-5]
`exponentialsurv`	beta1..beta10	Stratum slopes	θ_i on linear scale	normal	[0, 100] (beta1: [-1, 100])
`weibullsurv`	alpha + beta1..beta10	Shape + stratum slopes	θ = log(α)/0.1; θ_i linear	pc.alphaw / normal	[5] / [0, 100] (beta1: [-4, 100])
`lognormalsurv`	prec + beta1..beta10	Precision + stratum slopes	θ = log(τ); θ_i linear	loggamma / normal	[1, 5e-5] / [0, 100] (beta1: [-4, 100])
`loglogisticsurv`	alpha + beta1..beta10	Shape + stratum slopes	θ = log(α); θ_i linear	loggamma / normal	[25, 25] / [0, 100] (beta1: [-4, 100])
`gammasurv`	prec + beta1..beta10	Precision + stratum slopes	θ = log(φ); θ_i linear	loggamma / normal	[1, 0.01] / [0, 100] (beta1: [-4, 100])
`poisson`	No hyperparameters
`binomial`	No hyperparameters
`xbinomial`	No hyperparameters
`nbinomial2`	No hyperparameters
`exponential`	No hyperparameters

Detailed Family Specifications

Gaussian (`family="gaussian"`)

The Gaussian likelihood has two hyperparameters. The first (prec) controls the observation precision. The second (precoffset) is typically fixed and acts as a numerical safeguard.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`prec`	log precision	loggamma	[1, 5e-5]	4.0	False
1	`precoffset`	log precision offset	none	[]	72.087	True

# Custom Gaussian precision prior (precoffset stays at its fixed default)
control = {
    'family': {
        'hyper': [
            {'id': 'prec', 'prior': 'pc.prec', 'param': [1, 0.01], 'initial': 4.0, 'fixed': False}
        ]
    }
}

Gamma (`family="gamma"`)

The Gamma likelihood has one hyperparameter controlling the precision (shape parameter).

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`prec`	log precision	loggamma	[1, 0.01]	4.605	False

# Custom Gamma precision prior
control = {
    'family': {
        'hyper': [
            {'id': 'prec', 'prior': 'loggamma', 'param': [1.0, 0.1], 'initial': 2.0, 'fixed': False}
        ]
    }
}

Beta (`family="beta"`)

The Beta likelihood has one hyperparameter: the precision parameter φ. Note: The key is phi, not prec.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`phi`	precision parameter	loggamma	[1, 0.1]	2.303	False

# Custom Beta precision prior
control = {
    'family': {
        'hyper': [
            {'id': 'phi', 'prior': 'loggamma', 'param': [1.0, 0.5], 'initial': 1.609, 'fixed': False}
        ]
    }
}  # initial 1.609 = log(5), so phi = 5

Beta-Binomial (`family="betabinomial"`)

The Beta-Binomial likelihood has one hyperparameter: the overdispersion parameter ρ ∈ (0, 1). The internal scale uses the logit transformation.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`rho`	overdispersion	gaussian	[0, 0.4]	0	False

# Custom Beta-Binomial overdispersion prior
control = {
    'family': {
        'hyper': [
            {'id': 'rho', 'prior': 'gaussian', 'param': [0, 1.0], 'initial': 0, 'fixed': False}
        ]
    }
}

Negative Binomial (`family="nbinomial"`)

The Negative Binomial likelihood has one hyperparameter: the size (inverse overdispersion) parameter n. Large n means less overdispersion.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`size`	size	pcmgamma	[7]	2.303	False

# Custom Negative Binomial size prior
control = {
    'family': {
        'hyper': [
            {'id': 'size', 'prior': 'pcmgamma', 'param': [7], 'initial': 2.303, 'fixed': False}
        ]
    }
}

Student-t (`family="t"`)

The Student-t likelihood has two hyperparameters: precision and degrees of freedom. The PC prior on dof penalizes deviation from Gaussian (ν=∞).

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`prec`	log precision	loggamma	[1, 5e-5]	0	False
1	`dof`	log degrees of freedom	pcdof	[15, 0.5]	5	False

# Custom Student-t priors
control = {
    'family': {
        'hyper': [
            {'id': 'prec', 'prior': 'loggamma', 'param': [1.0, 5e-5], 'initial': 4, 'fixed': False},
            {'id': 'dof',  'prior': 'pcdof',    'param': [10, 0.5],   'initial': 3, 'fixed': False}
        ]
    }
}

Skew-Normal (`family="sn"`)

The Skew-Normal likelihood has two hyperparameters: precision and skewness. The PC prior on skewness penalizes deviation from Normal (γ=0).

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`prec`	log precision	loggamma	[1, 5e-5]	4	False
1	`skew`	logit skew	pc.sn	10 (scalar)	0.00123	False

# Custom Skew-Normal priors
control = {
    'family': {
        'hyper': [
            {'id': 'prec', 'prior': 'loggamma', 'param': [1, 5e-5], 'initial': 4, 'fixed': False},
            {'id': 'skew', 'prior': 'pc.sn',    'param': 10,        'initial': 0.00123, 'fixed': False}  # param is scalar!
        ]
    }
}

Weibull (`family="weibull"`)

The plain Weibull likelihood has one hyperparameter: the shape parameter α. For right-censored / cure-rate models with stratum slopes, see weibullsurv below.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`alpha`	log alpha (scaled)	pc.alphaw	[5]	-2	False

Logistic (`family="logistic"`)

The Logistic likelihood has one hyperparameter: the precision τ. It is a symmetric, heavy-tailed alternative to the Gaussian.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`prec`	log precision	loggamma	[1, 5e-5]	1	False

Log-Logistic (`family="loglogistic"`)

The plain Log-Logistic likelihood has one hyperparameter: the shape parameter α. For right-censored / cure-rate models with stratum slopes, see loglogisticsurv below.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`alpha`	log alpha	loggamma	[25, 25]	1	False

Log-Normal (`family="lognormal"`)

The plain Log-Normal likelihood has one hyperparameter: the precision τ. For right-censored / cure-rate models with stratum slopes, see lognormalsurv below.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`prec`	log precision	loggamma	[1, 5e-5]	0	False

Exponential Survival (`family="exponentialsurv"`)

The exponential survival likelihood declares 10 stratum-slope hyperparameters beta1..beta10 for cure-rate / stratified models. There is no precision or shape slot; the rate is determined entirely by the linear predictor and the stratum slopes.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`beta1`	stratum slope 1	normal	[-1, 100]	-4	False
1-9	`beta2..beta10`	stratum slopes 2-10	normal	[0, 100]	0	False

# Override one stratum slope; the others stay at their defaults
control = {
    'family': {
        'hyper': [
            {'id': 'beta1', 'prior': 'normal', 'param': [-2, 50], 'initial': -3, 'fixed': False}
        ]
    }
}

Weibull Survival (`family="weibullsurv"`)

The Weibull survival likelihood has an alpha shape slot plus 10 stratum slopes beta1..beta10.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`alpha`	shape (log/0.1)	pc.alphaw	[5]	-2	False
1	`beta1`	stratum slope 1	normal	[-4, 100]	-7	False
2-10	`beta2..beta10`	stratum slopes 2-10	normal	[0, 100]	0	False

Log-Normal Survival (`family="lognormalsurv"`)

The log-normal survival likelihood has a prec precision slot plus 10 stratum slopes beta1..beta10.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`prec`	log precision	loggamma	[1, 5e-5]	0	False
1	`beta1`	stratum slope 1	normal	[-4, 100]	-7	False
2-10	`beta2..beta10`	stratum slopes 2-10	normal	[0, 100]	0	False

Log-Logistic Survival (`family="loglogisticsurv"`)

The log-logistic survival likelihood has an alpha shape slot plus 10 stratum slopes beta1..beta10.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`alpha`	log alpha	loggamma	[25, 25]	1	False
1	`beta1`	stratum slope 1	normal	[-4, 100]	-5	False
2-10	`beta2..beta10`	stratum slopes 2-10	normal	[0, 100]	0	False

Gamma Survival (`family="gammasurv"`)

The gamma survival likelihood has a prec precision slot plus 10 stratum slopes beta1..beta10.

Index	Key	Name	Default Prior	Default Params	Initial	Fixed
0	`prec`	log precision	loggamma	[1, 0.01]	0	False
1	`beta1`	stratum slope 1	normal	[-4, 100]	-7	False
2-10	`beta2..beta10`	stratum slopes 2-10	normal	[0, 100]	0	False

Families Without Hyperparameters

The following families have no likelihood hyperparameters to configure:

poisson : Poisson distribution
binomial : Binomial distribution
xbinomial : Extended binomial (continuous response in [0, 1])
nbinomial2 : Negative binomial (variant 2)
exponential : Exponential distribution

Common Prior Distributions

Prior Name	Description	Parameters
`loggamma`	Log-gamma prior on θ	[shape, rate]
`gaussian` / `normal`	Gaussian prior on θ	[mean, precision]
`pc.prec`	PC prior for precision	[u, α] where P(σ > u) = α
`pcdof`	PC prior for degrees of freedom	[u, α] where P(ν < u) = α
`pc.sn`	PC prior for skewness	λ (scalar, not list)
`pcmgamma`	PC prior for size/overdispersion	[λ]
`pc.alphaw`	PC prior for Weibull shape	[λ]
`logitbeta`	Logit-beta prior	[a, b]
`none`	No prior (typically for fixed parameters)	[]

Notes

Entries in control['family']['hyper'] are routed to schema slots by their id field, not by position. Only families with exactly one hyperparameter accept a single entry without id.
Each entry uses exactly five keys: id, prior, param, initial, fixed. Unknown keys raise pyinla safety check: unsupported keys.
Omitted keys fall back to the schema default (the values shown in the tables above). A pinned entry ('fixed': True) may omit prior and param.
Unknown prior names raise pyinla safety check: unknown prior '...' with a "Did you mean ..." hint, before the engine runs.
For detailed mathematical definitions, see the Likelihoods documentation.

Overview

General Syntax

Quick Reference Table

Detailed Family Specifications

Gaussian (family="gaussian")

Gamma (family="gamma")

Beta (family="beta")

Beta-Binomial (family="betabinomial")

Negative Binomial (family="nbinomial")

Student-t (family="t")

Skew-Normal (family="sn")

Weibull (family="weibull")

Logistic (family="logistic")

Log-Logistic (family="loglogistic")

Log-Normal (family="lognormal")

Exponential Survival (family="exponentialsurv")

Weibull Survival (family="weibullsurv")

Log-Normal Survival (family="lognormalsurv")

Log-Logistic Survival (family="loglogisticsurv")

Gamma Survival (family="gammasurv")