Public Documentation

Module for defining latent models.

struct AR{D<:Distributions.Sampleable, S<:Distributions.Sampleable, I<:Distributions.Sampleable, P<:Int64} <: AbstractTuringLatentModel

The autoregressive (AR) model struct.

Constructors

• AR(damp_prior::Distribution, std_prior::Distribution, init_prior::Distribution; p::Int = 1): Constructs an AR model with the specified prior distributions for damping coefficients, standard deviation, and initial conditions. The order of the AR model can also be specified.

• AR(; damp_priors::Vector{D} = [truncated(Normal(0.0, 0.05))], std_prior::Distribution = truncated(Normal(0.0, 0.05), 0.0, Inf), init_priors::Vector{I} = [Normal()]) where {D <: Distribution, I <: Distribution}: Constructs an AR model with the specified prior distributions for damping coefficients, standard deviation, and initial conditions. The order of the AR model is determined by the length of the damp_priors vector.

• AR(damp_prior::Distribution, std_prior::Distribution, init_prior::Distribution, p::Int): Constructs an AR model with the specified prior distributions for damping coefficients, standard deviation, and initial conditions. The order of the AR model is explicitly specified.

Examples

using Distributions
using EpiAware
ar = AR()
ar_model = generate_latent(ar, 10)
rand(ar_model)

Fields

• damp_prior::Distributions.Sampleable: Prior distribution for the damping coefficients.

• std_prior::Distributions.Sampleable: Prior distribution for the standard deviation.

• init_prior::Distributions.Sampleable: Prior distribution for the initial conditions

• p::Int64: Order of the AR model.

struct BroadcastLatentModel{M<:AbstractTuringLatentModel, P<:Integer, B<:AbstractBroadcastRule} <: AbstractTuringLatentModel

The BroadcastLatentModel struct represents a latent model that supports broadcasting of latent periods.

Constructors

• BroadcastLatentModel(;model::M; period::Int, broadcast_rule::B): Constructs a BroadcastLatentModel with the given model, period, and broadcast_rule.
• BroadcastLatentModel(model::M, period::Int, broadcast_rule::B): An alternative constructor that allows the model, period, and broadcast_rule to be specified without keyword arguments.

Examples

using EpiAware, Turing
each_model = BroadcastLatentModel(RandomWalk(), 7, RepeatEach())
gen_each_model = generate_latent(each_model, 10)
rand(gen_each_model)

block_model = BroadcastLatentModel(RandomWalk(), 3, RepeatBlock())
gen_block_model = generate_latent(block_model, 10)
rand(gen_block_model)

Fields

• model::AbstractTuringLatentModel: The underlying latent model.

• period::Integer: The period of the broadcast.

• broadcast_rule::AbstractBroadcastRule: The broadcast rule to be applied.

struct CombineLatentModels{M<:(AbstractVector{<:AbstractTuringLatentModel}), P<:(AbstractVector{<:String})} <: AbstractTuringLatentModel

The CombineLatentModels struct.

This struct is used to combine multiple latent models into a single latent model. If a prefix is supplied wraps each model with PrefixLatentModel.

Constructors

• CombineLatentModels(models::M, prefixes::P) where {M <: AbstractVector{<:AbstractTuringLatentModel}, P <: AbstractVector{<:String}}: Constructs a CombineLatentModels instance with specified models and prefixes, ensuring that there are at least two models and the number of models and prefixes are equal.
• CombineLatentModels(models::M) where {M <: AbstractVector{<:AbstractTuringLatentModel}}: Constructs a CombineLatentModels instance with specified models, automatically generating prefixes for each model. The

automatic prefixes are of the form Combine.1, Combine.2, etc.

Examples

using EpiAware, Distributions
combined_model = CombineLatentModels([Intercept(Normal(2, 0.2)), AR()])
latent_model = generate_latent(combined_model, 10)
latent_model()

Fields

• models::AbstractVector{<:AbstractTuringLatentModel}: A vector of latent models

• prefixes::AbstractVector{<:String}: A vector of prefixes for the latent models

struct ConcatLatentModels{M<:(AbstractVector{<:AbstractTuringLatentModel}), N<:Int64, F<:Function, P<:(AbstractVector{<:String})} <: AbstractTuringLatentModel

The ConcatLatentModels struct.

This struct is used to concatenate multiple latent models into a single latent model.

Constructors

