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'.

init(ctx, vec)¶

Initialise a state vector.

Parameters:	ctx – The simulation context. vec – An uninitialised state vector of correct dimensions.

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.

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. Proposals will be drawn from the model prior distribution.

epifx.select.select(instance, target, seed, notify_fn=None)¶

Select particles according to a target distribution. Proposals will be drawn from the model prior distribution.

Parameters:	instance – The simulation instance. target – The target distribution. seed – The PRNG seed used for accepting particles. notify_fn – An optional function that is notified of each acceptance loop, and should accept two arguments: the number of particles and the number of accepted particles.
Returns:	The initial state vector for each accepted particle.
Return type:	numpy.ndarray

Note

The instance should not be reused after calling this function. To prevent this from happening, the instance settings will be deleted.

# Save the accepted particles to disk.
vec = epifx.select.select(instance, target, seed)
sampled_values = vec[column_names]
header = ' '.join(column_names)
np.savetxt(out_file, sampled_values, header=header, comments='')

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(instance)¶

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

Parameters:	instance – The simulation instance.

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:	instance – The simulation instance.

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(instance)¶

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

Parameters:	instance – The simulation instance.

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.

Forecast summaries¶

epifx.summary.make(ctx)¶

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

Parameters:	ctx – The simulation context.

Note

The 'sim_obs' table (pypfilt.summary.SimulatedObs) must be associated with an observation unit:

[components]
summary = "epifx.summary.make"

[summary.tables]
sim_obs.observation_unit = "cases"

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.

field_types(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.

Note

Use pypfilt.io.time_field() for columns that will contain time values. This ensures that the time values will be converted as necessary when loading and saving tables.

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

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

Return the number of rows required for a single simulation.

Parameters:	ctx – The simulation context. 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. forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(ctx, fs_date, window, insert_fn)¶

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

Parameters:

ctx – The simulation context.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
window – A list of Snapshot instances that capture the particle states at each time unit in the simulation window.
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¶

Record epidemic peak forecasts, for use with other statistics.

[summary.monitors]
peak_monitor.component = "epifx.summary.PeakMonitor"

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].

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].

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].

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].

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(ctx, date)¶

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

Parameters:	ctx – The simulation context. date – The date to convert into a scalar value.

class epifx.summary.PeakForecastEnsembles¶

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

This requires a PeakMonitor, which should be specified in the scenario settings. It also requires values for the following settings:

peak_monitor: the name of the PeakMonitor.
only_forecasts: whether to record results only during forecasts.

For example:

[summary.monitors]
peak_monitor.component = "epifx.summary.PeakMonitor"

[summary.tables]
peak_ensemble.component = "epifx.summary.PeakForecastEnsembles"
peak_ensemble.peak_monitor = "peak_monitor"
peak_ensemble.only_forecasts = false

