Update documentation

Update the documentation (package reference manual) for DESCRIPTION, functions `bayesmsm`, `bayesweight` and `bayesweight_cen`

DESCRIPTION

@@ -11,7 +11,7 @@ Authors@R: c(
     person("Martin", "Urner", ,"[email protected]", role = "aut",
            comment = "https://criticalcaretoronto.com/our-fellows/dr-martin-urner/"))
 Maintainer: Kuan Liu <[email protected]>
-Description: Fitting Bayesian marginal structrual models to estimate average treatment effect for drawing causal inference with time-varying treatment assignment and confoudning with extension to handle informative right-censoring. The Bayesian marginal structural models is a semi-parametric approach and features a two-step estimation process. The first step involves Bayesian parametric estimation of the time-varying treatment assignment models and the second step involves non-parametric Bayesian bootstrap to estimate the average treatment effect between two distinct treatment sequences of interest. Based on the Bayesian marginal structural models of Saarela et al (2015) <DOI: 10.1111/biom.12269> and Liu et al (2020) <DOI: 10.1177/0962280219900362>. 
+Description: Fitting Bayesian marginal structrual models to estimate average treatment effect for drawing causal inference with time-varying treatment assignment and confounding with extension to handle informative right-censoring. This package can be used for continuous or binary treatment assignments, covariates and end-of-study outcomes. Based on the Bayesian marginal structural models of Saarela et al (2015) <DOI: 10.1111/biom.12269> and Liu et al (2020) <DOI: 10.1177/0962280219900362>. 
 Depends:
     R (>= 4.2.0)
 Suggests: 

R/bayesmsm.R

@@ -4,18 +4,18 @@
 #' effects in Bayesian marginal structural models. It supports both continuous
 #' (gaussian) and binary (binomial) outcome variables.
 #'
-#' @param ymodel A formula representing the outcome model with interactions.
-#' @param nvisit Number of visits or time points.
-#' @param reference Reference intervention across all visits. Default is a vector of all 0's with length nvisit (i.e. never treated).
-#' @param comparator Comparison intervention across all visits. Default is a vector of all 1's with length nvisit (i.e. always treated).
-#' @param family Outcome distribution family; "gaussian" (default) for continuous outcomes or "binomial" for binary outcomes.
-#' @param data The dataset.
-#' @param wmean Vector of treatment assignment weights. Default is rep(1, 1000).
-#' @param nboot Number of bootstrap iterations.
-#' @param optim_method Optimization method to be used. Default is 'BFGS'.
-#' @param seed A seed to ensure reproducibility.
-#' @param parallel Whether parallel computation should be used. Default is TRUE.
-#' @param ncore Number of cores to use for parallel computation. Default is 4.
+#' @param ymodel Model statement for the outcome variable.
+#' @param nvisit Number of visits or time points to simulate.
+#' @param reference Vector denoting the intervention to be used as the reference across all visits for calculating the risk ratio and risk difference. The default is a vector of all 0's with length nvisit (i.e. never treated).
+#' @param comparator Vector denoting the intervention to be used as the comparator across all visits for calculating the risk ratio and risk difference. The default is a vector of all 1's with length nvisit (i.e. always treated).
+#' @param family Character string specifying the outcome distribution family. The possible distributions are: "gaussian" (default) for continuous outcomes, and "binomial" for binary outcomes.
+#' @param data Data table containing the variable names in `ymodel`.
+#' @param wmean Vector of treatment assignment weights. The default is rep(1, nrow(data)).
+#' @param nboot Integer specifying the number of bootstrap iterations. The default is 1000.
+#' @param optim_method Character string specifying the optimization method to be used. The default is 'BFGS'.
+#' @param seed Starting seed for simulations and bootstrapping. The default is 890123.
+#' @param parallel Logical scalar indicating whether to parallelize bootstrapping to multiple cores. The default is TRUE.
+#' @param ncore Integer specifying the number of CPU cores to use in parallel simulation. This argument is required when parallel is set to TRUE, and the default is 4.
 #'
 #' @return It returns an object of class `bayesmsm` that contains the information about the data, model, etc.
 #'
