CHANGELOG.md 17.9 KB
Newer Older
1
RELEASE INFORMATION
Lars Kasper's avatar
Lars Kasper committed
2
===================
3
4
5
6

Current Release
---------------

Lars Kasper's avatar
Lars Kasper committed
7
*Current version: PhysIO Toolbox Release R2022b, v8.2.0*
8

Lars Kasper's avatar
Lars Kasper committed
9
September 12th, 2022
Lars Kasper's avatar
Lars Kasper committed
10

Lars Kasper's avatar
Lars Kasper committed
11
12
13
14
15
16
17
18
19
20
21
22
23
Minor Release Notes (v8.2.0)
----------------------------

### Added
- Interface `tapas_physio_test` to TAPAS-generic `tapas_test` function
- Added suport for logfile version 3 of Siemens physio recordings 
    - multi ECG/Resp channels and interleaved status messages
    - new integration test for Siemens VB Logversion 3
### Fixed
- Removed dependence on `nanmean` (Statistics Toolbox)
    - See GitHub issue #205 
- Compatibility with multiple SPM toolbox locations for `lmod` ([GitHUb issue #211](https://github.com/translationalneuromodeling/tapas/issues/211))
    - as listed in `spm_get_defaults('tbx')`
Lars Kasper's avatar
Lars Kasper committed
24

Lars Kasper's avatar
Lars Kasper committed
25
26
Minor Release Notes (v8.1.0)
----------------------------
Lars Kasper's avatar
Lars Kasper committed
27
28

### Added
Lars Kasper's avatar
Lars Kasper committed
29
30
31
32
33
34
- Compatibility of whole code base with Matlab compiler in order to run `spm_make_standalone`
    - provides oppurtunity to run SPM Batch Editor GUI version of PhysIO without Matlab license requirement 
    - compiled version readily available within [Neurodesk](https://neurodesk.github.io/tutorials/functional_imaging/physio/) 
- BIDS Read-in for separate cardiac/respiratory trace files (e.g., due to different sampling frequencies)
    - see GitHub Issue #164 and pull request #167 by @alexsayal
    - Additional unit tests for new read-in and example data
Lars Kasper's avatar
Lars Kasper committed
35
36

### Changed
Lars Kasper's avatar
Lars Kasper committed
37
38
- Switch for certain toolbox functions (e.g., `imtool`) to only run in 
  non-compiled code
Lars Kasper's avatar
Lars Kasper committed
39
40

### Fixed
Lars Kasper's avatar
Lars Kasper committed
41
42
43
44
- Documentation (function headers, see Github issue #149)
- Typos in unused function (spotted in compilation)
- Synchronization SIEMENS AcquisitionLog / Physiological files (see Github issue #172)
    - better visualization of sync, clearer error messages if dummy scans not found
Lars Kasper's avatar
Lars Kasper committed
45

Lars Kasper's avatar
v8.0.1    
Lars Kasper committed
46
47
48
49
50
51
52
Bugfix Release Notes (v8.0.1)
-----------------------------

### Changed
- Citation of novel [TAPAS paper](https://doi.org/10.3389/fpsyt.2021.680811) in README and CITATION


Lars Kasper's avatar
Lars Kasper committed
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
Major Release Notes (v8.0.0)
----------------------------

### Added
- New method for computing respiratory volume per unit time (RVT) via the
  Hilbert transform.
    - Publication: Harrison et al., "A Hilbert-based method for processing
      respiratory timeseries", NeuroImage, 2021.
      <https://doi.org/10.1016/j.neuroimage.2021.117787>
    - This is now the default option, but the old method is available by
      setting `physio.model.rvt.method = 'peaks'` (or the equivalent within
      the SPM batch editor).

- Respiratory preprocessing now includes an optional de-spiking step based on
  median filtering.

### Changed
- Now possible to change the frequencies of the respiratory filtering during
  preprocessing via `physio.preproc.respiratory.filter` (or the equivalent
  within the SPM batch editor).

- More robust detrending of raw respiratory timeseries via windowed padding
  before filtering.

### Fixed


Bugfix Release Notes (v7.3.2)
-----------------------------

### Added
- version number `physio.version` in physio-struct (Gitlab issue #101)

### Fixed
- Subfolder of SPM in path (fieldtrip) created ambiguous function calls 
  to overloaded functions (Gitlab issue #102 and Gihub issue #110)
    - e.g., `filtfilt` in `tapas_physio_filter_respiratory` created flat 
      regressors for v7.3 for Siemens VD example dataset
    - now subfolders of SPM will be removed when calling
     `tapas_physio_main_create_regressors`


Bugfix Release Notes (v7.3.1)
-----------------------------

### Fixed
- PPU read-in works for BioPac mat-file now 
    - correct column labels and cardiac modality (Github Issue #103)
    - thank you to Manon Durand-Ruel @mdurandruel for reporting  


Lars Kasper's avatar
Lars Kasper committed
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
Minor Release Notes (R2020a, v7.3.0)
------------------------------------

### Added
- Added descriptive names for the multiple regressors matrix.
    - Closes GitLab issue #82.
    - Now possible to straightforwardly inspect `physio.model.R` and the
      contents of `physio.model.output_multiple_regressors` using
      `physio.model.R_column_names`.
    - Added `tapas_physio_guess_regressor_names()` to maintain backwards
      compatibility.
- New example datasets Siemens VB PPU3T with DICOM Sync (courtesy of Alexander Ritter, Jena, Germany)
- More versatile control on figure visibility, saving and closing during `main` and `review` runs of PhysIO
    - feature provided by Stephan Heunis, TU Eindhoven, The Netherlands (github issue #89)
    - figures can now be plotted in the background without disturbing interactive Matlab sessions, and can be (more) selectively saved and closed during execution of `tapas_physio_review`
    - more comprehensive support within `tapas_physio_main_create_regressors` to follow


Bugfix Release Notes (v7.2.8)
-----------------------------

### Fixed
- Bug(s) when checking SPM and PhysIO paths in `tapas_physio_init` under
  certain particular Matlab path environment settings (Gitlab merge request !37)
    - e.g., when add `physio-public/code` manually without subfolder
    - or if spm existed as a folder name without being added to path


Bugfix Release Notes (v7.2.7)
-----------------------------

### Changed
- Reimplemented `tapas_physio_filter_respiratory.m`.
    - Closes GitLab issue #98.
    - Reduces the cut-off frequency of the high-pass filter, so as to behave
      more like a detrending step. Previous value of 0.1 Hz could distort e.g.
      sigh breaths, which can easily last upwards of 10 s.
    - Reimplements the filters themselves, with a higher filter order, extra
      padding, and a two step high-pass and low-pass procedure (i.e. rather
      than band pass) to improve the overall stability.


Bugfix Release Notes (v7.2.6)
-----------------------------

### Fixed
- Meaningful error message for `auto_matched` peak detection, if time series is too short
    - at least 20 peaks (and pulse templates) are required to create a pulse template
    - this is now stated explicitly, if time series is too short
    - reported by Joy Schuurmans Stekhoven, TNU, as gitlab issue #92


Bugfix Release Notes (v7.2.5)
-----------------------------

### Fixed
- Corrected documentation for ` preproc.cardiac.initial_cpulse_select.min` parameter
    - threshold for peak relative to z-scored time series, *not* correlation
    - reported by Sam Harrison, TNU, as gitlab issue #95


Bugfix Release Notes (v7.2.4)
-----------------------------

### Fixed
- Stop docked figure default throwing error with `-nodisplay`
    - allows generating saved figure without a display, e.g., on remote server
    - bugfix provided by Sam Harrison, TNU


Bugfix Release Notes (v7.2.3)
-----------------------------

### Fixed
- Bugfix manual peak selection (Github issue #85, Gitlab #90)
    - did not work because of figure handling


Bugfix Release Notes (v7.2.2)
-----------------------------

### Fixed
- Bugfix Siemens VB (`*.resp, *.puls, *.ecg`)
    - Synchronization to DICOM time stamp did not work for extended physiological recordings (not starting/ending with functional run) due to ignored absolute start time stamp
    - reported by Alexander Ritter, Jena, Germany (Github issue #55, Gitlab #87)
    - probably fixes Github issue #63 (Gitlab #86) as well


Bugfix Release Notes (v7.2.1)
-----------------------------

### Changed
- PhysIO: removed Matlab statistics toolbox dependency for PCA by SVD implementation (thanks to Benoît Beranger, [pull request 64](https://github.com/translationalneuromodeling/tapas/pull/64))
    - new function `tapas_physio_pca` allows for switch between stats and native SVD implementation of PCA
    - comes with unit tests checking equivalency
Lars Kasper's avatar
Lars Kasper committed
199
200


Lars Kasper's avatar
Lars Kasper committed
201
202
Minor Release Notes (R2019b, v7.2.0)
------------------------------------
Lars Kasper's avatar
Lars Kasper committed
203

Lars Kasper's avatar
Lars Kasper committed
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
### 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
Lars Kasper's avatar
Lars Kasper committed
224
225
226
227
228
  erroneous use of Matlab `conv` 
    - For details on the bug, its impact and fix, see our specific [Release
    Info on RVT/HRV Bugfix](https://github.com/translationalneuromodeling/tapas/issues/65)
    - other references: TNU gitlab issue #83, found and fixed by Sam Harrison,
    TNU, see `tapas_physio_conv`)
Lars Kasper's avatar
Lars Kasper committed
229
230
231
232
233
234
235
- 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

Lars Kasper's avatar
Lars Kasper committed
236

Lars Kasper's avatar
Lars Kasper committed
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
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)
----------------------------------------

Lars Kasper's avatar
Lars Kasper committed
277
278
279
280
281
### Changed
- fixed bug for matching of Philips SCANPHYSLOG-files (Gitlab #62), if 
  physlogs were acquired on different days, but similar times


Lars Kasper's avatar
Lars Kasper committed
282
283
Bugfix Release Notes (R2018.1.2, v7.0.2)
----------------------------------------
Lars Kasper's avatar
Lars Kasper committed
284
285
286
287

### Added
- BioPac txt-file reader (for single file, resp/cardiac/trigger data in different columns)

Lars Kasper's avatar
Lars Kasper committed
288
289
290
291
292
293
### 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)
----------------------------------------
Lars Kasper's avatar
Lars Kasper committed
294
295
296
297

### Changed
- documentation.{html,pdf} export nicer with different FAQ numbering

Lars Kasper's avatar
Lars Kasper committed
298
299
300

Major Release Notes (R2018.1, v7.0.0)
-------------------------------------
Lars Kasper's avatar
Lars Kasper committed
301
302
303
304
305
306
307
308
309
310
311
312

### Added
- initialization function `tapas_physio_init()` to check Matlab paths, including SPM for batch processing
- Extended motion diagnostics via Framewise displacement (Power et al., 2012)
    - Outlier motion models generate 'spike' regressors from FD outliers (gitlab issue  #)
- Censoring of intervals with bad physiological recordings in RETROICOR regressors (github issue #11, gitlab #36)
- Added examples of Siemens VD (Tics Format, Prisma) and Human Connectome Project (HCP) format

### Changed
- Updated read-in examples of all vendors (Siemens, Philips, GE) to latest PhysIO Toolbox version.
- Updated `README.md` to reflect changes to example download, new references
- Extended Wiki documentation, in particular examples and read-in formats
Lars Kasper's avatar
Lars Kasper committed
313

Lars Kasper's avatar
Lars Kasper committed
314
315
316

Minor Release Notes (R2017.3, v6.3.0)
-------------------------------------
Lars Kasper's avatar
Lars Kasper committed
317
318
319
320
321
322
323
324
325
326
327

- 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`)
- Updated Siemens Reader for Multiband patches(CMRR), versions EJA_1
    - including multi-echo data (4,5 columns)
    - multi-channel ECG data
    - significant speed up of read-in
    - generalized framework for later changes to format
    - interpolation of different sampling rates RESP/CARDIAC
- updated README about documentation, new support policy and [TAPAS on GitHub](https://translationalneuromodeling.github.io/tapas)
- extended FAQ
328

Lars Kasper's avatar
Lars Kasper committed
329
330
331

Minor Release Notes (R2017.2, v6.2.0)
-------------------------------------
332
333
334
335
336
337
338

- Included Markdown-based documentation via Wiki (also CITATION, LICENSE, CHANGELOG.md)
- Included FAQ in Wiki
- Split git repositories into public, dev, examples, and added wiki, to disentangle development from deployed toolbox code and data
- Bugfix and Typo correction
- Philips SCANPYHSLOG for their software release 5.1.7.

Lars Kasper's avatar
Lars Kasper committed
339
340
341

Minor Release Notes (R2017.1, v6.1.0)
-------------------------------------
342
343
344
345
346
347
348

- Substantially improved Siemens interface, both for VB/VD and 3T/7T releases
    - several bugfixes
    - based on extensive user feedback from Berlin and Brisbane
- New functionality tapas_physio_overlay_contrasts.m to display non-physio 
  contrasts automatically as well

Lars Kasper's avatar
Lars Kasper committed
349
350
351

Major Release Notes (r904 / R2016.1, v6.0.0)
--------------------------------------------
352
353
354
355
356
357
358
359
360
361

- Software version for accepted PhysIO Toolbox Paper: doi:10.1016/j.jneumeth.2016.10.019
- Tested and expanded versions of examples
- Improved stability by bugfixes and compatibility to Matlab R2016
- Slice-wise regressor creation
- Detection of constant physiological time series (detachment, clipping)
- Refactoring of report_contrasts and compute_tsnr_gains as standalone functionality
- Improved Read-in capabilities (Siemens respiration data, BioPac .mat)
- Migration from svn (r904) to git (tnurepository) for version control

Lars Kasper's avatar
Lars Kasper committed
362
363
364

Major Release Notes (r835, v5.0.0)
----------------------------------
365
366
367
368
369
370
371
372
373
374

- Software version for Toolbox Paper submission
- Noise ROIs modeling
- Extended motion models (24 parameters, Volterra expansion)
- HRV/RVT models with optional multiple delay regressors
- Report_contrasts with automatic contrast generation for all regressor groups
- compute_tsnr_gains for individual physiological regressor groups
- consistent module naming (scan_timing, preproc)
- Visualisation improvement (color schemes, legends)

Lars Kasper's avatar
Lars Kasper committed
375
376
377

Minor Release Notes (r666, v4.1.0)
----------------------------------
378
379
380
381
382
383
384
385
386
387

- Compatibility tested for SPM12, small bugfixes Batch Dependencies
- Cleaner Batch Interface with grouped sub-menus (cfg_choice)
- new model: 'none' to just read out physiological raw data and preprocess,
  without noise modelling 
- Philips: Scan-timing via gradient log now automatized (gradient_log_auto)
- Siemens: Tics-Logfile read-in (proprietary, needs Siemens-agreement)
- All peak detections (cardiac/respiratory) now via auto_matched algorithm
- Adapt plots/saving for Matlab R2014b

Lars Kasper's avatar
Lars Kasper committed
388
389
390

Major Release Notes (r534, v4.0.0)
----------------------------------
391
392

- Read-in of Siemens plain text log files; new example dataset for Siemens
Lars Kasper's avatar
Lars Kasper committed
393
394
- Speed up and debugging of auto-detection method for noisy cardiac data => new
method thresh.cardiac.initial_cpulse_select.method = 'auto_matched'
395
396
397
- 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

Lars Kasper's avatar
Lars Kasper committed
398
399
400

Major Release Notes (r497, v3.0.0)
----------------------------------
401
402
403
404
405
406
407

- 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)
- QuickStart-Manual and PhysIO-Background presentation expanded/updated
- job .m/.mat-files created for all example datasets
- bugfixes cpulse-initial-select method-handling (auto/manual/load)

Lars Kasper's avatar
Lars Kasper committed
408
409
410

Major Release Notes (r429, v2.0.0)
----------------------------------
411
412
413
414
415
416
417

- Cardiac and Respiratory response function regressors integrated in workflow (heart rate and breathing volume computation)
- Handling of Cardiac and Respiratory Logfiles only
- expanded documentation (Quickstart.pdf and Handbook.pdf)
- read-in of custom log files, e.g. for BrainVoyager peripheral data
- more informative plots and commenting (especially in tapas_physio_new).

Lars Kasper's avatar
Lars Kasper committed
418
419
420

Minor Release Notes (r354, v1.1.0)
----------------------------------
421
422
423
424

- computation of heart and breathing rate in Philips/PPU/main_PPU.m
- prefix of functions with tapas_*

Lars Kasper's avatar
Lars Kasper committed
425
426
427

Major Release Notes (r241, v1.0.0)
----------------------------------
428
429
430
431
432
433
434
435
436

- complete modularization of reading/preprocessing/regressor creation for peripheral physiological data
- manual selection of missed heartbeats in ECG/pulse oximetry (courtesy of Jakob Heinzle)
- support for logfiles from GE scanners (courtesy of Steffen Bollmann, KiSpi Zuerich)
- improved detection of pulse oximetry peaks (courtesy of Steffen Bollmann)
- improved documentation
- 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.