Index of public API

EKS <: EnsembleInferenceAlgorithm

Represents a proxy for the Ensemble Kalman Sampler (Garbuno-Inigo et al. 2020) implementation provided by EnsembleKalmanProcesses.

ESMDA <: EnsembleInferenceAlgorithm

Implementation of the ensemble-smother multiple data assimilation algorithm of Emerick et al. 2013.

Emerick, Alexandre A., and Albert C. Reynolds. "Ensemble smoother with multiple data assimilation." Computers & Geosciences 55 (2013): 3-15.

Emcee

Wrapper type for affine-invariant Markov-chain Monte Carlo, a.k.a "emcee".

EmpiricalGaussian <: GaussianApproximationMethod

Represents a simple Gaussian approximation method which calculates a sample mean and covariance.

EnIS

Basic ensemble importance sampling (EnIS) inference algorithm. Also sometimes referred to as the "particle batch smoother" (PBS) or "generalized likelihood uncertainty estimation" (GLUE) depending on the context.

EnsembleSolver{algType,probType,ensalgType,stateType<:EnsembleState,kwargTypes}

Generic implementation of an iterative solver for any ensemble-based algorithm. Uses the SciML EnsembleProblem interface to automatically parallelize forward runs over the ensemble.

GaussianApproximationMethod

Base type for Gaussian approximations of arbitrary prior distributions.

JointPrior{modelPriorType<:AbstractSimulatorPrior,likNames,likPriorTypes,axesType} <: AbstractSimulatorPrior

Represents the "joint" prior p(θₘ,θₗ) where θ = [θₘ θₗ] are the full set of parameters in the joint; distribution p(x,θ). θₘ are the model (simulator) parameters and θₗ are the noise/error model parameters.

Constructs a JointPrior from the given prior and likelihoods.

MCMC(alg, strat; kwargs...)

Generic consturctor for MCMC algorithms with implementation-specific type alg and "strategy" strat.

MCMC{algType,stratType,kwargType} <: SimulatorInferenceAlgorithm

Generic container type for Markov Chain Monte Carlo (MCMC) based inference algorithms.

NamedProductPrior{distTypes<:NamedTuple}

Simple diagonal prior that wraps a NamedTuple of distributions from the Distributions package.

Alias for EnIS.

SimulationArrayStorage <: SimulationData

Simple implementation of SimulationData that stores all results in generically typed Vectors.

SimulationData

Base type representing storage for simulation data, i.e. input/output pairs.

SimulatorForwardProblem{probType,obsType,configType,names} <: SciMLBase.AbstractSciMLProblem

Represents a "forward" problem from parameters/initial conditions to output SimulatorObservables. This type wraps an underlying SciMLProblem, a set of Observables, and an optional, probelm-dependent configuration type.

SimulatorForwardProblem(prob::SciMLBase.AbstractSciMLProblem, observables::SimulatorObservable...)

Constructs a generic simulator forward problem from the given AbstractSciMLProblem; note that this could be any problem type, e.g. an optimization problem, nonlinear system, quadrature, etc.

SimulatorForwardProblem(f, p0::AbstractVector, observables::SimulatorObservable...)

Creates a forward problem from the given function or callable type f with initial parameters p0 and the given observables.

SimulatorForwardProblem(f, p0::AbstractVector)

Creates a forward problem from the given function or callable type f with initial parameters p0 and a default transient observable. Note that this constructor calls f(p0) in order to determine the shape of the observable. If f is very costly and this is undesirable, it is recommended to use the explicit constructor.

SimulatorForwardProblem(f, p0::AbstractVector, observables::SimulatorObservable...)

Constructs a SimulatorForwardProblem from the callable/function f(x) and observables. The base problem will be a SimpleForwardProblem which wraps f(x) and uses p0 as the default parameter/input values for x.

SimulatorForwardProblem(prob::SciMLBase.AbstractSciMLProblem, observables::SimulatorObservable...)

Constructs a SimulatorForwardProblem from the given SciML problem and observables.

SimulatorForwardSolution{solType,probType}

Solution for a SimulatorForwardProblem that wraps the underlying forward solution.

SimulatorForwardSolver{stateType}

Basic forward solver that simply wraps the value returned by init for the underlying problem.

Base type for all simulator-based inference algorithms.

SimulatorInferenceProblem{
    modelPriorType<:AbstractSimulatorPrior,
    uType,
    fwdProbType<:SimulatorForwardProblem,
    fwdSolverType,
    priorType<:JointPrior
} <: SciMLBase.AbstractSciMLProblem

Represents a generic simulation-based Bayesian inference problem for finding the posterior distribution over model parameters given some observed data.

SimulatorInferenceProblem(
    prob::SimulatorForwardProblem,
    forward_solver,
    prior::AbstractSimulatorPrior,
    likelihoods::AbstractLikelihood...;
    metadata::Dict=Dict(),
)

Constructs a SimulatorInferenceProblem from the given forward problem, prior, and likelihoods. Additional user-specified metadata may be included in the metadata dictionary.

