Antimalarial Resistance: Slow Parasite Clearance

[tbreweric]

Integrating Slow Parasite Clearance into the Antimalarial Resistance Model

Introduction
In this PR, I have added slow parasite clearance (SPC) as an outcome of malaria infections that are resistant to the artemisinin component of the artemisinin combination therapy (ACT) an individual is treated with. SPC is the phenomenon in which resistant malaria parasites remain in the blood beyond the usual 3 day period taken for the artemisinin component to remove malaria parasites from the patients' blood stream. The parasites are eventually removed by the ACT and the patient successfully treated.

Explanation of Slow Parasite Clearance Code Changes
We have captured SPC by increasing the average time individuals with a clinical infection treated with an ACT spend in the treated compartment. This has involved making changes to eight core model functions, which I will describe below:

1. set_antimalarial_resistance(): slow_parasite_clearance_probability (formerly slow_parasite_clearance_prob) has been removed from the test for undeveloped model features. The names of the resistance parameters have also been amended to make them clearer (e.g. reinfection_prob to reinfection_during_prophylaxis_probability.
2. get_parameters(): The documentation and entries for the resistance parameters have been to updated to reflect the changes to some of their names.
3. create_variables(): If parameters$antimalarial_resistance == TRUE dt is set up as a variable, initialised with parameters$dt for all individuals, and appended it to the variables list. A line has also been added to the documentation that explains the new dt variable.
4. create_progression_process(): The original create_progression_process() function was only used when the rate at which individuals transition from the from_state to the to_state was a single parameter value. When parameters$antimalarial_resistance == TRUE, the rate at which individuals move from the treated compartment to the susceptible compartment becomes a variable. When the rate becomes a variable an additional step is required to subset the variable values corresponding to the individuals in the from_state. The create_progression_process() has been amended to first retrieve and store the indices of all individuals in from_state. If length(rate) > 1, telling the function that the rate is a variable rather than a parameter, the rate is overwritten with only the values of the individuals in the from_state in the current timestep. These individual-specific rates are then used to determine which individuals will move from the from_state to the to_state in the current timestep.
5. create_processes(): I’ve replaced the create_progression_process() that governs the disease state transition from Tr to S. The updated version stores the parameters$dt as the dt_input and overwrites this with variables$dt if antimalarial_resistance == TRUE. The input for the create_progression_process() is then dt_input.
6. calculate_treated(): The major change in this PR is within the calculate_treated() function. The updated version can simulate both ETF and SPC as outcomes of antimalarial resistance. In the updated version, there are four possible outcomes for individuals that receive treatment:
   • Treatment failure due to drug efficacy (variables$state updated to D)
   • Treatment failure due to early treatment failure (variables$state updated to D)
   • Successful treatment with slow parasite clearance (variables$state updated to Tr, variables$dt updated to parameters$slow_parasite_clearance_time)
   • Successful treatment without slow parasite clearance (variables$state updated to Tr, variables$dt updated to parameters$dt)

The order of events has been updated. Once the drugs have been assigned to each individual in seek_treatment, the drug efficacy test is performed, with individuals who pass the drug efficacy step stored in the Bitset effectively_treated and the drugs vector updated to filter out the drugs of individuals who failed treatment due to drug efficacy.

If parameters$antimalarial_resistance == TRUE, the get_antimalarial_resistance_parameters() function is called to retrieve the resistance parameters associated with the drug administered to each individual in effectively_treated the current timestep (stored in object called resistance_parameters). Each individuals' probability of experiencing early treatment failure is calculated by multiplying the artemisinin_resistance_proportion and early_treatment_failure_probability corresponding to the drug they were administered and the current timestep. These probabilities are used by bernoulli_multi_p() to determine which individuals are successfully treated (avoid treatment failure due to drug efficacy or drug resistance) and their indices are stored in the Bitset successfully_treated. The drugs and dt_slow_parasite_clearance vector (stored in resistance_parameters) are subsetted to include only those individuals who have been successfully treated.

For each of the successfully_treated individuals, a final test is performed to see whether they will experience slow parasite clearance (again via bernoulli_multi_p()). Additional Bitsets are created to store individuals who will (slow_parasite_clearance_individuals) and will not experience slow parasite clearance (non_slow_parasite_clearance_individuals).

For the queue_update operations, the successfully_treated Bitset is used to queue updates to the state, infectivity, drug, and drug_time variables. For non_slow_parasite_clearance individuals, the dt variable is updated with the default/non-resistant parameters$dt. For the slow_parasite_clearance_individuals, the dt variable is updated to the parameters$dt_slow_parasite_clearance value for the drug the individual was administered (from resistance_parameters$dt_slow_parasite_clearance).

When parameters$antimalarial_resistance == TRUE, additional outputs are rendered to capture the number of people who received treatment (n_treated), the number of individuals who failed treatment due to drug efficacy (n_drug_efficacy_failures) or early treatment failure (n_early_treatment_failures), the number of people who experienced slow parasite clearance (n_slow_parasite_clearance), and the number of individuals who were successfully treated (n_successfully_treated). Note that n_successfully_treated includes individuals with slow parasite clearance as, although they will spend longer in the Tr compartment, they do transition to Tr and eventually S.

If parameters$antimalarial_resistance == FALSE, the drug resistance steps are skipped, the effectively_treated Bitset is copied into successfully_treated, and only the queue_update steps for state, infectivity, drug, and drug_time are performed.

8. reset_target(): When parameters$antimalarial_resistance == TRUE, a new variable dt is created. The reset_target() function has been amended to accept the parameters list as an input and reset the dt variable to parameters$dt when !is.null(variables$dt).

9. run_simulation(): I have added entries to the run_simulation() documentation to describe the new model outputs associated with antimalarial resistance. When parameters$antimalarial_resistance == TRUE, the function will now render the following outputs:
   - n_treated: number of individuals that were given an ACT in the current timestep
   - n_drug_efficacy_failures: number of individuals who failed treatment due to the drug efficacy in the current timestep
   - n_early_treatment_failures: number of individuals who failed treatment due to early treatment failure in the current timestep
   - n_slow_parasite_clearance: number of individuals who will experience slow parasite clearance in the current timestep
   - n_successfully_treated: number of individuals who were successfully treated in the current timestep. Note that this includes individuals with SPC (n_slow_parasite_clearance) as they progress to the Tr compartment and will be successfully treated after an increased residency in the compartment. To calculate the number of non-resistant successfully treated individuals the user can simply do n_successfully_treated - n_slow_parasite_clearance. Furthermore, of the new parameters, n_drug_efficacy_failures, n_early_treatment_failures, and n_successfully_treated sum to n_treated.

10. Antimalarial_resistance.Rmd: I have amended the antimalarial resistance vignette to capture the changes in the names of the resistance parameter inputs for set_antimalarial_resistance() and references to them in the text. I have also added an example of simulations with multiple resistance outcomes - comparing a no-intervention baseline scenario with treatment-only, ETF-only, SPC-only, and combined ETF and SPC simulations.

Additional Changes

• Additional tests have been added to test-antimalarial_resistance.R and test-infection-integration.R and, where necessary, tests have been fixed where the changes described above have broken them.
• Changed all instances of simparams to parameters in unit tests for consistency with other tests.

[giovannic]

This is incredible! I've requested a few stylistic changes.

Thank you so much

[tbreweric]

Thanks @giovannic! I've gone through and made all of the changes - just re-running the checks now but shall commit/push the changes shortly!

[pwinskill]

Thanks @tbreweric - this looks really nice! 🥳
I've left one key point regarding rates/probs
Interested to know what others think about the very clear but long variable names.

[tbreweric]

Thanks @tbreweric - this looks really nice! 🥳 I've left one key point regarding rates/probs Interested to know what others think about the very clear but long variable names.

I wondered if I'd gone too far the other way after we talked about naming clarity / length as we'd discussed it during one of our early code reviews. Happy to change them!

[giovannic]

My requested changes have been addressed. Thanks!