The XH Component

Human/Vertebrate Host Infection Dynamics and Immunity

The XH component was designed for human malaria epidemiology, defined in a narrow sense to include exposure, infection dynamics, immunity, disease, infectiousness, diagnostics and detection. (In the broader sense, human malaria epidemiology also includes malaria transmission dynamics, but this is handled by other parts of ramp.xds.) The XH component also handles models for the epidemiology of other mosquito-borne diseases (see ramp.library).

This vignette takes a deep dive into the design and structure of the XH component. It is useful for anyone who wants to learn more about how the code works.

Required Functions

Each XH module includes 19 required functions and some optional ones.

Some of these required functions are S3 class functions in human-XH-interface.R. Others are defined for each module.

One good example is the SIS module, posted in the ramp.xds github repository human-XH-SIS.R.

The required functions deal with various tasks for model building and solving: constructing the XH model object; the dynamics; the parameters; the variables and their initial values; computing terms and standard outputs; and consistency checks. Optional outputs include other metrics; functions to compute steady states; and module specific functions to visualize the outputs.

Each module is defined by a string, generically called Xname, that identifies the module: e.g. SIS.

Dynamics

1. The dynamics are defined by at least one of the following is required, depending on whether the model family is a system of differential equations or a discrete time system:

   • dXHdt.Xname :: differential equations are defined by a function that computes the derivatives. In ramp.xds these are encoded in a function called dXHdt. The function is set up to be solved by deSolve::ode or deSolve::dede.

   • Update_XHt.Xname :: discrete time systems are defined by the function that updates the state variables in one time step. In ramp.xds these are encoded in a function called Update_XHt that computes and returns the state variables. The forms mimic the ones used for differential equations.

XH Model Object

Each module has a pair of functions that set up a structured list called the XH model object. The object is a list that is assigned to a class that dispatches the S3 functions described below. It is a compound list, where some of the sub-lists are assigned their own class that dispatch other S3 functions.

2. make_XH_obj_Xname :: returns a structured list called an XH model object:

   • the parameter values are stored by name

   • class(XH_obj) = Xname

   • the indices for the model variables are stored as XH_obj$ix

   • the initial values are stored as XH_obj$inits

   • ports are added and set to their null values:

     • a function to model the population birth rate

     • a demographic matrix for deaths, aging, and more

     • functions to model mass treatment

   • anything else that is needed can be configured here

3. setup_XH_obj.Xname is a wrapper that calls make_XH_obj_Xname and (for the \(i^{th}\) species) attaches the object as xds_obj$XH_obj[[i]]

Parameters

4. change_XH_pars.Xname changes the values of some parameters. It is designed to be used after setup. New parameter values are passed by name in a list called options.

5. get_XH_pars.Xname is a utility to inspect the values of the parameters.

Variables

Since the XH component is one of three, a function sets up the indices for all the variables in a model.

Two other functions use those indices: one pulls the variables from the state variable vector \(y\); the other one pulls the variables by name from an output matrix returned by xds_solve.

After pulling, both functions return the variables in by name in a list to make it easy to inspect or use.

6. setup_XH_ix.Xname - is the function that assigns an index to each variable in the model, and stores it as xds_obj$XH_obj[[i]]$ix. The indices are returned as a named list.

7. get_XH_vars.Xname - retrieves the value of variables from the state variables vector \(y\) at a point in time and returns the values by name in a list; the function gets called by dXHdt and by change_XH_inits and it can be useful in other contexts.

8. parse_XH_orbits.Xname - this function is like get_XH_vars but it parses the matrix of outputs returned by xds_solve.

Initial Values

A set of functions is sets up or changes the initial values for the state variables.

9. make_XH_inits_Xname - each model must include a function that makes a set of initial values as a named list. This function does not belong to any S3 class, so it can take any form. The function should supply default initial values for all the variables. These can be overwritten by passing new initial values in options.

10. setup_XH_inits.Xname - is a wrapper, that gets called by xds_setup and that calls make_XH_inits_Xname. The setup options are passed to overwrite default values. The initial values are stored as XH_obj$inits.

11. change_XH_inits.Xname - a utility to change the initial values.

Dynamical Terms

These functions compute dynamical terms – the outputs passed to an interface.

12. F_X.Xname - compute the effective infectious density of the vertebrate hosts. This gets computed and passed through the blood feeding and transmission interface to compute \(\kappa.\)

13. F_H.Xname - get the human/host population density

14. F_infectivity.Xname - compute the probability a host will become infected by each infectious bite. This function gets called by the function Exposure, a part of the blood feeding and transmission interface that translates local and travel EIR into an estimated FoI under a model of environmental heterogeneity.

Standard Outputs

Each module must output a few key quantities:

15. F_prevalence.Xname - compute prevalence

16. F_ni.Xname - compute net infectiousness (NI) for each stratum. If \(F_X \rightarrow X\) and \(F_H \rightarrow H\), then \(F_{ni} \rightarrow X/H.\) The function gets called after solving, and the NI is attached as a term for inspection and visualization.

17. HTC.Xname - compute the human transmitting capacity. This is used by functions in ramp.work that compute threshold conditions.

Consistency Checks

Some modules in ramp.xds or ramp.library have been included for various reasons. Not all of those models are capable of being extended. To help users avoid using models in ways that are not appropriate, we developed two function classes:

18. skill_set_XH.Xname :: describes model capabilities and limitations

19. check_XH.Xname :: at the end of xds_setup and at the beginning of xds_solve, this function gets run to ensure that some quantities have been properly updated, and to see if anything has been added to a model that is not in its skill set.

Optional Functions

The XH interface also sets up S3 classes for some optional functions, but these might not be appropriate for all models. If a function is not in the skill set of the module, then the limitation should be noted in the documentation of skill_set_XH.Xname with information in the list.

Optional Outputs

For malaria models, built in functions compute prevalence by various diagnostics.

• F_pfpr_by_lm.Xname :: output predicted prevalence by light microscopy

• F_pfpr_by_rdt.Xname :: output predicted prevalence by rapid diagnostic test

• F_pfpr_by_pcr.Xname :: output predicted prevalence by PCR

Steady States

Methods are defined to compute various steady states under static parameter values.

• steady_state_X.Xname :: pass the FoI and H and computes steady states for the X component, if appropriate.

• steady_state_XH.Xname :: pass the FoI and compute states for the XH component, if appropriate.

• steady_state_H.Xname :: compute steady states for the H component, if appropriate.

Visualization

Functions have been developed to plot the standard terms, but each module can define its own method for plotting:

• xds_plot_XH.Xname is a wrapper that calls xds_lines_X

• xds_lines_XH.Xname defines a default method for plotting orbits