build_tools.syllable_analysis.plotting.static
=============================================

.. py:module:: build_tools.syllable_analysis.plotting.static

.. autoapi-nested-parse::

   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
---------

.. autoapisummary::

   build_tools.syllable_analysis.plotting.static.create_tsne_scatter
   build_tools.syllable_analysis.plotting.static.save_static_plot
   build_tools.syllable_analysis.plotting.static.create_metadata_text


Module Contents
---------------

.. py:function:: create_tsne_scatter(tsne_coords, frequencies, title = 't-SNE: Feature Signature Space', figsize = DEFAULT_FIGURE_SIZE, cmap = DEFAULT_COLORMAP, alpha = DEFAULT_ALPHA)

   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.

   :param tsne_coords: 2D coordinate array of shape (n_samples, 2) from t-SNE reduction
   :param frequencies: Frequency values for each point (used for sizing and coloring)
   :param title: Plot title (default: "t-SNE: Feature Signature Space")
   :param figsize: Figure size in inches as (width, height) (default: (14, 10))
   :param cmap: Matplotlib colormap name (default: "viridis")
   :param alpha: 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

   .. admonition:: 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)

   .. admonition:: 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


.. py:function:: save_static_plot(fig, output_path, dpi = DEFAULT_DPI)

   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.

   :param fig: Matplotlib Figure object to save
   :param output_path: Output PNG file path (parent directory must exist)
   :param dpi: Resolution in dots per inch (default: 300 for publication quality)

   :raises FileNotFoundError: If parent directory doesn't exist
   :raises PermissionError: If file cannot be written
   :raises ValueError: If output_path doesn't end with .png

   .. admonition:: 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)

   .. admonition:: 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


.. py:function:: create_metadata_text(output_filename, dpi, perplexity, random_state, processing_time)

   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.

   :param output_filename: Name of the output PNG file (e.g., "20260107_143022.tsne_visualization.png")
   :param dpi: Resolution used for PNG export
   :param perplexity: t-SNE perplexity parameter used
   :param random_state: Random seed used for reproducibility
   :param processing_time: Total processing time in seconds

   :returns: Formatted multi-line metadata string ready for file output

   .. admonition:: 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)

   .. admonition:: Notes

      - Includes timestamp of generation
      - Documents all algorithm parameters
      - Provides interpretation guidance
      - Uses Unicode box-drawing characters for formatting