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. 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:
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 Float64
s.
Pumas.PDiagDomain
— Type@param x ∈ PDiagDomain(n::Int)
@param x ∈ PDiagDomain(; init::AbstractVector{<:Real})
Specify a parameter as an n
-by-n
positive semi-definite diagonal matrix by providing either the number n
of rows and columns or the initial diagonal (variance) elements init
.
If the number n
of rows and columns in the matrix is specified, the initial diagonal elements are all set to 1.
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 (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 the first element will have a variance of 0.0
end the second element will have a variance of 1.0
. The covariance will be 0.0
since we structurally asked for a diagonal structure.
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.
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
— TypeConstrained
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.