hedtools 0.9.0

HED validation, summary, and analysis tools for annotating events and experimental metadata.

HEDTools - Python

Python tools for validation, analysis, and transformation of HED (Hierarchical Event Descriptors) tagged datasets.

Overview

HED (Hierarchical Event Descriptors) is a framework for systematically describing both laboratory and real-world events as well as other experimental metadata. HED tags are comma-separated path strings that provide a standardized vocabulary for annotating events and experimental conditions.

Key Features:

• Validate HED annotations against schema specifications
• Analyze and summarize HED-tagged datasets
• Transform and remodel event data
• Full HED support in BIDS (Brain Imaging Data Structure)
• HED support in NWB (Neurodata Without Borders) when used the ndx-hed extension.
• Platform-independent and data-neutral
• Command-line tools and Python API

Quick start

Online tools (no installation required)

For simple validation or transformation tasks, use the online tools at https://hedtools.org/hed - no installation needed!

Browser-based validation (no data upload) is available at https://www.hedtags.org/hed-javascript

A development version of the online tools is available at: https://hedtools.org/hed_dev

Python installation

Requirements: Python 3.10 or higher

Install from PyPI:

pip install hedtools

Or install from GitHub (latest):

pip install git+https://github.com/hed-standard/hed-python/@main

Basic usage

from hed import HedString, load_schema_version


# Load the latest HED schema
schema = load_schema_version("8.4.0")

# Create and validate a HED string
hed_string = HedString("Sensory-event, Visual-presentation, (Onset, (Red, Square))", schema)
issues = hed_string.validate()

if issues:
    print(get_printable_issue_string(issues, title="Validation issues found"))
else:
    print("HED string is valid!")

Command-line tools

HEDTools provides a unified command-line interface with git-like subcommands:

# Main command (new unified interface)
hedpy --help

# Validate a BIDS dataset
hedpy validate-bids /path/to/bids/dataset

# Extract sidecar template from BIDS dataset
hedpy extract-sidecar /path/to/dataset --suffix events

# Validate HED schemas
hedpy schema validate /path/to/schema.xml

# Convert schema between formats (XML, MEDIAWIKI, TSV, JSON)
hedpy schema convert /path/to/schema.xml

Legacy commands (deprecated, use hedpy instead):

validate_bids /path/to/dataset
hed_validate_schemas /path/to/schema.xml
run_remodel /path/to/data /path/to/config.json

For more examples, see the user guide.

Jupyter notebook examples

Note: Example notebooks are available in the GitHub repository only, not in the PyPI package.

The examples/ directory contains Jupyter notebooks demonstrating common HED workflows with BIDS datasets:

• validate_bids_dataset.ipynb - Validate HED annotations in a BIDS dataset
• summarize_events.ipynb - Summarize event file contents and value counts
• sidecar_to_spreadsheet.ipynb - Convert JSON sidecars to spreadsheet format
• merge_spreadsheet_into_sidecar.ipynb - Merge spreadsheet annotations into JSON sidecars
• extract_json_template.ipynb - Generate JSON sidecar templates from event files
• find_event_combinations.ipynb - Find unique combinations of event values
• validate_bids_dataset_with_libraries.ipynb - Validate with HED library schemas

To use these notebooks:

# Clone the repository to get the examples
git clone https://github.com/hed-standard/hed-python.git
cd hed-python

# Install HEDTools with Jupyter support
pip install -e .[examples]

# Launch Jupyter
jupyter notebook examples/

See examples/README.md for more details.

Documentation

📖 Full Documentation: https://www.hedtags.org/hed-python

• User guide - Usage instructions
• API reference - Detailed API documentation
• HED specification - Full HED standard specification

Building docs locally

# Install documentation dependencies
pip install -e .[docs]

# Build the documentation
cd docs
sphinx-build -b html . _build/html

# Or use the make command (if available)
make html

# View the built documentation
# Open docs/_build/html/index.html in your browser

Formatting with Black

This project uses Black for consistent code formatting.

# Check if code is properly formatted (without making changes)
black --check .

# Check and show what would change
black --check --diff .

# Format all Python code in the repository
black .

# Format specific files or directories
black hed/
black tests/

Windows Users: If you encounter "I/O operation on closed file" errors, use the --workers 1 flag:

black --workers 1 --check .
black --workers 1 .

Configuration: Black settings are in pyproject.toml with a line length of 127 characters (matching our ruff configuration).

Exclusions: Black automatically excludes .venv/, __pycache__/, auto-generated files (hed/_version.py), and external repos (spec_tests/hed-examples/, spec_tests/hed-specification/).

CI integration: All code is automatically checked for Black formatting in GitHub Actions. Run black . before committing to ensure your code passes CI checks.

Related repositories

The HED ecosystem consists of several interconnected repositories:

Repository	Description
hed-python	Python validation and analysis tools (this repo)
hed-web	Web interface and deployable Docker services
hed-resources	Tutorials and other HED resources
hed-specification	Official HED specification documents
hed-schemas	Official HED schema repository
ndx-hed	HED support for NWB
hed-javascript	JavaScript HED validation tools

Contributing

We welcome contributions! Here's how you can help:

1. Report issues: Use GitHub Issues for bug reports and feature requests
2. Submit pull requests (PRs): PRs should be from a non-main fork and target the main branch
3. Improve documentation: Help us make HED easier to use
4. Share examples: Contribute example code and use cases

Development setup:

# Clone the repository
git clone https://github.com/hed-standard/hed-python.git
cd hed-python

# Install in development mode with all dependencies (including Jupyter)
pip install -e .[examples]
pip install -r requirements-dev.txt

# Or just core development dependencies
pip install -e .
pip install -r requirements.txt

# Run tests
python -m unittest discover tests

# Run specific test file
python -m unittest tests/path/to/test_file.py

# Test notebooks (requires Jupyter dependencies)
python -m unittest tests.test_notebooks

For detailed contribution guidelines, please see CONTRIBUTING.md.

Configuration

Schema caching

By default, HED schemas are cached in ~/.hedtools/ (location varies by OS).

# Change the cache directory
import hed
hed.schema.set_cache_directory('/custom/path/to/cache')

Starting with hedtools 0.2.0, local copies of recent schema versions are bundled within the package for offline access.

Citation

If you use HEDTools in your research, please cite:

@software{hedtools,
  author = {Ian Callanan, Robbins, Kay and others},
  title = {HEDTools: Python tools for HED},
  year = {2024},
  publisher = {GitHub},
  url = {https://github.com/hed-standard/hed-python},
  doi = {10.5281/zenodo.8056010}
}

License

HEDTools is licensed under the MIT License. See LICENSE for details.

Support

• Documentation
• GitHub issues
• HED Homepage
• Contact: [e-mail]