Add aggregate() method for <epiparameter>

[joshwlambert]

This PR addresses #271 by adding an aggregate() method for the <multi_epiparameter> class. This is a feature that has been repeatedly requested and was worked on in a working group at an Epiverse-Imperial hackathon earlier this year.

That hackathon led to PR #270 which was sketched by @Bisaloo and others in the working group, and subsequently worked on by myself. However, the approach to aggregate <epiparameter> objects raised several concerns. One of which was the output of several aggregation methods being numerical vectors rather than parameterised distribution, and led to #372.

After discussing this feature with @adamkucharski, @chartgerink and @Bisaloo it was agreed to take a different approach to try and offer similar functionality, that has led to this PR.

This PR adds an aggregate() method to combine a list of <epiparameter> objects and output a parameterised mixture distribution, leveraging functionality and classes exported by {distributional}. The output of aggregate.multi_epiparameter() is an <epiparameter> object, with class methods updated in this PR to work seamlessly with mixture distributions.

A get_parameters.multi_epiparameter() method is added. The .get_mixture_family() internal function is added to easily access the individual distribution names from a mixture distribution (used for printing).

Unit tests have been added for the aggregate() method.

[joshwlambert]

Here is an example of the new functionality:

library(epiparameter)
ebola_si <- epiparameter_db(epi_dist = "serial interval", disease = "ebola")
#> Returning 4 results that match the criteria (4 are parameterised). 
#> Use subset to filter by entry variables or single_epiparameter to return a single entry. 
#> To retrieve the citation for each use the 'get_citation' function
ebola_si
#> # List of 4 <epiparameter> objects
#> Number of diseases: 1
#> ❯ Ebola Virus Disease
#> Number of epi distributions: 1
#> ❯ serial interval
#> [[1]]
#> Disease: Ebola Virus Disease
#> Pathogen: Ebola Virus
#> Epi Distribution: serial interval
#> Study: WHO Ebola Response Team, Agua-Agum J, Ariyarajah A, Aylward B, Blake I,
#> Brennan R, Cori A, Donnelly C, Dorigatti I, Dye C, Eckmanns T, Ferguson
#> N, Formenty P, Fraser C, Garcia E, Garske T, Hinsley W, Holmes D,
#> Hugonnet S, Iyengar S, Jombart T, Krishnan R, Meijers S, Mills H,
#> Mohamed Y, Nedjati-Gilani G, Newton E, Nouvellet P, Pelletier L,
#> Perkins D, Riley S, Sagrado M, Schnitzler J, Schumacher D, Shah A, Van
#> Kerkhove M, Varsaneux O, Kannangarage N (2015). "West African Ebola
#> Epidemic after One Year — Slowing but Not Yet under Control." _The New
#> England Journal of Medicine_. doi:10.1056/NEJMc1414992
#> <https://doi.org/10.1056/NEJMc1414992>.
#> Distribution: gamma
#> Parameters:
#>   shape: 2.188
#>   scale: 6.490
#> 
#> [[2]]
#> Disease: Ebola Virus Disease
#> Pathogen: Ebola Virus
#> Epi Distribution: serial interval
#> Study: WHO Ebola Response Team, Agua-Agum J, Ariyarajah A, Aylward B, Blake I,
#> Brennan R, Cori A, Donnelly C, Dorigatti I, Dye C, Eckmanns T, Ferguson
#> N, Formenty P, Fraser C, Garcia E, Garske T, Hinsley W, Holmes D,
#> Hugonnet S, Iyengar S, Jombart T, Krishnan R, Meijers S, Mills H,
#> Mohamed Y, Nedjati-Gilani G, Newton E, Nouvellet P, Pelletier L,
#> Perkins D, Riley S, Sagrado M, Schnitzler J, Schumacher D, Shah A, Van
#> Kerkhove M, Varsaneux O, Kannangarage N (2015). "West African Ebola
#> Epidemic after One Year — Slowing but Not Yet under Control." _The New
#> England Journal of Medicine_. doi:10.1056/NEJMc1414992
#> <https://doi.org/10.1056/NEJMc1414992>.
#> Distribution: gamma
#> Parameters:
#>   shape: 4.903
#>   scale: 3.161
#> 
#> [[3]]
#> Disease: Ebola Virus Disease
#> Pathogen: Ebola Virus
#> Epi Distribution: serial interval
#> Study: WHO Ebola Response Team, Agua-Agum J, Ariyarajah A, Aylward B, Blake I,
#> Brennan R, Cori A, Donnelly C, Dorigatti I, Dye C, Eckmanns T, Ferguson
#> N, Formenty P, Fraser C, Garcia E, Garske T, Hinsley W, Holmes D,
#> Hugonnet S, Iyengar S, Jombart T, Krishnan R, Meijers S, Mills H,
#> Mohamed Y, Nedjati-Gilani G, Newton E, Nouvellet P, Pelletier L,
#> Perkins D, Riley S, Sagrado M, Schnitzler J, Schumacher D, Shah A, Van
#> Kerkhove M, Varsaneux O, Kannangarage N (2015). "West African Ebola
#> Epidemic after One Year — Slowing but Not Yet under Control." _The New
#> England Journal of Medicine_. doi:10.1056/NEJMc1414992
#> <https://doi.org/10.1056/NEJMc1414992>.
#> Distribution: gamma
#> Parameters:
#>   shape: 2.068
#>   scale: 7.301
#> 
#> [[4]]
#> Disease: Ebola Virus Disease
#> Pathogen: Ebola Virus
#> Epi Distribution: serial interval
#> Study: WHO Ebola Response Team, Agua-Agum J, Ariyarajah A, Aylward B, Blake I,
#> Brennan R, Cori A, Donnelly C, Dorigatti I, Dye C, Eckmanns T, Ferguson
#> N, Formenty P, Fraser C, Garcia E, Garske T, Hinsley W, Holmes D,
#> Hugonnet S, Iyengar S, Jombart T, Krishnan R, Meijers S, Mills H,
#> Mohamed Y, Nedjati-Gilani G, Newton E, Nouvellet P, Pelletier L,
#> Perkins D, Riley S, Sagrado M, Schnitzler J, Schumacher D, Shah A, Van
#> Kerkhove M, Varsaneux O, Kannangarage N (2015). "West African Ebola
#> Epidemic after One Year — Slowing but Not Yet under Control." _The New
#> England Journal of Medicine_. doi:10.1056/NEJMc1414992
#> <https://doi.org/10.1056/NEJMc1414992>.
#> Distribution: gamma
#> Parameters:
#>   shape: 1.898
#>   scale: 6.532
#> 
#> # ℹ Use `parameter_tbl()` to see a summary table of the parameters.
#> # ℹ Explore database online at: https://epiverse-trace.github.io/epiparameter/articles/database.html
consensus_ebola_si <- aggregate(ebola_si)
density(consensus_ebola_si, at = 2)
#> [1] 0.02318493
plot(consensus_ebola_si)

