In ffinger/followup: Evidence based prioritisation of contacts to follow-up during infectious disease outbreaks

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width=7,
  fig.height=5,
  fig.path="figs-overview/")

Installing the package

To install the current stable, CRAN version of the package, type:

install.packages("followup")

To benefit from the latest features and bug fixes, install the development, github version of the package using:

devtools::install_github("ffinger/followup")

Note that this requires the package devtools installed.

Main functions of the package

The main functions of the package include:

followup_priorities() : Compute the followup priorities for a list of contacts.

Outputs the probability that the symptoms onset of a contact was between the last follow up (day of last follow up included in interval by default, see parameter include_last_follow_up) and the analysis date, which defaults to day before current day and is included in interval.

Background

THIS SECTION NEEDS UPDATING

Contact has never been followed up

The probability of symptoms onset by day $t$ after exposure event that leads to symptomatic infection is

$$P(\mathrm{onset\,by\,day\,}t) = \sum_{\tau=0}^t p_I(\tau)$$

where $p_I(\tau)$ is the probability that the incubation period is $\tau$.

Combined with a given probability $p_S$ of an exposure event leading to symptoms we thus get a probability of symptoms by day $t$ of

$$P(\mathrm{symptoms\,by\,day\,}t) = p_S\,\sum_{\tau=0}^t p_I(\tau)$$

Contact has previously been followed up

If a contact has previously been followed up on day $T$ and no symptoms observed the probability of onset on day $t >= T$ has to be modified as follows

$$P(\mathrm{onset\,between\,days\,}t \mathrm{\,and\,}T\, \vert \mathrm{\,no\,onset\,between\,days\,}0 \mathrm{\,and\,}T-1) = \frac{\sum_{\tau=T}^t p_I(\tau)}{1-\sum_{\tau=0}^{T-1} p_I(\tau)}$$

and

$$P(\mathrm{symptoms\,between\,days\,}t \mathrm{\,and\,}T) = p_S \frac{\sum_{\tau=T}^t p_I(\tau)}{1-\sum_{\tau=0}^{T-1} p_I(\tau)}$$

Note that due to the discrete nature of the problem, a decision has to be made if observing no symptoms at some time during day $T$ is taken as the onset of symptoms being at a time $t$ after the end of day $T-1$ (and thus could be during day $T$ but after the observation), or after the end of day $T$. By default this package assumes that follow up on day $T$ ensures that symptoms onset has not occurred before the end of day $T-1$, as shown in the equations above. The parameter include_last_follow_up can be used to modify this behaviour.

Examples

Load environment:

library(dplyr)
library(epitrix)
library(distcrete)
library(followup)

Set up the incubation period distribution:

incubation_days <- 0:12
incubation_frequency <- distcrete("gamma", 1, shape = 12, rate = 3, w =
0)$d(incubation_days)

plot(incubation_days, incubation_frequency, type = "h")

Create toy data

Make a list of example contacts each having a sequence of consecutive exposure dates. The beginning of the exposure is given in column dates_exposure and the end in exposure_end. Some contacts hae a date when they were last followed up. Contacts that have never been followed up will have NA in the date_last_followup column.

n = 10
contact_list <- data.frame(
  id_contact = replicate(n, paste(sample(letters, 3, replace = TRUE),
          collapse = "")),
  type_exposure = sample(c("hospital", "funeral", "family", "other"), n, replace = TRUE),
  dates_exposure = Sys.Date() - sample(6:20, n, replace = TRUE)
)

contact_list$exposure_end <- contact_list$dates_exposure + sample(1:5, n, replace = TRUE)
contact_list$date_last_followup <- Sys.Date() - sample(c(1:8, rep(NA, 6)), n, replace = TRUE)

contact_list

Sometimes exposure dates for a contact are not consecutive. In this case we can give the possible exposure dates for each patient as a list. Make a separate contact list to illustrate this case:

contact_list_2 <- dplyr::select(contact_list, id_contact, type_exposure, date_last_followup)

#function used to create toy non-consecutive exposure dates
mkexposures <- function(foo) foo - base::sample(
    incubation_days,
    size = sample.int(4, size = 1),
    replace = FALSE,
    prob = incubation_frequency
  )

contact_list_2$dates_exposure <- sapply(Sys.Date() - 15 + sample(1:15, n, replace = TRUE), mkexposures)

contact_list_2

Let's just have a closer look at the structure of the dates_exposure column, which is a so-called list column, where each element contains a vector of dates of variable length:

str(contact_list_2$dates_exposure)

All contacts have the same probability of getting disease

Now compute the probability of the symptoms onset being between the last day of follow up and yesterday (including start and end days):

contact_list_p <- followup_priorities(
                    contact_list,
                    exposure = dates_exposure,
                    exposure_end = exposure_end,
                    last_followup = date_last_followup,
                    rate_infectious_contact = 0.3,
                    incubation_period = incubation_frequency
                )

contact_list_p

Non-consecutive exposure dates

Do the same for contact_list_2, where exposure_dates are non-consecutive:

contact_list_p2 <- followup_priorities(
                    contact_list_2,
                    exposure = dates_exposure,
                    last_followup = date_last_followup,
                    rate_infectious_contact = 0.3,
                    incubation_period = incubation_frequency
                )

contact_list_p2

Probability of getting disease depends on type of exposure

Above we assumed that every kind of exposure results in the same probability of developing disease. Thus the prioritization is solely based on the incubation period, the time spent since exposure and the last follow up.

Let's now take into account different exposure pathways and assign different probabilities of developing disease after different types of exposure:

pathways = data.frame(
  type_exposure = c("hospital", "funeral", "family", "other"),
  rate_infectious_contact = c(0.2, 0.3, 0.45, 0.12)
)

pathways

Include those probabilities in the contact list:

contact_list <- dplyr::left_join(contact_list, pathways, by = "type_exposure")

contact_list

Now recompute the priorities:

contact_list_p3 <- followup_priorities(
                  contact_list,
                  exposure = dates_exposure,
                  exposure_end = exposure_end,
                  last_followup = date_last_followup,
                  rate_infectious_contact = contact_list$rate_infectious_contact,
                  incubation_period = incubation_frequency
                )

contact_list_p3