ABC Basic Reference

ABCRejectionOutput

A container for the output of a rejection-ABC computation.

Fields

• n_params::Int64: The number of parameters to be estimated.
• n_accepted::Int64: The number of accepted parameter vectors (particles) in the posterior.
• n_tries::Int64: The total number of parameter vectors (particles) that were tried.
• threshold::Float64: The maximum distance from the summarised model output to summarised observed data for a parameter vector to be included in the posterior.
• population::AbstractArray{Float64,2}: The parameter vectors (particles) in the posterior. Size: (n_accepted, n_params).
• distances::AbstractArray{Float64,1}: The distances for each parameter vector (particle) in the posterior to the observed data in summary statistic space. Size: (n_accepted).
• weights::StatsBase.Weights: The weight of each parameter vector (particle) in the posterior.

ABCSMCOutput

A container for the output of a rejection-ABC computation.

Fields

• n_params::Int64: The number of parameters to be estimated.
• n_accepted::Int64: The number of accepted parameter vectors (particles) in the posterior.
• n_tries::Int64: The total number of parameter vectors (particles) that were tried.
• threshold_schedule::AbstractArray{Float64}: A set of maximum distances from the summarised model output to summarised observed data for a parameter vector to be included in the posterior. Each distance will be used in a single run of the ABC-SMC algorithm.
• population::AbstractArray{Float64,2}: The parameter vectors (particles) in the posterior. Size: (n_accepted, n_params).
• distances::AbstractArray{Float64,1}: The distances for each parameter vector (particle) in the posterior to the observed data in summary statistic space. Size: (n_accepted).
• weights::StatsBase.Weights: The weight of each parameter vector (particle) in the posterior.

SimulatedABCRejection(
    reference_data,
    simulator_function,
    priors,
    threshold,
    n_particles;
    summary_statistic   = "keep_all",
    distance_function   = Distances.euclidean,
    max_iter            = 10 * n_particles,
    write_progress      = true,
    progress_every      = 1000,
    )

Run simulation-based rejection ABC algorithm. Particles are sampled from the prior, and the model is simulated for each particle. Only those particles are included in the posterior that have distance between the simulation results and the reference data below the threshold (after taking summary statistics into account).

See ABC Overview for more details.

Mandatory arguments

• reference_data::AbstractArray{Float,2}: Observed data to which the simulated model output will be compared. Array dimensions should match that of the simulator function result.
• simulator_function::Function: A function that takes a parameter vector as an argument and outputs model results.
• priors::AbstractArray{ContinuousUnivariateDistribution,1}: Continuous univariate distributions, from which candidate parameters will be sampled. Array size should match the number of parameters.
• threshold::Float: The $\varepsilon$ threshold to be used in ABC algorithm. Only those particles that produce simulated results that are within this threshold from the reference data are included into the posterior.
• n_particles::Int: The number of parameter vectors (particles) that will be included in the posterior.

Optional keyword arguments

• summary_statistic::Union{String,AbstractArray{String,1},Function}: Summary statistics that will be applied to the data before computing the distances. Defaults to keep_all. See detailed documentation of summary statistics.
• distance_function::Union{Function,Metric}: A function or metric that will be used to compute the distance between the summary statistic of the simulated data and that of reference data. Defaults to Distances.euclidean.
• max_iter::Int: The maximum number of simulations that will be run. The default is 1000 * n_particles.
• write_progress::Bool: Whether algorithm progress should be printed on standard output. Defaults to true.
• progress_every::Int: Number of iterations at which to print progress. Defaults to 1000.

Returns

An ABCRejectionOutput object.

EmulatedABCRejection(
    reference_data,
    simulator_function,
    priors,
    threshold,
    n_particles,
    n_design_points;
    summary_statistic               = "keep_all",
    distance_function               = Distances.euclidean,
    batch_size                      = 10*n_particles,
    max_iter                        = 1000,
    emulator_training               = DefaultEmulatorTraining(),
    emulated_particle_selection     = MeanEmulatedParticleSelection(),
    write_progress                  = true,
    progress_every                  = 1000,
    )

Run emulation-based rejection ABC algorithm. Model simulation results are used to train the emulator, which is then used to get the approximated distance for each particle. The rest of the workflow is similar to SimulatedABCRejection.

See ABC Overview for more details.

Mandatory arguments

• reference_data::AbstractArray{Float,2}: Observed data to which the simulated model output will be compared. Array dimensions should match that of the simulator function result.
• simulator_function::Function: A function that takes a parameter vector as an argument and outputs model results.
• priors::AbstractArray{ContinuousUnivariateDistribution,1}: Continuous univariate distributions, from which candidate parameters will be sampled. Array size should match the number of parameters.
• threshold::Float: The $\varepsilon$ threshold to be used in ABC algorithm. Only those particles that produce emulated results that are within this threshold from the reference data are included into the posterior.
• n_particles::Int: The number of parameter vectors (particles) that will be included in the posterior.
• n_design_points::Int: The number of design particles that will be simulated to train the emulator.

Optional keyword arguments

• summary_statistic::Union{String,AbstractArray{String,1},Function}: Summary statistics that will be applied to the data before computing the distances. Defaults to keep_all. See detailed documentation of summary statistics.
• distance_function::Union{Function,Metric}: A function or metric that will be used to compute the distance between the summary statistic of the simulated data and that of reference data. Defaults to Distances.euclidean.
• batch_size::Int: The number of particles that will be emulated on each iteration. Defaults to 1000 * n_particles.
• max_iter::Int: The maximum number of emulations that will be run. Defaults to 1000.
• emulator_training<:AbstractEmulatorTraining: This determines how the emulator will be trained. See AbstractEmulatorTraining for more details.
• emulated_particle_selection<:AbstractEmulatedParticleSelection: This determines how the particles that will be added to the posterior are selected after each emulation run. See AbstractEmulatedParticleSelection for details. Defaults to MeanEmulatedParticleSelection.
• write_progress::Bool: Whether algorithm progress should be printed on standard output. Defaults to true.

