Configuration

Defaults

Sensible baseline defaults for likelihoods, fixed/random effects, and hyperpriors, plus how to override them safely.

General Guidance

Start with the baseline; tighten priors only when motivated by domain knowledge.
Prefer PC priors for scale/precision: they express intuitive tail probabilities.
Likelihoods with no hyperparameters (Poisson, Binomial, Exponential) need no family-level prior configuration.

Gaussian

Continuous response with identity link. Two hyperparameters: precision and precision offset.

Gaussian · precision prior (log-gamma)

Classic log-gamma prior for the observation precision. This is the default.

\theta_1 = \log(\tau), \quad p(\theta_1) \propto \exp\bigl(a\, \theta_1 - b\, e^{\theta_1}\bigr)

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 5e-5]` (shape, rate)
Initial	`4` → τ ≈ 54.6
Fixed	`False`

control = {
    'family': {
        'hyper': {
            'prec': {
                'prior': 'loggamma',
                'param': [1.0, 5e-5],
                'initial': 4.0,
                'fixed': False,
            }
        }
    }
}

Gaussian · precision prior (pc.prec)

Penalized-complexity prior for precision: set a tail event on the standard deviation.

\Pr\!\left(\sigma > u\right) = \alpha, \quad \sigma = 1/\sqrt{\tau}

Key	`prec`
Prior	`pc.prec`
Parameters	`[u, α]`

# Example: P(σ > 0.1) = 0.01
control = {
    'family': {
        'hyper': {
            'prec': {
                'prior': 'pc.prec',
                'param': [0.1, 0.01],
                'initial': 2.0,
                'fixed': False,
            }
        }
    }
}

Gaussian · precision offset (precoffset)

Safety valve for numerical stability. Fixed by default, do not change.

Key	`precoffset`
Prior	`None`
Parameters	`[]`
Initial	`72.087`
Fixed	`True` (safety)

# Default: fixed, no prior (do not change)
control = {
    'family': {
        'hyper': {
            'precoffset': {
                'prior': None,
                'param': [],
                'initial': 72.087,
                'fixed': True,
            }
        }
    }
}

Poisson · Binomial · Exponential

Count/binary likelihoods with no hyperparameters. No family-level prior configuration needed.

Poisson

Count data with log link. No hyperparameters.

Family	`"poisson"`
Hyperparameters	None
Link	log (default)

result = pyinla(
    model={'response': 'y', 'fixed': ['x']},
    family='poisson',
    data=data
)

Binomial

Binary/count data with logit link. No hyperparameters.

Family	`"binomial"`
Hyperparameters	None
Link	logit (default)
Required	`Ntrials`

result = pyinla(
    model={'response': 'y', 'fixed': ['x']},
    family='binomial',
    data=data,
    Ntrials=data['n'].to_numpy()
)

Exponential

Positive continuous data with constant hazard. No hyperparameters.

Family	`"exponential"` / `"exponentialsurv"`
Hyperparameters	None
Link	log (default), neglog (survival)

result = pyinla(
    model={'response': 'y', 'fixed': ['x']},
    family='exponential',
    data=data
)

Negative Binomial

Overdispersed count data. One hyperparameter: size (inverse overdispersion).

Negative Binomial · size prior

PC prior on the size parameter (1/overdispersion). Large size → less overdispersion.

n = \exp(\theta), \quad \text{Var}(y) = \mu + \mu^2/n

Key	`size`
Prior	`pcmgamma`
Parameters	`[7]`
Initial	`2.303` → n ≈ 10
Fixed	`False`

# Using defaults
result = pyinla(
    model={'response': 'y', 'fixed': ['x']},
    family='nbinomial',
    data=data
)

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

Gamma

Positive continuous data with log link. One hyperparameter: precision (shape).

Gamma · precision prior

Log-gamma prior on the precision/shape parameter.

\theta = \log(\phi), \quad \text{Var}(y) = \mu^2 / (s \phi)

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 0.01]`
Initial	`4.605` → φ = 100
Fixed	`False`

control = {
    'family': {
        'hyper': {
            'prec': {
                'prior': 'loggamma',
                'param': [1.0, 0.01],
                'initial': 4.605,
                'fixed': False,
            }
        }
    }
}

Beta

Proportions on (0, 1) with logit link. One hyperparameter: phi (precision).

Beta · phi prior

Log-gamma prior on the precision parameter.

