diff --git a/DESCRIPTION b/DESCRIPTION index ea5d92de0..a46b14176 100644 --- a/DESCRIPTION +++ b/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."), diff --git a/NEWS.md b/NEWS.md index 89199522a..c318d70f4 100644 --- a/NEWS.md +++ b/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. diff --git a/R/Run_Mod.R b/R/Run_Mod.R index 25e75d601..c1ae89df0 100644 --- a/R/Run_Mod.R +++ b/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: diff --git a/R/nepal_sees_jags_output.R b/R/nepal_sees_jags_output.R index fb75a06c7..2f23ad2a0 100644 --- a/R/nepal_sees_jags_output.R +++ b/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 diff --git a/R/plot_predicted_curve.R b/R/plot_predicted_curve.R index 3a0d46545..f1cb1bff1 100644 --- a/R/plot_predicted_curve.R +++ b/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` diff --git a/R/sr_model-class.R b/R/sr_model-class.R new file mode 100644 index 000000000..508ad76ac --- /dev/null +++ b/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 diff --git a/R/use_att_names.R b/R/use_att_names.R index b72128587..02a40618c 100644 --- a/R/use_att_names.R +++ b/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()]. diff --git a/inst/WORDLIST b/inst/WORDLIST index 8ea3768d3..a0716aa22 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -43,6 +43,7 @@ onwards params pkgdown prec +precisions preinstalling rhat seroconversion diff --git a/man/nepal_sees_jags_output.Rd b/man/nepal_sees_jags_output.Rd index 2bd139153..8fdc71a75 100644 --- a/man/nepal_sees_jags_output.Rd +++ b/man/nepal_sees_jags_output.Rd @@ -5,7 +5,8 @@ \alias{nepal_sees_jags_output} \title{SEES Typhoid run_mod jags output} \format{ -An S3 object of class \code{sr_model}: A \link[dplyr:tbl_df]{dplyr::tbl_df} that contains the +An S3 object of class \code{sr_model}: +A \link[tibble:tbl_df-class]{tibble::tbl_df} that contains the posterior predictive distribution of the person-specific parameters for a "new person" with no observed data (\code{Subject = "newperson"}) and posterior distributions of the person-specific parameters for two arbitrarily-chosen diff --git a/man/plot_predicted_curve.Rd b/man/plot_predicted_curve.Rd index 7e2fabde6..194ba11f4 100644 --- a/man/plot_predicted_curve.Rd +++ b/man/plot_predicted_curve.Rd @@ -31,7 +31,7 @@ samples from the posterior distribution of the model parameters.} \item{antigen_iso}{The antigen isotype to plot; for example, "HlyE_IgA" or "HlyE_IgG".} -\item{dataset}{(Optional) A \link[dplyr:tbl_df]{dplyr::tbl_df} with observed antibody response +\item{dataset}{(Optional) A \link[tibble:tbl_df-class]{tibble::tbl_df} with observed antibody response data. Must contain: \itemize{ diff --git a/man/run_mod.Rd b/man/run_mod.Rd index 08f914275..a3aec9cd6 100644 --- a/man/run_mod.Rd +++ b/man/run_mod.Rd @@ -93,7 +93,7 @@ If specified, must be 2 values long: }} } \value{ -An \code{sr_model} class object: a subclass of \link[dplyr:tbl_df]{dplyr::tbl_df} that +An \code{sr_model} class object: a subclass of \link[tibble:tbl_df-class]{tibble::tbl_df} that contains MCMC samples from the joint posterior distribution of the model parameters, conditional on the provided input \code{data}, including the following: diff --git a/man/sr_model-class.Rd b/man/sr_model-class.Rd new file mode 100644 index 000000000..dec36f578 --- /dev/null +++ b/man/sr_model-class.Rd @@ -0,0 +1,124 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/sr_model-class.R +\name{sr_model-class} +\alias{sr_model-class} +\alias{sr_model} +\title{\code{sr_model} class} +\description{ +An S3 class representing the output of a Bayesian MCMC model +fitted by \code{\link[=run_mod]{run_mod()}}. The \code{sr_model} object is a subclass +of \link[tibble:tbl_df-class]{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}{\link{integer} MCMC sampling iteration index.} +\item{Chain}{\link{integer} MCMC chain index (between 1 and the number of +chains specified in \code{\link[=run_mod]{run_mod()}}).} +\item{Parameter}{\link{character} name of the antibody dynamic curve parameter. +One of: +\itemize{ +\item \code{y0} -- baseline antibody concentration +\item \code{y1} -- peak antibody concentration +\item \code{t1} -- time to peak +\item \code{shape} -- shape parameter +\item \code{alpha} -- decay rate +}} +\item{Iso_type}{\link{character} antibody/antigen isotype combination being +evaluated (e.g., \code{"HlyE_IgA"}, \code{"HlyE_IgG"}).} +\item{Stratification}{\link{character} the level of the stratification variable +used when fitting the model, or \code{"None"} if no stratification was +specified.} +\item{Subject}{\link{character} identifier of the subject. Includes observed +subjects as well as \code{"newperson"}, which represents the posterior +predictive distribution for a hypothetical new individual with no observed +data.} +\item{value}{\link{numeric} posterior sample value of the parameter.} +} +} + +\section{Attributes}{ + + +In addition to the standard \link[tibble:tbl_df-class]{tibble::tbl_df} attributes (\code{names}, +\code{row.names}, \code{class}), an \code{sr_model} object carries the following +custom attributes: + +\describe{ +\item{nChains}{\link{integer} number of MCMC chains run.} +\item{nParameters}{\link{integer} number of parameters estimated in the model.} +\item{nIterations}{\link{integer} total number of MCMC iterations specified.} +\item{nBurnin}{\link{integer} number of burn-in iterations discarded before +sampling.} +\item{nThin}{\link{integer} thinning interval (ratio of total iterations to +retained samples, i.e., \code{niter / nmc}).} +\item{population_params}{(optional) a \link[tibble:tbl_df-class]{tibble::tbl_df} of modeled +population-level parameters, included when \code{with_pop_params = TRUE} in +\code{\link[=run_mod]{run_mod()}}. Indexed by \code{Iteration}, \code{Chain}, \code{Parameter}, \code{Iso_type}, +and \code{Stratification}. Contains the following population parameters: +\itemize{ +\item \code{mu.par} -- the population means of the host-specific model +parameters (on logarithmic scales). +\item \code{prec.par} -- the population precision matrix of the +hyperparameters (with diagonal elements equal to inverse variances). +\item \code{prec.logy} -- a vector of population precisions (inverse +variances), one per antigen/isotype combination. +}} +\item{priors}{a \link{list} summarizing the input priors used in the model, +with the following elements: +\itemize{ +\item \code{mu_hyp_param} -- prior means for y0, y1, t1, shape, and alpha. +\item \code{prec_hyp_param} -- precision hyperparameters (inverse variances). +\item \code{omega_param} -- Wishart hyperprior diagonal entries. +\item \code{wishdf} -- degrees of freedom for the Wishart distribution. +\item \code{prec_logy_hyp_param} -- log-scale precision hyperparameters. +}} +\item{fitted_residuals}{a \link{data.frame} containing fitted values and +residuals for all observations, with columns: +\itemize{ +\item \code{Subject} -- subject identifier. +\item \code{Iso_type} -- antigen-isotype combination. +\item \code{t} -- time since infection. +\item \code{fitted} -- fitted value calculated from posterior parameter +estimates. +\item \code{residual} -- residual (observed minus fitted). +}} +\item{jags.post}{(optional) a \link{list} of raw \code{\link[runjags:run.jags]{runjags::run.jags()}} output +objects, one per stratification level. Included when +\code{with_post = TRUE} in \code{\link[=run_mod]{run_mod()}}. These objects can be large.} +} +} + +\section{Construction}{ + + +\code{sr_model} objects are created by \code{\link[=run_mod]{run_mod()}} and should not normally +be constructed directly. +} + +\section{Inheritance}{ + + +The class hierarchy is +\code{sr_model} > \code{tbl_df} > \code{tbl} > \code{data.frame}, +so standard \link[dplyr:dplyr-package]{dplyr::dplyr-package} and \link[tibble:tibble-package]{tibble::tibble-package} operations +work on \code{sr_model} objects. +} + +\seealso{ +\itemize{ +\item \code{\link[=run_mod]{run_mod()}} -- the constructor function. +\item \code{\link[=post_summ]{post_summ()}} -- posterior summary table. +\item \code{\link[=plot_predicted_curve]{plot_predicted_curve()}} -- predicted antibody response curves. +\item \code{\link[=plot_jags_trace]{plot_jags_trace()}} -- MCMC trace plots. +\item \code{\link[=plot_jags_dens]{plot_jags_dens()}} -- posterior density plots. +\item \code{\link[=plot_jags_Rhat]{plot_jags_Rhat()}} -- Rhat diagnostic plots. +\item \code{\link[=plot_jags_effect]{plot_jags_effect()}} -- effect size plots. +} +} diff --git a/man/use_att_names.Rd b/man/use_att_names.Rd index f43fcef0c..144aa5a81 100644 --- a/man/use_att_names.Rd +++ b/man/use_att_names.Rd @@ -16,7 +16,7 @@ The input \link{data.frame} with columns named after attributes. \description{ \code{use_att_names} takes prepared longitudinal data for antibody kinetic modeling and names columns using attribute values to allow merging -with a modeled \code{\link[=run_mod]{run_mod()}} output \link[dplyr:tbl_df]{dplyr::tbl_df}. The column names include +with a modeled \code{\link[=run_mod]{run_mod()}} output \link[tibble:tbl_df-class]{tibble::tbl_df}. The column names include \code{Subject}, \code{Iso_type}, \code{t}, and \code{result}. } \keyword{internal} diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 61c982025..f8e9528eb 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -29,6 +29,7 @@ reference: - title: Model seroreponse contents: - run_mod + - sr_model-class - title: Model diagnostics contents: - plot_jags_dens