harmonize documentation

Author: jcbeer

R/addTest.R

@@ -1,17 +1,17 @@
 #' Test for Additive Batch Effects
 #' 
-#' \code{addTest} function will test for additive batch effects in the residuals for each feature after fitting a linear mixed effects model. Uses Kenward-Roger method. Data should be in "long" format. Depends on \code{lme4} and \code{pbkrtest} packages.
-#' @param idvar name of ID variable (character string).
-#' @param batchvar name of the batch/site/scanner variable (character string).
-#' @param features vector of names of the feature variables (character string) or the numeric indices of the corresponding columns.
-#' @param formula character string representing everything on the right side of the formula for the model, in the notation used by \code{lme4} including covariates, time, and any interactions, e.g., \code{"age + sex + diagnosis*time"} fits model with main effects age, sex, diagnosis, and time and the diagnosis*time interaction. Formula should NOT include batchvar and should NOT include random effects.
-#' @param ranef character string representing formula for the random effects in the notation used by \code{lme4}, e.g., \code{"(1|subid)"} fits a random intercept for each unique idvar \code{subid}, and \code{"(1 + time|subid)"} fits a random intercept and slope for unique \code{subid}.
-#' @param data name of the data frame that contains the variables above. Rows are different subject/timepoints (long format), columns are different variables.
-#' @param verbose prints messages (logical \code{TRUE} or \code{FALSE}). Default is \code{TRUE}.
+#' \code{addTest} function will test for additive batch effects in the residuals for each feature after fitting a linear mixed effects model. Uses Kenward-Roger method for significance testing. Data should be in "long" format. Depends on \code{lme4} and \code{pbkrtest} packages.
+#' @param idvar character string that specifies name of ID variable. ID variable can be factor, numeric, or character. 
+#' @param batchvar character string that specifies name of the batch variable. Batch variable should be a factor.
+#' @param features character string that specifies names of the numeric feature variables, or the numeric indices of the corresponding columns.
+#' @param formula character string representing all fixed effects on the right side of the formula for the linear mixed effects model. This should be in the notation used by \code{lme4} and include covariates, time, and any interactions. For example, \code{"age + sex + diagnosis*time"} fits model with fixed effects age, sex, diagnosis, time, and the diagnosis*time interaction. Formula should NOT include batchvar and should NOT include random effects.
+#' @param ranef character string representing formula for the random effects in the notation used by \code{lme4}. For example, \code{"(1|subid)"} fits a random intercept for each unique idvar \code{subid}, and \code{"(1 + time|subid)"} fits a random intercept and random slope for each unique \code{subid}.
+#' @param data name of the data frame that contains the variables above. Rows are different observations (subject/timepoints), columns are different variables.
+#' @param verbose prints messages. Logical \code{TRUE} or \code{FALSE}. Default is \code{TRUE}.
 #' @return A data frame of Kenward-Roger test results for each feature.
 
