build_tools.syllable_analysis.plotting.interactive

Interactive Plotly visualizations for analysis tools.

This module provides Plotly-based interactive plotting functions for dimensionality reduction visualizations. Functions create standalone HTML files with zoom, pan, hover, and export capabilities.

Plotly is an optional dependency. If not installed, functions will raise ImportError with installation instructions.

Usage Example

import numpy as np
from pathlib import Path
from build_tools.syllable_analysis.plotting.interactive import (
    create_interactive_scatter,
    save_interactive_html,
    PLOTLY_AVAILABLE
)

if not PLOTLY_AVAILABLE:
    print("Plotly not installed - skipping interactive visualization")
else:
    # Create visualization
    records = [
        {"syllable": "ka", "frequency": 100, "features": {...}},
        ...
    ]
    tsne_coords = np.array([[...], [...]])
    fig = create_interactive_scatter(records, tsne_coords)

    # Save to HTML
    output_path = Path("_working/output.html")
    save_interactive_html(fig, output_path, perplexity=30, random_state=42)

Attributes

PLOTLY_AVAILABLE

Functions

create_interactive_scatter(records, tsne_coords[, title])	Create interactive Plotly scatter plot of t-SNE coordinates.
build_hover_text(record[, max_features])	Build rich hover text for a single syllable record.
save_interactive_html(fig, output_path, perplexity, ...)	Save interactive Plotly figure as standalone HTML.
inject_responsive_css(html_content[, min_width])	Inject responsive CSS into HTML content.
create_metadata_footer(perplexity, random_state)	Create HTML metadata footer with algorithm parameters.

Module Contents

build_tools.syllable_analysis.plotting.interactive.PLOTLY_AVAILABLE = True

build_tools.syllable_analysis.plotting.interactive.create_interactive_scatter(records, tsne_coords, title='t-SNE: Feature Signature Space (Interactive)')

Create interactive Plotly scatter plot of t-SNE coordinates.

Generates an interactive HTML-compatible visualization with rich hover tooltips, zoom/pan controls, and export capabilities. Points are sized (log scale) and colored by frequency.

Parameters:

• records (List[Dict]) – List of annotated syllable records. Each must contain: - syllable (str): Syllable text - frequency (int): Occurrence count - features (dict): Boolean feature flags (12 features)

• tsne_coords (numpy.ndarray) – 2D coordinate array of shape (n_samples, 2) from t-SNE

• title (str) – Plot title (default: “t-SNE: Feature Signature Space (Interactive)”)

Returns:

Plotly Figure object with configured interactive scatter plot

Raises:

• ImportError – If Plotly is not installed

• ValueError – If inputs are invalid or lengths don’t match

Return type:

plotly.graph_objects.Figure

Example

>>> records = [
...     {"syllable": "ka", "frequency": 100, "features": {"contains_plosive": True}},
...     {"syllable": "mi", "frequency": 50, "features": {"contains_nasal": True}},
... ]
>>> coords = np.array([[1.0, 2.0], [3.0, 4.0]])
>>> fig = create_interactive_scatter(records, coords)
>>> fig.show()  # Opens in browser

Notes

• Point size uses log1p scale for better visibility across frequency ranges

• Hover text shows syllable, frequency, feature count, and up to 4 features

• If more than 4 features, shows “…+N more” truncation

• Viridis colorscale provides perceptually uniform coloring

• Fixed height (900px) with responsive width for consistent aspect ratio

• Plotly CDN used when saving to HTML for smaller file size

build_tools.syllable_analysis.plotting.interactive.build_hover_text(record, max_features=4)

Build rich hover text for a single syllable record.

Creates HTML-formatted hover text showing syllable details, frequency, and active features. Features are truncated if more than max_features are present.

Parameters:

• record (Dict) – Syllable record with ‘syllable’, ‘frequency’, ‘features’ keys

• max_features (int) – Maximum features to show before truncating (default: 4)

Returns:

HTML-formatted hover text string

Return type:

str

Example

