Package 'epidist'

Description

Adds the mean and standard deviation of the delay distribution implied by each draw of the distributional parameters, and quantiles of that distribution if probs is given. Analytic solutions are used for the families that have one. The exponential family is summarised by simulating delays from it.

Usage

add_summaries(
  data,
  family = NULL,
  probs = NULL,
  method = c("auto", "analytic", "sample"),
  nsim = 1000
)

Arguments

Details

The summaries describe the delay distribution, not the posterior. A row of data holds one draw of the distributional parameters, and the columns added are the mean, standard deviation and quantiles of the delay distribution those parameters define. Summarise the resulting columns across draws to get posterior summaries of them.

Quantile columns are named as in posterior::quantile2(), so probs = 0.05 gives a q5 column.

Simulation adds Monte Carlo error to the summaries. The standard error of the mean is the delay standard deviation divided by the square root of nsim. Simulation is also memory hungry, because it draws nsim delays for every row of data. Reduce the number of rows with epidist_strata(), or the number of draws with the ndraws argument of delay_parameter_draws(), if it is slow.

Value

The input with mean and sd columns added, and one column per element of probs. It has the epidist_delay_draws class, which records the family used and gives it a plot() method.

See Also

Other postprocess: as_dist_spec.epidist_fit(), delay_parameter_draws(), delay_summary_draws(), epidist_delay_draws, epidist_strata()

Examples

draws <- data.frame(mu = c(1.8, 2.0), sigma = c(0.5, 0.4))
add_summaries(draws, family = "lognormal", probs = c(0.05, 0.95))

Description

Summarises the posterior of a fitted delay distribution into an uncertain ⁠<dist_spec>⁠ from the distspec package, for use in packages that take their delay distributions in that form. The natural parameters of the delay distribution are computed for each posterior draw and summarised into a prior on each of them.

Usage

## S3 method for class 'epidist_fit'
as_dist_spec(x, newdata = NULL, max = Inf, cdf_max = 1, ...)

Arguments

Details

The lognormal, gamma and Weibull families are supported, as those are the delay distributions distspec has. Their brms parameters are mapped to the natural parameters of the matching distspec constructor for every draw before summarising:

• lognormal: mu is meanlog and sigma is sdlog of distspec::LogNormal().

• gamma: shape is shape and shape / mu is rate of distspec::Gamma().

• Weibull: shape is shape and mu / gamma(1 + 1 / shape) is scale of distspec::Weibull().

Open an issue at https://github.com/epiforecasts/distspec/issues to ask distspec for another distribution.

Each natural parameter gets a distspec::Normal() prior with the mean and standard deviation of its marginal posterior. The posterior correlation between the parameters is not represented, so sampling from the result gives a wider range of delay distributions than the posterior does.

The default newdata is built with epidist_newdata() by expanding the variables in the model formula into a grid, so it has one row per unique combination of the predictors, and gives the delay distribution with no censoring and no truncation. A model with only an intercept gets a single row. A continuous predictor gets a row per distinct value, so pass newdata for such a model.

Value

A ⁠<dist_spec>⁠ when newdata has one row. A named list of them, one per row of newdata, when it has several. The names give the values of the columns of newdata that differ between rows, such as "sex=0", and are the row numbers when no column differs.

See Also

delay_parameter_draws() for the draws this summarises and epidist_newdata() to build newdata.

Other postprocess: add_summaries(), delay_parameter_draws(), delay_summary_draws(), epidist_delay_draws, epidist_strata()

Examples

if (requireNamespace("distspec", quietly = TRUE)) {
  fit <- sierra_leone_ebola_data |>
    as_epidist_linelist_data(
      pdate_lwr = "date_of_symptom_onset",
      sdate_lwr = "date_of_sample_tested"
    ) |>
    as_epidist_aggregate_data() |>
    as_epidist_marginal_model() |>
    epidist(chains = 2, cores = 2, refresh = ifelse(interactive(), 250, 0))

  dist <- distspec::as_dist_spec(fit)
  dist

  # The delay distribution at the posterior mean of its parameters
  distspec::fix_parameters(dist, strategy = "mean")

  # Bound the delay distribution at 60 days for a package that takes bounds
  distspec::as_dist_spec(fit, max = 60)
}

Description

Creates an epidist_aggregate_data object from various input formats. This is useful when working with pre-aggregated data where each row represents multiple identical observations. See the specific methods for details on supported input formats and usage examples.

Usage

as_epidist_aggregate_data(data, ...)

Arguments

Value

An object of class epidist_aggregate_data.

See Also

Other aggregate_data: as_epidist_aggregate_data.data.frame(), as_epidist_aggregate_data.default(), as_epidist_aggregate_data.epidist_linelist_data(), assert_epidist.epidist_aggregate_data(), is_epidist_aggregate_data(), new_epidist_aggregate_data()

Description

This method takes a data.frame containing event dates (primary/secondary event dates and observation date) along with counts and creates an epidist_aggregate_data object. This format is useful when working with pre-aggregated data where each row represents multiple identical observations with the count stored in a specified column. Internally it makes use of as_epidist_linelist_data.data.frame() to convert the data to a linelist format before adding the count column. See the other methods for other data input options.

Usage

## S3 method for class 'data.frame'
as_epidist_aggregate_data(
  data,
  n = NULL,
  pdate_lwr = NULL,
  sdate_lwr = NULL,
  pdate_upr = NULL,
  sdate_upr = NULL,
  obs_date = NULL,
  ...
)

Arguments

Value

An object of class epidist_aggregate_data.

See Also

Other aggregate_data: as_epidist_aggregate_data(), as_epidist_aggregate_data.default(), as_epidist_aggregate_data.epidist_linelist_data(), assert_epidist.epidist_aggregate_data(), is_epidist_aggregate_data(), new_epidist_aggregate_data()

Examples

sierra_leone_ebola_data |>
  dplyr::count(date_of_symptom_onset, date_of_sample_tested) |>
  as_epidist_aggregate_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested",
    n = "n"
  )

Description

This method takes vectors of event times (primary/secondary event times and observation time) along with counts and creates an epidist_aggregate_data object. This format is useful when working with pre-aggregated data where each row represents multiple identical observations with the count stored in the n column. Internally it makes use of as_epidist_linelist_data.default() to convert the data to a linelist format before adding the count column. See the other methods for other data input options.

Usage

## Default S3 method:
as_epidist_aggregate_data(
  data,
  n = NULL,
  ptime_upr = NULL,
  stime_lwr = NULL,
  stime_upr = NULL,
  obs_time = NULL,
  ...
)

Arguments

Value

An object of class epidist_aggregate_data.

See Also

Other aggregate_data: as_epidist_aggregate_data(), as_epidist_aggregate_data.data.frame(), as_epidist_aggregate_data.epidist_linelist_data(), assert_epidist.epidist_aggregate_data(), is_epidist_aggregate_data(), new_epidist_aggregate_data()

Examples

as_epidist_aggregate_data(
  data = c(1, 2, 3),
  ptime_upr = c(2, 3, 4),
  stime_lwr = c(3, 4, 5),
  stime_upr = c(4, 5, 6),
  obs_time = c(5, 6, 7),
  n = c(1, 2, 3)
)

Description

This method takes an epidist_linelist_data object (see as_epidist_linelist_data()) and aggregates it by counting unique combinations of the required time variables (primary/secondary event times and observation time) and any additional variables specified in by. The result is a more compact representation of the same data where each row represents multiple identical observations with the count stored in the n column.

Usage

## S3 method for class 'epidist_linelist_data'
as_epidist_aggregate_data(data, by = NULL, ...)

Arguments

Value

An object of class epidist_aggregate_data.

See Also

Other aggregate_data: as_epidist_aggregate_data(), as_epidist_aggregate_data.data.frame(), as_epidist_aggregate_data.default(), assert_epidist.epidist_aggregate_data(), is_epidist_aggregate_data(), new_epidist_aggregate_data()

Examples

# Default stratification by required time variables only
sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_aggregate_data()

# Additional stratification by other variables
sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_aggregate_data(by = "age")

Description

Creates an epidist_estimates_data object from published summary estimates of a delay distribution. Each row is a single reported summary component (a mean, a standard deviation, or a quantile) together with the metadata needed to work out what the study that reported it was actually estimating. These objects are the summary data input to as_epidist_meta_model(). See the specific methods for details on supported input formats and usage examples.

Usage

as_epidist_estimates_data(data, ...)

Arguments

Details

The meta model these objects feed is experimental. Its interface may still change in future releases.

Value

An object of class epidist_estimates_data.

See Also

Other estimates_data: as_epidist_estimates_data.data.frame(), as_epidist_estimates_data.epidist_estimates_data(), as_epidist_estimates_data.epidist_multivariate(), as_epidist_estimates_data.list(), assert_epidist.epidist_estimates_data(), epidist_estimates_epireview(), epidist_estimates_parameters(), epidist_estimates_summaries(), is_epidist_estimates_data(), new_epidist_estimates_data()

Description

This method takes a data.frame of published summary estimates and creates an epidist_estimates_data object. Column names may either match the names used below or be supplied via the corresponding argument.

Usage

## S3 method for class 'data.frame'
as_epidist_estimates_data(
  data,
  study = NULL,
  type = NULL,
  value = NULL,
  se = NULL,
  n = NULL,
  p = NULL,
  pwindow = NULL,
  swindow = NULL,
  relative_obs_time = NULL,
  trunc_adjusted = NULL,
  trunc_design = NULL,
  cens_adjusted = NULL,
  delay_min = NULL,
  growth_rate = NULL,
  growth_rate_sd = NULL,
  max_delay = NULL,
  advise = TRUE,
  ...
)

Arguments

Value

An object of class epidist_estimates_data.

What we need from each study

Published delay estimates are almost never estimates of the true continuous delay distribution. To use them we forward model what the study's estimation procedure would converge to, which means we need to know how the study handled the biases we support, along with the data process it saw. vignette("model") derives each estimand, and vignette("meta") works through assembling this metadata for simulated and real studies. For each study we need:

• How it adjusted for censoring (cens_adjusted). A taxonomy of the common ways interval censored delays are summarised, deliberately limited to a few widely used approaches:

  • 0: no adjustment. The study took integer date differences (for example date of onset subtracted from date of report) and summarised them directly. This is the most common case in the literature.

  • 1: fully adjusted. The study used a method targeting the underlying continuous distribution, such as a double interval censored likelihood.

  • 2: uniform single interval approximation. The study adjusted the secondary interval only, assuming a uniform delay within it, and left the primary interval uncorrected.

  • 3: midpoint imputation. The study assigned each delay to the centre of the interval it was observed in, which shifts every reported delay up by half a secondary window without changing its spread.

  • 4: midpoint imputation with a uniform interval. The study placed the primary event at the midpoint of its window and integrated the secondary interval. Common where the primary event has a wide exposure window and the secondary date is recorded precisely. With a wide primary window the shortest delays are reported below zero, so the estimand puts mass there. Set delay_min if the study dropped them.

  Use code 3 for a study that midpointed the secondary interval and left the primary alone. Anything more exotic must be approximated by whichever code is closest, and if you cannot tell which a study used, state the assumption you are making.

