API Reference

@Model begin
    @helpers begin ... end           # optional
    @fixedEffects begin ... end      # optional if @randomEffects present
    @covariates begin ... end        # optional
    @randomEffects begin ... end     # optional if @fixedEffects present
    @preDifferentialEquation begin ... end  # optional
    @DifferentialEquation begin ... end     # optional; requires @initialDE
    @initialDE begin ... end                # optional; requires @DifferentialEquation
    @formulas begin ... end          # required
end

Compose all model blocks into a Model struct.

Each block is optional except @formulas. At least one of @fixedEffects or @randomEffects must be non-empty. @DifferentialEquation and @initialDE must appear together.

After assembling the blocks, @Model:

1. Calls finalize_covariates to resolve constant_on defaults.
2. Validates that DE covariates are used correctly (no varying covariates, dynamic covariates must be called as w(t)).
3. Compiles formula builder functions and validates state/signal usage.
4. Returns a fully constructed Model ready for use with DataModel.

@helpers begin
    f(x) = ...
    g(x, y) = ...
end

Define user-provided helper functions that are available inside @randomEffects, @preDifferentialEquation, @DifferentialEquation, @initialDE, and @formulas blocks.

Each statement must be a function definition using short (f(x) = expr) or long (function f(x) ... end) form. Helper names must be unique within the block.

Returns a NamedTuple mapping each function name to its compiled anonymous function. The helpers NamedTuple is stored in the Model and passed automatically at evaluation time via get_helper_funs.

Mutating operations (calls ending in !, indexed assignment) trigger a warning since they may break Zygote-based automatic differentiation.

@fixedEffects begin
    name = ParameterBlockType(...)
    ...
end

Compile a block of fixed-effect parameter declarations into a FixedEffects struct.

Each statement must be an assignment name = constructor(...) where the right-hand side is one of the parameter block constructors: RealNumber, RealVector, RealPSDMatrix, RealDiagonalMatrix, NNParameters, SoftTreeParameters, SplineParameters, or NPFParameter.

The LHS symbol becomes the parameter name and is automatically injected as the name keyword argument into each constructor.

The @fixedEffects block is typically used inside @Model. It can also be used standalone to construct a FixedEffects object directly.

@covariates begin
    name = CovariateType(...)
    ...
end

Compile covariate declarations into a Covariates struct.

Each statement must be an assignment name = constructor(...) where the constructor is one of: Covariate, CovariateVector, ConstantCovariate, ConstantCovariateVector, DynamicCovariate, or DynamicCovariateVector.

For scalar types (Covariate, ConstantCovariate, DynamicCovariate), the LHS symbol determines the data-frame column name — do not pass an explicit column argument.

The @covariates block is typically used inside @Model. It can also be used standalone to construct a Covariates object directly.

@randomEffects begin
    name = RandomEffect(dist; column=:GroupCol)
    ...
end

Compile random-effect declarations into a RandomEffects struct.

Each statement must be an assignment name = RandomEffect(dist; column=:Col). The distribution expression dist may reference fixed effects, constant covariates, helper functions, and model functions (NNs, splines, soft trees). The symbols t and ξ are forbidden.

When using NormalizingPlanarFlow(ψ) in a distribution, it is automatically rewritten to call model_funs.NPF_ψ(ψ), where the NPF callable is registered automatically from the corresponding NPFParameter in @fixedEffects.

The @randomEffects block is typically used inside @Model.

@preDifferentialEquation begin
    name = expr
    ...
end

Compile time-constant derived quantities into a PreDifferentialEquation struct.

Each statement must be an assignment name = expr. The right-hand side may reference:

• fixed effects and random effects by name,
• constant covariates (including vector fields x.field),
• helper functions,
• model functions (NNs, splines, soft trees).

The symbols t and ξ are forbidden (pre-DE variables are time-constant).

Pre-DE variables are computed once per individual before the ODE is integrated and are available inside @DifferentialEquation and @initialDE.

Mutating operations trigger a warning since they may break Zygote-based AD.

@DifferentialEquation begin
    D(state) ~ rhs_expr
    signal(t) = signal_expr
    ...
end

Compile an ODE system into a DifferentialEquation struct.

Two statement forms are supported:

• D(state) ~ rhs: defines a state variable whose time derivative equals rhs.
• signal(t) = expr: defines a derived signal computed from states and parameters.

Symbols in right-hand sides are resolved from (in order): pre-DE variables, random effects, fixed effects, constant covariates, dynamic covariates (called as w(t)), model functions, and helper functions. Varying (non-dynamic) covariates are not allowed inside the DE.

Small vector literals (up to length 8) are automatically replaced with StaticArrays.SVector for allocation-free ODE evaluation.

Must be paired with @initialDE when used inside @Model.

@initialDE begin
    state = expr
    ...
end

Compile initial-condition declarations for an ODE system into an InitialDE struct.

Each statement must assign a scalar expression to a state name matching one declared with D(state) ~ ... in the paired @DifferentialEquation block. Every state must have exactly one initial condition. The symbols t and ξ are forbidden.

Right-hand sides may reference fixed effects, random effects, constant covariates, pre-DE variables, model functions, and helper functions.

@formulas begin
    name = expr          # deterministic node
    outcome ~ dist(...)  # observation node
    ...
end

Compile the observation model into a Formulas struct.

Two statement forms are supported:

• name = expr — a deterministic intermediate variable. May reference any previously defined deterministic name or any model symbol.
• outcome ~ dist(...) — an observation distribution. The right-hand side must be a Distributions.Distribution constructor.

Symbols are resolved from (in order): fixed effects, random effects, pre-DE variables, constant covariates, varying covariates, helper functions, model functions, and DE state/signal accessors. State and signal names must be called with a time argument: x1(t) or x1(t - offset).

Dynamic covariates used without an explicit (t) call are evaluated implicitly at the current time t.

The @formulas block is required in every @Model.

RealNumber(value; name, scale, lower, upper, prior, calculate_se) -> RealNumber

A scalar real-valued fixed-effect parameter block.

Arguments

• value::Real: initial value on the natural (untransformed) scale.

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• scale::Symbol = :identity: reparameterisation applied during optimisation. Must be one of REAL_SCALES (:identity, :log).
• lower::Real = -Inf: lower bound on the natural scale (defaults to EPSILON when scale=:log).
• upper::Real = Inf: upper bound on the natural scale.
• prior = Priorless(): prior distribution (Distributions.Distribution) or Priorless().
• calculate_se::Bool = true: whether to include this parameter in standard-error calculations.

RealVector(value; name, scale, lower, upper, prior, calculate_se) -> RealVector

A vector of real-valued fixed-effect parameters with per-element scale options.

Arguments

• value::AbstractVector{<:Real}: initial values on the natural scale.

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• scale: per-element scale symbols. A single Symbol or a Vector{Symbol} of the same length as value. Each element must be in REAL_SCALES (:identity, :log). Defaults to all :identity.
• lower: lower bounds per element. Defaults to -Inf (or EPSILON for :log elements).
• upper: upper bounds per element. Defaults to Inf.
• prior = Priorless(): a Distributions.Distribution, a Vector{Distribution} of matching length, or Priorless().
• calculate_se::Bool = true: whether to include this parameter in standard-error calculations.

RealPSDMatrix(value; name, scale, prior, calculate_se) -> RealPSDMatrix

A symmetric positive semi-definite (PSD) matrix parameter block, typically used to parameterise covariance matrices of random-effect distributions.

The matrix is reparameterised during optimisation to ensure PSD constraints are automatically satisfied.

Arguments

• value::AbstractMatrix{<:Real}: initial symmetric PSD matrix.

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• scale::Symbol = :cholesky: reparameterisation. Must be one of PSD_SCALES (:cholesky, :expm).
• prior = Priorless(): a Distributions.Distribution (e.g. Wishart) or Priorless().
• calculate_se::Bool = false: whether to include this parameter in standard-error calculations.

RealDiagonalMatrix(value; name, scale, prior, calculate_se) -> RealDiagonalMatrix

A diagonal positive-definite matrix parameter block, stored as a vector of the diagonal entries. Useful for diagonal covariance matrices.

All diagonal entries must be strictly positive. They are stored and optimised on the log scale.

Arguments

• value: initial diagonal entries as an AbstractVector{<:Real} or a diagonal AbstractMatrix. If a matrix is provided, off-diagonal entries are ignored with a warning.

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• scale::Symbol = :log: reparameterisation. Must be in DIAGONAL_SCALES (:log).
• prior = Priorless(): a Distributions.Distribution or Priorless().
• calculate_se::Bool = false: whether to include this parameter in standard-error calculations.

ProbabilityVector(value; name, scale, prior, calculate_se) -> ProbabilityVector

A probability vector parameter block: a vector of k ≥ 2 non-negative entries summing to 1. Optimised via the logistic stick-breaking reparameterisation, which maps the simplex to k-1 unconstrained reals.

Arguments

• value::AbstractVector{<:Real}: initial probability vector. All entries must be non-negative and sum to 1 (within tolerance); if the sum differs by less than atol=1e-6, the vector is silently normalised.

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• scale::Symbol = :stickbreak: reparameterisation. Must be in PROBABILITY_SCALES.
• prior = Priorless(): a Distributions.Distribution or Priorless().
• calculate_se::Bool = false: whether to include this parameter in standard-error calculations.

DiscreteTransitionMatrix(value; name, scale, prior, calculate_se) -> DiscreteTransitionMatrix

A square row-stochastic matrix parameter block of size n×n (n ≥ 2). Each row is a probability vector and is independently reparameterised via the logistic stick-breaking transform, yielding n*(n-1) unconstrained reals.

Arguments

• value::AbstractMatrix{<:Real}: initial row-stochastic matrix. Each row must be non-negative and sum to 1 (within tolerance); rows are silently normalised if needed.

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• scale::Symbol = :stickbreakrows: reparameterisation. Must be in TRANSITION_SCALES.
• prior = Priorless(): a Distributions.Distribution or Priorless().
• calculate_se::Bool = false: whether to include this parameter in standard-error calculations.

ContinuousTransitionMatrix(value; name, scale, prior, calculate_se) -> ContinuousTransitionMatrix

An n×n rate matrix (Q-matrix) parameter block for continuous-time Markov chains (n ≥ 2).

The Q-matrix has:

• Off-diagonal entries Q[i,j] ≥ 0 (transition rates from state i to state j, i ≠ j).
• Diagonal entries Q[i,i] = -∑_{j≠i} Q[i,j] (rows sum to zero).

The n*(n-1) off-diagonal rates are optimised on the log scale (:lograterows), mapping each rate to an unconstrained real via log. The diagonal is recomputed from the off-diagonals and is not an independent free parameter.

Arguments

• value::AbstractMatrix{<:Real}: initial n×n Q-matrix. Off-diagonal entries must be non-negative. The diagonal is always silently recomputed as -rowsum of the off-diagonals, so any diagonal values provided in value are ignored.

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• scale::Symbol = :lograterows: reparameterisation. Must be in RATE_MATRIX_SCALES.
• prior = Priorless(): a Distributions.Distribution or Priorless().
• calculate_se::Bool = false: whether to include this parameter in standard-error calculations.

NNParameters(chain; name, function_name, seed, prior, calculate_se) -> NNParameters

A parameter block that wraps the flattened parameters of a Lux.jl neural-network chain.

The resulting parameter is optimised as a flat real vector. Inside model blocks (@randomEffects, @preDifferentialEquation, @formulas) the network is called as function_name(input, θ_slice), where θ_slice is the corresponding slice of the fixed-effects ComponentArray.

Arguments

• chain: a Lux.Chain defining the neural-network architecture.

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• function_name::Symbol: the name used to call the network in model blocks.
• seed::Integer = 0: random seed for initialising the Lux parameters.
• prior = Priorless(): Priorless(), a Vector{Distribution} of length equal to the number of parameters, or a multivariate Distribution with matching length.
• calculate_se::Bool = false: whether to include this parameter in standard-error calculations.

NPFParameter(n_input, n_layers; name, seed, init, prior, calculate_se) -> NPFParameter

A parameter block for a Normalizing Planar Flow (NPF), enabling flexible non-Gaussian distributions in @randomEffects via RandomEffect(NormalizingPlanarFlow(ψ); column=:ID).

The flow is composed of n_layers planar transformations on an n_input-dimensional base Gaussian. Parameters are stored as a flat real vector.

Arguments

• n_input::Integer: dimensionality of the latent space (typically 1 for scalar random effects).
• n_layers::Integer: number of planar flow layers.

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• seed::Integer = 0: random seed for initialisation.
• init::Function: weight initialisation function; defaults to x -> sqrt(1/n_input) .* x.
• prior = Priorless(): Priorless(), a Vector{Distribution}, or a multivariate Distribution.
• calculate_se::Bool = false: whether to include this parameter in standard-error calculations.

SoftTreeParameters(input_dim, depth; name, function_name, n_output, seed, prior, calculate_se) -> SoftTreeParameters

A parameter block for a soft decision tree whose parameters are optimised as fixed effects.

The tree takes a real-valued vector of length input_dim and produces a vector of length n_output. Parameters are stored as a flat real vector. Inside model blocks the tree is called as function_name(x, θ_slice).

Arguments

• input_dim::Integer: number of input features.
• depth::Integer: depth of the tree (number of internal split levels).

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• function_name::Symbol: the name used to call the tree in model blocks.
• n_output::Integer = 1: number of output values.
• seed::Integer = 0: random seed for initialisation.
• prior = Priorless(): Priorless(), a Vector{Distribution}, or a multivariate Distribution.
• calculate_se::Bool = false: whether to include this parameter in standard-error calculations.

SplineParameters(knots; name, function_name, degree, prior, calculate_se) -> SplineParameters

A parameter block for a B-spline function whose coefficients are optimised as fixed effects.

The number of coefficients is determined by length(knots) - degree - 1. All coefficients are initialised to zero. Inside model blocks the spline is evaluated as function_name(x, θ_slice).

Arguments

• knots::AbstractVector{<:Real}: B-spline knot vector (including boundary knots).

Keyword Arguments

• name::Symbol = :unnamed: parameter name (injected automatically by @fixedEffects).
• function_name::Symbol: the name used to call the spline in model blocks.
• degree::Integer = 3: polynomial degree of the B-spline (e.g. 2 for quadratic, 3 for cubic).
• prior = Priorless(): Priorless(), a Vector{Distribution}, or a multivariate Distribution.
• calculate_se::Bool = false: whether to include this parameter in standard-error calculations.

Priorless()

Sentinel type indicating that no prior distribution is assigned to a parameter. Used as the default prior value in all parameter block constructors.

Covariate() -> Covariate

A time-varying scalar covariate read row-by-row from the data frame.

In @covariates, the LHS name determines the data column and must refer to a column present in the data frame. This type is also used to declare the time column:

@covariates begin
    t = Covariate()
    z = Covariate()
end

CovariateVector(columns::Vector{Symbol}) -> CovariateVector

A vector of time-varying scalar covariates read row-by-row.

@covariates begin
    z = CovariateVector([:z1, :z2])
end

Accessed in model blocks as z.z1, z.z2.

Arguments

• columns::Vector{Symbol}: names of the data-frame columns to collect.

ConstantCovariate(; constant_on) -> ConstantCovariate

A scalar covariate that is constant within a grouping (e.g. a subject-level baseline).

In @covariates, the LHS name determines the data column:

@covariates begin
    Age = ConstantCovariate(; constant_on=:ID)
end

Keyword Arguments

• constant_on: a Symbol or vector of Symbols naming the grouping column(s) within which the covariate is constant. When only one random-effect group exists, this defaults to that group's column.

ConstantCovariateVector(columns::Vector{Symbol}; constant_on) -> ConstantCovariateVector

A vector of scalar covariates, each constant within a grouping.

The LHS name in @covariates becomes the accessor name; columns specifies which data-frame columns to read:

@covariates begin
    x = ConstantCovariateVector([:Age, :BMI]; constant_on=:ID)
end

Accessed in model blocks as x.Age, x.BMI.

Keyword Arguments

• constant_on: a Symbol or vector of Symbols naming the grouping column(s).

DynamicCovariate(; interpolation=LinearInterpolation) -> DynamicCovariate

A time-varying covariate represented as a DataInterpolations.jl interpolant, callable as w(t) inside @DifferentialEquation and @formulas.

In @covariates, the LHS name provides both the accessor name and the data-frame column.

Keyword Arguments

• interpolation: a DataInterpolations.jl interpolation type (not instance). Must be one of ConstantInterpolation, SmoothedConstantInterpolation, LinearInterpolation, QuadraticInterpolation, LagrangeInterpolation, QuadraticSpline, CubicSpline, or AkimaInterpolation. Defaults to LinearInterpolation.

DynamicCovariateVector(columns::Vector{Symbol}; interpolations) -> DynamicCovariateVector

A vector of time-varying covariates, each represented as a separate interpolant.

@covariates begin
    inputs = DynamicCovariateVector([:i1, :i2]; interpolations=[LinearInterpolation, CubicSpline])
end

Arguments

• columns::Vector{Symbol}: data-frame column names.

Keyword Arguments

• interpolations: a Vector of DataInterpolations.jl types, one per column. Defaults to LinearInterpolation for all columns.

RandomEffect(dist; column::Symbol) -> RandomEffectDecl

Declare a random effect with the given distribution and grouping column.

Used exclusively inside @randomEffects:

@randomEffects begin
    η = RandomEffect(Normal(0.0, σ); column=:ID)
end

Arguments

• dist: a distribution expression (evaluated at model construction time). May reference fixed effects, constant covariates, helper functions, and model functions. The symbols t and ξ are forbidden (random effects are time-constant).

Keyword Arguments

• column::Symbol: the data-frame column that defines the grouping for this random effect.

Model{F, R, C, D, H, O}

Top-level model struct produced by the @Model macro. Bundles all model components: fixed effects, random effects, covariates, ODE system, helper functions, and observation formulas.

Fields

• fixed::FixedBundle: fixed-effects data (parameters, transforms, model functions).
• random::RandomBundle: random-effects data (distributions, logpdf).
• covariates::CovariatesBundle: covariate metadata.
• de::DEBundle: ODE system components (may hold nothing when no DE is defined).
• helpers::HelpersBundle: user-defined helper functions.
• formulas::FormulasBundle: observation model (deterministic + observation nodes).

Use accessor functions get_model_funs, get_helper_funs, get_solver_config, etc. rather than accessing fields directly.

ODESolverConfig{A, K, T}

Configuration for the ODE solver used when integrating the @DifferentialEquation block.

Fields

• alg: ODE algorithm (e.g. Tsit5(), CVODE_BDF()). nothing uses the SciML default.
• kwargs::NamedTuple: keyword arguments forwarded to solve (e.g. abstol, reltol).
• args::Tuple: positional arguments forwarded to solve.
• saveat_mode::Symbol: one of :dense, :saveat, or :auto.
  • :dense — full dense solution (required for non-constant time offsets in formulas).
  • :saveat — save only at observation + event + formula-offset times.
  • :auto — resolves to :saveat unless non-constant time offsets require :dense.

Constructed by the @Model macro with defaults and updated via set_solver_config.

set_solver_config(m::Model, cfg::ODESolverConfig) -> Model
set_solver_config(m::Model; alg, kwargs, args, saveat_mode) -> Model

Return a new Model with the ODE solver configuration replaced by cfg. The keyword form constructs a new ODESolverConfig from the given keyword arguments and replaces the existing configuration.

Keyword Arguments

• alg: ODE algorithm (e.g. Tsit5()). nothing uses the SciML default.
• kwargs = NamedTuple(): keyword arguments forwarded to solve.
• args = (): positional arguments forwarded to solve.
• saveat_mode::Symbol = :dense: save-time mode (:dense, :saveat, or :auto).

get_model_funs(fe::FixedEffects) -> NamedTuple

Return a NamedTuple of callable model functions derived from NNParameters, SoftTreeParameters, SplineParameters, and NPFParameter blocks. Each function has the signature matching its block type's function_name.

get_model_funs(m::Model) -> NamedTuple

Return the NamedTuple of callable model functions derived from NNParameters, SoftTreeParameters, SplineParameters, and NPFParameter blocks in @fixedEffects.

get_helper_funs(m::Model) -> NamedTuple

Return the NamedTuple of user-defined helper functions from the @helpers block.

get_solver_config(m::Model) -> ODESolverConfig

Return the ODESolverConfig controlling how the ODE is solved.

FixedEffects

Compiled representation of a @fixedEffects block. Contains initial parameter values, bounds, forward/inverse transforms, priors, SE masks, and model functions (NNs, splines, soft trees, NPFs).

Use accessor functions rather than accessing fields directly.

Covariates

Compiled representation of a @covariates block. Stores the covariate names categorised as constant, varying, or dynamic, along with interpolation types and the raw covariate parameter structs.

Use the model.covariates.covariates field (or the CovariatesBundle) to inspect this struct. Typically accessed indirectly via DataModel construction.

finalize_covariates(covariates::Covariates, random_effects::RandomEffects) -> Covariates

Resolve the constant_on grouping column for each ConstantCovariate / ConstantCovariateVector that did not specify one explicitly.

• When there is exactly one random-effect grouping column, constant_on defaults to it.
• When there are multiple grouping columns, constant_on must be explicit.
• Validates that covariates used inside random-effect distributions are declared constant_on for the correct grouping column.

This function is called automatically by @Model after @covariates and @randomEffects are evaluated.

RandomEffects

Compiled representation of a @randomEffects block. Stores metadata (names, grouping columns, distribution types, symbol dependencies) and runtime builder functions for constructing distributions and evaluating log-densities.

Use accessor functions rather than accessing fields directly.

PreDifferentialEquation

Compiled representation of a @preDifferentialEquation block. Stores derived variable names, symbol dependencies, raw expression lines, and a runtime builder function.

Pre-DE variables are time-constant quantities computed from fixed effects, random effects, and constant covariates before the ODE is solved. They are available inside @DifferentialEquation and @initialDE.

DifferentialEquation

Compiled representation of a @DifferentialEquation block. Stores state and signal names, in-place/out-of-place ODE functions, a parameter compiler, and an accessor builder for retrieving state/signal values from a solution object.

InitialDE

Compiled representation of an @initialDE block. Stores state names and the intermediate representation (IR) of initial-condition expressions. A runtime builder function is produced lazily via get_initialde_builder.

get_initialde_builder(i::InitialDE, state_names::Vector{Symbol}; static=false) -> Function

Build and return the initial-condition function for the ODE system.

The returned function has signature:

(θ::ComponentArray, η::ComponentArray, const_cov::NamedTuple,
 model_funs::NamedTuple, helpers::NamedTuple, preDE::NamedTuple) -> Vector

It returns the initial state vector ordered to match state_names.

Arguments

• i::InitialDE: the compiled initial-condition block.
• state_names::Vector{Symbol}: ordered state names from the @DifferentialEquation block.

Keyword Arguments

• static::Bool = false: if true, returns a StaticArrays.SVector for allocation-free ODE solving with small state dimensions.

Formulas

Compiled representation of a @formulas block. Stores deterministic-node and observation-node names and expressions in an intermediate representation (FormulasIR).

Builder functions are produced via get_formulas_builders.

get_formulas_builders(f::Formulas; fixed_names, random_names, prede_names,
                      const_cov_names, varying_cov_names, helper_names,
                      model_fun_names, state_names, signal_names,
                      index_sym) -> (all_fn, obs_fn, req_states, req_signals)

Compile the formula expressions into two runtime-generated functions and return them together with lists of required DE states and signals.

Returns

• all_fn: function (ctx, sol_accessors, const_cov_i, vary_cov) -> NamedTuple evaluating all deterministic and observation nodes.
• obs_fn: function (ctx, sol_accessors, const_cov_i, vary_cov) -> NamedTuple evaluating observation nodes only.
• req_states::Vector{Symbol}: DE state names that are accessed in the formulas.
• req_signals::Vector{Symbol}: derived signal names that are accessed in the formulas.

Keyword Arguments

• fixed_names, random_names, prede_names, const_cov_names, varying_cov_names: symbol lists from each model namespace.
• helper_names, model_fun_names: callable symbol lists.
• state_names, signal_names: DE state and signal names for time-call rewriting.
• index_sym::Symbol = :t: the varying-covariates key used to extract the current time.

DataModel{M, D, I, P, C, K, G, R}

Top-level struct pairing a Model with a dataset. Produced by the DataModel constructor and passed to fit_model and plotting functions.

Use accessor functions rather than accessing fields directly: get_model, get_df, get_individuals, get_individual, get_batches, get_batch_ids, get_primary_id, get_row_groups, get_re_group_info, get_re_indices.

get_individuals(dm::DataModel) -> Vector{Individual}

Return the vector of Individual structs (one per unique primary-id value).

get_individual(dm::DataModel, id) -> Individual

Return the Individual struct for the given primary-id value. Raises an error if the id is not found.

get_batches(dm::DataModel) -> Vector{Vector{Int}}

Return the list of batches, where each batch is a vector of individual indices. Individuals in the same batch share at least one random-effect level and must be estimated jointly.

get_batch_ids(dm::DataModel) -> Vector{Int}

Return the batch index for each individual (length equals number of individuals).

get_primary_id(dm::DataModel) -> Symbol

Return the primary individual-grouping column name.

get_df(dm::DataModel) -> DataFrame

Return the original DataFrame used to construct the DataModel.

