diff --git a/NAMESPACE b/NAMESPACE index 62bae11a..5e6ecbbd 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -505,6 +505,7 @@ 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) @@ -512,6 +513,7 @@ 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) diff --git a/R/plot-MYZ.R b/R/plot-MYZ.R index 7a2f4a15..3717f00b 100644 --- a/R/plot-MYZ.R +++ b/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]) + } + } + })} + diff --git a/_pkgdown.yml b/_pkgdown.yml index 0ac27576..8c55e109 100644 --- a/_pkgdown.yml +++ b/_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 diff --git a/man/xde_lines_Z_fracs.Rd b/man/xde_lines_Z_fracs.Rd new file mode 100644 index 00000000..5d457d11 --- /dev/null +++ b/man/xde_lines_Z_fracs.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/plot-MYZ.R +\name{xde_lines_Z_fracs} +\alias{xde_lines_Z_fracs} +\title{Add lines for the fraction of infected and infective mosquitoes} +\usage{ +xde_lines_Z_fracs(MZ, pars, Zclrs = "darkred", llty = 1) +} +\arguments{ +\item{MZ}{a list the output of \code{exDE::parse_deout()}} + +\item{pars}{a list that defines an \code{exDE} model (\emph{e.g.}, generated by \code{xde_setup()})} + +\item{Zclrs}{a vector of colors for infective mosquitoes} + +\item{llty}{an integer (or integers) to set the \code{lty} for plotting} +} +\description{ +Add lines for the fraction of infected and infective mosquitoes +} diff --git a/man/xde_plot_Z_fracs.Rd b/man/xde_plot_Z_fracs.Rd new file mode 100644 index 00000000..c70d6126 --- /dev/null +++ b/man/xde_plot_Z_fracs.Rd @@ -0,0 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/plot-MYZ.R +\name{xde_plot_Z_fracs} +\alias{xde_plot_Z_fracs} +\title{Plot the fraction of infected and infective mosquitoes} +\usage{ +xde_plot_Z_fracs( + pars, + s = 1, + Zclrs = "darkred", + llty = 1, + stable = FALSE, + add_axes = TRUE +) +} +\arguments{ +\item{pars}{a list that defines an \code{exDE} model (\emph{e.g.}, generated by \code{xde_setup()})} + +\item{s}{the vector species index} + +\item{Zclrs}{a vector of colors for infective mosquitoes} + +\item{llty}{an integer (or integers) to set the \code{lty} for plotting} + +\item{stable}{a logical, set to FALSE for \code{orbits} and TRUE for \code{stable_orbits}} + +\item{add_axes}{a logical to plot axes only if TRUE} +} +\description{ +Plot the fraction of infected and infective mosquitoes +} diff --git a/vignettes/heterogeneous_biting.Rmd b/vignettes/heterogeneous_biting.Rmd index 0e17466a..79a2686a 100644 --- a/vignettes/heterogeneous_biting.Rmd +++ b/vignettes/heterogeneous_biting.Rmd @@ -14,11 +14,16 @@ 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: @@ -26,7 +31,9 @@ To be more rigorous, let $h$ denote the *average* force of infection (FoI) for a + **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: @@ -34,8 +41,13 @@ $$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;$$ @@ -43,12 +55,37 @@ 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. +