build_tools.syllable_analysis.plotting.static

Static matplotlib visualizations for analysis tools.

This module provides matplotlib-based static plotting functions for dimensionality reduction visualizations. Functions create publication-quality PNG outputs with comprehensive metadata.

Usage Example

import numpy as np
from pathlib import Path
from build_tools.syllable_analysis.plotting.static import (
    create_tsne_scatter,
    save_static_plot,
    create_metadata_text
)

# Create visualization
tsne_coords = np.array([[...], [...]])  # From t-SNE
frequencies = [10, 25, 15, ...]
fig = create_tsne_scatter(tsne_coords, frequencies)

# Save to PNG
output_path = Path("_working/output.png")
save_static_plot(fig, output_path, dpi=300)

# Generate metadata
metadata = create_metadata_text(
    output_filename="output.png",
    dpi=300,
    perplexity=30,
    random_state=42,
    processing_time=2.5
)
Path("_working/output_meta.txt").write_text(metadata)

Functions

create_tsne_scatter(tsne_coords, frequencies[, title, ...])

Create static matplotlib scatter plot of t-SNE coordinates.

save_static_plot(fig, output_path[, dpi])

Save matplotlib figure to PNG file.

create_metadata_text(output_filename, dpi, perplexity, ...)

Generate formatted metadata text for static visualization.

Module Contents

build_tools.syllable_analysis.plotting.static.create_tsne_scatter(tsne_coords, frequencies, title='t-SNE: Feature Signature Space', figsize=DEFAULT_FIGURE_SIZE, cmap=DEFAULT_COLORMAP, alpha=DEFAULT_ALPHA)[source]

Create static matplotlib scatter plot of t-SNE coordinates.

Generates a publication-quality scatter plot showing t-SNE dimensionality reduction results. Points are sized and colored by frequency, with larger and brighter points indicating higher-frequency syllables.

Parameters:

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

  • frequencies (list[int]) – Frequency values for each point (used for sizing and coloring)

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

  • figsize (tuple[int, int]) – Figure size in inches as (width, height) (default: (14, 10))

  • cmap (str) – Matplotlib colormap name (default: “viridis”)

  • alpha (float) – Point transparency, 0.0=transparent to 1.0=opaque (default: 0.6)

Returns:

matplotlib Figure object with configured scatter plot

Raises:

ValueError – If tsne_coords shape is invalid or lengths don’t match

Return type:

matplotlib.pyplot.Figure

Example

>>> import numpy as np
>>> coords = np.random.randn(100, 2)
>>> freqs = list(range(1, 101))
>>> fig = create_tsne_scatter(coords, freqs)
>>> fig.savefig("output.png", dpi=300)
>>> plt.close(fig)

Notes

  • Point size is proportional to frequency (frequency × 2)

  • Colorbar is added automatically to show frequency scale

  • Black edge lines improve visibility of overlapping points

  • Layout uses tight_layout() for optimal spacing

build_tools.syllable_analysis.plotting.static.save_static_plot(fig, output_path, dpi=DEFAULT_DPI)[source]

Save matplotlib figure to PNG file.

Saves a matplotlib Figure to a high-resolution PNG file suitable for publication or presentation. Uses tight bounding box to minimize whitespace.

Parameters:

  • fig (matplotlib.pyplot.Figure) – Matplotlib Figure object to save

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

  • dpi (int) – Resolution in dots per inch (default: 300 for publication quality)

Raises:

Example

>>> import matplotlib.pyplot as plt
>>> from pathlib import Path
>>> fig, ax = plt.subplots()
>>> ax.plot([1, 2, 3], [1, 4, 9])
>>> save_static_plot(fig, Path("output.png"), dpi=300)
>>> plt.close(fig)

Notes

  • Uses bbox_inches=’tight’ to remove excess whitespace

  • Higher DPI values create larger files but better quality

  • Common DPI values: 150 (screen), 300 (print), 600 (high-quality print)

  • Figure is NOT automatically closed after saving

build_tools.syllable_analysis.plotting.static.create_metadata_text(output_filename, dpi, perplexity, random_state, processing_time)[source]

Generate formatted metadata text for static visualization.

Creates a human-readable metadata report describing the visualization parameters, algorithm settings, and interpretation guide. Suitable for saving alongside PNG output files.

Parameters:

  • output_filename (str) – Name of the output PNG file (e.g., “20260107_143022.tsne_visualization.png”)

  • dpi (int) – Resolution used for PNG export

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

  • random_state (int) – Random seed used for reproducibility

  • processing_time (float) – Total processing time in seconds

Returns:

Formatted multi-line metadata string ready for file output

Return type:

str

Example

>>> metadata = create_metadata_text(
...     output_filename="20260107_143022.tsne_visualization.png",
...     dpi=300,
...     perplexity=30,
...     random_state=42,
...     processing_time=2.5
... )
>>> Path("metadata.txt").write_text(metadata)

Notes

  • Includes timestamp of generation

  • Documents all algorithm parameters

  • Provides interpretation guidance

  • Uses Unicode box-drawing characters for formatting