HED visualization guide

This comprehensive guide shows how to use hedvis to create visualizations from HED-annotated data.

Table of contents

  1. Getting started

  2. Basic word clouds

  3. Configuration-based API

  4. Working with HED data

  5. Advanced customization

  6. Output formats

  7. Best practices

  8. Troubleshooting

Getting started with hedvis

Installation

Install hedvis from PyPI:

pip install hedvis

This automatically installs hedtools and all required dependencies.

Installing with Optional Dependencies

All dependencies are managed in pyproject.toml, which is the single source of truth. Install optional extras as needed.

Important: When you install with extras (e.g., [dev] or [docs]), pip automatically installs all base dependencies (hedtools, numpy, pandas, matplotlib, etc.) plus the specified extra tools. You don’t need a separate installation step for base dependencies.

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 (after cloning)
pip install ".[dev]"          # Regular install

# Editable local source install for active development
pip install -e ".[dev]"       # Editable install

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 (editable installation from source):

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

Installing from Source (Core Dependencies Only)

To install from source without optional dependencies:

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

Legacy Requirements Files

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

Do not use:

  • ~~pip install -r requirements.txt~~ → Use pip install . or pip install hedvis

  • ~~pip install -r requirements-dev.txt~~ → Use pip install ".[dev]"

  • ~~pip install -r docs/requirements.txt~~ → Use pip install ".[docs]"

Basic imports

# New API (recommended)
from hedvis import HedTagVisualizer, VisualizationConfig, WordCloudConfig

# Legacy API (simple word clouds)
from hedvis import create_wordcloud, word_cloud_to_svg

Basic word clouds

Simple word cloud from dictionary

The easiest way to create a word cloud is from a dictionary of word frequencies:

from hedvis import create_wordcloud

# Define word frequencies
word_freq = {
    "Event": 15,
    "Action": 10,
    "Sensory-event": 8,
    "Visual-presentation": 7,
    "Agent-action": 5
}

# Create word cloud
wc = create_wordcloud(word_freq, width=800, height=600)

# Save as image
wc.to_file("my_wordcloud.png")

Converting to SVG

SVG format is useful for publications and web display:

from hedvis import create_wordcloud, word_cloud_to_svg

wc = create_wordcloud(word_freq)
svg_string = word_cloud_to_svg(wc)

# Save SVG to file
with open("wordcloud.svg", "w") as f:
    f.write(svg_string)

Using a mask image

Create shaped word clouds using a mask image:

# Use a PNG image as mask (white areas = text, black = empty)
wc = create_wordcloud(
    word_freq,
    mask_path="brain_mask.png",
    background_color="white"
)
wc.to_file("shaped_wordcloud.png")

Customizing appearance

wc = create_wordcloud(
    word_freq,
    width=1200,
    height=800,
    background_color="white",
    prefer_horizontal=0.9,  # 90% horizontal text
    min_font_size=10,
    max_font_size=100,
    colormap="viridis"
)

Configuration-based API

The new API provides a more structured approach using configuration objects.

Using configuration dictionaries

from hedvis import HedTagVisualizer

# Define configuration as dictionary
config = {
    "word_cloud": {
        "width": 1000,
        "height": 700,
        "background_color": "white",
        "colormap": "plasma"
    },
    "output_formats": ["png", "svg"],
    "save_directory": "./visualizations"
}

# Create visualizer
visualizer = HedTagVisualizer(config)

Using configuration classes

For better type safety and IDE support:

from hedvis import HedTagVisualizer, VisualizationConfig, WordCloudConfig

# Configure word cloud
wc_config = WordCloudConfig(
    width=1200,
    height=800,
    background_color="white",
    colormap="viridis",
    prefer_horizontal=0.8,
    min_font_size=12,
    max_font_size=120
)

# Configure visualizer
viz_config = VisualizationConfig(
    word_cloud=wc_config,
    output_formats=["png", "svg"],
    save_directory="./output",
    save_files=True
)

# Create visualizer
visualizer = HedTagVisualizer(viz_config)

Masked word clouds with configuration

wc_config = WordCloudConfig(
    width=1000,
    height=1000,
    use_mask=True,
    mask_path="brain_outline.png",
    background_color="white",
    contour_width=3,
    contour_color="navy"
)

viz_config = VisualizationConfig(word_cloud=wc_config)
visualizer = HedTagVisualizer(viz_config)

Working with HED data

From pre-computed tag counts

If you’ve already computed tag frequencies using hedtools:

from hed.tools.analysis.hed_tag_counts import HedTagCounts
from hedvis import HedTagVisualizer

# Assume you have tag_counts from hedtools analysis
# tag_counts = HedTagCounts(...)

visualizer = HedTagVisualizer()
results = visualizer.visualize_from_counts(tag_counts)

# Access the word cloud
wc = results['word_cloud']['wordcloud_object']
wc.to_file("hed_tags.png")

From tabular data

Visualize directly from BIDS-style tabular data:

from hed import load_schema
from hed.models import TabularInput
from hedvis import HedTagVisualizer

# Load HED schema
schema = load_schema()

# Load your data
events_file = "sub-01_events.tsv"
sidecar_file = "task-experiment_events.json"
tabular = TabularInput(events_file, sidecar=sidecar_file)

# Create visualizer
visualizer = HedTagVisualizer()

# Generate visualizations
results = visualizer.visualize_from_tabular(
    tabular,
    schema,
    output_basename="experiment_tags",
    include_context=True,
    replace_defs=True
)

# Save outputs
wc = results['word_cloud']['wordcloud_object']
wc.to_file("experiment_wordcloud.png")

From pandas DataFrame