^{Created on 2024-10-02 with reprex v2.1.0}

[adamkucharski]

Thanks for putting together. This works for me.

One thing I noticed was that ebola_si is all the same distribution type – is there an easy way to check this in the multi_epiparameter object (e.g. if there's a mismatch in distribution types)? Perhaps one to follow up in this discussion point.

[joshwlambert]

The different probability distributions in the <multi_epiparameter> can be checked using: sapply(ebola_incub, family) (or lapply() or vapply() etc.).

Below I have pasted an example using the incubation periods for Ebola showing that different types of distributions can be included in the mixture distribution. In this case there is a lognormal distribution and four gamma distributions.

library(epiparameter)
ebola_incub <- epiparameter_db(epi_dist = "incubation", disease = "ebola")
#> Returning 5 results that match the criteria (5 are parameterised). 
#> Use subset to filter by entry variables or single_epiparameter to return a single entry. 
#> To retrieve the citation for each use the 'get_citation' function

# get probability distribution of each <epiparameter>
sapply(ebola_incub, family)
#> [1] "lnorm" "gamma" "gamma" "gamma" "gamma"

# remove subtype info for pathogens to match
for (i in seq_along(ebola_incub)) {
  ebola_incub[[i]]$pathogen <- "Ebola Virus"
}

ebola_incub_mix <- aggregate(ebola_incub)
ebola_incub_mix
#> Disease: Ebola Virus Disease
#> Pathogen: Ebola Virus
#> Epi Distribution: incubation period
#> Study: Eichner M, Dowell S, Firese N (2011). "Incubation period of ebola
#> hemorrhagic virus subtype zaire." _Osong Public Health and Research
#> Perspectives_. doi:10.1016/j.phrp.2011.04.001
#> <https://doi.org/10.1016/j.phrp.2011.04.001>.
#> Study: WHO Ebola Response Team, Agua-Agum J, Ariyarajah A, Aylward B, Blake I,
#> Brennan R, Cori A, Donnelly C, Dorigatti I, Dye C, Eckmanns T, Ferguson
#> N, Formenty P, Fraser C, Garcia E, Garske T, Hinsley W, Holmes D,
#> Hugonnet S, Iyengar S, Jombart T, Krishnan R, Meijers S, Mills H,
#> Mohamed Y, Nedjati-Gilani G, Newton E, Nouvellet P, Pelletier L,
#> Perkins D, Riley S, Sagrado M, Schnitzler J, Schumacher D, Shah A, Van
#> Kerkhove M, Varsaneux O, Kannangarage N (2015). "West African Ebola
#> Epidemic after One Year — Slowing but Not Yet under Control." _The New
#> England Journal of Medicine_. doi:10.1056/NEJMc1414992
#> <https://doi.org/10.1056/NEJMc1414992>.
#> Distribution: mixture: lnorm, gamma, gamma, gamma, gamma
#> Parameters:
#>   dist.mu: 2.487
#>   dist.sigma: 0.330
#>   dist.shape: 1.578
#>   dist.rate: 0.153
#>   dist.shape: 0.925
#>   dist.rate: 0.073
#>   dist.shape: 1.731
#>   dist.rate: 0.173
#>   dist.shape: 1.462
#>   dist.rate: 0.141
#>   w1: 0.200
#>   w2: 0.200
#>   w3: 0.200
#>   w4: 0.200
#>   w5: 0.200

^{Created on 2024-10-04 with reprex v2.1.0}

[chartgerink]

Thanks @joshwlambert 🙌

My only minor note (not blocking) is to double check the issue with the pkgdown build action. When it fails, it is worth investigating and seeing whether there's an unknown (unrelated) issue that may need to be documented and resolved elsewhere.

[Bisaloo]

Thanks, it looks very useful! I've left very minor comments