SimulatorInferenceSolution{algType,probType,storageType}

Generic container for solutions to SimulatorInferenceProblems. The type of result is method dependent and should generally correspond to the final state or product of the inference algorithm (e.g. posterior sampels). The field output should be an instance of SimulationData

SimulatorLikelihood{distType,obsType,dataType,priorType}

Represents a simulator-based likelihood function. A SimulatorLikelihood consists of four basic components:

(1) A distribution type, e.g. Normal,

(2) A SimulatorObservable which represents the observation operator,

(3) A set of data, usually a Vector or Matrix, which matches the structure of the observable,

(4) A prior distribution governing one or more additional parameters required to compute the likelihood.

Due to the typically high cost of evaluating the parameter forward map, SimulatorLikelihood effectively decouples the computation of the likelihood from the simulator via the SimulatorObservable, which stores the result of a forward simulation. When the SimulatorLikelihood is evaluated, these outputs are obtained from getvalue(obs) and the only additional parameters needed are those specified by prior.

SimulatorLikelihood(::Type{distType}, obs, data, prior, name=nameof(obs)) where {distType}

Creates a SimulatorLikelihood with the given distribution type, observable, data source, and prior distribtuion. A custom identifier may also be specified via the name argument; by default, the name of the observable is used.

SimulatorODEForwardSolver{algType,uType,tType,iip,integratorType<:AbstractODEIntegrator{algType,iip,uType,tType}} <: AbstractODEIntegrator{algType,iip,uType,tType}

Specialized integrator type that wraps a SciML ODE integrator and controls the stepping procedure such that each observable sample point is hit.

SimulatorObservable{N,outputType<:SimulatorOutput,funcType,coordsType} <: Observable{outputType}

Represents a named "observable" that stores output from a simulator. obsfunc defines a mapping from the simulator state to the observed quantity. The type and implementation of output determines how the samples are stored. The simplest output type is Transient which simply maintains a pointer to the last observed output.

SimulatorObservable(name::Symbol, f, coords::Tuple)

Constructs a Transient observable with state mapping function f and coordinates coords.

SimulatorObservable(
    name::Symbol,
    obsfunc,
    t0::tType,
    tsave::AbstractVector{tType},
    output_shape_or_coords::Tuple;
    reducer=mean,
    samplerate=default_sample_rate(tsave),
) where {tType}

Constructs a TimeSampled observable which iteratively samples and stores outputs on each call to observe!.

DiagonalGaussianLikelihood(obs, data, prior, name)

Alias for SimulatorLikelihood(DiagNormal, obs, data, prior, name). Represents a multivaraite i.i.d Guassian likelihood with heteroscedastic noise.

DiracLikelihood(
    obs,
    data,
    name=nameof(obs),
)

Represents a Dirac delta likelihood function which assigns full probability mass to a single point, i.e. the predicted value of the simulator observable.

GPLikelihood(obs, data, kernelfn, prior::AbstractSimulatorPrior, name=nameof(obs))

Constructs a GP likelihood from the given observable, data, kernel function, and prior. The kernel function should be a function that takes parameters matching those sampled from prior and constructs any Kernel from KernelFunctions.

GaussianLikelihood(obs, data, prior, name)

Alias for SimulatorLikelihood(Normal, obs, data, prior, name). Represents a univariate Guassian likelihood.

ImplicitLikelihood(
    obs,
    data,
    name=nameof(obs),
)

Represents a Dirac delta likelihood function which assigns full probability mass to a single point, i.e. the predicted value of the simulator observable.

IsotropicGaussianLikelihood(obs, data, prior, name)

Alias for SimulatorLikelihood(IsoNormal, obs, data, prior, name). Represents a multivaraite i.i.d Guassian likelihood with homoscedastic noise.

autoprior(mean, stddev; lower=-Inf, upper=Inf)

Helper function that automatically constructs a prior distribution with the given mean, standard deviation, and support. Note that lower < mean <= upper must be satisfied. For unbounded variables, Normal is returned. For variabels bounded from below (i.e. either lower or upper bound is finite), a transformed LogNormal distribution is constructed. For double bounded variables, (i.e. both lower and upper are finite) a tranformed Beta distribution is constructed.

coordinates(dims...)

Converts arguments dims to a tuple of coordinate Dimensions according to the following rules:

- Integers `n` are converted to simple step indices `1:n`
- Vectors are converted to `Dim`s

coordinates(obs::Observable)

Retrieves coordinates for each dimension of the observables as a Tuple with length matching the number of dimensions.

ensemble_kalman_analysis(
    prior::AbstractVecOrMat,
    obs::AbstractVector,
    pred::AbstractMatrix,
    alpha,
    R_cov;
    ρ_AB=1.0,
    ρ_BB=1.0,
    stochastic=true,
    dosvd=true,
    svd_thresh=0.90,
    rng::AbstractRNG=Random.GLOBAL_RNG,
)

Performs a single ensemble Kalman analysis step. Adapted from the python implementation by Kristoffer Aalstad:

