PumasModel Domains

Domains are used to define the param portion of a PumasModel. This segment of the documentation describes the available Domain types that can be used within the param portions.

Matching Parameter Types and Domains

A param specification in a PumasModel directly defines the types which are required to be given as the input to the model's interface functions such as simobs and fit. For example, if the param specification is given as:

@param begin
    θ ∈ VectorDomain(2; lower = [0, 0], upper = [20, 20])
    Ω ∈ PSDDomain(2)
    Σ ∈ RealDomain(; lower = 0.01, upper = 0.2)
end

Then in simobs(model, data, param) or fit(model, data, param), the parameters param must be a NamedTuple of values where the type fits in the domain. For example, param must have param.θ as a Vector. Thus, the following would be a valid definition of param for this structure:

param = (; θ = [0.4, 7.0], Ω = [
    0.04 0.0
    0.0 0.01
], Σ = 0.1)

Below are the specifications of the Domain types and their matching value types.

RealDomain and VectorDomain

RealDomain and VectorDomain are the core domain types of Pumas. A RealDomain defines a scalar value which exists in the real line, while a VectorDomain defines a real-valued vector which lives in a hypercube of $\mathbb{R}^n$. The length n of a VectorDomain is given as a positional argument, or left out and derived from the bounds and the initial value. Each of these allow keyword arguments for setting an upper and lower bound for the segment, where for the RealDomain these are scalars and for the VectorDomain it is a vector of upper and lower bound for each component of the vector. Thus, the constructors are:

@param x ∈ RealDomain(;lower=-∞,upper=∞,init=0)

@param x ∈ VectorDomain(n::Int; lower=-∞,upper=∞,init=0)

A RealDomain requires that the matching parameters are an AbstractFloat type. A VectorDomain requires that the matching parameters are a Vector of an AbstractFloat type which has the correct size.

OrderedVectorDomain

An OrderedVectorDomain defines a real-valued vector whose elements are in non-decreasing order, optionally bounded below by lower. Equal neighbouring elements are allowed. The main use case is the vector of cut points of an ordered logit model, which has to be ordered for the model to be well defined.

OrderedVectorDomain(n::Int; lower=-∞)
OrderedVectorDomain(; init::AbstractVector{<:Real}, lower=-∞)

The dimension can be given either as the positional argument n or implicitly through an initial value:

@param begin
    cutoffs ∈ OrderedVectorDomain(3)
    intercepts ∈ OrderedVectorDomain(; init = [-1.0, 0.0, 2.0])
end

Unlike VectorDomain, an OrderedVectorDomain has no default initial value, since no single vector is a natural starting point for every ordering. An initial value for such a parameter therefore has to be supplied when fitting.

Values are estimated on a transformed scale on which the ordering holds by construction, so a fit cannot produce a vector that violates it.

SimplexDomain

A SimplexDomain defines a probability vector: a real-valued vector whose elements are non-negative and sum to one.

SimplexDomain(n::Int)

The dimension is given as the positional argument n and has to be at least two:

@param begin
    p ∈ SimplexDomain(3)
end

Unlike OrderedVectorDomain, a SimplexDomain has a default initial value, the uniform vector fill(1 / n, n). Parameter values that do not sum to one, for instance as the initial or fixed values of fit or as the parameters of simobs or loglikelihood, throw a DomainError.

Because of the sum constraint, a SimplexDomain of length n has only n - 1 free coordinates. These are what dof counts and what the displayed fit reports as optimized. Results nevertheless report all n elements on the scale of the estimates: vcov has one row and column per element and is therefore singular, and coeftable, stderror and the columns of the Chains of a Bayesian fit include every element. A covariance matrix passed to simobs or as the proposal_covariance keyword argument of infer with SIR has the same layout and has to respect the sum constraint.

Positive-Definite Matrix Domains

In many cases, one may wish to specify a positive-definite covariance matrix as a parameter in a model. In the diagonal case this is then a matrix with variances on the diagonal. A common use case for this functionality is for defining the domain of a random effect. There are two domains for positive-definite matrices: PSDDomain and PDiagDomain. Since they are matrices, elements represent variances (diagonal elements) and covariances. Both of the constructors require the size n of the n x n positive-definite matrix:

@param x ∈ PSDDomain(n::Int)
@param x ∈ PSDDomain(; init=Matrix{Float64}(I, n, n))

@param x ∈ PDiagDomain(n::Int)
@param x ∈ PDiagDomain(; init::AbstractVector{<:Real})

A PSDDomain requires that the matching matrix input is positive definite but puts no further restrictions on the matrix. If a domain is specified as Ω ∈ PSDDomain(2), then

Ω = [
    0.04 0.0
    0.0 0.01
]

is a valid parameter specification. The PDiagDomain restricts the parameter space to positive definite diagonal matrices, i.e. diagonal matrices with positive diagonal (variance) elements. Thus, if a domain is specified as Ω ∈ PDiagDomain(2), then

Ω = Diagonal([0.0, 1.0])

is a valid parameter specification. If used to parameterize a MvNormal the first element will have a variance of 0.0 and the second element will have a variance of 1.0. The covariance will be 0.0 since we structurally asked for a diagonal structure.

Passing a vector of diagonal entries to PSDDomain is deprecated: write PDiagDomain(; init) for a diagonal covariance matrix, or PSDDomain(; init = Diagonal(init)) to keep a dense one.

Distributional Domains

Instead of using a Domain type from Pumas, a Distribution can be used to specify a domain. For example,

Ω ~ Normal(0.0, 1.0)

is a valid domain specification. If this is done, then the probability distribution is used and interpreted as the prior distribution if using the maximum A posteriori Probability wrapper is used (e.g. MAP(FOCE)) or if performing bayesian inference. Implicitly, the domain of a distribution is treated as the support of the distribution. A distributional domain requires that the matching parameter is of the same type as a sample from the domain. For example, if Ω ~ Normal(0,1), then Ω should be given as a scalar. A Dirichlet prior implies a SimplexDomain of the same length, in the same way that a Wishart prior implies a PSDDomain.

Constrained Domains

The Constrained domain is for defining a Constrained probability distribution. Constrained takes in a distribution and has keyword arguments for upper and lower bounds.

Constrained

julia> d = Constrained(MvNormal(fill(1.0, 1, 1)), lower = -1, upper = 1)
Constrained(
  ZeroMeanFullNormal(
  dim: 1
  μ: Zeros(1)
  Σ: [1.0;;]
  );
  lower = [-1],
  upper = [1],
)

julia> logpdf(d, [0])
-0.9189385332046728

julia> logpdf(d, [-2])
-Inf

For example, ψ ~ Constrained(MVNormal(Ω),lower=[0.0,0.0]) defines a ψ to be from the distributional domain which corresponds to a multivariate normal distribution, but is constrained to be positive. Like with the distributional domains, Constrained requires that the matching parameter is of the same type as a sample from the domain.