|
|
# Brain Imaging Data Structure (BIDS)
|
|
|
|
|
|
PhysIO supports physiological logfiles prepared according to the [BIDS standard](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/06-physiological-and-other-continous-recordings.html)
|
|
|
|
|
|
- In brief, BIDS files are (optionally compressed) tab-separated values
|
|
|
(`*.tsv[.gz]`) files that contain raw traces of peripheral recordings from
|
|
|
cardiac and respiratory sources, as well as scan trigger events
|
|
|
- The header of the columns of this `*.tsv` file, as well as meta-information,
|
|
|
such as sampling rate and relative onset of physiological logging to MRI scan
|
|
|
onset is described in an accompanying `*.json` file
|
|
|
- It is assumed to have the that this `*.json` file has the same name
|
|
|
(apart from the extension) as the `*.tsv` file
|
|
|
- If PhysIO does not find this file, you can manually enter the timing
|
|
|
information in the `log_files` structure, and a default column order of
|
|
|
(cardiac, respiratory, trigger) is assumed
|
|
|
- Example `*.tsv` file (with cardiac, respiratory, trigger column
|
|
|
:
|
|
|
- In brief, BIDS files are (optionally compressed) tab-separated values (`\*.tsv\[.gz\]`) files that contain raw traces of peripheral recordings from cardiac and respiratory sources, as well as scan trigger events
|
|
|
- The header of the columns of this `\*.tsv` file, as well as meta-information, such as sampling rate and relative onset of physiological logging to MRI scan onset is described in an accompanying `\*.json` file
|
|
|
- It is assumed to have the that this `\*.json` file has the same name (apart from the extension) as the `\*.tsv` file
|
|
|
- If PhysIO does not find this file, you can manually enter the timing information in the `log_files` structure, and a default column order of (cardiac, respiratory, trigger) is assumed
|
|
|
- Example `\*.tsv` file (with cardiac, respiratory, trigger column :
|
|
|
|
|
|
```
|
|
|
-0.949402 -0.00610382 0
|
|
|
-0.949402 -0.00610382 0
|
... | ... | @@ -24,7 +18,9 @@ onset is described in an accompanying `*.json` file |
|
|
-0.95459 -0.0076297 1
|
|
|
-0.95459 -0.0076297 0
|
|
|
```
|
|
|
- Example `*.json` file:
|
|
|
|
|
|
- Example `\*.json` file:
|
|
|
|
|
|
```
|
|
|
{
|
|
|
"SamplingFrequency": 50.0,
|
... | ... | @@ -36,14 +32,14 @@ onset is described in an accompanying `*.json` file |
|
|
"StartTime": -255.45
|
|
|
}
|
|
|
```
|
|
|
- Note that `StartTime` refers to when the physiological recording started relative to the first scan volume of the fMRI run, which means that typically this value is negative, because one starts the recording before the onset of scan volumes.
|
|
|
- See `tapas_physio_read_physlogfiles_bids.m` for more details and technical
|
|
|
documentation.
|
|
|
|
|
|
- Note that `StartTime` refers to when the physiological recording started relative to the first scan volume of the fMRI run, which means that typically this value is negative, because one starts the recording before the onset of scan volumes.
|
|
|
- See `tapas_physio_read_physlogfiles_bids.m` for more details and technical documentation.
|
|
|
|
|
|
# BioPac
|
|
|
|
|
|
## Mat-file Export (`.mat`)
|
|
|
|
|
|
- assuming the following variables (as columns): `data`, `isi`, `isi_units`, `labels`, `start_sample`, `units`
|
|
|
- See `tapas_physio_read_physlogfiles_biopac_mat.m` for details
|
|
|
|
... | ... | @@ -65,24 +61,24 @@ RESP - RSP100C GSR - EDA100C-MRI PPG - PPG100C Marker |
|
|
If you have logfile data from any other vendor than the ones specified below, you may still use it with PhysIO:
|
|
|
|
|
|
1. Export your traces from cardiac and breathing recording devices into 2 text files and select `log_files.vendor = 'Custom'`. The format is explained in `tapas_physio_new` or the help window of the Batch Editor:
|
|
|
- 'Custom' expects the logfiles (separate files for cardiac and respiratory) to be plain text, with one cardiac (or respiratory) sample per row;
|
|
|
- If heartbeat (R-wave peak) events are recorded as well, they have to be put as a 2nd column in the cardiac logfile by specifying a 1; 0 in all other rows, e.g.
|
|
|
|
|
|
```
|
|
|
- 'Custom' expects the logfiles (separate files for cardiac and respiratory) to be plain text, with one cardiac (or respiratory) sample per row;
|
|
|
- If heartbeat (R-wave peak) events are recorded as well, they have to be put as a 2nd column in the cardiac logfile by specifying a 1; 0 in all other rows, e.g.
|
|
|
|
|
|
```
|
|
|
0.2 0
|
|
|
0.4 1 <- cardiac pulse event
|
|
|
0.2 0
|
|
|
-0.3 0
|
|
|
```
|
|
|
2. You have to specify the sampling intervals for these log files (in seconds), via ` log_files.sampling_interval`, e.g. [0.01 0.02] if you have 10 ms (100 Hz) and 20 ms (50 Hz) sampling intervals (frequencies) for cardiac and respiratory data, respectively
|
|
|
2. You have to specify the sampling intervals for these log files (in seconds), via `log_files.sampling_interval`, e.g. \[0.01 0.02\] if you have 10 ms (100 Hz) and 20 ms (50 Hz) sampling intervals (frequencies) for cardiac and respiratory data, respectively
|
|
|
3. You will probably have to change `log_files.relative_start_acquisition`, if logging of your physiological recording device does not start synchronized to the first fMRI volume.
|
|
|
|
|
|
|
|
|
# General Electric (GE)
|
|
|
|
|
|
- Very similar to custom format
|
|
|
- One text file each for ECG, pulse oximetry and respiratory data, e.g., `ECGData_epiRT_phys_0921201215_38_08` or `RespData_epiRT_phys_0921201215_38_08`
|
|
|
- One amplitude entry per line, e.g.,
|
|
|
|
|
|
```
|
|
|
2626
|
|
|
2649
|
... | ... | @@ -91,14 +87,14 @@ If you have logfile data from any other vendor than the ones specified below, yo |
|
|
2727
|
|
|
2755
|
|
|
```
|
|
|
- sampling rate is determined as a setting beforehand, has to be noted manually (not in log file)
|
|
|
|
|
|
- sampling rate is determined as a setting beforehand, has to be noted manually (not in log file)
|
|
|
|
|
|
# Philips
|
|
|
|
|
|
- Physiology automatically recorded into `SCANPHYSLOG_<Date>_<Time>.log` (one file per scan) as soon as ECG is connected to scanner, and scan is started
|
|
|
- Physiology automatically recorded into `SCANPHYSLOG\_<Date>\_<Time>.log` (one file per scan) as soon as ECG is connected to scanner, and scan is started
|
|
|
- tabular text (ascii) format, different columns for ECG, pulse oximetry and breathing data
|
|
|
- additionally, trigger events and gradient timecourses are logged, and can be used for synchronization by the toolbox
|
|
|
- additionally, trigger events and gradient timecourses are logged, and can be used for synchronization by the toolbox
|
|
|
|
|
|
```
|
|
|
## <YourScannerLocation>, Release r32 (SWID 77)
|
... | ... | @@ -112,8 +108,8 @@ If you have logfile data from any other vendor than the ones specified below, yo |
|
|
-571 219 -592 -104 0 -745 0 0 0 0000
|
|
|
-606 190 -623 -139 0 -745 0 0 0 0000
|
|
|
```
|
|
|
- fixed sampling rate (2 ms for cable connection, 1/496 ms for Wi-Fi devices)
|
|
|
|
|
|
- fixed sampling rate (2 ms for cable connection, 1/496 ms for Wi-Fi devices)
|
|
|
|
|
|
# Siemens
|
|
|
|
... | ... | @@ -121,11 +117,13 @@ If you have logfile data from any other vendor than the ones specified below, yo |
|
|
|
|
|
Physiological data collection on the Siemens scanners uses the physiological monitoring unit (PMU). The initial sampling is performed at 400 Hz, but through the PMU buffer the effective sampling intervals are ECG: 2.5 ms, RESP: 20 ms, PULS: 20 ms and EXT: 5 ms.
|
|
|
|
|
|
There are several ways to control the physiological data collection. The 'manual' version is available on all platforms. It uses the telnet mpcu/ideacmdtool to manually start and stop the log file acquisition. The log files (`logFileName.ecg`, `logFileName.resp`, `logFileName.puls`, `logFileName.ext`) are stored in `\MedCom\log`. More details on how to record these data can be found [here](https://cfn.upenn.edu/aguirre/wiki/public:pulse-oximetry_during_fmri_scanning) or in the "Other Miscellaneous Topics" slides from the IDEA course.
|
|
|
There are several ways to control the physiological data collection. The 'manual' version is available on all platforms. It uses the telnet mpcu/ideacmdtool to manually start and stop the log file acquisition. The log files (`logFileName.ecg`, `logFileName.resp`, `logFileName.puls`, `logFileName.ext`) are stored in `\\MedCom\\log`. More details on how to record these data can be found [here](https://cfn.upenn.edu/aguirre/wiki/public:pulse-oximetry_during_fmri_scanning) or in the "Other Miscellaneous Topics" slides from the IDEA course.
|
|
|
|
|
|
### General Properties
|
|
|
|
|
|
An example of a `.puls` logfile is given below. The data are stored in one long line. The text between 5002 and 6002 forms the header, and the text between 5003 and 6003 the footer. Important information in the footer is the `LogStartMDHTime` and the `LogStopMDHTime` (in ms since midnight), which can be used to synchronize the logfiles with the DICOM images using the `AcquisitionTime` in the DICOM header (in hhmmss.ms). The values 5000 and 6000 are inserted into the signal trace and indicate trigger events. Note that only the modality which is selected to be displayed during the acquisition will have triggers.
|
|
|
|
|
|
We use the time stamp of the clock of the Measurement Data Header (MDH), i.e., computer that controls the scanner, to synchronize with the DICOMs, because this computer also controls the creation of the scan data, i.e., reconstructed DICOM images. This is in accordance to other packages reading Siemens physiological logfile data, e.g., Chris Rorden's [PART](https://github.com/neurolabusc/Part#usage), with a detailed explanation on the DICOM timestamp in `AcquisitionTime` found [here](https://github.com/nipy/heudiconv/issues/450#issuecomment-645003447).
|
|
|
We use the time stamp of the clock of the Measurement Data Header (MDH), i.e., computer that controls the scanner, to synchronize with the DICOMs, because this computer also controls the creation of the scan data, i.e., reconstructed DICOM images. This is in accordance to other packages reading Siemens physiological logfile data, e.g., Chris Rorden's [PART](https://github.com/neurolabusc/Part#usage), with a detailed explanation on the DICOM timestamp in `AcquisitionTime` found [here](https://github.com/nipy/heudiconv/issues/450#issuecomment-645003447).
|
|
|
|
|
|
```
|
|
|
1 2 40 280 5002 Logging PULSE signal: reduction factor = 1, PULS_SAMPLES_PER_SECOND = 50; PULS_SAMPLE_INTERVAL = 20000 6002 1653 1593 1545 1510 1484 ...
|
... | ... | @@ -147,11 +145,34 @@ LogStopMPCUTime: 47652240 |
|
|
6003
|
|
|
```
|
|
|
|
|
|
## CMRR Sequence
|
|
|
### Updates Logversion 3
|
|
|
|
|
|
The above specification for physiological Siemens logfiles has been changed by the new logfile version 3 for both cardiac and respiratory data:
|
|
|
|
|
|
1. There may be multiple info regions between `5002` and `6002` tags, interleaved with the physiological trace, e.g., to log an update in the respiratory cushion gain.
|
|
|
2. The `.ecg` file has now 4 instead of 2 channels.
|
|
|
3. The `.resp` file now contains not only the respiratory bellows signal, but also 4 datapoints per sampling interval of the biomatrix signals (integrated sensors in patient bed for breathing detection, e.g., in Siemens Vida series).
|
|
|
|
|
|
A logfile in version 3 therefore adheres to the following template (note the logfile version indicated by keyword `LOGVERSION` at the start):
|
|
|
|
|
|
```
|
|
|
<Header> 5002 <LOGVERSION XX> 6002
|
|
|
<[optional] training trace data> 5002 uiHwRevisionPeru ... [optional] 6002
|
|
|
5002 <infoRegion3> 6002 5002 <infoRegion4> 6002 ... 5002 <infoRegionN> 6002
|
|
|
<trace data 1 (all channels, arbitrary number of samples, trigger markers 5000, 6000)> ...
|
|
|
5002 <infoRegionN+1> 6002
|
|
|
<trace data 2 (all channels, arbitrary number of samples, trigger markers 5000, 6000)> ...
|
|
|
5002 <infoRegionN+2> 6002 ...
|
|
|
<trace data M> ... 5003
|
|
|
```
|
|
|
|
|
|
PhysIO automatically reads the Siemens logfiles correctly for all modalities and logfile versions 1,2 and 3.
|
|
|
|
|
|
## CMRR Sequence / WIP Advanced Physio Logging
|
|
|
|
|
|
The CMRR sequence on VD/VE also allows the automatic recording of physiological log files (to be selected in the sequence special card). For more information have a look at the [manual](https://www.cmrr.umn.edu/multiband/). The physiological traces are stored in logFileName_PULS.log, logFileName_RESP, logFileName_ECG.log. Timing information is stored in logFileName_Info.log and external trigger events in logFileName_EXT.log.
|
|
|
|
|
|
An example of the current format (December 2017, Release 016a) for the logFileName_Info.log is given below:
|
|
|
An example of the current format (December 2017, Release 016a) for the logFileName_Info.log is given below:
|
|
|
|
|
|
```
|
|
|
UUID = 7a16ea95-ac36-4ee3-9b76-bbb686ac07ca
|
... | ... | @@ -213,7 +234,7 @@ PhysIO uses the logFileName_Info.log to synchronize the physiological traces wit |
|
|
|
|
|
Disclaimer: Most of the information below is a best guess from the developers, but without any guarantee of accuracy.
|
|
|
|
|
|
The physiological log file (`*paradigm*_Physio_log.txt`) distributed with the Human Connectome Project data contains respiratory and puls-oximeter data in one file. The first column marks when data acquisition is performed, the second and third contain the respiratory and puls-oximeter traces, respectively. The files are written at a sampling rate of 400Hz and start and end with the scan. PhysIO does provide a reader, you just need to select the appropriate option in the file format tab. An example is provided below:
|
|
|
The physiological log file (`\*paradigm\*\_Physio_log.txt`) distributed with the Human Connectome Project data contains respiratory and puls-oximeter data in one file. The first column marks when data acquisition is performed, the second and third contain the respiratory and puls-oximeter traces, respectively. The files are written at a sampling rate of 400Hz and start and end with the scan. PhysIO does provide a reader, you just need to select the appropriate option in the file format tab. An example is provided below:
|
|
|
|
|
|
```
|
|
|
1 1904 1756
|
... | ... | |