Getting Started¶

This page assumes that you have already installed the epifx package, and shows how to generate forecasts using an SEIR model.

Infection models¶

class epifx.det.SEIR¶

An SEIR compartment model for a single circulating influenza strain, under the assumption that recovered individuals are completely protected against reinfection.

\[\begin{split}\frac{dS}{dt} &= - \beta S^\eta I \\[0.5em] \frac{dE}{dt} &= \beta S^\eta I - \sigma E \\[0.5em] \frac{dI}{dt} &= \sigma E - \gamma I \\[0.5em] \frac{dR}{dt} &= \gamma I \\[0.5em] \beta &= R_0 \cdot \gamma\end{split}\]

Parameter	Meaning
\(R_0\)	Basic reproduction number
\(\sigma\)	Inverse of the incubation period (day ^-1)
\(\gamma\)	Inverse of the infectious period (day ^-1)
\(\eta\)	Inhomogeneous social mixing coefficient
\(\alpha\)	Temporal forcing coefficient

The force of infection can be subject to temporal forcing \(F(t)\), as mediated by \(\alpha\):

\[\beta(t) = \beta \cdot \left[1 + \alpha \cdot F(t)\right]\]

Note that this requires the forcing time-series to be stored in the lookup table 'R0_forcing'.

Initialise the model instance.

init(ctx, vec)¶

Initialise a state vector.

Parameters:	ctx – The simulation context. vec – An uninitialised state vector of correct dimensions (see `state_size()`).

update(ctx, step_date, dt, is_fs, prev, curr)¶

Perform a single time-step.

Parameters:	ctx – The simulation context. step_date – The date and time of the current time-step. dt – The time-step size (days). is_fs – Indicates whether this is a forecasting simulation. prev – The state before the time-step. curr – The state after the time-step (destructively updated).

class epifx.det.SEEIIR¶

An SEEIIR compartment model for a single circulating influenza strain, under the assumption that recovered individuals are completely protected against reinfection.

\[\begin{split}\frac{dS}{dt} &= - \beta S^\eta (I_1 + I_2) \\[0.5em] \frac{dE_1}{dt} &= \beta S^\eta (I_1 + I_2) - 2 \sigma E_1 \\[0.5em] \frac{dE_2}{dt} &= 2 \sigma E_1 - 2 \sigma E_2 \\[0.5em] \frac{dI_1}{dt} &= 2 \sigma E_2 - 2 \gamma I_1 \\[0.5em] \frac{dI_2}{dt} &= 2 \gamma I_1 - 2 \gamma I_2 \\[0.5em] \frac{dR}{dt} &= 2 \gamma I_2 \\[0.5em] \beta &= R_0 \cdot \gamma\end{split}\]

Parameter	Meaning
\(R_0\)	Basic reproduction number
\(\sigma\)	Inverse of the incubation period (day ^-1)
\(\gamma\)	Inverse of the infectious period (day ^-1)
\(\eta\)	Inhomogeneous social mixing coefficient
\(\alpha\)	Temporal forcing coefficient

The force of infection can be subject to temporal forcing \(F(t)\), as mediated by \(\alpha\):

\[\beta(t) = \beta \cdot \left[1 + \alpha \cdot F(t)\right]\]

Note that this requires the forcing time-series to be stored in the lookup table 'R0_forcing'.

Initialise the model instance.

init(ctx, vec)¶

Initialise a state vector.

Parameters:	ctx – The simulation context. vec – An uninitialised state vector of correct dimensions (see `state_size()`).

update(ctx, step_date, dt, is_fs, prev, curr)¶

Perform a single time-step.

Parameters:	ctx – The simulation context. step_date – The date and time of the current time-step. dt – The time-step size (days). is_fs – Indicates whether this is a forecasting simulation. prev – The state before the time-step. curr – The state after the time-step (destructively updated).

class epifx.stoch.SEEIIR¶

A stochastic SEEIIR compartment model.

