0.8.4: documentation and other fixes

Author: slamballais

DESCRIPTION

@@ -17,7 +17,8 @@ Imports:
     Matrix (>= 1.2.12),
     methods,
     parallel,
-    RcppEigen (>= 0.3.3.4.0)
+    RcppEigen (>= 0.3.3.4.0),
+    stats (>= 3.4.3)
 Suggests:
     magick (>= 2.0),
     mi (>= 1.0),

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(formula,vw_fastlm)
 S3method(hist,vw)
 S3method(nobs,vw_fastlm)
 S3method(print,vw)
@@ -14,7 +15,6 @@ export(fbm_row_is_0)
 export(fbm_row_mean)
 export(fbm_row_sd)
 export(fbm_row_sum)
-export(formula.vw_fastlm)
 export(freeview)
 export(imp2list)
 export(load.annot)
@@ -38,3 +38,4 @@ importFrom(bigstatsr,cols_along)
 importFrom(bigstatsr,rows_along)
 importFrom(foreach,"%dopar%")
 importFrom(foreach,foreach)
+importFrom(stats,nobs)

NEWS.md

@@ -6,6 +6,7 @@
 
 ## Minor Tweaks
 * Added the `file_out_tree` argument, which controls whether output files also contain the full project name. By default, it is the inverse of `dir_out_tree`.
+* Fixed a lot of the documentation.
 
 # QDECR 0.8.3
 

R/FBM_functions.R

@@ -1,6 +1,20 @@
+#' @name fbm_functions_from_qdecr
+#' @rdname fbm_functions_from_qdecr
+#' 
+#' @title fbm functions from qdecr
+#' 
+#' @param X the FBM (file-backed matrix) object
+#' @param ncores the number of cores to be used
+#' @param row.ind the rows to go over (by default, it goes over all rows)
+#' @param col.ind the columns to go over (by default, it goes over all columns)
+#' @param row.mask a separate mask for the rows (added because this was useful internally)
+#' @param col.mask a separate mask for the columns (added because this was useful internally)
 #' @importFrom bigstatsr rows_along
 #' @importFrom bigstatsr cols_along
+#' @return an mgh object of the corresponding map
+NULL
 
