From d25ad2a942aecef494a09473ec53e7667abffe07 Mon Sep 17 00:00:00 2001
From: athowes <xwg3@cdc.gov>
Date: Thu, 17 Oct 2024 15:50:45 +0100
Subject: [PATCH] Document and lint, plus move default formula to delay ~ .

---
 NAMESPACE                                     |  4 ++
 R/direct_model.R                              | 47 +++++++++++++++----
 R/formula.R                                   |  3 ++
 man/as_direct_model.Rd                        | 30 ++++++++++++
 man/as_latent_individual.Rd                   |  2 +
 man/epidist.Rd                                | 10 ++--
 man/epidist.default.Rd                        | 10 ++--
 ..._family_model.epidist_latent_individual.Rd |  1 +
 ...formula_model.epidist_latent_individual.Rd |  1 +
 man/epidist_validate.epidist_direct_model.Rd  | 24 ++++++++++
 ...dist_validate.epidist_latent_individual.Rd |  1 +
 man/is_direct_model.Rd                        | 23 +++++++++
 man/is_latent_individual.Rd                   |  3 +-
 13 files changed, 138 insertions(+), 21 deletions(-)
 create mode 100644 man/as_direct_model.Rd
 create mode 100644 man/epidist_validate.epidist_direct_model.Rd
 create mode 100644 man/is_direct_model.Rd

diff --git a/NAMESPACE b/NAMESPACE
index 76f052cae..70ce4e9ec 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -3,6 +3,7 @@
 S3method(add_mean_sd,default)
 S3method(add_mean_sd,gamma_samples)
 S3method(add_mean_sd,lognormal_samples)
+S3method(as_direct_model,data.frame)
 S3method(as_latent_individual,data.frame)
 S3method(epidist,default)
 S3method(epidist_family_model,default)
@@ -17,9 +18,11 @@ S3method(epidist_model_prior,default)
 S3method(epidist_stancode,default)
 S3method(epidist_stancode,epidist_latent_individual)
 S3method(epidist_validate,default)
+S3method(epidist_validate,epidist_direct_model)
 S3method(epidist_validate,epidist_latent_individual)
 export(add_event_vars)
 export(add_mean_sd)
+export(as_direct_model)
 export(as_latent_individual)
 export(epidist)
 export(epidist_diagnostics)
@@ -35,6 +38,7 @@ export(epidist_stancode)
 export(epidist_validate)
 export(filter_obs_by_obs_time)
 export(filter_obs_by_ptime)
+export(is_direct_model)
 export(is_latent_individual)
 export(observe_process)
 export(predict_delay_parameters)
diff --git a/R/direct_model.R b/R/direct_model.R
index 864f5bc6d..73ff566bf 100644
--- a/R/direct_model.R
+++ b/R/direct_model.R
@@ -1,3 +1,8 @@
+#' Prepare direct model to pass through to `brms`
+#'
+#' @param data A `data.frame` containing line list data
+#' @family direct_model
+#' @export
 as_direct_model <- function(data) {
   UseMethod("as_direct_model")
 }
@@ -10,6 +15,21 @@ assert_direct_model_input <- function(data) {
   assert_numeric(data$stime, lower = 0)
 }
 