get_model(dm::DataModel) -> Model

Return the Model stored in the DataModel.

get_row_groups(dm::DataModel) -> RowGroups

Return the RowGroups struct mapping each individual index to its data-frame row indices (all rows and observation-only rows).

get_re_group_info(dm::DataModel) -> REGroupInfo

Return the REGroupInfo struct containing random-effect level values and per-row level indices, plus per-individual row-level assignments.

get_re_indices(dm::DataModel, id_or_ind_or_idx; obs_only=true) -> NamedTuple

Return a NamedTuple mapping each random-effect name to a vector of level indices for the specified individual.

The individual can be identified by its primary-id value, an Individual object, or its integer position in get_individuals(dm).

Keyword Arguments

• obs_only::Bool = true: if true, only return indices for observation rows; if false, include all rows (including event rows).

ModelSummary

Structured summary of a Model. Created by summarize(model).

Provides counts and lists of all model components: fixed effects, random effects, covariates, deterministic formulas, outcome distributions, and differential equation states/signals. Displayed via Base.show.

DataModelSummary

Structured summary of a DataModel. Created by summarize(dm).

Provides individual-level, covariate, outcome, and random-effects statistics, as well as data-quality checks (duplicate times, non-monotonic time, missing values). Displayed via Base.show.

DescriptiveStats

Descriptive statistics for a numeric variable. Contains n, mean, sd, min, q25, median, q75, and max.

summarize(m::Model) -> ModelSummary
summarize(dm::DataModel) -> DataModelSummary
summarize(res::FitResult; scale, include_non_se, constants_re) -> FitResultSummary
summarize(uq::UQResult; scale) -> UQResultSummary
summarize(res::FitResult, uq::UQResult; scale, include_non_se, constants_re) -> FitResultSummary

Compute a structured summary of a model, data model, fit result, or UQ result.

Each overload returns a specialised summary struct that has a pretty-printed show method for interactive inspection.

Keyword Arguments (for fit/UQ overloads)

• scale::Symbol = :natural: parameter scale to report (:natural or :transformed).
• include_non_se::Bool = false: include parameters marked calculate_se=false.
• constants_re::NamedTuple = NamedTuple(): constants for random-effects reporting.

FittingMethod

Abstract base type for all estimation methods. Concrete subtypes include MLE, MAP, MCMC, Laplace, LaplaceMAP, SAEM, MCEM, and Multistart.

MethodResult

Abstract base type for the method-specific result structs stored inside FitResult. Each FittingMethod subtype has a corresponding MethodResult subtype.

FitResult{M, R, S, D, DM, A, K}

Unified result wrapper returned by fit_model. Contains the fitting method, method-specific result, summary, diagnostics, and optionally the DataModel.

Use accessor functions rather than accessing fields directly: get_summary, get_diagnostics, get_result, get_method, get_objective, get_converged, get_params, get_data_model.

FitSummary{O, C, P, N}

High-level summary of a fitting result.

Fields

• objective::O: the final objective value (negative log-likelihood, negative log-posterior, etc.).
• converged::C: convergence flag (true / false / nothing for MCMC).
• params::P: a FitParameters struct with parameter estimates.
• notes::N: method-specific string notes or nothing.

FitDiagnostics{T, O, X, N}

Diagnostic information for a fitting run.

Fields

• timing::T: elapsed time in seconds.
• optimizer::O: optimizer-specific diagnostic (e.g. Optim.jl result).
• convergence::X: convergence-related metadata.
• notes::N: additional string notes.

FitParameters{T, U}

Stores parameter estimates on both the transformed (optimisation) and untransformed (natural) scales as ComponentArrays.

Fields

• transformed::T: parameter vector on the optimisation scale.
• untransformed::U: parameter vector on the natural scale.

fit_model(dm::DataModel, method::FittingMethod; constants, penalty,
          ode_args, ode_kwargs, serialization, rng,
          theta_0_untransformed, store_data_model) -> FitResult

Fit a model to data using the specified estimation method.

Arguments

• dm::DataModel: the data model.
• method::FittingMethod: estimation method (e.g. MLE(), Laplace(), MCMC(...)).

Keyword Arguments

• constants::NamedTuple = NamedTuple(): fix named parameters at given values on the natural scale. Fixed parameters are removed from the optimiser state.
• penalty::NamedTuple = NamedTuple(): add per-parameter quadratic penalties on the natural scale (not available for MCMC).
• ode_args::Tuple = (): extra positional arguments forwarded to the ODE solver.
• ode_kwargs::NamedTuple = NamedTuple(): extra keyword arguments forwarded to the ODE solver.
• serialization = EnsembleSerial(): parallelisation strategy.
• rng = Random.default_rng(): random number generator (used by MCMC/SAEM/MCEM).
• theta_0_untransformed::Union{Nothing, ComponentArray} = nothing: custom starting point on the natural scale; defaults to the model's declared initial values.
• store_data_model::Bool = true: whether to store a reference to dm in the result.

MLE(; optimizer, optim_kwargs, adtype, lb, ub) <: FittingMethod

Maximum Likelihood Estimation for models without random effects.

Keyword Arguments

• optimizer: Optimization.jl-compatible optimiser. Defaults to LBFGS with backtracking line search.
• optim_kwargs::NamedTuple = NamedTuple(): keyword arguments forwarded to Optimization.solve (e.g. maxiters, reltol).
• adtype: automatic-differentiation backend. Defaults to AutoForwardDiff().
• lb: lower bounds on the transformed parameter scale, or nothing to use the model-declared bounds.
• ub: upper bounds on the transformed parameter scale, or nothing.

MAP(; optimizer, optim_kwargs, adtype, lb, ub, ignore_model_bounds) <: FittingMethod

Maximum A Posteriori estimation for models without random effects. Requires prior distributions on at least one free fixed effect.

Keyword Arguments

• optimizer: Optimization.jl-compatible optimiser. Defaults to LBFGS with backtracking line search.
• optim_kwargs::NamedTuple = NamedTuple(): keyword arguments forwarded to Optimization.solve (e.g. maxiters, reltol).
• adtype: automatic-differentiation backend. Defaults to AutoForwardDiff().
• lb: lower bounds on the transformed parameter scale, or nothing to use the model-declared bounds.
• ub: upper bounds on the transformed parameter scale, or nothing.
• ignore_model_bounds::Bool = false: when true, ignore bounds declared in @fixedEffects unless explicit lb/ub are passed.

Laplace(; optimizer, optim_kwargs, adtype, inner_options, hessian_options,
          cache_options, multistart_options, inner_optimizer, inner_kwargs,
          inner_adtype, inner_grad_tol, multistart_n, multistart_k,
          multistart_grad_tol, multistart_max_rounds, multistart_sampling,
          jitter, max_tries, jitter_growth, adaptive_jitter, jitter_scale,
          use_trace_logdet_grad, use_hutchinson, hutchinson_n, theta_tol,
          fastpath_options, fastpath_mode, lb, ub) <: FittingMethod

Laplace approximation with Empirical Bayes Estimates (EBE) for random-effects models. The outer optimiser maximises the Laplace-approximated marginal likelihood over the fixed effects, while the inner optimiser computes per-individual MAP estimates of the random effects.

Keyword Arguments

• optimizer: outer Optimization.jl optimiser. Defaults to LBFGS with backtracking.
• optim_kwargs::NamedTuple = NamedTuple(): keyword arguments for the outer solve call.
• adtype: AD backend for the outer optimiser. Defaults to AutoForwardDiff().
• inner_optimizer: inner optimiser for computing EBE modes. Defaults to LBFGS.
• inner_kwargs::NamedTuple = NamedTuple(): keyword arguments for the inner solve call.
• inner_adtype: AD backend for the inner optimiser. Defaults to AutoForwardDiff().
• inner_grad_tol: gradient tolerance for inner convergence (:auto chooses automatically).
• multistart_n::Int = 50: number of random starts for the inner EBE multistart.
• multistart_k::Int = 10: number of best starts to refine in the inner multistart.
• multistart_grad_tol: gradient tolerance for multistart refinement.
• multistart_max_rounds::Int = 1: maximum multistart refinement rounds.
• multistart_sampling::Symbol = :lhs: inner multistart sampling strategy (:lhs or :random).
• jitter::Float64 = 1e-6: initial diagonal jitter added to ensure Hessian PD.
• max_tries::Int = 6: maximum attempts to regularise the Hessian.
• jitter_growth::Float64 = 10.0: multiplicative growth factor for jitter on each retry.
• adaptive_jitter::Bool = true: whether to adapt jitter magnitude based on scale.
• jitter_scale::Float64 = 1e-6: scale for the adaptive jitter.
• use_trace_logdet_grad::Bool = true: use trace estimator for log-determinant gradient.
• use_hutchinson::Bool = false: use Hutchinson estimator instead of Cholesky for log-det.
• hutchinson_n::Int = 8: number of Rademacher vectors for the Hutchinson estimator.
• theta_tol::Float64 = 0.0: fixed-effect change tolerance for EBE caching.
• fastpath_mode::Symbol = :auto: fast-path mode (:auto or :off). In step 4, this enables a Newton-based inner-mode backend for fully eligible models (with a generic polishing pass for ODE models) and falls back to the generic path otherwise.
• lb, ub: bounds on the transformed fixed-effect scale, or nothing.

LaplaceMAP(; optimizer, optim_kwargs, adtype, inner_options, hessian_options,
             cache_options, multistart_options, inner_optimizer, inner_kwargs,
             inner_adtype, inner_grad_tol, multistart_n, multistart_k,
             multistart_grad_tol, multistart_max_rounds, multistart_sampling,
             jitter, max_tries, jitter_growth, adaptive_jitter, jitter_scale,
             use_trace_logdet_grad, use_hutchinson, hutchinson_n, theta_tol,
             fastpath_options, fastpath_mode, lb, ub, ignore_model_bounds) <: FittingMethod

Laplace approximation with MAP-regularised fixed effects for random-effects models. Identical to Laplace but adds the log-prior of the fixed effects to the outer objective, giving a MAP estimate of the fixed effects rather than MLE. Requires prior distributions on at least one free fixed effect.

See Laplace for a description of all keyword arguments. The only difference in defaults is multistart_max_rounds = 5.

MCEM(; optimizer, optim_kwargs, adtype, sampler, turing_kwargs, sample_schedule,
       warm_start, verbose, progress, maxiters, rtol_theta, atol_theta, rtol_Q,
       atol_Q, consecutive_params, ebe_optimizer, ebe_optim_kwargs, ebe_adtype,
       ebe_grad_tol, ebe_multistart_n, ebe_multistart_k, ebe_multistart_max_rounds,
       ebe_multistart_sampling, ebe_rescue_on_high_grad, ebe_rescue_multistart_n,
       ebe_rescue_multistart_k, ebe_rescue_max_rounds, ebe_rescue_grad_tol,
       ebe_rescue_multistart_sampling, lb, ub) <: FittingMethod

Monte Carlo Expectation-Maximisation for random-effects models. At each EM iteration the E-step draws random effects from the posterior using a Turing.jl sampler; the M-step maximises the Monte Carlo Q-function over the fixed effects.

Keyword Arguments

• optimizer: M-step Optimization.jl optimiser. Defaults to LBFGS with backtracking.
• optim_kwargs::NamedTuple = NamedTuple(): keyword arguments for the M-step solve.
• adtype: AD backend for the M-step. Defaults to AutoForwardDiff().
• sampler: Turing-compatible sampler for the E-step. Defaults to NUTS(0.75).
• turing_kwargs::NamedTuple = NamedTuple(): keyword arguments forwarded to Turing.sample.
• sample_schedule::Int = 250: number of MCMC samples per E-step iteration.
• warm_start::Bool = true: initialise sampler from the previous iteration's modes.
• verbose::Bool = false: print per-iteration diagnostics.
• progress::Bool = true: show a progress bar.
• maxiters::Int = 100: maximum number of EM iterations.
• rtol_theta, atol_theta: relative/absolute convergence tolerance on fixed effects.
• rtol_Q, atol_Q: relative/absolute convergence tolerance on the Q-function.
• consecutive_params::Int = 3: number of consecutive iterations satisfying the tolerance required to declare convergence.
• ebe_optimizer, ebe_optim_kwargs, ebe_adtype, ebe_grad_tol: EBE inner optimiser settings used to compute mode starting points.
• ebe_multistart_n, ebe_multistart_k, ebe_multistart_max_rounds, ebe_multistart_sampling: multistart settings for EBE mode computation.
• ebe_rescue_on_high_grad, ebe_rescue_multistart_n, ebe_rescue_multistart_k, ebe_rescue_max_rounds, ebe_rescue_grad_tol, ebe_rescue_multistart_sampling: rescue multistart settings when an EBE mode has a high gradient norm.
• lb, ub: bounds on the transformed fixed-effect scale, or nothing.