• Whether it adjusted for right truncation (trunc_adjusted) and, if it did not, the observation time (relative_obs_time) and how collection stopped (trunc_design). For a cohort the observation time is the truncation point on the delay scale. For an accrual design, where collection stopped at a calendar date, it is the length of the collection window, which is usually easier to read off a paper. Real time estimates are right truncated unless the study corrected for it.

• The censoring windows (pwindow, swindow). The width, in the same time units as the delay, of the interval each event was observed in. Daily reporting gives windows of 1, weekly reporting gives 7. A fully adjusted study does not use them and may leave them NA.

• The sample size (n), the number of delays the summary was computed from. This sets the sampling uncertainty on the reported value. A reported standard error (se) may be given instead, and takes precedence when supplied.

• The minimum delay it counted (delay_min), where the study dropped delays below some point. Its summaries then describe a left truncated delay distribution. Defaults to 0, meaning the study counted every delay.

Systematic reviews rarely record this metadata, so you must supply your own assumption and say so alongside any results. Where it is missing entirely, a covariate for the phase of the outbreak each estimate was made in is another option, since the brms formula makes it a meta-regression that estimates the residual bias rather than correcting it mechanically.

What shape a study reported its estimate in

This method takes a long table with one row per reported summary. Two other shapes are common enough to have their own entry points, each returning an object this one would.

• epidist_estimates_summaries() takes one study's summaries in wide form.

• epidist_estimates_parameters() takes the parameters of a distribution a study fitted, which studies often publish in place of summaries, and converts them to the summaries the fitted distribution implies. Reported parameters are not a type here, because the family a study fitted need not be the family being fitted to it.

A study that published draws of its parameters, rather than point summaries of them, can report the correlation between the quantities it reports. Pass the draws to as_epidist_multivariate() and the result to as_epidist_estimates_data(), which is the only route by which a covariance reaches as_epidist_meta_model(). Such rows need no n and no se.

Contributions from several studies combine by passing them in a list, which as_epidist_estimates_data() binds into one object.

Checks

Beyond validating its input, this method runs advisory checks on the summaries and messages about the studies they flag. They run once, when the object is built, and not again when it is passed to as_epidist_meta_model(). Each message names the studies concerned, and the row of the input where a single summary is meant, and a pointer here follows the messages of a call. Studies combined in a list are checked once, together, and simulate_study() leaves the checks to that combined object. Set advise = FALSE to skip them.

• Assumed truncation adjustment. Where no trunc_adjusted column is supplied, a study with no finite relative_obs_time is taken to have adjusted for right truncation and every other study not to have. Real time estimates are right truncated unless the study corrected for it, and reviews rarely record which did, so this is the assumption most likely to be wrong and is a warning rather than a message.

• Short grid cutoff. The implied summaries of a study that adjusted for right truncation but is evaluated on a grid, which is a study with cens_adjusted 0 or 3, or 2 or 4 with a non zero or estimated growth_rate, run to max_delay. A cutoff the delay distribution has not decayed by biases them downwards, and the standard deviation most, because the tail beyond the cutoff carries a share of the second moment out of all proportion to its mass. A lognormal is matched to what the study reported, through its mean and standard deviation, or its median and largest quantile above the median where it reported only quantiles, and the study is flagged when more than 2% of the second moment of that lognormal lies beyond the cutoff. That is where the standard deviation on the grid falls about 1% short, and the shortfall grows with the share. Studies reporting neither pair are not checked. Raise max_delay for the study.

• Coarse quadrature. The moments and distribution function of a continuous estimand truncated at the grid cutoff are computed by Simpson's rule on equally spaced intervals from delay_min to the cutoff, so the node spacing is set by the cutoff and not by the scale of the delay. The number of intervals is chosen per study so that the spacing is at most a quarter of the spread the study reported, with options(epidist.meta_n_quad) as its floor and 2000 as a cap the option lifts when set above it. A study whose cutoff is very long relative to its spread hits the cap and is left with nodes further apart than that, so its implied summaries may be inaccurate. This covers a study that did not adjust for right truncation and used a continuous adjustment (cens_adjusted 1, 2 or 4), a study that did adjust but whose primary events were not uniform within their window (cens_adjusted 2 or 4 with a non zero or estimated growth_rate), and the quantiles of a study reporting a covariance matrix, which are read off the same nodes. Raise the option above the cap before building the model data, or lower max_delay.

• Coarse quantiles. A study that summarised interval censored delays without adjusting for censoring (cens_adjusted 0 or 3) reports quantiles of a discrete distribution, which the model interpolates through the mid points of its cells. The reported value is still rounded to that grid, and what the interpolation leaves behind does not shrink with the study sample size. It is a few percent once a reported quantile sits a few tens of cells above the smallest delay the study counted, and tens of percent when it sits within about ten. A study is flagged on its smallest reported quantile, the one nearest that edge of the grid, because the residual on that quantile is what biases the fitted spread even when the larger quantiles of the same study sit well up the grid. Check that swindow is the resolution the study worked at. A reported mean and standard deviation of the same delays do not carry this residual, so fit them in preference where the study gives them.

• Heavy tailed standard deviation. The sampling standard error of a reported standard deviation is $\sigma \sqrt{(\kappa - 1) / (4 n)}$, with $\kappa$ the kurtosis of the delays. The normal approximation behind it holds while that relative standard error is below about a quarter. Above it the sampling distribution of a sample standard deviation is far from normal, the asymptotic standard error overstates its spread by up to two times, and the joint likelihood of a mean and standard deviation pair is biased by about a standard error. The kurtosis is taken from the reported mean and standard deviation under a lognormal delay, which is a plausible tail for a delay of that coefficient of variation. Where the study reports quantiles inside the body of the distribution, those are safer to fit.

See Also

Other estimates_data: as_epidist_estimates_data(), as_epidist_estimates_data.epidist_estimates_data(), as_epidist_estimates_data.epidist_multivariate(), as_epidist_estimates_data.list(), assert_epidist.epidist_estimates_data(), epidist_estimates_epireview(), epidist_estimates_parameters(), epidist_estimates_summaries(), is_epidist_estimates_data(), new_epidist_estimates_data()

Examples

as_epidist_estimates_data(
  data.frame(
    study = c("A", "A", "B"),
    type = c("mean", "sd", "quantile"),
    value = c(7.5, 3.6, 11.2),
    p = c(NA, NA, 0.9),
    n = c(120, 120, 80),
    relative_obs_time = c(20, 20, Inf),
    trunc_adjusted = c(FALSE, FALSE, TRUE),
    cens_adjusted = c(0, 0, 1)
  )
)

Description

An object carrying the class has already been checked, and the epidist_data methods re-check it whenever it is modified, so nothing is done here.

Usage

## S3 method for class 'epidist_estimates_data'
as_epidist_estimates_data(data, ...)

Arguments

Value

The input, unchanged.

See Also

Other estimates_data: as_epidist_estimates_data(), as_epidist_estimates_data.data.frame(), as_epidist_estimates_data.epidist_multivariate(), as_epidist_estimates_data.list(), assert_epidist.epidist_estimates_data(), epidist_estimates_epireview(), epidist_estimates_parameters(), epidist_estimates_summaries(), is_epidist_estimates_data(), new_epidist_estimates_data()

Examples

estimates <- epidist_estimates_summaries(
  "A",
  mean = 7.5, n = 120, trunc_adjusted = TRUE
)
identical(as_epidist_estimates_data(estimates), estimates)

Description

This is the only route by which a covariance between a study's reported summaries reaches as_epidist_meta_model(). The covariance comes from draws of the study's parameters, so it is one the study could have computed, and the summaries it covers are fitted with a multivariate normal likelihood rather than as independent observations.

Usage

## S3 method for class 'epidist_multivariate'
as_epidist_estimates_data(
  data,
  study,
  family = NULL,
  moments = c("mean", "sd"),
  probs = numeric(0),
  mvn_id = NULL,
  advise = TRUE,
  ...
)

Arguments

Details

Where family is given, the draws hold the natural parameters of a distribution the study fitted. Each draw is pushed through to the summaries the fitted distribution implies, over the range of delays the study could have seen, and the covariance is taken over those. This is the exact version of the delta method epidist_estimates_parameters() applies, and it needs no linearisation.

Where family is NULL, the parameters must already be quantities a study reports. Name them mean, sd, or q followed by a probability, such as q0.25.

Draws over more than one index point are not yet supported for fitting, because the linear predictor would have to vary within one likelihood observation.

Value

An object of class epidist_estimates_data with one row per reported summary and the covariance matrix attached.

See Also

Other estimates_data: as_epidist_estimates_data(), as_epidist_estimates_data.data.frame(), as_epidist_estimates_data.epidist_estimates_data(), as_epidist_estimates_data.list(), assert_epidist.epidist_estimates_data(), epidist_estimates_epireview(), epidist_estimates_parameters(), epidist_estimates_summaries(), is_epidist_estimates_data(), new_epidist_estimates_data()

Examples

set.seed(1)
draws <- cbind(mean = rnorm(500, 7.5, 0.3), sd = rnorm(500, 3.6, 0.2))
as_epidist_estimates_data(
  as_epidist_multivariate(draws),
  study = "site A",
  trunc_adjusted = TRUE,
  cens_adjusted = 1
)

Description

Each element is coerced on its own and the results are bound into one object. Combining is associative, so contributions can be assembled in any order and in any grouping. The advisory checks of the Checks section of as_epidist_estimates_data.data.frame() run once, on the combined object, so each message names every study it applies to.

Usage

## S3 method for class 'list'
as_epidist_estimates_data(data, advise = TRUE, ...)

Arguments

Value

An object of class epidist_estimates_data holding the rows of every element.

See Also

Other estimates_data: as_epidist_estimates_data(), as_epidist_estimates_data.data.frame(), as_epidist_estimates_data.epidist_estimates_data(), as_epidist_estimates_data.epidist_multivariate(), assert_epidist.epidist_estimates_data(), epidist_estimates_epireview(), epidist_estimates_parameters(), epidist_estimates_summaries(), is_epidist_estimates_data(), new_epidist_estimates_data()

Examples

as_epidist_estimates_data(list(
  epidist_estimates_summaries(
    "A",
    mean = 7.5, sd = 3.6, n = 120, trunc_adjusted = TRUE
  ),
  epidist_estimates_summaries(
    "B",
    mean = 6.9, n = 80, relative_obs_time = 20, trunc_adjusted = FALSE
  )
))

Description

Creates an epidist_latent_model object from various input formats. This enables fitting latent variable models for epidemiological delays using epidist(), as described in Park et al. (2024) and Charniga et al. (2024) The latent model approach accounts for double interval censoring and right truncation in delay data.

