Skip to contents

verywise

vertex-wise, whole-brain linear mixed models

The goal of verywise is to offer a flexible, user-friendly interface to whole-brain analysis of neuro-imaging data that has been pre-processed using FreeSurfer.

The package was specifically designed for the analysis of longitudinal (e.g. multi-session) and/or multi-site neuroimaging data.

Currently, verywise allows the estimation of vertex-wise Linear Mixed Models, and meta-analysis, but will be extended to other statistical models in the future.

It can handle imputed (phenotype) data from several packages (mice, mi, amelia, etc.).

Multiple testing correction is currently achieved using MCZ simulations from FreeSurfer. This means that you will need FreeSurfer installed and correctly set up.

Installation

You can install the development version of verywise from GitHub with:

# install.packages("pak")
pak::pak("SereDef/verywise")

# or 
# install.packages("devtools")
devtools::install_github("SereDef/verywise")

Basic use 

# Run a linear mixed model
run_vw_lmm(
  formula = vw_thickness ~ sex * age + site + (1 | id), # model formula
  pheno = long_format_data, # An R object already in memory, or "path/to/phentype/data"
  subj_dir = "/path/to/freesurfer/subjects", # Neuro-imaging data location
  outp_dir = "/path/to/output", # Where you want to store results
  hemi = "lh", # (default) or "rh": which hemisphere to run
  n_cores = 4  # parallel processing
)
# Run a meta-analysis
run_vw_meta(
  term = "age", # Which "term" / predictor / effect to pool
  hemi = "lh", # (default) or "rh": which hemisphere to run
  measure = "area", # (default) or any available FreeSurfer metric.
  res_dirs = c("/path/to/study1/results", "/path/to/study2/results"),
  study_names = c("Study1", "Study2"),
  n_cores = 4  # parallel processing
)

Visualization

To inspect and plot your results, you can use our interactive web application, verywiseWIZard. You can run this locally or try it out here.

Plots can also be generated using verywise like so:

# Plot result brain map (requires FreeSurfer for templates and reticulate for interface with Python-based plotting libraries)
plot_vw_map(
  term = "age",
  hemi = "lh",
  measure = "area",
  res_dir = "/path/to/output",
  outline_rois = c("entorhinal", "precuneus"),
  fs_home = "/path/to/FREESURFER_HOME"
)

Tutorials and documentation

You can find more info and extended tutorials on the package website. For example:

License and credits

verywise is open-source and free to use under the Apache-2.0. license.

This is a spin-off of the QDECR package, which handles linear regression models.

Contributing

If you spot a bug or you have a question, please let us know on the GitHub issues page.

We are always happy to get suggestions, ideas and help!

Funders

Funders

This work was supported by the FLAG-ERA grant Infant2Adult and by The Netherlands Organization for Health Research and Development (ZonMw, grant number 16080606).