field_types(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.

Note

Use pypfilt.io.time_field() for columns that will contain time values. This ensures that the time values will be converted as necessary when loading and saving tables.

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

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

Return the number of rows required for a single simulation.

Parameters:	ctx – The simulation context. 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. forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(ctx, fs_date, window, insert_fn)¶

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

Parameters:

ctx – The simulation context.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
window – A list of Snapshot instances that capture the particle states at each time unit in the simulation window.
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(ctx, fs_date, window, 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¶

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

This requires a PeakMonitor, which should be specified in the scenario settings. It also requires values for the following settings:

peak_monitor: the name of the PeakMonitor.
credible_intervals: the central credible intervals to record; the default is [0, 50, 60, 70, 80, 90, 95, 99, 100].

For example:

[summary.monitors]
peak_monitor.component = "epifx.summary.PeakMonitor"

[summary.tables]
peak_cints.component = "epifx.summary.PeakForecastCIs"
peak_cints.peak_monitor = "peak_monitor"
peak_cints.credible_intervals = [0, 50, 95]

field_types(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.

Note

Use pypfilt.io.time_field() for columns that will contain time values. This ensures that the time values will be converted as necessary when loading and saving tables.

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

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

Return the number of rows required for a single simulation.

Parameters:	ctx – The simulation context. 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. forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(ctx, fs_date, window, insert_fn)¶

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

Parameters:

ctx – The simulation context.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
window – A list of Snapshot instances that capture the particle states at each time unit in the simulation window.
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(ctx, fs_date, window, 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¶

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

This requires a PeakMonitor, which should be specified in the scenario settings. It also requires values for the following settings:

peak_monitor: the name of the PeakMonitor.
thresholds: the accuracy thresholds for peak size predictions, expressed as percentages of the true size; the default is [10, 20, 25, 33].

For example:

[summary.monitors]
peak_monitor.component = "epifx.summary.PeakMonitor"

[summary.tables]
peak_size_acc.component = "epifx.summary.PeakSizeAccuracy"
peak_size_acc.peak_monitor = "peak_monitor"
peak_size_acc.thresholds = [10, 20, 25, 33]

field_types(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.

Note

Use pypfilt.io.time_field() for columns that will contain time values. This ensures that the time values will be converted as necessary when loading and saving tables.

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

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

Return the number of rows required for a single simulation.

Parameters:	ctx – The simulation context. 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. forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(ctx, fs_date, window, insert_fn)¶

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

Parameters:

ctx – The simulation context.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
window – A list of Snapshot instances that capture the particle states at each time unit in the simulation window.
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(ctx, fs_date, window, 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¶

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

This requires a PeakMonitor, which should be specified in the scenario settings. It also requires values for the following settings:

peak_monitor: the name of the PeakMonitor.
thresholds: the accuracy thresholds for peak time predictions, expressed as numbers of days; the default is [7, 10, 14].

For example:

[summary.monitors]
peak_monitor.component = "epifx.summary.PeakMonitor"

[summary.tables]
peak_time_acc.component = "epifx.summary.PeakTimeAccuracy"
peak_time_acc.peak_monitor = "peak_monitor"
peak_time_acc.thresholds = [7, 10, 14]

field_types(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.

Note

Use pypfilt.io.time_field() for columns that will contain time values. This ensures that the time values will be converted as necessary when loading and saving tables.

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

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

Return the number of rows required for a single simulation.

Parameters:	ctx – The simulation context. 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. forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(ctx, fs_date, window, insert_fn)¶

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

Parameters:

ctx – The simulation context.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
window – A list of Snapshot instances that capture the particle states at each time unit in the simulation window.
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(ctx, fs_date, window, 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¶

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

The default intervals are: 0%, 50%, 90%, 95%, 99%, 100%. These can be overridden in the scenario settings. For example:

[summary.tables]
expected_obs.credible_intervals = [0, 50, 95]

field_types(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.

Note

Use pypfilt.io.time_field() for columns that will contain time values. This ensures that the time values will be converted as necessary when loading and saving tables.

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

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

Return the number of rows required for a single simulation.

Parameters:	ctx – The simulation context. 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. forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(ctx, fs_date, window, insert_fn)¶

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

Parameters:

ctx – The simulation context.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
window – A list of Snapshot instances that capture the particle states at each time unit in the simulation window.
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¶

Record the likelihood of each observation according to each particle.

This table registers its record_obs_llhd method as a handler for the 'obs_llhd' event so that it can record the observation likelihoods.

Note

Each observation must have a 'value' field that contains a numeric scalar value, or this table will raise an exception.

load_state(ctx, group)¶: Restore the state of each PRNG from the cache.

save_state(ctx, group)¶: Save the current state of each PRNG to the cache.

field_types(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.

Note

Use pypfilt.io.time_field() for columns that will contain time values. This ensures that the time values will be converted as necessary when loading and saving tables.

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

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

Return the number of rows required for a single simulation.

Parameters:	ctx – The simulation context. 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. forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(ctx, fs_date, window, insert_fn)¶

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

Parameters:

ctx – The simulation context.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
window – A list of Snapshot instances that capture the particle states at each time unit in the simulation window.
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(ctx, fs_date, window, 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¶

Monitor when expected observations exceed a specific threshold.

The threshold should be specified in the simulation settings. For example:

[summary.monitors]
thresh_500.component = "epifx.summary.ThresholdMonitor"
thresh_500.threshold = 500

exceed_date = None¶

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

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].

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¶

Record when expected observations exceed a specific threshold.

The simulation is divided into a finite number of bins, and this table will record the (weighted) proportion of particles that first exceeded the threshold in each of these bins.

This requires a ThresholdMonitor, which should be specified in the scenario settings. It also requires values for the following settings:

threshold_monitor: the name of the ThresholdMonitor.
only_forecasts: whether to record results only during forecasts.
start: the time at which to begin recording events.
until: the time at which to stop recording events.
bin_width: the width of the time bins.

For example:

[summary.monitors]
thresh_500.component = "epifx.summary.ThresholdMonitor"
thresh_500.threshold = 500

[summary.tables]
exceed_500.component = "epifx.summary.ExceedThreshold"
exceed_500.threshold_monitor = "thresh_500"
exceed_500.only_forecasts = true
exceed_500.start = "2014-04-01"
exceed_500.until = "2014-10-01"
exceed_500.bin_width = 7

field_types(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.

Note

Use pypfilt.io.time_field() for columns that will contain time values. This ensures that the time values will be converted as necessary when loading and saving tables.

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

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

Return the number of rows required for a single simulation.

Parameters:	ctx – The simulation context. 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. forecasting – `True` if this is a forecasting simulation, otherwise `False`.

add_rows(ctx, fs_date, window, insert_fn)¶

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

Parameters:

ctx – The simulation context.
fs_date – The forecasting date; if this is not a forecasting simulation, this is the date at which the simulation ends.
window – A list of Snapshot instances that capture the particle states at each time unit in the simulation window.
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(ctx, fs_date, window, 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.

Example scenarios¶

epifx.example.seir.write_example_files(scenario)¶

Save the example files for a scenario to the working directory.

Parameters:	scenario – The scenario name.
Raises:	ValueError – If the scenario name is invalid (see below).

The valid scenarios are:

'seir': The deterministic SEIR model with date times.
'seir_quick': : The deterministic SEIR model with date times, using only 20 particles.
'seeiir': The deterministic SEEIIR model with date times.
'seeiir_scalar': The deterministic SEEIIR model with scalar time.
'stoch': The stochastic SEEIIR model with date times.

Generating forecasts¶

import datetime
import epifx.example.seir
import pypfilt

scenario = 'seir'
toml_file = 'seir.toml'
output_file = 'seir_forecasts.hdf5'
forecast_dates = [datetime.datetime(2014, 4, 1)]

# Write the scenario files to the working directory.
epifx.example.seir.write_example_files(scenario)

# Run forecasts for each scenario instance (there is only one instance).
for instance in pypfilt.load_instances(toml_file):
    context = instance.build_context()
    pypfilt.forecast(context, forecast_dates, output_file)