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(*args: Any, **kwargs: Any)

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(*args: Any, **kwargs: Any)

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
class epifx.summary.PeakSizeAccuracy(*args: Any, **kwargs: Any)

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(*args: Any, **kwargs: Any)

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(*args: Any, **kwargs: Any)

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(*args: Any, **kwargs: Any)

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(*args: Any, **kwargs: Any)

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(*args: Any, **kwargs: Any)

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(*args: Any, **kwargs: Any)

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, time)

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

Parameters:

  • ctx – The simulation context.

  • time – The time to convert into a scalar value.

class epifx.summary.ThresholdMonitor(*args: Any, **kwargs: Any)

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_time = None

A dictionary that maps observation systems to the time when each particle exceeded the specific threshold: exceed_time[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.