Work directly with pandas DataFrames:

import pandas as pd
from hed import load_schema
from hedvis import HedTagVisualizer

# Load your data
df = pd.read_csv("events.tsv", sep="\t")

# Load schema
schema = load_schema()

# Create visualizer with config
config = {
    "word_cloud": {"width": 1000, "height": 600},
    "output_formats": ["svg"],
    "save_directory": "./output"
}
visualizer = HedTagVisualizer(config)

# Generate visualizations
results = visualizer.visualize_from_dataframe(
    df,
    schema,
    name="my_dataset"
)

Using tag templates

Organize tags by category using templates:

# Define which tags to include by category
tag_template = {
    "sensory": ["Sensory-event", "Visual-presentation", "Auditory-presentation"],
    "actions": ["Agent-action", "Action"],
    "timing": ["Onset", "Offset", "Duration"]
}

results = visualizer.visualize_from_counts(
    tag_counts,
    tag_template=tag_template,
    output_basename="categorized_tags"
)

Advanced customization

Custom color schemes

from hedvis import WordCloudConfig

# Use built-in matplotlib colormaps
config = WordCloudConfig(
    colormap="plasma",      # Options: viridis, plasma, inferno, magma, etc.
    color_range=(0.2, 0.8)  # Use middle 60% of colormap
)

# Or use color names
config = WordCloudConfig(
    background_color="navy",
    contour_color="gold"
)

Font customization

config = WordCloudConfig(
    font_path="/path/to/custom-font.ttf",
    min_font_size=10,
    max_font_size=150,
    prefer_horizontal=0.95  # Nearly all horizontal text
)

Scaling and layout

config = WordCloudConfig(
    relative_scaling=0.8,        # Word size scaling factor
    scale_adjustment=1.5,        # Frequency scaling
    prefer_horizontal=0.75       # 75% horizontal orientation
)

Processing multiple datasets

visualizer = HedTagVisualizer()

datasets = [
    ("baseline", baseline_counts),
    ("task", task_counts),
    ("rest", rest_counts)
]

for name, counts in datasets:
    results = visualizer.visualize_from_counts(
        counts,
        output_basename=f"{name}_tags"
    )
    results['word_cloud']['wordcloud_object'].to_file(f"{name}_cloud.png")

Output formats

PNG output

Raster image format, good for presentations and papers:

wc = create_wordcloud(word_freq)
wc.to_file("output.png")

SVG output

Vector format, scalable and editable:

from hedvis import word_cloud_to_svg

wc = create_wordcloud(word_freq)
svg = word_cloud_to_svg(wc)

with open("output.svg", "w") as f:
    f.write(svg)

Automatic output management

Let the visualizer handle file saving:

config = VisualizationConfig(
    output_formats=["png", "svg"],
    save_directory="./results",
    save_files=True
)

visualizer = HedTagVisualizer(config)
results = visualizer.visualize_from_counts(tag_counts)

# Files automatically saved to ./results/

Best practices

1. Data preparation

  • Use hedtools to compute tag frequencies before visualization

  • Filter out unwanted tag types (e.g., Condition-variable, Task)

  • Consider using tag templates to organize visualizations by category

2. Visual design

  • Choose dimensions appropriate for your output medium:

    • Presentations: 1920x1080 or 1600x900

    • Papers: 1200x800 or 1000x600

    • Web: 800x600 or flexible SVG

  • Use transparent backgrounds for flexibility

  • Select colormaps appropriate for your audience (colorblind-friendly when possible)

3. Mask images

  • Use high-contrast black/white images for masks

  • PNG format recommended for masks

  • Ensure mask resolution matches desired output size

  • Test mask shape before applying to real data

4. Performance

  • For large datasets, compute tag counts once and reuse

  • Save intermediate results (tag counts) for reproducibility

  • Use appropriate image dimensions - larger isn’t always better

5. Reproducibility

  • Save configuration dictionaries alongside outputs

  • Document HED schema versions used

  • Include tag templates in documentation

  • Version control visualization scripts

Troubleshooting

Word cloud appears empty

Problem: Word cloud generates but shows no words.

Solutions:

  • Check that word_freq dictionary is not empty

  • Verify frequencies are positive numbers

  • Ensure dimensions are large enough (minimum 100x100)

  • Check if mask is blocking all text placement

Font not found error

Problem: Custom font path raises an error.

Solutions:

  • Verify font file exists at specified path

  • Ensure font is .ttf, .otf, or .ttc format

  • Try with font_path=None (uses default)

  • Check file permissions

Mask not applied

Problem: Mask image specified but word cloud is rectangular.

Solutions:

  • Verify mask path is correct

  • Check mask is high-contrast (black/white)

  • Ensure mask is PNG or JPEG format

  • Try converting mask to pure black/white

Import errors

Problem: Cannot import hedvis modules.

Solutions:

  • Ensure installation: pip install hedvis

  • For development: install in editable mode pip install -e .

  • Activate virtual environment if using one

  • Check Python version (3.10+ required)

Colors look wrong

Problem: Word cloud colors don’t match expectations.

Solutions:

  • Check colormap name spelling

  • Try standard colormaps: ‘viridis’, ‘plasma’, ‘rainbow’

  • Adjust color_range parameter

  • Set background_color explicitly

Performance issues

Problem: Word cloud generation is slow.

Solutions:

  • Reduce image dimensions

  • Simplify mask if using one

  • Reduce number of words (filter low-frequency tags)

  • Check available RAM

Next steps

  • Explore the API reference for complete function documentation

  • Check out example scripts in the examples/ directory

  • Visit HED resources for more HED tutorials

  • Join discussions in the HED forum