Merge branch 'main' into 249-test-devtag-for-internal-documentation

NEWS.md

@@ -2,6 +2,8 @@
 
 ## New features
 
+* Added default value for `antigen_isos` argument in `log_likelihood()` (#286)
+
 * Updated enteric fever example article with upgraded code and visualizations (#290)
 
 * Added template for reporting Issues 

R/llik.R → R/log_likelihood.R

@@ -1,55 +1,55 @@
-#' Calculate log-likelihood
+#' @title Calculate log-likelihood
 #'
 #' @description
-#' Calculates the log-likelihood of a set of cross-sectional antibody response data, for a given incidence rate (`lambda`) value.
+#' Calculates the log-likelihood of a set of cross-sectional antibody response
+#' data, for a given incidence rate (`lambda`) value.
+#'
 #' `r lifecycle::badge("deprecated")`
 #'
 #' `llik()` was renamed to [log_likelihood()] to create a more
 #' consistent API.
 #'
 #' @keywords internal
 #' @export
-
-llik <- function(
-    lambda,
-    pop_data,
-    antigen_isos,
-    curve_params,
-    noise_params,
-    verbose = FALSE,
-    ...) {
+llik <- function(...) {
   lifecycle::deprecate_warn("1.0.0", "llik()", "log_likelihood()")
-  log_likelihood(lambda,
-                 pop_data,
-                 antigen_isos,
-                 curve_params,
-                 noise_params,
-                 verbose)
+  log_likelihood(...)
 }
 
-#' Calculate log-likelihood
+#' @title Calculate log-likelihood
 #'
 #' @description
-#' Calculates the log-likelihood of a set of cross-sectional antibody response data, for a given incidence rate (`lambda`) value.
-#' @param pop_data a [data.frame()] with cross-sectional serology data per antibody and age, and additional columns
-#' @param antigen_isos Character vector listing one or more antigen isotypes. Values must match `pop_data`.
-#' @param curve_params a [data.frame()] containing MCMC samples of parameters from the Bayesian posterior distribution of a longitudinal decay curve model. The parameter columns must be named:
-#' - `antigen_iso`: a [character()] vector indicating antigen-isotype combinations
+#' Calculates the log-likelihood of a set of cross-sectional antibody response
+#' data, for a given incidence rate (`lambda`) value.
+#' @param pop_data a [data.frame()] with cross-sectional serology data
+#' by antibody and age, and additional columns
+#' @param antigen_isos Character vector listing one or more antigen isotypes.
+#' Values must match `pop_data`.
+#' @param curve_params a [data.frame()] containing MCMC samples of parameters
+#' from the Bayesian posterior distribution of a longitudinal decay curve model.
+#' The parameter columns must be named:
+#' - `antigen_iso`: a [character()] vector indicating antigen-isotype
+#' combinations
 #' - `iter`: an [integer()] vector indicating MCMC sampling iterations
 #' - `y0`: baseline antibody level at $t=0$ ($y(t=0)$)
 #' - `y1`: antibody peak level (ELISA units)
 #' - `t1`: duration of infection
-#' - `alpha`: antibody decay rate (1/days for the current longitudinal parameter sets)
+#' - `alpha`: antibody decay rate
+#' (1/days for the current longitudinal parameter sets)
 #' - `r`: shape factor of antibody decay
-#' @param noise_params a [data.frame()] (or [tibble::tibble()]) containing the following variables, specifying noise parameters for each antigen isotype:
-#' * `antigen_iso`: antigen isotype whose noise parameters are being specified on each row
+#' @param noise_params a [data.frame()] (or [tibble::tibble()])
+#' containing the following variables,
+#' specifying noise parameters for each antigen isotype:
+#' * `antigen_iso`: antigen isotype whose noise parameters are being specified
+#' on each row
 #' * `nu`: biological noise
 #' * `eps`: measurement noise
 #' * `y.low`: lower limit of detection for the current antigen isotype
 #' * `y.high`: upper limit of detection for the current antigen isotype
 #'
 #' @param verbose logical: if TRUE, print verbose log information to console
-#' @param ... additional arguments passed to other functions (not currently used).
+#' @param ... additional arguments passed to other functions
+#' (not currently used).
 #' @inheritParams f_dev
 #' @return the log-likelihood of the data with the current parameter values
 #' @export
@@ -84,19 +84,19 @@ llik <- function(
 log_likelihood <- function(
     lambda,
     pop_data,
-    antigen_isos,
     curve_params,
     noise_params,
+    antigen_isos = get_biomarker_levels(pop_data),
     verbose = FALSE,
     ...) {
   # Start with zero total
-  nllTotal <- 0
+  nll_total <- 0
 
   # Loop over antigen_isos
-  for (cur_antibody in antigen_isos)
-  {
+  for (cur_antibody in antigen_isos) {
     # the inputs can be lists, after `split(~antigen_ios)`
-    # this gives some speedups compared to running filter() every time .nll() is called
+    # this gives some speedups compared to running filter() every time .nll()
+    # is called
     if (!is.data.frame(pop_data)) {
       cur_data <- pop_data[[cur_antibody]]
       cur_curve_params <- curve_params[[cur_antibody]]
@@ -124,7 +124,7 @@ log_likelihood <- function(
       }
     }
 
-    nllSingle <-
+    nll_single <-
       f_dev(
         lambda = lambda,
         csdata = cur_data,
@@ -133,11 +133,12 @@ log_likelihood <- function(
       )
 
     # if (!is.na(nllSingle))  # not meaningful for vectorized f_dev()
-    {
-      nllTotal <- nllTotal + nllSingle # DEM note: summing log likelihoods represents an independence assumption for multiple Antibodies, given time since seroconversion
-    }
+    nll_total <- nll_total + nll_single
+    # note: summing log likelihoods represents an independence assumption
+    # for multiple Antibodies, given time since seroconversion
+
   }
 
   # Return total log-likelihood
-  return(-nllTotal)
+  return(-nll_total)
 }