+#' Prepare latent individual model
+#'
+#' This function prepares data for use with the direct model. It does this by
+#' adding columns used in the model to the `data` object provided. To do this,
+#' the `data` must already have columns for the case number (integer),
+#' (positive, numeric) times for the primary and secondary event times. The
+#' output of this function is a `epidist_direct_model` class object, which may
+#' be passed to [epidist()] to perform inference for the model.
+#'
+#' @param data A `data.frame` containing line list data
+#' @rdname as_direct_model
+#' @method as_direct_model data.frame
+#' @family direct_model
+#' @autoglobal
+#' @export
 as_direct_model.data.frame <- function(data) {
   assert_direct_model_input(data)
   class(data) <- c("epidist_direct_model", class(data))
@@ -19,6 +39,18 @@ as_direct_model.data.frame <- function(data) {
   return(data)
 }
 
+#' Validate direct model data
+#'
+#' This function checks whether the provided `data` object is suitable for
+#' running the direct model. As well as making sure that
+#' `is_direct_model()` is true, it also checks that `data` is a `data.frame`
+#' with the correct columns.
+#'
+#' @param data A `data.frame` containing line list data
+#' @param ... ...
+#' @method epidist_validate epidist_direct_model
+#' @family direct_model
+#' @export
 epidist_validate.epidist_direct_model <- function(data, ...) {
   assert_true(is_direct_model(data))
   assert_direct_model_input(data)
@@ -26,16 +58,11 @@ epidist_validate.epidist_direct_model <- function(data, ...) {
   assert_numeric(data$delay, lower = 0)
 }
 
+#' Check if data has the `epidist_direct_model` class
+#'
+#' @param data A `data.frame` containing line list data
+#' @family latent_individual
+#' @export
 is_direct_model <- function(data) {
   inherits(data, "epidist_direct_model")
 }
-
-epidist_formula_model.epidist_direct_model <- function(
-    data, formula, ...
-) {
-  # data is only used to dispatch on
-  formula <- stats::update(
-    formula, delay ~ .
-  )
-  return(formula)
-}
diff --git a/R/formula.R b/R/formula.R
index 47ffdffc2..14a762fad 100644
--- a/R/formula.R
+++ b/R/formula.R
@@ -41,5 +41,8 @@ epidist_formula_model <- function(data, formula, ...) {
 #' @family formula
 #' @export
 epidist_formula_model.default <- function(data, formula, ...) {
+  formula <- stats::update(
+    formula, delay ~ .
+  )
   return(formula)
 }
diff --git a/man/as_direct_model.Rd b/man/as_direct_model.Rd
new file mode 100644
index 000000000..f2c9d8ed7
--- /dev/null
+++ b/man/as_direct_model.Rd
@@ -0,0 +1,30 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/direct_model.R
+\name{as_direct_model}
+\alias{as_direct_model}
+\alias{as_direct_model.data.frame}
+\title{Prepare direct model to pass through to \code{brms}}
+\usage{
+as_direct_model(data)
+
+\method{as_direct_model}{data.frame}(data)
+}
+\arguments{
+\item{data}{A \code{data.frame} containing line list data}
+}
+\description{
+This function prepares data for use with the direct model. It does this by
+adding columns used in the model to the \code{data} object provided. To do this,
+the \code{data} must already have columns for the case number (integer),
+(positive, numeric) times for the primary and secondary event times. The
+output of this function is a \code{epidist_direct_model} class object, which may
+be passed to \code{\link[=epidist]{epidist()}} to perform inference for the model.
+}
+\seealso{
+Other direct_model: 
+\code{\link{epidist_validate.epidist_direct_model}()}
+
+Other direct_model: 
+\code{\link{epidist_validate.epidist_direct_model}()}
+}
+\concept{direct_model}
diff --git a/man/as_latent_individual.Rd b/man/as_latent_individual.Rd
index 21d48e429..ad4d10fa2 100644
--- a/man/as_latent_individual.Rd
+++ b/man/as_latent_individual.Rd
@@ -27,12 +27,14 @@ Other latent_individual:
 \code{\link{epidist_family_model.epidist_latent_individual}()},
 \code{\link{epidist_formula_model.epidist_latent_individual}()},
 \code{\link{epidist_validate.epidist_latent_individual}()},
+\code{\link{is_direct_model}()},
 \code{\link{is_latent_individual}()}
 
 Other latent_individual: 
 \code{\link{epidist_family_model.epidist_latent_individual}()},
 \code{\link{epidist_formula_model.epidist_latent_individual}()},
 \code{\link{epidist_validate.epidist_latent_individual}()},
+\code{\link{is_direct_model}()},
 \code{\link{is_latent_individual}()}
 }
 \concept{latent_individual}
diff --git a/man/epidist.Rd b/man/epidist.Rd
index dbb162aa5..832c79a29 100644
--- a/man/epidist.Rd
+++ b/man/epidist.Rd
@@ -9,7 +9,7 @@ epidist(data, formula, family, prior, backend, fn, ...)
 \arguments{
 \item{data}{A \code{data.frame} containing line list data.}
 
-\item{formula}{A formula object created using \code{\link[brms:brmsformula]{brms::bf()}}. A formula must be
+\item{formula}{A formula object created using \code{brms::bf}. A formula must be
 provided for the distributional parameter \code{mu} common to all \code{brms} families.
 Optionally, formulas may also be provided for additional distributional
 parameters.}
@@ -29,10 +29,10 @@ for specifying prior distributions.}
 fitting the Stan model. Options are \code{"rstan"} and \code{"cmdstanr"} (the default).
 This option is passed directly through to \code{fn}.}
 
-\item{fn}{The internal function to be called. By default this is
-\code{\link[brms:brm]{brms::brm()}} which performs inference for the specified model. Other options
-\code{\link[brms:stancode]{brms::make_stancode()}}, which returns the Stan code for the specified model,
-and \code{\link[brms:standata]{brms::make_standata()}} which returns the data passed to Stan. These
+\item{fn}{The internal function to be called. By default this is \code{brms::brm},
+which performs inference for the specified model. Other options
+\code{brms::make_stancode}, which returns the Stan code for the specified model,
+and \code{brms::make_standata} which returns the data passed to Stan. These
 options may be useful for model debugging and extensions.}
 
 \item{...}{Additional arguments for method.}
diff --git a/man/epidist.default.Rd b/man/epidist.default.Rd
index 376fb7645..105bdab21 100644
--- a/man/epidist.default.Rd
+++ b/man/epidist.default.Rd
@@ -17,7 +17,7 @@
 \arguments{
 \item{data}{A \code{data.frame} containing line list data.}
 
-\item{formula}{A formula object created using \code{\link[brms:brmsformula]{brms::bf()}}. A formula must be
+\item{formula}{A formula object created using \code{brms::bf}. A formula must be
 provided for the distributional parameter \code{mu} common to all \code{brms} families.
 Optionally, formulas may also be provided for additional distributional
 parameters.}
@@ -37,10 +37,10 @@ for specifying prior distributions.}
 fitting the Stan model. Options are \code{"rstan"} and \code{"cmdstanr"} (the default).
 This option is passed directly through to \code{fn}.}
 
-\item{fn}{The internal function to be called. By default this is
-\code{\link[brms:brm]{brms::brm()}} which performs inference for the specified model. Other options
-\code{\link[brms:stancode]{brms::make_stancode()}}, which returns the Stan code for the specified model,
-and \code{\link[brms:standata]{brms::make_standata()}} which returns the data passed to Stan. These
+\item{fn}{The internal function to be called. By default this is \code{brms::brm},
+which performs inference for the specified model. Other options
+\code{brms::make_stancode}, which returns the Stan code for the specified model,
+and \code{brms::make_standata} which returns the data passed to Stan. These
 options may be useful for model debugging and extensions.}
 
 \item{...}{Additional arguments for method.}
diff --git a/man/epidist_family_model.epidist_latent_individual.Rd b/man/epidist_family_model.epidist_latent_individual.Rd
index 15490b26e..2f880e0a6 100644
--- a/man/epidist_family_model.epidist_latent_individual.Rd
+++ b/man/epidist_family_model.epidist_latent_individual.Rd
@@ -22,6 +22,7 @@ Other latent_individual:
 \code{\link{as_latent_individual}()},
 \code{\link{epidist_formula_model.epidist_latent_individual}()},
 \code{\link{epidist_validate.epidist_latent_individual}()},
+\code{\link{is_direct_model}()},
 \code{\link{is_latent_individual}()}
 }
 \concept{latent_individual}
diff --git a/man/epidist_formula_model.epidist_latent_individual.Rd b/man/epidist_formula_model.epidist_latent_individual.Rd
index 885264cfc..60fa7251e 100644
--- a/man/epidist_formula_model.epidist_latent_individual.Rd
+++ b/man/epidist_formula_model.epidist_latent_individual.Rd
@@ -21,6 +21,7 @@ Other latent_individual:
 \code{\link{as_latent_individual}()},
 \code{\link{epidist_family_model.epidist_latent_individual}()},
 \code{\link{epidist_validate.epidist_latent_individual}()},
+\code{\link{is_direct_model}()},
 \code{\link{is_latent_individual}()}
 }
 \concept{latent_individual}
diff --git a/man/epidist_validate.epidist_direct_model.Rd b/man/epidist_validate.epidist_direct_model.Rd
new file mode 100644
index 000000000..fb43f6b9b
--- /dev/null
+++ b/man/epidist_validate.epidist_direct_model.Rd
@@ -0,0 +1,24 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/direct_model.R
+\name{epidist_validate.epidist_direct_model}
+\alias{epidist_validate.epidist_direct_model}
+\title{Validate direct model data}
+\usage{
+\method{epidist_validate}{epidist_direct_model}(data, ...)
+}
+\arguments{
+\item{data}{A \code{data.frame} containing line list data}
+
+\item{...}{...}
+}
+\description{
+This function checks whether the provided \code{data} object is suitable for
+running the direct model. As well as making sure that
+\code{is_direct_model()} is true, it also checks that \code{data} is a \code{data.frame}
+with the correct columns.
+}
+\seealso{
+Other direct_model: 
+\code{\link{as_direct_model}()}
+}
+\concept{direct_model}
diff --git a/man/epidist_validate.epidist_latent_individual.Rd b/man/epidist_validate.epidist_latent_individual.Rd
index 986b13ded..0c0b33def 100644
--- a/man/epidist_validate.epidist_latent_individual.Rd
+++ b/man/epidist_validate.epidist_latent_individual.Rd
@@ -22,6 +22,7 @@ Other latent_individual:
 \code{\link{as_latent_individual}()},
 \code{\link{epidist_family_model.epidist_latent_individual}()},
 \code{\link{epidist_formula_model.epidist_latent_individual}()},
+\code{\link{is_direct_model}()},
 \code{\link{is_latent_individual}()}
 }
 \concept{latent_individual}
diff --git a/man/is_direct_model.Rd b/man/is_direct_model.Rd
new file mode 100644
index 000000000..18ef5d24f
--- /dev/null
+++ b/man/is_direct_model.Rd
@@ -0,0 +1,23 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/direct_model.R
+\name{is_direct_model}
+\alias{is_direct_model}
+\title{Check if data has the \code{epidist_direct_model} class}
+\usage{
+is_direct_model(data)
+}
+\arguments{
+\item{data}{A \code{data.frame} containing line list data}
+}
+\description{
+Check if data has the \code{epidist_direct_model} class
+}
+\seealso{
+Other latent_individual: 
+\code{\link{as_latent_individual}()},
+\code{\link{epidist_family_model.epidist_latent_individual}()},
+\code{\link{epidist_formula_model.epidist_latent_individual}()},
+\code{\link{epidist_validate.epidist_latent_individual}()},
+\code{\link{is_latent_individual}()}
+}
+\concept{latent_individual}
diff --git a/man/is_latent_individual.Rd b/man/is_latent_individual.Rd
index e42e351ea..204d510e9 100644
--- a/man/is_latent_individual.Rd
+++ b/man/is_latent_individual.Rd
@@ -17,6 +17,7 @@ Other latent_individual:
 \code{\link{as_latent_individual}()},
 \code{\link{epidist_family_model.epidist_latent_individual}()},
 \code{\link{epidist_formula_model.epidist_latent_individual}()},
-\code{\link{epidist_validate.epidist_latent_individual}()}
+\code{\link{epidist_validate.epidist_latent_individual}()},
+\code{\link{is_direct_model}()}
 }
 \concept{latent_individual}