periodMortality: Period Mortality Rate Tabulation and Estimation

In SEEG-Oxford/seegMBG: Streamlined Model-Based Geostatistics Functions for the SEEG Research Group

Description

Compute period mortality estimates, or tabulate exposures/deaths, using DHS or IHME methods

Usage

periodMortality(age_death, birth_int, cluster_id, windows_lower = c(0, 1, 3,
  6, 12, 24, 36, 48), windows_upper = c(0, 2, 5, 11, 23, 35, 47, 59),
  ages_lower = c(0, 0), ages_upper = c(12, 60), nperiod = 1,
  period = 60, period_end = NULL, interview_dates = NULL,
  method = c("monthly", "direct"), cohorts = c("one", "three"),
  inclusion = c("enter", "exit", "both", "either"), mortality = c("bin",
  "monthly"), delay = NULL, glm = FALSE, verbose = TRUE, n_cores = 1,
  ...)

periodTabulate(age_death, birth_int, cluster_id, windows_lower = c(0, 1, 3, 6,
  12, 24, 36, 48), windows_upper = c(0, 2, 5, 11, 23, 35, 47, 59),
  nperiod = 1, period = 60, period_end = NULL, interview_dates = NULL,
  method = c("monthly", "direct"), cohorts = c("one", "three"),
  inclusion = c("enter", "exit", "both", "either"), mortality = c("bin",
  "monthly"), delay = NULL, verbose = TRUE, n_cores = 1)

Arguments

age_death	numeric vector giving the age of death in months of each child. Note that if the child is still alive at the time of interview, corresponding elements of age_death should be given a number greater than max(windows_upper)
birth_int	numeric vector giving the time in month between the child's birth and the interview
cluster_id	vector giving the cluster identifier (can be numeric, cahracter or factor)
windows_lower, windows_upper	numeric vectors giving the non-overlapping lower and upper ages in months of each survival window
ages_lower, ages_upper	numeric vectors giving the non-overlapping lower and upper ages in months of the age windows for which to estimate mortality rates
nperiod	the number of consecutive periods to calculate for. I.e. if period = 12 and nperiod = 3, numbers will be returned for periods 0-12, 13-24 and 25-36 months prior to the interview (plus delay).
period	the length of time in months for which mortality rates should be estimated - scalar
period_end	an optional Dates specifying the end month for the final period for which to tabulate mortality. period_end can only be used if interview_dates is also specified. For example, if three 5-year periods are to be tabulated, ranging from 2000-2015 this date should between 2015-12-01 and 2015-12-31. If period_end = NULL (the default), periods will instead be defined by the period, nperiod and delay arguments. Note that if delay is specified, this *will* be used as well, pushing back all periods be the specified amount.
interview_dates	an optional vector of Dates of the same length as age_death giving the interview date corresponding to each record, to be used in conjunction with period_end. If period_end = NULL, this argument is ignored.
method	the method used to tabulate exposures and deaths, either by combining monthly exposures within the window (method = 'monthly') or directly counting the individuals exposed over the whole period (method = 'direct')
cohorts	the number of cohorts used to tabulate exposures and deaths for each age bins. If cohorts = 'one' then only individuals falling starting and ending the age bin inside the period are counted. If cohorts = 'three' then individuals starting but not ending, or ending but not starting, the age bin inside the period are also counted but the numbers divided by two.
inclusion	which individuals to include in each cohort: 'enter', those entering the target ages during the cohort time period; 'exit', those exiting the target ages during the cohort time period; 'both', those both entering and exiting the target ages during the cohort time period; 'either', those either entering or exiting the target ages during the cohort time period;
mortality	whether to aggregate births/deaths or mortality to return mortality across each age bin (if mortality = 'bin', the default) or to return monthly mortality in that age bin (if mortality = 'monthly'). The latter option is only possible if method = 'monthly', an error will be thrown if this isn't the case.
delay	the length of time in months prior to the interview date to end the (last) period (I.e. the period runs from period + delay months before the interview date to delay days before). Either scalar or NULL, in which case the default delay for cohorts is used: for cohorts = 'one' delay = 0; for cohorts = 'three' delay = max(windows_upper - windows_lower).
glm	whether to infer the window-specific survival probabilities using a binomial random effects model across cluster, window and cohort. If FALSE probabilities are calculated as the raw ratio of the number that survived to the number exposed and may therefore contain zeros and indeterminate values.
verbose	whether to regularly report the stage of the analysis
n_cores	the number of cores on which to carry out computations. periodTabulate will split clusters up and run them on separate cores, and in periodMortality if method = 'glm', this is passed to the num.threads) agument of INLA::inla. To run everything sequentially (the default), just set n_cores = 1.
...	other arguments to pass to INLA::inla

