From 81c178d4fedb60b2f78258e8793ec9cd8a6ad1be Mon Sep 17 00:00:00 2001 From: kgostic Date: Wed, 29 Jan 2025 22:52:32 +0000 Subject: [PATCH 1/3] update marginal model docs --- R/marginal_model.R | 37 ++++++++++++++++++- ...st_marginal_model.epidist_linelist_data.Rd | 37 ++++++++++++++++++- 2 files changed, 72 insertions(+), 2 deletions(-) diff --git a/R/marginal_model.R b/R/marginal_model.R index b22248e3f..05c3e0b9b 100644 --- a/R/marginal_model.R +++ b/R/marginal_model.R @@ -18,8 +18,43 @@ as_epidist_marginal_model <- function(data, ...) { #' Default is 2. #' @param weight A column name to use for weighting the data in the #' likelihood. Default is NULL. Internally this is used to define the 'n' -#' column of the returned object. +#' column of the returned object. See details. #' @param ... Not used in this method. +#' @details To ensure efficient computation, the model automatically +#' identifies groups of individuals in the data that contribute identically +#' to the likelihood, and evaluates the likelihood at the group level. Groups +#' are defined by unique combinations of: {ptime_upr, stime_upr, stime_lwr, +#' relative_obs_time, pwindow, swindow, and other_vars}, where the first six +#' fields are defined by `as_epidist_linelist_data()` (see also the [getting started vignette](linelihttps://epidist.epinowcast.org/dev/articles/epidist.html#data)), +#' and where `other_vars` includes other variables used in the model forumla, +#' (e.g. age, sex, or location). +#' +#' The `weight` option can be used for convenience when working with data that +#' contain too many individuals to represent easily in linelist format. For +#' example, `prepped` and `prepped_weighted` would be +#' interpreted identically by epidist(): +#' +#' ``` +#' ## Prep as a linelist +#' prepped <- linelist |> +#' as_epidist_linelist_data() |> +#' as_epidist_marginal_model(linelist) +#' ``` +#' +#' or +#' +#' ``` +#' ## Aggregate by relevant variables +#' prepped_weighted <- linelist |> +#' as_epidist_linelist_data() |> +#' # summarise by unique combinations of variables +#' group_by(ptime_upr, stime_upr, stime_lwr, +#' relative_obs_time, pwindow, swindow, +#' other_vars) |> +#' summarise(n = n()) +#' # prep with weight option +#' as_epidist_marginal_model(linelist, weight = "n") +#' ``` #' @method as_epidist_marginal_model epidist_linelist_data #' @family marginal_model #' @autoglobal diff --git a/man/as_epidist_marginal_model.epidist_linelist_data.Rd b/man/as_epidist_marginal_model.epidist_linelist_data.Rd index 063f80d82..fe3d81b54 100644 --- a/man/as_epidist_marginal_model.epidist_linelist_data.Rd +++ b/man/as_epidist_marginal_model.epidist_linelist_data.Rd @@ -17,13 +17,48 @@ Default is 2.} \item{weight}{A column name to use for weighting the data in the likelihood. Default is NULL. Internally this is used to define the 'n' -column of the returned object.} +column of the returned object. See details.} \item{...}{Not used in this method.} } \description{ The marginal model method for \code{epidist_linelist_data} objects } +\details{ +To ensure efficient computation, the model automatically +identifies groups of individuals in the data that contribute identically +to the likelihood, and evaluates the likelihood at the group level. Groups +are defined by unique combinations of: {ptime_upr, stime_upr, stime_lwr, +relative_obs_time, pwindow, swindow, and other_vars}, where the first six +fields are defined by \code{as_epidist_linelist_data()} (see also the \href{linelihttps://epidist.epinowcast.org/dev/articles/epidist.html#data}{getting started vignette}), # nolint +and where \code{other_vars} includes other variables used in the model forumla, +(e.g. age, sex, or location). + +The \code{weight} option can be used for convenience when working with data that +contain too many individuals to represent easily in linelist format. For +example, \code{prepped} and \code{prepped_weighted} would be +interpreted identically by epidist(): + +\if{html}{\out{
}}\preformatted{## Prep as a linelist +prepped <- linelist |> + as_epidist_linelist_data() |> + as_epidist_marginal_model(linelist) +}\if{html}{\out{
}} + +or + +\if{html}{\out{
}}\preformatted{## Aggregate by relevant variables +prepped_weighted <- linelist |> + as_epidist_linelist_data() |> + # summarise by unique combinations of variables + group_by(ptime_upr, stime_upr, stime_lwr, + relative_obs_time, pwindow, swindow, + other_vars) |> +summarise(n = n()) +# prep with weight option +as_epidist_marginal_model(linelist, weight = "n") +}\if{html}{\out{
}} +} \seealso{ Other marginal_model: \code{\link{as_epidist_marginal_model}()}, From 876a5b8bb6342a2ec52bc4819bbee0603ba2348f Mon Sep 17 00:00:00 2001 From: kgostic Date: Wed, 29 Jan 2025 22:52:32 +0000 Subject: [PATCH 2/3] update marginal model docs --- R/marginal_model.R | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/R/marginal_model.R b/R/marginal_model.R index 05c3e0b9b..a8eb952f5 100644 --- a/R/marginal_model.R +++ b/R/marginal_model.R @@ -19,13 +19,14 @@ as_epidist_marginal_model <- function(data, ...) { #' @param weight A column name to use for weighting the data in the #' likelihood. Default is NULL. Internally this is used to define the 'n' #' column of the returned object. See details. +#' column of the returned object. See details. #' @param ... Not used in this method. #' @details To ensure efficient computation, the model automatically #' identifies groups of individuals in the data that contribute identically #' to the likelihood, and evaluates the likelihood at the group level. Groups #' are defined by unique combinations of: {ptime_upr, stime_upr, stime_lwr, #' relative_obs_time, pwindow, swindow, and other_vars}, where the first six -#' fields are defined by `as_epidist_linelist_data()` (see also the [getting started vignette](linelihttps://epidist.epinowcast.org/dev/articles/epidist.html#data)), +#' fields are defined by `as_epidist_linelist_data()`, #' and where `other_vars` includes other variables used in the model forumla, #' (e.g. age, sex, or location). #' From 9c27d26cbc4c154955e4dcbe1127829eafa69f52 Mon Sep 17 00:00:00 2001 From: kgostic Date: Thu, 30 Jan 2025 15:20:16 +0000 Subject: [PATCH 3/3] Fixed mistake in pseudocode --- R/marginal_model.R | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/R/marginal_model.R b/R/marginal_model.R index a8eb952f5..3dad21d62 100644 --- a/R/marginal_model.R +++ b/R/marginal_model.R @@ -39,7 +39,7 @@ as_epidist_marginal_model <- function(data, ...) { #' ## Prep as a linelist #' prepped <- linelist |> #' as_epidist_linelist_data() |> -#' as_epidist_marginal_model(linelist) +#' as_epidist_marginal_model() #' ``` #' #' or @@ -52,9 +52,9 @@ as_epidist_marginal_model <- function(data, ...) { #' group_by(ptime_upr, stime_upr, stime_lwr, #' relative_obs_time, pwindow, swindow, #' other_vars) |> -#' summarise(n = n()) +#' summarise(n = n()) |> #' # prep with weight option -#' as_epidist_marginal_model(linelist, weight = "n") +#' as_epidist_marginal_model(weight = "n") #' ``` #' @method as_epidist_marginal_model epidist_linelist_data #' @family marginal_model