SAEM(; optimizer, optim_kwargs, adtype, sampler, turing_kwargs, update_schedule,
       warm_start, verbose, progress, mcmc_steps, max_store, t0, kappa, maxiters,
       rtol_theta, atol_theta, rtol_Q, atol_Q, consecutive_params, suffstats,
       q_from_stats, mstep_closed_form, builtin_stats, builtin_mean,
       resid_var_param, re_cov_params, re_mean_params, ebe_optimizer,
       ebe_optim_kwargs, ebe_adtype, ebe_grad_tol, ebe_multistart_n,
       ebe_multistart_k, ebe_multistart_max_rounds, ebe_multistart_sampling,
       ebe_rescue_on_high_grad, ebe_rescue_multistart_n, ebe_rescue_multistart_k,
       ebe_rescue_max_rounds, ebe_rescue_grad_tol, ebe_rescue_multistart_sampling,
       lb, ub) <: FittingMethod

Stochastic Approximation Expectation-Maximisation for random-effects models. SAEM maintains a stochastic approximation of the sufficient statistics using a decreasing step-size sequence; the M-step updates the fixed effects via gradient-based optimisation or closed-form updates (when builtin_stats is enabled).

Keyword Arguments

• optimizer: M-step Optimization.jl optimiser. Defaults to LBFGS with backtracking.
• optim_kwargs::NamedTuple = NamedTuple(): keyword arguments for the M-step solve.
• adtype: AD backend for the M-step. Defaults to AutoForwardDiff().
• sampler: Turing-compatible sampler. Defaults to MH().
• turing_kwargs::NamedTuple = NamedTuple(): keyword arguments for Turing.sample.
• update_schedule: which parameters to update per iteration (:all or a Vector{Symbol}).
• warm_start::Bool = true: initialise the sampler from the previous iteration's modes.
• verbose::Bool = false: print per-iteration diagnostics.
• progress::Bool = true: show a progress bar.
• mcmc_steps::Int = 80: number of MCMC steps per E-step.
• max_store::Int = 50: size of the sufficient statistic history window.
• t0::Int = 20: burn-in iterations before stochastic approximation averaging begins.
• kappa::Float64 = 0.65: step-size decay exponent for the Robbins-Monro schedule.
• maxiters::Int = 300: maximum number of SAEM iterations.
• rtol_theta, atol_theta: relative/absolute convergence tolerance on fixed effects.
• rtol_Q, atol_Q: relative/absolute convergence tolerance on the Q-function.
• consecutive_params::Int = 4: consecutive iterations satisfying tolerance to converge.
• suffstats: custom sufficient statistics function, or nothing to use the built-in.
• q_from_stats: custom Q-function from sufficient statistics, or nothing.
• mstep_closed_form: custom closed-form M-step function, or nothing.
• builtin_stats: :auto, :on, or :off; controls use of built-in Gaussian statistics.
• builtin_mean: :none, :additive, or :all; controls built-in mean parameterisation.
• resid_var_param::Symbol = :σ: fixed-effect name for the residual standard deviation.
• re_cov_params::NamedTuple = NamedTuple(): mapping of RE name to covariance parameter.
• re_mean_params::NamedTuple = NamedTuple(): mapping of RE name to mean parameter.
• ebe_optimizer, ebe_optim_kwargs, ebe_adtype, ebe_grad_tol: EBE inner optimiser.
• ebe_multistart_n, ebe_multistart_k, ebe_multistart_max_rounds, ebe_multistart_sampling: multistart settings for EBE mode computation.
• ebe_rescue_*: rescue multistart settings when an EBE mode has a high gradient norm.
• lb, ub: bounds on the transformed fixed-effect scale, or nothing.
• mstep_sa_on_params::Bool = false: if true, the numerical M-step uses only the current iteration's random-effect samples (not the ring buffer) as the objective, and applies a Robbins-Monro parameter update θ_new = θ_old + γ*(θ̂ − θ_old) rather than setting θ_new = θ̂ directly. Useful with SaemixMH (whose kernel-1 draws from the prior, so the current-sample Q is well-identified). For Turing-based samplers (MH, NUTS) the ring-buffer default is preferred.

MCMC(; sampler, turing_kwargs, adtype, progress) <: FittingMethod

Bayesian sampling via Turing.jl for models with or without random effects. All free fixed effects and random effects must have prior distributions.

Keyword Arguments

• sampler: Turing-compatible sampler. Defaults to NUTS(0.75).
• turing_kwargs::NamedTuple = NamedTuple(): keyword arguments forwarded to Turing.sample (e.g. n_samples, n_adapt).
• adtype: automatic-differentiation backend. Defaults to AutoForwardDiff().
• progress::Bool = false: whether to display a progress bar during sampling.

Multistart(; dists, n_draws_requested, n_draws_used, sampling, serialization, rng)

Multistart wrapper that runs any optimization-based fitting method from multiple initial parameter vectors and returns the best result.

Starting points are drawn either from the fixed-effect priors or from user-supplied dists; the top-n_draws_used candidates (by a cheap objective evaluation) are then fully optimised.

Keyword Arguments

• dists::NamedTuple = NamedTuple(): per-parameter sampling distributions, keyed by fixed-effect name. Parameters without an entry use their prior, if available.
• n_draws_requested::Int = 100: number of candidate starting points to sample.
• n_draws_used::Int = 50: number of candidates to fully optimise after screening.
• sampling::Symbol = :random: sampling strategy for starting points: :random or :lhs (Latin hypercube sampling).
• serialization::SciMLBase.EnsembleAlgorithm = EnsembleSerial(): parallelisation strategy for running multiple starts.
• rng::AbstractRNG = Random.default_rng(): random-number generator.
• progress::Bool = true: whether to display progress bars for the screening and fitting phases.

MLEResult{S, O, I, R, N} <: MethodResult

Method-specific result from an MLE fit. Stores the solution, objective value, iteration count, raw Optimization.jl result, and optional notes.

MAPResult{S, O, I, R, N} <: MethodResult

Method-specific result from a MAP fit. Stores the solution, objective value, iteration count, raw Optimization.jl result, and optional notes.

LaplaceResult{S, O, I, R, N, B} <: MethodResult

Method-specific result from a Laplace fit. Stores the solution, objective value, iteration count, raw solver result, optional notes, and empirical-Bayes mode estimates for each individual.

LaplaceMAPResult{S, O, I, R, N, B} <: MethodResult

Method-specific result from a LaplaceMAP fit. Stores the solution, objective value, iteration count, raw solver result, optional notes, and empirical-Bayes mode estimates for each individual.

MCEMResult{S, O, I, R, N, B} <: MethodResult

Method-specific result from a MCEM fit. Stores the solution, objective value, iteration count, raw solver result, optional notes, and final empirical-Bayes mode estimates for each individual.

SAEMResult{S, O, I, R, N, B} <: MethodResult

Method-specific result from a SAEM fit. Stores the solution, objective value, iteration count, raw solver result, optional notes, and final empirical-Bayes mode estimates for each individual.

MCMCResult{C, S, A, N, O} <: MethodResult

Method-specific result from a MCMC fit. Stores the MCMCChains chain, sampler, number of samples, optional notes, and observed data columns.

MultistartFitResult{M, R, RE, S, E, B}

Result from a Multistart run. Stores all successful and failed per-start results together with the index of the best (lowest objective) successful start.

Use the accessor functions to retrieve individual components: get_multistart_results, get_multistart_errors, get_multistart_starts, get_multistart_failed_results, get_multistart_failed_starts, get_multistart_best_index, get_multistart_best.

get_params(fe::FixedEffects) -> NamedTuple

Return the raw parameter block structs as a NamedTuple keyed by parameter name.

get_params(res::FitResult; scale=:both) -> FitParameters or ComponentArray

Return the estimated parameter vector.

Keyword Arguments

• scale::Symbol = :both: which scale to return.
  • :both — a FitParameters struct with both scales.
  • :transformed — the optimisation-scale ComponentArray.
  • :untransformed — the natural-scale ComponentArray.

get_objective(res::FitResult) -> Real

Return the final objective value (e.g. negative log-likelihood for MLE).

get_converged(res::FitResult) -> Bool or Nothing

Return the convergence flag. true indicates successful convergence, false indicates failure, and nothing is returned for methods that do not track convergence (e.g. MCMC).

get_diagnostics(res::FitResult) -> FitDiagnostics

Return the FitDiagnostics with timing, optimizer, and convergence details.

get_summary(res::FitResult) -> FitSummary

Return the FitSummary containing objective, convergence flag, and parameters.

get_method(res::FitResult) -> FittingMethod

Return the FittingMethod used to produce this result.

get_result(res::FitResult) -> MethodResult

Return the method-specific MethodResult subtype (e.g. MLEResult, MCMCResult).

get_data_model(res::FitResult) -> DataModel or Nothing

Return the DataModel stored in the fit result, or nothing if the result was created with store_data_model=false.

get_iterations(res::FitResult) -> Int

Return the number of optimiser iterations. Valid for optimisation-based methods (MLE, MAP, Laplace, MCEM, SAEM).

get_raw(res::FitResult)

Return the raw method-specific result object (e.g. the Optim.jl result for MLE/MAP).

get_notes(res::FitResult) -> String or Nothing

Return any method-specific string notes attached to the result.

get_chain(res::FitResult) -> MCMCChains.Chains

Return the MCMC chain. Only valid for results produced by MCMC.

get_observed(res::FitResult)

Return the observed data used during MCMC sampling. Only valid for MCMC results.

get_sampler(res::FitResult)

Return the sampler object (e.g. NUTS) used for MCMC. Only valid for MCMC results.

get_random_effects(dm::DataModel, res::FitResult; constants_re, flatten,
                   include_constants) -> NamedTuple
get_random_effects(res::FitResult; constants_re, flatten, include_constants) -> NamedTuple

Return empirical Bayes (EB) random-effect estimates as a NamedTuple of DataFrames, one per random effect.

Supported methods: Laplace, LaplaceMAP, FOCEI, FOCEIMAP, MCEM, SAEM.

Keyword Arguments

• constants_re::NamedTuple = NamedTuple(): fix random effects at given values (natural scale).
• flatten::Bool = true: if true, expand vector random effects to individual columns.
• include_constants::Bool = true: if true, include constant random effects in the output.

get_loglikelihood(dm::DataModel, res::FitResult; constants_re, ode_args,
                  ode_kwargs, serialization) -> Real
get_loglikelihood(res::FitResult; constants_re, ode_args, ode_kwargs,
                  serialization) -> Real

Compute the marginal log-likelihood at the estimated parameter values.

For MLE/MAP results, evaluates the population log-likelihood. For Laplace/FOCEI results, evaluates using the EB modes stored in the result.

Keyword Arguments

• constants_re::NamedTuple = NamedTuple(): random effects fixed at given values.
• ode_args::Tuple = (): additional positional arguments for the ODE solver.
• ode_kwargs::NamedTuple = NamedTuple(): additional keyword arguments for the ODE solver.
• serialization = EnsembleSerial(): parallelisation strategy.

get_multistart_results(res::MultistartFitResult) -> Vector{FitResult}

Return the FitResult objects for all successful multistart runs.

get_multistart_errors(res::MultistartFitResult) -> Vector

Return the error objects thrown by failed multistart runs.

get_multistart_starts(res::MultistartFitResult) -> Vector

Return the starting parameter vectors (on the untransformed scale) for all successful multistart runs.

get_multistart_failed_results(res::MultistartFitResult) -> Vector

Return any partially-computed FitResult objects from failed multistart runs.

get_multistart_failed_starts(res::MultistartFitResult) -> Vector

Return the starting parameter vectors for all failed multistart runs.

get_multistart_best_index(res::MultistartFitResult) -> Int

Return the index (into get_multistart_results) of the run with the lowest objective value.

get_multistart_best(res::MultistartFitResult) -> FitResult

Return the FitResult with the lowest objective value across all successful multistart runs.

FitResultSummary

Structured summary of a FitResult. Created by summarize(res) or summarize(res, uq). Contains per-parameter rows with estimates and optional standard errors, outcome coverage statistics, and random-effects summaries. Displayed via Base.show.

UQResultSummary

Structured summary of a UQResult. Created by summarize(uq). Contains per-parameter rows with point estimates, standard errors, and confidence/credible intervals. Displayed via Base.show.

default_bounds_from_start(dm::DataModel; margin=1.0) -> (lower, upper)

Generate symmetric box bounds on the transformed parameter scale centred at the initial parameter values, with half-width margin.

Useful for passing to MLE(lb=lower, ub=upper) when the model-declared bounds are too wide or absent.

Keyword Arguments

• margin::Real = 1.0: half-width of the symmetric box on the transformed scale.

