Core API

Main visualization interface

Main API for generating HED tag visualizations.

class hedvis.core.tag_visualizer.HedTagVisualizer(config: VisualizationConfig | Dict | None = None)[source]

Bases: object

Generate visualizations from HED tag data.

This class provides an API for creating visualizations from HED-annotated datasets without requiring the remodeling framework. It works directly with hedtools data structures.

__init__(config: VisualizationConfig | Dict | None = None)[source]

Initialize visualizer with configuration.

Parameters:

config – VisualizationConfig object or dictionary of settings. If None, uses default configuration.

visualize_from_counts(tag_counts: HedTagCounts, tag_template: Dict[str, List[str]] | None = None, output_basename: str = 'hed_tags') → Dict[str, Any][source]

Generate visualizations from pre-computed tag counts.

Parameters:

  • tag_counts – HedTagCounts object with tag frequency data.

  • tag_template – Optional dictionary organizing tags by category. Keys are category names, values are lists of tag patterns.

  • output_basename – Base name for output files.

Returns:

Dictionary with generated visualizations (paths and/or objects). Structure: {‘word_cloud’: {‘wordcloud_object’: …, ‘svg_path’: …, ‘png_path’: …}}

visualize_from_tabular(tabular_input: TabularInput, schema: HedSchema, tag_template: Dict[str, List[str]] | None = None, output_basename: str = 'hed_tags', include_context: bool = True, replace_defs: bool = True, remove_types: List[str] | None = None) → Dict[str, Any][source]

Generate visualizations directly from tabular data.

Parameters:

  • tabular_input – TabularInput with HED annotations.

  • schema – HED schema for validation and processing.

  • tag_template – Optional dictionary organizing tags by category.

  • output_basename – Base name for output files.

  • include_context – Include contextual tags in counts.

  • replace_defs – Replace Def tags with their definitions.

  • remove_types – List of type tags to exclude (e.g., [‘Condition-variable’]).

Returns:

Dictionary with generated visualizations.

visualize_from_dataframe(df, schema: HedSchema | str, sidecar=None, name: str = 'dataset', tag_template: Dict[str, List[str]] | None = None, output_basename: str = 'hed_tags', include_context: bool = True, replace_defs: bool = True, remove_types: List[str] | None = None) → Dict[str, Any][source]

Generate visualizations from a pandas DataFrame.

Parameters:

  • df – Pandas DataFrame with event data.

  • schema – HED schema object or version string.

  • sidecar – JSON sidecar dictionary or file path.

  • name – Name for this dataset.

  • tag_template – Optional dictionary organizing tags by category.

  • output_basename – Base name for output files.

  • include_context – Include contextual tags in counts.

  • replace_defs – Replace Def tags with their definitions.

  • remove_types – List of type tags to exclude.

Returns:

Dictionary with generated visualizations.

HedTagVisualizer

class hedvis.core.tag_visualizer.HedTagVisualizer(config: VisualizationConfig | Dict | None = None)[source]

Bases: object

Generate visualizations from HED tag data.

This class provides an API for creating visualizations from HED-annotated datasets without requiring the remodeling framework. It works directly with hedtools data structures.

The main class for generating HED tag visualizations.

Key Methods:

Examples:

Basic usage with tag counts:

from hedvis import HedTagVisualizer

visualizer = HedTagVisualizer()
results = visualizer.visualize_from_counts(tag_counts)
results['word_cloud']['wordcloud_object'].to_file('output.png')

With custom configuration:

from hedvis import HedTagVisualizer, WordCloudConfig, VisualizationConfig

wc_config = WordCloudConfig(width=1200, height=800)
viz_config = VisualizationConfig(word_cloud=wc_config)
visualizer = HedTagVisualizer(viz_config)
__init__(config: VisualizationConfig | Dict | None = None)[source]

Initialize visualizer with configuration.

Parameters:

config – VisualizationConfig object or dictionary of settings. If None, uses default configuration.

