Skip to content

MANUAL_PART_READIN

Jump to bottom
Lars Kasper edited this page Oct 19, 2023 · 28 revisions

Brain Imaging Data Structure (BIDS)

PhysIO supports physiological logfiles prepared according to the BIDS standard

  • 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
                             -0.951233 -0.00915558 0
                             -0.951233 -0.00915558 0
                             -0.953064 -0.0122073  0
                             -0.953064 -0.0122073  0
                             -0.95459  -0.0076297  1
                             -0.95459  -0.0076297  0
  • Example \*.json file:
{
    "SamplingFrequency": 50.0, 
    "Columns": [
        "cardiac", 
        "respiratory", 
        "trigger"
    ], 
    "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.

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

Single Text File Export (.txt)

RESP - RSP100C	GSR - EDA100C-MRI	PPG - PPG100C	Marker
-0.949402	-0.00610382	0.0134277	0
-0.949402	-0.00610382	0.0134277	0
...
-0.951233	-0.00915558	0.0204468	11
-0.951233	-0.00915558	0.0204468	11
-0.953064	-0.0122073	0.0259399	0
...

Custom

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.
    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

  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
 2673
 2699
 2727
 2755
  • 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
  • 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
## <YourScannerLocation>, Release r32 (SWID 77)
## Mon 01-01-2011 12:00:01
## 2628 1214 775 387 -1024 -323 -780 -274 0
## Dockable table = FALSE
# v1raw v2raw  v1 v2  ppu resp  gx gy gz mark
-458 325  -494 2  0 -762  0 0 0 0000
-497 284  -527 -32  0 -745  0 0 0 0000
-533 251  -560 -68  0 -745  0 0 0 0000
-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)

Siemens

Manual Recording (IdeaCmdTool, Siemens VB)

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 or in the "Other Miscellaneous Topics" slides from the IDEA course.

This is the classical method to do physiological recordings on a Siemens scanner. According to the CMRR multi-band sequence manual (see this blogpost), it used to be accurate in terms of timing until Siemens software release VB (hence the name in PhysIO), but has since been superseded by more integrated methods (like CMRR Tics logging or the AdvPhysio Work-in-progress (WIP) by Siemens, which can write the physiological traces as part of the DICOM image header files, see below).

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, with a detailed explanation on the DICOM timestamp in AcquisitionTime found here.

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 ...
ACQ FINISHED
 6002 3093 3096 3064 5000 3016 2926 5003
ECG  Freq Per: 0 0
PULS Freq Per: 66 906
RESP Freq Per: 18 3260
EXT  Freq Per: 0 0
ECG  Min Max Avg StdDiff: 0 0 0 0
PULS Min Max Avg StdDiff: 731 1113 914 1
RESP Min Max Avg StdDiff: 3080 4540 3779 73
EXT  Min Max Avg StdDiff: 0 0 0 0
NrTrig NrMP NrArr AcqWin: 0 0 0 0
LogStartMDHTime:  47029710
LogStopMDHTime:   47654452
LogStartMPCUTime: 47030087
LogStopMPCUTime:  47652240
6003

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 (Siemens_VD, Siemens_Tics)

The CMRR sequence on VD/VE/XA 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. The physiological traces are stored in logFileName_PULS.log, logFileName_RESP, logFileName_ECG.log or in the DICOM image file header (use readCMRRPhysio to extract it into separate files for PhysIO). 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:

UUID        = 7a16ea95-ac36-4ee3-9b76-bbb686ac07ca
ScanDate    = 20171206_150609
LogVersion  = EJA_1
LogDataType = ACQUISITION_INFO
NumSlices   = 48
NumVolumes  = 30
NumEchoes   = 3

VOLUME   SLICE   ACQ_START_TICS  ACQ_FINISH_TICS  ECHO

     0       0         21754755         21754762     0
     0      12         21754755         21754762     0
     0      24         21754755         21754762     0
     0      36         21754755         21754762     0
     0       0         21754763         21754770     1
     0      12         21754763         21754770     1
     0      24         21754763         21754770     1
     0      36         21754763         21754770     1
     0       0         21754771         21754779     2
     0      12         21754771         21754779     2
     0      24         21754771         21754779     2
     0      36         21754771         21754779     2
     0       5         21754787         21754795     0
     0      17         21754787         21754795     0
     0      29         21754787         21754795     0
     0      41         21754787         21754795     0
     0       5         21754795         21754803     1
     0      17         21754795         21754803     1

The accompanying logFileName_PULS.log looks like this:

UUID        = 7a16ea95-ac36-4ee3-9b76-bbb686ac07ca
ScanDate    = 20171206_150609
LogVersion  = EJA_1
LogDataType = PULS
SampleTime  = 2

ACQ_TIME_TICS  CHANNEL  VALUE  SIGNAL

     21747857     PULS   2086 
     21747859     PULS   2076 
     21747861     PULS   2071 
     21747863     PULS   2057 
     21747867     PULS   2038 
     21747869     PULS   2024 
     21747871     PULS   2010 
     21747873     PULS   1991 
     21747875     PULS   1976 
     21747877     PULS   1962

PhysIO uses the logFileName_Info.log to synchronize the physiological traces with the data acquisition. Note that the reference slice does not yet take into account the multiband slice ordering, but just assumes an even distribution. Older version of the CMRR sequence produced slightly different output files, which might work. Please log an issue if you have a very different format that is not supported.

Human Connectome Project

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:

1	1904	1756
1	1904	1756
1	1907	1754
1	1904	1756
1	1907	1756
1	1907	1756
1	1907	1758
1	1907	1760
1	1910	1760
1	1907	1762
1	1907	1762
1	1904	1764
1	1907	1766
1	1904	1766
1	1907	1768
1	1907	1768
1	1904	1768
1	1904	1770
1	1904	1770
1	1904	1772
1	1904	1772
1	1904	1776
1	1904	1776
1	1904	1778
1	1904	1780

Clone this wiki locally