init(ctx, vec)¶

Initialise a state vector.

Parameters:	ctx – The simulation context. vec – An uninitialised state vector of correct dimensions (see `state_size()`).

update(ctx, step_date, dt, is_fs, prev, curr)¶

Perform a single time-step.

Parameters:	ctx – The simulation context. step_date – The date and time of the current time-step. dt – The time-step size (days). is_fs – Indicates whether this is a forecasting simulation. prev – The state before the time-step. curr – The state after the time-step (destructively updated).

stat_info()¶

Return the summary statistics that are provided by this model.

Each statistic is represented as a (name, stat_fn) tuple, where name is a string and stat_fn is a function that accepts one argument (the particle history matrix) and returns the statistic (see, e.g., stat_generation_interval()).

stat_generation_interval(hist)¶

Calculate the mean generation interval for each particle.

Parameters:	hist – The particle history matrix, or a subset thereof.

Arbitrary model priors¶

In addition to sampling each model parameter independently, the epifx.select module provides support for sampling particles according to arbitrary target distributions, using an accept-reject sampler.

epifx.select.select(params, proposal, target, seed)¶

Select particles according to a target distribution.

Parameters:	params – The simulation parameters (note: the parameter dictionary will be emptied once the particles have been selected). proposal – The proposal distribution. target – The target distribution. seed – The PRNG seed used for sampling and accepting particles.
Returns:	The initial state vector for each accepted particle.
Return type:	numpy.ndarray

# Save the accepted particles to disk.
vec = epifx.select.select(params, start, end, proposal, target, seed)

# Load the accepted particles for use in a simulation.
model = epifx.SEIR()
model.set_params(vec)
params = epifx.default_params(px_count, model, time, popn_size)

Any proposal distribution can be used with this sampler, including the default model prior:

class epifx.select.Proposal¶

The base class for proposal particle distributions.

sample(params, hist, prng)¶

Draw particle samples from the proposal distribution.

Parameters:	params – The simulation parameters. hist – The particle history matrix into which the samples should be written. prng – The PRNG instance to use for any random sampling.

class epifx.select.DefaultProposal¶

A proposal distribution that independently samples each parameter from the prior distributions provided in the simulation parameters.

sample(ctx, hist, prng)¶

Draw particle samples from the proposal distribution.

Parameters:	params – The simulation parameters. hist – The particle history matrix into which the samples should be written. prng – The PRNG instance to use for any random sampling.

Any target distribution for which a probability density can be defined can be used with this sampler:

class epifx.select.Target¶

The base class for target particle distributions.

define_summary_components(params)¶

Add summary monitors and tables so that required summary statistics are recorded for each proposed particle.

Parameters:	params – The simulation parameters.

logpdf(ctx, output)¶

Return the log of the target probability density for each particle.

Parameters:	ctx – The simulation context. output – The state object returned by `pypfilt.pfilter.run`; summary tables are located at `output['summary'][table_name]`.

Two target distributions are provided by this module.

The TargetAny distribution accepts all particles with equal likelihood, for the case where the proposal distribution is identical to the desired target distribution:

class epifx.select.TargetAny¶

A distribution that accepts all proposals with equal likelihood.

define_summary_components(params)¶

Add summary monitors and tables so that required summary statistics are recorded for each proposed particle.

Parameters:	params – The simulation parameters.

logpdf(ctx, output)¶

Return the log of the target probability density for each particle.

Parameters:	ctx – The simulation context. output – The state object returned by `pypfilt.pfilter.run`; summary tables are located at `output['summary'][table_name]`.

The TargetPeakMVN distribution is a multivariate normal distribution for the peak timing and size, as defined by previously-observed peaks:

class epifx.select.TargetPeakMVN(peak_sizes, peak_times)¶

A multivariate normal distribution for the peak timing and size.

Parameters:	peak_sizes – An array of previously-observed peak sizes. peak_time – An array of previously-observed peak times.

