Add standalone documentation for sr_model class

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: serodynamics
 Title: What the Package Does (One Line, Title Case)
-Version: 0.0.0.9047
+Version: 0.0.0.9048
 Authors@R: c(
     person("Peter", "Teunis", , "p.teunis@emory.edu", role = c("aut", "cph"),
            comment = "Author of the method and original code."),

NEWS.md

@@ -1,5 +1,9 @@
 # serodynamics (development version)
 
+* Added standalone documentation page for the `sr_model` class, describing all
+  data columns and attributes including the upcoming `population_params`
+  attribute from PR #141.
+
 * Added dev container configuration for persistent, cached development environment
   that includes R, JAGS, and all dependencies preinstalled, making Copilot
   Workspace sessions much faster.

R/Run_Mod.R

@@ -26,7 +26,7 @@
 #' should be included as an element of the [list] object returned by `run_mod()`
 #' (see `Value` section below for details).
 #' Note: These objects can be large.
-#' @returns An `sr_model` class object: a subclass of [dplyr::tbl_df] that
+#' @returns An `sr_model` class object: a subclass of [tibble::tbl_df] that
 #' contains MCMC samples from the joint posterior distribution of the model
 #' parameters, conditional on the provided input `data`, 
 #' including the following:

R/nepal_sees_jags_output.R

@@ -8,7 +8,8 @@
 #' which is the diagnosis type (typhoid or
 #' paratyphoid). Keeping only IDs `"newperson"`, `"sees_npl_1"`, `"sees_npl_2"`.
 #'
-#' @format An S3 object of class `sr_model`: A [dplyr::tbl_df] that contains the
+#' @format An S3 object of class `sr_model`:
+#' A [tibble::tbl_df] that contains the
 #'   posterior predictive distribution of the person-specific parameters for a
 #'   "new person" with no observed data (`Subject = "newperson"`) and posterior
 #'   distributions of the person-specific parameters for two arbitrarily-chosen

R/plot_predicted_curve.R

@@ -12,7 +12,7 @@
 #' @param ids The participant IDs to plot; for example, `"sees_npl_128"`.
 #' @param antigen_iso  The antigen isotype to plot; for example, "HlyE_IgA" or 
 #' "HlyE_IgG".
-#' @param dataset (Optional) A [dplyr::tbl_df] with observed antibody response 
+#' @param dataset (Optional) A [tibble::tbl_df] with observed antibody response 
 #' data. 
 #' Must contain:
 #'   - `timeindays`

R/sr_model-class.R

@@ -0,0 +1,113 @@
+#' `sr_model` class
+#'
+#' @description
+#' An S3 class representing the output of a Bayesian MCMC model
+#' fitted by [run_mod()]. The `sr_model` object is a subclass
+#' of [tibble::tbl_df] containing MCMC samples from the joint posterior
+#' distribution of host-specific antibody kinetic parameters,
+#' conditional on the provided input data.
+#'
+#' Each row represents one posterior draw for one parameter, one
+#' antigen-isotype combination, one subject, and one stratification level.
+#'
+#' @section Data columns:
+#'
+#' \describe{
+#'   \item{Iteration}{[integer] MCMC sampling iteration index.}
+#'   \item{Chain}{[integer] MCMC chain index (between 1 and the number of
+#'   chains specified in [run_mod()]).}
+#'   \item{Parameter}{[character] name of the antibody dynamic curve parameter.
+#'   One of:
+#'   \itemize{
+#'     \item `y0` -- baseline antibody concentration
+#'     \item `y1` -- peak antibody concentration
+#'     \item `t1` -- time to peak
+#'     \item `shape` -- shape parameter
+#'     \item `alpha` -- decay rate
+#'   }}
+#'   \item{Iso_type}{[character] antibody/antigen isotype combination being
+#'   evaluated (e.g., `"HlyE_IgA"`, `"HlyE_IgG"`).}
+#'   \item{Stratification}{[character] the level of the stratification variable
+#'   used when fitting the model, or `"None"` if no stratification was
+#'   specified.}
+#'   \item{Subject}{[character] identifier of the subject. Includes observed
+#'   subjects as well as `"newperson"`, which represents the posterior
+#'   predictive distribution for a hypothetical new individual with no observed
+#'   data.}
+#'   \item{value}{[numeric] posterior sample value of the parameter.}
+#' }
+#'
+#' @section Attributes:
+#'
+#' In addition to the standard [tibble::tbl_df] attributes (`names`,
+#' `row.names`, `class`), an `sr_model` object carries the following
+#' custom attributes:
+#'
+#' \describe{
+#'   \item{nChains}{[integer] number of MCMC chains run.}
+#'   \item{nParameters}{[integer] number of parameters estimated in the model.}
+#'   \item{nIterations}{[integer] total number of MCMC iterations specified.}
+#'   \item{nBurnin}{[integer] number of burn-in iterations discarded before
+#'   sampling.}
+#'   \item{nThin}{[integer] thinning interval (ratio of total iterations to
+#'   retained samples, i.e., `niter / nmc`).}
+#'   \item{population_params}{(optional) a [tibble::tbl_df] of modeled
+#'   population-level parameters, included when `with_pop_params = TRUE` in
+#'   [run_mod()]. Indexed by `Iteration`, `Chain`, `Parameter`, `Iso_type`,
+#'   and `Stratification`. Contains the following population parameters:
+#'   \itemize{
+#'     \item `mu.par` -- the population means of the host-specific model
+#'     parameters (on logarithmic scales).
+#'     \item `prec.par` -- the population precision matrix of the
+#'     hyperparameters (with diagonal elements equal to inverse variances).
+#'     \item `prec.logy` -- a vector of population precisions (inverse
+#'     variances), one per antigen/isotype combination.
+#'   }}
+#'   \item{priors}{a [list] summarizing the input priors used in the model,
+#'   with the following elements:
+#'   \itemize{
+#'     \item `mu_hyp_param` -- prior means for y0, y1, t1, shape, and alpha.
+#'     \item `prec_hyp_param` -- precision hyperparameters (inverse variances).
+#'     \item `omega_param` -- Wishart hyperprior diagonal entries.
+#'     \item `wishdf` -- degrees of freedom for the Wishart distribution.
+#'     \item `prec_logy_hyp_param` -- log-scale precision hyperparameters.
+#'   }}
+#'   \item{fitted_residuals}{a [data.frame] containing fitted values and
+#'   residuals for all observations, with columns:
+#'   \itemize{
+#'     \item `Subject` -- subject identifier.
+#'     \item `Iso_type` -- antigen-isotype combination.
+#'     \item `t` -- time since infection.
+#'     \item `fitted` -- fitted value calculated from posterior parameter
+#'     estimates.
+#'     \item `residual` -- residual (observed minus fitted).
+#'   }}
+#'   \item{jags.post}{(optional) a [list] of raw [runjags::run.jags()] output
+#'   objects, one per stratification level. Included when
+#'   `with_post = TRUE` in [run_mod()]. These objects can be large.}
+#' }
+#'
+#' @section Construction:
+#'
+#' `sr_model` objects are created by [run_mod()] and should not normally
+#' be constructed directly.
+#'
+#' @section Inheritance:
+#'
+#' The class hierarchy is
+#' `sr_model` > `tbl_df` > `tbl` > `data.frame`,
+#' so standard [dplyr::dplyr-package] and [tibble::tibble-package] operations
+#' work on `sr_model` objects.
+#'
+#' @seealso
+#' * [run_mod()] -- the constructor function.
+#' * [post_summ()] -- posterior summary table.
+#' * [plot_predicted_curve()] -- predicted antibody response curves.
+#' * [plot_jags_trace()] -- MCMC trace plots.
+#' * [plot_jags_dens()] -- posterior density plots.
+#' * [plot_jags_Rhat()] -- Rhat diagnostic plots.
+#' * [plot_jags_effect()] -- effect size plots.
+#'
+#' @name sr_model-class
+#' @aliases sr_model
+NULL

R/use_att_names.R

@@ -2,7 +2,7 @@
 #' @description
 #'  `use_att_names` takes prepared longitudinal data for antibody kinetic
 #'  modeling and names columns using attribute values to allow merging
-#'  with a modeled [run_mod()] output [dplyr::tbl_df]. The column names include
+#'  with a modeled [run_mod()] output [tibble::tbl_df]. The column names include
 #'  `Subject`, `Iso_type`, `t`, and `result`. 
 #' @param data A [data.frame] raw longitudinal data that has been
 #' prepared for antibody kinetic modeling using [as_case_data()].

inst/WORDLIST

@@ -43,6 +43,7 @@ onwards
 params
 pkgdown
 prec
+precisions
 preinstalling
 rhat
 seroconversion

pkgdown/_pkgdown.yml

@@ -29,6 +29,7 @@ reference:
 - title: Model seroreponse
   contents:
   - run_mod
+  - sr_model-class
 - title: Model diagnostics
   contents:
   - plot_jags_dens