Discuit.jl manual

See Discuit.jl examples for a brief introduction to the package's core functionality.

• Discuit.jl manual
  • Types
  • Functions
    • core functionality
    • model helpers
    • utilities
    • visualisation
    • custom MCMC
  • Index
  • References

Types

# Discuit.DiscuitModel — Type.

DiscuitModel

Fields

• model_name – string, e,g, "SIR".
• initial_condition – initial condition
• rate_function – event rate function.
• m_transition – transition matrix.
• `observation_function – observation function, use this to add 'noise' to simulated observations.
• prior_density – prior density function.
• observation_model – observation model likelihood function.
• t0_index – index of the parameter that represents the initial time. 0 if fixed at 0.0.

A mutable struct which represents a DSSCT model (see Discuit.jl models for further details).

source

# Discuit.SimResults — Type.

SimResults

Fields

• trajectory – a variable of type Trajectory.
• population – gives the state of the system after each event.
• observations – variable of type Observations.

The results of a simulation.

source

# Discuit.Trajectory — Type.

Trajectory

Fields

• time – event times.
• event_type – event type, index of model.rate_function.

A single realisation of the model.

source

# Discuit.Observations — Type.

Observations

Fields

• time – observation times.
• val – observation values.

Examples

# pooley dataset
pooley = Observations([20, 40, 60, 80, 100], [0 18; 0 65; 0 70; 0 66; 0 67])

Stores one column vector of observation times and one or more column vectors of observation integer values.

source

# Discuit.MCMCResults — Type.

MCMCResults

Fields

• samples – two dimensional array of samples.
• mc_accepted – proposal accepted
• mean – sample mean.
• covar – parameter covariance matrix.
• proposal_alg – proposal algorithm.
• num_obs – number of observations.
• adapt_period – adaptation (i.e. 'burn in') period.
• geweke – Geweke convergence diagnostic results (Tuple of Arrays).

The results of an MCMC analysis including samples; mean; covariance matrix; adaptation period; and results of the Geweke test of stationarity.

source

# Discuit.GelmanResults — Type.

GelmanResults

Fields

• mu – between chain sample mean.
• sdw – within chain standard deviation.
• sre – scale reduction factor estimate.
• sre_ll – scale reduction factor lower confidence interval.
• sre_ul – scale reduction factor upper confidence interval.
• mcmc – array of MCMCResults

Results of a Gelman Rubin convergence diagnostic including n MCMCResults variables; mu; and the scale reduction factor estimates (sre).

source

# Discuit.AutocorrelationResults — Type.

AutocorrelationResults

Fields

• lag – autocorrelation lag.
• autocorrelation – autocorrelation statistics.

Results of a call to compute_autocorrelation.

source

Functions

This section is organised in three parts:

• the main package core functionality for working with standard Discuit models
• utilities, for loading to and from file
• custom MCMC, for running custom algorithms

core functionality

# Discuit.set_random_seed — Function.

set_random_seed(seed)

Examples

set_random_seed(1234)

Does what it says on the tin but only if you give it an integer.

source

# Discuit.gillespie_sim — Function.

gillespie_sim(model, parameters, tmax = 100.0, num_obs = 5)

Parameters

• model – DiscuitModel (see [Discuit.jl models]@ref).
• parameters – model parameters.
• tmax – maximum time.
• num_obs – number of observations to draw,

Run a DGA simulation on model. Returns a SimResults containing the trajectory and observations data.

source

# Discuit.run_met_hastings_mcmc — Function.

run_met_hastings_mcmc(model, obs_data, initial_parameters, steps = 50000, adapt_period = 10000, mbp = true, ppp = 0.3)

Parameters

• model – DiscuitModel (see [Discuit.jl models]@ref).
• obs_data – Observations data.
• initial_parameters – initial model parameters (i.e. sample).
• steps – number of iterations.
• mbp – model based proposals (MBP). Set mbp = false for standard proposals.
• ppp – the proportion of parameter (vs. trajectory) proposals. Default: 30%. NB. not required for MBP.

Run an MCMC analysis based on model and obs_data of type Observations. The number of samples obtained is equal to steps - adapt_period.

source

# Discuit.run_gelman_diagnostic — Function.

run_gelman_diagnostic(model, obs_data, initial_parameters, steps = 50000, adapt_period = 10000, mbp = true, ppp = 0.3)

Parameters

• model – DiscuitModel (see [Discuit.jl models]@ref).
• obs_data – Observations data.
• initial_parameters – matrix of initial model parameters. Each column vector correspondes to a single model parameter.
• steps – number of iterations.
• adapt_period – number of discarded samples.
• mbp – model based proposals (MBP). Set mbp = false for standard proposals.
• ppp – the proportion of parameter (vs. trajectory) proposals. Default: 30%. NB. not required for MBP.

Run n (equal to the number of rows in initial_parameters) MCMC analyses and perform a Gelman-Rubin convergence diagnostic on the results. NEED TO OVERLOAD AND EXPAND.

source

# Discuit.compute_autocorrelation — Function.

compute_autocorrelation(mcmc, lags = 200)

Parameters

• mcmc – MCMCResults variable.
• lags – the number of lags to compute. Default: 200.

Compute autocorrelation R for a single Markov chain. Autocorrelation can be used to help determine how well the algorithm mixed by using compute_autocorrelation(rs.mcmc). The autocorrelation function for a single Markov chain is implemented in Discuit using the standard formula:

$$R_l = \frac{\textrm{E} [(X_i - \bar{X})(X_{i+l} - \bar{X})]}{\sigma^2}$$

for any given lag l up to lags (default: 200).

source

compute_autocorrelation(mcmc, lags = 200)

Parameters

• mcmc – an array of MCMCResults variables.
• lags – the number of lags to compute. Default: 200.

Compute autocorrelation R' for a two or more Markov chains. The formula for multiple chains is given by:

$$R^{\prime}_l = \frac{\textrm{E} [ (X_i - \bar{X}_b) ( X_{i + l} - \bar{X}_b ) ]}{\sigma^2_b}$$

$$\sigma^2_b = \textrm{E} [(X_i - \bar{X}_b)^2]$$

for any given lag l up to lags (default: 200).

source

model helpers

Discuit.jl includes tools for generating components which can help minimise the amount of work required to generate customised DiscuitModels, including generate_model(...) which is used to access a library of pre defined Discuit.jl models.

# Discuit.generate_generic_obs_function — Function.

generate_generic_obs_function()

Generates a simple observation function for use in a DiscuitModel. Not very realistic...

source

# Discuit.generate_weak_prior — Method.

generate_weak_prior(n)

Parameters

• n – the number of parameters in the model.

Examples

generate_weak_prior(1)

Generate a "weak" prior density function, where n is the number of parameters in the model.

source

# Discuit.generate_gaussian_obs_model — Function.

generate_gaussian_obs_model(n, σ = 2.0)

Parameters

• n – the number of discrete states in the model.
• σ – observation error.

test latex eqn:

$$rac{n!}{k!(n - k)!} = inom{n}{k}$$

Examples

p = generate_weak_prior(1)

Generate a Gaussian observation model for a model with n states. Optionally specify observation error σ.

source

# Discuit.generate_model — Function.

generate_model(model_name, initial_condition, σ = 2.0)

Parameters

• model_name – the model, e.g. "SI"; "SIR"; "SEIR"; etc
• initial_condition – initial condition.
• σ – observation error.

model_name options

• "SI"
• "SIR"
• "SIS"
• "SEI"
• "SEIR"
• "SEIS"
• "SEIRS"
• "PREDPREY"
• "ROSSMAC"

Examples

generate_model("SIS", [100,1])

Generates a DiscuitModel. Optionally specify observation error σ.

source

utilities

# Discuit.print_trajectory — Function.

print_trajectory(model, sim_results, fpath)

Parameters

• model – DiscuitModel (see [Discuit.jl models]@ref).
• sim_results – SimResults variable.
• fpath – the destination file path.

Save an augmented trajectory from a variable of type SimResults (i.e. from a call to gillespie_sim, see Simulation) to the file fpath, e.g. "./out/sim.csv".

source

# Discuit.print_observations — Function.

print_observations(obs_data, fpath)

Parameters

• obs_data – Observations data.
• fpath – the destination file path.

Save a set of observations (e.g. from a SimResults obtained by a call to gillespie_sim to the file fpath, e.g. "./out/obs.csv".

source

# Discuit.get_observations — Function.

get_observations(source)

Parameters

• source – Array, DataFrame or filepath (i.e. String) containing the data (with times in the first column).

Create and return a variable of type Observations based on a two dimensional array, DataFrame or file location.

source

# Discuit.tabulate_mcmc_results — Function.

tabulate_mcmc_results

Parameters

• results – MCMCResults object.
• proposals – display proposal analysis.

Display the results of an MCMC analysis.

source

# Discuit.print_mcmc_results — Function.

print_mcmc_results(mcmc, dpath)

Parameters

• results – MCMCResults variable.
• dpath – the path of the directory where the results will be saved.

Save the results from a call to run_met_hastings_mcmc or run_custom_mcmc to the directory dpath, e.g. "./out/mcmc/".

source

# Discuit.tabulate_gelman_results — Function.

tabulate_gelman_results

Parameters

• results – the results of a call to run_gelman_diagnostic.
• proposals – display proposal analysis.

Display the results of a multi chain analysis run using run_gelman_diagnostic.

source

# Discuit.print_gelman_results — Function.

print_gelman_results(results::GelmanResults, dpath::String)

Parameters

• results – GelmanResults variable.
• dpath – the path of the directory where the results will be saved.

Save the results from a call to run_gelman_diagnostic to the directory dpath, e.g. "./out/gelman/".

source

# Discuit.print_autocorrelation — Function.

print_autocorrelation(autocorrelation, fpath)

Parameters

• autocorrelation – the results of a call to compute_autocorrelation.
• fpath – the file path of the destination file.

Save the results from a call to compute_autocorrelation to the file fpath, e.g. "./out/ac.csv".

source

visualisation

# Discuit.plot_trajectory — Function.

plot_trajectory(x)

Parameters

• x – SimResults, i.e. from a call to gillespie_sim.

Plot the trajectory of a a DGA simulation on model using UnicodePlots.jl.

source

# Discuit.plot_parameter_trace — Function.

plot_parameter_trace(mcmc, parameter)

Parameters

• mcmc – MCMCResults, e.g. from a call to run_met_hastings_mcmc.
• parameter – the index of the model parameter to be plotted.

Trace plot of samples from an MCMC analysis for a given model parameter using UnicodePlots.jl.

source

plot_parameter_trace(mcmc, parameter)

Parameters

• mcmc – array of MCMCResults, e.g. from a call to run_gelman_diagnostic.
• parameter – the index of the model parameter to be plotted.

Trace plot of samples from n MCMC analyses for a given model parameter using UnicodePlots.jl.

source

# Discuit.plot_parameter_marginal — Function.

plot_parameter_marginal(mcmc, parameter)

Parameters

• mcmc – MCMCResults, e.g. from a call to run_met_hastings_mcmc.
• parameter – the index of the model parameter to be plotted.

Plot the marginal distribution of samples from an MCMC analysis for a given model parameter using UnicodePlots.jl.

source

# Discuit.plot_parameter_heatmap — Function.

plot_parameter_heatmap(mcmc, x_parameter, y_parameter)

Parameters

• mcmc – MCMCResults, e.g. from a call to run_met_hastings_mcmc.
• x_parameter – the index of the model parameter to be plotted on the x axis.
• y_parameter – the index of the model parameter to be plotted on the y axis.

Plot the marginal distribution of samples from an MCMC analysis for two model parameters using UnicodePlots.jl.

source

# Discuit.plot_geweke_series — Function.

plot_geweke_series(mcmc)

Parameters

• mcmc – MCMCResults, e.g. from a call to run_met_hastings_mcmc.

Plot the Geweke series...

source

# Discuit.plot_autocorrelation — Function.

plot_autocorrelation(autocorrelation)

Parameters

• autocorrelation – The results from a call to compute_autocorrelation.

Plot autocorrelation for an MCMC analysis.

source

custom MCMC

# Discuit.run_custom_mcmc — Function.

run_custom_mcmc(model, obs_data, proposal_function, x0, steps = 50000, adapt_period = 10000, prop_param = false, ppp = 0.3)

Parameters

• model – DiscuitModel (see [Discuit.jl models]@ref).
• obs_data – Observations data.
• proposal_function – Function for proposing changes to the trajectory. Must have the signature: custom_proposal(model::PrivateDiscuitModel, xi::MarkovState, xf_parameters::ParameterProposal) = MarkovState(...)
• x0 – MarkovState representing the initial sample and trajectory.
• steps – number of iterations.
• adapt_period – burn in period.
• prop_param – simulaneously propose changes to parameters. Default: false.
• ppp – the proportion of parameter (vs. trajectory) proposals. Default: 30%. NB. not relevant if prop_param = true.

Run a custom MCMC analysis. Similar to run_met_hastings_mcmc except that theproposal_function (of type Function) and initial state x0 (of type MarkovState) are user defined.

source

# Discuit.run_custom_mcmc_gelman_diagnostic — Function.

run_custom_mcmc_gelman_diagnostic(m_model, obs_data, proposal_function, x0, initial_parameters, steps = 50000, adapt_period = 10000, mbp = true, ppp = 0.3)

Parameters

• model – DiscuitModel (see [Discuit.jl models]@ref).
• obs_data – Observations data.
• proposal_function – Function for proposing changes to the trajectory. Must have the signature: custom_proposal(model::PrivateDiscuitModel, xi::MarkovState, xf_parameters::ParameterProposal) = MarkovState(...)
• x0 – vector of MarkovStates representing the initial samples.
• initial_parameters – matrix of initial model parameters. Each column vector correspondes to a single model parameter.
• steps – number of iterations.
• adapt_period – number of discarded samples.
• prop_param – simulaneously propose changes to parameters. Default: false.
• ppp – the proportion of parameter (vs. trajectory) proposals. Default: 30%. NB. not required for MBP.

Run n (equal to the number of rows in initial_parameters) custom MCMC analyses and perform a Gelman-Rubin convergence diagnostic on the results. NEED TO OVERLOAD AND EXPAND.

source

# Discuit.generate_custom_x0 — Function.

generate_custom_x0(model, obs_data, parameters, event_times, event_types)

Parameters

• model – DiscuitModel (see [Discuit.jl models]@ref).
• obs_data – Observations data.
• parameters – Array of initial model parameters.
• event_times – Array of floats representing the event times.
• event_types – Array of integer event types.

Generate an initial MarkovState for use in a custom MCMC algorithm.

source

Index

• Discuit
• Discuit.AutocorrelationResults
• Discuit.DiscuitModel
• Discuit.GelmanResults
• Discuit.MCMCResults
• Discuit.Observations
• Discuit.SimResults
• Discuit.Trajectory
• Discuit.compute_autocorrelation
• Discuit.generate_custom_x0
• Discuit.generate_gaussian_obs_model
• Discuit.generate_generic_obs_function
• Discuit.generate_model
• Discuit.generate_weak_prior
• Discuit.get_observations
• Discuit.gillespie_sim
• Discuit.plot_autocorrelation
• Discuit.plot_geweke_series
• Discuit.plot_parameter_heatmap
• Discuit.plot_parameter_marginal
• Discuit.plot_parameter_trace
• Discuit.plot_trajectory
• Discuit.print_autocorrelation
• Discuit.print_gelman_results
• Discuit.print_mcmc_results
• Discuit.print_observations
• Discuit.print_trajectory
• Discuit.run_custom_mcmc
• Discuit.run_custom_mcmc_gelman_diagnostic
• Discuit.run_gelman_diagnostic
• Discuit.run_met_hastings_mcmc
• Discuit.set_random_seed
• Discuit.tabulate_gelman_results
• Discuit.tabulate_mcmc_results

References

TBA