Merge pull request #161 from dd-harp/dev

Heterogeneous biting vignette updated; new function to plot Z

NAMESPACE

@@ -505,13 +505,15 @@ export(xde_lines_X_SIP)
 export(xde_lines_X_SIS)
 export(xde_lines_YZ)
 export(xde_lines_YZ_fracs)
+export(xde_lines_Z_fracs)
 export(xde_lines_aEIR)
 export(xde_plot_EIR)
 export(xde_plot_M)
 export(xde_plot_PR)
 export(xde_plot_X)
 export(xde_plot_YZ)
 export(xde_plot_YZ_fracs)
+export(xde_plot_Z_fracs)
 export(xde_plot_aEIR)
 export(xde_setup)
 export(xde_setup_aquatic)

R/plot-MYZ.R

@@ -55,7 +55,7 @@ xde_plot_YZ = function(pars, s=1, Yclrs = "purple", Zclrs="darkred", llty=1, sta
 
   if(add_axes == TRUE)
     with(vars$MYZ[[s]],
-         plot(time, 0*time, type = "n", ylim = range(0,max(Y)),
+         plot(time, 0*time, type = "n", ylim = range(0,max(Y,Z)),
               ylab = "Mosquito Density", xlab = "Time"))
 
   xde_lines_YZ(vars$MYZ[[s]], pars, Yclrs, Zclrs, llty)
@@ -136,3 +136,49 @@ xde_lines_YZ_fracs = function(MYZ, pars, Yclrs="purple", Zclrs="darkred", llty=1
       }
     }
 })}
+
+
+#' Plot the fraction of infected and infective mosquitoes
+#'
+#' @param pars a list that defines an `exDE` model (*e.g.*,  generated by `xde_setup()`)
+#' @param s the vector species index
+#' @param Zclrs a vector of colors for infective mosquitoes
+#' @param llty an integer (or integers) to set the `lty` for plotting
+#' @param stable a logical, set to FALSE for `orbits` and TRUE for `stable_orbits`
+#' @param add_axes a logical to plot axes only if TRUE
+#'
+#' @export
+xde_plot_Z_fracs = function(pars, s=1, Zclrs = "darkred", llty=1, stable=FALSE, add_axes=TRUE){
+  vars=with(pars$outputs,if(stable==TRUE){stable_orbits}else{orbits})
+
+  if(add_axes == TRUE)
+    with(vars$MZ[[s]],
+         plot(time, 0*time, type = "n", ylim = range(0,vars$MZ[[s]]$z),
+              ylab = "Fraction Infected", xlab = "Time"))
+
+  xde_lines_Z_fracs(vars$MZ[[s]], pars,  Zclrs, llty)
+}
+
+#' Add lines for the fraction of infected and infective mosquitoes
+#'
+#' @param MZ a list the output of `exDE::parse_deout()`
+#' @param pars a list that defines an `exDE` model (*e.g.*,  generated by `xde_setup()`)
+#' @param Zclrs a vector of colors for infective mosquitoes
+#' @param llty an integer (or integers) to set the `lty` for plotting
+#'
+#' @export
+xde_lines_Z_fracs = function(MZ, pars, Zclrs="darkred", llty=1){
+  with(MZ,{
+    if(pars$nPatches==1) {
+      lines(time, z, col=Zclrs, lty = llty[1])
+    }
+    if(pars$nPatches>1){
+      if (length(Zclrs)==1) Zclrs=rep(Zclrs, pars$nPatches)
+      if (length(llty)==1) llty=rep(llty, pars$nPatches)
+
+      for(i in 1:pars$nPatches){
+        lines(time, z[,i], col=Zclrs[i], lty = llty[i])
+      }
+    }
+  })}
+

_pkgdown.yml

@@ -183,6 +183,8 @@ reference:
   - xde_lines_YZ
   - xde_plot_YZ_fracs
   - xde_lines_YZ_fracs
+  - xde_plot_Z_fracs
+  - xde_lines_Z_fracs
 - subtitle: EIP
   desc: |
     Specialized methods for  NULL dynamics: a funtion generates values of Z to force human infection dynamics

vignettes/heterogeneous_biting.Rmd

@@ -14,41 +14,78 @@ knitr::opts_chunk$set(
 )
 ```
 
-Heterogeneous blood feeding is a basic feature of malaria transmission (see [Heterogeneous Transmission](heterogeneous_transmission.html)). In `exDE,` the term **heterogeneous biting** is used to describe differences in the expected rate of exposure among population strata. 
+In `exDE,` the term **heterogeneous biting** is used to describe differences among population strata in the expected rate of exposure to infective mosquitoes. 
+To be more rigorous, let $E$ denote the *average* daily entomological inoculation rate (dEIR) for a population with multiple strata, and $\xi_i$ the frailty term, then the dEIR for the $i^{th}$ stratum is: 
+$$E_i = \xi_i E.$$ 
+The implementation is part of a coherent model for blood feeding that serves at the interface between models of parasite/pathogen infections in humans (*i.e.* $\cal X$), and models of parasite infections in mosquitoes (*i.e.* $\cal YZ$). In this vignette, we introduce the *concept* of heterogeneous biting and its implementation in the blood feeding model using **blood feeding search weights.**
 
-To be more rigorous, let $h$ denote the *average* force of infection (FoI) for a population with multiple strata, and $\xi_i$ the frailty term, then the FoI for the $i^{th}$ stratum is $$h_i = \xi_i h;$$ 
 
-## Heterogeneous Biting 
+Heterogeneous blood feeding is a basic feature of malaria transmission, and an important aspect of [Heterogeneous Transmission](heterogeneous_transmission.html). 
+
+
+## Definitions 
 
 **Heterogeneous Biting** is defined throughout the `exDE` implementation and documentation as a difference in the relative biting rates for two strata that are otherwise identical. The implementation relies on two concepts:
 
 + **blood feeding search weights** or $\left\{\omega\right\}$
 
 + **relative biting rates** or  $\left\{\xi\right\}$
 
-### Blood Feeding Search Weights 
+The software deals mainly with the search weights because the denominators are changing, but it is useful to understand how search weights are related to relative biting rates. 
+
+## Blood Feeding Search Weights 
 
 A flexible implementation is handled through the blood feeding model, which includes the the concepts of *blood feeding search weights* and *availability*. The search weights, $\left\{\omega\right\}$, are a measure of how easy it is for mosquitoes to find and blood feed on a host. The total *availability* of humans for blood feeding is:
 
 $$W = \sum_i \omega_i H_i.$$
 Availability is used to compute the overall blood feeding rate for mosquitoes and the human fraction (human blood meals as a fraction of all blood meals). If we assign a biting weight to a stratum, then the fraction of bites received by that stratum is: 
 
 $$ \frac{\omega_i H_i}W.$$ 
+**Example 1:** For example, suppose that there are 200 people with a biting weight of 2.25 and 800 people with a biting weight of 1. In this model, the first stratum would get 36% of the total bites:
+
+```{r}
+2.25*200/(2.25*(200) + 1*(800))
+```
 
-### Relative Biting Rates 
+## Relative Biting Rates 
 
 If we let $h$ denote the *average* force of infection (FoI) for a population with multiple strata, and $\xi_i$ the frailty term, then the FoI for the $i^{th}$ stratum is $$h_i = \xi_i h;$$ 
 
 We let $H_i$ denote the size of the $i^{th}$ population, where $$H = \sum_i H_i.$$ 
 
 The relative biting rates are constrained such that 
 $$\sum_i \xi_i \frac{H_i}H = 1$$ 
-For example, if 20% of the population gets bitten at a rate that is twice as high as the population  average, then the other 80% must get bitten (on average) at a rate that is 3/4 the population average, since:
 
-$$ 2\;(0.2)+ 0.75\;(0.8)= 1$$ 
+**Example 2:**
 
+For example, if 20% of the population gets bitten at a rate that is 80% higher than the population average, then the other 80% must get bitten (on average) at a rate that is 80% of the population average.
 
+```{r}
+1.8*0.2+ 0.8*0.8
+```
 
 Relative biting rates are computed automatically from the blood feeding search weights, $\left\{\omega\right\},$ where 
 
-$$\xi_i = \omega_i \frac H W.$$
+$$\xi_i = \omega_i\frac{H}{W}.$$
+
+
+**Example 3** computes the search weights from the biting weights
+
+```{r}
+searchWts = c(2.25, 1)
+Hi = c(200, 800)
+H = sum(Hi) 
+W = sum(searchWts*Hi)
+xi = searchWts*H/W
+xi 
+```
+```{r}
+sum(xi*Hi)/H
+```
+
+## Implementation
+
+In `exDE,` the concept of human *availability* for blood feeding is also modified by time spent, and the algorithms were designed to deal with both changing denominators and changing search weights. Infective bites in a patch are distributed among population strata by taking a stratum's availability divided by the whole. The blood feeding model outputs a vector of dEIR values for each stratum. 
+
+A relative biting rate is an interesting summary statistic, but it not computed as part of the blood feeding model.  
+