compute_uq(res::FitResult; method, interval, vcov, re_approx, re_approx_method,
           level, pseudo_inverse, hessian_backend, fd_abs_step, fd_rel_step,
           fd_max_tries, n_draws, mcmc_warmup, mcmc_draws, constants,
           constants_re, penalty, ode_args, ode_kwargs, serialization,
           profile_method, profile_scan_width, profile_scan_tol, profile_loss_tol,
           profile_local_alg, profile_max_iter, profile_ftol_abs, profile_kwargs,
           mcmc_method, mcmc_sampler, mcmc_turing_kwargs, mcmc_adtype,
           mcmc_fit_kwargs, rng) -> UQResult

Compute uncertainty quantification for the fixed-effect parameters of a fitted model.

Three backends are supported:

• :wald – Wald intervals derived from the inverse Hessian of the objective.
• :chain – Posterior intervals from posterior draws (MCMC chains or VI posterior samples).
• :profile – Profile-likelihood intervals computed by NLopt.

Keyword Arguments

• method::Symbol = :auto: UQ backend. :auto selects :chain for MCMC/VI fits and :wald otherwise; can also be :wald, :chain, :profile, or :mcmc_refit.
• interval::Symbol = :auto: interval type. :auto picks a sensible default per backend. For Wald: :wald or :normal; for chain: :equaltail or :chain; for profile: :profile.
• vcov::Symbol = :hessian: covariance source for Wald UQ (:hessian only).
• re_approx::Symbol = :auto: random-effects approximation for Laplace/FOCEI Hessians.
• re_approx_method: fitting method used for the RE approximation, or nothing.
• level::Real = 0.95: nominal coverage level for the intervals.
• pseudo_inverse::Bool = false: use the Moore-Penrose pseudo-inverse for singular Hessians (Wald only).
• hessian_backend::Symbol = :auto: Hessian computation backend.
• fd_abs_step, fd_rel_step, fd_max_tries: finite-difference Hessian settings.
• n_draws::Int = 2000: number of draws to generate (for the chain and MCMC backends).
• mcmc_warmup, mcmc_draws: chain-draw settings. For MCMC, warm-up and draw count; for VI, mcmc_draws is the posterior sample count (mcmc_warmup ignored).
• constants, constants_re, penalty, ode_args, ode_kwargs, serialization: forwarded to objective evaluations (default: inherit from the source fit result).
• profile_method, profile_scan_width, profile_scan_tol, profile_loss_tol, profile_local_alg, profile_max_iter, profile_ftol_abs, profile_kwargs: NLopt profile-likelihood settings.
• mcmc_method, mcmc_sampler, mcmc_turing_kwargs, mcmc_adtype, mcmc_fit_kwargs: MCMC backend settings.
• rng::AbstractRNG = Random.default_rng(): random-number generator.

Returns

A UQResult with point estimates, intervals, covariance matrices, and draws.

UQResult

Result from compute_uq. Stores parameter uncertainty quantification on both the natural and transformed scales.

Use the accessor functions to retrieve individual components: get_uq_backend, get_uq_source_method, get_uq_parameter_names, get_uq_estimates, get_uq_intervals, get_uq_vcov, get_uq_draws, get_uq_diagnostics.

Fields:

• backend::Symbol: UQ backend used (:wald, :chain, or :profile).
• source_method::Symbol: estimation method of the source fit result.
• parameter_names::Vector{Symbol}: names on the transformed scale.
• parameter_names_natural::Union{Nothing, Vector{Symbol}}: names on the natural scale, or nothing if identical to parameter_names. For ProbabilityVector and DiscreteTransitionMatrix parameters the Wald backend extends the natural scale with the derived last probability / last-column entries, giving more names than the transformed scale.
• estimates_transformed, estimates_natural: point estimates on each scale.
• intervals_transformed, intervals_natural: UQIntervals or nothing.
• vcov_transformed, vcov_natural: variance-covariance matrices or nothing.
• draws_transformed, draws_natural: posterior/bootstrap draws (nparams × ndraws) or nothing.
• diagnostics::NamedTuple: backend-specific diagnostic information.

UQIntervals

Confidence or credible intervals at a given coverage level for a set of parameters.

Fields:

• level::Float64: nominal coverage level (e.g. 0.95 for 95% intervals).
• lower::Vector{Float64}: lower bounds in the order given by the parent UQResult.
• upper::Vector{Float64}: upper bounds in the order given by the parent UQResult.

get_uq_backend(uq::UQResult) -> Symbol

Return the UQ backend used (:wald, :chain, or :profile).

get_uq_source_method(uq::UQResult) -> Symbol

Return the symbol identifying the estimation method of the source fit result.

get_uq_parameter_names(uq::UQResult; scale=:transformed) -> Vector{Symbol}

Return the names of the free fixed-effect parameters covered by this result.

Keyword Arguments

• scale::Symbol = :transformed: :transformed (default) or :natural. For the Wald backend with ProbabilityVector or DiscreteTransitionMatrix parameters, the natural scale includes the derived last probability / last-column entries and may have more names than the transformed scale.

get_uq_estimates(uq::UQResult; scale=:natural, as_component=true)

Return point estimates from a UQResult.

Keyword Arguments

• scale::Symbol = :natural: :natural for the untransformed scale, :transformed for the optimisation scale.
• as_component::Bool = true: if true, return a ComponentArray keyed by parameter name; otherwise return a plain Vector{Float64}.

get_uq_intervals(uq::UQResult; scale=:natural, as_component=true)
-> NamedTuple{(:level, :lower, :upper)} or nothing

Return confidence/credible intervals from a UQResult, or nothing if not available.

Keyword Arguments

• scale::Symbol = :natural: :natural or :transformed.
• as_component::Bool = true: if true, lower and upper are ComponentArrays; otherwise plain Vector{Float64}.

get_uq_vcov(uq::UQResult; scale=:natural) -> Matrix{Float64} or nothing

Return the variance-covariance matrix from a UQResult, or nothing if not available.

Keyword Arguments

• scale::Symbol = :natural: :natural or :transformed.

get_uq_draws(uq::UQResult; scale=:natural) -> Matrix{Float64} or nothing

Return the posterior or bootstrap draws (nparams × ndraws) from a UQResult, or nothing if not available.

Keyword Arguments

• scale::Symbol = :natural: :natural or :transformed.

get_uq_diagnostics(uq::UQResult) -> NamedTuple

Return backend-specific diagnostic information from the UQ computation.

simulate_data(dm::DataModel; rng, replace_missings, serialization) -> DataFrame

Simulate observations from a DataModel using the model's initial parameter values.

Random effects are drawn from their prior distributions and observation columns are replaced with draws from the model's observation distributions. Non-observation columns are left unchanged.

Keyword Arguments

• rng::AbstractRNG = Random.default_rng(): random-number generator.
• replace_missings::Bool = false: if true, fill missing observation entries with simulated values; otherwise leave them as missing.
• serialization::SciMLBase.EnsembleAlgorithm = EnsembleSerial(): parallelisation strategy (e.g. EnsembleThreads()).

Returns

A copy of dm.df with simulated observation values.

simulate_data_model(dm::DataModel; rng, replace_missings, serialization) -> DataModel

Simulate observations from a DataModel and return a new DataModel wrapping the simulated data.

Calls simulate_data and constructs a fresh DataModel from the resulting DataFrame, preserving the original model, id columns, and serialization settings.

Keyword Arguments

• rng::AbstractRNG = Random.default_rng(): random-number generator.
• replace_missings::Bool = false: forwarded to simulate_data.
• serialization::SciMLBase.EnsembleAlgorithm: parallelisation strategy; defaults to the strategy stored in dm.

identifiability_report(dm::DataModel; method, at, constants, constants_re, penalty,
                       ode_args, ode_kwargs, serialization, rng, rng_seed, atol, rtol,
                       hessian_backend, fd_abs_step, fd_rel_step, fd_max_tries)
                       -> IdentifiabilityReport

identifiability_report(res::FitResult; method, at, constants, constants_re, penalty,
                       ode_args, ode_kwargs, serialization, rng, rng_seed, atol, rtol,
                       hessian_backend, fd_abs_step, fd_rel_step, fd_max_tries)
                       -> IdentifiabilityReport

Compute a local identifiability report by evaluating the Hessian of the chosen objective at a specified parameter point and checking its rank.

When called with a DataModel, the starting values from the model definition are used by default (at=:start). When called with a FitResult, the fitted parameter estimates are used by default (at=:fit).

Keyword Arguments

• method::Union{Symbol, FittingMethod} = :auto: estimation method whose objective is used. :auto selects MLE for models without random effects and Laplace otherwise. Supported symbols: :mle, :map, :laplace, :laplace_map, :focei, :focei_map.
• at::Union{Symbol, ComponentArray} = :start: evaluation point. :start uses the model initial values, :fit uses the fitted estimates (only for the FitResult method), or a ComponentArray of untransformed parameter values.
• constants, constants_re, penalty, ode_args, ode_kwargs, serialization, rng: forwarded to the objective; see fit_model for descriptions.
• rng_seed::Union{Nothing, UInt64} = nothing: optional fixed seed for reproducibility.
• atol::Real = 1e-8: absolute tolerance for Hessian rank determination.
• rtol::Real = sqrt(eps(Float64)): relative tolerance for Hessian rank determination.
• hessian_backend::Symbol = :auto: Hessian computation backend. :auto tries ForwardDiff then finite differences.
• fd_abs_step::Real = 1e-4: absolute finite-difference step size.
• fd_rel_step::Real = 1e-3: relative finite-difference step size.
• fd_max_tries::Int = 8: maximum step-size retry attempts for finite differences.

Returns

An IdentifiabilityReport with the Hessian, its spectral decomposition, a local identifiability verdict, and any null directions.

IdentifiabilityReport{U, T, S}

Result of identifiability_report. Contains the Hessian of the objective at the evaluation point, its spectral decomposition, and a local identifiability verdict.

Fields:

• method::Symbol: estimation method used (e.g. :mle, :laplace).
• objective::Symbol: objective evaluated (:nll, :map, or :laplace_nll).
• at::Symbol: where the Hessian was evaluated (:start or :fit).
• point_untransformed: parameter values on the natural scale.
• point_transformed: parameter values on the transformed scale.
• free_parameters::Vector{Symbol}: names of the free (non-constant) parameters.
• hessian::Matrix{Float64}: Hessian of the objective on the transformed scale.
• singular_values, eigenvalues: spectral decomposition of the Hessian.
• rank::Int, nullity::Int: numerical rank and null-space dimension.
• tolerance::Float64: tolerance used for rank determination.
• condition_number::Float64: ratio of the largest to smallest singular value.
• locally_identifiable::Bool: true if the Hessian has full rank (nullity = 0).
• null_directions::Vector{NullDirection}: directions of non-identifiability.
• random_effect_information::Vector{RandomEffectInformation}: per-batch RE information.
• settings::S: NamedTuple of the tolerances and backend settings used.

NullDirection{L}

A direction in the fixed-effect parameter space along which the objective function is (numerically) flat, indicating a potential non-identifiability.

Fields:

• singular_value::Float64: the singular value associated with this direction.
• vector::Vector{Float64}: the null-space direction on the transformed scale.
• loadings::L: per-parameter loadings showing which parameters contribute to the direction.

RandomEffectInformation

Fisher information analysis of the random-effects contribution for a single batch of individuals, as computed within identifiability_report.

Fields:

• batch::Int: batch index.
• n_latent::Int: number of latent (random-effect) dimensions in the batch.
• labels::Vector{String}: human-readable labels for each latent dimension.
• singular_values::Vector{Float64}: singular values of the RE information matrix.
• eigenvalues::Vector{Float64}: eigenvalues of the RE information matrix.
• rank::Int: numerical rank.
• nullity::Int: dimension of the null space.
• tolerance::Float64: tolerance used for rank determination.
• condition_number::Float64: ratio of the largest to smallest eigenvalue.
• positive_definite::Bool: whether the information matrix is numerically PD.

PlotStyle(; color_primary, color_secondary, color_accent, color_dark,
           color_density, color_reference, font_family, font_size_title,
           font_size_label, font_size_tick, font_size_legend,
           font_size_annotation, line_width_primary, line_width_secondary,
           comparison_default_linestyle, comparison_line_styles, marker_size,
           marker_size_small, marker_alpha, marker_stroke_width,
           marker_size_pmf, marker_stroke_width_pmf,
           base_subplot_width, base_subplot_height)

Visual style configuration for all NoLimits plotting functions.

All plotting functions accept a style::PlotStyle keyword argument. Construct a PlotStyle() with the defaults and override individual fields as needed.

Keyword Arguments