Usage

as_epidist_latent_model(data, ...)

Arguments

Value

An object of class epidist_latent_model.

References

• Park et al. (2024) doi:10.1101/2024.01.12.24301247

• Charniga et al. (2024) doi:10.1371/journal.pcbi.1012520

See Also

Other latent_model: as_epidist_latent_model.epidist_aggregate_data(), as_epidist_latent_model.epidist_linelist_data(), epidist_family_model.epidist_latent_model(), epidist_formula_model.epidist_latent_model(), epidist_model_prior.epidist_latent_model(), epidist_newdata.epidist_latent_model(), is_epidist_latent_model(), new_epidist_latent_model()

Description

This method converts aggregate data to a latent model format by first converting it to linelist format using as_epidist_linelist_data.epidist_aggregate_data() and then passing it to as_epidist_latent_model.epidist_linelist_data(). This ensures that the counts in the aggregate data are properly expanded into individual observations before fitting the latent model.

Usage

## S3 method for class 'epidist_aggregate_data'
as_epidist_latent_model(data, primary = .primary_choices(), ...)

Arguments

Value

An object of class epidist_latent_model.

See Also

Other latent_model: as_epidist_latent_model(), as_epidist_latent_model.epidist_linelist_data(), epidist_family_model.epidist_latent_model(), epidist_formula_model.epidist_latent_model(), epidist_model_prior.epidist_latent_model(), epidist_newdata.epidist_latent_model(), is_epidist_latent_model(), new_epidist_latent_model()

Examples

sierra_leone_ebola_data |>
  dplyr::count(date_of_symptom_onset, date_of_sample_tested) |>
  as_epidist_aggregate_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested",
    n = "n"
  ) |>
  as_epidist_latent_model()

Description

This method takes an epidist_linelist_data object and converts it to a format suitable for fitting latent variable models. It calculates key variables needed for the latent variable method described in Park et al. (2024) and Charniga et al. (2024). This approach adjusts for double interval censoring and right truncation in the data.

Usage

## S3 method for class 'epidist_linelist_data'
as_epidist_latent_model(data, primary = .primary_choices(), ...)

Arguments

Value

An object of class epidist_latent_model.

References

• Park et al. (2024) doi:10.1101/2024.01.12.24301247

• Charniga et al. (2024) doi:10.1371/journal.pcbi.1012520

See Also

Other latent_model: as_epidist_latent_model(), as_epidist_latent_model.epidist_aggregate_data(), epidist_family_model.epidist_latent_model(), epidist_formula_model.epidist_latent_model(), epidist_model_prior.epidist_latent_model(), epidist_newdata.epidist_latent_model(), is_epidist_latent_model(), new_epidist_latent_model()

Examples

sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_latent_model()

Description

Creates an epidist_linelist_data object from various input formats. This is useful when working with individual-level data where each row represents a single observation with primary and secondary event times. See the specific methods for details on supported input formats and usage examples.

Usage

as_epidist_linelist_data(data, ...)

Arguments

Value

An object of class epidist_linelist_data.

See Also

Other linelist_data: as_epidist_linelist_data.data.frame(), as_epidist_linelist_data.default(), as_epidist_linelist_data.epidist_aggregate_data(), assert_epidist.epidist_linelist_data(), is_epidist_linelist_data(), new_epidist_linelist_data()

Description

This method takes a data.frame containing event dates (primary/secondary event dates and observation date) and creates an epidist_linelist_data object. This format is useful when working with individual-level data where each row represents a single observation. Internally it converts dates to numeric times relative to the earliest primary event date and uses as_epidist_linelist_data.default() to create the final object. See the other methods for other data input options.

Usage

## S3 method for class 'data.frame'
as_epidist_linelist_data(
  data,
  pdate_lwr = NULL,
  sdate_lwr = NULL,
  pdate_upr = NULL,
  sdate_upr = NULL,
  obs_date = NULL,
  ...
)

Arguments

Value

An object of class epidist_linelist_data.

See Also

Other linelist_data: as_epidist_linelist_data(), as_epidist_linelist_data.default(), as_epidist_linelist_data.epidist_aggregate_data(), assert_epidist.epidist_linelist_data(), is_epidist_linelist_data(), new_epidist_linelist_data()

Examples

sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  )

Description

This method takes vectors of event times (primary/secondary event times and observation time) and creates an epidist_linelist_data object. This format is useful when working with individual-level data where each row represents a single observation. See the other methods for other data input options.

Usage

## Default S3 method:
as_epidist_linelist_data(
  data,
  ptime_upr = NULL,
  stime_lwr = NULL,
  stime_upr = NULL,
  obs_time = NULL,
  ...
)

Arguments

Value

An object of class epidist_linelist_data.

See Also

Other linelist_data: as_epidist_linelist_data(), as_epidist_linelist_data.data.frame(), as_epidist_linelist_data.epidist_aggregate_data(), assert_epidist.epidist_linelist_data(), is_epidist_linelist_data(), new_epidist_linelist_data()

Examples

as_epidist_linelist_data(
  data = c(1, 2, 3),
  ptime_upr = c(2, 3, 4),
  stime_lwr = c(3, 4, 5),
  stime_upr = c(4, 5, 6),
  obs_time = c(5, 6, 7)
)

Description

This method expands an epidist_aggregate_data object into individual observations by uncounting the n column, then converts it to linelist format using as_epidist_linelist_data.data.frame().

Usage

## S3 method for class 'epidist_aggregate_data'
as_epidist_linelist_data(data, ...)

Arguments

Value

An object of class epidist_linelist_data.

See Also

Other linelist_data: as_epidist_linelist_data(), as_epidist_linelist_data.data.frame(), as_epidist_linelist_data.default(), assert_epidist.epidist_linelist_data(), is_epidist_linelist_data(), new_epidist_linelist_data()

Examples

sierra_leone_ebola_data |>
  dplyr::count(date_of_symptom_onset, date_of_sample_tested) |>
  as_epidist_aggregate_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested",
    n = "n"
  ) |>
  as_epidist_linelist_data()

Description

Creates an epidist_marginal_model object from various input formats. This enables fitting marginal models for epidemiological delays using epidist(). The marginal model approach uses the likelihood from the primarycensored package to efficiently handle censoring in both primary and secondary events as well as truncation due to observation times. See the specific methods as_epidist_marginal_model.epidist_linelist_data() and as_epidist_marginal_model.epidist_aggregate_data() for details on supported input formats and usage examples.

Usage

as_epidist_marginal_model(data, ...)

Arguments

Value

An object of class epidist_marginal_model.

See Also

Other marginal_model: as_epidist_marginal_model.epidist_aggregate_data(), as_epidist_marginal_model.epidist_linelist_data(), epidist_family_model.epidist_marginal_model(), epidist_formula_model.epidist_marginal_model(), epidist_newdata.epidist_marginal_model(), epidist_transform_data_model.epidist_marginal_model(), is_epidist_marginal_model(), new_epidist_marginal_model()

Description

This method converts aggregate data to a marginal model format by passing it to as_epidist_marginal_model.epidist_linelist_data() with the n column used as weights. This ensures that the likelihood is weighted by the counts in the aggregate data.

Usage

## S3 method for class 'epidist_aggregate_data'
as_epidist_marginal_model(
  data,
  obs_time_threshold = 2,
  delay_min = NULL,
  primary = .primary_choices(),
  ...
)

Arguments

Value

An object of class epidist_marginal_model.

See Also

Other marginal_model: as_epidist_marginal_model(), as_epidist_marginal_model.epidist_linelist_data(), epidist_family_model.epidist_marginal_model(), epidist_formula_model.epidist_marginal_model(), epidist_newdata.epidist_marginal_model(), epidist_transform_data_model.epidist_marginal_model(), is_epidist_marginal_model(), new_epidist_marginal_model()

Examples

sierra_leone_ebola_data |>
  dplyr::count(date_of_symptom_onset, date_of_sample_tested) |>
  as_epidist_aggregate_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested",
    n = "n"
  ) |>
  as_epidist_marginal_model()

Description

This method converts linelist data to a marginal model format by calculating delays between primary and secondary events, along with observation times and censoring windows. The likelihood used is imported from the primarycensored package which handles censoring in both primary and secondary events as well as truncation due to observation times. In principle, this method should be more accurate and more computationally efficient than the latent model (as_epidist_latent_model()) approach in most settings except when the number of unique strata approaches the number of observations.

Usage

## S3 method for class 'epidist_linelist_data'
as_epidist_marginal_model(
  data,
  obs_time_threshold = 2,
  weight = NULL,
  primary = .primary_choices(),
  delay_min = NULL,
  ...
)

Arguments

Details

The marginal model performs internal aggregation to optimize computational efficiency while preserving all statistical information. If your data already contains repeated observations with identical characteristics, you can use the weight parameter to provide counts of these duplicates. This allows for more efficient data representation without any loss of information.

When a formula is specified in epidist(), the data will be transformed using epidist_transform_data_model.epidist_marginal_model() to prepare it for model fitting. This transformation summarises the data by counting unique combinations of delays, observation times, censoring windows and any variables in the model formula.

Value

An object of class epidist_marginal_model.

See Also

Other marginal_model: as_epidist_marginal_model(), as_epidist_marginal_model.epidist_aggregate_data(), epidist_family_model.epidist_marginal_model(), epidist_formula_model.epidist_marginal_model(), epidist_newdata.epidist_marginal_model(), epidist_transform_data_model.epidist_marginal_model(), is_epidist_marginal_model(), new_epidist_marginal_model()

Examples

sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_marginal_model()

Description

Creates an epidist_meta_model object from individual level data, published summary estimates, or a mix of the two. This enables fitting a single delay distribution to all of the evidence available using epidist().

Usage

as_epidist_meta_model(data = NULL, estimates = NULL, ...)

Arguments

Details

The meta model is experimental. Its interface may still change in future releases.

Individual level rows use the same likelihood as the marginal model (see as_epidist_marginal_model()), imported from the primarycensored package. Summary rows are instead forward modelled. Given the delay distribution, the model works out what the study's own estimation procedure would have converged to, and fits the reported value to that. Published estimates that did not adjust for right truncation, or that treated interval censored data as continuous, can therefore still contribute unbiased information. That holds only where the metadata describing what each study did is correct. It is usually the analyst's judgement rather than something the study reported, so state it explicitly and vary it in a sensitivity analysis. vignette("model") gives the forward model, the sampling likelihoods and the accuracy of the approximations, and vignette("meta") works through a simulated and a real example.

At least one of data and estimates must be supplied. Study level heterogeneity is specified through the brms formula in epidist(), for example mu ~ 1 + (1 | study), rather than through this function. Individual level rows are labelled "individual" in the study column so that they form their own level of any such term.

Value

An object of class epidist_meta_model.

What this means in practice

