Commit c57b34b9 authored by Lars Kasper's avatar Lars Kasper

updated doc files from public

parent c94a17f4
......@@ -4,42 +4,107 @@ RELEASE INFORMATION
Current Release
---------------
PhysIO_Toolbox_R2018.1.3
*Current version: PhysIO Toolbox Release R2019a, v7.1.0*
October 30, 2018
March 19, 2019
WIP Release Notes (R2018.2.0)
-----------------------------
*not released yet*
### CHANGED
- put all functions in `code` into subfolders relating to different modules: `readin`, `sync`, `preproc`, `model`, `assess`, `utils` (gitlab-issue #58)
- updated deployment `tapas_physio_init` because of that
Bugfix Release Notes (R2018.1.3)
Unreleased (R2019b, v7.2.0-beta)
--------------------------------
### Added
- `requirements.txt` making dependencies on Matlab and specific toolboxes
explicit
- `max_heart_rate_bpm` now a user parameter to adjust prior on max allowed
heart rate for cardiac pulse detection (`method = 'auto_matched'`)
- bandpass-filtering of cardiac data during preprocessing now possible
(`preproc.cardiac.filter`)
- Added integration tests for all examples in `tests/integration` for both SPM
Batch Editor and Matlab-only configuration scripts. Reference data provided in
`examples/TestReferenceResults/examples`
### Changed
- Toned down and replaced irrelevant peak height and missing cardiac pulse
warnings (github issue #51)
- Updated README to include external contributors and recent findings about
impact of physiological noise for serial correlations (Bollmann2018)
- Added unit tests for convolution and moved all to `tests/unit`
### Fixed
- Corrected half-width shift of response functions for HRV and RVT regressors by
erroneous use of Matlab conv (gitlab issue #83, found and fixed by Sam
Harrison, TNU, see `tapas_physio_conv`)
- Bugfix `tapas_physio_init()` not working, because dependent on functions
in `utils` subfolder not in path; `utils` added to path
- `tapas_physio_review` for motion parameters (found and fixed by
Sam Harrison, TNU)
- visualization error for regressor orthogonalization (github issue #57),
when only `'RETROICOR'` set was chosen
Minor Release Notes (R2019a, v7.1.0)
------------------------------------
### Added
- BIDS reader and example (Brain Imaging Data Structure,
http://bids.neuroimaging.io/bids_spec.pdf) for `*_physio.tsv[.gz]/.json` files
- Added BioPac txt-File read-in and example
- Template example with all physio-fields for matlab script and settings as in default SPM batch
- Started unit testing framework in folder `tests`
- example functions for findpeaks and BIDS readin
- reference data saved with example data in subfolder `TestReferenceResults`
- reference data reflects physio structure after running example scripts
with PhysIO R2019a
### Changed
- put all functions in `code` into subfolders relating to different modules:
`readin`, `sync`, `preproc`, `model`, `assess`, `utils` (gitlab-issue #58)
- updated deployment `tapas_physio_init` because of that
- updated figure names to reflect respective code module
- matlab-script examples now contain more comments
- fixed internal bug that prepended absolute paths to input logfiles in automatic example generation
- `tapas_physio_create_noise_rois_regressors` with more flexible ROI reslicing
options (speed-up) and uses `spm_erode` (no Matlab image processing toolbox needed),
thanks to a [contribution by Benoît Béranger](https://github.com/translationalneuromodeling/tapas/pull/34)
- introduced semantic version numbers for all previous releases, and changed
Release numbering to R<YEAR><LETTER> style
- extended documentation (FAQ, new read-in BIDS)
- several bugfixes (Sep 18 - Mar 19), see
[GitHub Issues](https://github.com/translationalneuromodeling/tapas/issues?q=label:physio)
### Removed
- `tapas_physio_findpeaks` now refers to current Matlab signal processing
toolbox implementation, instead of copy of older version
- some Matlab toolbox dependencies by custom simplified functions (e.g.,
`suptitle`)
Bugfix Release Notes (R2018.1.3, v7.0.3)
----------------------------------------
### Changed
- fixed bug for matching of Philips SCANPHYSLOG-files (Gitlab #62), if
physlogs were acquired on different days, but similar times
Bugfix Release Notes (R2018.1.2)
--------------------------------
### Changed
- fixed bug for 3D nifti array read-in in tapas_physio_create_noise_rois_regressors (github issue #24, gitlab #52)
Bugfix Release Notes (R2018.1.2, v7.0.2)
----------------------------------------
### Added
- BioPac txt-file reader (for single file, resp/cardiac/trigger data in different columns)
Bugfix Release Notes (R2018.1.1)
-------------------------------
### Changed
- fixed bug for 3D nifti array read-in in tapas_physio_create_noise_rois_regressors (github issue #24, gitlab #52)
Bugfix Release Notes (R2018.1.1, v7.0.1)
----------------------------------------
### Changed
- documentation.{html,pdf} export nicer with different FAQ numbering
Major Release Notes (R2018.1)
-----------------------------
Major Release Notes (R2018.1, v7.0.0)
-------------------------------------
### Added
- initialization function `tapas_physio_init()` to check Matlab paths, including SPM for batch processing
......@@ -53,8 +118,9 @@ Major Release Notes (R2018.1)
- Updated `README.md` to reflect changes to example download, new references
- Extended Wiki documentation, in particular examples and read-in formats
Minor Release Notes (R2017.3)
-----------------------------
Minor Release Notes (R2017.3, v6.3.0)
-------------------------------------
- Included references to external [ETH gitlab physio-doc repo and wiki](https://gitlab.ethz.ch/physio/physio-doc)
- New Human Connectome Project reader for preprocessed Siemens 3-column logfiles (`*Physio_log.txt`)
......@@ -67,8 +133,9 @@ Minor Release Notes (R2017.3)
- updated README about documentation, new support policy and [TAPAS on GitHub](https://translationalneuromodeling.github.io/tapas)
- extended FAQ
Minor Release Notes (R2017.2)
-----------------------------
Minor Release Notes (R2017.2, v6.2.0)
-------------------------------------
- Included Markdown-based documentation via Wiki (also CITATION, LICENSE, CHANGELOG.md)
- Included FAQ in Wiki
......@@ -76,8 +143,9 @@ Minor Release Notes (R2017.2)
- Bugfix and Typo correction
- Philips SCANPYHSLOG for their software release 5.1.7.
Minor Release Notes (R2017.1)
-----------------------------
Minor Release Notes (R2017.1, v6.1.0)
-------------------------------------
- Substantially improved Siemens interface, both for VB/VD and 3T/7T releases
- several bugfixes
......@@ -85,8 +153,9 @@ Minor Release Notes (R2017.1)
- New functionality tapas_physio_overlay_contrasts.m to display non-physio
contrasts automatically as well
Major Release Notes (r904 / R2016.1)
------------------------------------
Major Release Notes (r904 / R2016.1, v6.0.0)
--------------------------------------------
- Software version for accepted PhysIO Toolbox Paper: doi:10.1016/j.jneumeth.2016.10.019
- Tested and expanded versions of examples
......@@ -97,8 +166,9 @@ Major Release Notes (r904 / R2016.1)
- Improved Read-in capabilities (Siemens respiration data, BioPac .mat)
- Migration from svn (r904) to git (tnurepository) for version control
Major Release Notes (r835)
--------------------------
Major Release Notes (r835, v5.0.0)
----------------------------------
- Software version for Toolbox Paper submission
- Noise ROIs modeling
......@@ -109,8 +179,9 @@ Major Release Notes (r835)
- consistent module naming (scan_timing, preproc)
- Visualisation improvement (color schemes, legends)
Minor Release Notes (r666)
--------------------------
Minor Release Notes (r666, v4.1.0)
----------------------------------
- Compatibility tested for SPM12, small bugfixes Batch Dependencies
- Cleaner Batch Interface with grouped sub-menus (cfg_choice)
......@@ -121,16 +192,19 @@ Minor Release Notes (r666)
- All peak detections (cardiac/respiratory) now via auto_matched algorithm
- Adapt plots/saving for Matlab R2014b
Major Release Notes (r534)
--------------------------
Major Release Notes (r534, v4.0.0)
----------------------------------
- Read-in of Siemens plain text log files; new example dataset for Siemens
- Speed up and debugging of auto-detection method for noisy cardiac data => new method thresh.cardiac.initial_cpulse_select.method = ???auto_matched???
- Speed up and debugging of auto-detection method for noisy cardiac data => new
method thresh.cardiac.initial_cpulse_select.method = 'auto_matched'
- Error handling for temporary breathing belt failures (Eduardo Aponte, TNU Zurich)
- slice-wise regressors can be created by setting sqpar.onset_slice to a index vector of slices
Major Release Notes (r497)
--------------------------
Major Release Notes (r497, v3.0.0)
----------------------------------
- SPM matlabbatch GUI implemented (Call via Batch -> SPM -> Tools -> TAPAS PhysIO Toolbox)
- improved, automatic heartbeat detection for noisy ECG now standard for ECG and Pulse oximetry (courtesy of Steffen Bollmann)
......@@ -138,8 +212,9 @@ Major Release Notes (r497)
- job .m/.mat-files created for all example datasets
- bugfixes cpulse-initial-select method-handling (auto/manual/load)
Major Release Notes (r429)
--------------------------
Major Release Notes (r429, v2.0.0)
----------------------------------
- Cardiac and Respiratory response function regressors integrated in workflow (heart rate and breathing volume computation)
- Handling of Cardiac and Respiratory Logfiles only
......@@ -147,14 +222,16 @@ Major Release Notes (r429)
- read-in of custom log files, e.g. for BrainVoyager peripheral data
- more informative plots and commenting (especially in tapas_physio_new).
Minor Release Notes (r354)
--------------------------
Minor Release Notes (r354, v1.1.0)
----------------------------------
- computation of heart and breathing rate in Philips/PPU/main_PPU.m
- prefix of functions with tapas_*
Major Release Notes (r241)
--------------------------
Major Release Notes (r241, v1.0.0)
----------------------------------
- complete modularization of reading/preprocessing/regressor creation for peripheral physiological data
- manual selection of missed heartbeats in ECG/pulse oximetry (courtesy of Jakob Heinzle)
......@@ -164,4 +241,3 @@ Major Release Notes (r241)
- consistent function names (prefixed by "physio_")
NOTE: Your main_ECG/PPU.m etc. scripts from previous versions (<=r159) will not work with this one any more. Please adapt one of the example scripts for your needs (~5 min of work). The main benefit of this version is a complete new variable structure that is more sustainable and makes the code more readable.
TAPAS PhysIO Toolbox
====================
*Current version: 2018.1.3*
*Current version: Release 2019a, v7.1.0*
> Copyright (C) 2012-2018
> Copyright (C) 2012-2019
> Lars Kasper
> <kasper@biomed.ee.ethz.ch>
>
......@@ -76,7 +76,8 @@ Getting Started
...following the installation, you can try out an example:
1. Download the TAPAS examples via running `tapas_download_example_data()` (found in `misc`-subfolder of TAPAS)
1. Download the TAPAS examples via running `tapas_download_example_data()`
(found in `misc`-subfolder of TAPAS)
- The PhysIO Example files will be downloaded to `tapas/examples/<tapas-version>/PhysIO`
2. Run `philips_ecg3t_matlab_script.m` in subdirectory `Philips/ECG3T`
3. See subdirectory `physio/docs` and the next two section of this document for help.
......@@ -98,7 +99,9 @@ pointers and templates. Before you contact us, please try the following:
[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
[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).
[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).
Documentation
......@@ -144,8 +147,14 @@ Facts about physiological noise in fMRI:
become a particular concern at and above 3 Tesla (Kasper2009, Hutton2011).
- In resting state fMRI, disregarding physiological noise leads to wrong
connectivity results (Birn2006).
- 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)
Therefore, some kind of physiological noise correction is highly recommended for every statistical fMRI analysis.
Therefore, some kind of physiological noise correction is highly recommended for
every statistical fMRI analysis.
Model-based correction of physiological noise:
- Physiological noise can be decomposed into periodic time series following
......@@ -174,30 +183,39 @@ Features of this Toolbox
- Flexible expansion orders to model different contributions of cardiac,
respiratory and interaction terms (see Harvey2008, Hutton2011)
- Data-driven noise regressors
- PCA extraction from nuisance ROIs (CSF, white matter), similar to aCompCor (Behzadi2007)
- PCA extraction from nuisance ROIs (CSF, white matter), similar to aCompCor
(Behzadi2007)
### Automatization and Performance Assessment
- Automatic creation of nuisance regressors, full integration into standard
GLMs, tested for SPM8/12 ("multiple_regressors.mat")
- 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
- 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()`.
### Flexible Read-in
The toolbox is dedicated to seamless integration into a clinical research s
etting and therefore offers correction methods to recover physiological
data from imperfect peripheral measures.
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):
- 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.
- General Electric
- Philips SCANPHYSLOG files (all versions from release 2.6 to 5.3)
- Siemens VB (files `.ecg`, `.resp`, `.puls`)
- Siemens VD (files `*_ECG.log`, `*_RESP.log`, `*_PULS.log`)
- Siemens Human Connectome Project (preprocessed files `*Physio_log.txt`)
- 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
- 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.
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.
Compatibility
......@@ -217,7 +235,9 @@ Compatibility
or as text file for export to any other package
- raw and processed physiological logfile data
- Graphical Batch Editor interface to SPM
- Part of the TAPAS Software Collection of the Translational Neuromodeling Unit (TNU) Zurich:long term support and ongoing development
- Part of the TAPAS Software Collection of the Translational Neuromodeling Unit
(TNU) Zurich
- ensures long term support and ongoing development
Contributors
......@@ -229,12 +249,43 @@ Contributors
- Project Team:
- Steffen Bollmann, Centre for Advanced Imaging, University of Queensland, Australia
- Saskia Bollmann, Centre for Advanced Imaging, University of Queensland, Australia
- Contributors:
- Contributors (Code):
- Eduardo Aponte, TNU Zurich
- Tobias U. Hauser, FIL London, UK
- Sam Harrison, TNU Zurich
- Jakob Heinzle, TNU Zurich
- Chloe Hutton, FIL London, UK (previously)
- Miriam Sebold, Charite Berlin, Germany
- 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
References
......@@ -242,55 +293,79 @@ References
### Main Toolbox Reference
Please cite the following paper in all of your publications that utilized the
PhysIO Toolbox.
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.
Journal of Neuroscience Methods 276, 56–72. doi:10.1016/j.jneumeth.2016.10.019
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.
### Related Papers (Implemented noise correction algorithms and optimal parameter choices)
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.
#### RETROICOR
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).
3. Hutton, C. et al. The impact of PhysIOlogical noise correction on fMRI at 7 T.
3. Hutton, C. et al. The impact of Physiological noise correction on fMRI at 7 T.
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).
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
#### aCompCor / Noise ROIs
5. Behzadi, Y., Restom, K., Liau, J., Liu, T.T., 2007. A component based noise
6. 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
90–101. https://doi.org/10.1016/j.neuroimage.2007.04.042
#### RVT
6. Birn, R.M., Smith, M.A., Jones, T.B., Bandettini, P.A., 2008. The respiration response
7. 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
7. Jo, H.J., Saad, Z.S., Simmons, W.K., Milbury, L.A., Cox, R.W., 2010.
8. Jo, H.J., Saad, Z.S., Simmons, W.K., Milbury, L.A., Cox, R.W., 2010.
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
*regressor delay suggestions*
- *regressor delay suggestions*
#### HRV
8. Chang, C., Cunningham, J.P., Glover, G.H., 2009. Influence of heart rate on the
9. 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
9. Shmueli, K., van Gelderen, P., de Zwart, J.A., Horovitz, S.G., Fukunaga, M.,
10. Shmueli, K., van Gelderen, P., de Zwart, J.A., Horovitz, S.G., Fukunaga, M.,
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
*regressor delay suggestions*
- *regressor delay suggestions*
#### Motion (Censoring, Framewise Displacement)
10. Siegel, J.S., Power, J.D., Dubis, J.W., Vogel, A.C., Church, J.A., Schlaggar, B.L.,
11. 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
35, 1981–1996. https://doi.org/10.1002/hbm.22307
11. 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
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
Copying/License
......@@ -308,4 +383,4 @@ 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
<http://www.gnu.org/licenses/>.
\ No newline at end of file
<http://www.gnu.org/licenses/>.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment