`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 a required positional argument. 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:

Pumas.RealDomain — Type

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

Specifies a parameter as a real value. lower and upper are the respective bounds, init sets the initial value of the parameter and is used for init_params.

Pumas.VectorDomain — Type

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

Specifies a parameter as a real vector of length n. lower and upper are the respective bounds, init sets the initial value of the parameter and is used for init_params. The keyword arguments can all take either numbers or vectors. If numbers then the same value will be applied to all n vector elements. If a you specify a vector (of length n) then you can adjust the parameters of the VectorDomain elements individually.

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.

Positive-Definite Matrix Domains

In many cases, one may wish to specify a positive-definite covariance matrix as a parameter in a model. 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. Both of the constructors require the size n of the n x n positive-definite matrix:

Pumas.PSDDomain — Type

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

Specifies a parameter as a symmetric n-by-n positive semi-definite matrix. The user must either specify n as the number of rows and columns in the matrix or init as the initial value of the parameter. init should be a positive semi- definite Matrix of Float64s.

Pumas.PDiagDomain — Type

@param x ∈ PDiagDomain(n::Int; init=ones(n))

Specifies a parameter as a positive diagonal matrix, with initial diagonal elements specified by init.

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 is, i.e. diagonal matrices with positive diagonal elements. Thus, if a domain is specified as Ω ∈ PDiagDomain(2), then

Ω = Diagonal([0.0, 1.0])

is a valid parameter specification.

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. 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.

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.

Pumas.Constrained — Type

Constrained

Constrain a Distribution within a Domain. The most common case is an MvNormal constrained within a VectorDomain. The only supported method for Constrained is logpdf. Notice that the result does not represent a probability distribution since the remaining probability mass is not scaled by the mass excluded by the constraints.

Example

julia> d = Constrained(MvNormal(fill(1.0, 1, 1)), lower=-1, upper=1)
Constrained{ZeroMeanFullNormal{Tuple{Base.OneTo{Int64}}}, VectorDomain{Vector{Int64}, Vector{Int64}, Vector{Float64}}}(ZeroMeanFullNormal(
dim: 1
μ: Zeros(1)
Σ: [1.0;;]
)
, VectorDomain{Vector{Int64}, Vector{Int64}, Vector{Float64}}([-1], [1], [0.0]))


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.

PumasModel Domains