• color_primary::String: main series colour (default: "#0072B2" — blue).
• color_secondary::String: secondary series colour (default: "#E69F00" — orange).
• color_accent::String: accent colour (default: "#009E73" — green).
• color_dark::String: dark foreground colour (default: "#2C3E50").
• color_density::String: colour for density bands (default: "#E69F00").
• color_reference::String: reference line colour (default: "#2C3E50").
• font_family::String: font family for all text (default: "Helvetica").
• font_size_title, font_size_label, font_size_tick, font_size_legend, font_size_annotation: font sizes in points.
• line_width_primary, line_width_secondary: line widths in pixels.
• comparison_default_linestyle, comparison_line_styles: line style overrides for plot_fits_comparison.
• marker_size, marker_size_small, marker_alpha, marker_stroke_width: marker appearance for continuous outcomes.
• marker_size_pmf, marker_stroke_width_pmf: marker appearance for discrete outcomes.
• base_subplot_width, base_subplot_height: base pixel dimensions per subplot panel.

PlotCache{S, O, C, P, R, M}

Pre-computed plotting cache for efficient repeated rendering of model predictions.

Create via build_plot_cache and pass to plot_fits via the cache keyword argument to avoid re-solving the ODE or re-evaluating formulas on each call.

build_plot_cache(res::FitResult; dm, params, constants_re, cache_obs_dists,
                 ode_args, ode_kwargs, mcmc_draws, mcmc_warmup, rng) -> PlotCache

build_plot_cache(res::MultistartFitResult; kwargs...) -> PlotCache

build_plot_cache(dm::DataModel; params, constants_re, cache_obs_dists,
                 ode_args, ode_kwargs, rng) -> PlotCache

Pre-compute ODE solutions and (optionally) observation distributions for fast repeated plotting. Pass the returned PlotCache to plot_fits via the cache keyword.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• params::NamedTuple = NamedTuple(): fixed-effect overrides applied before caching.
• constants_re::NamedTuple = NamedTuple(): random-effect constants.
• cache_obs_dists::Bool = false: also pre-compute observation distributions.
• ode_args::Tuple = (), ode_kwargs::NamedTuple = NamedTuple(): forwarded to the ODE solver.
• mcmc_draws::Int = 1000: number of MCMC draws to use for chain-based fits.
• mcmc_warmup::Union{Nothing, Int} = nothing: warm-up count override for MCMC.
• rng::AbstractRNG = Random.default_rng(): random-number generator.

plot_data(res::FitResult; dm, x_axis_feature, individuals_idx, shared_x_axis,
          shared_y_axis, ncols, style, kwargs_subplot, kwargs_layout,
          save_path, plot_path, marginal_layout) -> Plots.Plot | Vector{Plots.Plot}

plot_data(dm::DataModel; x_axis_feature, individuals_idx, shared_x_axis,
          shared_y_axis, ncols, style, kwargs_subplot, kwargs_layout,
          save_path, plot_path, marginal_layout) -> Plots.Plot | Vector{Plots.Plot}

Plot raw observed data for each individual as a multi-panel figure.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• x_axis_feature::Union{Symbol, Nothing} = nothing: covariate to use as the x-axis; defaults to the time column.
• individuals_idx: indices or IDs of individuals to include, or nothing for all.
• shared_x_axis::Bool = true: share the x-axis range across panels.
• shared_y_axis::Bool = true: share the y-axis range across panels.
• ncols::Int = 3: number of subplot columns.
• marginal_layout::Symbol = :single: :single keeps one figure with every marginal overlaid per individual; :vector returns a figure per marginal (only valid for vector-valued observables and requires save_path/plot_path to be nothing).
• style::PlotStyle = PlotStyle(): visual style configuration.
• marginal_layout::Symbol = :single: :single produces one figure with subplots per individual showing every marginal; :vector returns a figure per marginal (only valid when the observable is vector-valued and requires save_path and plot_path to be nothing).
• kwargs_subplot, kwargs_layout: extra keyword arguments for subplots and layout.
• save_path::Union{Nothing, String} = nothing: file path to save the plot (ignored for :vector mode).

plot_fits(res::FitResult; dm, plot_density, plot_func, plot_data_points, observable,
          individuals_idx, x_axis_feature, shared_x_axis, shared_y_axis, ncols,
          style, kwargs_subplot, kwargs_layout, save_path, cache, params,
          constants_re, cache_obs_dists, plot_mcmc_quantiles, mcmc_quantiles,
          mcmc_quantiles_alpha, mcmc_draws, mcmc_warmup, rng) -> Plots.Plot

plot_fits(dm::DataModel; params, constants_re, observable, individuals_idx,
          x_axis_feature, shared_x_axis, shared_y_axis, ncols, plot_data_points,
          style, kwargs_subplot, kwargs_layout, save_path, cache) -> Plots.Plot

Plot model predictions against observed data for each individual as a multi-panel figure.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• plot_density::Bool = false: overlay the predictive distribution density.
• plot_func = mean: function applied to the predictive distribution to obtain the prediction line (e.g. mean, median).
• plot_data_points::Bool = true: overlay the observed data points.
• observable: name of the outcome variable to plot, or nothing to use the first.
• individuals_idx: indices or IDs of individuals to include, or nothing for all.
• x_axis_feature::Union{Nothing, Symbol} = nothing: covariate for the x-axis.
• shared_x_axis::Bool = true, shared_y_axis::Bool = true: share axis ranges.
• ncols::Int = 3: number of subplot columns.
• style::PlotStyle = PlotStyle(): visual style configuration.
• kwargs_subplot, kwargs_layout: extra keyword arguments for subplots and layout.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.
• cache::Union{Nothing, PlotCache} = nothing: pre-computed plot cache.
• params::NamedTuple = NamedTuple(): fixed-effect overrides.
• constants_re::NamedTuple = NamedTuple(): random-effect constants.
• cache_obs_dists::Bool = false: pre-compute observation distributions when building cache.
• plot_mcmc_quantiles::Bool = false: plot posterior predictive quantile bands (MCMC).
• mcmc_quantiles::Vector = [5, 95]: quantile percentages for posterior bands.
• mcmc_quantiles_alpha::Float64 = 0.8: opacity of the quantile band.
• mcmc_draws::Int = 1000: number of MCMC draws for posterior predictive plotting.
• mcmc_warmup::Union{Nothing, Int} = nothing: warm-up count override for MCMC.
• rng::AbstractRNG = Random.default_rng(): random-number generator.

plot_fits_comparison(res::Union{FitResult, MultistartFitResult}; kwargs...)
                     -> Plots.Plot

plot_fits_comparison(results::AbstractVector; kwargs...) -> Plots.Plot

plot_fits_comparison(results::NamedTuple; kwargs...) -> Plots.Plot

plot_fits_comparison(results::AbstractDict; kwargs...) -> Plots.Plot

Plot predictions from one or more fitted models side-by-side for visual comparison.

When called with a single FitResult or MultistartFitResult, behaves like plot_fits. When called with a collection, overlays predictions from each model on the same panel, labelled by vector index, NamedTuple key, or Dict key.

All keyword arguments are forwarded to the underlying plot_fits implementation.

plot_vpc(res::FitResult; dm, n_simulations, n_sim, percentiles, show_obs_points,
         show_obs_percentiles, n_bins, seed, observables, x_axis_feature, ncols,
         kwargs_plot, save_path, obs_percentiles_mode, bandwidth,
         obs_percentiles_method, constants_re, mcmc_draws, mcmc_warmup, style)
         -> Plots.Plot

Visual Predictive Check (VPC): compares observed percentile bands to simulated predictive percentile bands stratified by x-axis bins.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• n_simulations::Int = 100: number of simulated datasets for the VPC envelopes.
• percentiles::Vector = [5, 50, 95]: percentiles to display (in [0, 100]).
• show_obs_points::Bool = true: overlay observed data points.
• show_obs_percentiles::Bool = true: overlay observed percentile lines.
• n_bins::Union{Nothing, Int} = nothing: number of x-axis bins; nothing for auto.
• seed::Int = 12345: random seed for reproducible simulations.
• observables: outcome name(s) to plot, or nothing for all.
• x_axis_feature::Union{Nothing, Symbol} = nothing: covariate for the x-axis; defaults to time.
• ncols::Int = 3: number of subplot columns.
• kwargs_plot: extra keyword arguments forwarded to the plot.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.
• obs_percentiles_mode::Symbol = :pooled: :pooled or :individual percentile computation.
• bandwidth::Union{Nothing, Float64} = nothing: smoothing bandwidth for percentile curves, or nothing for no smoothing.
• obs_percentiles_method::Symbol = :quantile: :quantile or :weighted.
• constants_re::NamedTuple = NamedTuple(): random-effect constants.
• mcmc_draws::Int = 1000, mcmc_warmup: MCMC draw settings.
• style::PlotStyle = PlotStyle(): visual style configuration.

get_residuals(res::FitResult; dm, cache, observables, individuals_idx, obs_rows,
              x_axis_feature, params, constants_re, cache_obs_dists, residuals,
              fitted_stat, randomize_discrete, cdf_fallback_mc, ode_args,
              ode_kwargs, mcmc_draws, mcmc_warmup, mcmc_quantiles, rng,
              return_draw_level) -> DataFrame

get_residuals(dm::DataModel; params, constants_re, observables, individuals_idx,
              obs_rows, x_axis_feature, cache, cache_obs_dists, residuals,
              fitted_stat, randomize_discrete, cdf_fallback_mc, ode_args,
              ode_kwargs, rng) -> DataFrame

Compute residuals for each observation and return a DataFrame.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• cache::Union{Nothing, PlotCache} = nothing: pre-computed plot cache.
• observables: outcome name(s) to include, or nothing for all.
• individuals_idx: individuals to include, or nothing for all.
• obs_rows: specific observation row indices to include, or nothing for all.
• x_axis_feature::Union{Nothing, Symbol} = nothing: covariate for the x column.
• params::NamedTuple = NamedTuple(): fixed-effect overrides.
• constants_re::NamedTuple = NamedTuple(): random-effect constants.
• cache_obs_dists::Bool = true: cache observation distributions.
• residuals: residual metrics to compute. Allowed: :pit, :quantile, :raw, :pearson, :logscore.
• fitted_stat = mean: statistic applied to the predictive distribution for raw residuals.
• randomize_discrete::Bool = true: randomise PIT values for discrete outcomes.
• cdf_fallback_mc::Int = 0: MC samples for CDF approximation with non-analytic distributions.
• ode_args::Tuple = (), ode_kwargs::NamedTuple = NamedTuple(): forwarded to ODE solver.
• mcmc_draws::Int = 1000, mcmc_warmup: MCMC draw settings.
• mcmc_quantiles::Vector = [5, 95]: percentiles for MCMC residual uncertainty bands.
• rng::AbstractRNG = Random.default_rng(): random-number generator.
• return_draw_level::Bool = false: if true, return draw-level residuals for MCMC.

plot_residuals(res::FitResult; dm, cache, residual, observables, individuals_idx,
               obs_rows, x_axis_feature, shared_x_axis, shared_y_axis, ncols,
               style, params, constants_re, cache_obs_dists, fitted_stat,
               randomize_discrete, cdf_fallback_mc, ode_args, ode_kwargs,
               mcmc_draws, mcmc_warmup, mcmc_quantiles, rng, save_path,
               kwargs_subplot, kwargs_layout) -> Plots.Plot

plot_residuals(dm::DataModel; ...) -> Plots.Plot

Plot residuals versus time (or another x-axis feature) for each individual.

Keyword Arguments

• residual::Symbol = :quantile: residual metric to plot. One of :pit, :quantile, :raw, :pearson, :logscore.
• All other arguments are forwarded to get_residuals; see that function for descriptions.
• shared_x_axis::Bool = true, shared_y_axis::Bool = true: share axis ranges.
• ncols::Int = 3: number of subplot columns.
• style::PlotStyle = PlotStyle(): visual style configuration.
• kwargs_subplot, kwargs_layout: extra keyword arguments for subplots and layout.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.

plot_residual_distribution(res::FitResult; dm, cache, residual, observables,
                           individuals_idx, obs_rows, x_axis_feature,
                           shared_x_axis, shared_y_axis, ncols, style, bins,
                           params, constants_re, cache_obs_dists, fitted_stat,
                           randomize_discrete, cdf_fallback_mc, ode_args,
                           ode_kwargs, mcmc_draws, mcmc_warmup, mcmc_quantiles,
                           rng, save_path, kwargs_subplot, kwargs_layout)
                           -> Plots.Plot

plot_residual_distribution(dm::DataModel; ...) -> Plots.Plot

Plot the marginal distribution of residuals as histograms with optional density overlays.

Keyword Arguments

• residual::Symbol = :quantile: residual metric (:pit, :quantile, :raw, :pearson, :logscore).
• bins::Int = 20: number of histogram bins.
• All other arguments are forwarded to get_residuals.

