/osprey

All-in-one toolbox for processing of magnetic resonance spectroscopy data.

Primary LanguageMATLABMIT LicenseMIT

Osprey

GitHub release (latest by date) GitHub Release Date Build Status GitHub commit activity GitHub last commit Website License

Osprey

Osprey Documentation

Osprey is an all-in-one software suite for state-of-the art processing and quantitative analysis of in-vivo magnetic resonance spectroscopy (MRS) data.

Features

  • 1-file job definition system for reproducible data analysis
  • Automated recognition of input file format and sequence origin
  • Fully-automated loading and pre-processing pipeline for optimal SNR, linewidth, phasing, and alignment
  • Integrated linear-combination modeling module
  • Full density-matrix simulated basis sets (using real pulses and sequence timings; including effects of localization and spectral editing) for many metabolites and common sequence implementations
  • Functions to create custom basis sets and import basis sets from LCModel or Tarquin
  • Integrated voxel co-registration and segmentation module (requires SPM12)
  • Quantification based on tissue fractions and (customizable) metabolite/tissue water relaxation times
  • GUI to display data, quality assessment, and quantitative results at each step of the analysis
  • Rich 'Overview' GUI panel for batched datasets to visualize distributions of metabolite estimates and mean +/- SD spectra

Supported methods

  • Conventional MRS (STEAM, PRESS, semi-LASER, LASER)
  • MEGA editing
  • Hadamard-encoded editing (HERMES, HERCULES)
  • Dual voxel (PRIAM)

Supported sequence implementations

  • Philips (Philips product sequences; Johns Hopkins patches)
  • Siemens (Siemens product and WIP sequences; Johns Hopkins patches; CMRR sequences; Jamie Near sequence)
  • GE (GE product sequences; Ralph Noeske sequence)

Supported file formats

  • Philips: SDAT/SPAR, DATA/LIST, SIN/LAB/RAW (coming soon)
  • Siemens: TWIX/DAT, RDA (single- & multi-file), DICOM (DCM/IMA, single- & multi-file)
  • GE: P

Getting started

Prerequisites

Osprey requires MATLAB and has been tested on version 2017a and newer. The following toolboxes are required for full functionality:

  • Optimization
  • Statistics and Machine Learning

Installation

Download the latest Osprey code from its GitHub repository, then extract and add the entire folder (with subfolders) to your MATLAB path. Make sure to regularly check for updates, as we frequently commit new features, bug fixes, and improved functions.

To perform voxel co-registration and tissue segmentation, download SPM12 from the UCL website, then extract and add to your MATLAB path.

If you want to use the Osprey Graphical User Interface (GUI), please download the following toolboxes from the MATLAB File Exchange:

Download both toolboxes in the MATLAB toolbox format (.mltbx). You can double-click to install. MATLAB will automatically add the toolboxes to its path.

Make sure to remove FID-A and Gannet from your MATLAB path.

Contact, Feedback, Suggestions

For any sort of questions, feedback, suggestions, or critique, please visit the Osprey support forum on the MRSHub.

We also welcome your direct contributions to Osprey here in the GitHub repository.

Developers

Should you publish material that made use of Osprey, please cite the following publication:

G Oeltzschner, HJ Zöllner, SCN Hui, M Mikkelsen, MG Saleh, S Tapper, RAE Edden. Osprey: Open-Source Processing, Reconstruction & Estimation of Magnetic Resonance Spectroscopy Data. J Neurosci Meth 343:108827 (2020).

Acknowledgements

This work has been supported by NIH grants R01 EB016089, P41 EB15909, P41 EB031771, R01 EB023963, and K99 AG062230.

We wish to thank collaborators and partners for providing LCModel basis sets and control files. If you use these resources for your analysis of the following data types, please mention the respective individuals in your acknowledgements:

  • Siemens 7T STEAM (TE = 5 ms): Dr. Dinesh Deelchand (University of Minnesota)
  • Siemens 3T and 7T SPECIAL (TE = 8.5/9 ms): Dr. Ariane Fillmer (PTB Berlin)

We also wish to thank the following individuals for their contributions to the development of Osprey and shared processing code:

  • Jamie Near (McGill University, Montreal)
  • Ralph Noeske (GE Healthcare, Berlin)
  • Peter Barker (Johns Hopkins University, Baltimore, MD)
  • Robin de Graaf (Yale School of Medicine, New Haven, CT)
  • Philipp Ehses (German Center for Neurodegenerative Diseases, Bonn)
  • Wouter Potters (UMC Amsterdam)
  • Xiangrui Li (Ohio State University, Columbus, OH)
  • Peter Van Schuerbeek (UZ Brussel)

We are particularly grateful for the incredible raincloud plot tools developed by Micah Allen, Davide Poggiali, Kirstie Whitaker, Tom Rhys Marshall, and Rogier Kievit. Should you make use of the OspreyOverview raincloud plots, please consider citing their original publications:

  • Allen M, Poggiali D, Whitaker K et al. Raincloud plots: a multi-platform tool for robust data visualization [version 1; peer review: 2 approved]. Wellcome Open Res 2019, 4:63. DOI: 10.12688/wellcomeopenres.15191.1
  • Allen M, Poggiali D, Whitaker K, Marshall TR, Kievit R. (2018) RainCloudPlots tutorials and codebase (Version v1.1). Zenodo. http://doi.org/10.5281/zenodo.3368186