Merge pull request #58 from mandymejia/13.0

13.0

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: ciftiTools
 Type: Package
 Title: Tools for Reading, Writing, Viewing and Manipulating CIFTI Files
-Version: 0.12.2
+Version: 0.13.4
 Authors@R: c(
     person(given = "Amanda",
            family = "Mejia",
@@ -55,6 +55,6 @@ Suggests:
     png,
     testthat (>= 3.0.0)
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.0
 URL: https://github.com/mandymejia/ciftiTools
 BugReports: https://github.com/mandymejia/ciftiTools/issues

NAMESPACE

@@ -27,6 +27,9 @@ export(ciftiTools.getOption)
 export(ciftiTools.listOptions)
 export(ciftiTools.setOption)
 export(combine_xifti)
+export(convert_to_dlabel)
+export(convert_to_dscalar)
+export(convert_to_dtseries)
 export(convert_xifti)
 export(dilate_mask_surf)
 export(edit_mask_surf)
@@ -54,13 +57,20 @@ export(merge_xifti)
 export(move_from_mwall)
 export(move_to_mwall)
 export(newdata_xifti)
+export(parc_add_subcortex)
 export(parc_borders)
+export(parc_vals_to_xifti)
 export(readCIfTI)
 export(read_cifti)
 export(read_surf)
 export(read_xifti)
 export(read_xifti2)
 export(readcii)
+export(remapCIfTI)
+export(remap_cifti)
+export(remap_gifti)
+export(remap_xifti)
+export(remapcii)
 export(remove_xifti)
 export(resampleCIfTI)
 export(resampleGIfTI)
@@ -88,6 +98,7 @@ export(smoothcii)
 export(smoothgii)
 export(substructure_table)
 export(supported_intents)
+export(surf_area)
 export(transform_xifti)
 export(unmask_subcortex)
 export(use_color_pal)

NEWS.md

@@ -1,3 +1,25 @@
+# 13.2
+
+`ciftiTools` now has a couple functions which make working with parcellations easier. (A parcellation is a single-column dlabel CIFTI or `"xifti"` object. Each label level, or "Key", represents a "parcel." Each location belongs to exactly one parcel. Parcels are usually contiguous regions--but not necessarily. `ciftiTools` includes a few of the most commonly-used parcellations. These can be loaded with `load_parc`. Any other parcellation CIFTI file can be read in with `read_cifti`.)
+* `apply_parc`: Apply a parcellation `"xifti"` to a data `"xifti"`. Can be used to compute the mean of each column, e.g. for FC calculation, but also supports applying any other function parcel-wise.
+* `parc_vals_to_xifti`: Create a `"xifti"` from a parcellation and a numeric matrix of values corresponding to each parcel.
+
+Other new functions:
+* `remap_cifti`: an extension of resampling. Beware, we might revamp this function in the future.
+* `surf_area`: computes the surface area attributable to each vertex or face of a `"surf"` object.
+
+Changes to existing functions:
+* `convert_xifti`, `convert_to_dlabel`: arguments related to levels & labels have been renamed to match `factor` more closely.
+* `separate_cifti` and `write_xifti2`: now require users to provide either the `write_dir` argument, or file names for each desired output file. This gives users more flexibility to control which files are written. 
+* `view_xifti` qualitative color legend: add black outline.
+* `view_xifti`, `view_volume`: print out indices of the selected subcortical slices.
+* `unmask_subcortex`: now expects `xifti` input. If necessary, use the internal function `ciftiTools:::unvec_vol` to unmask a numeric matrix directly.
+
+Bug fixes:
+* `view_xifti`: fix bug where legend image was still written if `legend_fname=NULL`.
+
+13.1 also includes misc. documentation and warning improvements.
+
 # 12.0 (Jul 28, 2023)
 
 New features

R/add_surf.R

@@ -16,16 +16,15 @@
 #'
 #' @return the \code{"xifti"} object with added surface geometry components.
 #'
-#' @family manipulating
+#' @family manipulating xifti
+#' @family surface-related
 #' @export
 #'
 add_surf <- function(xifti, surfL=NULL, surfR=NULL) {
   if (!is.xifti(xifti)) { stop("The input \"xifti\" object is invalid.") }
 
   resamp_res <- infer_resolution(xifti)
-  if (all(resamp_res %in% c(NA, NaN))) {
-    resamp_res <- NULL
-  }
+  if (all(is.na(resamp_res))) { resamp_res <- NULL }
 
   # Left.
   if (!is.null(surfL)) {

R/apply_xifti.R

@@ -18,7 +18,7 @@
 #' @return A \code{"xifti"} if \code{margin == 1}, or a numeric matrix if 
 #'  \code{margin == 2}
 #' 
-#' @family manipulating
+#' @family manipulating xifti
 #' @export
 #' 
 apply_xifti <- function(xifti, margin=c(1,2), FUN, ...) {

R/as.gifti.R

@@ -1,13 +1,13 @@
 #' Format metric data as a \code{"gifti"}
 #'
-#' Format a \eqn{V x T} numeric matrix (V vertices, T measurements) or a length-T list 
+#' Format a \eqn{V \times T} numeric matrix (V vertices, T measurements) or a length-T list 
 #'  of length-V numeric vectors as a \code{"gifti"} using a template 
 #'  \code{"gifti"}. The brain hemisphere (left or right) must be indicated.
 #' 
 #'  If \code{data} is already a \code{"gifti"}, \code{data$data} will be
 #'  used and any metadata will be overwritten by the template or discarded.
 #'
-#' @param data \eqn{V x T} numeric matrix, or length \eqn{T} list of length
+#' @param data \eqn{V \times T} numeric matrix, or length \eqn{T} list of length
 #'  \eqn{V} numeric vectors
 #' @param hemisphere The side of the brain the data represents: \code{"left"} 
 #'  (default) or \code{"right"}. Used to fill the "AnatomicalStructurePrimary"

R/as.xifti.R

@@ -10,15 +10,15 @@
 #'  matrix or vector.
 #' 
 #'  If \code{cortexL_mwall} is not provided, \code{cortexL} should have data for
-#'  all vertices on the left cortical surface (\eqn{V_L x T} data matrix). There 
+#'  all vertices on the left cortical surface (\eqn{V_L \times T} data matrix). There 
 #'  will not be a mask for the medial wall. Not providing the medial wall mask 
 #'  is appropriate for ".dlabels.nii" files where the medial wall may have its 
 #'  own label and therefore should not be treated as missing data.
 #' 
 #'  If \code{cortexL_mwall} is provided, \code{cortexL} should either have data
-#'  for all vertices on the left cortical surface (\eqn{V_L x T} data matrix, with
+#'  for all vertices on the left cortical surface (\eqn{V_L \times T} data matrix, with
 #'  filler values e.g. \code{0} or \code{NaN} for medial wall vertices), or have data 
-#'  only for non-medial wall vertices (\eqn{(V_L - mwall_L) x T} data matrix).
+#'  only for non-medial wall vertices (\eqn{(V_L - mwall_L) \times T} data matrix).
 #'  The medial wall mask will be the \code{0} values in \code{cortexL_mwall}. 
 #'  The medial wall mask should be provided whenever the medial wall should be
 #'  treated as missing data. 
@@ -29,15 +29,15 @@
 #'  matrix or vector.
 #' 
 #'  If \code{cortexR_mwall} is not provided, \code{cortexR} should have data for
-#'  all vertices on the right cortical surface (\eqn{V_R x T} data mre 
+#'  all vertices on the right cortical surface (\eqn{V_R \times T} data mre 
 #'  will not be a mask for the medial wall. Not providing the medial wall mask 
 #'  is appropriate for ".dlabels.nii" files where the medial wall may have its 
 #'  own label and therefore should not be treated as missing data.
 #' 
 #'  If \code{cortexR_mwall} is provided, \code{cortexR} should either have data
-#'  for all vertices on the right cortical surface (\eqn{V_R x T} data matrix, with
+#'  for all vertices on the right cortical surface (\eqn{V_R \times T} data matrix, with
 #'  filler values e.g. \code{0} or \code{NaN} for medial wall vertices), or have data 
-#'  only for non-medial wall vertices (\eqn{(V_R - mwall_R) x T} data matrix).
+#'  only for non-medial wall vertices (\eqn{(V_R - mwall_R) \times T} data matrix).
 #'  The medial wall mask will be the \code{0} values in \code{cortexR_mwall}. 
 #'  The medial wall mask should be provided whenever the medial wall should be
 #'  treated as missing data. 
@@ -46,19 +46,19 @@
 #'  \code{V_L} should match \code{V_R}.
 #' @param subcortVol,subcortLabs,subcortMask \code{subcortVol} represents the
 #'  data values of the subcortex. It is either a 3D/4D numeric array
-#'  (\eqn{i x j x k x T}), or a vectorized matrix (\eqn{V_S} voxels by \eqn{T} 
+#'  (\eqn{i \times j \times k \times T}), or a vectorized matrix (\eqn{V_S} voxels by \eqn{T} 
 #'  measurements). If it's vectorized, the voxels should be in spatial order 
 #'  (\eqn{i} index increasing fastest, then \eqn{j}, then \eqn{k}).
 #' 
 #'  \code{subcortLabs} represents the brainstructure labels of each voxel: see
 #'  \code{\link{substructure_table}}. It is either a 3D data array 
-#'  (\eqn{i x j x k}) of integer brainstructure indices, or a \eqn{V_S} length
+#'  (\eqn{i \times j \times k}) of integer brainstructure indices, or a \eqn{V_S} length
 #'  vector in spatial order with brainstructure names as factors or integer
 #'  indices. The indices should be 3-21 (1 and 2 correspond to left and right
 #'  cortex, respectively) or 1-19 (cortex labels omitted), with 0 representing
 #'  out-of-mask voxels.
 #'  
-#'  \code{subcortMask} is logical 3D data array (\eqn{i x j x k}) where \code{TRUE}
+#'  \code{subcortMask} is logical 3D data array (\eqn{i \times j \times k}) where \code{TRUE}
 #'  values indicate subcortical voxels (in-mask). If it is not provided, the
 #'  mask will be inferred from voxels with labels \code{0}, \code{NA}, or 
 #'  \code{NaN} in \code{subcortLabs}. If \code{subcortLabs} are vectorized and 

R/ciftiTools-package.R

@@ -1,10 +1,12 @@
+## usethis namespace: start
+## usethis namespace: end
 #' ciftiTools: Tools for Reading and Visualizing CIFTI Brain Files
 #' 
 #' Here are groups of commonly-used functions in \code{ciftiTools}:
 #'
 #' Functions for reading in CIFTI or GIFTI data:
 #' 
-#' \itemize{
+#' \describe{
 #'  \item{\code{read_xifti}:}{   Read in a CIFTI file as a \code{"xifti"}}
 #'  \item{\code{read_xifti2}:}{   Read in GIFTI files as a \code{"xifti"}}
 #'  \item{\code{as.xifti}:}{   Combine numeric data to form a \code{"xifti"}}
@@ -16,7 +18,7 @@
 #' 
 #' Functions for writing CIFTI or GIFTI data:
 #' 
-#' \itemize{
+#' \describe{
 #'  \item{\code{write_cifti}:}{   Write a \code{"xifti"} to a CIFTI file}
 #'  \item{\code{write_xifti2}:}{   Write a \code{"xifti"} to GIFTI and NIFTI files}
 #'  \item{\code{write_metric_gifti}:}{   Write a numeric data matrix to a metric GIFTI file}
@@ -27,7 +29,7 @@
 #' 
 #' Functions for manipulating \code{"xifti"}s:
 #' 
-#' \itemize{
+#' \describe{
 #'  \item{\code{apply_xifti}:}{   Apply a function along the rows or columns of the \code{"xifti"} data matrix}
 #'  \item{\code{combine_xifti}:}{   Combine multiple \code{"xifti"}s with non-overlapping brain structures}
 #'  \item{\code{convert_xifti}:}{   Convert the intent of a \code{"xifti"}}
@@ -43,7 +45,7 @@
 #' 
 #' S3 methods for \code{"xifti"}s:
 #' 
-#' \itemize{
+#' \describe{
 #'  \item{\code{summary} and \code{print}:}{   Summarize the contents.}
 #'  \item{\code{as.matrix}:}{   Convert data to a locations by measurements numeric matrix.}
 #'  \item{\code{dim}:}{    Obtain number of locations and number of measurements.}
@@ -54,7 +56,7 @@
 #' 
 #' Functions for working with surfaces:
 #' 
-#' \itemize{
+#' \describe{
 #'  \item{\code{read_surf}:}{   Read in a surface GIFTI file as a \code{"surf"}}
 #'  \item{\code{is.surf}:}{   Verify a \code{"surf"}}
 #'  \item{\code{write_surf_gifti}:}{   Write a \code{"surf"} to a surface GIFTI file}
@@ -63,6 +65,5 @@
 #'  \item{\code{rotate_surf}:}{   Rotate the geometry of a \code{"surf"}}
 #' }
 #'
-#' @docType package
 #' @name ciftiTools
-NULL
+"_PACKAGE"

R/combine_xifti.R

@@ -11,7 +11,7 @@
 #'  argument, or \code{"all"} to include the other metadata in a list.
 #' @return A \code{"xifti"} with data from the inputs
 #' 
-#' @family manipulating
+#' @family manipulating xifti
 #' @export
 #' 
 combine_xifti <- function(..., xii_list=NULL, meta=c("first", "all")) {
@@ -68,7 +68,7 @@ combine_xifti <- function(..., xii_list=NULL, meta=c("first", "all")) {
     # Intent.
     dlabel_ii <- (!is.null(xiis[[ii]]$meta$cifti$intent)) && (xiis[[ii]]$meta$cifti$intent == 3007)
     if (dlabel_out && (!dlabel_ii)) {
-      xiis[[ii]] <- convert_to_dlabel(xiis[[ii]], values=dlabel_vals)
+      xiis[[ii]] <- convert_to_dlabel(xiis[[ii]], levels=dlabel_vals)
     }
 
     # Combine data.