Issue #382: Reorganise function locations (#389)

* Move fitting functions into fit

* Create stancode.R

* Create validate.R

* Remove defaults.R and generics.R and pkgdown groups

* Document

* Don't need this line

* Standardise providing ... argument to generics

* Remove whitespace

* Fix R CMD CHECK warning

* Return NULL by default for stancode

* Add test of Stan code NULL case

* Add test for stanvars class

R/generics.R → R/fit.R

@@ -1,36 +1,7 @@
-#' Validate a data object for use with [epidist()]
-#'
-#' This function validates that the provided `data` is suitable to run a
-#' particular `epidist` model. This may include checking the class of `data`,
-#' and that it contains suitable columns.
-#'
-#' @param data A `data.frame` containing line list data.
-#' @family generics
-#' @export
-epidist_validate <- function(data) {
-  UseMethod("epidist_validate")
-}
-
-#' Define model specific Stan code
-#'
-#' This function is used within [epidist()] to create any custom Stan code which
-#' is injected into `brms` via the `stanvars` argument. 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()].
-#'
-#' @inheritParams epidist_validate
-#' @param ... Additional arguments passed to method.
-#' @rdname epidist_stancode
-#' @family generics
-#' @export
-epidist_stancode <- function(data, ...) {
-  UseMethod("epidist_stancode")
-}
-
 #' Fit epidemiological delay distributions using a `brms` interface
 #'
 #' @inheritParams epidist_validate
-#' @param formula A formula object created using [brms::bf()]. A formula must be
+#' @param formula A formula object created using `brms::bf`. A formula must be
 #' provided for the distributional parameter `mu` common to all `brms` families.
 #' Optionally, formulas may also be provided for additional distributional
 #' parameters.
@@ -46,14 +17,43 @@ epidist_stancode <- function(data, ...) {
 #' @param backend Character string naming the package to use as the backend for
 #' fitting the Stan model. Options are `"rstan"` and `"cmdstanr"` (the default).
 #' This option is passed directly through to `fn`.
-#' @param fn The internal function to be called. By default this is
-#' [brms::brm()] which performs inference for the specified model. Other options
-#' [brms::make_stancode()], which returns the Stan code for the specified model,
-#' and [brms::make_standata()] which returns the data passed to Stan. These
+#' @param fn The internal function to be called. By default this is `brms::brm`,
+#' which performs inference for the specified model. Other options
+#' `brms::make_stancode`, which returns the Stan code for the specified model,
+#' and `brms::make_standata` which returns the data passed to Stan. These
 #' options may be useful for model debugging and extensions.
 #' @param ... Additional arguments for method.
-#' @family generics
+#' @family fit
 #' @export
 epidist <- function(data, formula, family, prior, backend, fn, ...) {
   UseMethod("epidist")
 }
+
+#' Default method used for interface using `brms`
+#'
+#' @inheritParams epidist
+#' @rdname epidist.default
+#' @method epidist default
+#' @family fit
+#' @export
+epidist.default <- function(data, formula = brms::bf(mu ~ 1),
+                            family = "lognormal", prior = NULL,
+                            backend = "cmdstanr", fn = brms::brm, ...) {
+  epidist_validate(data)
+  epidist_family <- epidist_family(data, family)
+  epidist_formula <- epidist_formula(
+    data = data, family = epidist_family, formula = formula
+  )
+  epidist_prior <- epidist_prior(
+    data = data, family = family, formula = epidist_formula, prior
+  )
+  epidist_stancode <- epidist_stancode(
+    data = data, family = epidist_family, formula = epidist_formula
+  )
+  fit <- fn(
+    formula = epidist_formula, family = epidist_family, prior = epidist_prior,
+    stanvars = epidist_stancode, backend = backend, data = data, ...
+  )
+  class(fit) <- c(class(fit), "epidist_fit")
+  return(fit)
+}

R/latent_individual.R

@@ -72,10 +72,11 @@ as_latent_individual.data.frame <- function(data) {
 #' `data.frame` with the correct columns.
 #'
 #' @param data A `data.frame` containing line list data
+#' @param ... ...
 #' @method epidist_validate epidist_latent_individual
 #' @family latent_individual
 #' @export
-epidist_validate.epidist_latent_individual <- function(data) {
+epidist_validate.epidist_latent_individual <- function(data, ...) {
   assert_true(is_latent_individual(data))
   assert_latent_individual_input(data)
   assert_names(

R/stancode.R

@@ -0,0 +1,25 @@
+#' Define model specific Stan code
+#'
+#' This function is used within [epidist()] to create any custom Stan code which
+#' is injected into `brms` via the `stanvars` argument. 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()].
+#'
+#' @inheritParams epidist_validate
+#' @param ... Additional arguments passed to method.
+#' @rdname epidist_stancode
+#' @family stan
+#' @export
+epidist_stancode <- function(data, ...) {
+  UseMethod("epidist_stancode")
+}
+
+#' Default method for defining model specific Stan code
+#'
+#' @inheritParams epidist_stancode
+#' @param ... Additional arguments passed to method.
+#' @family stan
+#' @export
+epidist_stancode.default <- function(data, ...) {
+  return(NULL)
+}

R/validate.R

@@ -0,0 +1,26 @@
+#' Validate a data object for use with [epidist()]
+#'
+#' This function validates that the provided `data` is suitable to run a
+#' particular `epidist` model. This may include checking the class of `data`,
+#' and that it contains suitable columns.
+#'
+#' @param data A `data.frame` containing line list data.
+#' @param ... Additional arguments passed to method.
+#' @family validate
+#' @export
+epidist_validate <- function(data, ...) {
+  UseMethod("epidist_validate")
+}
+
+#' Default method for data validation
+#'
+#' @inheritParams epidist_validate
+#' @param ... Additional arguments passed to method.
+#' @family validate
+#' @export
+epidist_validate.default <- function(data, ...) {
+  cli_abort(
+    "No epidist_validate method implemented for the class ", class(data), "\n",
+    "See methods(epidist_validate) for available methods"
+  )
+}

_pkgdown.yml

@@ -41,14 +41,10 @@ reference:
   desc: Functions for preprocessing data
   contents:
   - has_concept("preprocess")
-- title: S3 generics
-  desc: S3 generics for delay modelling
+- title: Validation
+  desc: Functions used to check validity of package objects
   contents:
-  - has_concept("generics")
-- title: Method default
-  desc: Default methods for S3 generics
-  contents:
-  - has_concept("defaults")
+  - has_concept("validate")
 - title: Family
   desc: Functions related to specifying custom `brms` families
   contents:
@@ -57,10 +53,18 @@ reference:
   desc: Functions related to specifying custom `brms` formula
   contents:
   - has_concept("formula")
-- title: Priors
+- title: Prior distributions
   desc: Functions for specifying prior distributions
   contents:
   - has_concept("prior")
+- title: Stan code
+  desc: Functions for specifying custom Stan code to put into `brms`
+  contents:
+  - has_concept("stan") 
+- title: Model fitting
+  desc: Functions for fitting delay distribution models using `brms`
+  contents:
+  - has_concept("fit")
 - title: Latent individual model
   desc: Specific methods for the latent individual model
   contents: