HED visualization overview

hedvis (HED Visualization Tools) is a Python package that provides visualization utilities for HED (Hierarchical Event Descriptors) annotated datasets. It focuses specifically on creating word clouds and visual summaries from HED tag data.

This package is a companion library to hedtools, the core HED Python tools package. While hedtools handles HED schema management, validation, and data processing, hedvis provides specialized visualization capabilities.

Why use hedvis?

HED-annotated datasets contain rich semantic information about events and experimental conditions. hedvis makes it easy to:

  • Visualize tag frequency - Create word clouds showing which HED tags are most commonly used

  • Identify patterns - Quickly spot dominant tags and event types in your data

  • Generate reports - Produce publication-ready visualizations

  • Explore datasets - Get a quick visual overview of what’s in your data

Key hedvis features

Word cloud generation

  • Create customizable word clouds from HED tag frequencies

  • Support for shaped clouds using mask images

  • Flexible color schemes and layouts

  • Export to PNG and SVG formats

Integration with hedtools

  • Works seamlessly with hedtools data structures

  • Process data from BIDS datasets, spreadsheets, or dataframes

  • Automatic tag frequency counting

  • Support for tag templates and filtering

Two APIs for flexibility

  • New API - Modern, configuration-based interface using HedTagVisualizer

  • Legacy API - Simple functional interface for quick word cloud generation

Installing hedvis

Install from PyPI:

pip install hedvis

This automatically installs hedtools and all required dependencies.

Installing with Optional Dependencies

All dependencies are managed in pyproject.toml. Install optional extras as needed.

Important: Installing with extras automatically includes all base dependencies (hedtools, numpy, pandas, matplotlib, etc.) plus the extra tools.

Key distinction:

  • Use "hedvis[extra]" when installing from PyPI (the published package)

  • Use ".[extra]" when installing from local source (after cloning the repository)

# Development tools (formatting, linting, testing)
# From PyPI
pip install "hedvis[dev]"
# From local source
pip install ".[dev]"          # Regular install
pip install -e ".[dev]"       # Editable install (recommended for development)

# Documentation tools (Sphinx, themes)
# From PyPI
pip install "hedvis[docs]"
# From local source
pip install ".[docs]"

# Both dev and docs dependencies
# From PyPI
pip install "hedvis[dev,docs]"
# From local source
pip install ".[dev,docs]"

For development work (clone and install in editable mode):

git clone https://github.com/hed-standard/hed-vis.git
cd hed-vis
pip install -e ".[dev]"

Install directly from the GitHub repository:

pip install git+https://github.com/hed-standard/hed-vis.git

Note: All dependencies are defined in pyproject.toml. Legacy requirements files (requirements.txt, requirements-dev.txt, docs/requirements.txt) are deprecated and will be removed in a future release.

Quick example

from hedvis import HedTagVisualizer

# Create visualizer with default configuration
visualizer = HedTagVisualizer()

# Visualize from pre-computed tag counts (from hedtools)
results = visualizer.visualize_from_counts(tag_counts)

# Save word cloud
results['word_cloud']['wordcloud_object'].to_file('output.png')

Finding help

Documentation

Issues and problems

If you encounter bugs or have feature requests: