Merge branch 'label_means' into 'master'

Add function to extract label coordinates.

See merge request choh/rsanalysis!5

.Rbuildignore

@@ -3,3 +3,6 @@
 ^LICENSE\.md$
 ^readme\.md$
 ^data-raw$
+^\.gitlab-ci\.yml$
+^changelog\.md$
+^lint\.sh$

DESCRIPTION

 Package: rsAnalysis
 Title: High-Level Tools for rsfMRI analysis
-Version: 0.2.9000
+Version: 0.3
 Authors@R: 
     person(given = "Christian",
            family = "Hohenfeld",
@@ -22,6 +22,7 @@ Imports:
          igraph,
          littlehelpers,
          magrittr,
+         oro.nifti,
          parameters,
          rlang,
          rsfmri, 
@@ -36,6 +37,7 @@ Imports:
          utils
 Suggests:
     testthat,
-    lintr
+    lintr,
+    withr
 Depends: 
     R (>= 2.10)

NAMESPACE

@@ -10,6 +10,7 @@ export(binarize_graph)
 export(check_motion)
 export(compare_measure_group)
 export(group_plot)
+export(label_means)
 export(make_random_graphs)
 export(node_measures)
 export(node_plot)

R/label_means.R

+#' Get mean coordinates from a Nifti atlas file.
+#'
+#' @param atlas_file The path to the atlas file to extract coordinates from.
+#' @param atlas_label_file A text file containing associations between label
+#' numbers and names (optional).
+#' @param merge_by Numeric index of the column in the label file giving the
+#' label numbers.
+#' @param name_col Numeric index of the column in the label file giving the
+#' label names.
+#' @param max_labels A number of maximum allowed labels in the file. The
+#' default is probably reasonably high, but of course you can increase it as
+#' needed. This is mainly to avoid reading some non-atlas file.
+#'
+#' @return A table with coordinates with label number and if specified also
+#' the names of the regions.
+#' @export
+label_means <- function(atlas_file, atlas_label_file = NULL, merge_by = 1,
+                        name_col = 2, max_labels = 250) {
+    raw_atlas <- oro.nifti::readNIfTI(atlas_file)
+    labels <- unique(as.vector(raw_atlas@.Data))
+    labels <- labels[labels != 0]
+    if (length(labels) > max_labels) {
+        stop(paste("Too many labels, is this an atlas file?",
+                   "You can try adjusting the max_labels."))
+    }
+
+    extract_coords <- function(x) {
+        idx <- which(raw_atlas@.Data == x, arr.ind = TRUE)
+        mean_coord <- colMeans(idx)
+        c(mean_coord, label = x)
+    }
+
+    coords <- lapply(labels, extract_coords)
+    coords <- as.data.frame(do.call("rbind", coords))
+
+    if (!is.null(atlas_label_file)) {
+        stopifnot(merge_by != name_col)
+        regions <- utils::read.table(file = atlas_label_file, fill = TRUE)
+        regions <- regions[1:2]
+        names(regions)[merge_by] <- "label"
+        names(regions)[name_col] <- "region"
+        coords <- dplyr::left_join(coords, regions, by = "label")
+    }
+
+    coords
+}

R/plot_density.R

@@ -10,8 +10,9 @@
 plot_density <- function(rawtbl_list, what, label) {
   merged_tbl <- lapply(seq_along(names(rawtbl_list)), function(x)
     rawtbl_list[[x]] %>%
-      dplyr::mutate(group = names(rawtbl_list)[x])) %>%
-      do.call("rbind", .)
+      dplyr::mutate(group = names(rawtbl_list)[x]))
+
+  merged_tbl <- do.call("rbind", merged_tbl)
 
   cpal <- colour_palette()
 

changelog.md

 # Changelog
 
+## Version 0.3, 2021-07-08
+
+* Add label_means function to extract mean coordinates from atlas files
+
 ## Version 0.2, 2021-04-27
 
 * Merge most helpers from other projects into this main package

man/label_means.Rd

+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/label_means.R
+\name{label_means}
+\alias{label_means}
+\title{Get mean coordinates from a Nifti atlas file.}
+\usage{
+label_means(
+  atlas_file,
+  atlas_label_file = NULL,
+  merge_by = 1,
+  name_col = 2,
+  max_labels = 250
+)
+}
+\arguments{
+\item{atlas_file}{The path to the atlas file to extract coordinates from.}
+
+\item{atlas_label_file}{A text file containing associations between label
+numbers and names (optional).}
+
+\item{merge_by}{Numeric index of the column in the label file giving the
+label numbers.}
+
+\item{name_col}{Numeric index of the column in the label file giving the
+label names.}
+
+\item{max_labels}{A number of maximum allowed labels in the file. The
+default is probably reasonably high, but of course you can increase it as
+needed. This is mainly to avoid reading some non-atlas file.}
+}
+\value{
+A table with coordinates with label number and if specified also
+the names of the regions.
+}
+\description{
+Get mean coordinates from a Nifti atlas file.
+}

tests/testthat/test-label_means.R

+describe("label means", {
+    get_mindboggle_atlas <- function() {
+        # Mindboggle atlas is available at https://mindboggle.info/data.html
+        # under CC BY 4.0 licence.
+        utils::download.file(
+            url = "https://osf.io/d2cmy/?action=download&version=1",
+            destfile = "mindboggle.nii.gz"
+        )
+        withr::defer_parent(unlink("mindboggle.nii.gz"))
+    }
+
+    get_aal_atlas <- function() {
+        # nolint start
+        # AAL atlas is available from https://www.gin.cnrs.fr/en/tools/aal/
+        # The paper describing the version used here is:
+        # Automated anatomical labelling atlas 3. Rolls, E. T., Huang, C. C.,
+        # Lin, C. P., Feng, J., & Joliot, M., Neuroimage, 2020, 206, 116189,
+        # doi:10.1016/j.neuroimage.2019.116189
+        utils::download.file(
+            url = "http://www.gin.cnrs.fr/wp-content/uploads/AAL3v1_for_SPM12.zip",
+            destfile = "aal.zip"
+        )
+        # nolint end
+        utils::unzip("aal.zip",
+                     files = c("AAL3/AAL3v1_1mm.nii.gz",
+                               "AAL3/AAL3v1_1mm.nii.txt"))
+        withr::defer_parent(unlink("aal.zip"))
+        withr::defer_parent(unlink("AAL3", recursive = TRUE))
+    }
+
+    get_mindboggle_atlas()
+    get_aal_atlas()
+
+    it("reads an atlas and outputs mean coordinates as data frame", {
+        atlas_coords <- label_means("mindboggle.nii.gz")
+        expect_true(is.data.frame(atlas_coords))
+        # atlas has 96 regions
+        expect_equal(nrow(atlas_coords), 96)
+        expect_equal(ncol(atlas_coords), 4)
+    })
+
+    it("can also read an atlas with additional labels", {
+        atlas_coords <- label_means(
+            atlas_file = "AAL3/AAL3v1_1mm.nii.gz",
+            atlas_label_file = "AAL3/AAL3v1_1mm.nii.txt"
+        )
+        expect_true(is.data.frame(atlas_coords))
+        # atlas has 166 regions
+        expect_equal(nrow(atlas_coords), 166)
+        expect_equal(ncol(atlas_coords), 5)
+        expect_true(is.character(as.vector(atlas_coords[, 5])))
+    })
+
+    it("aborts if more regions than max_labels", {
+        expect_error(
+            label_means("mindboggle.nii.gz", max_labels = 2)
+        )
+    })
+})