Summary tables

The epifx.summary module provides the following summary tables:

  • PrOutbreak records the probability that an outbreak has occurred at each time unit.
  • ExceedThreshold records the time at which the expected observations exceed a specific threshold.
  • PeakSizeAccuracy records the accuracy of the epidemic peak size predictions.
  • PeakTimeAccuracy records the accuracy of the epidemic peak time predictions.
  • PeakForecastCIs records credible intervals for the epidemic peak size and time.
  • PeakForecastEnsembles records the weighted ensemble of peak size and time predictions.
  • ObsLikelihood records the likelihood of each observation, according to each particle.
  • ExpectedObs records credible intervals for the expected observations (i.e., this does not account for observation model variance).

Some of these tables make use of the following monitors:

  • PeakMonitor monitors epidemic peak size and time predictions.
  • ThresholdMonitor monitors when expected observations exceed a specific threshold.

You can use epifx.summary.make() as the summary component to add most of these summary tables to your forecasting scenarios:

epifx.summary.make(ctx)

A convenience function that adds most of the summary statistics defined in the pypfilt.summary and epifx.summary modules to forecast scenarios.

Parameters:ctx – The simulation context.

It currently defines the following tables:

and the following monitors:

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"

Additional tables

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.

[summary.tables]
pr_outbreak.component = "epifx.summary.PrOutbreak"
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.

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

[summary.tables]
obs_llhd.component = "epifx.summary.ObsLikelihood"
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.component = "epifx.summary.ExpectedObs"
expected_obs.credible_intervals = [0, 50, 95]

Additional monitors

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