Skip to content

Changes

Page history
Added physio-public.wiki content authored by Lars Kasper's avatar Lars Kasper
Hide whitespace changes
Inline Side-by-side
FAQ.md 0 → 100644
View page @ a9a116ef
Frequently Asked Questions (FAQ)
================================
1. What is the PhysIO Toolbox?
------------------------------
PhysIO is a toolbox for model-based physiological noise correction of fMRI data.
PhysIO stands for Physiological Input/Output toolbox, which summarizes its core purpose. A quote from our [paper](http://dx.doi.org/10.1016/j.jneumeth.2016.10.019>):
> In short, the toolbox transforms physiological input, i.e. peripheral recordings, into physiological output, i.e. regressors encoding components of physiological noise [...] A modular Matlab implementation supports command-line operation and is compatible with all major fMRI analysis packages via the export of regressor text-files. For the Statistical Parametric Mapping [SPM](<http://www.fil.ion.ucl.ac.uk/spm>) software package in particular, PhysIO features a full integration as a Batch Editor Tool, which allows user-friendly, GUI-based setup and inclusion into existing preprocessing and modeling pipelines.
2. How does PhysIO differ from other toolboxes for physiological noise correction for fMRI using peripheral recordings?
----------------------------------------------------------------------------------------------------------------------
Citing from the introduction of our [paper](http://dx.doi.org/10.1016/j.jneumeth.2016.10.019>) again
>
> ### Highlights ###
* A Toolbox to integrate preprocessing of physiological data and fMRI noise modeling.
* Robust preprocessing via iterative peak detection, shown for noisy data and patients.
* Flexible support of peripheral data formats and noise models (RETROICOR, RVHRCOR).
* Fully automated noise correction and performance assessment for group studies.
* Integration in fMRI pre-processing pipelines as SPM Toolbox (Batch Editor GUI).
>
3. How do I cite PhysIO?
------------------------
The **core reference for PhysIO** is: _The PhysIO Toolbox for Modeling Physiological Noise in fMRI Data_ (http://dx.doi.org/10.1016/j.jneumeth.2016.10.019)
Please cite this paper if you use PhysIO in your work. Moreover, this paper is also a good source for more information on PhysIO (see next question).
A **standard snippet to include** in your method section could look like the following, assuming you use our specific implementation of RETROICOR, which uses Fourier expansions of different order for the estimated phases of cardiac pulsation (3rd order), respiration (4th order) and cardio-­‐respiratory interactions (1st order) following (Harvey et al., 2008)
> Correction for physiological noise was performed via RETROICOR [1,2] using Fourier
> expansions of different order for the estimated phases of cardiac pulsation (3rd order),
> respiration (4th order) and cardio-­‐respiratory interactions (1st order) [2]: The
> corresponding confound regressors were created using the Matlab PhysIO Toolbox ([4],
> open source code available as part of the TAPAS software collection:
> https://www.translationalneuromodeling.org/tapas).
1. 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).
2. Hutton, C. et al. The impact of PhysIOlogical noise correction on fMRI at 7 T.
NeuroImage 57, 101-­‐112 (2011).
3. Harvey, A.K. et al. Brainstem functional magnetic resonance imaging:
Disentangling signal from PhysIOlogical noise. Journal of Magnetic Resonance
Imaging 28, 1337-­‐1344 (2008).
4. 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. Journal of Neuroscience Methods 276, 56–72. doi:10.1016/j.jneumeth.2016.10.019
If you use **respiratory‐volume-­per time (RVT), heart-‐rate
variability (HRV), noise ROIs or 12/24 regressor motion modeling**, also include the
respective references:
5. Behzadi, Y., Restom, K., Liau, J., Liu, T.T., 2007. A component based noise
correction method (CompCor) for BOLD and perfusion based fMRI. NeuroImage 37,
90–101. doi:10.1016/j.neuroimage.2007.04.042
6. Birn, R.M., Smith, M.A., Jones, T.B., Bandettini, P.A., 2008. The respiration response
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
PhysIO Toolbox | Citing this work 20
7. Chang, C., Cunningham, J.P., Glover, G.H., 2009. Influence of heart rate on the
BOLD signal: The cardiac response function. NeuroImage 44, 857–869.
doi:10.1016/j.neuroimage.2008.09.029
8. Siegel, J.S., Power, J.D., Dubis, J.W., Vogel, A.C., Church, J.A., Schlaggar, B.L.,
Petersen, S.E., 2014. Statistical improvements in functional magnetic resonance
imaging analyses produced by censoring high-motion data points. Hum. Brain Mapp.
35, 1981–1996. doi:10.1002/hbm.22307
4. Where do I find more documentation for PhysIO?
-------------------------------------------------
* The [paper](http://dx.doi.org/10.1016/j.jneumeth.2016.10.019) describing its structure, objective and modules
* [README.md](https://tnurepository.ethz.ch/physio/physio-public/blob/master/README.md) in the main folder when downloading
- For help on installation and getting started
* Quickstart
- PDF (or markdown .md file)
- Tutorial matlab-scripts
* Reference Manual (for developers)
5. I am using FSL, AFNI, BrainVoyager, etc., for my fMRI analyses. Do I need SPM for PhysIO to work?
----------------------------------------------------------------------------------------------------
No, the basic functionality of PhysIO, i.e. creating nuisance regressors for your GLM analysis, is available in plain Matlab. The following extra functionality related to automatizing and assessing noise correction, require the installation of SPM:
- GUI (SPM Batch Editor)
- Pipeline dependencies (automatic input of realignment parameters, feed-in of multiple regressors file to GLM)
- Model assessment via F-tests and automatic F-map/tSNR report
- Noise-ROIs model (read-in of nifti files via SPM)
6. I am using device X for physiological recordings. Does PhysIO support the physiological logfile format Y?
-------------------------------------------------------------------------------------------------------------
Currently, PhysIO natively supports the following physiological logfile types:
- General Electric
- Philips SCANPHYSLOG files (all versions from release 2.6 to 5.3)
- Siemens VB (files `.ecg`, `.resp`, `.puls`
- Siemens VD/VE (files (`*_ECG.log`, `*_RESP.log`, `*_PULS.log`)
- including CMRR-like multiband-files
- Biopac .mat-export
- assuming the following variables (as columns): `data`, `isi`, `isi_units`, `labels`, `start_sample`, `units`
- See `tapas_physio_read_physlogfiles_biopac_mat.m` for details
Furthermore, physiological recordings can be entered via a *custom* data format, i.e., providing one text file per device. The files should contain one amplitude value per line. The corresponding sampling interval(s) are provided as a separate parameter in the toolbox.
If your favourite logfile format is not supported, please contact the developers. We try everything to accomodate the read-in flexibility of the toolbox to your needs.
7. I am running the toolbox for a lot of subjects / on a remote server without graphics. Can I somehow reproduce the output figures relevant to assess the data quality?
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Yes you can, using the toolbox function `tapas_physio_review`. This function takes the physio-structure as an input argument, which is per default saved as `physio.mat` in the specified output folder of your batch job.
8. How do I interpret the various output plots of the toolbox?
--------------------------------------------------------------
Have a look at our publication: _The PhysIO Toolbox for Modeling Physiological Noise in fMRI Data_ (http://dx.doi.org/10.1016/j.jneumeth.2016.10.019)
The figures there give a good overview of the toolbox output figures, in particular:
- Fig. S1 (supplementary): Philips Scan Timing Sync from `gradient_log` (explanation of `thresh.zero`, `thresh.sli`, `thresh.vol`, `thresh.vol_spacing`
- Fig. 3: Diagnostic Raw Time Series (cardiac cycle length curve, respiration histogram)
- Fig. 8C: Single Subject F-contrast results (cardiac regressors)
- Fig. 9: Group results/typical activation sites for F-contrasts of RETROICOR regressors (cardiac/resp/interaction)
9. I want to access subject's physiological measures, e.g. heart rate or respiratory volume (per time), before they enter the regressors. Where can I do that?
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
All intermediate data processing steps (e.g. filtering, cropping) of the peripheral data, including the computation of physiologically meaningful time courses, such as heart rate and respiratory volume, are saved in the substructure `ons_secs` ("onsets in seconds) of the physio-structure mentioned in question 7. This structure is typically saved in a file `physio.mat`.
`physio.ons_secs` then contains the different time courses, cropped to the acquisition window synchronized to your fMRI scan (the same values before synchronization/cropping, is found in `physio.ons_secs.raw`). Here are the most important ones:
- `ons_secs.t` = []; % time vector corresponding to c and r
- `ons_secs.c` = []; % raw cardiac waveform (ECG or PPU)
- `ons_secs.r` = []; % raw respiration amplitude time course
- `ons_secs.cpulse` = []; % onset times of cardiac pulse events (e.g. R-peaks)
- `ons_secs.fr` = []; % filtered respiration amplitude time series
- `ons_secs.c_sample_phase` = []; % phase in heart-cycle when each slice of each volume was acquired
- `ons_secs.r_sample_phase` = []; % phase in respiratory cycle when each slice of each volume was acquired
- `ons_secs.hr` = []; % [nScans,1] estimated heart rate at each scan
- `ons_secs.rvt` = []; % [nScans,1] estimated respiratory volume per time at each scan
- `ons_secs.c_outliers_high` = []; % onset of too long heart beats
- `ons_secs.c_outliers_low` = []; % onsets of too short heart beats
- `ons_secs.r_hist` = []; % histogram of breathing amplitudes
For a detailed list of all properties and their documentation, read the source code of `tapas_physio_new.m`
10. What is the order of the regressor columns in the multiple regressors file?
-------------------------------------------------------------------------------
This depends on the physiological models (and their order) specified in the `model`-submodule of physio (or in the batch editor). The general order is outlined in Fig. 7A of the [http://dx.doi.org/10.1016/j.jneumeth.2016.10.019](Main PhysIO Toolbox Paper). The []-brackets indicate the number of regressors:
1. RETROICOR cardiac regressors [2 x nOrderCardiac]
2. RETROICOR respiratory regressors [2 x nOrderRespiratory]
3. RETROICOR cardXResp interaction regressors [4 x nOrderCardiacXRespiratory]
4. HRV [nDelaysHRV]
5. RVT [nDelaysRVT]
6. Noise ROIs (PCA signatures and mean of each region) [nNoiseROIs x (nComponents+1)]
7. Other (included other text file) [nColumnsOtherFile]
8. Motion [6 or 12 or 24, depending on motion model]
If any of the models was not specified, the number of regressors is reduced accordingly.
11. How do I know whether the physiological noise correction worked?
--------------------------------------------------------------------
The best way to assess the quality of the correction is an F-test over the respective physiological noise model regressors in the design matrix. Luckily, if you use SPM, the toolbox can create these contrasts and corresponding output plots with overlays of your brain automatically via calling the following function in the Matlab command window:
```
args = tapas_physio_report_contrasts(...
'fileReport', 'physio.ps', ...
'fileSpm', 'analysisFolder/SPM.mat', ...
'filePhysIO', 'analysisFolder/physio.mat', ...
'fileStructural', 'anatomyFolder/warpedAnatomy.nii')
```
Of course, you will have to adapt all paths to your `SPM.mat`, `physio.mat` and `anatomy.nii` files. There are more parameters to set (e.g. F-contrast thresholds), type `help tapas_physio_report_contrasts` for a list of options.
There should be whole-brain multiple-comparison corrected "activation" in physiological noise sites (similar to Fig. 8C or 9 in our [paper](https://doi.org/10.1016/j.jneumeth.2016.10.019).
If your F-contrast results differ or are absent, have a look at the *Diagnostic raw physiological time series*-plot and check whether it resembles Fig. 3 in the paper or whether there are any suspicious spikes in the heart cycle length.
Other than that, scan timing synchronisation is a major source of error, so always check the *Cutout actual scans* plot, whether the curves and scan events, TR etc. make sense.
12. I cannot find the answer to my question in the FAQ. Whom do I ask for help?
------------------------------------------------------------------------------
Subscribe to our TAPAS mailing list by clicking **Subscribe** on the left side of [this website]( <https://sympa.ethz.ch/sympa/info/tapas>)
Afterwards you can send e-mails with your questions to `tapas@sympa.ethz.ch`. Both, core developers of PhysIO and experienced users are receiving your e-mail and are eager to help.
The mailing list also has a searchable archive (click **Archive** on the left of above-mentioned website), where you might already find the answer to your question.
\ No newline at end of file