visualize_from_counts(tag_counts: HedTagCounts, tag_template: Dict[str, List[str]] | None = None, output_basename: str = 'hed_tags') → Dict[str, Any][source]

Generate visualizations from pre-computed tag counts.

Parameters:

  • tag_counts – HedTagCounts object with tag frequency data.

  • tag_template – Optional dictionary organizing tags by category. Keys are category names, values are lists of tag patterns.

  • output_basename – Base name for output files.

Returns:

Dictionary with generated visualizations (paths and/or objects). Structure: {‘word_cloud’: {‘wordcloud_object’: …, ‘svg_path’: …, ‘png_path’: …}}

visualize_from_tabular(tabular_input: TabularInput, schema: HedSchema, tag_template: Dict[str, List[str]] | None = None, output_basename: str = 'hed_tags', include_context: bool = True, replace_defs: bool = True, remove_types: List[str] | None = None) → Dict[str, Any][source]

Generate visualizations directly from tabular data.

Parameters:

  • tabular_input – TabularInput with HED annotations.

  • schema – HED schema for validation and processing.

  • tag_template – Optional dictionary organizing tags by category.

  • output_basename – Base name for output files.

  • include_context – Include contextual tags in counts.

  • replace_defs – Replace Def tags with their definitions.

  • remove_types – List of type tags to exclude (e.g., [‘Condition-variable’]).

Returns:

Dictionary with generated visualizations.

visualize_from_dataframe(df, schema: HedSchema | str, sidecar=None, name: str = 'dataset', tag_template: Dict[str, List[str]] | None = None, output_basename: str = 'hed_tags', include_context: bool = True, replace_defs: bool = True, remove_types: List[str] | None = None) → Dict[str, Any][source]

Generate visualizations from a pandas DataFrame.

Parameters:

  • df – Pandas DataFrame with event data.

  • schema – HED schema object or version string.

  • sidecar – JSON sidecar dictionary or file path.

  • name – Name for this dataset.

  • tag_template – Optional dictionary organizing tags by category.

  • output_basename – Base name for output files.

  • include_context – Include contextual tags in counts.

  • replace_defs – Replace Def tags with their definitions.

  • remove_types – List of type tags to exclude.

Returns:

Dictionary with generated visualizations.

Sequence map

A map of containing the number of times a particular sequence of values in a column of a columnar file.

class hedvis.core.sequence_map.SequenceMap(codes=None, name='')[source]

Bases: object

A map of unique sequences of column values of a particular length appear in a columnar file.

name

An optional name of this remap for identification purposes.

Type:

str

Notes: This mapping converts all columns in the mapping to strings. The remapping does not support other types of columns.

__init__(codes=None, name='')[source]

Information for setting up the maps.

Parameters:

  • codes (list or None) – If None use all codes, otherwise only include listed codes in the map.

  • name (str) – Name associated with this remap (usually a pathname of the events file).

dot_str(group_spec=None)[source]

Produce a DOT string representing this sequence map.

Parameters:

group_spec (dict or None) – Specification for grouping nodes. If None, defaults to empty dict.

Returns:

DOT format string representation of the sequence map.

Return type:

str

edge_to_str(key)[source]

Convert a graph edge to a DOT string.

Parameters:

key (str) – Hashcode string representing a graph edge.

get_edge_list(sort=True)[source]

Return a DOT format edge list with the option of sorting by edge counts.

Parameters:

sort (bool) – If True (the default), the edge list is sorted by edge counts.

Returns:

list of DOT strings representing the edges labeled by counts.

Return type:

list

filter_edges()[source]
update(data)[source]

Update the existing map with information from data.

Parameters:

  • data (Series) – DataFrame or filename of an events file or event map.

  • allow_missing (bool) – If True allow missing keys and add as n/a columns.

Raises:

HedFileError – If there are missing keys and allow_missing is False.

static prep(data)[source]

Remove quotes from the specified columns and convert to string.

Parameters:

data (Series) – Dataframe to process by removing quotes.

Returns:

Series

Notes

  • Replacement is done in place.