Lower-level construction

The @latte macro is the primary way to define a model: you write the latent field and likelihood once, and Latte assembles the LatentGaussianModel and its hyperparameter prior for you. This page documents the secondary path — building an LatentGaussianModel by hand from its three components. Reach for it when @latte cannot express your model, for example when you want full control over the latent precision matrix and assemble it yourself.

Prefer @latte for most models

Most models are written with the @latte macro, which builds a LatentGaussianModel for you (see Defining models: the @latte macro and the tutorials). Construct one directly, as shown below, when you need full control over the latent prior.

A hand-built model has three parts:

a hyperparameter prior, declared with @hyperparams;
a latent field prior — a function of the hyperparameters returning a mean and a precision matrix, wrapped in FunctionLatentModel;
an observation model linking observations to the latent field (see Observation Models).

Hyperparameters: `@hyperparams`

Hyperparameters control the latent prior (e.g. marginal variance, correlation) and the observation model (e.g. noise level). The @hyperparams macro declares them, each with a prior distribution, a transformation, and the space in which the prior is written.

julia

using Latte, Distributions

spec = @hyperparams begin
    (σ ~ Exponential(1.0), transform = log, space = natural)
    (ρ ~ Beta(2, 2),       transform = logit, space = natural)
end

Each ~ line introduces a free parameter; a plain name = value line fixes a parameter to a constant. Only free parameters appear in the parameter vector.

Natural and working space

Latte distinguishes two spaces:

Natural space is where parameters live for the user and for the model functions: a standard deviation σ > 0, a correlation ρ ∈ (0, 1).
Working space is the unconstrained space the inference engines optimise and explore in. The transform field is the bijector mapping natural → working (log for positive parameters, logit for the unit interval, identity for unbounded ones).

The two parameter wrappers, WorkingHyperparameters and NaturalHyperparameters, carry a vector together with the spec, and convert moves between them and to a NamedTuple:

julia

θ_w  = WorkingHyperparameters([0.5, -1.2], spec)  # working space (log σ, logit ρ)
θ_n  = convert(NaturalHyperparameters, θ_w)        # natural space (σ, ρ)
θ_nt = convert(NamedTuple, θ_n)                    # (ρ = logistic(-1.2), σ = exp(0.5))

Model functions receive parameters in natural space as keyword arguments, even though optimisation happens in working space.

Prior space and the Jacobian correction

The space field records where the prior is written. With space = natural, the prior is a density over the natural parameter, and Latte applies the change of variables to evaluate it in working space:

\log p_{working} (η) = \log p_{natural} (θ) + \log | \frac{d θ}{d η} |,

where $η$ is the working value and $θ = g (η)$ the corresponding natural value. The log-Jacobian term is supplied by logdetjac. With space = working, the prior is already a density over the working parameter and no correction is added. logpdf_prior evaluates the prior in working space — including this correction when the prior was specified in natural space.

julia

spec = @hyperparams begin
    (σ ~ Exponential(1.0), transform = log, space = natural)
end
# Equivalent to a prior on log(σ) in working space:
# p(log σ) = Exponential(1.0)(σ) · |dσ/d(log σ)| = Exponential(1.0)(σ) · σ

Vector-valued hyperparameters

A free hyperparameter may carry a continuous vector prior, so several components share one joint distribution — for example regression-style coefficients with a non-diagonal covariance:

julia

spec = @hyperparams begin
    (σ ~ Exponential(1.0), transform = log, space = natural)
    κ ~ MvNormal(zeros(2), [0.7 0.4; 0.4 1.3])   # one vector-valued hyperparameter
end

The flat parameter vector concatenates the entries in declaration order — here [σ; κ[1]; κ[2]], three coordinates — and the wrappers expose each entry under its name, as a scalar or a Vector:

julia

θ_n = NaturalHyperparameters([2.0, 0.1, -0.3], spec)
θ_n.σ                     # 2.0
θ_n.κ                     # [0.1, -0.3]
convert(NamedTuple, θ_n)  # (σ = 2.0, κ = [0.1, -0.3])

Model functions receive the vector entry as a Vector keyword argument, in natural space, exactly as written in the prior.

Two restrictions keep the flat layout well-defined:

Transforms on vector entries must be dimension-preserving and act elementwise: identity (the default, right for MvNormal) or elementwise(f) (e.g. elementwise(log) for a positive vector). Dimension-changing bijectors — simplex, Cholesky — are rejected at construction.
The prior must be vector-shaped (Distribution{Multivariate}); matrix-variate priors are not supported.

Inference engines treat each coordinate as one dimension of the θ-space, so marginals stay per-coordinate: a vector entry κ of length 2 contributes marginals named κ[1] and κ[2], and the by-name accessor hyperparameter_marginals(result, :κ) returns both. hyperparameter_groups maps :κ to its coordinate range. Note that grid exploration is exponential in the total θ dimension — a long vector hyperparameter calls for the CCD strategy (selected automatically for more than two coordinates).

