init

.Rbuildignore

@@ -0,0 +1,9 @@
+^neuromat\.Rproj$
+^\.Rproj\.user$
+^LICENSE\.md$
+^README\.Rmd$
+^\.github$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$
+^man-roxygen$

.github/.gitignore

@@ -0,0 +1 @@
+*.html

.github/workflows/R-CMD-check.yaml

@@ -0,0 +1,49 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+name: R-CMD-check
+
+jobs:
+  R-CMD-check:
+    runs-on: ${{ matrix.config.os }}
+
+    name: ${{ matrix.config.os }} (${{ matrix.config.r }})
+
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - {os: macos-latest,   r: 'release'}
+          - {os: windows-latest, r: 'release'}
+          - {os: ubuntu-latest,   r: 'devel', http-user-agent: 'release'}
+          - {os: ubuntu-latest,   r: 'release'}
+          - {os: ubuntu-latest,   r: 'oldrel-1'}
+
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      R_KEEP_PKG_SOURCE: yes
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: ${{ matrix.config.r }}
+          http-user-agent: ${{ matrix.config.http-user-agent }}
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+
+      - uses: r-lib/actions/check-r-package@v2
+        with:
+          upload-snapshots: true

.github/workflows/pkgdown.yaml

@@ -0,0 +1,48 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: pkgdown
+
+jobs:
+  pkgdown:
+    runs-on: ubuntu-latest
+    # Only restrict concurrency for non-PR jobs
+    concurrency:
+      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::pkgdown, local::.
+          needs: website
+
+      - name: Build site
+        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+        shell: Rscript {0}
+
+      - name: Deploy to GitHub pages 🚀
+        if: github.event_name != 'pull_request'
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
+        with:
+          clean: false
+          branch: gh-pages
+          folder: docs

.gitignore

@@ -0,0 +1,3 @@
+.Rproj.user
+docs
+inst/doc

DESCRIPTION

@@ -0,0 +1,30 @@
+Package: neuromat
+Title: Create Model Matrices for Neuroimaging Analyses
+Version: 0.0.0.9000
+Authors@R: 
+    person(
+    given = "Athanasia Mo", 
+    family = "Mowinckel",
+    email = "a.m.mowinckel@psykologi.uio.no", 
+    role = c("aut", "cre"),
+    comment = c(ORCID = "0000-0002-5756-0223"))
+Description: Neuroimaging software often requires the specification
+    of model matrices to run analyses. These can be difficult to 
+    correctly. This package helps neuroscientists to create such
+    This includes creating qdec-files for Freesurfer Linear Mixes
+    Effects models.
+License: MIT + file LICENSE
+Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.2.3
+Imports: 
+    grDevices,
+    methods,
+    stats,
+    utils
+URL: https://github.com/capro-uio/neuromat, http://www.capro.dev/neuromat/
+BugReports: https://github.com/capro-uio/neuromat/issues
+Suggests: 
+    knitr,
+    rmarkdown
+VignetteBuilder: knitr

LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2024
+COPYRIGHT HOLDER: freesurfer.lme authors

LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 freesurfer.lme authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

NAMESPACE

@@ -0,0 +1,11 @@
+# Generated by roxygen2: do not edit by hand
+
+S3method(plot,qdec)
+export(make_fs_qdec)
+export(qdec)
+export(scale_vec)
+importFrom(grDevices,hcl.colors)
+importFrom(methods,is)
+importFrom(stats,heatmap)
+importFrom(stats,model.matrix)
+importFrom(utils,write.csv)

R/qdec.R

