Overview
The cas_visualizer library provides multiple ways to visualize Common Analysis System (CAS) annotations from dkpro-cassis and Udapi. It supports rendering in various formats:
- Spacy-style HTML spans - Interactive span visualizations using spaCy's displaCy
- Dependency trees - Both UDPipe format and spaCy-style HTML
- Tables - CSV/HTML tabular representation of annotations
- Heatmaps - Matplotlib heatmaps showing annotation density
- DOCX - Microsoft Word documents with colored span annotations
Quick start
(see examples for complete implementations)
1. Basic Span Visualization
We require a CAS file or cassis.Cas object containing text:
from cassis import load_cas_from_xmi, load_typesystem
from cas_visualizer import SpacySpanVisualizer
# Load CAS and TypeSystem
cas = load_cas_from_xmi('../data/hagen.txt.xmi', typesystem=load_typesystem('../data/TypeSystem.xml'))
ts = load_typesystem('../data/TypeSystem.xml')
# Create visualizer
vis = SpacySpanVisualizer(ts)
# Configure annotation types
vis.add_type(name='de.tudarmstadt.ukp.dkpro.core.api.ner.type.NamedEntity', color='lightblue')
# Render to HTML
html = vis.visualize(cas)
print(html) # Display in browser or save to file
2. Configuration Examples
Map feature values to labels and colors:
vis.add_feature(
name='de.tudarmstadt.ukp.dkpro.core.api.ner.type.NamedEntity',
feature='value',
value='PERSON',
label='Person',
color='lightblue'
)
vis.add_feature(
name='de.tudarmstadt.ukp.dkpro.core.api.ner.type.NamedEntity',
feature='value',
value='LOCATION',
label='Location',
color='lightgreen'
)
Highlighting mode (instead of underlines):
# Default is underline via SpanRenderer
# Use HIGHLIGHT mode via EntityRenderer
vis = SpacySpanVisualizer(ts)
vis.render_mode = "HIGHLIGHT" # or "UNDERLINE" (default)
html = vis.visualize(cas)
3. Other Visualizers
Dependency trees:
from cas_visualizer import SpacyDependencyVisualizer, UdapiDependencyVisualizer
# spaCy-style HTML
dep_vis = SpacyDependencyVisualizer(ts)
html = dep_vis.visualize(cas)
# UDPipe format (string-based)
udapi_vis = UdapiDependencyVisualizer(ts)
conllu = udapi_vis.visualize(cas)
Tables:
from cas_visualizer import TableVisualizer
table_vis = TableVisualizer(ts)
table_vis.add_type(name='de.tudarmstadt.ukp.dkpro.core.api.ner.type.NamedEntity')
# CSV format
csv_output = table_vis.visualize(cas, output_format='csv')
# HTML format
html_output = table_vis.visualize(cas, output_format='html')
Heatmaps:
from cas_visualizer import HeatmapVisualizer
heatmap_vis = HeatmapVisualizer(ts)
heatmap_vis.add_type(name='de.tudarmstadt.ukp.dkpro.core.api.ner.type.NamedEntity')
# Returns matplotlib Figure object
fig = heatmap_vis.visualize(cas)
fig.show() # or fig.savefig('heatmap.png')
API Reference
Core Classes
All visualizers inherit from the Visualizer base class:
class Visualizer(abc.ABC):
"""Base class for CAS visualizers."""
def __init__(self, ts: str | Path | TypeSystem):
"""Initialize with TypeSystem (file path or TypeSystem object)."""
def add_type(self, name: str, feature: str | None = None,
color: str | None = None, label: str | None = None) -> None:
"""Register a CAS type for visualization."""
def add_feature(self, name: str, feature: str, value: Any,
color: str | None = None, label: str | None = None) -> None:
"""Map specific feature values to labels and colors."""
def visualize(self, cas: Cas, *, start: int = 0, end: int = -1,
output_format: str = "html") -> str:
"""Build and render visualization."""
def list_types(self) -> list[str]:
"""List registered type names."""
def clear_types(self) -> None:
"""Clear all type configurations."""
Available Visualizers
SpacySpanVisualizer- HTML span visualization (underline or highlight)DocxSpanVisualizer- DOCX document with colored spansTableVisualizer- Tabular representation (CSV/HTML)SpacyDependencyVisualizer- spaCy-style dependency tree HTMLUdapiDependencyVisualizer- UDPipe conllu formatHeatmapVisualizer- Matplotlib annotation density heatmap
Architecture
The library is organized into separate modules for each visualizer type:
cas_visualizer/_base.py- Base classes (Visualizer,VisualizerException,TypeConfig)cas_visualizer/span.py- Span visualizerscas_visualizer/dependency.py- Dependency tree visualizerscas_visualizer/table.py- Table visualizercas_visualizer/heatmap.py- Heatmap visualizercas_visualizer/util.py- Utility functionscas_visualizer/__init__.py- Public API exports
All visualizers follow a consistent interface:
build(cas, start, end)- Build internal representationrender(spec, output_format)- Render to output formatvisualize(cas, output_format)- Convenience method combining both
Development
Setup
git clone https://github.com/zesch/cas-visualizer.git
cd cas-visualizer
poetry install
Running Tests
# Run all tests
poetry run pytest
# With coverage
poetry run pytest --cov=cas_visualizer
# Specific test file
poetry run pytest tests/test_span_visualizer.py -v
Code Quality
# Format code
poetry run black cas_visualizer/ tests/
poetry run isort cas_visualizer/ tests/
# Lint
poetry run flake8 cas_visualizer/ tests/
# Type check
poetry run mypy cas_visualizer/
# Or use pre-commit hooks
pre-commit install
pre-commit run --all-files
CI/CD
The project uses GitHub Actions for:
- Testing on Python 3.11, 3.12, 3.13 (Linux, macOS, Windows)
- Linting with Black, isort, flake8
- Type checking with mypy
- Coverage reporting
Workflows run on every push and pull request to main and develop branches.
How to Publish
Only for maintainers:
- Update version in
pyproject.toml - Run
poetry build - Push to GitHub - CI/CD will handle the rest (when release automation is configured)
Or manually:
poetry publish
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cas_visualizer-0.2.0.tar.gz.
File metadata
- Download URL: cas_visualizer-0.2.0.tar.gz
- Upload date:
- Size: 26.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.1.2 CPython/3.13.0 Darwin/25.5.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6334db0f425bc285f77887dccb65480ea9b52edd9a64f6ed4bd9b8b062fb0f17
|
|
| MD5 |
4cff6d1cb426e6f2a454be459893a45e
|
|
| BLAKE2b-256 |
67dafe6b07c108e744c9f6d10c7b913d5bee347f632ce8117dc539278db41e1b
|
File details
Details for the file cas_visualizer-0.2.0-py3-none-any.whl.
File metadata
- Download URL: cas_visualizer-0.2.0-py3-none-any.whl
- Upload date:
- Size: 29.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.1.2 CPython/3.13.0 Darwin/25.5.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
652d01be62f264ce27b5ccaeb5fdbcd6ecc33aa05aa09722cc465cb8da336da2
|
|
| MD5 |
8fc32b76a80b9f849ce15634bd338233
|
|
| BLAKE2b-256 |
be16d56786bec5385709a28a408cceb41421ca5decfc4daedd85733daa7fdd8e
|