In the @latte macro, mark a vector prior with @fixed to make it a hyperparameter — an unmarked MvNormal site classifies as a latent (fixed-effects) block.

Latte.@hyperparams Macro

julia

@hyperparams begin ... end

Convenient macro for creating HyperparameterSpec objects with clean, declarative syntax.

Syntax

Free parameters use the ~ operator:

julia

name ~ prior                                         # Identity transform, working space (default)
(name ~ prior, transform = transform_expr)           # With custom transform
(name ~ prior, transform = log, space = natural)     # With options

Fixed parameters use =:

julia

name = value

Builtin Transforms

The macro provides convenient shortcuts for common transformations:

log → elementwise(log) for positive parameters (σ, τ, κ, etc.)
logit → Bijectors.Logit(0.0, 1.0) for parameters in (0,1) (ρ, correlation, etc.)
identity → no transformation (default for parameters already unconstrained)

Call aliases are also supported: Log(), Logit(), Identity()

For maximum flexibility, you can also provide any custom bijector expression directly.

Options

transform: Bijector mapping natural → working space (default: identity)
space or prior_space: Space in which the prior is specified
- :natural - Prior is on the natural (constrained) parameter space
- :working - Prior is already on the working (unconstrained) space (default)

Important: When specifying options, wrap the entire clause in parentheses!

Examples

julia

using Distributions, Bijectors

# Example 1: PC priors (Penalizing Complexity priors)
# Exponential prior on σ, optimized on log(σ)
spec = @hyperparams begin
    (σ ~ Exponential(1.0), transform = log, space = natural)
    (ρ ~ Beta(2, 2), transform = logit, space = natural)
    μ = 0.0  # Fixed parameter
end

# Example 2: Using call aliases
spec = @hyperparams begin
    (σ ~ Exponential(1.0), transform = Log(), space = natural)
    (ρ ~ Beta(2, 2), transform = Logit(), space = natural)
end

# Example 3: Custom bijector expression
spec = @hyperparams begin
    (τ ~ Gamma(2, 1), transform = elementwise(x -> log(x + 1)), space = natural)
end

# Example 4: Identity transform (default) - prior already in working space
spec = @hyperparams begin
    μ ~ Normal(0, 10)      # No transformation needed
    σ ~ Gamma(2, 1)        # Prior specified directly in working space
end

# Example 5: Mixed free and fixed parameters
spec = @hyperparams begin
    (σ ~ Exponential(1.0), transform = log, space = natural)
    (ρ ~ Beta(2, 2), transform = logit, space = natural)
    μ = 0.0    # Fixed intercept
    n = 100    # Fixed sample size
end

# Example 6: Using prior_space keyword (synonym for space)
spec = @hyperparams begin
    (σ ~ Exponential(1.0), transform = log, prior_space = natural)
end

# Example 7: Vector-valued hyperparameter (joint prior over the components).
# Vector entries admit `identity` (default) or `elementwise(f)` transforms.
spec = @hyperparams begin
    (σ ~ Exponential(1.0), transform = log, space = natural)
    κ ~ MvNormal(zeros(2), [1.0 0.5; 0.5 2.0])
end

Comparison with Manual Construction

The macro provides a much more concise syntax compared to manual construction:

julia

# With macro (recommended)
spec = @hyperparams begin
    (σ ~ Exponential(1.0), transform = log, space = natural)
    (ρ ~ Beta(2, 2), transform = logit, space = natural)
    μ = 0.0
end

# Manual construction (verbose)
spec = HyperparameterSpec(
    free = (
        σ = Hyperparameter(Exponential(1.0), transform=elementwise(log), prior_space=:natural),
        ρ = Hyperparameter(Beta(2, 2), transform=Bijectors.Logit(0.0, 1.0), prior_space=:natural)
    ),
    fixed = (μ = 0.0,)
)

Notes

At least one free parameter (using ~) is required
When specifying options, use parentheses: (name ~ prior, option = value)
Options use unquoted symbols: space = natural, not space = :natural
Parameters cannot be specified multiple times
The space and prior_space keywords are synonyms - use whichever is more natural

See Also

HyperparameterSpec: The underlying type created by this macro
Hyperparameter: Individual hyperparameter specification

Lower-level construction ​

Hyperparameters: @hyperparams ​

Natural and working space ​

Prior space and the Jacobian correction ​

Vector-valued hyperparameters ​

Building a model directly: LatentGaussianModel ​

Validation ​

Lower-level construction

Hyperparameters: `@hyperparams`

Natural and working space

Prior space and the Jacobian correction

Vector-valued hyperparameters

Building a model directly: `LatentGaussianModel`

Validation