@@ -63,7 +63,7 @@ bayesmsm <- function(ymodel,
                      optim_method = 'BFGS',
                      seed = 890123,
                      parallel = TRUE,
-                     ncore = 6){
+                     ncore = 4){
 
   # load all the required R packages;
   # require(foreach)

R/bayesweight.R

@@ -3,14 +3,14 @@
 #' This function estimates Bayesian weights for time-varying treatment effects using specified models for each treatment time point.
 #' It uses JAGS for Bayesian inference and supports parallel computation to speed up the MCMC simulations.
 #'
-#' @param trtmodel.list A list of formulas corresponding to each time point with the time-specific treatment variable on the left hand side and pre-treatment covariates to be balanced on the right hand side. Interactions and functions of covariates are allowed.
-#' @param data A dataframe containing the variables mentioned in the `trtmodel.list`.
-#' @param n.chains The number of MCMC chains to run. Set to 1 for non-parallel computation. For parallel computation, it is required to use at least 2 chains.
-#' @param n.iter The total number of iterations for each chain (including burn-in).
-#' @param n.burnin The number of burn-in iterations for each chain.
-#' @param n.thin Thinning rate for the MCMC sampler.
-#' @param seed A seed to ensure reproducibility.
-#' @param parallel Logical. Indicates whether to run the MCMC chains in parallel. Default is TRUE.
+#' @param trtmodel.list A list of formulas corresponding to each time point with the time-specific treatment variable on the left hand side and pre-treatment covariates to be balanced on the right hand side. The formulas must be in temporal order, and must contain all covariates to be balanced at that time point. Interactions and functions of covariates are allowed.
+#' @param data A data set in the form of a data frame containing the variables in `trtmodel.list`. This must be a wide data set with exactly one row per unit.
+#' @param n.chains Integer specifying the number of MCMC chains to run. Set to 1 for non-parallel computation. For parallel computation, it is required to use at least 2 chains. The default is 2.
+#' @param n.iter Integer specifying the total number of iterations for each chain (including burn-in). The default is 25000.
+#' @param n.burnin Integer specifying the number of burn-in iterations for each chain. The default is 15000.
+#' @param n.thin Integer specifying the thinning rate for the MCMC sampler. The default is 5.
+#' @param seed Starting seed for the JAGS model. The default is 890123.
+#' @param parallel Logical scalar indicating whether to run the MCMC chains in parallel. The default is TRUE.
 #'
 #' @return A list of the calculated weights.
 #'

R/bayesweight_cen.R

@@ -1,16 +1,17 @@
-#' Bayesian Weight Estimation for Censored Data
+#' Bayesian Treatment Effect Weight Estimation for Censored Data
 #'
-#' This function computes posterior mean weights using Bayesian estimation for treatment models and censoring models across multiple time points. The models can be run in parallel to estimate the weights needed for causal inference with censored data.
+#' This function computes posterior mean weights using Bayesian estimation for treatment models and censoring models across multiple time points.
+#' The models can be run in parallel to estimate the weights for censored data.
 #'
-#' @param trtmodel.list A list of formulas corresponding to each time point with the time-specific treatment variable on the left-hand side and pre-treatment covariates to be balanced on the right-hand side. Interactions and functions of covariates are allowed.
-#' @param cenmodel.list A list of formulas for the censoring data at each time point, with censoring indicators on the left-hand side and covariates on the right-hand side.
-#' @param data A data frame containing the variables in the models (treatment, censoring, and covariates).
-#' @param n.iter Number of iterations to run the MCMC algorithm in JAGS.
-#' @param n.burnin Number of iterations to discard as burn-in in the MCMC algorithm.
-#' @param n.thin Thinning rate for the MCMC samples.
-#' @param parallel Logical, indicating whether to run the MCMC sampling in parallel (default is `FALSE`).
-#' @param n.chains Number of MCMC chains to run. If parallel is `TRUE`, this specifies the number of chains run in parallel.
-#' @param seed A seed for random number generation to ensure reproducibility of the MCMC.
+#' @param trtmodel.list A list of formulas corresponding to each time point with the time-specific treatment variable on the left-hand side and pre-treatment covariates to be balanced on the right-hand side. The formulas must be in temporal order, and must contain all covariates to be balanced at that time point. Interactions and functions of covariates are allowed.
+#' @param cenmodel.list A list of formulas for the censored data at each time point, with censoring indicators on the left-hand side and covariates on the right-hand side. The formulas must be in temporal order, and must contain all covariates to be balanced at that time point.
+#' @param data A data set in the form of a data frame containing the variables in `trtmodel.list` and `cenmodel.list`. This must be a wide data set with exactly one row per unit.
+#' @param n.iter Integer specifying the total number of iterations for each chain (including burn-in). The default is 25000.
+#' @param n.burnin Integer specifying the number of burn-in iterations for each chain. The default is 15000.
+#' @param n.thin Integer specifying the thinning rate for the MCMC sampler. The default is 5.
+#' @param parallel Logical scalar indicating whether to run the MCMC chains in parallel. The default is TRUE.
+#' @param n.chains Integer specifying the number of MCMC chains to run. Set to 1 for non-parallel computation. For parallel computation, it is required to use at least 2 chains. The default is 2.
+#' @param seed Starting seed for the JAGS model. The default is 890123.
 #'
 #' @return A vector of posterior mean weights, computed by taking the average of the weights across all MCMC iterations.
 #' @importFrom R2jags jags
@@ -43,18 +44,14 @@
 #'                                parallel = FALSE,
 #'                                n.chains = 1,
 #'                                seed = 890123)
-bayesweight_cen <- function(trtmodel.list = list(A1 ~ L11 + L21,
-                                                 A2 ~ L11 + L21 + L12 + L22 + A1,
-                                                 A3 ~ L11 + L21 + L12 + L22 + A1 + L13 + L23 + A2),
-                            cenmodel.list = list(C1 ~ L11 + L21,
-                                                 C2 ~ L11 + L21 + A1,
-                                                 C3 ~ L11 + L21 + A1 + L12 + L22 + A2),
+bayesweight_cen <- function(trtmodel.list,
+                            cenmodel.list,
                             data,
-                            n.iter = 2500,
-                            n.burnin = 1500,
+                            n.iter = 25000,
+                            n.burnin = 15000,
                             n.thin = 5,
-                            parallel = FALSE,
-                            n.chains = 1,
+                            parallel = TRUE,
+                            n.chains = 2,
                             seed = 890123) {