build_tools.syllable_walk_tui.modules.analyzer.exporter

Analysis export functionality.

This module provides functions to export corpus shape metrics to text format for sharing and discussion. Exports are human-readable and include all metrics displayed on the AnalysisScreen.

Design Philosophy:

  • Mirror the screen display in text form

  • Include timestamps and corpus paths for provenance

  • Pure formatting functions (no side effects except final write)

  • Percentages shown in parentheses for contextual understanding

Percentage Display:

Exported metrics include percentages where they add meaningful context:

  • Length distribution: Each length count shown as “length:count (pct%)” where pct is the share of total inventory at that length. Example: “2:120 (9.7%), 3:456 (37.0%)”

  • Hapax rate: Syllables appearing exactly once, shown as “count (pct%)” where pct is hapax_count / total_syllables * 100. Example: “Hapax (freq=1): 456 (37.0%)”

  • Top 5 frequency: Each top syllable shown as “syllable: count (pct%)” where pct is count / total_occurrences * 100. Example: “the: 500 (4.1%)”

These percentages help users quickly assess: - Syllable shape preferences (length distribution) - Vocabulary diversity vs. concentration (hapax rate) - Zipfian distribution characteristics (top N coverage)

Export Format:

CORPUS SHAPE METRICS EXPORT Generated: YYYY-MM-DD HH:MM:SS

Corpus: corpus_name

INVENTORY

Total syllables: 1,234 Length dist: 2:120 (9.7%), 3:456 (37.0%), …

FREQUENCY

Hapax (freq=1): 456 (37.0%) Top 5 by frequency:

the: 500 (4.1%) …

[FEATURE SATURATION, TERRAIN sections follow]

[Same format as Patch A]

Functions

format_inventory_metrics(inv)

Format inventory metrics as text.

format_frequency_metrics(freq[, total_syllables])

Format frequency metrics as text.

format_feature_saturation(feat)

Format feature saturation metrics as text.

format_terrain_metrics(terrain)

Format terrain metrics as text with ASCII bars.

format_patch_metrics(patch_name, metrics[, corpus_path])

Format all metrics for a single patch.

format_analysis_export(metrics_a, metrics_b[, ...])

Format complete analysis export for both patches.

export_analysis_to_file(filepath, metrics_a, metrics_b)

Export analysis to a text file.

generate_export_filename()

Generate a timestamped filename for export.

Module Contents

build_tools.syllable_walk_tui.modules.analyzer.exporter.format_inventory_metrics(inv)[source]

Format inventory metrics as text.

Displays raw counts and derived percentages for length distribution. Percentages show each length’s share of total inventory.

Parameters:

inv (build_tools.syllable_walk_tui.services.metrics.InventoryMetrics) – Inventory metrics to format

Returns:

Formatted text block with length distribution percentages

Return type:

str

Example output:
INVENTORY

Total syllables: 1,234 Length min: 2 Length max: 8 Length mean: 3.45 Length median: 3.0 Length std: 1.23 Length dist: 2:120 (9.7%), 3:456 (37.0%), 4:389 (31.5%), …

build_tools.syllable_walk_tui.modules.analyzer.exporter.format_frequency_metrics(freq, total_syllables=None)[source]

Format frequency metrics as text.

Displays raw frequency statistics and derived percentages for: - Hapax rate: percentage of unique syllables appearing exactly once - Top 5 coverage: percentage of total occurrences for most frequent syllables

Parameters:
Returns:

Formatted text block with percentages in parentheses

Return type:

str

Example output:
FREQUENCY

Total occurrences: 12,345 Freq min: 1 Freq max: 500 Freq mean: 10.00 Freq median: 5.0 Freq std: 25.50 Unique freq values: 234 Hapax (freq=1): 456 (37.0%) … Top 5 by frequency:

the: 500 (4.1%) and: 350 (2.8%)

build_tools.syllable_walk_tui.modules.analyzer.exporter.format_feature_saturation(feat)[source]

Format feature saturation metrics as text.

Parameters:

feat (build_tools.syllable_walk_tui.services.metrics.FeatureSaturationMetrics) – Feature saturation metrics to format

Returns:

Formatted text block

Return type:

str

build_tools.syllable_walk_tui.modules.analyzer.exporter.format_terrain_metrics(terrain)[source]

Format terrain metrics as text with ASCII bars.

Hi-fi resolution (30 chars) with center marker and delta display.

Parameters:

terrain (build_tools.syllable_walk_tui.services.metrics.TerrainMetrics) – Terrain metrics to format

Returns:

Formatted text block with visualization

Return type:

str

build_tools.syllable_walk_tui.modules.analyzer.exporter.format_patch_metrics(patch_name, metrics, corpus_path=None)[source]

Format all metrics for a single patch.

Combines inventory, frequency, feature saturation, and terrain metrics into a single formatted text block. Passes total_syllables from inventory to frequency formatter for hapax rate percentage computation.

Parameters:
Returns:

Formatted text block for entire patch with all metrics and percentages

Return type:

str

build_tools.syllable_walk_tui.modules.analyzer.exporter.format_analysis_export(metrics_a, metrics_b, corpus_path_a=None, corpus_path_b=None)[source]

Format complete analysis export for both patches.

Parameters:
Returns:

Complete formatted export text

Return type:

str

build_tools.syllable_walk_tui.modules.analyzer.exporter.export_analysis_to_file(filepath, metrics_a, metrics_b, corpus_path_a=None, corpus_path_b=None)[source]

Export analysis to a text file.

Parameters:
Returns:

Path to the written file

Raises:

OSError – If file cannot be written

Return type:

pathlib.Path

build_tools.syllable_walk_tui.modules.analyzer.exporter.generate_export_filename()[source]

Generate a timestamped filename for export.

Returns:

Filename like “corpus_metrics_20260118_143022.txt”

Return type:

str