build_tools.syllable_analysis.dimensionality.mapping
====================================================

.. py:module:: build_tools.syllable_analysis.dimensionality.mapping

.. autoapi-nested-parse::

   Coordinate mapping utilities for dimensionality reduction results.

   This module provides functions for creating and saving mappings between syllables
   and their reduced-dimension coordinates (e.g., from t-SNE, PCA, UMAP).



Functions
---------

.. autoapisummary::

   build_tools.syllable_analysis.dimensionality.mapping.create_tsne_mapping
   build_tools.syllable_analysis.dimensionality.mapping.save_tsne_mapping


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

.. py:function:: create_tsne_mapping(records, tsne_coords)

   Create syllable→features→coordinates mapping.

   Combines annotated syllable records with their t-SNE coordinates to create
   a comprehensive mapping structure. This is useful for:
   - Post-hoc cluster analysis
   - Cross-referencing visualizations
   - Interactive exploration
   - Sharing visualizations with collaborators

   :param records: Original annotated syllable records from load_annotated_syllables().
                   Each record should have:
                   - syllable (str): The syllable text
                   - frequency (int): Occurrence count
                   - features (dict): Boolean feature flags
   :param tsne_coords: t-SNE coordinate array (n_syllables × n_dimensions).
                       Typically 2D for visualization, but can be 3D or higher.

   :returns:

             [
                 {
                     "syllable": "kran",
                     "frequency": 7,
                     "tsne_x": -2.34,
                     "tsne_y": 5.67,
                     "features": {...}
                 },
                 ...
             ]
   :rtype: List of mapping records with structure

   :raises ValueError: If records and tsne_coords have mismatched lengths

   .. admonition:: Example

      >>> records = [
      ...     {"syllable": "ka", "frequency": 187, "features": {...}},
      ...     {"syllable": "ran", "frequency": 42, "features": {...}}
      ... ]
      >>> coords = np.array([[-2.1, 3.4], [1.5, -0.8]])
      >>> mapping = create_tsne_mapping(records, coords)
      >>> mapping[0]["tsne_x"]
      -2.1
      >>> mapping[0]["syllable"]
      'ka'

   .. admonition:: Notes

      - Array indices preserve order from input records
      - Coordinates are converted from numpy float64 to Python float for JSON compatibility
      - All original record fields are preserved in the mapping
      - For 2D t-SNE: creates tsne_x and tsne_y fields
      - For 3D+ t-SNE: creates tsne_x, tsne_y, tsne_z, ... fields


.. py:function:: save_tsne_mapping(mapping, output_path, indent = 2)

   Save t-SNE mapping to JSON file.

   Writes the syllable→coordinates mapping as formatted JSON for human readability
   and programmatic access.

   :param mapping: Mapping data from create_tsne_mapping()
   :param output_path: Output file path (should end in .json)
   :param indent: JSON indentation for readability (default: 2)

   .. admonition:: Example

      >>> from pathlib import Path
      >>> mapping = [{"syllable": "ka", "tsne_x": -2.1, "tsne_y": 3.4, "features": {...}}]
      >>> save_tsne_mapping(mapping, Path("output.json"))

   .. admonition:: Notes

      - Output is formatted with indentation for human readability
      - Uses ensure_ascii=False to preserve Unicode characters
      - UTF-8 encoding ensures international character support
      - Parent directories are created if they don't exist