define_summary_components(params)¶

Add summary monitors and tables so that required summary statistics are recorded for each proposed particle.

Parameters:	params – The simulation parameters.

logpdf(ctx, output)¶

Return the log of the target probability density for each particle.

Parameters:	ctx – The simulation context. output – The state object returned by `pypfilt.pfilter.run`; summary tables are located at `output['summary'][table_name]`.

Observation models¶

The epifx.obs module provides generic observation models for count data with known or unknown denominators, as well as functions for reading observations from disk.

Each observation model must have a unique unit, and is used to calculate likelihoods for all observations that share this same unit.

import epifx.obs

# Create the simulation parameters.
params = ...
# Create an observation model for weekly data (with a period of 7 days),
# that pertains to all observations whose unit is "obs_unit".
obs_model = epifx.obs.PopnCounts("obs_unit", obs_period=7)
# Define the observation model parameters.
obs_model.define_params(params, bg_obs=300, pr_obs=0.01, disp=100)

Forecast summaries¶

epifx.summary.make(params, all_obs, default=True, extra_tbls=None)¶

A convenience function that collects all of the summary statistics defined in the pypfilt.summary and epifx.summary modules.

Parameters:	params – The simulation parameters. all_obs – A list of all observations. default – Whether to add all of the tables defined in the `pypfilt.summary` and `epifx.summary` modules. extra_tbls – A list of extra summary statistic tables to include.

For example:

from epifx.summary import make
params = ...
all_obs = ...
stats = make(params, all_obs, first_day=True, only_fs=True)

class epifx.summary.PrOutbreak¶

Record the daily outbreak probability, defined as the sum of the weights of all particles in which an outbreak has been seeded.

Parameters:	name – the name of the table in the output file.

dtype(ctx, obs_list, name)¶

Return the column names and data types, represented as a list of (name, data type) tuples. See the NumPy documentation for details.

Parameters:	params – The simulation parameters. obs_list – A list of all observations. name – The table’s name.

n_rows(start_date, end_date, n_days, n_sys, forecasting)¶

Return the number of rows required for a single simulation.

Parameters:	start_date – The date at which the simulation starts. end_date – The date at which the simulation ends. n_days – The number of days for which the simulation runs. n_sys – The number of observation systems (i.e., data sources). forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics for some portion of a simulation.

Parameters:

hist – The particle history matrix.
weights – The weight of each particle at each date in the simulation window; it has dimensions (d, p) for d days and p particles.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
dates – A list of (datetime, ix, hist_ix) tuples that identify each day in the simulation window, the index of that day in the simulation window, and the index of that day in the particle history matrix.
obs_types – A set of (unit, period) tuples that identify each observation system from which observations have been taken.
insert_fn – A function that inserts one or more rows into the underlying data table; see the examples below.

The row insertion function can be used as follows:

# Insert a single row, represented as a tuple.
insert_fn((x, y, z))
# Insert multiple rows, represented as a list of tuples.
insert_fn([(x0, y0, z0), (x1, y1, z1)], n=2)

class epifx.summary.PeakMonitor(exp_obs_monitor)¶

Record epidemic peak forecasts, for use with other statistics.

Parameters:	exp_obs_monitor – the name of a `pypfilt.summary.ExpectedObsMonitor`.

peak_size = None¶

A dictionary that maps observation systems to the size of each particle’s peak with respect to that system: peak_size[(unit, period)].

Note that this is only valid for tables to inspect in the finished() method, and not in the add_rows() method.

peak_date = None¶

A dictionary that maps observation systems to the date of each particle’s peak with respect to that system: peak_date[(unit, period)].

Note that this is only valid for tables to inspect in the finished() method, and not in the add_rows() method.

peak_time = None¶

A dictionary that maps observation systems to the time of each particle’s peak with respect to that system, measured in (fractional) days from the start of the forecasting period: peak_time[(unit, period)].

Note that this is only valid for tables to inspect in the finished() method, and not in the add_rows() method.