• ConcatLatentModels(models::M, no_models::I, dimension_adaptor::F, prefixes::P) where {M <: AbstractVector{<:AbstractTuringLatentModel}, I <: Int, F <: Function, P <: AbstractVector{String}}: Constructs a ConcatLatentModels instance with specified models, number of models, dimension adaptor, and prefixes.
• ConcatLatentModels(models::M, dimension_adaptor::F; prefixes::P = "Concat." * string.(1:length(models))) where {M <: AbstractVector{<:AbstractTuringLatentModel}, F <: Function}: Constructs a ConcatLatentModels instance with specified models and dimension adaptor. The number of models is automatically determined as are the prefixes (of the form Concat.1, Concat.2, etc.) by default.
• ConcatLatentModels(models::M; dimension_adaptor::Function, prefixes::P) where {M <: AbstractVector{<:AbstractTuringLatentModel}, P <: AbstractVector{String}}: Constructs a ConcatLatentModels instance with specified models, dimension adaptor, prefixes, and automatically determines the number of models.The default dimension adaptor is equal_dimensions. The default prefixes are of the form Concat.1, Concat.2, etc.
• ConcatLatentModels(; models::M, dimension_adaptor::Function, prefixes::P) where {M <: AbstractVector{<:AbstractTuringLatentModel}, P <: AbstractVector{String}}: Constructs a ConcatLatentModels instance with specified models, dimension adaptor, prefixes, and automatically determines the number of models. The default dimension adaptor is equal_dimensions. The default prefixes are of the form Concat.1, Concat.2, etc.

Examples

using EpiAware, Distributions
combined_model = ConcatLatentModels([Intercept(Normal(2, 0.2)), AR()])
latent_model = generate_latent(combined_model, 10)
latent_model()

Fields

• models::AbstractVector{<:AbstractTuringLatentModel}: A vector of latent models

• no_models::Int64: The number of models in the collection

• dimension_adaptor::Function: The dimension function for the latent variables. By default this divides the number of latent variables by the number of models and returns a vector of dimensions rounding up the first element and rounding down the rest.

• prefixes::AbstractVector{<:String}: A vector of prefixes for the latent models

struct DiffLatentModel{M<:AbstractTuringLatentModel, P<:Distributions.Distribution} <: AbstractTuringLatentModel

Model the latent process as a d-fold differenced version of another process.

Mathematical specification

Let $\Delta$ be the differencing operator. If $\tilde{Z}_t$ is a realisation of undifferenced latent model supplied to DiffLatentModel, then the differenced process is given by,

\[\Delta^{(d)} Z_t = \tilde{Z}_t, \quad t = d+1, \ldots.\]

We can recover $Z_t$ by applying the inverse differencing operator $\Delta^{-1}$, which corresponds to the cumulative sum operator cumsum in Julia, d-times. The d initial terms $Z_1, \ldots, Z_d$ are inferred.

Constructors

• DiffLatentModel(latent_model, init_prior_distribution::Distribution; d::Int) Constructs a DiffLatentModel for d-fold differencing with latent_model as the undifferenced latent process. All initial terms have common prior init_prior_distribution.
• DiffLatentModel(;model, init_priors::Vector{D} where {D <: Distribution}) Constructs a DiffLatentModel for d-fold differencing with latent_model as the undifferenced latent process. The d initial terms have priors given by the vector init_priors, therefore length(init_priors) sets d.

Example usage with generate_latent

generate_latent can be used to construct a Turing model for the differenced latent process. In this example, the underlying undifferenced process is a RandomWalk model.

First, we construct a RandomWalk struct with an initial value prior and a step size standard deviation prior.

using Distributions, EpiAware
rw = RandomWalk(Normal(0.0, 1.0), truncated(Normal(0.0, 0.05), 0.0, Inf))

Then, we can use DiffLatentModel to construct a DiffLatentModel for d-fold differenced process with rw as the undifferenced latent process.

We have two constructor options for DiffLatentModel. The first option is to supply a common prior distribution for the initial terms and specify d as follows:

diff_model = DiffLatentModel(rw, Normal(); d = 2)

Or we can supply a vector of priors for the initial terms and d is inferred as follows:

diff_model2 = DiffLatentModel(;undiffmodel = rw, init_priors = [Normal(), Normal()])

Then, we can use generate_latent to construct a Turing model for the differenced latent process generating a length n process,

# Construct a Turing model
n = 100
difference_mdl = generate_latent(diff_model, n)

Now we can use the Turing PPL API to sample underlying parameters and generate the unobserved latent process.

#Sample random parameters from prior
θ = rand(difference_mdl)
#Get a sampled latent process as a generated quantity from the model
(Z_t, _) = generated_quantities(difference_mdl, θ)
Z_t

Fields

• model::AbstractTuringLatentModel: Underlying latent model for the differenced process