+#' @rdname fbm_functions_from_qdecr
 #' @export
 fbm_row_mean <- function(X, ncores = 1, 
                          row.ind = bigstatsr::rows_along(X), col.ind = bigstatsr::cols_along(X), 
@@ -12,6 +26,7 @@ fbm_row_mean <- function(X, ncores = 1,
   bigstatsr::big_apply(X, a.FUN = function(X, ind) rowMeans(X[row.ind[ind], col.ind]), a.combine = "c", ncores = ncores, ind = seq_along(row.ind))
 }
 
+#' @rdname fbm_functions_from_qdecr
 #' @export
 fbm_col_mean <- function(X, ncores = 1, 
                          row.ind = bigstatsr::rows_along(X), col.ind = bigstatsr::cols_along(X), 
@@ -23,6 +38,7 @@ fbm_col_mean <- function(X, ncores = 1,
   bigstatsr::big_apply(X, a.FUN = function(X, ind) colMeans(X[row.ind, col.ind[ind]]), a.combine = "c", ncores = ncores, ind = seq_along(col.ind))
 }
 
+#' @rdname fbm_functions_from_qdecr
 #' @export
 fbm_row_is_0 <- function(X, ncores = 1, 
                          row.ind = bigstatsr::rows_along(X), col.ind = bigstatsr::cols_along(X), 
@@ -34,6 +50,7 @@ fbm_row_is_0 <- function(X, ncores = 1,
   bigstatsr::big_apply(X, a.FUN = function(X, ind) apply(X[row.ind[ind], col.ind], 1, function(q) any(q == 0)), a.combine = "c", ncores = ncores, ind = seq_along(row.ind))
 }
 
+#' @rdname fbm_functions_from_qdecr
 #' @export
 fbm_col_is_0 <- function(X, ncores = 1, 
                          row.ind = bigstatsr::rows_along(X), col.ind = bigstatsr::cols_along(X), 
@@ -45,6 +62,7 @@ fbm_col_is_0 <- function(X, ncores = 1,
   bigstatsr::big_apply(X, a.FUN = function(X, ind) apply(X[row.ind, col.ind[ind]], 2, function(q) any(q == 0)), a.combine = "c", ncores = ncores, ind = seq_along(col.ind))
 }
 
+#' @rdname fbm_functions_from_qdecr
 #' @export
 fbm_row_sum <- function(X, ncores = 1, 
                          row.ind = bigstatsr::rows_along(X), col.ind = bigstatsr::cols_along(X), 
@@ -56,6 +74,7 @@ fbm_row_sum <- function(X, ncores = 1,
   bigstatsr::big_apply(X, a.FUN = function(X, ind) rowSums(X[row.ind[ind], col.ind]), a.combine = "c", ncores = ncores, ind = seq_along(row.ind))
 }
 
+#' @rdname fbm_functions_from_qdecr
 #' @export
 fbm_col_sum <- function(X, ncores = 1, 
                          row.ind = bigstatsr::rows_along(X), col.ind = bigstatsr::cols_along(X), 
@@ -67,6 +86,7 @@ fbm_col_sum <- function(X, ncores = 1,
   bigstatsr::big_apply(X, a.FUN = function(X, ind) colSums(X[row.ind, col.ind[ind]]), a.combine = "c", ncores = ncores, ind = seq_along(col.ind))
 }
 
+#' @rdname fbm_functions_from_qdecr
 #' @export
 fbm_row_sd <- function(X, ncores = 1, 
                          row.ind = bigstatsr::rows_along(X), col.ind = bigstatsr::cols_along(X), 
@@ -75,9 +95,10 @@ fbm_row_sd <- function(X, ncores = 1,
   if (is.numeric(col.mask)) col.mask <- as.logical(col.mask)
   if(!is.null(row.mask)) row.ind <- row.ind[row.mask] 
   if(!is.null(col.mask)) col.ind <- col.ind[col.mask] 
-  bigstatsr::big_apply(X, a.FUN = function(X, ind) apply(X[row.ind[ind], col.ind], 1, sd), a.combine = "c", ncores = ncores, ind = seq_along(row.ind))
+  bigstatsr::big_apply(X, a.FUN = function(X, ind) apply(X[row.ind[ind], col.ind], 1, stats::sd), a.combine = "c", ncores = ncores, ind = seq_along(row.ind))
 }
 
+#' @rdname fbm_functions_from_qdecr
 #' @export
 fbm_col_sd <- function(X, ncores = 1, 
                          row.ind = bigstatsr::rows_along(X), col.ind = bigstatsr::cols_along(X), 
@@ -86,5 +107,5 @@ fbm_col_sd <- function(X, ncores = 1,
   if (is.numeric(col.mask)) col.mask <- as.logical(col.mask)
   if(!is.null(row.mask)) row.ind <- row.ind[row.mask] 
   if(!is.null(col.mask)) col.ind <- col.ind[col.mask] 
-  bigstatsr::big_apply(X, a.FUN = function(X, ind) apply(X[row.ind, col.ind[ind]], 2, sd), a.combine = "c", ncores = ncores, ind = seq_along(col.ind))
+  bigstatsr::big_apply(X, a.FUN = function(X, ind) apply(X[row.ind, col.ind[ind]], 2, stats::sd), a.combine = "c", ncores = ncores, ind = seq_along(col.ind))
 }

R/imp2list.R

@@ -44,14 +44,14 @@ imp2list.list <- function(obj) {
 imp2list.matrix <- function(obj) imp2list(as.data.frame(obj))
 
 imp2list.mi <- function(obj) {
-  err <- require(mi)
-  if (!err) stop("You are trying to load in an `mi` output object, but `mi` is not installed.")
+  if (!requireNamespace("mi", quietly = TRUE))
+    stop("You are trying to load in an `mi` output object, but `mi` is not installed.")
   mi::complete(obj)
 }
 
 imp2list.mids <- function(obj) {
-  err <- require(mice)
-  if (!err) stop("You are trying to load in an `mice` output object (class `mids`), but `mice` is not installed.")
+  if (!requireNamespace("mice", quietly = TRUE))
+    stop("You are trying to load in an `mice` output object (class `mids`), but `mice` is not installed.")
   lapply(seq_len(obj$m), function(y) mice::complete(obj, y))
 }
 

R/io_mgh.R

@@ -1,11 +1,18 @@
 #' Combine all MGH files into one object
 #'
-#' @param input.list path to parent directory
-#' @param files.list file names within `input.list`
-#'
+#' @param input_path path to parent directory
+#' @param files_list file names within `input.list`
+#' @param mask mask to be used in later steps (i.e. analysis)
+#' @param hemi "lh" or "rh"
+#' @param measure vertex measure (e.g. "thickness")
+#' @param fwhmc the fwhm value in full notation (i.e. 20, 23, 30, etc)
+#' @param target the target template (usually "fsaverage")
+#' @param n_cores the number of cores to be used
+#' @param dir_tmp directory to store the temporary big matrices; useful for shared memory; defaults to `dir_out`
+#' @param project the base name you want to assign to the output files
+#' @param backing the path to the backing file
+#' @param verbose if TRUE, writes out standard log; if FALSE, no output is generated
 #' @return matrix with vertex data (columns) for each file (rows)
-#'
-#'
 qdecr_prep_mgh <- function(input_path, 
                            files_list = list.files(input_path),
                            mask, hemi, measure, fwhmc, target, 
@@ -19,9 +26,10 @@ qdecr_prep_mgh <- function(input_path,
   m <- bigstatsr::FBM(temp$ndim1, n, backingfile = backing)
   cl <- if(verbose) parallel::makeForkCluster(n_cores, outfile = "") else parallel::makeForkCluster(n_cores)
   doParallel::registerDoParallel(cl)
-  capture.output(pb <- txtProgressBar(0, n, style = 3), file = "/dev/null")
+  utils::capture.output(pb <- utils::txtProgressBar(0, n, style = 3), file = "/dev/null")
+  i <- NULL
   foreach(i = seq_len(n)) %dopar% {
-    setTxtProgressBar(pb, i)
+    utils::setTxtProgressBar(pb, i)
     m[,i] <- load.mgh(new_files[i])$x
     NULL
   }
@@ -117,8 +125,9 @@ load.annot <- function(input.file) {
 #'
 #' Modified version of save_mgh.m (by Heath Pardoe, 09/12/2013)
 #'
-#' @param vol MGH object (as from load.mgh)
+#' @param fbm a file backed matrix
 #' @param fname file name to be used to save out the data
+#' @param filter a vector of indices of rows to include of fbm
 #'
 #' @export
 #' 

R/plotting.R

@@ -6,13 +6,13 @@
 #'variable. As it opens Freeview directly, you will have access to all the functions
 #'of Freeview by default. To continue using R, simply close Freeview.
 #'
-#'@param vw The output object of a qdecr call (e.g. qdecr_fastlm)
-#'@param stack Either a numeric or a string for your variable (use `stacks(vw)`)
-#'@param type The type of map to plot (currently for OLS). Default is `coef`, others are `se`, `t` and `p`
-#'@param sig Logical; if TRUE (default), only the significant clusters are shown
-#'@param ... any arguments that freeview (on command line) normally takes for manipulating surface files
-#'@return NULL
-#'@export
+#' @param vw The output object of a qdecr call (e.g. qdecr_fastlm)
+#' @param stack Either a numeric or a string for your variable (use `stacks(vw)`)
+#' @param type The type of map to plot (currently for OLS). Default is `coef`, others are `se`, `t` and `p`
+#' @param sig Logical; if TRUE (default), only the significant clusters are shown
+#' @param ... any arguments that freeview (on command line) normally takes for manipulating surface files
+#' @return NULL
+#' @export
 
 freeview <- function(vw, stack = NULL, type = c("coef", "se", "t", "p"), sig = TRUE, ...) {
   if (is.null(stack)) stop("`stack` not defined. Please choose: ", paste(stacks(vw), collapse = ", "))
@@ -132,20 +132,21 @@ freeview_surf_cmd <- function(surface,
 #'This function works on top of the base `hist` function. It simply makes a histogram
 #'of the mean vertex values either per vertex or per subject (if you specify `qtype = "subject"`)
 #'
-#'@param vw The output object of a qdecr call (e.g. qdecr_fastlm)
-#'@param qtype A string; either "vertex" for vertex-wise means, or "subject" for subject-wise means
-#'@param xlab See `?hist`
-#'@param main see `?hist`
-#'@param ... Further arguments for `hist`
-#'@return see `?hist`
-#'@export
+#' @param x The output object of a qdecr call (e.g. qdecr_fastlm)
+#' @param qtype A string; either "vertex" for vertex-wise means, or "subject" for subject-wise means
+#' @param xlab See `?hist`
+#' @param main see `?hist`
+#' @param ... Further arguments for `hist`
+#' @return see `?hist`
+#' @method hist vw
+#' @export
 #'
-hist.vw <- function(vw, qtype = c("vertex", "subject"), xlab = NULL, main = NULL, ...) {
+hist.vw <- function(x, qtype = c("vertex", "subject"), xlab = NULL, main = NULL, ...) {
   qtype <- match.arg(qtype)
-  x <- if(qtype == "vertex") vw$post$mgh_description$vertex_mean else vw$post$mgh_description$subject_mean
-  if (is.null(xlab)) xlab <- vw$input$measure
+  y <- if(qtype == "vertex") x$post$mgh_description$vertex_mean else x$post$mgh_description$subject_mean
+  if (is.null(xlab)) xlab <- x$input$measure
   if (is.null(main)) main <- qtype
-  hist(x[], xlab = xlab, main = main, ...)
+  graphics::hist(y[], xlab = xlab, main = main, ...)
 }
 
 #'Opens Freeview to take snapshots
@@ -156,18 +157,18 @@ hist.vw <- function(vw, qtype = c("vertex", "subject"), xlab = NULL, main = NULL
 #'and additionally composes the images and plots them. Magick++ is required
 #'for the composing step (see www.qdecr.com).
 #'
-#'@param vw The output object of a qdecr call (e.g. qdecr_fastlm)
-#'@param stack Either a numeric or a string for your variable (use `stacks(vw)`)
-#'@param type The type of map to plot (currently for OLS). Default is `coef`, others are `se`, `t` and `p`
-#'@param ext Extension of the image files that will be stored on disk
-#'@param zoom Float that determines how far the brains are zoomed in
-#'@param compose Logical; if TRUE, a single compiled image will be made (requires Magick++)
-#'@param plot_brain Logical; if TRUE, returns a graphical device with the composed images
-#'@param save_plot Logical; if TRUE, saves the composed image
-#'@param sig Logical; if TRUE, only the significant clusters are shown
-#'@param ... any arguments that freeview (on command line) normally takes for manipulating surface files
-#'@return NULL
-#'@export
+#' @param vw The output object of a qdecr call (e.g. qdecr_fastlm)
+#' @param stack Either a numeric or a string for your variable (use `stacks(vw)`)
+#' @param type The type of map to plot (currently for OLS). Default is `coef`, others are `se`, `t` and `p`
+#' @param ext Extension of the image files that will be stored on disk
+#' @param zoom Float that determines how far the brains are zoomed in
+#' @param compose Logical; if TRUE, a single compiled image will be made (requires Magick++)
+#' @param plot_brain Logical; if TRUE, returns a graphical device with the composed images
+#' @param save_plot Logical; if TRUE, saves the composed image
+#' @param sig Logical; if TRUE, only the significant clusters are shown
+#' @param ... any arguments that freeview (on command line) normally takes for manipulating surface files
+#' @return NULL
+#' @export
 
 qdecr_snap <- function(vw, stack = NULL, type = c("coef", "se", "t", "p"), ext = ".tiff", zoom = 1, compose = TRUE, plot_brain = TRUE, save_plot = TRUE, sig = TRUE, ...) {
   if (is.null(stack)) stop("`stack` not defined. Please choose: ", paste(stacks(vw), collapse = ", "))
@@ -195,7 +196,7 @@ qdecr_snap <- function(vw, stack = NULL, type = c("coef", "se", "t", "p"), ext =
                 qsnap(snap_names[4]),
                 "--quit")
   tfile <- file.path(vw$paths$dir_tmp, "tmp_snapshot_qdecr.txt")
-  write.table(snap_cmd, tfile, quote = F, row.names = F, col.names = F)
+  utils::write.table(snap_cmd, tfile, quote = F, row.names = F, col.names = F)
   on.exit(file.remove(tfile))
 
   type <- match.arg(type)
@@ -271,7 +272,7 @@ qdecr_snap <- function(vw, stack = NULL, type = c("coef", "se", "t", "p"), ext =
     ia1 <- magick::image_append(nn2[1:2])
     ia2 <- magick::image_append(nn2[3:4])
     p <- magick::image_append(c(ia1, ia2), stack = TRUE)
-    if (plot_brain) print(plot(p))
+    if (plot_brain) print(graphics::plot(p))
     if (save_plot) magick::image_write(p, paste0(name, ".", "plot", ext))
     return(p)
   } else {

R/qdecr.R

@@ -6,14 +6,36 @@
 #' .mgh format data as input and allows statistical analyses per vertex. A variety
 #' of statistical models have been implemented, such as linear regression.
 #' 
-#' @param a test
-#' @param b test
-#' @param c test
-#' @param d test
-#' @param e test
-#' @param f test
-#' @param g test
-#' @param h test
+#' @param id the name of the id variable that matches the dataset to the Freesurfer output
+#' @param data a required argument that contains a data frame, a list of data frames or an imputed object that is supported by the `imp2list` function (mice, mi, etc.).
+#' @param vertex the preposition to the vertex measure (default: "qdecr_")
+#' @param margs the arguments that should be provided to the function of interest (e.g. stats::lm)
+#' @param model the function to grab the arguments from (this will be removed in a later version)
+#' @param target the target template (default = "fsaverage")
+#' @param hemi hemisphere to analyze ("lh" or "rh")
+#' @param measure the vertex-wise measure to use ("thickness", "area", etc.)
+#' @param fwhm full width half max (default = 10 mm, for pial_lgi it is 5 mm)
+#' @param mcz_thr A numeric value for the Monte Carlo simulation threshold (default: 0.001). Any of the following are accepted (equivalent values separate by `/`): 13/1.3/0.05, 20/2.0/0.01, 23/2.3/0.005, 30/3.0/0.001, 33/3.3/0.0005, 40/4.0/0.0001.
+#' @param cwp_thr the cluster-wise p-value threshold on top of all correction (default = 0.025, as there are 2 hemispheres)
+#' @param mgh NOT IMPLEMENTED; path to existing merged mgh file, default is NULL
+#' @param mask mgh file to mask analysis; default is to use the cortex label from the target
+#' @param mask_path path to the mask; default is the cortex mask that is provided with the QDECR package
+#' @param project the base name you want to assign to the output files
+#' @param dir_subj directory contain the surface-based maps (mgh files); defaults to SUBJECTS_DIR
+#' @param dir_fshome Freesurfer directory; defaults to FREESURFER_HOME
+#' @param dir_tmp directory to store the temporary big matrices; useful for shared memory; defaults to `dir_out`
+#' @param dir_out the directory where to save the data to (defaults to the current directory)
+#' @param dir_out_tree if TRUE, creates a dir_out/project directory. If FALSE, all output is placed directory into dir_out
+#' @param file_out_tree if TRUE, adds the full project name to the output file names. By default it is the inverse of dir_out_tree
+#' @param clean_up NOT IMPLEMENTED; will be used for setting cleaning of other files
+#' @param clean_up_bm if TRUE, cleans all big matrices (.bk) that were generated in dir_tmp
+#' @param clobber if TRUE, ignores already existing directories and writes over them; if FALSE, stops and warns user that a given directory already exists
+#' @param verbose if TRUE, writes out standard log; if FALSE, no output is generated
+#' @param debug NOT IMPLEMENTED; will output the maximal log to allow for easy debugging
+#' @param n_cores the number of cores to be used
+#' @param prep_fun Name of the function that needs to be called for the preparation step (do not touch unless you know what you are doing!)
+#' @param analysis_fun Name of the function that needs to be called for the analysis step (do not touch unless you know what you are doing!)
+#' @param chunk_size Integer; the desired chunk size for the chunked lm
 #' 
 #' @return out
 #' @importFrom foreach %dopar%
@@ -52,14 +74,13 @@ qdecr <- function(id,
                   n_cores = 1,
                   prep_fun = "prep_fastlm",
                   analysis_fun = "analysis_chunkedlm",
-                  chunk_size = 1000,
-                  sander = FALSE
+                  chunk_size = 1000
                   ){
 
   if (verbose) {
     message("\n")
-    catprompt(paste0("QDECR v", packageVersion("QDECR")))
-    message(paste0("Welcome to QDECR (v", packageVersion("QDECR"), ")"))
+    catprompt(paste0("QDECR v", utils::packageVersion("QDECR")))
+    message(paste0("Welcome to QDECR (v", utils::packageVersion("QDECR"), ")"))
     message("Authors: Sander Lamballais & Ryan Muetzel")
     message("Website: www.qdecr.com")
     message("Repository: www.github.com/slamballais/QDECR")
@@ -187,7 +208,6 @@ qdecr <- function(id,
   catprompt("Summarizing results", verbose = verbose)
 
   # Post-describe
-  if (sander) return(vw)
   vw$describe <- qdecr_post_describe(vw, verbose = verbose)
   vw$summary <- summary(vw, verbose = verbose)
   if(clean_up_bm) vw$mgh <- NULL

R/qdecr_analysis.R

@@ -39,10 +39,11 @@ analysis_chunkedlm <- function(vw, chunk) {
   doParallel::registerDoParallel(cl)
   on.exit(parallel::stopCluster(cl))
 
-  capture.output(pb <- txtProgressBar(0, length(cstart), style = 3), file = "/dev/null")
+  utils::capture.output(pb <- utils::txtProgressBar(0, length(cstart), style = 3), file = "/dev/null")
 
+  i <- NULL
   foreach::foreach (i = seq_along(cstart), .combine = "c") %dopar% {
-    setTxtProgressBar(pb, i)
+    utils::setTxtProgressBar(pb, i)
 
     id <- iv[cstart[i]:cend[i]]
 

R/qdecr_decon.R

@@ -16,7 +16,7 @@ qdecr_extract <- function(margs, model){
 qdecr_setnames <- function(margs, model){
   m <- names(margs)
   if(is.null(m)) m <- rep("", length(margs))
-  f <- formalArgs(get2(model))
+  f <- methods::formalArgs(get2(model))
   f2 <- formals(get2(model))
   b <- which(m[-1] == "")
   m[b+1] <- f[!f %in% m[-1]][length(b)]