\theta = \log(\phi), \quad \text{Var}(y) = \frac{\mu(1-\mu)}{1+\phi}

Key	`phi`
Prior	`loggamma`
Parameters	`[1, 0.1]`
Initial	`2.303` → φ = 10
Fixed	`False`

control = {
    'family': {
        'hyper': {
            'phi': {
                'prior': 'loggamma',
                'param': [1.0, 0.1],
                'initial': 2.303,
                'fixed': False,
            }
        }
    }
}

Beta-Binomial

Overdispersed binomial data. One hyperparameter: rho (overdispersion).

Beta-Binomial · rho prior

Gaussian prior on the logit-transformed overdispersion.

\rho = \frac{\exp(\theta)}{1+\exp(\theta)}, \quad \rho \in (0,1)

Key	`rho`
Prior	`gaussian`
Parameters	`[0, 0.4]` (mean, precision)
Initial	`0` → ρ = 0.5
Fixed	`False`

control = {
    'family': {
        'hyper': {
            'rho': {
                'prior': 'gaussian',
                'param': [0, 0.4],
                'initial': 0,
                'fixed': False,
            }
        }
    }
}

Log-Normal

Positive continuous data (log(y) ~ Normal). One hyperparameter: precision.

Log-Normal · precision prior

Log-gamma prior on the precision (inverse variance on log scale).

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 5e-5]`
Initial	`0` → τ = 1
Fixed	`False`

control = {
    'family': {
        'hyper': {
            'prec': {
                'prior': 'loggamma',
                'param': [1, 5e-5],
                'initial': 0,
                'fixed': False,
            }
        }
    }
}

Logistic

Continuous data with heavier tails than Gaussian. One hyperparameter: precision.

Logistic · precision prior

Log-gamma prior on the precision parameter.

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 5e-5]`
Initial	`1` → τ ≈ 2.72
Fixed	`False`

control = {
    'family': {
        'hyper': {
            'prec': {
                'prior': 'loggamma',
                'param': [1, 5e-5],
                'initial': 1,
                'fixed': False,
            }
        }
    }
}

Log-Logistic

Positive continuous data, often for survival. One hyperparameter: alpha (shape).

Log-Logistic · alpha prior

Log-gamma prior on the shape parameter with informative defaults.

\theta = \log(\alpha), \quad \alpha > 0

Key	`alpha`
Prior	`loggamma`
Parameters	`[25, 25]` (shape, rate)
Initial	`1` → α ≈ 2.72
Fixed	`False`

control = {
    'family': {
        'hyper': {
            'alpha': {
                'prior': 'loggamma',
                'param': [25, 25],
                'initial': 1,
                'fixed': False,
            }
        }
    }
}

Weibull

Survival/positive data with flexible hazard. One hyperparameter: alpha (shape).

Weibull · alpha prior (pc.alphaw)

PC prior penalizing deviation from exponential (α=1).

\alpha = \exp(0.1 \cdot \theta)

Key	`alpha`
Prior	`pc.alphaw`
Parameters	`[5]`
Initial	`-2` → α ≈ 0.82
Fixed	`False`

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

Student's t

Robust regression with heavy tails. Two hyperparameters: precision and degrees of freedom.

Student's t · precision prior

Log-gamma prior on precision.

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 5e-5]`
Initial	`0` → τ = 1
Fixed	`False`

Student's t · degrees of freedom prior (pcdof)

PC prior penalizing deviation from Gaussian (ν=∞). P(ν < u) = α.

\theta_2 = \log(\nu - 2), \quad \nu > 2

Key	`dof`
Prior	`pcdof`
Parameters	`[15, 0.5]` (u, α)
Initial	`5` → ν ≈ 150
Fixed	`False`

control = {
    'family': {
        'hyper': {
            'prec': {
                'prior': 'loggamma',
                'param': [1, 5e-5],
                'initial': 0,
                'fixed': False
            },
            'dof': {
                'prior': 'pcdof',
                'param': [15, 0.5],
                'initial': 5,
                'fixed': False
            }
        }
    }
}

Skew Normal

Asymmetric continuous data. Two hyperparameters: precision and skewness.

Skew Normal · precision prior

Log-gamma prior on precision.

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 5e-5]`
Initial	`4` → τ ≈ 54.6
Fixed	`False`

Skew Normal · skewness prior (pc.sn)

PC prior penalizing deviation from Normal (γ=0). Scalar parameter controls penalty strength.

