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
andepifx.summary
modules to forecast scenarios.- Parameters
ctx – The simulation context.
It currently defines the following tables:
'model_cints'
:pypfilt.summary.ModelCIs
;'param_covar'
:pypfilt.summary.ParamCovar
;'forecasts'
:pypfilt.summary.PredictiveCIs
;'sim_obs'
:pypfilt.summary.SimulatedObs
(see the note below);'pr_epi'
:PrOutbreak
;'obs_llhd'
:ObsLikelihood
;'peak_size_acc'
:PeakSizeAccuracy
;'peak_time_acc'
:PeakTimeAccuracy
;'peak_cints'
:PeakForecastCIs
;'peak_ensemble'
:PeakForecastEnsembles
;
and the following monitors:
'peak_monitor'
:PeakMonitor
.
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 theThresholdMonitor
.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 thePeakMonitor
.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 thePeakMonitor
.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 thePeakMonitor
.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 thePeakMonitor
.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 theadd_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 theadd_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 theadd_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 theadd_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 tofinished()
.
- 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 theadd_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 theadd_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 theadd_rows()
method.