R/RMINC.R

In Mouse-Imaging-Centre/RMINC: Statistical Tools for Medical Imaging NetCDF (MINC) Files

#' RMINC: R interface to the MINC universe
#' 
#' RMINC provides a means of accessing and performing statistical
#' analyses on MINC volumes. With facilities to calculate voxel-wise
#' statistics, perform FDR correction, rapidly visualize 
#' results, and much more.
#' @import dplyr
#' @import tidyr
#' @import shiny
#' @import Rcpp
#' @import lme4
#' @import batchtools
#' @import methods
#' @importFrom Matrix diag
#' @importFrom Matrix sparseMatrix
#' @importFrom Matrix Diagonal
#' @importFrom grDevices colorRampPalette gray.colors heat.colors rainbow
#'                       rgb
#' @importFrom graphics abline contour hist layout mtext par plot.default
#'                      plot.new rasterImage text segments points plot
#' @importFrom stats anova df.residual formula lm lm.fit
#'                   logLik median model.matrix p.adjust pchisq
#'                   pf predict pt pwilcox qchisq qf qt
#'                   quantile qwilcox rnorm runif sd setNames
#'                   simulate smooth.spline t.test terms var
#'                   update vcov AIC BIC getCall aggregate optimize
#' @importFrom utils download.file capture.output glob2rx read.csv read.table 
#'                   untar write.table
#' @importFrom grid plotViewport popViewport pushViewport
#' @importFrom gridBase baseViewports
#' @importFrom yaml yaml.load_file
#' @importFrom data.tree FindNode Clone isLeaf Traverse Aggregate isNotLeaf
#'                       SetGraphStyle FromListSimple as.Node
#' @importFrom visNetwork visNetwork visNodes visEdges visHierarchicalLayout
#'                        visPhysics
#' @importFrom rjson fromJSON
#' @importFrom purrr map map_df map2
#' @importFrom rlang UQ quo
#' @useDynLib RMINC, .registration = TRUE 
#' @docType package
#' @name RMINC
NULL

#' Voxel Atlas Definitions
#' 
#' Voxel based analyses often require an atlas to differentiate
#' voxels by structure membership. In conjunction with the atlas, 
#' a set of atlas definitions allow you to calculate summaries by region
#' for measures and statistics of interest. For example the \code{defs} 
#' argument of \link{anatGetAll} is a character vector
#' pointing to atlas definitions.
#' 
#' @details
#' the basic format for voxel atlas definitions is a 3-column csv
#' file. The file should be formatted like: \cr
#' \tabular{lrr}{
#' Structure \tab right.label \tab left.label \cr
#' amygdala \tab 51 \tab 151 \cr
#' anterior commisure: pars anterior \tab 115 \tab 215 
#' }
#' The csv file may contain additional columns, but the
#' three columns above must by present with names spelling/case
#' sensitive. Additional columns may include a tissue.type
#' column which is used in some functions.
#' 
#' @name voxel_atlas_defs
NULL

#' RMINC Masked Value
#' 
#' RMINC_MASKED_VALUE is an object with the S3 class "RMINC_MASKED_VALUE" with NA value 
#' used to differentiate whether an NA was generated by the user or by an RMINC masking
#' procedure. The value, which will be written out with \link{mincWriteVolume}, can be changed
#' to zero for example with \link{setRMINCMaskedValue}.
#' @name RMINC_MASKED_VALUE
NULL


### Package initialization function, syncs environment vars and defines defaults
.onLoad <-
  function(libname, pkgname){
    empty_to_null <- function(x){
      `if`(x == "", NULL, x)
    }
    
    #Set default options taken from Hadley's r-packages book
    op <- options()
    
    op.RMINC <- list(
      RMINC_MASKED_VALUE = 
        structure(0, class = "RMINC_MASKED_VALUE")
    , RMINC_LABEL_DEFINITIONS =
        empty_to_null(Sys.getenv("RMINC_LABEL_DEFINITIONS"))          
    , RMINC_BATCH_CONF =
        `if`(Sys.getenv("RMINC_BATCH_CONF") == ""
           , system.file("parallel/pbs_batchtools.R", package = "RMINC")
           , Sys.getenv("RMINC_BATCH_CONF"))
    , RMINC_DATA_DIR =
        empty_to_null(Sys.getenv("RMINC_DATA_DIR"))           
    )
    
    toset <- !(names(op.RMINC) %in% names(op))
    if(any(toset)) options(op.RMINC[toset])
    
    invisible()
  }

# Silence warning about magrittr/dplyr dot
# a la https://github.com/smbache/magrittr/issues/29
utils::globalVariables(".")
utils::globalVariables(".data")