@@ -0,0 +1,163 @@
+#' Create a Freesurfer qdec
+#'
+#' Create a Freesurfer qdec from a model formula,
+#' utilising R's robust model formula syntax. The function
+#' also scales continuous variables, and can keep the original
+#' data in the output.
+#'
+#' @details
+#' The \code{\link{formula}} should in all likelihood also
+#' include the \code{-1} to remove the intercept, as this
+#' will provide a matrix where all levels of factor variables
+#' have their own binary column. This is necessary to follow
+#' the steps from the Freesurfer documentation.
+#'
+#' It is highly recommended to have the base-id's for Freesurfer
+#' in their own column, and request to have this remain
+#' in the qdec by using the id-column's name in the
+#' \code{keep} argument.
+#'
+#' @param data data.frame, list or environment
+#'    containing the data. Neither matrix nor an array
+#'    will be accepted.
+#' @template formula
+#' @param path an option file path to write qdec to csv
+#' @param keep logical or vector of column names,
+#'    to keep the original data in the output.
+#'     Default is \code{FALSE}.
+#'
+#' @return data.frame with model matrix and
+#'    scaled continuous variables.
+#' @export
+#' @importFrom stats model.matrix
+#' @importFrom utils write.csv
+#' @importFrom methods is
+#'
+#' @examples
+#' cars <- mtcars
+#' cars$cyl <- as.factor(cars$cyl)
+#' cars$gear <- as.factor(cars$gear)
+#'
+#' make_fs_qdec(cars, mpg ~ cyl + hp)
+#'
+#' # Remove the intercept, necessary to follow
+#' # steps from Freesurfer docs
+#' make_fs_qdec(cars, mpg ~ -1 + cyl + hp)
+#' make_fs_qdec(cars, mpg ~ -1 + cyl + hp + gear)
+#'
+#' # Keep the original data also in the output
+#' make_fs_qdec(cars, mpg ~ -1 + cyl + hp, keep = TRUE)
+#'
+#' # Keep the original data of specific columns
+#' # Use a character vector
+#' make_fs_qdec(cars, mpg ~ -1 + cyl + hp, keep = c("mpg", "gear"))
+#'
+make_fs_qdec <- function(data,
+                      formula,
+                      path = NULL,
+                      keep = FALSE) {
+  if(all(
+    is(keep, "character") &
+    keep == ""
+  )){
+    stop("`keep` cannot be ''. Use TRUE/FALSE or the names of columns.", call. = FALSE)
+  }
+
+  qdec <- qdec(data, formula)
+  vars <- attr(qdec, "vars")
+
+  if(is(keep, "character")){
+    vars <- keep
+  }
+  data <- data[ , vars, drop = FALSE]
+
+  add_orig <- suppressWarnings(
+    any(keep, is.character(keep))
+  )
+  if(add_orig){
+    qdec <- cbind(qdec, data)
+  }
+
+  # write to path if requested
+  if(!is.null(path)){
+    write.csv(qdec, path, row.names = FALSE)
+  }
+
+  qdec
+}
+
+#' Freesurfer qdec constructor
+#'
+#' Creates a qdec matrix from a model formula.
+#'
+#' @param data input data.frame
+#' @template formula
+#'
+#' @return qdec with model matrix
+#' @export
+#'
+#' @examples
+#' cars <- mtcars
+#' cars$cyl <- as.factor(cars$cyl)
+#'
+#' qdec <- qdec(cars, mpg ~ cyl + hp)
+qdec <- function(data, formula){
+  # extract variable names from formula
+  vars <- all.vars(formula)
+
+  # create model matrix
+  mm <- model.matrix(formula, data)
+  mm <- as.data.frame(mm)
+  mm <- mm[, !names(mm) %in% names(data)]
+
+  # scale continuous variables
+  dataz <- scale_num_data(data, vars)
+
+  # combine model matrix and scaled data
+  qdec <- cbind(mm, dataz)
+
+  structure(
+    qdec,
+    class   = c("qdec", "tbl", "data.frame"),
+    formula = formula,
+    vars    = vars
+  )
+}
+
+
+#' Plot qdec matrix
+#'
+#' Visualise a Freesurfer qdec matrix as returned
+#' byt the \code{\link{make_fs_qdec}} function.
+#'
+#' @param x a qdec object
+#' @param col a vector of colors to be used in the heatmap.
+#' @param ... arguments to be passed to \code{\link{heatmap}}.
+#'     \code{scale}, \code{Rowv}, \code{Colv} already have
+#'     custom values that may not be overwritten for the sake
+#'     of a better visualisation.
+#'
+#' @return a heatmap of the qdec matrix
+#' @export
+#' @importFrom grDevices hcl.colors
+#' @importFrom stats heatmap
+#' @examples
+#' cars <- mtcars
+#' cars$cyl <- as.factor(cars$cyl)
+#'
+#' qdec <- make_fs_qdec(cars, mpg ~ -1 + cyl + hp)
+#' plot(qdec)
+plot.qdec <- function(x,
+                      col = hcl.colors(12, "viridis"),
+                      ...) {
+  if(!inherits(x, "qdec")){
+    stop("Input `x` must be a qdec object", call. = FALSE)
+  }
+  x <- x[, !names(x) %in% attr(x, "vars")]
+  x <- as.matrix(x)
+  x <- x[dim(x)[1]:1, ]
+  heatmap(x, scale = "none",
+          Rowv = NA, Colv = NA,
+          col = col,
+          ...)
+}

R/utils.R

@@ -0,0 +1,27 @@
+#' Scale a numeric vector
+#'
+#' @param x numeric vector to scale
+#' @param ... additional arguments to be passed to \code{\link{scale}}
+#'
+#' @return scaled vector
+#' @export
+#' @keywords internal
+#' @examples
+#' scale_vec(1:20)
+scale_vec <- function(x, ...) {
+  # Error if x has more than one dimension
+  if(!is.null(dim(x))){
+    stop("Input `x` must be a vector", call. = FALSE)
+  }
+  as.numeric(scale(x, ...))
+}
+
+scale_num_data <- function(data, formula){
+  # scale continuous variables
+  cl <- sapply(data, class)
+  dataz <- data[,which(cl %in% "numeric")]
+  dataz <- apply(dataz, 2, scale_vec)
+  dataz <- as.data.frame(dataz, check.names = FALSE)
+  names(dataz) <- paste0(names(dataz), "z")
+  dataz
+}