hedvis 0.1.0

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

hed-vis

</code></pre>
<pre lang="{index}"><code>

</code></pre>
<p><a href="https://hed-vis.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/hed-vis/badge/?version=latest" alt="Documentation Status" /></a> <a href="https://badge.fury.io/py/hedvis"><img src="https://badge.fury.io/py/hedvis.svg" alt="PyPI version" /></a> <a href="https://pypi.org/project/hedvis/"><img src="https://img.shields.io/pypi/pyversions/hedvis.svg" alt="Python" /></a></p>
<p>Visualization tools for {index}<code>HED (Hierarchical Event Descriptors)</code> annotated datasets.</p>
<p><strong>hedvis</strong> provides {index}<code>word cloud</code> generation and {index}<code>visual summaries <visualization></code> for {index}<code>HED-annotated data <dataset; HED-annotated></code>, making it easy to explore and present the semantic content of your experimental datasets.</p>
<h2>Features</h2>
<pre lang="{index}"><code>

• Word Cloud Generation - Create beautiful word clouds from {index}HED tag frequencies <tag frequency>
• Flexible Configuration - Extensive {index}customization <configuration> options for visualizations
• Shaped Clouds - Support for {index}mask images <mask image> to create custom-shaped word clouds
• Multiple Formats - Export to {index}PNG <PNG format> and {index}SVG <SVG format> formats
• hedtools Integration - Seamless integration with the {index}HED Python tools <hedtools> ecosystem
• Two APIs - Modern {index}configuration-based API <VisualizationConfig> and simple {index}legacy API <API; legacy> for quick tasks

Installation

</code></pre>
<pre lang="{index}"><code>

From PyPI (Recommended)

Install the latest stable release:

pip install hedvis

This automatically installs hedtools and all required dependencies.

Development Installation

For development work, clone the repository and install in editable mode:

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

Installing Optional Dependencies

</code></pre>
<pre lang="{index}"><code>

</code></pre>
<p><strong>The project uses <code>pyproject.toml</code> as the single source of truth for all dependencies.</strong> Install optional dependencies using pip extras.</p>
<p><strong>Important:</strong> Installing with extras automatically includes all base dependencies (hedtools, numpy, pandas, etc.) plus the extra tools.</p>
<p><strong>Development tools</strong> (code formatting, linting, testing):</p>
<pre lang="bash"><code># From PyPI (if you installed hedvis from PyPI)
pip install "hedvis[dev]"

# From local source (if you cloned the repository)
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]"

Installing from Source Without Extras

To install from source with only the core 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 should not be used. All dependencies are now managed in pyproject.toml, which is the canonical source. These files will be removed in a future release.

If you need to install dependencies for development or documentation:

• Use pip install ".[dev]" instead of pip install -r requirements-dev.txt
• Use pip install ".[docs]" instead of pip install -r docs/requirements.txt
• Core dependencies are installed automatically with pip install . or pip install hedvis

Quick Start

</code></pre>
<pre lang="{index}"><code>

Simple Word Cloud

from hedvis import create_wordcloud

# Create word cloud from frequency dictionary
word_freq = {
    "Event": 15,
    "Action": 10,
    "Sensory-event": 8,
    "Visual-presentation": 7
}

wc = create_wordcloud(word_freq, width=800, height=600)
wc.to_file("wordcloud.png")

Using the New API

</code></pre>
<pre lang="{index}"><code>

from hedvis import HedTagVisualizer, WordCloudConfig, VisualizationConfig

# Configure visualization
wc_config = WordCloudConfig(
    width=1200,
    height=800,
    background_color="white",
    colormap="viridis"
)

viz_config = VisualizationConfig(
    word_cloud=wc_config,
    output_formats=["png", "svg"]
)

# Create visualizer
visualizer = HedTagVisualizer(viz_config)

# Generate from HED tag counts (from hedtools)
results = visualizer.visualize_from_counts(tag_counts)

Integration with hedtools

</code></pre>
<pre lang="{index}"><code>

</code></pre>
<pre lang="python"><code>from hed import load_schema
from hed.models import TabularInput
from hedvis import HedTagVisualizer

# Load HED schema and data
schema = load_schema()
tabular = TabularInput("events.tsv", sidecar="events.json")

# Create visualizer
visualizer = HedTagVisualizer()

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

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

Documentation

</code></pre>
<p>Full documentation is available at <a href="https://hed-vis.readthedocs.io/">Read the Docs</a>:</p>
<ul>
<li><a href="https://hed-vis.readthedocs.io/en/latest/introduction.html">Introduction</a></li>
<li><a href="https://hed-vis.readthedocs.io/en/latest/user_guide.html">User Guide</a></li>
<li><a href="https://hed-vis.readthedocs.io/en/latest/api/index.html">API Reference</a></li>
</ul>
<h2>Requirements</h2>
<pre lang="{index}"><code>

</code></pre>
<ul>
<li>Python 3.10+</li>
<li>hedtools (>=0.8.1)</li>
<li>wordcloud (>=1.9.4)</li>
<li>matplotlib (>=3.9.0)</li>
<li>Pillow (>=11.2.1)</li>
<li>numpy (>=2.0.2)</li>
<li>pandas (>=2.2.3)</li>
</ul>
<p>All dependencies are managed in <code>pyproject.toml</code> and installed automatically with <code>pip install hedvis</code>.</p>
<p>For the complete list of dependencies with exact versions, see the <code>dependencies</code> section in <a href="pyproject.toml">pyproject.toml</a>.</p>
<h2>Related Projects</h2>
<ul>
<li><strong><a href="https://github.com/hed-standard/hed-python">hedtools</a></strong> - Core HED tools for validation and analysis</li>
<li><strong><a href="https://github.com/hed-standard/hed-schemas">hed-schemas</a></strong> - Official HED schemas</li>
<li><strong><a href="https://github.com/hed-standard/hed-specification">hed-specification</a></strong> - HED specification</li>
<li><strong><a href="https://www.hed-resources.org">HED Resources</a></strong> - User documentation and tutorials</li>
</ul>
<h2>Contributing</h2>
<p>Contributions are welcome! Please see <a href="CONTRIBUTING.md">CONTRIBUTING.md</a> for guidelines.</p>
<h2>Issues</h2>
<p>For bug reports and feature requests, please <a href="https://github.com/hed-standard/hed-vis/issues">open an issue</a> on GitHub.</p>
<p>For general HED questions, visit the <a href="https://github.com/hed-standard/hed-specification/discussions">HED forum</a>.</p>
<h2>License</h2>
<p>This project is licensed under the MIT License - see <a href="LICENSE">LICENSE</a> for details.</p>
<h2>Citation</h2>
<p>If you use hedvis in your research, please cite:</p>
<pre><code>HED Visualization Tools (hedvis)
https://github.com/hed-standard/hed-vis

For HED in general, please cite the HED specification paper.