peak_weight = None¶

A dictionary that maps observation systems to the weight of each particle at the time that its peak occurs: peak_weight[(unit, period)].

Note that this is only valid for tables to inspect in the finished() method, and not in the add_rows() method.

expected_obs = None¶

The expected observation for each particle for the duration of the current simulation window.

Note that this is only valid for tables to inspect in each call to add_rows(), and not in a call to finished().

days_to(date)¶: Convert a date to the (fractional) number of days from the start of the forecasting period.

class epifx.summary.PeakForecastEnsembles(peak_monitor, fs_only=True)¶

Record the weighted ensemble of peak size and time predictions for each forecasting simulation.

Parameters:	peak_monitor – the name of a `PeakMonitor`. name – the name of the table in the output file.

dtype(ctx, obs_list, name)¶

Return the column names and data types, represented as a list of (name, data type) tuples. See the NumPy documentation for details.

Parameters:	params – The simulation parameters. obs_list – A list of all observations. name – The table’s name.

n_rows(start_date, end_date, n_days, n_sys, forecasting)¶

Return the number of rows required for a single simulation.

Parameters:	start_date – The date at which the simulation starts. end_date – The date at which the simulation ends. n_days – The number of days for which the simulation runs. n_sys – The number of observation systems (i.e., data sources). forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics for some portion of a simulation.

Parameters:

hist – The particle history matrix.
weights – The weight of each particle at each date in the simulation window; it has dimensions (d, p) for d days and p particles.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
dates – A list of (datetime, ix, hist_ix) tuples that identify each day in the simulation window, the index of that day in the simulation window, and the index of that day in the particle history matrix.
obs_types – A set of (unit, period) tuples that identify each observation system from which observations have been taken.
insert_fn – A function that inserts one or more rows into the underlying data table; see the examples below.

The row insertion function can be used as follows:

# Insert a single row, represented as a tuple.
insert_fn((x, y, z))
# Insert multiple rows, represented as a list of tuples.
insert_fn([(x0, y0, z0), (x1, y1, z1)], n=2)

