Docs/convoxel

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: ModelArray
 Title: An R package for statistical analysis of fixel-wise data
-Version: 0.1.3
+Version: 0.1.3.9000
 Authors@R:
     c(person(given = "Chenying",
            family = "Zhao",

R/analyse.R

@@ -426,9 +426,12 @@ ModelArray.lm <- function(formula, data, phenotypes, scalar, element.subset = NU
 #' }
 #' You may be interested in how important a term is in a model. We provide two ways of quantification (see below). Both of them require running the reduced model without this term of interest, thus it will take longer time to run. You can make such request via argument \code{changed.rsq.term.index}, and you'll get both quantifications.
 #' \itemize{
-#'   \item Delta adjusted R-squared (delta.adj.rsq) is defined as the difference between adjusted R-squared of full model (full formula in \code{formula}) and that of reduced model (formula without the term of interest). Notice that adjusted R-squared includes the penalty from the model complexity.
-#'   \item Partial R-squared (partial.rsq) is defined as: (sse.reduced.model - sse.full.model) / sse.reduced.model, where sse is the error sum of squares (or, residual sum of squares). It quantifies the amount of variance in the response variable that cannot be explained by the reduced model (model without term of interest), but can be explained by the term of interest in the full model.
+#'   \item Delta adjusted R-squared (\code{delta.adj.rsq}) is defined as the difference between adjusted R-squared of full model (full formula in \code{formula}) and that of reduced model (formula without the term of interest). Notice that adjusted R-squared includes the penalty from the model complexity.
+#'   \item Partial R-squared (\code{partial.rsq}) is defined as: \code{(sse.reduced.model - sse.full.model) / sse.reduced.model}, where \code{sse} is the error sum of squares (or, residual sum of squares). It quantifies the amount of variance in the response variable that cannot be explained by the reduced model (model without term of interest), but can be explained by the term of interest in the full model.
 #' }
+#' ___!!! WARNING !!!___: If you want to request \code{changed.rsq.term.index} for a term that has missing values, before feeding \code{phenotypes} into \code{ModelArray.gam()}, you must exclude those observations (i.e., those rows in \code{phenotypes}) who have missing values in this term of interest from \code{phenotypes}. 
+#' You should do the same for each term you'd like to request in \code{changed.rsq.term.index}, if that term has missing values. 
+#' Without such exclusion, the full and reduced models would include different number of subjects, causing inaccuracy of calculation of \code{delta.adj.rsq} and \code{partial.rsq}. \cr \cr
 #' Other notes on \code{changed.rsq.term.index}:
 #' \itemize{
 #'   \item When requesting \code{changed.rsq.term.index}, \code{fx} should be set as \code{TRUE}, so that degree of freedom is fixed.
@@ -447,7 +450,7 @@ ModelArray.lm <- function(formula, data, phenotypes, scalar, element.subset = NU
 #' @param var.smoothTerms A list of characters. The list of variables to save for smooth terms (got from `broom::tidy(parametric = FALSE)`). Example smooth term: age in formula "outcome ~ s(age)". See "Details" section for more.
 #' @param var.parametricTerms A list of characters. The list of variables to save for parametric terms (got from `broom::tidy(parametric = TRUE)`). Example parametric term: sex in formula "outcome ~ s(age) + sex". See "Details" section for more.
 #' @param var.model A list of characters. The list of variables to save for the model (got from `broom::glance()` and `summary()`). See "Details" section for more.
-#' @param changed.rsq.term.index A list of (one or several) positive integers. Each element in the list means the i-th term of the formula's right hand side as the term of interest for changed R-squared between with and without it. Both delta adjusted R-squared and partial R-squared will be calculated for each of term requested. Usually term of interest is smooth term, or interaction term in models with interactions.
+#' @param changed.rsq.term.index A list of (one or several) positive integers. Each element in the list means the i-th term of the formula's right hand side as the term of interest for changed R-squared between with and without it. Both delta adjusted R-squared and partial R-squared will be calculated for each of term requested. Usually term of interest is smooth term, or interaction term in models with interactions. See "Details" section for more, especially the "WARNING" in Details section for cases with caution!!
 #' @param correct.p.value.smoothTerms A list of characters. To perform and add a column for p.value correction for each smooth term. Default: "fdr". See "Details" section for more.
 #' @param correct.p.value.parametricTerms A list of characters. To perform and add a column for p.value correction for each parametric term. Default: "fdr". See "Details" section for more.
 #' @param num.subj.lthr.abs An integer, lower threshold of absolute number of subjects. For an element, if number of subjects who have finite values (defined by `is.finite()`, i.e. not NaN or NA or Inf) in h5 file > \code{num.subj.lthr.abs}, then this element will be run normally; otherwise, this element will be skipped and statistical outputs will be set as NaN. Default is 10.

README.Rmd

@@ -19,12 +19,30 @@ knitr::opts_chunk$set(
 [![CircleCI build status](https://circleci.com/gh/PennLINC/ModelArray.svg?style=svg)](https://circleci.com/gh/PennLINC/ModelArray)
 <!-- badges: end -->
 
-`ModelArray` is an R package for statistical analysis of fixel-wise data. Its features include:
+`ModelArray` is an R package for statistical analysis of fixel-wise data and beyond. Its features include:
 
 * Easy to use: set up your statistical analysis with just several lines of code;
 * Supporting linear and nonlinear modeling, and extensible to more models: 
-  * At present, `ModelArray` supports linear models as well as generalized additive models (GAMs) with and without penalized splines, which are particularly useful for studying nonlinear effects in lifespan data. ModelArray is also extensible to diverse models available in R.
-* Scalable for large-scale datasets.
+  * At present, `ModelArray` supports linear models as well as generalized additive models (GAMs) with and without penalized splines, which are particularly useful for studying nonlinear effects in lifespan data. `ModelArray` is also extensible to diverse models available in R;
+* Scalable for large-scale datasets;
+* Compatible with fixel-wise data and voxel-wise data.
+
+Please cite our [bioRxiv preprint article](https://doi.org/10.1101/2022.07.12.499631) if you use `ModelArray`: 
+
+> Zhao, C., Tapera, T. M., Bagautdinova, J., Bourque, J., Covitz, S., Gur, R. E., Gur, R. C., Larsen, B., Mehta, K., Meisler, S. L., Murtha, K., Muschelli, J., Roalf, D. R., Sydnor, V. J., Valcarcel, A. M., Shinohara, R. T., Cieslak, M. & Satterthwaite, T. D. (2022). ModelArray: a memory-efficient R package for statistical analysis of fixel data. bioRxiv. https://doi.org/10.1101/2022.07.12.499631
+
+
+## Overview
+
+<center>
+
+![Overview](vignettes/overview_structure.png)
+
+</center>
+
+ModelArray is packaged with the companion software [ConFixel](https://github.com/PennLINC/ConFixel) for converting fixel-wise data and voxel-wise data to the expected file format that ModelArray uses. Specifically, [ConFixel](https://github.com/PennLINC/ConFixel) is Python-based command-line interface software, and it converts between the original image format (`.mif` for fixel-wise data, NIfTI for voxel-wise data) and the HDF5 file format (`.h5`) used for ModelArray.
+
+<!-- if there is any changes in this overview section, please also update ConFixel's frontpage! -->
 
 ## Installation
 Please refer to webpage [Installation](https://pennlinc.github.io/ModelArray/articles/installations.html) for a full guidance of installation of `ModelArray` and its companion python package [ConFixel](https://github.com/PennLINC/ConFixel). The most important steps for installing `ModelArray` are:
@@ -42,7 +60,7 @@ Load the `ModelArray` package into R via:
 library(ModelArray)
 ```
 
-We provide a walkthrough [here](https://pennlinc.github.io/ModelArray/articles/walkthrough.html).
+We provide a walkthrough [here](https://pennlinc.github.io/ModelArray/articles/walkthrough.html) with example fixel-wise data. For additional notes on application to voxel-wise data, please refer to [here](https://pennlinc.github.io/ModelArray/articles/voxel-wise_data.html).
 
 For documentation of `ModelArray` functions, you can:
 

README.md

@@ -9,19 +9,50 @@
 status](https://circleci.com/gh/PennLINC/ModelArray.svg?style=svg)](https://circleci.com/gh/PennLINC/ModelArray)
 <!-- badges: end -->
 
-`ModelArray` is an R package for statistical analysis of fixel-wise
-data. Its features include:
-
--   Easy to use: set up your statistical analysis with just several
-    lines of code;
--   Supporting linear and nonlinear modeling, and extensible to more
-    models:
-    -   At present, `ModelArray` supports linear models as well as
-        generalized additive models (GAMs) with and without penalized
-        splines, which are particularly useful for studying nonlinear
-        effects in lifespan data. ModelArray is also extensible to
-        diverse models available in R.
--   Scalable for large-scale datasets.
+`ModelArray` is an R package for statistical analysis of fixel-wise data
+and beyond. Its features include:
+
+- Easy to use: set up your statistical analysis with just several lines
+  of code;
+- Supporting linear and nonlinear modeling, and extensible to more
+  models:
+  - At present, `ModelArray` supports linear models as well as
+    generalized additive models (GAMs) with and without penalized
+    splines, which are particularly useful for studying nonlinear
+    effects in lifespan data. `ModelArray` is also extensible to diverse
+    models available in R;
+- Scalable for large-scale datasets;
+- Compatible with fixel-wise data and voxel-wise data.
+
+Please cite our [bioRxiv preprint
+article](https://doi.org/10.1101/2022.07.12.499631) if you use
+`ModelArray`:
+
+> Zhao, C., Tapera, T. M., Bagautdinova, J., Bourque, J., Covitz, S.,
+> Gur, R. E., Gur, R. C., Larsen, B., Mehta, K., Meisler, S. L., Murtha,
+> K., Muschelli, J., Roalf, D. R., Sydnor, V. J., Valcarcel, A. M.,
+> Shinohara, R. T., Cieslak, M. & Satterthwaite, T. D. (2022).
+> ModelArray: a memory-efficient R package for statistical analysis of
+> fixel data. bioRxiv. <https://doi.org/10.1101/2022.07.12.499631>
+
+## Overview
+
+<center>
+
+![Overview](vignettes/overview_structure.png)
+
+</center>
+
+ModelArray is packaged with the companion software
+[ConFixel](https://github.com/PennLINC/ConFixel) for converting
+fixel-wise data and voxel-wise data to the expected file format that
+ModelArray uses. Specifically,
+[ConFixel](https://github.com/PennLINC/ConFixel) is Python-based
+command-line interface software, and it converts between the original
+image format (`.mif` for fixel-wise data, NIfTI for voxel-wise data) and
+the HDF5 file format (`.h5`) used for ModelArray.
+
+<!-- if there is any changes in this overview section, please also update ConFixel's frontpage! -->
 
 ## Installation
 
@@ -31,10 +62,10 @@ for a full guidance of installation of `ModelArray` and its companion
 python package [ConFixel](https://github.com/PennLINC/ConFixel). The
 most important steps for installing `ModelArray` are:
 
--   Make sure you have necessary libraries for HDF5 - see [this
-    section](https://pennlinc.github.io/ModelArray/articles/installations.html#install-hdf5-libraries-in-the-system)
--   Install `ModelArray` from GitHub - see [this
-    section](https://pennlinc.github.io/ModelArray/articles/installations.html#install-modelarray-r-package-from-github)
+- Make sure you have necessary libraries for HDF5 - see [this
+  section](https://pennlinc.github.io/ModelArray/articles/installations.html#install-hdf5-libraries-in-the-system)
+- Install `ModelArray` from GitHub - see [this
+  section](https://pennlinc.github.io/ModelArray/articles/installations.html#install-modelarray-r-package-from-github)
 
 Additionally, we also provide a [container
 image](https://hub.docker.com/r/pennlinc/modelarray_confixel) that
@@ -55,14 +86,17 @@ library(ModelArray)
 ```
 
 We provide a walkthrough
-[here](https://pennlinc.github.io/ModelArray/articles/walkthrough.html).
+[here](https://pennlinc.github.io/ModelArray/articles/walkthrough.html)
+with example fixel-wise data. For additional notes on application to
+voxel-wise data, please refer to
+[here](https://pennlinc.github.io/ModelArray/articles/voxel-wise_data.html).
 
 For documentation of `ModelArray` functions, you can:
 
--   Either go to [this
-    webpage](https://pennlinc.github.io/ModelArray/reference/index.html);
--   Or in R console, type: `help(<function_name>)`. For example:
-    `help(ModelArray.lm)`
+- Either go to [this
+  webpage](https://pennlinc.github.io/ModelArray/reference/index.html);
+- Or in R console, type: `help(<function_name>)`. For example:
+  `help(ModelArray.lm)`
 
 Full documentation of `ModelArray` can be found
 [here](https://pennlinc.github.io/ModelArray/).

_pkgdown.yml

@@ -39,6 +39,7 @@ articles:
   - installations
   - walkthrough
   - container
+  - voxel-wise_data
   - doc_for_developer
 
 - title: More