Skip to main content Link Menu Expand (external link) Document Search Copy Copied

PhysioData File Format

This page contains information about the PhysioData file format and examples of custom PhysioData file generation in MATLAB.

Table of contents
  1. Introduction
    1. PhysioAnalyzers
  2. File Specification and Format
    1. File Contents Outline
  3. MATLAB Examples
    1. Basic Example 1
    2. Other Examples

Introduction

The Toolbox can only read data from PhysioData files, which are standard MATLAB MAT files that correspond to the Toolbox’s data format, and have the .physioData extension. PhysioData files can be generated using the File Converter or a custom MATLAB script.

Using a custom MATLAB script to generate PhysioData file has the following benefits:

  • Any Suitable Raw Data:
    If the raw data format is not supported by the File Converter, it can still be saved as a PhysioData file using a custom MATLAB script and analyzed by the Toolbox.

  • Pre-generated Epoch:
    If the logic needed to generate epochs is not supported by the Toolbox’s epoch resolution engine, or the data required to generate the epochs are saved in separate files, the desired epochs can be pre-generated using a MATLAB script and still analyzed using the Toolbox. Additionally, this method allows the inclusion of custom metadata in the epoch table, which will be copied to the results table.

PhysioAnalyzers

The PhysioData Toolbox is essentially a collection of graphical user interfaces that allow users to visualize and process the data inside PhysioData files. The processing occurs using specific modules called PhysioAnalyzers. Each such module is designed to analyze one specific type of signal; e.g., the ECG Signal Analyzer module analyzes a raw ECG signal, extracts the heart rate and other cardiac metrics, and allows the user to review and correct the generated data.

Analyzing data using the toolbox consists of the user first creating a PhysioAnalyzer module and defining its Settings, then propagating that to one or more imported PhysioData files. The settings determine: the source of the raw data (e.g. the channel); the gain and filtering parameters; the epoch definition; etc. Subsequently, the user can visualize the PhysioAnalyzer data and insert corrections, scored landmarks, etc. These user-added data is referred to as the State of the PhysioAnalyzer module.

The derived signals generated by the PhysioAnalyzer modules (e.g. the filtered ECG signals and the Heart Rate) are not saved to in the PhysioData file, only the necessary information to generate these signals from the raw data is: i.e. its type (aka class name, e.g. ECG_Module), and its Settings and State. The Toolbox internally refers to these data as the PhysioAnalyzer template, and saves it in the base of the PhysioData file inside a struct named physioAnalyzerTemplates. The Toolbox was not designed to allow user-modification of the physioAnalyzerTemplates variable.

Using the Raw Data, the Settings and the State, the Toolbox dynamically generates the PhysioAnalyzer data when it is requested. As such, no derived data is saved to disk other than when generating a Data Archive.

File Specification and Format

PhysioData files are MATLAB MAT v7.3 files with the .physioData extension. The Toolbox only saves data inside the PhysioData file using built-in MATLAB types: structs, cell arrays, tables, etc. PhysioData files can contain physiological signals, eye-tracking data, and timing metadata. These raw data are visualized by the Raw Data Viewer, as described here.

🚧

This page is still under development and does not currently contain information about eye-tracking data inside PhysioData files.

Please note the following:

  • No Strings:
    The PhysioData file does not use Strings, only character arrays (use single quotes, more info). Cell arrays of chars are used to represent arrays of strings.

  • Sampling Frequency:
    All signals must have the same sampling frequency and the same number of samples. The sampling frequency (pdtData.data.signals.fs) must be between 10 and 10000 Hz.

  • User Variables:
    When loading and subsequently saving a PhysioData file, the Toolbox will strip any base variables not part of the official file specification; other non-compliant variables may be deleted as well. To include additional data inside PhysioData files, place them in the UserData variable. This variable will also be included when a Data Archive is generated.

  • Marker Signals:
    If a signal fulfils the definition of a “Marker signal”, the Toolbox will extract markers from it and make those markers available for referencing when generating epochs (more info about markers).

  • Loading and Saving PhysioData Files:
    To load the data from a PhysioData file into MATLAB, call the load function with the -mat flag: pdtData = load(filename, '-mat');. Similarly, to save the data as a PhysioDat file, call save with the -struct flag and the name of the struct that corresponds to the PhysioData file format: save('filename', '-struct', 'pdtData');. Make sure to specify the physioData extension.

  • Updating a PhysioData File:
    The raw data inside a PhysioData file—including the pre-generated epochs—can be modified without losing the PhysioAnalyzer module’s settings and state by calling MATLAB’s save function with the ‘-append’ flag. This will append the desired base variable to the PhysioData file and keep the PhysioAnalyzer modules, which are saved in the physioAnalyzerTemplates variable, intact.

  • File Version Warning:
    When generating PhysioData files in MATLAB and opening them in the Toolbox, a warning may be encountered upon loading the files specifying that they not generated using the current version of the Toolbox. The warning will not be shown again after the file has been saved by the Toolbox.

File Contents Outline

The tree below visualizes the most user-relevant contents of a PhysioData file, as represented in MATLAB by a struct.

Outline 1: The contents of an PhysioData file. The bold strings with frames indicate the field-name if the parent is a struct, and the variable-name otherwise. Click on the triangle to expand or collapse a node.

MATLAB Examples

Any suitable data can be converted into a PhysioData file for use in the Toolbox using custom MATLAB scripts. Download the code and data for the examples below from this GitHub repo by clicking on the Code button and Download ZIP.

Basic Example 1

This example shows how to create a PhysioData file from ECG and EDA (skin conductance) data saved inside a tsv file. It also shows how to add custom referenceable events (labels) and pre-generated epochs.

Code 1: An example showing the basic elements of saving signals and timing metadata inside a PhysioData file. Find this example and its data in the /code_examples/Generating_PhysioData_Files/ folder of the examples repo.


















  
  
     Other Examples
  
  


    

This page is still under construction and will be extended as needed. If you require help generating PhysioData files in MATLAB, please contact the Toolbox developers.


        

        

        

  

  

    

    


© Copyright Leiden University, 2022.