finished(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics at the end of a simulation.

The parameters are as per add_rows().

Derived classes should only implement this method if rows must be recorded by this method; the provided method does nothing.

class epifx.summary.PeakForecastCIs(peak_monitor, probs=None)¶

Record fixed-probability central credible intervals for the peak size and time predictions.

Parameters:	peak_monitor – the name of a `PeakMonitor`. probs – an array of probabilities that define the size of each central credible interval. The default value is `numpy.uint8([0, 50, 90, 95, 99, 100])`. name – the name of the table in the output file.

dtype(ctx, obs_list, name)¶

Return the column names and data types, represented as a list of (name, data type) tuples. See the NumPy documentation for details.

Parameters:	params – The simulation parameters. obs_list – A list of all observations. name – The table’s name.

n_rows(start_date, end_date, n_days, n_sys, forecasting)¶

Return the number of rows required for a single simulation.

Parameters:	start_date – The date at which the simulation starts. end_date – The date at which the simulation ends. n_days – The number of days for which the simulation runs. n_sys – The number of observation systems (i.e., data sources). forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics for some portion of a simulation.

Parameters:

hist – The particle history matrix.
weights – The weight of each particle at each date in the simulation window; it has dimensions (d, p) for d days and p particles.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
dates – A list of (datetime, ix, hist_ix) tuples that identify each day in the simulation window, the index of that day in the simulation window, and the index of that day in the particle history matrix.
obs_types – A set of (unit, period) tuples that identify each observation system from which observations have been taken.
insert_fn – A function that inserts one or more rows into the underlying data table; see the examples below.

The row insertion function can be used as follows:

# Insert a single row, represented as a tuple.
insert_fn((x, y, z))
# Insert multiple rows, represented as a list of tuples.
insert_fn([(x0, y0, z0), (x1, y1, z1)], n=2)

finished(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics at the end of a simulation.

The parameters are as per add_rows().

Derived classes should only implement this method if rows must be recorded by this method; the provided method does nothing.

class epifx.summary.PeakSizeAccuracy(peak_monitor, toln=None)¶

Record the accuracy of the peak size predictions against multiple accuracy tolerances.

Parameters:	peak_monitor – the name of a `PeakMonitor`. name – the name of the table in the output file. toln – The accuracy thresholds for peak size predictions, expressed as percentages of the true size. The default is `np.array([10, 20, 25, 33])`.

dtype(ctx, obs_list, name)¶

Return the column names and data types, represented as a list of (name, data type) tuples. See the NumPy documentation for details.

Parameters:	params – The simulation parameters. obs_list – A list of all observations. name – The table’s name.

n_rows(start_date, end_date, n_days, n_sys, forecasting)¶

Return the number of rows required for a single simulation.

Parameters:	start_date – The date at which the simulation starts. end_date – The date at which the simulation ends. n_days – The number of days for which the simulation runs. n_sys – The number of observation systems (i.e., data sources). forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics for some portion of a simulation.

Parameters:

hist – The particle history matrix.
weights – The weight of each particle at each date in the simulation window; it has dimensions (d, p) for d days and p particles.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
dates – A list of (datetime, ix, hist_ix) tuples that identify each day in the simulation window, the index of that day in the simulation window, and the index of that day in the particle history matrix.
obs_types – A set of (unit, period) tuples that identify each observation system from which observations have been taken.
insert_fn – A function that inserts one or more rows into the underlying data table; see the examples below.

The row insertion function can be used as follows:

# Insert a single row, represented as a tuple.
insert_fn((x, y, z))
# Insert multiple rows, represented as a list of tuples.
insert_fn([(x0, y0, z0), (x1, y1, z1)], n=2)

finished(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics at the end of a simulation.

The parameters are as per add_rows().

Derived classes should only implement this method if rows must be recorded by this method; the provided method does nothing.

class epifx.summary.PeakTimeAccuracy(peak_monitor, toln=None)¶

Record the accuracy of the peak time predictions against multiple accuracy tolerances.

Parameters:	peak_monitor – the name of a `PeakMonitor`. name – the name of the table in the output file. toln – The accuracy thresholds for peak time predictions, expressed as numbers of days. The default is `np.array([7, 10, 14])`.

dtype(ctx, obs_list, name)¶

Return the column names and data types, represented as a list of (name, data type) tuples. See the NumPy documentation for details.

Parameters:	params – The simulation parameters. obs_list – A list of all observations. name – The table’s name.

n_rows(start_date, end_date, n_days, n_sys, forecasting)¶

Return the number of rows required for a single simulation.

Parameters:	start_date – The date at which the simulation starts. end_date – The date at which the simulation ends. n_days – The number of days for which the simulation runs. n_sys – The number of observation systems (i.e., data sources). forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics for some portion of a simulation.

Parameters:

hist – The particle history matrix.
weights – The weight of each particle at each date in the simulation window; it has dimensions (d, p) for d days and p particles.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
dates – A list of (datetime, ix, hist_ix) tuples that identify each day in the simulation window, the index of that day in the simulation window, and the index of that day in the particle history matrix.
obs_types – A set of (unit, period) tuples that identify each observation system from which observations have been taken.
insert_fn – A function that inserts one or more rows into the underlying data table; see the examples below.

The row insertion function can be used as follows:

# Insert a single row, represented as a tuple.
insert_fn((x, y, z))
# Insert multiple rows, represented as a list of tuples.
insert_fn([(x0, y0, z0), (x1, y1, z1)], n=2)

finished(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics at the end of a simulation.

The parameters are as per add_rows().

Derived classes should only implement this method if rows must be recorded by this method; the provided method does nothing.

class epifx.summary.ExpectedObs(exp_obs_monitor, probs=None)¶

Record fixed-probability central credible intervals for the expected observations.

Parameters:	exp_obs_monitor – the name of a `pypfilt.summary.ExpectedObsMonitor`. probs – an array of probabilities that define the size of each central credible interval. The default value is `numpy.uint8([0, 50, 90, 95, 99, 100])`. name – the name of the table in the output file.

dtype(ctx, obs_list, name)¶

Return the column names and data types, represented as a list of (name, data type) tuples. See the NumPy documentation for details.

Parameters:	params – The simulation parameters. obs_list – A list of all observations. name – The table’s name.

n_rows(start_date, end_date, n_days, n_sys, forecasting)¶

Return the number of rows required for a single simulation.

Parameters:	start_date – The date at which the simulation starts. end_date – The date at which the simulation ends. n_days – The number of days for which the simulation runs. n_sys – The number of observation systems (i.e., data sources). forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics for some portion of a simulation.

Parameters:

hist – The particle history matrix.
weights – The weight of each particle at each date in the simulation window; it has dimensions (d, p) for d days and p particles.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
dates – A list of (datetime, ix, hist_ix) tuples that identify each day in the simulation window, the index of that day in the simulation window, and the index of that day in the particle history matrix.
obs_types – A set of (unit, period) tuples that identify each observation system from which observations have been taken.
insert_fn – A function that inserts one or more rows into the underlying data table; see the examples below.

The row insertion function can be used as follows:

# Insert a single row, represented as a tuple.
insert_fn((x, y, z))
# Insert multiple rows, represented as a list of tuples.
insert_fn([(x0, y0, z0), (x1, y1, z1)], n=2)

class epifx.summary.ObsLikelihood(extra_obs=None)¶

Record the likelihood of each observation according to each particle. Note that this table registers its record_obs_llhd method in the parameter dictionary so that it can obtain the observation likelihoods.

Parameters:	name – the name of the table in the output file. extra_obs – Observations that will not be used in the filtering process, but whose likelihoods are of interest.

dtype(ctx, obs_list, name)¶

Return the column names and data types, represented as a list of (name, data type) tuples. See the NumPy documentation for details.

Parameters:	params – The simulation parameters. obs_list – A list of all observations. name – The table’s name.

n_rows(start_date, end_date, n_days, n_sys, forecasting)¶

Return the number of rows required for a single simulation.

Parameters:	start_date – The date at which the simulation starts. end_date – The date at which the simulation ends. n_days – The number of days for which the simulation runs. n_sys – The number of observation systems (i.e., data sources). forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics for some portion of a simulation.

Parameters:

hist – The particle history matrix.
weights – The weight of each particle at each date in the simulation window; it has dimensions (d, p) for d days and p particles.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
dates – A list of (datetime, ix, hist_ix) tuples that identify each day in the simulation window, the index of that day in the simulation window, and the index of that day in the particle history matrix.
obs_types – A set of (unit, period) tuples that identify each observation system from which observations have been taken.
insert_fn – A function that inserts one or more rows into the underlying data table; see the examples below.

The row insertion function can be used as follows:

# Insert a single row, represented as a tuple.
insert_fn((x, y, z))
# Insert multiple rows, represented as a list of tuples.
insert_fn([(x0, y0, z0), (x1, y1, z1)], n=2)

finished(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics at the end of a simulation.

The parameters are as per add_rows().

Derived classes should only implement this method if rows must be recorded by this method; the provided method does nothing.

class epifx.summary.ThresholdMonitor(threshold)¶

Record when expected observations exceed a specific threshold.

Parameters:	threshold – The threshold observation value.

exceed_date = None¶

A dictionary that maps observation systems to the date when each particle exceeded the specific threshold: exceed_date[(unit, period)].

Note that this is only valid for tables to inspect in the finished() method, and not in the add_rows() method.

exceed_weight = None¶

A dictionary that maps observation systems to the final weight of each particle: exceed_weight.

Note that this is only valid for tables to inspect in the finished() method, and not in the add_rows() method.

exceed_mask = None¶

A dictionary that maps observation systems to Boolean arrays that indicate which particles have exceeded the threshold: exceed_mask[(unit, period)].

Note that this is only valid for tables to inspect in the finished() method, and not in the add_rows() method.

class epifx.summary.ExceedThreshold(thresh_monitor, start, until, width, fs_only=True)¶

Record when expected observations exceed a specific threshold.

Parameters:	thresh_monitor – the name of a `ThresholdMonitor`. name – the name of the table in the output file.

dtype(ctx, obs_list, name)¶

Return the column names and data types, represented as a list of (name, data type) tuples. See the NumPy documentation for details.

Parameters:	params – The simulation parameters. obs_list – A list of all observations. name – The table’s name.

n_rows(start_date, end_date, n_days, n_sys, forecasting)¶

Return the number of rows required for a single simulation.

Parameters:	start_date – The date at which the simulation starts. end_date – The date at which the simulation ends. n_days – The number of days for which the simulation runs. n_sys – The number of observation systems (i.e., data sources). forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics for some portion of a simulation.

Parameters:

hist – The particle history matrix.
weights – The weight of each particle at each date in the simulation window; it has dimensions (d, p) for d days and p particles.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
dates – A list of (datetime, ix, hist_ix) tuples that identify each day in the simulation window, the index of that day in the simulation window, and the index of that day in the particle history matrix.
obs_types – A set of (unit, period) tuples that identify each observation system from which observations have been taken.
insert_fn – A function that inserts one or more rows into the underlying data table; see the examples below.

The row insertion function can be used as follows:

# Insert a single row, represented as a tuple.
insert_fn((x, y, z))
# Insert multiple rows, represented as a list of tuples.
insert_fn([(x0, y0, z0), (x1, y1, z1)], n=2)

finished(hist, weights, fs_date, dates, obs_types, insert_fn)¶

Record rows of summary statistics at the end of a simulation.

The parameters are as per add_rows().

Derived classes should only implement this method if rows must be recorded by this method; the provided method does nothing.

Generating forecasts¶

import datetime
import epifx
import epifx.obs

# Simulation parameters
num_px = 3600
model = epifx.SEIR()
time = pypfilt.Datetime()
popn = 4000000
prng_seed = 42
params = epifx.default_params(num_px, model, time, popn_size, prng_seed)

# Simulate from the 1st of May to the 31st of October, 2015.
start = datetime.datetime(2015, 5, 1)
until = start + datetime.timedelta(days=183)

# Load the relevant observations.
obs_list = ...
# Create an observation model for weekly data (with a period of 7 days).
obs_model = epifx.obs.PopnCounts("obs_unit", obs_period=7)
# Define the observation model parameters.
obs_model.define_params(params, bg_obs=300, pr_obs=0.01, disp=100)

# Generate weekly forecasts for the first 9 weeks (and the start date).
fs_dates = [start + datetime.timedelta(days=week * 7)
            for week in range(10)]

# Summary statistics and output file.
summary = epifx.summary.make(params, obs_list))
out = "forecasts.hdf5"

# Generate the forecasts and save them to disk.
pypfilt.forecast(params, start, until, [obs_list], fs_dates, summary, out)

Comparing forecast outputs¶

Output files can be compared for equality, which is useful for ensuring that different systems produce identical results.

epifx.cmd.cmp.files(path1, path2, verbose=True, examine=None)¶

Compare two HDF5 files for identical simulation outputs.

Parameters:	path1 – The filename of the first HDF5 file. path2 – The filename of the second HDF5 file. verbose – Whether to report successful matches. examine – The data groups to examine for equality; the default is to examine the simulation outputs (`'/data'`) and ignore the associated metadata (`'/meta'`).
Returns:	`True` if the files contain identical simulation outputs, otherwise `False`.

This functionality is also provided as a command-line script.