• init_prior::Distributions.Distribution: The prior distribution for the initial latent variables.

• d::Int64: Number of times differenced.

struct FixedIntercept{F<:Real} <: AbstractTuringIntercept

A variant of the Intercept struct that represents a fixed intercept value for a latent model.

Constructors

• FixedIntercept(intercept) : Constructs a FixedIntercept instance with the specified intercept value.
• FixedIntercept(; intercept) : Constructs a FixedIntercept instance with the specified intercept value using named arguments.

Examples

using EpiAware
fi = FixedIntercept(2.0)
fi_model = generate_latent(fi, 10)
fi_model()

Fields

• intercept::Real

struct HierarchicalNormal{R<:Real, D<:Distributions.Sampleable} <: AbstractTuringLatentModel

The HierarchicalNormal struct represents a non-centered hierarchical normal distribution.

Constructors

• HierarchicalNormal(mean, std_prior): Constructs a HierarchicalNormal instance with the specified mean and standard deviation prior.
• HierarchicalNormal(; mean = 0.0, std_prior = truncated(Normal(0,1), 0, Inf)): Constructs a HierarchicalNormal instance with the specified mean and standard deviation prior using named arguments and with default values.

Examples

using Distributions, EpiAware
hnorm = HierarchicalNormal(0.0, truncated(Normal(0, 1), 0, Inf))
hnorm_model = generate_latent(hnorm, 10)
hnorm_model()

Fields

• mean::Real

• std_prior::Distributions.Sampleable

struct Intercept{D<:Distributions.Sampleable} <: AbstractTuringIntercept

The Intercept struct is used to model the intercept of a latent process. It broadcasts a single intercept value to a length n latent process.

Constructors

• Intercept(intercept_prior)
• Intercept(; intercept_prior)

Examples

using Distributions, Turing, EpiAware
int = Intercept(Normal(0, 1))
int_model = generate_latent(int, 10)
rand(int_model)
int_model()

Fields

• intercept_prior::Distributions.Sampleable: Prior distribution for the intercept.

struct PrefixLatentModel{M<:AbstractTuringLatentModel, P<:String} <: AbstractTuringLatentModel

Generate a latent model with a prefix. A lightweight wrapper around `EpiAwareUtils.prefix_submodel`.

# Constructors
- `PrefixLatentModel(model::M, prefix::P)`: Create a `PrefixLatentModel` with the latent model `model` and the prefix `prefix`.
- `PrefixLatentModel(; model::M, prefix::P)`: Create a `PrefixLatentModel` with the latent model `model` and the prefix `prefix`.

# Examples
```julia
using EpiAware
latent_model = PrefixLatentModel(model = HierarchicalNormal(), prefix = "Test")
mdl = generate_latent(latent_model, 10)
rand(mdl)
```

Fields

• model::AbstractTuringLatentModel: The latent model

• prefix::String: The prefix for the latent model

struct RandomWalk{D<:Distributions.Sampleable, S<:Distributions.Sampleable} <: AbstractTuringLatentModel

Model latent process $Z_t$ as a random walk.

Mathematical specification

The random walk $Z_t$ is specified as a parameteric transformation of the white noise sequence $(\epsilon_t)_{t\geq 1}$,

\[Z_t = Z_0 + \sigma \sum_{i = 1}^t \epsilon_t\]

Constructing a random walk requires specifying:

• An init_prior as a prior for $Z_0$. Default is Normal().
• A std_prior for $\sigma$. The default is HalfNormal with a mean of 0.25.

Constructors

• RandomWalk(; init_prior, std_prior)

Example usage with generate_latent

generate_latent can be used to construct a Turing model for the random walk $Z_t$.

First, we construct a RandomWalk struct with priors,

using Distributions, Turing, EpiAware

# Create a RandomWalk model
rw = RandomWalk(init_prior = Normal(2., 1.),
                                std_prior = HalfNormal(0.1))

Then, we can use generate_latent to construct a Turing model for a 10 step random walk.

# Construct a Turing model
rw_model = generate_latent(rw, 10)

Now we can use the Turing PPL API to sample underlying parameters and generate the unobserved infections.

#Sample random parameters from prior
θ = rand(rw_model)
#Get random walk sample path as a generated quantities from the model
Z_t, _ = generated_quantities(rw_model, θ)

Fields

• init_prior::Distributions.Sampleable

• std_prior::Distributions.Sampleable

struct RecordExpectedLatent{M<:AbstractTuringLatentModel} <: AbstractTuringLatentModel

Record a variable (using the Turing := syntax) in a latent model.

# Fields
- `model::AbstractTuringLatentModel`: The latent model to dispatch to.