https://github.com/ealonsogzl/MuSA/blob/0c02b8dc25a0f902bf63099de68174f4738705f0/modules/filters.py#L33

forward_map(prior::AbstractSimulatorPrior, ζ)

Applies the forward map from the sample space of the prior to the parameter space of the forward model (simulator). Note that this mapping need not necessarily be bijective in the case of hierarchical or reparamterized formulations of the model parameter prior. Defaults to returning identity(ζ).

from_moments(::Type{T}, mean, stddev) where {T<:Distribution}

Construct a distribution of type T using the method of moments. It is assumed that the given mean lies within the untransformed support of the distribution.

gaussian_gapprox(prior::AbstractSimulatorPrior; num_prior_samples::Int=10_000, rng::Random.AbstractRNG=Random.default_rng())

Builds an empirical multivariate Gaussian approximation of the given prior distribution by computing the moments of the transformed samples.

get_ensemble(sol::SimulatorInferenceSolution{<:EnsembleInferenceAlgorithm}, iter::Int=-1)

Fetches the state of the ensemble from the given solution object. For iterative algorithms, the optinal argument iter may be provided, which then retrieves the ensemble at the given iteration.

get_ensemble(state::EnsembleState)

Retrieves the current ensemble matrix from the given EnsembleState. Must be implemented for each ensemble algorithm state type.

get_observables(sol::SimulatorInferenceSolution{<:EnsembleInferenceAlgorithm}, iter::Int=-1)

Returns a NamedTuple of concatenated observables at iteration iter.

get_transformed_ensemble(sol::SimulatorInferenceSolution{<:EnsembleInferenceAlgorithm}, iter::Int=-1)

Fetches the transformed ensemble from the given solution object. For iterative algorithms, the optinal argument iter may be provided, which then retrieves the ensemble at the given iteration.

getvalue(::Observable, ::Type{T}=Any) where {T}

Retreive the obsevable at all coordinates.

importance_weights(obs::AbstractVector, pred::AbstractMatrix, R::AbstractMatrix)

Computes the importance weights from the given observations, predictions, and noise covariance. When used for data assimilation, this algorithm is also known as the "particle batch smoother". This implementation is adapted from the python implementation by Kristoffer Aalstad:

https://github.com/ealonsogzl/MuSA/blob/0c02b8dc25a0f902bf63099de68174f4738705f0/modules/filters.py#L169

Original docstring:

Inputs: obs: Observation vector (m x 1 array) pred: Predicted observation ensemble matrix (m x N array) R: Observation error covariance 'matrix' (m x 1 array, or scalar) Outputs: w: Posterior weights (N x 1 array) Neff: Effective sample size Dimensions: N is the number of ensemble members and m is the number of observations.

Here we have implemented the particle batch smoother, which is a batch-smoother version of the particle filter (i.e. a particle filter without resampling), described in Margulis et al. (2015, doi: 10.1175/JHM-D-14-0177.1). As such, this routine can also be used for particle filtering with sequential data assimilation. This scheme is obtained by using a particle (mixture of Dirac delta functions) representation of the prior and applying this directly to Bayes theorem. In other words, it is just an application of importance sampling with the prior as the proposal density (importance distribution). It is also the same as the Generalized Likelihood Uncertainty Estimation (GLUE) technique (with a formal Gaussian likelihood)which is widely used in hydrology.

This particular scheme assumes that the observation errors are additive Gaussian white noise (uncorrelated in time and space). The "logsumexp" trick is used to deal with potential numerical issues with floating point operations that occur when dealing with ratios of likelihoods that vary by many orders of magnitude.

loglikelihood(lik::SimulatorLikelihood, args...)

Evaluates the log-lielihood of lik on the current observable state by constructing the predictive_distribution and evaluating the logpdf of the data.

logprob(d::UnivariateDistribution, x::Number)

Alias for logpdf(d,x) on Distribution types.

obscov(::AbstractMatrix)
obscov(::AbstractVector)
obscov(::Number)

Builds a standard form multivariate normal covariance matrix from the given matrix, vector (diagonal), or scalar (isotropic).

obscov(likelihoods::SimulatorLikelihood...)

Implementations should build a combined covariance matrix from the given likelihood types. The default implementation simply throws an error.

observe!(::Observable, state)

Computes and stores the relevant state variables from the given simulator state.

prior(args...; kwargs...)

Generic constructor for prior distribution types that can be implemented by subtypes of AbstractSimulatorPrior.

prior(name::Symbol, dist::Distribution)

Alias for NamedProductPrior((name = dist)).

prior(; dists...)

Alias for NamedProductPrior((; dists...)).

store!(::SimulationData, x::AbstractVector, y)

Stores the input/output pair x/y in the given forward map storage container.

unconstrained_forward_map(prior::AbstractSimulatorPrior, ζ)

Applies the forward map from unconstrained to forward model parameter (g ∘ f): Ζ ↦ Θ ↦ Φ where f⁻¹ is the inverse bijector of prior (i.e. mapping from unconstrained Ζ to constrained Θ space) and g is defined by forward_map which maps from Θ to the parameter space of the forward model, Φ.