Summaries that one study computed from the same delays are correlated, so they are fitted jointly. Two are grouped when they agree on every column of as_epidist_estimates_data() other than the summary itself, and a summary supplied with its own se is fitted alone. A study that reported integer date differences (cens_adjusted 0 or 3) is the exception: its mean and standard deviation form one group and its quantiles another. One observation is therefore a group rather than a single reported value, so log_lik() and loo::loo() report per group, and loo only compares fits to the same studies and the same mix of individual and summary rows. Summary rows are evaluated in R for each posterior draw, so both are slow for a fit with many draws and summary rows. Pass ndraws to use fewer draws, as epidist_gen_meta_log_lik() explains. See vignette("faq"). epidist_meta_leave_one_out() asks the study level question instead, refitting with each study held out.

The sampling standard errors are plug in quantities that depend on the parameters, so allow for genuine differences between studies with a term such as mu ~ 1 + (1 | study) rather than relying on them alone. Supply a reported se in as_epidist_estimates_data() for quantiles read off a fitted distribution rather than the empirical data. Where a study reported integer date differences, keep its mean and standard deviation and drop its quantiles. as_epidist_estimates_data() warns for the studies the approximations serve least well, and documents the two settings, max_delay and options(epidist.meta_n_quad = ), that trade accuracy against speed.

Advanced: an estimated growth rate

A summary row tilts its primary event, and weights the follow up of an accrual design, by the growth_rate of its study. Where that rate is NA in as_epidist_estimates_data(), or was given there with a growth_rate_sd, the study estimates it as the pgrowth distributional parameter instead. That is the parameter primary = "expgrowth" estimates from individual level rows, so the two can share it. The model adds pgrowth ~ 0 + study unless a pgrowth formula is given, and epidist_model_prior() sets the priors from the reported rates. Summaries carry little information about the rate on their own, so share the coefficient with rows that do inform it, for example pgrowth ~ 1 with a line list from the same outbreak. vignette("model") gives the details.

See Also

as_epidist_estimates_data() for preparing the summary estimates, and for the checks and the settings the approximations here depend on.

Other meta_model: as_epidist_meta_model.NULL(), as_epidist_meta_model.epidist_aggregate_data(), as_epidist_meta_model.epidist_estimates_data(), as_epidist_meta_model.epidist_linelist_data(), assert_epidist.epidist_meta_model(), epidist_family_model.epidist_meta_model(), epidist_formula_model.epidist_meta_model(), epidist_meta_leave_one_out(), epidist_model_prior.epidist_meta_model(), epidist_newdata.epidist_meta_model(), epidist_transform_data_model.epidist_meta_model(), is_epidist_meta_model(), new_epidist_meta_model()

Description

This method converts aggregate data to a meta model format by passing it to as_epidist_meta_model.epidist_linelist_data() with the n column used as weights.

Usage

## S3 method for class 'epidist_aggregate_data'
as_epidist_meta_model(
  data,
  estimates = NULL,
  obs_time_threshold = 2,
  delay_min = NULL,
  primary = .primary_choices(),
  ...
)

Arguments

Value

An object of class epidist_meta_model.

See Also

Other meta_model: as_epidist_meta_model(), as_epidist_meta_model.NULL(), as_epidist_meta_model.epidist_estimates_data(), as_epidist_meta_model.epidist_linelist_data(), assert_epidist.epidist_meta_model(), epidist_family_model.epidist_meta_model(), epidist_formula_model.epidist_meta_model(), epidist_meta_leave_one_out(), epidist_model_prior.epidist_meta_model(), epidist_newdata.epidist_meta_model(), epidist_transform_data_model.epidist_meta_model(), is_epidist_meta_model(), new_epidist_meta_model()

Examples

sierra_leone_ebola_data |>
  dplyr::count(date_of_symptom_onset, date_of_sample_tested) |>
  as_epidist_aggregate_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested",
    n = "n"
  ) |>
  as_epidist_meta_model()

Description

Allows summary estimates to be passed as the first argument, so that as_epidist_meta_model(estimates) and as_epidist_meta_model(estimates = estimates) are equivalent.

Usage

## S3 method for class 'epidist_estimates_data'
as_epidist_meta_model(data, estimates = NULL, ...)

Arguments

Details

A model built from summaries alone takes no primary argument, because summary rows tilt the primary event by the growth_rate metadata of their study, estimating it only where that is NA or has a growth_rate_sd. Passing one is an error.

Value

An object of class epidist_meta_model.

See Also

Other meta_model: as_epidist_meta_model(), as_epidist_meta_model.NULL(), as_epidist_meta_model.epidist_aggregate_data(), as_epidist_meta_model.epidist_linelist_data(), assert_epidist.epidist_meta_model(), epidist_family_model.epidist_meta_model(), epidist_formula_model.epidist_meta_model(), epidist_meta_leave_one_out(), epidist_model_prior.epidist_meta_model(), epidist_newdata.epidist_meta_model(), epidist_transform_data_model.epidist_meta_model(), is_epidist_meta_model(), new_epidist_meta_model()

Examples

estimates <- as_epidist_estimates_data(
  data.frame(
    study = c("A", "A"),
    type = c("mean", "sd"),
    value = c(7.5, 3.6),
    n = c(120, 120),
    relative_obs_time = c(20, 20),
    trunc_adjusted = c(FALSE, FALSE),
    cens_adjusted = c(0, 0)
  )
)
as_epidist_meta_model(estimates)

Description

Prepares individual level data exactly as as_epidist_marginal_model.epidist_linelist_data() does and then stacks it with any supplied summary estimates.

Usage

## S3 method for class 'epidist_linelist_data'
as_epidist_meta_model(
  data,
  estimates = NULL,
  obs_time_threshold = 2,
  weight = NULL,
  delay_min = NULL,
  primary = .primary_choices(),
  ...
)

Arguments

Value

An object of class epidist_meta_model.

See Also

Other meta_model: as_epidist_meta_model(), as_epidist_meta_model.NULL(), as_epidist_meta_model.epidist_aggregate_data(), as_epidist_meta_model.epidist_estimates_data(), assert_epidist.epidist_meta_model(), epidist_family_model.epidist_meta_model(), epidist_formula_model.epidist_meta_model(), epidist_meta_leave_one_out(), epidist_model_prior.epidist_meta_model(), epidist_newdata.epidist_meta_model(), epidist_transform_data_model.epidist_meta_model(), is_epidist_meta_model(), new_epidist_meta_model()

Examples

sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_meta_model()

Description

Used when no individual level data is available and only the estimates argument is supplied. It takes no primary argument, because summary rows tilt the primary event by the growth_rate metadata of their study, estimating it only where that is NA or has a growth_rate_sd. Passing one is an error.

Usage

## S3 method for class ''NULL''
as_epidist_meta_model(data = NULL, estimates = NULL, ...)

Arguments

Value

An object of class epidist_meta_model.

See Also

Other meta_model: as_epidist_meta_model(), as_epidist_meta_model.epidist_aggregate_data(), as_epidist_meta_model.epidist_estimates_data(), as_epidist_meta_model.epidist_linelist_data(), assert_epidist.epidist_meta_model(), epidist_family_model.epidist_meta_model(), epidist_formula_model.epidist_meta_model(), epidist_meta_leave_one_out(), epidist_model_prior.epidist_meta_model(), epidist_newdata.epidist_meta_model(), epidist_transform_data_model.epidist_meta_model(), is_epidist_meta_model(), new_epidist_meta_model()

Examples

estimates <- as_epidist_estimates_data(
  data.frame(
    study = c("A", "A"),
    type = c("mean", "sd"),
    value = c(7.5, 3.6),
    n = c(120, 120),
    relative_obs_time = c(20, 20),
    trunc_adjusted = c(FALSE, FALSE),
    cens_adjusted = c(0, 0)
  )
)
as_epidist_meta_model(estimates = estimates)

Description

Summarises draws of a set of parameters by their mean vector and covariance matrix. The result is a multivariate normal approximation to whatever the draws describe, and it is the only route by which a covariance between reported quantities reaches as_epidist_meta_model().

Usage

as_epidist_multivariate(draws, ...)

Arguments

Details

The draws may be of any parameters. Posterior draws of a delay mean and standard deviation, of a meanlog and sdlog, or of a shape and a scale all give the same object. Nothing here checks that a parameter is something a study could report, because that only matters when the object is converted with as_epidist_estimates_data().

Draws may also cover a trajectory, with the parameters varying over an index. The elements are then ordered index major and parameter minor, so a mean and an sd over two index points give mean[1], sd[1], mean[2], sd[2]. The order is fixed because the covariance is indexed by it.

There is no method for a vector of individual delays. Resampling delays manufactures a covariance the study never estimated, which is not what this represents.

Value

An object of class epidist_multivariate.

See Also

Other multivariate: as_epidist_multivariate.data.frame(), as_epidist_multivariate.matrix(), assert_epidist.epidist_multivariate(), is_epidist_multivariate(), new_epidist_multivariate(), print.epidist_multivariate(), vcov.epidist_multivariate()

Description

delay_parameter_draws() returns exactly this shape, with a .draw column, a .row column and one column per parameter, so its output can be passed straight in. Add add_summaries() to report the natural scale mean and standard deviation rather than the distributional parameters.

Usage

## S3 method for class 'data.frame'
as_epidist_multivariate(draws, params = NULL, index = NULL, draw = NULL, ...)

Arguments

Value

An object of class epidist_multivariate.

See Also

Other multivariate: as_epidist_multivariate(), as_epidist_multivariate.matrix(), assert_epidist.epidist_multivariate(), is_epidist_multivariate(), new_epidist_multivariate(), print.epidist_multivariate(), vcov.epidist_multivariate()

Examples

set.seed(1)
draws <- data.frame(
  mean = rnorm(500, 7.5, 0.3), sd = rnorm(500, 3.6, 0.2)
)
as_epidist_multivariate(draws)

Description

Rows are draws and columns are parameters, describing a single point.

Usage

## S3 method for class 'matrix'
as_epidist_multivariate(draws, params = NULL, ...)

Arguments

Value

An object of class epidist_multivariate.

See Also

Other multivariate: as_epidist_multivariate(), as_epidist_multivariate.data.frame(), assert_epidist.epidist_multivariate(), is_epidist_multivariate(), new_epidist_multivariate(), print.epidist_multivariate(), vcov.epidist_multivariate()

Examples

set.seed(1)
draws <- cbind(mean = rnorm(500, 7.5, 0.3), sd = rnorm(500, 3.6, 0.2))
as_epidist_multivariate(draws)

Description

Creates an epidist_naive_model object from various input formats. This enables fitting naive models for epidemiological delays using epidist(). The naive model approach ignores censoring and truncation in the data, using only the lower bounds of the intervals as point estimates. This is the simplest approach but may lead to biased estimates if there is substantial censoring or truncation in the data.

Usage

as_epidist_naive_model(data, ...)