# Constructors

- `RecordExpectedLatent(model::AbstractTuringLatentModel)`: Record the expected latent vector from the model as `exp_latent`.

# Examples

```julia
using EpiAware, Turing
mdl = RecordExpectedLatent(FixedIntercept(0.1))
gen_latent = generate_latent(mdl, 1)
sample(gen_latent, Prior(), 10)
```

Fields

• model::AbstractTuringLatentModel

struct RepeatBlock <: AbstractBroadcastRule

RepeatBlock is a struct that represents a broadcasting rule. It is a subtype of AbstractBroadcastRule.

It repeats the latent process in blocks of size period. An example of this rule is to repeat the latent process in blocks of size 7 to model a weekly process (though for this we also provide the broadcast_weekly helper function).

Examples

using EpiAware
rule = RepeatBlock()
latent = [1, 2, 3, 4, 5]
n = 10
period = 2
broadcast_rule(rule, latent, n, period)

Fields

struct RepeatEach <: AbstractBroadcastRule

RepeatEach is a struct that represents a broadcasting rule. It is a subtype of AbstractBroadcastRule.

It repeats the latent process at each period. An example of this rule is to repeat the latent process at each day of the week (though for this we also provide the dayofweek helper function).

Examples

using EpiAware
rule = RepeatEach()
latent = [1, 2]
n = 10
period = 2
broadcast_rule(rule, latent, n, period)

Fields

struct TransformLatentModel{M<:AbstractTuringLatentModel, F<:Function} <: AbstractTuringLatentModel

The TransformLatentModel struct represents a latent model that applies a transformation function to the latent variables generated by another latent model.

Constructors

• TransformLatentModel(model, trans_function): Constructs a TransformLatentModel instance with the specified latent model and transformation function.
• TransformLatentModel(; model, trans_function): Constructs a TransformLatentModel instance with the specified latent model and transformation function using named arguments.

Example

using EpiAware, Distributions
trans = TransformLatentModel(Intercept(Normal(2, 0.2)), x -> x .|> exp)
trans_model = generate_latent(trans, 5)
trans_model()

Fields

• model::AbstractTuringLatentModel: The latent model to transform.

• trans_function::Function: The transformation function.

broadcast_rule(_::RepeatBlock, latent, n, period) -> Any

broadcast_rule is a function that applies the RepeatBlock rule to the latent process latent to generate n samples.

Arguments

• rule::RepeatBlock: The broadcasting rule.
• latent::Vector: The latent process.
• n: The number of samples to generate.
• period: The period of the broadcast.

Returns

• latent: The generated broadcasted latent periods.

broadcast_rule(_::RepeatEach, latent, n, period) -> Any

broadcast_rule is a function that applies the RepeatEach rule to the latent process latent to generate n samples.

Arguments

• rule::RepeatEach: The broadcasting rule.
• latent::Vector: The latent process.
• n: The number of samples to generate.
• period: The period of the broadcast.

Returns

• latent: The generated broadcasted latent periods.

broadcast_dayofweek(
    model::AbstractTuringLatentModel;
    link
) -> BroadcastLatentModel{TransformLatentModel{M, EpiAware.EpiLatentModels.var"#42#44"}, Int64, RepeatEach} where M<:AbstractTuringLatentModel

Constructs a BroadcastLatentModel appropriate for modelling the day of the week for a given AbstractTuringLatentModel.

Arguments

• model::AbstractTuringLatentModel: The latent model to be repeated.
• link::Function: The link function to transform the latent model before broadcasting

to periodic weekly. Default is x -> 7 * softmax(x) which implements constraint of the sum week effects to be 7.

Returns

• BroadcastLatentModel: The broadcast latent model.

broadcast_weekly(
    model::AbstractTuringLatentModel
) -> BroadcastLatentModel{<:AbstractTuringLatentModel, Int64, RepeatBlock}

Constructs a BroadcastLatentModel appropriate for modelling piecewise constant weekly processes for a given AbstractTuringLatentModel.

Arguments

• model::AbstractTuringLatentModel: The latent model to be repeated.

Returns

• BroadcastLatentModel: The broadcast latent model.

equal_dimensions(n::Int64, m::Int64) -> Vector{Int64}

Return a vector of dimensions that are equal or as close as possible, given the total number of elements n and the number of dimensions m. The default dimension adaptor for ConcatLatentModels.

Arguments

• n::Int: The total number of elements.
• m::Int: The number of dimensions.

Returns

• dims::AbstractVector{Int}: A vector of dimensions, where the first element is the ceiling of n / m and the remaining elements are the floor of n / m.