plot_residual_qq(res::FitResult; dm, cache, residual, observables, individuals_idx,
                 obs_rows, x_axis_feature, ncols, style, params, constants_re,
                 cache_obs_dists, fitted_stat, randomize_discrete, cdf_fallback_mc,
                 ode_args, ode_kwargs, mcmc_draws, mcmc_warmup, mcmc_quantiles,
                 rng, save_path, kwargs_subplot, kwargs_layout) -> Plots.Plot

plot_residual_qq(dm::DataModel; ...) -> Plots.Plot

Quantile-quantile plot of residuals against the theoretical distribution (Uniform for :pit, Normal for other metrics).

Keyword Arguments

• residual::Symbol = :quantile: residual metric (:pit, :quantile, :raw, :pearson, :logscore).
• All other arguments are forwarded to get_residuals.

plot_residual_pit(res::FitResult; dm, cache, observables, individuals_idx, obs_rows,
                  x_axis_feature, show_hist, show_kde, show_qq, ncols, style,
                  kde_bandwidth, params, constants_re, cache_obs_dists,
                  randomize_discrete, cdf_fallback_mc, ode_args, ode_kwargs,
                  mcmc_draws, mcmc_warmup, rng, save_path, kwargs_subplot,
                  kwargs_layout) -> Plots.Plot

plot_residual_pit(dm::DataModel; ...) -> Plots.Plot

Plot the probability integral transform (PIT) values as histograms and/or KDE curves. Uniform PIT values indicate a well-calibrated model.

Keyword Arguments

• show_hist::Bool = true: show a histogram of PIT values.
• show_kde::Bool = false: overlay a kernel density estimate.
• show_qq::Bool = false: add a uniform QQ reference line.
• kde_bandwidth::Union{Nothing, Float64} = nothing: KDE bandwidth, or nothing for auto.
• All other arguments are forwarded to get_residuals.

plot_residual_acf(res::FitResult; dm, cache, residual, observables, individuals_idx,
                  obs_rows, x_axis_feature, max_lag, ncols, style, params,
                  constants_re, cache_obs_dists, fitted_stat, randomize_discrete,
                  cdf_fallback_mc, ode_args, ode_kwargs, mcmc_draws, mcmc_warmup,
                  mcmc_quantiles, rng, save_path, kwargs_subplot, kwargs_layout)
                  -> Plots.Plot

plot_residual_acf(dm::DataModel; ...) -> Plots.Plot

Plot the autocorrelation function (ACF) of residuals across time lags for each outcome.

Keyword Arguments

• residual::Symbol = :quantile: residual metric (:pit, :quantile, :raw, :pearson, :logscore).
• max_lag::Int = 5: maximum lag to compute and display.
• All other arguments are forwarded to get_residuals.

plot_random_effects_pdf(res::FitResult; dm, re_names, levels, individuals_idx,
                        shared_x_axis, shared_y_axis, ncols, style, mcmc_draws,
                        mcmc_warmup, mcmc_quantiles, mcmc_quantiles_alpha,
                        flow_samples, flow_plot, flow_bins, flow_bandwidth, rng,
                        save_path, kwargs_subplot, kwargs_layout) -> Plots.Plot

Plot the fitted marginal PDF of each random effect alongside the posterior EBE histogram, showing how well the parametric distribution fits the estimated random-effect values.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• re_names: random-effect name(s) to include, or nothing for all.
• levels, individuals_idx: grouping level or individual filters.
• shared_x_axis::Bool = true, shared_y_axis::Bool = true: share axes.
• ncols::Int = 3: number of subplot columns.
• style::PlotStyle = PlotStyle(): visual style configuration.
• mcmc_draws, mcmc_warmup, mcmc_quantiles, mcmc_quantiles_alpha: MCMC settings.
• flow_samples::Int = 500: number of samples for normalizing-flow distributions.
• flow_plot::Symbol = :kde: :kde or :hist for flow-based distributions.
• flow_bins::Int = 20, flow_bandwidth: histogram bins / KDE bandwidth for flows.
• rng::AbstractRNG = Random.default_rng(): random-number generator.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.
• kwargs_subplot, kwargs_layout: extra keyword arguments for subplots and layout.

plot_random_effects_scatter(res::FitResult; dm, re_names, levels, individuals_idx,
                            x_covariate, mcmc_draws, ncols, style, save_path,
                            kwargs_subplot, kwargs_layout) -> Plots.Plot

Scatter plot of empirical-Bayes estimates for each random effect against a constant covariate or group level index, useful for detecting covariate relationships.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• re_names: random-effect name(s) to include, or nothing for all.
• levels, individuals_idx: grouping level or individual filters.
• x_covariate::Union{Nothing, Symbol} = nothing: constant covariate for the x-axis; defaults to the group level index.
• mcmc_draws::Int = 1000: MCMC draws for posterior mean EBE.
• ncols::Int = 3: number of subplot columns.
• style::PlotStyle = PlotStyle(): visual style configuration.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.
• kwargs_subplot, kwargs_layout: extra keyword arguments.

plot_random_effect_pairplot(res::FitResult; dm, re_names, levels, individuals_idx,
                            ncols, style, kde_bandwidth, mcmc_draws, rng, save_path,
                            kwargs_subplot, kwargs_layout) -> Plots.Plot

Pairplot (scatter matrix) of empirical-Bayes estimates across all pairs of random effects, useful for visualising correlations and joint structure.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• re_names: random-effect names to include, or nothing for all.
• levels, individuals_idx: grouping level or individual filters.
• ncols::Int = 3: number of subplot columns.
• style::PlotStyle = PlotStyle(): visual style configuration.
• kde_bandwidth::Union{Nothing, Float64} = nothing: KDE bandwidth for diagonal panels.
• mcmc_draws::Int = 1000: MCMC draws for posterior mean EBE.
• rng::AbstractRNG = Random.default_rng(): random-number generator.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.
• kwargs_subplot, kwargs_layout: extra keyword arguments.

plot_random_effect_distributions(res::FitResult; dm, re_names, levels,
                                 individuals_idx, shared_x_axis, shared_y_axis,
                                 ncols, style, mcmc_draws, mcmc_warmup,
                                 mcmc_quantiles, mcmc_quantiles_alpha, flow_samples,
                                 flow_plot, flow_bins, flow_bandwidth, rng,
                                 save_path, kwargs_subplot, kwargs_layout)
                                 -> Plots.Plot

Plot empirical and fitted distributions for each random effect side-by-side, combining the EBE histogram with the parametric prior PDF.

Keyword Arguments

All arguments are identical to plot_random_effects_pdf.

plot_random_effect_pit(res::FitResult; dm, re_names, levels, individuals_idx,
                       show_hist, show_kde, show_qq, shared_x_axis, shared_y_axis,
                       ncols, style, kde_bandwidth, mcmc_draws, mcmc_warmup,
                       mcmc_quantiles, mcmc_quantiles_alpha, flow_samples, rng,
                       save_path, kwargs_subplot, kwargs_layout) -> Plots.Plot

Plot the probability integral transform (PIT) of empirical-Bayes estimates under their fitted prior distributions, providing a calibration check for the random-effects model.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• re_names: random-effect names to include, or nothing for all.
• levels, individuals_idx: grouping level or individual filters.
• show_hist::Bool = true: show a PIT histogram.
• show_kde::Bool = false: overlay a KDE curve.
• show_qq::Bool = true: add a Uniform QQ reference line.
• shared_x_axis::Bool = true, shared_y_axis::Bool = true: share axes.
• ncols::Int = 3: number of subplot columns.
• style::PlotStyle = PlotStyle(): visual style configuration.
• kde_bandwidth::Union{Nothing, Float64} = nothing: KDE bandwidth.
• mcmc_draws, mcmc_warmup, mcmc_quantiles, mcmc_quantiles_alpha: MCMC settings.
• flow_samples::Int = 500: samples for normalizing-flow distributions.
• rng::AbstractRNG = Random.default_rng(): random-number generator.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.
• kwargs_subplot, kwargs_layout: extra keyword arguments.

plot_random_effect_standardized(res::FitResult; dm, re_names, levels,
                                individuals_idx, show_hist, show_kde, kde_bandwidth,
                                mcmc_draws, flow_samples, ncols, style, save_path,
                                kwargs_subplot, kwargs_layout) -> Plots.Plot

Plot standardised (z-score) empirical-Bayes estimates for each random effect as a histogram and/or KDE, with a standard Normal reference. Values far from zero indicate outliers or misspecification.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• re_names: random-effect names to include, or nothing for all.
• levels, individuals_idx: grouping level or individual filters.
• show_hist::Bool = true: show a histogram.
• show_kde::Bool = false: overlay a KDE curve.
• kde_bandwidth::Union{Nothing, Float64} = nothing: KDE bandwidth.
• mcmc_draws::Int = 1000: MCMC draws for posterior mean EBE.
• flow_samples::Int = 500: samples for normalizing-flow distributions.
• ncols::Int = 3: number of subplot columns.
• style::PlotStyle = PlotStyle(): visual style configuration.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.
• kwargs_subplot, kwargs_layout: extra keyword arguments.

plot_random_effect_standardized_scatter(res::FitResult; dm, re_names, levels,
                                        individuals_idx, x_covariate, mcmc_draws,
                                        flow_samples, ncols, style, save_path,
                                        kwargs_subplot, kwargs_layout) -> Plots.Plot

Scatter plot of standardised (z-score) empirical-Bayes estimates against a covariate or group level index. Useful for detecting systematic patterns in the residual structure of the random-effects model.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• re_names: random-effect names to include, or nothing for all.
• levels, individuals_idx: grouping level or individual filters.
• x_covariate::Union{Nothing, Symbol} = nothing: constant covariate for the x-axis.
• mcmc_draws::Int = 1000: MCMC draws for posterior mean EBE.
• flow_samples::Int = 500: samples for normalizing-flow distributions.
• ncols::Int = 3: number of subplot columns.
• style::PlotStyle = PlotStyle(): visual style configuration.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.
• kwargs_subplot, kwargs_layout: extra keyword arguments.

plot_observation_distributions(res::FitResult; dm, individuals_idx, obs_rows,
                               observables, x_axis_feature, shared_x_axis,
                               shared_y_axis, ncols, style, cache, cache_obs_dists,
                               constants_re, mcmc_quantiles, mcmc_quantiles_alpha,
                               mcmc_draws, mcmc_warmup, rng, save_path,
                               kwargs_subplot, kwargs_layout) -> Plots.Plot

Plot the predictive observation distributions at each time point as density or PMF curves overlaid on the observed data, providing a detailed look at model calibration.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• individuals_idx: individuals to include (default: first individual only).
• obs_rows: specific observation row indices, or nothing for all.
• observables: outcome name(s) to include, or nothing for first.
• x_axis_feature::Union{Nothing, Symbol} = nothing: covariate for the x-axis.
• shared_x_axis::Bool = true, shared_y_axis::Bool = true: share axes.
• ncols::Int = 3: number of subplot columns.
• style::PlotStyle = PlotStyle(): visual style configuration.
• cache::Union{Nothing, PlotCache} = nothing: pre-computed plot cache.
• cache_obs_dists::Bool = false: pre-compute observation distributions when building cache.
• constants_re::NamedTuple = NamedTuple(): random-effect constants.
• mcmc_quantiles, mcmc_quantiles_alpha, mcmc_draws, mcmc_warmup: MCMC settings.
• rng::AbstractRNG = Random.default_rng(): random-number generator.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.
• kwargs_subplot, kwargs_layout: extra keyword arguments.

plot_uq_distributions(uq::UQResult;
                      scale=:natural,
                      parameters=nothing,
                      interval_alpha=0.22,
                      histogram_alpha=0.45,
                      show_estimate=true,
                      show_interval=true,
                      show_legend=false,
                      bins=:auto,
                      plot_type=:density,
                      kde_bandwidth=nothing,
                      ncols=3,
                      style=PlotStyle(),
                      kwargs_subplot=NamedTuple(),
                      kwargs_layout=NamedTuple(),
                      save_path=nothing)

Plot marginal parameter distributions from a UQResult.

For :chain and :mcmc_refit backends, draws are shown as a KDE or histogram. For the :wald backend, analytic Gaussian approximations are plotted where the parameter is on a transformed scale; otherwise KDE is used. Point estimates and credible/confidence intervals are overlaid as vertical lines and shaded regions.

Arguments

• uq::UQResult - Uncertainty quantification result from compute_uq.

Keyword Arguments