Returns

An ABCRejectionOutput object.

SimulatedABCSMC(
    reference_data,
    simulator_function,
    priors,
    threshold_schedule,
    n_particles;
    summary_statistic   = "keep_all",
    distance_function   = Distances.euclidean,
    max_iter            = 10 * n_particles,
    write_progress      = true,
    progress_every      = 1000,
    )

Run a simulation-based ABC-SMC algorithm. This is similar to SimulatedABCRejection, the main difference being that an array of thresholds is provided instead of a single threshold. It is assumed that thresholds are sorted in decreasing order.

A simulation based ABC iteration is executed for each threshold. For the first threshold, the provided prior is used. For each subsequent threshold, the posterior from the previous iteration is used as a prior.

See ABC Overview for more details.

Mandatory arguments

• reference_data::AbstractArray{Float,2}: Observed data to which the simulated model output will be compared. Array dimensions should match that of the simulator function result.
• simulator_function::Function: A function that takes a parameter vector as an argument and outputs model results.
• priors::AbstractArray{ContinuousUnivariateDistribution,1}: Continuous univariate distributions, from which candidate parameters will be sampled during the first iteration. Array size should match the number of parameters.
• threshold_schedule::AbstractArray{Float,1}: The threshold schedule to be used in ABC algorithm. An ABC iteration is executed for each threshold. It is assumed that thresholds are sorted in decreasing order.
• n_particles::Int: The number of parameter vectors (particles) that will be included in the posterior.

Optional keyword arguments

• summary_statistic::Union{String,AbstractArray{String,1},Function}: Summary statistics that will be applied to the data before computing the distances. Defaults to keep_all. See detailed documentation of summary statistics.
• distance_function::Union{Function,Metric}: A function or metric that will be used to compute the distance between the summary statistic of the simulated data and that of reference data. Defaults to Distances.euclidean.
• max_iter::Int: The maximum number of simulations that will be run. The default is 1000 * n_particles.
• write_progress::Bool: Whether algorithm progress should be printed on standard output. Defaults to true.
• progress_every::Int: Number of iterations at which to print progress. Defaults to 1000.

Returns

An ABCSMCOutput object.

EmulatedABCSMC(
    reference_data,
    simulator_function,
    priors,
    threshold_schedule,
    n_particles,
    n_design_points;
    summary_statistic               = "keep_all",
    distance_function               = Distances.euclidean,
    batch_size                      = 10*n_particles,
    max_iter                        = 1000,
    emulator_training               = DefaultEmulatorTraining(),
    emulator_retraining             = NoopRetraining(),
    emulated_particle_selection     = MeanEmulatedParticleSelection(),
    write_progress                  = true,
    progress_every                  = 1000,
    )

Run emulation-based ABC-SMC algorithm. This is similar to EmulatedABCRejection, the main difference being that an array of thresholds is provided instead of a single threshold. It is assumed that thresholds are sorted in decreasing order.

An emulation based ABC iteration is executed for each threshold. For the first threshold, the provided prior is used. For each subsequent threshold, the posterior from the previous iteration is used as a prior.

See ABC Overview for more details.

Mandatory arguments

• reference_data::AbstractArray{Float,2}: Observed data to which the simulated model output will be compared. Array dimensions should match that of the simulator function result.
• simulator_function::Function: A function that takes a parameter vector as an argument and outputs model results.
• priors::AbstractArray{ContinuousUnivariateDistribution,1}: Continuous univariate distributions, from which candidate parameters will be sampled during the first iteration. Array size should match the number of parameters.
• threshold_schedule::AbstractArray{Float,1}: The threshold schedule to be used in ABC algorithm. An ABC iteration is executed for each threshold. It is assumed that thresholds are sorted in decreasing order.
• n_particles::Int: The number of parameter vectors (particles) that will be included in the posterior.
• n_design_points::Int: The number of design particles that will be simulated to train the emulator.

Optional keyword arguments

• summary_statistic::Union{String,AbstractArray{String,1},Function}: Summary statistics that will be applied to the data before computing the distances. Defaults to keep_all. See detailed documentation of summary statistics.
• distance_function::Union{Function,Metric}: A function or metric that will be used to compute the distance between the summary statistic of the simulated data and that of reference data. Defaults to Distances.euclidean.
• batch_size::Int: The number of particles that will be emulated on each iteration. Defaults to 1000 * n_particles.
• max_iter::Int: The maximum number of emulations that will be run. Defaults to 1000.
• emulator_training<:AbstractEmulatorTraining: This determines how the emulator will be trained for each iteration. See AbstractEmulatorTraining for more details.
• emulator_retraining<:AbstractEmulatorRetraining: This is used to specify parameters of additional emulator retraining that can be done for each iteration. By default this retraining is switched off (NoopRetraining). See [AbstractEmulatorRetraining] for more details.
• emulated_particle_selection<:AbstractEmulatedParticleSelection: This determines how the particles that will be added to the posterior are selected after each emulation run. See AbstractEmulatedParticleSelection for details. Defaults to MeanEmulatedParticleSelection.
• write_progress::Bool: Whether algorithm progress should be printed on standard output. Defaults to true.

Returns

An ABCSMCOutput object.