Overhaul severe and mortality outcomes

[pwinskill]

Aim: to make assumptions about severe treatment (hospitalisation) coverage and resulting probability of death more transparent and flexible.

The refactor replaces the hard‑wired Griffin‑2016 shortcut, where all malaria deaths were simply taken as 0.215 times the modelled incidence of hospital‑treated severe cases, with an explicit two‑stream calculation that first separates severe episodes into hospital and community compartments, then applies setting‑specific case‑fatality ratios to each stream. A new column, ft_sev, lets users supply (and vary over time) the proportion of severe cases that reach hospital. A warning‑backed default of 0.8 preserves backward compatibility - when this default is used the original 0.215 deaths‑to‑hospitalised‑cases ratio is recovered.

The flow is as follows:

1. Estimate total severe inc based on original parameterisation from Griffen et al (2016) outputting hospitalised severe malaria inc, with an assummed 80% of severe cases hospitalised.
2. Split total severe inc into hospitalised and community severe inc based on user-specified (or default) ft_sev parameter that defines the proportion of severe cases that are hospitalised.
3. Rescale severe incidence metrics to account for the impact of first-line treatment reducing progression to severe.
4. Use hospital and community-specific severe case fatality rates to convert to mortality.

The same treatment‑coverage multiplier that used to be applied is still applied to both severe streams before mortality is derived, making the algebra transparent and allowing referral improvements to be explored independently of first‑line treatment scale‑up.

Adding derivation of the 80% for reference

Let
mH = severe case fatality hospital: 0.065
mC= severe case fatality community: 0.6
λH= severe incidence hospital
λC= severe incidence community
ν = scaling factor linking hospitalised severe incidence to total malaria deaths: 0.215

Total deaths (predicted two ways) are:

Solving for the ratio of non‑hospitalised to hospitalised severe cases gives:

Coverage (ρ): the share of severe episodes treated in hospital, is therefore:

Which = 80%

[RJSheppard]

How will the ft_sev be defined? I can see it gets set to 0.8 in the absence of other inputs, but would it be anticipated to be an output of malaria simulation? Or is it possible to input it as a parameter in get_rates (I may have misunderstood!)

[RJSheppard]

I suppose it means you can assign the proportion quite flexibly and through time, but it just means that it needs to be done actively before the get_rates function is called, right?

[pwinskill]

Exactly, yes, the user can specify the ft_sev column prior to running get rates manual if they so wish, if not, it will default to the 0.8.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (50c7756) to head (b4a38b3).
⚠️ Report is 17 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main        #8      +/-   ##
===========================================
+ Coverage   98.37%   100.00%   +1.62%     
===========================================
  Files           5         5              
  Lines         123       201      +78     
===========================================
+ Hits          121       201      +80     
+ Misses          2         0       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[pwinskill]

@

Latest changes on severe_inc

Pushed up to 3a7e302. This brings in the severe/mortality vignette (PR #10, now merged into this branch) and a set of corrections to keep the severe/mortality calculations faithful to the original Griffin (2016) inference.

Vignettes

• Merged the severe-mortality vignette and made it work alongside the existing "rates" vignette (analysing_malaria_output): added ggplot2 to Suggests, declared VignetteBuilder: knitr, and cross-referenced the two (methodology <-> runnable example).

Severe / mortality

• Restored the Griffin (2016) baseline-treatment normalisation (f0 = 0.1). Per the Griffin SI, severe incidence and mortality at coverage f1 are expressed relative to the baseline coverage f0 the model was fitted at, via ((1-chi)*f1 + (1-f1)) / ((1-chi)*f0 + (1-f0)). It had been dropped, leaving results inconsistent with the 0.215 scaler. Now hard-coded (not user-exposed) with a citation comment.
• Fixed the severe-incidence formula in the vignette, which had inverted averted vs not-averted (s_m*(1-0.58*tx) instead of the correct s_m*(1-0.42*tx)); rewritten to match the code and SI, including the f0 baseline and 1/rho0 hospitalised->total gross-up.
• P. vivax support: get_rates() no longer errors when n_inc_severe_... columns are absent. It creates them to match the clinical age groups, fills with NA, and warns that severe/mortality/DALY outputs will be NA.
• Fixed an "assumming" -> "assuming" typo in the warnings.

Verification

• Compared against main (identical simulation input, all defaults): clinical, severe_hospital, mortality and yll are numerically identical (differences at machine epsilon). Defaults reproduce the original behaviour, with extra disaggregation (_hospital/_community, ft_sev, CFR args) available when needed.
• yld/dalys intentionally differ from main: YLD now weights total (hospital + community) severe rather than hospitalised-only.
• devtools::test(): 56 passed, 0 failures (added regression tests for the f0 normalisation and the missing-severe-column path).
• R CMD check: Status OK (0 errors / 0 warnings / 0 notes), both vignettes rebuild.
  @

[pwinskill]

closes #11