• scale::Symbol - Parameter scale for display: :natural (default) or :transformed.
• parameters - Symbol, vector of Symbols, or nothing (all parameters, default).
• interval_alpha::Float64 - Opacity of the shaded interval region (default: 0.22).
• histogram_alpha::Float64 - Opacity of histogram bars (default: 0.45).
• show_estimate::Bool - Show point estimate as a vertical line (default: true).
• show_interval::Bool - Shade the credible/confidence interval (default: true).
• show_legend::Bool - Show plot legend (default: false).
• bins - Histogram bin count or :auto (default).
• plot_type::Symbol - :density (KDE, default) or :histogram.
• kde_bandwidth::Union{Nothing, Float64} - KDE bandwidth; nothing uses automatic selection (default).
• ncols::Int - Number of subplot columns (default: 3).
• style::PlotStyle - Visual style configuration.
• kwargs_subplot - Extra keyword arguments forwarded to each subplot.
• kwargs_layout - Extra keyword arguments forwarded to the layout call.
• save_path::Union{Nothing, String} - File path to save the plot, or nothing.

Returns

A Plots.jl plot object showing one panel per selected parameter.

plot_multistart_waterfall(res::MultistartFitResult; style, kwargs_subplot, save_path)
-> Plots.Plot

Plot the objective values of all successful multistart runs in ascending order (waterfall plot), highlighting the best run.

Keyword Arguments

• style::PlotStyle = PlotStyle(): visual style configuration.
• kwargs_subplot: additional keyword arguments forwarded to the subplot.
• save_path::Union{Nothing, String} = nothing: file path to save the plot, or nothing.

plot_multistart_fixed_effect_variability(res::MultistartFitResult; dm, k_best, mode,
                                         quantiles, scale, include_parameters,
                                         exclude_parameters, style, kwargs_subplot,
                                         save_path) -> Plots.Plot

Plot the variation of fixed-effect estimates across the k_best multistart runs with the lowest objective values.

Keyword Arguments

• dm::Union{Nothing, DataModel} = nothing: data model (inferred from res by default).
• k_best::Int = 20: number of best runs to include.
• mode::Symbol = :points: :points to show individual estimates; :quantiles to show quantile bands.
• quantiles::AbstractVector = [0.1, 0.5, 0.9]: quantile levels for :quantiles mode.
• scale::Symbol = :untransformed: :untransformed or :transformed.
• include_parameters, exclude_parameters: parameter name filters.
• style::PlotStyle = PlotStyle(): visual style configuration.
• kwargs_subplot: additional keyword arguments forwarded to each subplot.
• save_path::Union{Nothing, String} = nothing: file path to save the plot.

DiscreteTimeDiscreteStatesHMM(transition_matrix, emission_dists, initial_dist)
<: Distribution{Univariate, Continuous}

A discrete-time Hidden Markov Model (HMM) with a finite number of hidden states and continuous or discrete emission distributions.

Implements the Distributions.jl interface (pdf, logpdf, rand, mean, var). Used as an observation distribution in @formulas blocks to model outcomes with latent state dynamics.

Arguments

• transition_matrix::AbstractMatrix{<:Real}: row-stochastic transition matrix of shape (n_states, n_states). Entry [i, j] is P(State_t = j | State_{t-1} = i).
• emission_dists::Tuple: tuple of n_states emission distributions, one per state.
• initial_dist::Distributions.Categorical: prior over hidden states at the current time step. Propagated one step via transition_matrix before computing the emission likelihood.

probabilities_hidden_states(hmm::DiscreteTimeDiscreteStatesHMM) -> Vector{Float64}
probabilities_hidden_states(hmm::ContinuousTimeDiscreteStatesHMM) -> Vector{Float64}

Compute the marginal prior probabilities of the hidden states at the current observation time, propagated from hmm.initial_dist through the transition dynamics.

Returns a normalised probability vector of length n_states.

probabilities_hidden_states(hmm::MVDiscreteTimeDiscreteStatesHMM) -> Vector

Marginal prior probabilities of the hidden states at the current observation time, propagated one step from hmm.initial_dist via hmm.transition_matrix.

probabilities_hidden_states(hmm::MVContinuousTimeDiscreteStatesHMM) -> Vector

Marginal prior probabilities of the hidden states at the current observation time, propagated from hmm.initial_dist via exp(Q · Δt).

probabilities_hidden_states(dist::DiscreteTimeObservedStatesMarkovModel) -> Vector

Marginal prior probabilities of the state at the current observation time, propagated one step from dist.initial_dist via dist.transition_matrix.

probabilities_hidden_states(dist::ContinuousTimeObservedStatesMarkovModel) -> Vector

Marginal prior probabilities of the state at the current observation time, propagated from dist.initial_dist via exp(Q · Δt). Reuses the CT-HMM propagation kernel.

posterior_hidden_states(hmm::ContinuousTimeDiscreteStatesHMM, y::Real)

Compute the posterior probability distribution of hidden states given observation y.

Returns a vector of probabilities p where p[s] is P(State = s | Y = y).

Uses Bayes' rule: P(S | Y) ∝ P(Y | S) * P(S)

posterior_hidden_states(hmm::DiscreteTimeDiscreteStatesHMM, y::Real)

Compute posterior probabilities of hidden states given observation y.

posterior_hidden_states(hmm::MVDiscreteTimeDiscreteStatesHMM, y::AbstractVector)

Posterior probabilities of hidden states given the length-M observation vector y (which may contain missing entries). Uses all non-missing outcomes jointly.

posterior_hidden_states(hmm::MVContinuousTimeDiscreteStatesHMM, y::AbstractVector)

Posterior probabilities of hidden states given the length-M observation vector y (which may contain missing entries). Uses all non-missing outcomes jointly.

posterior_hidden_states(dist::DiscreteTimeObservedStatesMarkovModel, y)

Returns the one-hot posterior after observing state y. Since the state is fully observed, the posterior is degenerate: probability 1 at the index of y, 0 elsewhere.

Returns a zero vector if y is not found in state_labels.

posterior_hidden_states(dist::ContinuousTimeObservedStatesMarkovModel, y)

Returns the one-hot posterior after observing state y. Since the state is fully observed, the posterior is degenerate: probability 1 at the index of y, 0 elsewhere.

Returns a zero vector if y is not found in state_labels.

ContinuousTimeDiscreteStatesHMM(transition_matrix, emission_dists, initial_dist, Δt)
<: Distribution{Univariate, Continuous}

A continuous-time Hidden Markov Model (HMM) with a finite number of hidden states and continuous or discrete emission distributions.

State propagation is performed via the matrix exponential exp(Q·Δt) where Q is the rate matrix (transition_matrix). Implements the Distributions.jl interface.

Arguments

• transition_matrix::AbstractMatrix{<:Real}: rate matrix (generator) of shape (n_states, n_states). Off-diagonal entries must be non-negative; each row must sum to zero.
• emission_dists::Tuple: tuple of n_states emission distributions.
• initial_dist::Distributions.Categorical: prior over hidden states at the previous observation time.
• Δt::Real: time elapsed since the previous observation.

AbstractNormalizingFlow <: Distributions.ContinuousMultivariateDistribution

Abstract supertype for all normalizing flow distributions in NoLimits.jl. Subtypes include NormalizingPlanarFlow.

NormalizingPlanarFlow{D, R} <: AbstractNormalizingFlow

A normalizing planar flow distribution for flexible random effects.

Transforms a base distribution (typically multivariate normal) through a series of planar layers to create a more expressive distribution. Used in @randomEffects blocks to allow random effects to have non-Gaussian distributions.

Fields

• base::D - Transformed distribution (base distribution + flow transformations)
• rebuild::R - Optimisers.Restructure function to reconstruct the bijector from flat parameters

Constructors

# Direct construction with dimensions
NormalizingPlanarFlow(n_input::Int, n_layers::Int; init=glorot_init)

# Construction from parameters (used internally by model macro)
NormalizingPlanarFlow(θ::Vector, rebuild::Restructure, q0::Distribution)

Arguments

• n_input - Dimension of random effects
• n_layers - Number of planar transformation layers
• init - Initialization function (default: Glorot normal)
• θ - Flattened flow parameters
• rebuild - Function to reconstruct bijector from θ
• q0 - Base distribution (typically MvNormal)

# Theory
Planar flows apply transformations of the form:

f(z) = z + u·h(wᵀz + b)

where `h` is a nonlinear activation (typically `tanh`), and `u`, `w`, `b` are learnable
parameters. Multiple layers compose to create complex distributions:

x = fK ∘ f{K-1} ∘ ... ∘ f_1(z₀), z₀ ~ q₀

The log-density is computed via change of variables:

log p(x) = log q₀(z₀) - Σᵢ log|det(Jfᵢ)| ```

Advantages

• Flexibility: Can approximate complex, multimodal distributions
• Expressiveness: Captures non-Gaussian features (skewness, heavy tails, multimodality)
• Differentiability: Fully differentiable for gradient-based optimization
• Interpretability: Parameters are estimated along with other fixed effects

Limitations

• Computational cost: More expensive than multivariate normal
• Convergence: May require more iterations to converge
• Identifiability: Flow parameters and base distribution parameters may trade off

Implementation Details

• Uses planar layer architecture from NormalizingFlows.jl
• Parameters are flattened for optimization and reconstructed during evaluation
• Base distribution is typically MvNormal(zeros(d), I)
• Default initialization: Glorot normal scaled by 1/√n_input

See Also

• NPFParameter - Parameter specification for flows (in @fixedEffects)
• PlanarLayer - Individual transformation layer (from NormalizingFlows.jl)

References

• Rezende, D. J., & Mohamed, S. (2015). "Variational Inference with Normalizing Flows" ICML 2015.

SoftTree(input_dim::Int, depth::Int, n_output::Int)

A differentiable soft decision tree with input_dim input features, depth levels, and n_output outputs.

The tree has 2^depth - 1 internal nodes and 2^depth leaves. Each internal node applies a soft sigmoid split to route inputs; each leaf stores a learnable output value. The forward pass returns the weighted sum of leaf values, differentiable with respect to both inputs and parameters.

Arguments

• input_dim::Int: number of input features (must be > 0).
• depth::Int: number of tree levels (must be > 0).
• n_output::Int: number of output values per evaluation (must be > 0).

SoftTreeParams{WM, BV, LM}

Parameters for a SoftTree. Created via init_params.

Fields:

• node_weights::WM: weight matrix of shape (n_internal, input_dim).
• node_biases::BV: bias vector of length n_internal.
• leaf_values::LM: leaf value matrix of shape (n_output, n_leaves).

init_params(tree::SoftTree; init_weight=0.0, init_bias=0.0, init_leaf=0.0)
-> SoftTreeParams

init_params(tree::SoftTree, rng::AbstractRNG; init_weight_std=0.1,
            init_bias_std=0.0, init_leaf_std=0.1) -> SoftTreeParams

Initialise parameters for a SoftTree.

The no-rng overload fills all parameters with the given constant values. The rng overload draws parameters from zero-mean Normal distributions with the specified standard deviations.

Arguments

• tree::SoftTree: the soft tree architecture.
• rng::AbstractRNG: random-number generator (second overload only).

Keyword Arguments (constant initialisation)

• init_weight::Real = 0.0: node weight initial value.
• init_bias::Real = 0.0: node bias initial value.
• init_leaf::Real = 0.0: leaf value initial value.

Keyword Arguments (random initialisation)

• init_weight_std::Real = 0.1: standard deviation for node weights.
• init_bias_std::Real = 0.0: standard deviation for node biases.
• init_leaf_std::Real = 0.1: standard deviation for leaf values.

destructure_params(params::SoftTreeParams) -> (Vector, Restructure)

Flatten a SoftTreeParams to a parameter vector and return the vector together with a reconstruction function (using Optimisers.destructure).

The reconstruction function can be called with a new flat vector to reconstruct a SoftTreeParams with the same structure.

bspline_basis(x::Real, knots::AbstractVector{<:Real}, degree::Integer)
-> Vector{Float64}

Evaluate the B-spline basis functions of the given degree at the scalar point x using the provided knots vector.

Returns a vector of length length(knots) - degree - 1 containing the values of each basis function at x. The knots must be sorted in non-decreasing order and x must lie within [knots[1], knots[end]].

Arguments

• x::Real: evaluation point.
• knots::AbstractVector{<:Real}: sorted knot sequence (may include repeated boundary knots).
• degree::Integer: polynomial degree of the spline (e.g. 2 for quadratic, 3 for cubic).

bspline_eval(x::Real, coeffs::AbstractVector{<:Real},
             knots::AbstractVector{<:Real}, degree::Integer) -> Real

bspline_eval(x::AbstractVector{<:Real}, coeffs::AbstractVector{<:Real},
             knots::AbstractVector{<:Real}, degree::Integer) -> Real

Evaluate a B-spline at x given coefficient vector coeffs, knot sequence knots, and polynomial degree.

The coefficient vector must have length length(knots) - degree - 1. When x is a length-1 vector it is treated as a scalar.

Arguments

• x::Real (or length-1 AbstractVector): evaluation point.
• coeffs::AbstractVector{<:Real}: B-spline coefficients.
• knots::AbstractVector{<:Real}: sorted knot sequence.
• degree::Integer: polynomial degree.