MATLAB HEDTools

HED (Hierarchical Event Descriptors) is a framework for annotating behavioral, physiological, and other events in scientific data using standardized, machine-readable vocabulary organized in hierarchical tag trees. HED is used for human behavioral and neuroimaging experiments.

MATLAB HEDTools provides a convenient interface for MATLAB users to validate HED annotations, search and summarize events, remodel event data, perform factorization and data epoching, and integrate HED with MATLAB-based analysis workflows such as EEGLAB.

Installation

Downloading MATLAB HEDTools

MATLAB HEDTools can be downloaded from the hed-matlab GitHub repository.

Using Git:

git clone https://github.com/hed-standard/hed-matlab.git

Using zip download:

You can also download the latest release as a zip file from the hed-matlab releases tab on GitHub.

Setting up your MATLAB path:

Once you have downloaded (and unzipped if necessary), add the hedmat directory and all of its subdirectories to your MATLAB path:

myPath = 'xxx';  % This should be the full path to hedmat
addpath(genpath(myPath));

The following table describes the directories of this repository:

Directory

Description

data

Data used for the demos and tests.

docs

Source code for the documentation.

hedmat/hedtools

MATLAB interface for the HED tools.

hedmat/remodeling_demos

Demos of calling the table remodeler.

hedmat/utilities

General purpose utilities.

hedmat/web_services_demos

Demos of directly using the HED web services (without hedtools).

tests

Unit tests for MATLAB. (Execute run_tests.m to run all unit tests.)

Using web services (no installation)

The simplest way to use MATLAB HEDTools is through web services. This approach:

  • Requires no installation beyond downloading the MATLAB HEDTools package

  • Requires Internet access to connect to HED web services

  • Works immediately without any Python setup

See the User Guide for examples of using web services.

Using direct Python calls (optional)

For more efficient operation and additional functionality, you can configure MATLAB to call the Python HEDTools directly. This approach:

  • Requires one-time Python setup (Python 3.10+, HEDTools package)

  • Provides better performance than web services

  • Works offline once configured

  • Provides access to additional features not available through web services

  • Some additional functionality not in the MATLAB HEDTools interface is directly accessible through Python

For Python installation instructions, see the Python installation guide in the user guide.

Quick example

Here’s a simple example to get you started with HED validation in MATLAB:

HED validation in MATLAB using web services

% Get HED tools using web services
hed = getHedTools('8.4.0', 'https://hedtools.org/hed');

% Validate a string containing HED tags
issues = hed.validateTags('Sensory-event,Red,(Image,Face)');

if isempty(issues)
    disp('✓ HED string is valid!');
else
    disp(issues);
end

For more examples and detailed usage, see the MATLAB HEDTools user guide.

Getting help

Documentation resources

Support

Funding

Partial support for this project was provided by NIH 1R01MH126700-01A1.