Arguments

Value

An object of class epidist_naive_model.

See Also

Other naive_model: as_epidist_naive_model.epidist_aggregate_data(), as_epidist_naive_model.epidist_linelist_data(), epidist_formula_model.epidist_naive_model(), epidist_newdata.epidist_naive_model(), epidist_stancode.epidist_naive_model(), epidist_transform_data_model.epidist_naive_model(), is_epidist_naive_model(), new_epidist_naive_model()

Description

This method converts aggregate data to a naive model format by passing it to as_epidist_naive_model.epidist_linelist_data() with the n column used as weights. This ensures that the likelihood is weighted by the counts in the aggregate data.

Usage

## S3 method for class 'epidist_aggregate_data'
as_epidist_naive_model(data, ...)

Arguments

Value

An object of class epidist_naive_model.

See Also

Other naive_model: as_epidist_naive_model(), as_epidist_naive_model.epidist_linelist_data(), epidist_formula_model.epidist_naive_model(), epidist_newdata.epidist_naive_model(), epidist_stancode.epidist_naive_model(), epidist_transform_data_model.epidist_naive_model(), is_epidist_naive_model(), new_epidist_naive_model()

Examples

sierra_leone_ebola_data |>
  dplyr::count(date_of_symptom_onset, date_of_sample_tested) |>
  as_epidist_aggregate_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested",
    n = "n"
  ) |>
  as_epidist_naive_model()

Description

This method converts linelist data to a naive model format by calculating delays between primary and secondary events to enable model fitting in epidist(). If the input data contains an n column (e.g. from aggregated data), the likelihood will be weighted by these counts.

Usage

## S3 method for class 'epidist_linelist_data'
as_epidist_naive_model(data, weight = NULL, ...)

Arguments

Details

When a formula is specified in epidist(), the data will be transformed using epidist_transform_data_model.epidist_naive_model() to prepare it for model fitting. This transformation summarises the data by counting unique combinations of delays and any variables in the model formula.

The naive model is the simplest approach but ignores censoring and truncation in the data by using only lower bounds as point estimates. For data with substantial censoring or truncation, consider using as_epidist_latent_model() or as_epidist_marginal_model() which properly account for these features.

Value

An object of class epidist_naive_model.

See Also

Other naive_model: as_epidist_naive_model(), as_epidist_naive_model.epidist_aggregate_data(), epidist_formula_model.epidist_naive_model(), epidist_newdata.epidist_naive_model(), epidist_stancode.epidist_naive_model(), epidist_transform_data_model.epidist_naive_model(), is_epidist_naive_model(), new_epidist_naive_model()

Examples

sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_naive_model()

Description

Validation for epidist objects

Usage

assert_epidist(data, ...)

Arguments

Value

NULL invisibly

Description

Assert validity of epidist_aggregate_data objects

Usage

## S3 method for class 'epidist_aggregate_data'
assert_epidist(data, ...)

Arguments

Value

NULL, invisibly. Called for the side effect of validating data.

See Also

Other aggregate_data: as_epidist_aggregate_data(), as_epidist_aggregate_data.data.frame(), as_epidist_aggregate_data.default(), as_epidist_aggregate_data.epidist_linelist_data(), is_epidist_aggregate_data(), new_epidist_aggregate_data()

Examples

sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_aggregate_data() |>
  assert_epidist()

Description

Assert validity of epidist_estimates_data objects

Usage

## S3 method for class 'epidist_estimates_data'
assert_epidist(data, ...)

Arguments

Value

NULL, invisibly. Called for the side effect of validating data.

See Also

Other estimates_data: as_epidist_estimates_data(), as_epidist_estimates_data.data.frame(), as_epidist_estimates_data.epidist_estimates_data(), as_epidist_estimates_data.epidist_multivariate(), as_epidist_estimates_data.list(), epidist_estimates_epireview(), epidist_estimates_parameters(), epidist_estimates_summaries(), is_epidist_estimates_data(), new_epidist_estimates_data()

Description

Assert validity of epidist_linelist_data objects

Usage

## S3 method for class 'epidist_linelist_data'
assert_epidist(data, ...)

Arguments

Value

NULL, invisibly. Called for the side effect of validating data.

See Also

Other linelist_data: as_epidist_linelist_data(), as_epidist_linelist_data.data.frame(), as_epidist_linelist_data.default(), as_epidist_linelist_data.epidist_aggregate_data(), is_epidist_linelist_data(), new_epidist_linelist_data()

Description

Assert validity of epidist_meta_model objects

Usage

## S3 method for class 'epidist_meta_model'
assert_epidist(data, ...)

Arguments

Value

NULL, invisibly. Called for the side effect of validating data.

See Also

Other meta_model: as_epidist_meta_model(), as_epidist_meta_model.NULL(), as_epidist_meta_model.epidist_aggregate_data(), as_epidist_meta_model.epidist_estimates_data(), as_epidist_meta_model.epidist_linelist_data(), epidist_family_model.epidist_meta_model(), epidist_formula_model.epidist_meta_model(), epidist_meta_leave_one_out(), epidist_model_prior.epidist_meta_model(), epidist_newdata.epidist_meta_model(), epidist_transform_data_model.epidist_meta_model(), is_epidist_meta_model(), new_epidist_meta_model()

Description

Assert validity of epidist_multivariate objects

Usage

## S3 method for class 'epidist_multivariate'
assert_epidist(data, ...)

Arguments

Value

NULL, invisibly. Called for the side effect of validating data.

See Also

Other multivariate: as_epidist_multivariate(), as_epidist_multivariate.data.frame(), as_epidist_multivariate.matrix(), is_epidist_multivariate(), new_epidist_multivariate(), print.epidist_multivariate(), vcov.epidist_multivariate()

Description

Returns posterior draws of the parameters of the delay distribution in the long format used by tidybayes. The delay parameters are the distributional parameters of the brms family, evaluated on the response scale for each row of newdata. For a lognormal model they are mu and sigma. They are the parameters of the delay distribution itself, so they do not describe the censoring or truncation of the observation process, and they are not the natural scale mean and standard deviation of the delay. Use add_summaries() to add those.

add_delay_parameter_draws() is the same function with newdata first, for use at the start of a pipeline as with tidybayes::add_epred_draws().

Usage

delay_parameter_draws(object, newdata = NULL, ...)

add_delay_parameter_draws(newdata, object, ...)

Arguments

Details

The returned columns follow the tidybayes conventions. The columns of newdata come first, followed by .row, .chain, .iteration and .draw, followed by one column per distributional parameter. The result is grouped by the columns of newdata and by .row. .chain and .iteration are NA when the draws have been subset, because the chain a subset draw came from is not recoverable.

Every row of newdata gets its own draws, so passing the data the model was fitted to produces many identical draws when the model has few unique combinations of predictors. epidist_strata() returns one row per unique combination and is usually the better input.

Value

A tibble of posterior draws of the delay distribution parameters, grouped by the columns of newdata and by .row. It has the epidist_delay_draws class, which records the delay distribution family and gives it a plot() method.

See Also

add_summaries() to add natural scale summaries of the delay, epidist_strata() to build newdata, and plot.epidist_delay_draws() to plot the draws.

Other postprocess: add_summaries(), as_dist_spec.epidist_fit(), delay_summary_draws(), epidist_delay_draws, epidist_strata()

Examples

fit <- sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_aggregate_data() |>
  as_epidist_marginal_model() |>
  epidist(chains = 2, cores = 2, refresh = ifelse(interactive(), 250, 0))

fit |>
  epidist_strata() |>
  add_delay_parameter_draws(fit) |>
  add_summaries(probs = c(0.05, 0.95))

Description

The usual last step of a fit. Builds one row per unique combination of the predictors with epidist_strata(), draws the delay distribution parameters for each with delay_parameter_draws(), and adds the natural scale mean and standard deviation, and any quantiles asked for, with add_summaries().

Each of those three steps is available on its own where a step needs different arguments, or where newdata is built some other way.

Usage

delay_summary_draws(
  object,
  newdata = NULL,
  vars = NULL,
  probs = NULL,
  method = c("auto", "analytic", "sample"),
  nsim = 1000,
  ...
)

Arguments

Value

A tibble of posterior draws of the delay distribution parameters with mean and sd columns added, and one column per element of probs. Grouped as delay_parameter_draws() returns it.

See Also

delay_parameter_draws() for the parameters alone, add_summaries() to summarise draws you already have, and epidist_strata() to build newdata.

Other postprocess: add_summaries(), as_dist_spec.epidist_fit(), delay_parameter_draws(), epidist_delay_draws, epidist_strata()

Examples

fit <- sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_aggregate_data() |>
  as_epidist_marginal_model() |>
  epidist(chains = 2, cores = 2, refresh = ifelse(interactive(), 250, 0))

delay_summary_draws(fit, probs = c(0.05, 0.95))

Description

Fit epidemiological delay distributions using a brms interface

Usage

epidist(
  data,
  formula = mu ~ 1,
  family = lognormal(),
  prior = NULL,
  merge_priors = TRUE,
  fn = brms::brm,
  ...
)

Arguments

Value

A fitted model of class epidist_fit.

Examples

fit <- sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_aggregate_data() |>
  as_epidist_marginal_model() |>
  epidist(chains = 2, cores = 2, refresh = ifelse(interactive(), 250, 0))

summary(fit)

Description

Every epidist data object also carries the epidist_data class. The methods documented here re-check an object after it has been modified and drop any epidist class whose requirements the modified object no longer meets, warning about what was dropped and why. An object that still carries an epidist class is therefore a valid object of that class, so functions which accept one do not need to re-check it.

Usage

## S3 method for class 'epidist_data'
x[...]

## S3 replacement method for class 'epidist_data'
x[...] <- value

## S3 replacement method for class 'epidist_data'
x[[...]] <- value

## S3 replacement method for class 'epidist_data'
x$... <- value

## S3 replacement method for class 'epidist_data'
names(x) <- value

## S3 method for class 'epidist_data'
rbind(..., deparse.level = 1)

## S3 method for class 'epidist_data'
dplyr_reconstruct(data, template)

## S3 method for class 'epidist_data'
dplyr_row_slice(data, i, ...)

## S3 method for class 'epidist_data'
dplyr_col_modify(data, cols)

## S3 method for class 'epidist_data'
group_by(.data, ..., .add = FALSE, .drop = dplyr::group_by_drop_default(.data))

## S3 method for class 'epidist_data'
ungroup(x, ...)

Arguments

Details

Methods are provided for base subsetting and replacement, and for dplyr::dplyr_reconstruct(), which dplyr verbs such as dplyr::mutate(), dplyr::filter() and dplyr::select() use to restore the class of their input. dplyr::group_by() and dplyr::ungroup() build a new tibble rather than restoring the class of their input, as do the grouped_df methods for dplyr::dplyr_row_slice() and dplyr::dplyr_col_modify(), so each has a method of its own that puts the classes back. A grouped object keeps the grouped_df class after the epidist classes, and the dplyr verbs keep both. dplyr::summarise() builds a new object from the groups rather than modifying its input, so its result does not carry the epidist classes.