\gamma = 0.988 \cdot \left(2 \cdot \text{logit}^{-1}(\theta_2) - 1\right), \quad |\gamma| < 0.988

Key	`skew`
Prior	`pc.sn`
Parameters	`10` (scalar, penalty strength)
Initial	`0.00123` → γ ≈ 0
Fixed	`False`

control = {
    'family': {
        'hyper': {
            'prec': {
                'prior': 'loggamma',
                'param': [1, 5e-5],
                'initial': 4,
                'fixed': False
            },
            'skew': {
                'prior': 'pc.sn',
                'param': 10,  # scalar, not list
                'initial': 0.00123456789,
                'fixed': False
            }
        }
    }
}

Random Effects

Default hyperpriors for latent model components (random effects). Most use a log-gamma prior on precision.

IID (Independent)

Independent and identically distributed random effects. One hyperparameter: precision.

IID · precision prior

Log-gamma prior on precision. Default for unstructured random effects.

x_i \stackrel{\text{iid}}{\sim} \mathcal{N}(0, 1/\tau)

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 0.00005]` (shape, rate)
Initial	`4` → τ ≈ 54.6
Fixed	`False`

'random': [
    {
        'id': 'group',
        'model': 'iid',
        'hyper': {
            'prec': {
                'prior': 'loggamma',
                'param': [1, 0.00005],
                'initial': 4,
                'fixed': False
            }
        }
    }
]

RW1 (Random Walk 1)

First-order random walk for temporal/ordered data. One hyperparameter: precision.

RW1 · precision prior

Log-gamma prior on precision of first differences.

x_{i+1} - x_i \stackrel{\text{iid}}{\sim} \mathcal{N}(0, 1/\tau)

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 0.00005]`
Initial	`4`
Fixed	`False`

'random': [
    {
        'id': 'time',
        'model': 'rw1',
        'hyper': [{
            'prior': 'loggamma',
            'param': [1, 0.00005],
            'initial': 4,
            'fixed': False
        }]
    }
]

RW2 (Random Walk 2)

Second-order random walk for smooth temporal/ordered data. One hyperparameter: precision.

RW2 · precision prior

Log-gamma prior on precision of second differences.

x_{i+1} - 2x_i + x_{i-1} \stackrel{\text{iid}}{\sim} \mathcal{N}(0, 1/\tau)

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 0.00005]`
Initial	`4`
Fixed	`False`

'random': [
    {
        'id': 'time',
        'model': 'rw2',
        'scale.model': True,  # recommended
        'hyper': [{
            'prior': 'pc.prec',  # recommended with scale.model
            'param': [1, 0.01],
            'initial': 4,
            'fixed': False
        }]
    }
]

Seasonal

Seasonal random effect for periodic patterns. One hyperparameter: precision.

Seasonal · precision prior

Log-gamma prior on precision.

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 0.00005]`
Initial	`4`
Fixed	`False`

'random': [
    {
        'id': 'month',
        'model': 'seasonal',
        'season.length': 12,
        'hyper': [{
            'prior': 'loggamma',
            'param': [1, 0.00005],
            'initial': 4,
            'fixed': False
        }]
    }
]

AR1 (Autoregressive)

First-order autoregressive model. Three hyperparameters: precision, lag-1 correlation (rho), and the process mean (fixed at 0 by default).

AR1 · precision prior

Log-gamma prior on precision.

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 0.00005]`
Initial	`4`
Fixed	`False`

AR1 · rho prior (correlation)

Normal prior on transformed lag-1 correlation. ρ ∈ (-1, 1).

\rho = 2 \cdot \text{logit}^{-1}(\theta_2) - 1

Key	`rho`
Prior	`normal`
Parameters	`[0, 0.15]` (mean, precision)
Initial	`2` → ρ ≈ 0.76
Fixed	`False`

AR1 · process mean prior

Normal prior on the AR(1) process mean. Fixed at 0 by default; set 'fixed': False to estimate.

Key	`mean`
Prior	`normal`
Parameters	`[0, 1]` (mean, precision)
Initial	`0`
Fixed	`True` (default)

'random': [
    {
        'id': 'time',
        'model': 'ar1',
        'hyper': {
            'prec': {
                'prior': 'loggamma',
                'param': [1, 0.00005],
                'initial': 4,
                'fixed': False
            },
            'rho': {
                'prior': 'normal',
                'param': [0, 0.15],
                'initial': 2,
                'fixed': False
            },
            'mean': {
                'prior': 'normal',
                'param': [0, 1],
                'initial': 0,
                'fixed': True   # set False to estimate the process mean
            }
        }
    }
]

Besag (ICAR)

Intrinsic Conditional Autoregressive model for areal spatial data. One hyperparameter: precision.

Besag · precision prior

Log-gamma prior on spatial precision.

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 0.00005]`
Initial	`4`
Fixed	`False`

