Design of the comparisons class

[pratikunterwegs]

This issue is intended for design discussions relating to the comparisons class.

The comparisonsclass is intended to be an S3 class object that holds comparisons between epidemic scenario modelling outputs, which are represented as scenario objects. The idea is for this object to ingest several scenario objects as a list, set a user-specified scenario as a ‘baseline’ or ‘reference’, check which other scenarios are comparable (based on user-specified fields and model type; see General helper functions), and get the difference in a user-specified outcome between the baseline and all other comparable scenarios.

An example is a comparison of multiple final_size() scenarios with varying susceptibility matrices reflecting different assumptions about population immunity to an infection (due to vaccination or prior exposure) but sharing the same underlying population demographic structure and contact patterns, and sharing infection parameters.

Attributes

• Data: A list of scenario class objects representing epidemic simulation outcomes (see above). This list should ideally be informatively named. scenario objects can exist as function-and-parameter specifications without the simulation being run (see above).
• Baseline outcome tag: Which object in the data list is the baseline outcome. Can be a string or integer, with strings preferred.
• Scenario matching tags: Named list that specifies which attributes are used to check whether scenarios are comparable. Should have at least one element, the function used to run the epidemic simulation, to avoid comparing outputs from different packages.
• Scenario comparison tags: Named list that specifies which outcomes should be compared. E.g. The proportion of individuals infected in a final_size() run.
• Comparison grouping tags: Named list that specifies which groups should be used when making comparisons.
  The idea here is to make it possible to compare both (1) scenarios with different susceptibility groups at a relatively broad level (e.g. a final_size() scenario with a fully susceptible population, against one with multiple [reduced] susceptibility groups; in this case, the outcomes of the latter scenario should be pooled across groups), but also (2) scenarios with similar groups, at the group level.
• Comparison summary: A summary of the comparison, obtained after setting a baseline and comparing scenarios . 

Functions

• Constructor: Initialise a new comparisons object, with a list of scenario objects. Optionally, specify a baseline. 
• Print (and Summary): Print the contents of the object to screen. Prints a summary of the most important details. If a baseline is set, prints the identity and a summary of the baseline scenario. If the comparison summary has been generated, prints the comparison summary as well; if not, a warning that the comparison has not yet been calculated.
• Make comparisons: Match comparable scenarios and compare against the baseline. Comparisons could be at the level of summary statistics. This function should be able to check whether the scenarios data list has scenario objects with the data available, or whether the scenario data itself needs to be generated by calling the scenario function (see above). If the latter, the function should generate the scenario data before making the comparison. The output of this function is one or more data structures (lists or data frames, or a named list and a data.frame) with differences between each scenario and the baseline.
  For discussion: How to correctly propagate uncertainty in epidemic simulation outcomes when getting the difference between each scenario and the baseline. Options include a simple difference of central tendency, a comparison of the variance in outcomes, or a measure of the overlap between the 95% CIs of any pair of scenarios (where one is the baseline). 
• Access functions: Simple functions to access the scenario data or comparisons data, and/or other object attributes.