A result with no columns is unclassed without a warning. Such a result is almost always the prototype vctrs takes internally, in dplyr::bind_cols() for example, rather than something the user asked for, and it cannot be told apart from a deliberate empty selection.

Value

The modified object with any epidist class whose requirements it no longer meets removed.

See Also

Other epidist_data: is_epidist_data()

Examples

linelist_data <- sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  )

# Subsetting rows keeps the class
class(linelist_data[1:10, ])

# Dropping a required column drops the class
class(dplyr::select(linelist_data, -"obs_time"))

# Grouping keeps the class alongside the grouped_df class
class(dplyr::group_by(linelist_data, obs_time))

Description

The epidist_delay_draws class records the delay distribution family and the variables that define the strata, which add_summaries() and plot.epidist_delay_draws() read. Most dplyr verbs build a new object rather than keeping the class of their input, so the methods documented here put the class and what it records back.

Usage

## S3 method for class 'epidist_delay_draws'
x[...]

## S3 replacement method for class 'epidist_delay_draws'
names(x) <- value

## S3 method for class 'epidist_delay_draws'
dplyr_reconstruct(data, template)

## S3 method for class 'epidist_delay_draws'
dplyr_row_slice(data, i, ...)

## S3 method for class 'epidist_delay_draws'
dplyr_col_modify(data, cols)

## S3 method for class 'epidist_delay_draws'
group_by(.data, ..., .add = FALSE, .drop = dplyr::group_by_drop_default(.data))

## S3 method for class 'epidist_delay_draws'
ungroup(x, ...)

Arguments

Details

Methods are provided for base subsetting and renaming, and for dplyr::dplyr_reconstruct(), which verbs such as dplyr::mutate() and dplyr::bind_rows() use to restore the class of their input. dplyr::group_by() and dplyr::ungroup() build a new tibble rather than restoring the class of their input, as do the grouped_df methods for dplyr::dplyr_row_slice() and dplyr::dplyr_col_modify(), so each has a method of its own that puts the class back. A grouped object keeps the epidist_delay_draws class ahead of grouped_df, and the dplyr verbs keep both. dplyr::summarise() builds a new object from the groups rather than modifying its input, so its result does not carry the class.

dplyr::bind_rows() restores the class from its first argument, so combining draws keeps the family and the stratum variables of the first set of draws. Combining draws from two fits of different families therefore describes the result by the family of the first. Pass the family to add_summaries() or plot() with the family argument when the draws combined are not all from the same family.

Value

The modified object with the epidist_delay_draws class, and the family and stratum variables it records, put back.

See Also

Other postprocess: add_summaries(), as_dist_spec.epidist_fit(), delay_parameter_draws(), delay_summary_draws(), epidist_strata()

Examples

draws <- data.frame(mu = c(1.8, 2.0), sigma = c(0.5, 0.4)) |>
  add_summaries(family = "lognormal")

# Adding a column keeps the class
class(dplyr::mutate(draws, model = "a"))

# Combining two sets of draws keeps the class
class(dplyr::bind_rows(draws, draws))

Description

This function computes diagnostics to assess the quality of a fitted model. When the fitting algorithm used is "sampling" (HMC) then the output of epidist_diagnostics is a data.frame containing:

• time: the total time taken to fit all chains

• samples: the total number of samples across all chains

• max_rhat: the highest value of the Gelman-Rubin statistic

• divergent_transitions: the total number of divergent transitions

• per_divergent_transitions: the proportion of samples which had divergent transitions

• max_treedepth: the highest value of the treedepth HMC parameter

• no_at_max_treedepth: the number of samples which attained the max_treedepth

• per_at_max_treedepth: the proportion of samples which attained the max_treedepth

Usage

epidist_diagnostics(fit)

Arguments

Details

When the fitting algorithm is not "sampling" (see brms::brm() for other possible algorithms) then diagnostics are yet to be implemented.

Value

A data.frame of summary diagnostics for the fit.

Examples

fit <- sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_aggregate_data() |>
  as_epidist_marginal_model() |>
  epidist(chains = 2, cores = 2, refresh = ifelse(interactive(), 250, 0))
epidist_diagnostics(fit)

Description

Maps a table of published delay estimates from the epireview package, one row per reported estimate, to the long format as_epidist_estimates_data() takes, and returns the epidist_estimates_data object it builds. epireview collates the parameter estimates gathered by the Pathogen Epidemiology Review Group. It is not on CRAN, and is installed from the mrc-ide r-universe. Filter the params table of epireview::load_epidata() to one delay before passing it here, because the rows of one object all describe the same delay.

Usage

epidist_estimates_epireview(
  data,
  study = "article_label",
  metadata = NULL,
  keep = NULL,
  advise = TRUE,
  ...
)

Arguments

Value

An epidist_estimates_data object.

What each record becomes

A record is mapped by its parameter_value_type.

• A "Mean" becomes a "mean" row. A "Standard Deviation" in parameter_uncertainty_singe_type becomes a matching "sd" row, as does the second parameter of a fitted distribution that epireview records as a mean and a standard deviation. A "Standard Error" becomes the se of the mean row instead, and so does a 95% confidence or credible interval of the mean, as its width over 2 * qnorm(0.975).

• A "Median" becomes a "quantile" row at p = 0.5, with further rows at p = 0.25 and p = 0.75 where parameter_uncertainty_type is "IQR".

• A record whose distribution_type is a gamma, a Weibull or a lognormal reported by its natural parameters (a shape with a scale or a rate, or a meanlog with a sdlog) becomes the mean and standard deviation the fitted distribution implies over the delays the study could have seen, as epidist_estimates_parameters() computes them. Its reported value and spread are not used again, because they are functions of the same parameters. epireview records no uncertainty for the parameters, so the rows take their sampling uncertainty from the sample size.

A range is the smallest and largest delay a study saw rather than a summary of the distribution, and is not used. A spread that does not match the value type, such as a standard deviation reported alongside a median, is not used either, because the two kinds of summary from a study that reported integer date differences are fitted as though they were independent.

Records that cannot be mapped are dropped with a message naming them. These are records reporting an inverse rate, units other than days, a value with a scaling exponent, no mean or median and no usable distribution parameters, and records left with no sample size and no standard error. Fill a missing sample size through metadata.

Several records may share a study, for example estimates stratified by outbreak or by group, and they are then fitted as separate summaries of the same study.

Study metadata

epireview does not record how a study handled censoring or right truncation, its censoring windows or its observation time. Give the metadata that applies to every record through ..., and the metadata that differs by study through metadata, a data frame with one row per study whose values replace those of ... for that study's records. Anything given for neither is assumed as as_epidist_estimates_data() assumes it, with the same messages, and a study that metadata leaves blank for a column it holds is assumed in the same way and named. The Checks section of as_epidist_estimates_data.data.frame() says which assumptions matter most.