Value

periodMortality: a list with one element for each period, each element being a dataframe with the same number of columns as elements in ages_lower, each column giving the estimated mortality rates for the corresponding age bin in each cluster.

periodTabulate: a dataframe with number of rows equal to all combinations of clusters, age bins and periods; i.e. length(unique(cluster_id)) * length(windows_lower) * nperiod, and four columns:

• cluster_id identifier for the cluster

• exposed number exposed in a given period and age bin

• died number exposed and died in a given period and age bin

• period the corresponding period number

• age_bin the corresponding age bin number

Note

These functions enable reconstruction of the DHS three-cohort method, as well as the IHME method, for estimating period mortality rates via specification of the method,cohorts and inclusion arguments. For the IHME method, the user should specify: method = 'monthly', cohorts = 'one', inclusion = 'enter' and for the DHS method: method = 'direct', cohorts = 'three', inclusion = 'both'. Note that mixing and matching these argument in other ways will likely not lead to sane mortality rate estiamtes, since indivivduals could be recorded multiple times.

Examples

# set seed for reproducibility
set.seed(1)

# make fake mortality data
n <- 1000
birth_int <- rpois(n, 100)
age_death <- rpois(n, exp(rnorm(n, 2)))
cluster_id <- sample(1:5, n, replace = TRUE)

# if any children died after the interview, their age at death chouls be
# recorded as being higher than the upper window max
age_death[age_death > birth_int] <- 6000

# run with default settings
ans <- periodTabulate(age_death,
                     birth_int,
                     cluster_id)

head(ans)

# use four age bins
ans <- periodTabulate(age_death,
                      birth_int,
                      cluster_id,
                      windows_lower = c(0, 1, 12, 36),
                      windows_upper = c(0, 11, 35, 59))

head(ans)

# DHS method for four age bins
ans <- periodTabulate(age_death,
                      birth_int,
                      cluster_id,
                      windows_lower = c(0, 1, 12, 36),
                      windows_upper = c(0, 11, 35, 59),
                      method = 'direct',
                      cohorts = 'three',
                      inclusion = 'both')

head(ans)

# IHME method for four age bins
ans <- periodTabulate(age_death,
                      birth_int,
                      cluster_id,
                      windows_lower = c(0, 1, 12, 36),
                      windows_upper = c(0, 11, 35, 59),
                      method = 'monthly',
                      cohorts = 'one',
                      inclusion = 'enter')

head(ans)

# IHME method for four age bins, tabulating monthly exposures
ans <- periodTabulate(age_death,
                      birth_int,
                      cluster_id,
                      windows_lower = c(0, 1, 12, 36),
                      windows_upper = c(0, 11, 35, 59),
                      method = 'monthly',
                      cohorts = 'one',
                      inclusion = 'enter',
                      mortality = 'monthly')

head(ans)

# calculate mortality rates over fixed periods

# assign an interview date to each cluster
(int_date_cluster <- Sys.Date() - rpois(5, exp(rnorm(5, 6))))
int_date <- int_date_cluster[cluster_id]

# & define the final month of the final estimation period
# E.g. for 3x 5-year bins starting in 2000, the final period would end in
# December 2014

ans <- periodTabulate(age_death,
                      birth_int,
                      cluster_id,
                      windows_lower = c(0, 1, 12, 36),
                      windows_upper = c(0, 11, 35, 59),
                      method = 'monthly',
                      cohorts = 'one',
                      nperiod = 3,
                      period = 60,
                      period_end = as.Date('2014-12-01'),
                      interview_dates = int_date,
                      inclusion = 'enter',
                      mortality = 'monthly')

SEEG-Oxford/seegMBG documentation built on May 9, 2019, 11:08 a.m.