-addTest <- function(idvar, batchvar, features, 
-                       formula, ranef, data, verbose=TRUE){
+addTest <- function(idvar, batchvar, features,
+                    formula, ranef, data, verbose=TRUE){
   # make batch a factor if not already
   batch <- as.factor(data[,batchvar])
   if (verbose) cat("[addTest] found", nlevels(batch), 'batches\n')

R/batchBoxplot.R

@@ -1,21 +1,21 @@
 #' Boxplot for Batch Effects
 #' 
-#' \code{batchBoxplot} function will plot residuals of linear mixed effect model for a simgle feature by batch to visualize additive and multiplicative batch effects. Data should be in "long" format. Depends on \code{lme4} packages.
-#' @param idvar name of ID variable (character string).
-#' @param batchvar name of the batch/site/scanner variable (character string).
-#' @param feature name of the feature variable (character string) or the numeric index of the corresponding column.
-#' @param formula character string representing everything on the right side of the formula for the model, in the notation used by \code{lme4} including covariates, time, and any interaction, e.g., \code{"age + sex + diagnosis*time"} fits model with main effects age, sex, diagnosis, and time and the diagnosis*time interaction. Formula should NOT include batchvar and should NOT include random effects.
-#' @param ranef character string representing formula for the random effects in the notation used by \code{lme4}, e.g., \code{"(1|subid)"} fits a random intercept for each unique idvar \code{subid}, and \code{"(1 + time|subid)"} fits a random intercept and slope for unique \code{subid}.
-#' @param data name of the data frame that contains the variables above. Rows are different subject/timepoints (long format), columns are different variables.
-#' @param adjustBatch should residuals be adjusted for batch? (logical \code{TRUE} or \code{FALSE}). Use \code{FALSE} to illustrate additive (and multiplicative) batch effects. Use \code{TRUE} to illustrate only multiplicative batch effects. Default is \code{FALSE}.
-#' @param orderby \code{'mean'} orders boxplots by increasing mean; best for illustrating additive batch effects (use with \code{adjustBatch=FALSE}). \code{'var'} orders boxplots by increasing variance; best for illustrating multiplicative batch effects.
-#' @param plotMeans Should batch means be plotted on top of the boxplots? (logical \code{TRUE} or \code{FALSE}). Default is \code{TRUE}.
-#' @param colors Vector of colors the same length and order as \code{levels(as.factor(data[,batchvar]))} that determines the colors of the boxplots (character string of color names or hexadecimal codes). Default is \code{"grey"}.
-#' @param xlabel x-axis label, default is \code{'batch'} (character string).
-#' @param ylabel y-axis label, default is \code{'residuals'} (character string).
+#' \code{batchBoxplot} function will plot residuals of linear mixed effects model for a single feature by batch to visualize additive and multiplicative batch effects. Data should be in "long" format. Depends on \code{lme4} package.
+#' @param idvar character string that specifies name of ID variable. ID variable can be factor, numeric, or character.
+#' @param batchvar character string that specifies name of the batch variable. Batch variable should be a factor.
+#' @param feature character string that specifies name of the numeric feature variable, or the numeric index of the corresponding column.
+#' @param formula character string representing all fixed effects on the right side of the formula for the linear mixed effects model. This should be in the notation used by \code{lme4} and include covariates, time, and any interactions. For example, \code{"age + sex + diagnosis*time"} fits model with fixed effects age, sex, diagnosis, time, and the diagnosis*time interaction. Formula should NOT include batchvar and should NOT include random effects.
+#' @param ranef character string representing formula for the random effects in the notation used by \code{lme4}. For example, \code{"(1|subid)"} fits a random intercept for each unique idvar \code{subid}, and \code{"(1 + time|subid)"} fits a random intercept and random slope for each unique \code{subid}.
+#' @param data name of the data frame that contains the variables above. Rows are different observations (subject/timepoints), columns are different variables.
+#' @param adjustBatch should residuals be adjusted for the fixed effect of batch? Logical \code{TRUE} or \code{FALSE}. Use \code{FALSE} to illustrate additive (and multiplicative) batch effects. Use \code{TRUE} to illustrate only multiplicative batch effects. Default is \code{FALSE}.
+#' @param orderby \code{'mean'} orders boxplots by increasing mean; best for illustrating additive batch effects (use with \code{adjustBatch=FALSE}). \code{'var'} orders boxplots by increasing variance; best for illustrating multiplicative batch effects. Default is \code{'mean'}.
+#' @param plotMeans should batch means be plotted on top of the boxplots? Logical \code{TRUE} or \code{FALSE}. Default is \code{TRUE}.
+#' @param colors vector of colors the same length and order as \code{levels(as.factor(data[,batchvar]))} that determines the colors of the boxplots (character string of color names or hexadecimal codes). Default is \code{"grey"} for all.
+#' @param xlabel x-axis label (character string). Default is \code{'batch'}.
+#' @param ylabel y-axis label (character string). Default is \code{'residuals'}.
 #' @param title main title for the plot, default is no title (character string).
-#' @param verbose prints messages (logical \code{TRUE} or \code{FALSE}). Default is \code{TRUE}.
-#' @param ... other graphical parameter arguments passed to \code{par()}.
+#' @param verbose prints messages. Logical \code{TRUE} or \code{FALSE}. Default is \code{TRUE}.
+#' @param ... other graphical parameter arguments passed to \code{\link[graphics]{par}}.
 #' @return Creates a boxplot.
 
 batchBoxplot <- function(idvar, batchvar, feature, 

R/batchTimeViz.R

@@ -1,18 +1,19 @@
 #' Visualize Batches Over Time
 #' 
 #' \code{batchTimeViz} is a simple function that will visualize batches over time for multi-batch longitudinal data. Data should be in "long" format.
-#' @param batchvar name of the batch/site/scanner variable (character string).
-#' @param timevar name of the time variable, e.g. age or time from baseline (character string).
-#' @param xlabel x-axis label, default is \code{'time'} (character string).
-#' @param ylabel y-axis label, default is \code{'batch'} (character string).
-#' @param title main title for the plot, default is no title (character string).
-#' @param data name of the data frame that contains the variables above rows are different subject/timepoints (long format), columns are different variables.
-#' @param verbose prints messages (logical \code{TRUE} or \code{FALSE}). Default is \code{TRUE}.
-#' @param ... other graphical parameter arguments passed to \code{par()}.
+#' @param batchvar character string that specifies name of the batch variable. Batch variable should be a factor.
+#' @param timevar character string that specifies name of numeric variable that distinguishes within-subject repeated measures, e.g., time, age, or visit. Will be plotted along x-axis.
+#' @param data name of the data frame that contains the variables above. Rows are different observations (subject/timepoints), columns are different variables.
+#' @param xlabel x-axis label (character string). Default is \code{'time'}.
+#' @param ylabel y-axis label (character string). Default is \code{'batch'}.
+#' @param title main title for the plot (character string). Default is no title.
+#' @param verbose prints messages. Logical \code{TRUE} or \code{FALSE}. Default is \code{TRUE}.
+#' @param ... other graphical parameter arguments passed to \code{\link[graphics]{par}}.
 #' @return Creates a plot.
 
-batchTimeViz <- function(batchvar, timevar, xlabel='time', ylabel='batch', 
-                     title='', data, verbose=TRUE, ...){
+batchTimeViz <- function(batchvar, timevar, data, 
+                         xlabel='time', ylabel='batch', title='', 
+                         verbose=TRUE, ...){
 
   # make batch a factor if not already
   batch <- as.factor(data[,batchvar])

R/longCombat.R

@@ -1,19 +1,19 @@
 #' Harmonize Multi-batch Longitudinal Data
 #' 
 #' \code{longCombat} function will implement longitudinal ComBat harmonization for multi-batch longitudinal data. Longitudinal ComBat uses an empirical Bayes method to harmonize means and variances of the residuals across batches in a linear mixed effects model framework. Detailed methods are described in the manuscript at \url{https://www.biorxiv.org/content/10.1101/868810v4}. This is a modification of the ComBat function code from the \code{sva} package that can be found at \url{https://bioconductor.org/packages/release/bioc/html/sva.html} and \code{combat.R} that can be found at \url{https://github.com/Jfortin1/ComBatHarmonization}. Data should be in "long" format. Depends on \code{lme4} package.
-#' @param idvar name of ID variable (character string).
-#' @param timevar name of variable that distinguishes within-subject repeated measures, e.g., time, age, or visit (character string).
-#' @param batchvar name of the batch/site/scanner variable (character string).
-#' @param features vector of names of the feature variables (character string) or the numeric indices of the corresponding columns.
-#' @param formula character string representing everything on the right side of the formula for the model, in the notation used by \code{lme4} including covariates, time, and any interactions, e.g., \code{"age + sex + diagnosis*time"} fits model with main effects age, sex, diagnosis, and time and the diagnosis*time interaction. Formula should NOT include batchvar and should NOT include random effects.
-#' @param ranef character string representing formula for the random effects in the notation used by \code{lme4}, e.g., \code{"(1|subid)"} fits a random intercept for each unique idvar \code{subid}, and \code{"(1 + time|subid)"} fits a random intercept and slope for unique \code{subid}.
-#' @param data name of the data frame that contains the variables above. Rows are different subject/timepoints (long format); columns are different variables.
+#' @param idvar character string that specifies name of ID variable. ID variable can be factor, numeric, or character. 
+#' @param timevar character string that specifies name of numeric variable that distinguishes within-subject repeated measures, e.g., time, age, or visit.
+#' @param batchvar character string that specifies name of the batch variable. Batch variable should be a factor.
+#' @param features character string that specifies names of the numeric feature variables, or the numeric indices of the corresponding columns.
+#' @param formula character string representing all fixed effects on the right side of the formula for the linear mixed effects model. This should be in the notation used by \code{lme4} and include covariates, time, and any interactions. For example, \code{"age + sex + diagnosis*time"} fits model with fixed effects age, sex, diagnosis, time, and the diagnosis*time interaction. Formula should NOT include batchvar and should NOT include random effects.
+#' @param ranef character string representing formula for the random effects in the notation used by \code{lme4}. For example, \code{"(1|subid)"} fits a random intercept for each unique idvar \code{subid}, and \code{"(1 + time|subid)"} fits a random intercept and random slope for each unique \code{subid}.
+#' @param data name of the data frame that contains the variables above. Rows are different observations (subject/timepoints), columns are different variables.
 #' @param niter number of iterations for empirical Bayes step. Usually converges quickly in less than 30 iterations. Default is 30.
-#' @param method method for estimating sigma in standardization step (character string). \code{'REML'} (default, more conservative type I error control) or \code{'MSR'} (more powerful, may not control type I error at nominal level).
-#' @param verbose prints messages (logical \code{TRUE} or \code{FALSE}). Default is \code{TRUE}.
+#' @param method method for estimating sigma in standardization step (character string). \code{'REML'} (default, more conservative type I error control) or \code{'MSR'} (more powerful, less conservative type I error control).
+#' @param verbose prints messages. Logical \code{TRUE} or \code{FALSE}. Default is \code{TRUE}.
 #' @return Function outputs a list including the following:
 #' \describe{
-#'     \item{\code{data_combat}}{data frame with columns idvar, timevar, and ComBat harmonized data}
+#'     \item{\code{data_combat}}{data frame with columns idvar, timevar, and ComBat-harmonized data for each feature}
 #'     \item{\code{gammahat}}{data frame containing mean of standardized data for each batch (row) and feature (column)}
 #'     \item{\code{delta2hat}}{data frame containing variance of standardized data for each batch (row) and feature (column)}
 #'     \item{\code{gammastarhat}}{data frame containing empirical Bayes estimate of additive batch effects}

R/multTest.R

@@ -1,13 +1,13 @@
 #' Test for Multiplicative Batch Effects
 #' 
-#' \code{multTest} function will test for multiplicative batch effects in the residuals for each feature after fitting a linear mixed effects model. Uses Fligner-Killeen method. Data should be in "long" format. Depends on \code{lme4} package.
-#' @param idvar name of ID variable (character string).
-#' @param batchvar name of the batch/site/scanner variable (character string).
-#' @param features vector of names of the feature variables (character string) or the numeric indices of the corresponding columns.
-#' @param formula character string representing everything on the right side of the formula for the model, in the notation used by \code{lme4} including covariates, time, and any interactions, e.g., \code{"age + sex + diagnosis*time"} fits model with main effects age, sex, diagnosis, and time and the diagnosis*time interaction. Formula should NOT include batchvar and should NOT include random effects.
-#' @param ranef character string representing formula for the random effects in the notation used by lme4, e.g., \code{"(1|subid)"} fits a random intercept for each unique idvar \code{"subid"}, and \code{"(1 + time|subid)"} fits a random intercept and slope unique \code{"subid"}.
-#' @param data name of the data.frame that contains the variables above. Rows are different subject/timepoints (long format), columns are different variables.
-#' @param verbose prints messages (logical \code{TRUE} or \code{FALSE}). Default is \code{TRUE}.
+#' \code{multTest} function will test for multiplicative batch effects in the residuals for each feature after fitting a linear mixed effects model. Uses Fligner-Killeen method for significance testing. Data should be in "long" format. Depends on \code{lme4} package.
+#' @param idvar character string that specifies name of ID variable. ID variable can be factor, numeric, or character. 
+#' @param batchvar character string that specifies name of the batch variable. Batch variable should be a factor.
+#' @param features character string that specifies names of the numeric feature variables, or the numeric indices of the corresponding columns.
+#' @param formula character string representing all fixed effects on the right side of the formula for the linear mixed effects model. This should be in the notation used by \code{lme4} and include covariates, time, and any interactions. For example, \code{"age + sex + diagnosis*time"} fits model with fixed effects age, sex, diagnosis, time, and the diagnosis*time interaction. Formula should NOT include batchvar and should NOT include random effects.
+#' @param ranef character string representing formula for the random effects in the notation used by \code{lme4}. For example, \code{"(1|subid)"} fits a random intercept for each unique idvar \code{subid}, and \code{"(1 + time|subid)"} fits a random intercept and random slope for each unique \code{subid}.
+#' @param data name of the data frame that contains the variables above. Rows are different observations (subject/timepoints), columns are different variables.
+#' @param verbose prints messages. Logical \code{TRUE} or \code{FALSE}. Default is \code{TRUE}.
 #' @return A data frame of Fligner-Killeen test results for each feature.
 
 multTest <- function(idvar, batchvar, features,