The result is an epidist_estimates_data object, so metadata learnt later can be edited in with dplyr::mutate() or ⁠[<-⁠. The object is checked again after each change and drops its class if the change breaks a requirement, so make related changes, such as setting trunc_adjusted to FALSE and giving the relative_obs_time it then needs, in one call. See epidist_data.

See Also

Other estimates_data: as_epidist_estimates_data(), as_epidist_estimates_data.data.frame(), as_epidist_estimates_data.epidist_estimates_data(), as_epidist_estimates_data.epidist_multivariate(), as_epidist_estimates_data.list(), assert_epidist.epidist_estimates_data(), epidist_estimates_parameters(), epidist_estimates_summaries(), is_epidist_estimates_data(), new_epidist_estimates_data()

Examples

# A table with the columns epireview uses
records <- data.frame(
  article_label = c("A 2015", "B 2016", "B 2016"),
  parameter_value = c(10.6, 14, 8.9),
  parameter_value_type = c("Mean", "Median", "Mean"),
  parameter_unit = "Days",
  parameter_uncertainty_single_value = c(3.2, NA, NA),
  parameter_uncertainty_singe_type = c("Standard Deviation", NA, NA),
  parameter_uncertainty_lower_value = c(NA, 11, NA),
  parameter_uncertainty_upper_value = c(NA, 15, NA),
  parameter_uncertainty_type = c(NA, "IQR", NA),
  population_sample_size = c(76, 20, 92)
)
epidist_estimates_epireview(
  records,
  metadata = data.frame(
    study = "A 2015", relative_obs_time = 60, trunc_adjusted = FALSE
  ),
  trunc_adjusted = TRUE,
  cens_adjusted = 0
)

Description

Studies often publish the parameters of a distribution they fitted rather than summaries of the delays themselves. This converts those parameters into the summaries the fitted distribution implies, which is what as_epidist_meta_model() fits to.

Usage

epidist_estimates_parameters(
  study,
  family,
  parameters,
  moments = c("mean", "sd"),
  probs = numeric(0),
  se = NULL,
  n = NULL,
  ...
)

Arguments

Value

An epidist_estimates_data object.

What the reported parameters are taken to mean

The reported parameters describe the distribution the study's own estimation procedure converged to. Where the procedure was correct, that is the delay distribution itself. Where it was not, it is the biased distribution the procedure targeted, which is exactly what the meta model forward models from the study metadata. Converting to summaries therefore covers both cases with one route, and the study metadata documented in as_epidist_estimates_data.data.frame() is supplied in the same way as for any other summary.

Because the returned rows are summaries, the family the study fitted need not match the family being fitted to it. A study reporting a gamma can be used in a lognormal meta model. Parameters are never compared across families, which would be meaningless. For a two parameter family the map from parameters to a mean and a standard deviation is one to one, so a study that fitted correctly loses nothing by being converted.

What this does assume is that summaries of the study's reported distribution are the summaries of what its procedure targeted. That holds exactly when the study reported a distribution of the same shape as its estimand, and approximately otherwise, for example where a study fitted a continuous distribution to integer date differences.

The range the summaries are taken over

A study that did not correct for right truncation fitted a distribution to delays that stop at its observation time, but the families studies fit have a tail running past that point. Taking the reported distribution's summaries over its whole support would then charge it with spread its data never had, which is worst for a standard deviation and can reach tens of percent for a short observation time.

Summaries are therefore taken over the range of delays the study could have seen, conditioning the reported distribution on falling between delay_min and relative_obs_time. This is the same range the meta model computes its implied summaries over, so the two sides are the same functional of the two distributions. Both fields are read from the metadata passed through ..., and a study that adjusted for right truncation is left unconditioned above. A reported quantile at probability p is the value the conditioned distribution puts p below, so it too stays inside the observed range.

Where the study fitted a family that cannot represent its own estimand, quantiles inside the body of the distribution are more reliable than a standard deviation, which depends on a tail the study never saw.

Uncertainty

Supply the standard errors the study reported on its parameters through se. They are carried onto the summary scale by the delta method, using a numerical Jacobian of the map from parameters to summaries, and the summaries are reported with the covariance matrix that implies between them, so they are fitted jointly as a multivariate normal in the same way as the output of as_epidist_multivariate(). For a fit with as many summaries as parameters this carries the study's information about its parameters exactly, which fitting each summary with its own standard error would not.

Summaries of a two parameter fit are deterministic functions of two numbers, so at most two of them can carry the reported uncertainty, and asking for more with se is an error. A study that published a full parameter covariance rather than standard errors can draw from it, push each draw through to the summaries, and use as_epidist_multivariate(), which needs no linearisation.

Without se the summaries fall back to the sample size likelihoods, which derive their sampling uncertainty from n, and any number of them may be reported.

See Also

Other estimates_data: as_epidist_estimates_data(), as_epidist_estimates_data.data.frame(), as_epidist_estimates_data.epidist_estimates_data(), as_epidist_estimates_data.epidist_multivariate(), as_epidist_estimates_data.list(), assert_epidist.epidist_estimates_data(), epidist_estimates_epireview(), epidist_estimates_summaries(), is_epidist_estimates_data(), new_epidist_estimates_data()

Examples

epidist_estimates_parameters(
  "study A",
  family = "gamma",
  parameters = c(shape = 4.1, rate = 0.55),
  se = c(0.4, 0.06),
  relative_obs_time = 20,
  trunc_adjusted = FALSE,
  cens_adjusted = 0
)

Description

Builds the rows as_epidist_meta_model() takes from the summaries a study published in wide form, one argument per kind of summary.

Usage

epidist_estimates_summaries(
  study,
  mean = NULL,
  sd = NULL,
  quantiles = NULL,
  probs = NULL,
  se = NULL,
  n = NULL,
  ...
)

Arguments

Details

Give the uncertainty of each summary through se, or the number of delays the study summarised through n, which the model uses to derive a sampling uncertainty instead. One of the two is needed for every row.

Value

An epidist_estimates_data object.

See Also

Other estimates_data: as_epidist_estimates_data(), as_epidist_estimates_data.data.frame(), as_epidist_estimates_data.epidist_estimates_data(), as_epidist_estimates_data.epidist_multivariate(), as_epidist_estimates_data.list(), assert_epidist.epidist_estimates_data(), epidist_estimates_epireview(), epidist_estimates_parameters(), is_epidist_estimates_data(), new_epidist_estimates_data()

Examples

epidist_estimates_summaries(
  "study A",
  mean = 7.5, sd = 3.6, n = 120,
  relative_obs_time = 20, trunc_adjusted = FALSE, cens_adjusted = 0
)

Description

This function is used within epidist() to create a model specific custom brms family object. This custom family is passed to brms. It is unlikely that as a user you will need this function, but we export it nonetheless to be transparent about what happens inside of a call to epidist().

Usage

epidist_family(data, family = lognormal(), ...)

Arguments

Details

The family may be any brms family of a positive response, such as brms::lognormal(), Gamma(link = "log") or brms::weibull(), or a family epidist defines itself, such as gengamma().

Value

A brms custom family object.

See Also

Other family: epidist_family_model(), epidist_family_model.default(), epidist_family_param(), epidist_family_param.default(), epidist_family_param.gengamma(), gengamma()

Examples

data <- sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_aggregate_data() |>
  as_epidist_marginal_model()
family <- epidist_family(data, family = lognormal())
family

Description

The model-specific parts of an epidist_family() call

Usage

epidist_family_model(data, family, ...)

Arguments

Value

A brms custom family object.

See Also

Other family: epidist_family(), epidist_family_model.default(), epidist_family_param(), epidist_family_param.default(), epidist_family_param.gengamma(), gengamma()

Description

Default method for defining a model specific family

Usage

## Default S3 method:
epidist_family_model(data, family, ...)

Arguments

Value

A brms custom family object.

See Also

Other family: epidist_family(), epidist_family_model(), epidist_family_param(), epidist_family_param.default(), epidist_family_param.gengamma(), gengamma()

Description

Create the model-specific component of an epidist custom family

Usage

## S3 method for class 'epidist_latent_model'
epidist_family_model(data, family, ...)

Arguments

Value

A brms custom family object.

See Also

Other latent_model: as_epidist_latent_model(), as_epidist_latent_model.epidist_aggregate_data(), as_epidist_latent_model.epidist_linelist_data(), epidist_formula_model.epidist_latent_model(), epidist_model_prior.epidist_latent_model(), epidist_newdata.epidist_latent_model(), is_epidist_latent_model(), new_epidist_latent_model()

Description

Create the model-specific component of an epidist custom family

Usage

## S3 method for class 'epidist_marginal_model'
epidist_family_model(data, family, ...)

Arguments

Value

A brms custom family object.

See Also

Other marginal_model: as_epidist_marginal_model(), as_epidist_marginal_model.epidist_aggregate_data(), as_epidist_marginal_model.epidist_linelist_data(), epidist_formula_model.epidist_marginal_model(), epidist_newdata.epidist_marginal_model(), epidist_transform_data_model.epidist_marginal_model(), is_epidist_marginal_model(), new_epidist_marginal_model()

Description

Create the model-specific component of an epidist custom family

Usage

## S3 method for class 'epidist_meta_model'
epidist_family_model(data, family, ...)

Arguments

Value

A brms custom family object.

See Also

Other meta_model: as_epidist_meta_model(), as_epidist_meta_model.NULL(), as_epidist_meta_model.epidist_aggregate_data(), as_epidist_meta_model.epidist_estimates_data(), as_epidist_meta_model.epidist_linelist_data(), assert_epidist.epidist_meta_model(), epidist_formula_model.epidist_meta_model(), epidist_meta_leave_one_out(), epidist_model_prior.epidist_meta_model(), epidist_newdata.epidist_meta_model(), epidist_transform_data_model.epidist_meta_model(), is_epidist_meta_model(), new_epidist_meta_model()

Description

This function extracts the Stan parameterisation for a given brms family by creating a dummy model and parsing its Stan code. It looks for the log probability density function (lpdf) call in the Stan code and extracts the parameter order used by Stan. This is needed because brms and Stan may use different parameter orderings for the same distribution.

Usage

## Default S3 method:
epidist_family_param(family, ...)

Arguments

Details

The function works by:

1. Creating a minimal dummy model using the specified family

2. Extracting the Stan code for this model

3. Finding the lpdf function call for the family

4. Parsing out the parameter ordering used in Stan

5. Adding this as the param element to the family object

Value

The input family object with an additional param element containing the Stan parameter ordering as a string

See Also

Other family: epidist_family(), epidist_family_model(), epidist_family_model.default(), epidist_family_param(), epidist_family_param.gengamma(), gengamma()

Method for the gengamma() family

Description

The latent and naive models call the Stan density in the order brms declares the parameters. The marginal and meta models pass pcd_param, the Stacy form primarycensored takes.

Usage

## S3 method for class 'gengamma'
epidist_family_param(family, ...)

Arguments

Value

The family with param and pcd_param elements.

See Also

Other family: epidist_family(), epidist_family_model(), epidist_family_model.default(), epidist_family_param(), epidist_family_param.default(), gengamma()

Description

This function contains brms prior distributions which are specific to particular likelihood families e.g. brms::lognormal().

Usage

epidist_family_prior(family, ...)

Arguments

Value

A brmsprior object, or NULL when the model adds no priors.

See Also

Other prior: epidist_family_prior.default(), epidist_family_prior.gengamma(), epidist_family_prior.lognormal(), epidist_model_prior(), epidist_model_prior.default(), epidist_model_prior.epidist_meta_model(), epidist_prior()

Description

By default, we do not return any family specific prior distributions.

Usage

## Default S3 method:
epidist_family_prior(family, formula, ...)

Arguments

Value

A brmsprior object, or NULL when the model adds no priors.

See Also

Other prior: epidist_family_prior(), epidist_family_prior.gengamma(), epidist_family_prior.lognormal(), epidist_model_prior(), epidist_model_prior.default(), epidist_model_prior.epidist_meta_model(), epidist_prior()

Description

mu and sigma get the intercept priors of the lognormal family. The intercept of Q, on the log scale, gets normal(0, 0.5), centred on the Weibull case.

Usage

## S3 method for class 'gengamma'
epidist_family_prior(family, formula, ...)

Arguments

Value

A brmsprior object.

See Also

Other prior: epidist_family_prior(), epidist_family_prior.default(), epidist_family_prior.lognormal(), epidist_model_prior(), epidist_model_prior.default(), epidist_model_prior.epidist_meta_model(), epidist_prior()

Description

We suggest priors to overwrite the brms defaults for the lognormal family.

Usage

## S3 method for class 'lognormal'
epidist_family_prior(family, formula, ...)

Arguments

Value

A brmsprior object, or NULL when the model adds no priors.

See Also

Other prior: epidist_family_prior(), epidist_family_prior.default(), epidist_family_prior.gengamma(), epidist_model_prior(), epidist_model_prior.default(), epidist_model_prior.epidist_meta_model(), epidist_prior()

Description

This function is used within epidist() to create the formula object passed to brms. It is unlikely that as a user you will need this function, but we export it nonetheless to be transparent about what exactly is happening inside of a call to epidist().

Usage

epidist_formula(data, family, formula, ...)

Arguments

Value

A brmsformula object.

See Also

Other formula: epidist_formula_model(), epidist_formula_model.default()

Examples

data <- sierra_leone_ebola_data |>
  as_epidist_linelist_data(
    pdate_lwr = "date_of_symptom_onset",
    sdate_lwr = "date_of_sample_tested"
  ) |>
  as_epidist_aggregate_data() |>
  as_epidist_marginal_model()
family <- epidist_family(data, family = lognormal())
formula <- epidist_formula(data, family = family, formula = mu ~ 1)
formula

Description

The model-specific parts of an epidist_formula() call

Usage

epidist_formula_model(data, formula, ...)

Arguments

Value

A brmsformula object.

See Also

Other formula: epidist_formula(), epidist_formula_model.default()

Description

Default method for defining a model specific formula

Usage

## Default S3 method:
epidist_formula_model(data, formula, ...)

Arguments

Value

A brmsformula object.

See Also

Other formula: epidist_formula(), epidist_formula_model()

Description

Define the model-specific component of an epidist custom formula for the latent model

Usage

## S3 method for class 'epidist_latent_model'
epidist_formula_model(data, formula, ...)

Arguments

Value

A brmsformula object.

See Also

Other latent_model: as_epidist_latent_model(), as_epidist_latent_model.epidist_aggregate_data(), as_epidist_latent_model.epidist_linelist_data(), epidist_family_model.epidist_latent_model(), epidist_model_prior.epidist_latent_model(), epidist_newdata.epidist_latent_model(), is_epidist_latent_model(), new_epidist_latent_model()

Description

Define the model-specific component of an epidist custom formula for the marginal model

Usage

## S3 method for class 'epidist_marginal_model'
epidist_formula_model(data, formula, ...)

Arguments

Value

A brmsformula object.

See Also

Other marginal_model: as_epidist_marginal_model(), as_epidist_marginal_model.epidist_aggregate_data(), as_epidist_marginal_model.epidist_linelist_data(), epidist_family_model.epidist_marginal_model(), epidist_newdata.epidist_marginal_model(), epidist_transform_data_model.epidist_marginal_model(), is_epidist_marginal_model(), new_epidist_marginal_model()

Description

Adds the response and the slots of the meta model to the formula. Where a summary row estimates its growth rate as the pgrowth distributional parameter, see as_epidist_meta_model(), and the formula has no term for pgrowth, pgrowth ~ 0 + study is added so that each study has its own rate and the priors epidist_model_prior() builds from the reported rates have a coefficient to act on. Data holding a single study get pgrowth ~ 1 instead, because brms cannot code a factor with one level. A pgrowth formula given by the user is kept as it is.

Usage

## S3 method for class 'epidist_meta_model'
epidist_formula_model(data, formula, ...)

Arguments

Value

A brmsformula object.

See Also

Other meta_model: as_epidist_meta_model(), as_epidist_meta_model.NULL(), as_epidist_meta_model.epidist_aggregate_data(), as_epidist_meta_model.epidist_estimates_data(), as_epidist_meta_model.epidist_linelist_data(), assert_epidist.epidist_meta_model(), epidist_family_model.epidist_meta_model(), epidist_meta_leave_one_out(), epidist_model_prior.epidist_meta_model(), epidist_newdata.epidist_meta_model(), epidist_transform_data_model.epidist_meta_model(), is_epidist_meta_model(), new_epidist_meta_model()

Description

Define the model-specific component of an epidist custom formula for the naive model

Usage

## S3 method for class 'epidist_naive_model'
epidist_formula_model(data, formula, ...)

Arguments

Value

A brmsformula object.

See Also

Other naive_model: as_epidist_naive_model(), as_epidist_naive_model.epidist_aggregate_data(), as_epidist_naive_model.epidist_linelist_data(), epidist_newdata.epidist_naive_model(), epidist_stancode.epidist_naive_model(), epidist_transform_data_model.epidist_naive_model(), is_epidist_naive_model(), new_epidist_naive_model()

Description

This function creates a log likelihood function that calculates the marginal likelihood for a single observation by integrating over the latent primary and secondary event windows. Where analytical solutions exist in primarycensored::dpcens() these are used, otherwise the integration is performed numerically. primarycensored::dpcens() handles the double censoring and truncation of the delay distribution.

Usage

epidist_gen_log_lik(family)

Arguments

Details

The marginal likelihood accounts for uncertainty in both the primary and secondary event windows by integrating over their possible values, weighted by their respective uniform distributions.

Value

A function that calculates the marginal log likelihood for a single observation. The prep object must have the following variables:

• vreal1: relative observation time

• vreal2: primary event window

• vreal3: secondary event window

• vreal4: delay upper bound

• vreal5: minimum delay (left truncation point; defaults to 0 if absent)

See Also

brms::log_lik() for details on the brms log likelihood interface.

Other gen: epidist_gen_meta_log_lik(), epidist_gen_meta_predict(), epidist_gen_posterior_epred(), epidist_gen_posterior_predict()

Description

Individual level rows use the marginal model log likelihood created by epidist_gen_log_lik(). Summary rows use the sampling distributions described in as_epidist_meta_model(), evaluated at the implied summaries for each posterior draw. A row that stands for several summaries reported by one study returns the joint log likelihood of all of them, so an observation here is a group of summaries rather than a single reported value.

Usage

epidist_gen_meta_log_lik(family)

Arguments

Details

Summary rows are evaluated in R, one posterior draw at a time, and each evaluation can run a quadrature of up to 2000 intervals by default. The cost of brms::log_lik() and loo::loo() therefore grows with the number of draws times the number of summary rows. Pass ndraws to either to use fewer draws, at the price of noisier estimates.

Value

A function that calculates the log likelihood for a single observation. The prep object must have the meta model vint and vreal slots.

See Also

brms::log_lik() for details on the brms log likelihood interface.

Other gen: epidist_gen_log_lik(), epidist_gen_meta_predict(), epidist_gen_posterior_epred(), epidist_gen_posterior_predict()

Description

Individual level rows are predicted as in the marginal model using epidist_gen_posterior_predict(). For summary rows the predicted quantity is the reported summary itself, that is a simulated reported mean, standard deviation, or, for quantile rows, cumulative probability at the reported value. A row that stands for several summaries reported by one study predicts the first of them, drawn from its marginal. Predictions for summary rows are therefore not on the delay scale and should not be compared directly with individual level predictions. They come from the normal approximations described in as_epidist_meta_model(), so a predicted cumulative probability for a quantile row can fall outside [0, 1] when the study sample size is small.

Usage

epidist_gen_meta_predict(family)

Arguments

Value

A function that takes a prep argument from brms and returns a matrix of posterior predictions.

See Also

brms::posterior_predict() for details on how this is used within brms.

Other gen: epidist_gen_log_lik(), epidist_gen_meta_log_lik(), epidist_gen_posterior_epred(), epidist_gen_posterior_predict()

Description

This function creates a function that calculates the expected value of the posterior predictive distribution for a latent model. The returned function takes a prep argument (from brms) and returns posterior expected values. This is used internally by brms::posterior_epred() to calculate expected values for latent models.

Usage

epidist_gen_posterior_epred(family)

Arguments

Value

A function that takes a prep argument from brms and returns a matrix of posterior expected values, with one row per posterior draw and one column per observation.

See Also

brms::posterior_epred() for details on how this is used within brms.

Other gen: epidist_gen_log_lik(), epidist_gen_meta_log_lik(), epidist_gen_meta_predict(), epidist_gen_posterior_predict()

Description

This function creates a function that draws from the posterior predictive distribution for a latent model using primarycensored::rpcens() to handle censoring and truncation. The returned function takes a prep argument from brms and returns posterior predictions. This is used internally by brms::posterior_predict() to generate predictions for latent models.

Usage

epidist_gen_posterior_predict(family)

Arguments

Value

A function that takes a prep argument from brms and returns a matrix of posterior predictions, with one row per posterior draw and one column per observation. The prep object must have the following variables:

• vreal1: relative observation time

• vreal2: primary event window

• vreal3: secondary event window

• vreal4: delay upper bound

• vreal5: minimum delay (left truncation point; defaults to 0 if absent)

See Also

brms::posterior_predict() for details on how this is used within brms, primarycensored::rpcens() for details on the censoring approach

Other gen: epidist_gen_log_lik(), epidist_gen_meta_log_lik(), epidist_gen_meta_predict(), epidist_gen_posterior_epred()

Description

Refits a meta model once per study with that study removed, and compares the delay mean and standard deviation of each refit with the full fit.

Usage

epidist_meta_leave_one_out(
  fit,
  data = NULL,
  newdata = NULL,
  re_formula = NA,
  width = 0.95,
  keep_fits = FALSE,
  studies = NULL,
  cores = NULL,
  ...
)

Arguments

Details

Individual level rows are held out together as the "individual" study. If the formula does not use study, pass the epidist_meta_model object as data, because brms drops unused variables from fit$data. Each refit reuses the compiled model through brms::update.brmsfit(). The refits are exact because Pareto smoothed importance sampling (Vehtari et al. 2017) is often unreliable when a whole study is left out.

The comparison is reported as estimates with intervals and no threshold, as in marginaleffects (Arel-Bundock et al. 2024). difference is the refit posterior minus the full fit's posterior median. The two fits share most of their data, so their draws are not differenced.

Value

A tibble with one row per held out study, row of newdata and summary ("mean" or "sd"). It gives the posterior median (estimate) and interval (lower, upper) of the refit and of the full fit (⁠full_*⁠), and the difference from the full fit with its interval. Predictors of the model in newdata other than study are included. The width attribute records the interval width.

References

• Vehtari et al. (2017) doi:10.1007/s11222-016-9696-4

• Arel-Bundock et al. (2024) doi:10.18637/jss.v111.i09

See Also

delay_summary_draws() for the summaries the comparison uses and epidist_newdata() to build newdata.

Other meta_model: as_epidist_meta_model(), as_epidist_meta_model.NULL(), as_epidist_meta_model.epidist_aggregate_data(), as_epidist_meta_model.epidist_estimates_data(), as_epidist_meta_model.epidist_linelist_data(), assert_epidist.epidist_meta_model(), epidist_family_model.epidist_meta_model(), epidist_formula_model.epidist_meta_model(), epidist_model_prior.epidist_meta_model(), epidist_newdata.epidist_meta_model(), epidist_transform_data_model.epidist_meta_model(), is_epidist_meta_model(), new_epidist_meta_model()

Examples

estimates <- as_epidist_estimates_data(
  data.frame(
    study = c("A", "A", "B", "B", "C", "C"),
    type = c("mean", "sd", "mean", "sd", "mean", "sd"),
    value = c(7.5, 3.6, 6.4, 3.1, 8.2, 4.0),
    n = c(120, 120, 80, 80, 150, 150),
    relative_obs_time = c(20, 20, 25, 25, Inf, Inf),
    trunc_adjusted = c(FALSE, FALSE, FALSE, FALSE, TRUE, TRUE),
    cens_adjusted = c(0, 0, 0, 0, 1, 1)
  )
)
meta <- as_epidist_meta_model(estimates = estimates)
fit <- epidist(
  meta,
  chains = 2, cores = 2, refresh = ifelse(interactive(), 250, 0)
)

# The formula does not use study, so pass the model data
epidist_meta_leave_one_out(fit, data = meta, refresh = 0)

Description

This function contains brms prior distributions which are specific to particular epidist models e.g. the latent_lognormal model.

Usage

epidist_model_prior(data, ...)

Arguments

Value

A brmsprior object, or NULL when the model adds no priors.

See Also

Other prior: epidist_family_prior(), epidist_family_prior.default(), epidist_family_prior.gengamma(), epidist_family_prior.lognormal(), epidist_model_prior.default(), epidist_model_prior.epidist_meta_model(), epidist_prior()

Description

By default, we do not return any model specific prior distributions.

Usage

## Default S3 method:
epidist_model_prior(data, formula, ...)

Arguments

Value

A brmsprior object, or NULL when the model adds no priors.

See Also

Other prior: epidist_family_prior(), epidist_family_prior.default(), epidist_family_prior.gengamma(), epidist_family_prior.lognormal(), epidist_model_prior(), epidist_model_prior.epidist_meta_model(), epidist_prior()

Description

Defines prior distributions for the latent model parameters pwindow_raw and swindow_raw which control the width of the observation windows.

Usage