>>> record = {
...     "syllable": "kran",
...     "frequency": 150,
...     "features": {
...         "contains_plosive": True,
...         "contains_liquid": True,
...         "contains_nasal": True,
...         "starts_with_cluster": True,
...         "ends_with_nasal": True,
...     }
... }
>>> text = build_hover_text(record, max_features=4)
>>> print(text)
<b>kran</b><br>Frequency: 150<br>Features: 5/12<br><i>contains_plosive, ...</i><br>...

Notes

• Syllable shown in bold

• Frequency shown with comma separators (e.g., “1,234”)

• Feature count shows active/total (e.g., “5/12”)

• First N features shown in italics

• If more than N features, shows “+M more” truncation message

build_tools.syllable_analysis.plotting.interactive.save_interactive_html(fig, output_path, perplexity, random_state, min_width=DEFAULT_PLOT_MIN_WIDTH)

Save interactive Plotly figure as standalone HTML.

Creates a self-contained HTML file with embedded Plotly visualization that can be: - Opened directly in any web browser - Shared with collaborators - Embedded in reports or documentation - Explored with zoom, pan, hover, and export controls

The HTML file uses Plotly CDN for JavaScript dependencies (smaller file size) and includes responsive CSS and a metadata footer.

Parameters:

• fig (plotly.graph_objects.Figure) – Plotly Figure object from create_interactive_scatter()

• output_path (pathlib.Path) – Output HTML file path (parent directory must exist)

• perplexity (int) – t-SNE perplexity parameter (for metadata footer)

• random_state (int) – Random seed used (for metadata footer)

• min_width (int) – Minimum width constraint in pixels (default: 1250)

Raises:

• ImportError – If Plotly is not installed

• FileNotFoundError – If parent directory doesn’t exist

• ValueError – If output_path doesn’t end with .html

Example

>>> fig = create_interactive_scatter(records, tsne_coords)
>>> output_path = Path("_working/visualization.html")
>>> save_interactive_html(fig, output_path, perplexity=30, random_state=42)

Notes

• Plotly CDN used for smaller file size vs. full JS bundle

• Mode bar configured with additional tools (hoverclosest, hovercompare)

• Export to PNG button configured for high-resolution (1600x1200, 2x scale)

• Responsive CSS ensures minimum width of 1250px

• Metadata footer includes algorithm parameters and generation time

build_tools.syllable_analysis.plotting.interactive.inject_responsive_css(html_content, min_width=DEFAULT_PLOT_MIN_WIDTH)

Inject responsive CSS into HTML content.

Adds CSS rules to ensure the plot has a minimum width and proper scrolling behavior. This prevents the plot from becoming too narrow on small screens while allowing horizontal scrolling when necessary.

Parameters:

• html_content (str) – Original HTML content from Plotly

• min_width (int) – Minimum width constraint in pixels (default: 1250)

Returns:

HTML content with injected CSS in <head> section

Return type:

str

Example

>>> html = "<html><head></head><body>...</body></html>"
>>> modified = inject_responsive_css(html, min_width=1250)
>>> "<style>" in modified
True

Notes

• CSS is inserted after the opening <head> tag

• Sets body margin/padding to 0 for full-width layout

• Enables horizontal scrolling when plot exceeds viewport width

• Sets fixed height (900px) matching plot configuration

• Uses !important to override Plotly’s inline styles

build_tools.syllable_analysis.plotting.interactive.create_metadata_footer(perplexity, random_state)

Create HTML metadata footer with algorithm parameters.

Generates a styled HTML block showing t-SNE parameters and generation information. Designed to be appended to the end of the HTML file.

Parameters:

• perplexity (int) – t-SNE perplexity parameter used

• random_state (int) – Random seed used for reproducibility

Returns:

HTML string with formatted metadata table

Return type:

str

Example

>>> footer = create_metadata_footer(perplexity=30, random_state=42)
>>> "t-SNE Visualization Parameters" in footer
True

Notes

• Uses inline CSS for styling (no external dependencies)

• Light gray background (#f5f5f5) for visual separation

• Monospace font for technical parameters

• Includes usage instructions for toolbar

• Shows current timestamp of generation