README.md 17.3 KB
Newer Older
Lars Kasper's avatar
Lars Kasper committed
1 2
TAPAS PhysIO Toolbox 
====================
3

Lars Kasper's avatar
Lars Kasper committed
4
*Current version: Release 2019b, v7.2.0*
Lars Kasper's avatar
Lars Kasper committed
5

Lars Kasper's avatar
Lars Kasper committed
6
> Copyright (C) 2012-2019  
Lars Kasper's avatar
Lars Kasper committed
7 8 9 10 11 12
> Lars Kasper  
> <kasper@biomed.ee.ethz.ch>  
>  
> Translational Neuromodeling Unit (TNU)  
> Institute for Biomedical Engineering  
> University of Zurich and ETH Zurich  
13 14


15 16
Download
--------
17

Lars Kasper's avatar
Lars Kasper committed
18 19 20 21 22 23
- Please download the latest stable versions of the PhysIO Toolbox on GitHub as part of the 
  [TAPAS software releases of the TNU](https://github.com/translationalneuromodeling/tapas/releases).
- Older versions are available on the [TNU website](http://www.translationalneuromodeling.org/tapas).
- The latest bugfixes can be found in the [GitHub Issue Forum](https://github.com/translationalneuromodeling/tapas/issues) or by request to the authors. 
- Changes between all versions are documented in the 
  [CHANGELOG](https://gitlab.ethz.ch/physio/physio-doc/blob/master/CHANGELOG.md).
24 25 26 27 28


Purpose
-------

Lars Kasper's avatar
Lars Kasper committed
29 30 31
The general purpose of this Matlab toolbox is the model-based physiological noise 
correction of fMRI data using peripheral measures of respiration and cardiac 
pulsation. It incorporates noise models of cardiac/respiratory phase (RETROICOR, 
32 33
Glover et al. 2000), as well as heart rate variability and respiratory 
volume per time (cardiac response function, Chang et. al, 2009, respiratory 
Lars Kasper's avatar
Lars Kasper committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
response function, Birn et al. 2006), and extended motion models. 
While the toolbox is particularly well integrated with SPM via the Batch Editor GUI, its 
simple output nuisance regressor text files can be incorporated into any major 
neuroimaging analysis package.

Core design goals for the toolbox were: *flexibility*, *robustness*, and *quality assurance* 
to enable physiological noise correction for large-scale and multi-center studies. 

Some highlights:
1. Robust automatic preprocessing of peripheral recordings via iterative peak 
   detection, validated in noisy data and patients.
2. Flexible support of peripheral data formats (Siemens, Philips, HCP, GE, Biopac, ...) 
   and noise models (RETROICOR, RVHRCOR).
3. Fully automated noise correction and performance assessment for group studies.
4. Integration in fMRI pre-processing pipelines as SPM Toolbox (Batch Editor GUI).

The accompanying technical paper about the toolbox concept and methodology 
can be found at: https://doi.org/10.1016/j.jneumeth.2016.10.019

53 54 55 56

Installation
------------

Lars Kasper's avatar
Lars Kasper committed
57
### Matlab
Lars Kasper's avatar
Lars Kasper committed
58 59 60 61
1. Unzip the TAPAS archive in your folder of choice
2. Open Matlab
3. Go to `/your/path/to/tapas/physio/code`
4. Run `tapas_physio_init()` in Matlab
62

Lars Kasper's avatar
Lars Kasper committed
63 64 65 66

*Note*: Step (4) executes the following steps, which you could do manually as well.
- Adds the `physio/code/` folder to your Matlab path
- Adds SPM to your Matlab path (you can enter it manually, if not found)
Lars Kasper's avatar
Lars Kasper committed
67
- Links the folder (Linux/Max) or copies the folder (Windows) `physio/code/` to `/your/path/to/SPM/toolbox/PhysIO`, if the PhysIO code is not already found there  
Lars Kasper's avatar
Lars Kasper committed
68 69 70 71

Only the first point is necessary for using PhysIO standalone with Matlab.
The other two points enable PhysIO's SPM integration, i.e., certain functionality 
(Batch Editor GUI, pipeline dependencies, model assessment via F-contrasts).
72 73 74 75 76


Getting Started
---------------

Lars Kasper's avatar
Lars Kasper committed
77 78
...following the installation, you can try out an example:

Lars Kasper's avatar
Lars Kasper committed
79 80
1. Download the TAPAS examples via running `tapas_download_example_data()` 
   (found in `misc`-subfolder of TAPAS)
Lars Kasper's avatar
Lars Kasper committed
81 82
    - The PhysIO Example files will be downloaded to `tapas/examples/<tapas-version>/PhysIO`
2. Run `philips_ecg3t_matlab_script.m` in subdirectory `Philips/ECG3T`
Lars Kasper's avatar
Lars Kasper committed
83
3. See subdirectory `physio/docs` and the next two section of this document for help.
84

Lars Kasper's avatar
Lars Kasper committed
85 86
You may try any of the examples in the other vendor folders as well.

87

88 89 90 91 92 93 94 95
Contact/Support
---------------

We are very happy to provide support on how to use the PhysIO Toolbox. However, 
as every researcher, we only have a limited amount of time. So please excuse, if 
we might not provide a detailed answer to your request, but just some general 
pointers and templates. Before you contact us, please try the following:

Lars Kasper's avatar
Lars Kasper committed
96
1. A first look at the [FAQ](https://gitlab.ethz.ch/physio/physio-doc/wikis/FAQ) 
97
   (which is frequently extended) might already answer your questions.
Lars Kasper's avatar
Lars Kasper committed
98
2. A lot of questions (before 2018) have also been discussed on our mailinglist 
99 100 101
   [tapas@sympa.ethz.ch](https://sympa.ethz.ch/sympa/info/tapas), 
   which has a searchable [archive](https://sympa.ethz.ch/sympa/arc/tapas).
3. For new requests, we would like to ask you to submit them as 
Lars Kasper's avatar
Lars Kasper committed
102 103 104
   [issues](https://github.com/translationalneuromodeling/tapas/issues) on our 
   github release page for TAPAS, which is also an up-to-date resource to 
   user-driven questions (since 2018).
105

106

107 108
Documentation
-------------
109

Lars Kasper's avatar
Lars Kasper committed
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
Documentation for this toolbox is provided in the following forms

1. Overview and guide to further documentation: README.md and CHANGELOG.md
    - [README.md](README.md): this file, purpose, installation, getting started, pointer to more help
    - [CHANGELOG.md](CHANGELOG.md): List of all toolbox versions and the respective release notes, 
      i.e. major changes in functionality, bugfixes etc.
2. User Guide: The markdown-based [GitLab Wiki](https://gitlab.ethz.ch/physio/physio-doc/wikis/home), including an FAQ
    - online (and frequently updated) at http://gitlab.ethz.ch/physio/physio-doc/wikis/home.
    - offline (with stables releases) as part of the toolbox in folder `physio/wikidocs`: 
        - plain text `.md` markdown files
        - as single HTML and PDF  file: `documentation.{html,pdf}`
3. Within SPM: All toolbox parameters and their settings are explained in the 
   Help Window of the SPM Batch Editor
4. Within Matlab: Extensive header at the start of each `tapas_physio_*` function and commenting
    - accessible via `help` and `doc` commands from Matlab command line
    - starting point for all parameters (comments within file): `edit tapas_physio_new` 
    - also useful for developers (technical documentation)
    
128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149

Background
----------

The PhysIO Toolbox provides physiological noise correction for fMRI-data 
from peripheral measures (ECG/pulse oximetry, breathing belt). It is 
model-based, i.e. creates nuisance regressors from the physiological 
monitoring that can enter a General Linear Model (GLM) analysis, e.g. 
SPM8/12. Furthermore, for scanner vendor logfiles (PHILIPS, GE, Siemens), 
it provides means to statistically assess peripheral data (e.g. heart rate variability) 
and recover imperfect measures (e.g. distorted R-peaks of the ECG).

Facts about physiological noise in fMRI:
- Physiological noise can explain 20-60 % of variance in fMRI voxel time 
  series (Birn2006, Hutton2011, Harvey2008)
    - Physiological noise affects a lot of brain regions (s. figure, e.g. 
      brainstem or OFC), especially next to CSF, arteries (Hutton2011). 
    - If not accounted for, this is a key factor limiting sensitivity for effects of interest.
- Physiological noise contributions increase with field strength; they 
  become a particular concern at and above 3 Tesla (Kasper2009, Hutton2011).
- In resting state fMRI, disregarding physiological noise leads to wrong 
  connectivity results (Birn2006).
Lars Kasper's avatar
Lars Kasper committed
150 151 152 153 154
- Uncorrected physiological noise introduces serial correlations into the residual
  voxel time series, that invalidate assumptions on noise correlations (e.g., AR(1)) 
  used in data prewhitening by all major analysis packages. This issue is particularly
  aggravated at short TR (<1s), and most of its effects can be suitably addressed
  by physiological noise correction (Bollmann2018)
155

Lars Kasper's avatar
Lars Kasper committed
156 157
Therefore, some kind of physiological noise correction is highly recommended for
every statistical fMRI analysis.
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174

Model-based correction of physiological noise: 
- Physiological noise can be decomposed into periodic time series following 
  heart rate and breathing cycle.
- The Fourier expansion of cardiac and respiratory phases was introduced as 
  RETROICOR (RETROspective Image CORrection, Glover2000, 
  see also Josephs1997).
- These Fourier Terms can enter a General Linear Model (GLM) as nuisance 
  regressors, analogous to movement parameters.
- As the physiological noise regressors augment the GLM and explain 
  variance in the time series, they increase sensitivity in all contrasts 
  of interest.

		
Features of this Toolbox
------------------------

Lars Kasper's avatar
Lars Kasper committed
175
### Physiological Noise Modeling
176 177 178 179 180 181 182 183 184 185

- Modeling physiological noise regressors from peripheral data 
  (breathing belt, ECG, pulse oximeter) 
    - State of the art RETROICOR cardiac and respiratory phase expansion
    - Cardiac response function (Chang et al, 2009) and respiratory response 
      function (Birn et al. 2006) modelling of heart-rate variability and 
      respiratory volume  per time influence on physiological noise
    - Flexible expansion orders to model different contributions of cardiac, 
      respiratory and interaction terms (see Harvey2008, Hutton2011)
- Data-driven noise regressors
Lars Kasper's avatar
Lars Kasper committed
186 187
    - PCA extraction from nuisance ROIs (CSF, white matter), similar to aCompCor 
      (Behzadi2007)
188

Lars Kasper's avatar
Lars Kasper committed
189 190
### Automatization and Performance Assessment

191 192
- Automatic creation of nuisance regressors, full integration into standard 
  GLMs, tested for SPM8/12 ("multiple_regressors.mat")
Lars Kasper's avatar
Lars Kasper committed
193 194 195 196 197
- Integration in SPM Batch Editor: GUI for parameter input, dependencies to 
  integrate physiological noise correction in preprocessing pipeline
- Performance Assessment: Automatic F-contrast and tSNR Map creation and display 
  for groups of physiological noise regressors, using SPM GLM tools via 
  `tapas_physio_report_contrasts()`.
198

Lars Kasper's avatar
Lars Kasper committed
199
### Flexible Read-in
200

Lars Kasper's avatar
Lars Kasper committed
201 202 203 204
The toolbox is dedicated to seamless integration into a clinical research 
setting and therefore offers correction methods to recover physiological 
data from imperfect peripheral measures. Read-in of the following formats is 
currently supported (alphabetic order):
205

Lars Kasper's avatar
Lars Kasper committed
206 207 208 209
- Biopac `.mat` and `.txt` -export
- Brain Imaging Data Structure (BIDS)
- Custom logfiles: should contain one amplitude value per line, one logfile per 
  device. Sampling interval(s) are provided as a separate parameter to the toolbox.
210 211
- General Electric
- Philips SCANPHYSLOG files (all versions from release 2.6 to 5.3)
Lars Kasper's avatar
Lars Kasper committed
212 213 214
- Siemens VB (files `.ecg`, `.resp`, `.puls`)
- Siemens VD (files `*_ECG.log`, `*_RESP.log`, `*_PULS.log`)
- Siemens Human Connectome Project (preprocessed files `*Physio_log.txt`)
Lars Kasper's avatar
Lars Kasper committed
215 216 217 218

See also the 
[Wiki page on Read-In](https://gitlab.ethz.ch/physio/physio-doc/wikis/MANUAL_PART_READIN) 
for a more detailed list and description of the supported formats.
219 220


221 222
Compatibility
-------------
223 224 225 226 227

- Matlab Toolbox
- Input: 
    - Fully integrated to work with physiological logfiles for Philips MR systems (SCANPHYSLOG)
    - tested for General Electric (GE) log-files
228
    - implementation for Siemens log-files (both VB and VD/VE, CMRR multiband)
229 230
    - also: interface for 'Custom', i.e. general heart-beat time stamps 
      & breathing volume time courses from other log formats
231 232
    - BioPac
    - ... (other upcoming formats)
233 234 235 236
- Output: 
    - Nuisance regressors for mass-univariate statistical analysis with SPM5,8,12
      or as text file for export to any other package
    - raw and processed physiological logfile data
237
    - Graphical Batch Editor interface to SPM
Lars Kasper's avatar
Lars Kasper committed
238 239 240
- Part of the TAPAS Software Collection of the Translational Neuromodeling Unit 
  (TNU) Zurich
    - ensures long term support and ongoing development
241 242 243 244 245 246


Contributors
------------

- Lead Programmer: 
247 248
    - [Lars Kasper](https://www.tnu.ethz.ch/en/team/faculty-and-scientific-staff/kasper.html),
      TNU & MR-Technology Group, IBT, University of Zurich & ETH Zurich
249 250 251
- Project Team: 
    - Steffen Bollmann, Centre for Advanced Imaging, University of Queensland, Australia
    - Saskia Bollmann, Centre for Advanced Imaging, University of Queensland, Australia
Lars Kasper's avatar
Lars Kasper committed
252
- Contributors (Code):
253 254
    - Eduardo Aponte, TNU Zurich
    - Tobias U. Hauser, FIL London, UK
Lars Kasper's avatar
Lars Kasper committed
255
    - Sam Harrison, TNU Zurich
256 257 258
    - Jakob Heinzle, TNU Zurich
    - Chloe Hutton, FIL London, UK (previously)
    - Miriam Sebold, Charite Berlin, Germany
Lars Kasper's avatar
Lars Kasper committed
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
    - External TAPAS contributors listed in its [Contributor License Agreement]
    (https://github.com/translationalneuromodeling/tapas/blob/master/Contributor-License-Agreement.md)
- Contributors (Examples):
    - listed in [EXAMPLES.md](https://gitlab.ethz.ch/physio/physio-doc/wikis/EXAMPLES)


Requirements
------------

- All specific software requirements and their versions are in a separate file
  in this folder, `requirements.txt`.
- In brief:
    - PhysIO needs Matlab to run, and some of its toolboxes.
    - Some functionality requires SPM (GUI, nuisance regression, contrast reporting, 
      writing residual and SNR images).


Acknowledgements
----------------

The PhysIO Toolbox ships with the following publicly available code from other
open source projects and gratefully acknowledges their use.

- `utils\tapas_physio_propval.m`
    - `propval` function from Princeton MVPA toolbox (GPL)
      a nice wrapper function to create flexible propertyName/value optional
      parameters
- `utils\tapas_physio_fieldnamesr.m`
    - recursive parser for field names of a structure
    - Matlab file exchange, adam.tudorjones@pharm.ox.ac.uk
289 290 291 292 293


References
----------

Lars Kasper's avatar
Lars Kasper committed
294 295
### Main Toolbox Reference

Lars Kasper's avatar
Lars Kasper committed
296 297 298
Please cite the following paper in all of your publications that utilized the 
PhysIO Toolbox. 

Lars Kasper's avatar
Lars Kasper committed
299 300 301
1. Kasper, L., Bollmann, S., Diaconescu, A.O., Hutton, C., Heinzle, J., Iglesias, 
S., Hauser, T.U., Sebold, M., Manjaly, Z.-M., Pruessmann, K.P., Stephan, K.E., 2017. 
The PhysIO Toolbox for Modeling Physiological Noise in fMRI Data. 
Lars Kasper's avatar
Lars Kasper committed
302 303 304 305
Journal of Neuroscience Methods 276, 56–72. https://doi.org/10.1016/j.jneumeth.2016.10.019

The [FAQ](https://gitlab.ethz.ch/physio/physio-doc/wikis/FAQ#3-how-do-i-cite-physio) 
contains a complete suggestion for a snippet in your methods section.
Lars Kasper's avatar
Lars Kasper committed
306 307

### Related Papers (Implemented noise correction algorithms and optimal parameter choices)
308

Lars Kasper's avatar
Lars Kasper committed
309 310 311 312 313 314 315 316 317 318
The following sections list papers that 
- first implemented specific noise correction algorithms
- determined optimal parameter choices for these algorithms, depending on the
  targeted application
- demonstrate the impact of physiological noise and the importance of its correction

It is loosely ordered by the dominant physiological noise model used in the 
paper. The list is by no means complete, and we are happy to add any relevant papers 
suggested to us. 

Lars Kasper's avatar
Lars Kasper committed
319
#### RETROICOR 
320 321 322
2. Glover, G.H., Li, T.Q. & Ress, D. Image‐based method for retrospective correction
of PhysIOlogical motion effects in fMRI: RETROICOR. Magn Reson Med 44, 162-7 (2000).

Lars Kasper's avatar
Lars Kasper committed
323
3. Hutton, C. et al. The impact of Physiological noise correction on fMRI at 7 T.
324 325 326 327 328 329
NeuroImage 57, 101‐112 (2011).

4. Harvey, A.K. et al. Brainstem functional magnetic resonance imaging:
Disentangling signal from PhysIOlogical noise. Journal of Magnetic Resonance
Imaging 28, 1337‐1344 (2008).

Lars Kasper's avatar
Lars Kasper committed
330 331 332 333 334
5. Bollmann, S., Puckett, A.M., Cunnington, R., Barth, M., 2018. 
Serial correlations in single-subject fMRI with sub-second TR. 
NeuroImage 166, 152–166. https://doi.org/10.1016/j.neuroimage.2017.10.043


Lars Kasper's avatar
Lars Kasper committed
335
#### aCompCor / Noise ROIs 
Lars Kasper's avatar
Lars Kasper committed
336
6. Behzadi, Y., Restom, K., Liau, J., Liu, T.T., 2007. A component based noise
337
correction method (CompCor) for BOLD and perfusion based fMRI. NeuroImage 37,
Lars Kasper's avatar
Lars Kasper committed
338
90–101. https://doi.org/10.1016/j.neuroimage.2007.04.042
Lars Kasper's avatar
Lars Kasper committed
339 340

#### RVT
Lars Kasper's avatar
Lars Kasper committed
341
7. Birn, R.M., Smith, M.A., Jones, T.B., Bandettini, P.A., 2008. The respiration response
342 343
function: The temporal dynamics of fMRI s ignal fluctuations related to changes in
respiration. NeuroImage 40, 644–654. doi:10.1016/j.neuroimage.2007.11.059
Lars Kasper's avatar
Lars Kasper committed
344
8. Jo, H.J., Saad, Z.S., Simmons, W.K., Milbury, L.A., Cox, R.W., 2010. 
Lars Kasper's avatar
Lars Kasper committed
345 346
Mapping sources of correlation in resting state FMRI, with artifact detection 
and removal. NeuroImage 52, 571–582. https://doi.org/10.1016/j.neuroimage.2010.04.246  
Lars Kasper's avatar
Lars Kasper committed
347
    - *regressor delay suggestions*
Lars Kasper's avatar
Lars Kasper committed
348 349

#### HRV
Lars Kasper's avatar
Lars Kasper committed
350
9. Chang, C., Cunningham, J.P., Glover, G.H., 2009. Influence of heart rate on the
351 352
BOLD signal: The cardiac response function. NeuroImage 44, 857–869.
doi:10.1016/j.neuroimage.2008.09.029
Lars Kasper's avatar
Lars Kasper committed
353
10. Shmueli, K., van Gelderen, P., de Zwart, J.A., Horovitz, S.G., Fukunaga, M., 
Lars Kasper's avatar
Lars Kasper committed
354 355 356
Jansma, J.M., Duyn, J.H., 2007. Low-frequency fluctuations in the cardiac rate 
as a source of variance in the resting-state fMRI BOLD signal. 
NeuroImage 38, 306–320. https://doi.org/10.1016/j.neuroimage.2007.07.037  
Lars Kasper's avatar
Lars Kasper committed
357
    - *regressor delay suggestions*
Lars Kasper's avatar
Lars Kasper committed
358 359

#### Motion (Censoring, Framewise Displacement)
Lars Kasper's avatar
Lars Kasper committed
360
11. Siegel, J.S., Power, J.D., Dubis, J.W., Vogel, A.C., Church, J.A., Schlaggar, B.L.,
361 362
Petersen, S.E., 2014. Statistical improvements in functional magnetic resonance
imaging analyses produced by censoring high-motion data points. Hum. Brain Mapp.
Lars Kasper's avatar
Lars Kasper committed
363
35, 1981–1996. https://doi.org/10.1002/hbm.22307
364

Lars Kasper's avatar
Lars Kasper committed
365 366 367 368
12. Power, J.D., Barnes, K.A., Snyder, A.Z., Schlaggar, B.L., Petersen, S.E., 2012. 
Spurious but systematic correlations in functional connectivity MRI networks 
arise from subject motion. NeuroImage 59, 2142–2154. 
https://doi.org/10.1016/j.neuroimage.2011.10.018
Lars Kasper's avatar
Lars Kasper committed
369

370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385

Copying/License
---------------

The PhysIO Toolbox is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program (see the file [LICENSE](LICENSE)).  If not, see
Lars Kasper's avatar
Lars Kasper committed
386
<http://www.gnu.org/licenses/>.