'random': [
    {
        'id': 'region',
        'model': 'besag',
        'graph': adj_sparse,
        'scale.model': True,
        'hyper': {
            'prec': {
                'prior': 'pc.prec',  # recommended with scale.model
                'param': [1, 0.01],
                'initial': 4,
                'fixed': False
            }
        }
    }
]

BYM2

Besag-York-Mollie reparameterization. Two hyperparameters: precision and mixing (phi).

BYM2 · precision prior

PC prior on overall precision (total marginal variance).

Key	`prec`
Prior	`pc.prec`
Parameters	`[1, 0.01]` → P(σ > 1) = 0.01
Initial	`4`
Fixed	`False`

BYM2 · phi prior (mixing)

PC prior on mixing parameter. φ = proportion of variance from spatial component.

\phi \in (0, 1): \quad \phi \to 1 \text{ = spatial}, \quad \phi \to 0 \text{ = IID}

Key	`phi`
Prior	`pc`
Parameters	`[0.5, 0.5]` → P(φ < 0.5) = 0.5
Initial	`-3` → φ ≈ 0.05
Fixed	`False`

'random': [
    {
        'id': 'region',
        'model': 'bym2',
        'graph': adj_sparse,
        'hyper': {
            'prec': {
                'prior': 'pc.prec',
                'param': [1, 0.01],
                'initial': 4,
                'fixed': False
            },
            'phi': {
                'prior': 'pc',
                'param': [0.5, 0.5],
                'initial': -3,
                'fixed': False
            }
        }
    }
]

Generic0

Custom precision structure with user-defined C matrix. One hyperparameter: precision.

Generic0 · precision prior

Log-gamma prior on precision. Q = τ · C.

Key	`prec`
Prior	`loggamma`
Parameters	`[1, 0.00005]`
Initial	`4`
Fixed	`False`

'random': [
    {
        'id': 'idx',
        'model': 'generic0',
        'Cmatrix': C,  # your n x n precision structure
        'hyper': {
            'prec': {
                'prior': 'loggamma',
                'param': [1, 0.00005],
                'initial': 4,
                'fixed': False
            }
        }
    }
]

Quick Reference: Likelihoods

Family	Hyper	Prior	Param	Initial
`gaussian`	prec	loggamma	[1, 5e-5]	4
`poisson`	-	-	-	-
`binomial`	-	-	-	-
`exponential`	-	-	-	-
`nbinomial`	size	pcmgamma	[7]	2.303
`gamma`	prec	loggamma	[1, 0.01]	4.605
`beta`	phi	loggamma	[1, 0.1]	2.303
`betabinomial`	rho	gaussian	[0, 0.4]	0
`lognormal`	prec	loggamma	[1, 5e-5]	0
`logistic`	prec	loggamma	[1, 5e-5]	1
`loglogistic`	alpha	loggamma	[25, 25]	1
`weibull`	alpha	pc.alphaw	[5]	-2
`t`	prec	loggamma	[1, 5e-5]	0
	dof	pcdof	[15, 0.5]	5
`sn`	prec	loggamma	[1, 5e-5]	4
	skew	pc.sn	10	0.00123

Quick Reference: Random Effects

Model	Hyper	Prior	Param	Initial
`iid`	prec	loggamma	[1, 5e-5]	4
`rw1`	prec	loggamma	[1, 5e-5]	4
`rw2`	prec	loggamma	[1, 5e-5]	4
`seasonal`	prec	loggamma	[1, 5e-5]	4
`ar1`	prec	loggamma	[1, 5e-5]	4
	rho	normal	[0, 0.15]	2
	mean	normal	[0, 1]	0 (fixed)
`besag`	prec	loggamma	[1, 5e-5]	4
`bym2`	prec	pc.prec	[1, 0.01]	4
	phi	pc	[0.5, 0.5]	-3
`generic0`	prec	loggamma	[1, 5e-5]	4