save figures to directory

plots.py

@@ -1,10 +1,36 @@
 """Plotting functions for Voice Branding analysis."""
 
+import re
+from pathlib import Path
+
 import plotly.graph_objects as go
 import polars as pl
 from theme import ColorPalette
 
 
+def _sanitize_filename(title: str) -> str:
+    """Convert plot title to a safe filename."""
+    # Remove HTML tags
+    clean = re.sub(r'<[^>]+>', ' ', title)
+    # Replace special characters with underscores
+    clean = re.sub(r'[^\w\s-]', '', clean)
+    # Replace whitespace with underscores
+    clean = re.sub(r'\s+', '_', clean.strip())
+    # Remove consecutive underscores
+    clean = re.sub(r'_+', '_', clean)
+    # Lowercase and limit length
+    return clean.lower()[:100]
+
+
+def _save_plot(fig: go.Figure, results_dir: str | None, title: str) -> None:
+    """Save plot to PNG file if results_dir is provided."""
+    if results_dir:
+        path = Path(results_dir)
+        path.mkdir(parents=True, exist_ok=True)
+        filename = f"{_sanitize_filename(title)}.png"
+        fig.write_image(path / filename, width=fig.layout.width, height=fig.layout.height)
+
+
 
 def plot_average_scores_with_counts(
     df: pl.DataFrame,
@@ -14,6 +40,7 @@ def plot_average_scores_with_counts(
     color: str = ColorPalette.PRIMARY,
     height: int = 500,
     width: int = 1000,
+    results_dir: str | None = None,
 ) -> go.Figure:
     """
     Create a bar plot showing average scores and count of non-null values for each column.
@@ -91,6 +118,7 @@ def plot_average_scores_with_counts(
         font=dict(size=11)
     )
 
+    _save_plot(fig, results_dir, title)
     return fig
 
 
@@ -101,6 +129,7 @@ def plot_top3_ranking_distribution(
     y_label: str = "Number of Mentions in Top 3",
     height: int = 500,
     width: int = 1000,
+    results_dir: str | None = None,
 ) -> go.Figure:
     """
     Create a stacked bar chart showing how often each voice was ranked 1st, 2nd, or 3rd.
@@ -213,6 +242,7 @@ def plot_top3_ranking_distribution(
         font=dict(size=11)
     )
 
+    _save_plot(fig, results_dir, title)
     return fig
 
 
@@ -223,6 +253,7 @@ def plot_ranking_distribution(
     y_label: str = "Number of Votes",
     height: int = 500,
     width: int = 1000,
+    results_dir: str | None = None,
 ) -> go.Figure:
     """
     Create a stacked bar chart showing the distribution of rankings (1st to 4th) for characters or voices.
@@ -351,6 +382,7 @@ def plot_ranking_distribution(
         font=dict(size=11)
     )
 
+    _save_plot(fig, results_dir, title)
     return fig
 
 
@@ -361,6 +393,7 @@ def plot_most_ranked_1(
     y_label: str = "Count of 1st Place Rankings",
     height: int = 500,
     width: int = 1000,
+    results_dir: str | None = None,
 ) -> go.Figure:
     """
     Create a bar chart showing which item (character/voice) was ranked #1 the most.
@@ -445,6 +478,7 @@ def plot_most_ranked_1(
         font=dict(size=11)
     )
 
+    _save_plot(fig, results_dir, title)
     return fig
 
 
@@ -457,6 +491,7 @@ def plot_weighted_ranking_score(
     color: str = ColorPalette.PRIMARY,
     height: int = 500,
     width: int = 1000,
+    results_dir: str | None = None,
 ) -> go.Figure:
     """
     Create a bar chart showing the weighted ranking score for each character.
@@ -515,6 +550,7 @@ def plot_weighted_ranking_score(
         font=dict(size=11)
     )
 
+    _save_plot(fig, results_dir, title)
     return fig
 
 
@@ -526,6 +562,7 @@ def plot_voice_selection_counts(
     y_label: str = "Number of Times Chosen",
     height: int = 500,
     width: int = 1000,
+    results_dir: str | None = None,
 ) -> go.Figure:
     """
     Create a bar plot showing the frequency of voice selections.
@@ -612,6 +649,7 @@ def plot_voice_selection_counts(
         font=dict(size=11),
     )
 
+    _save_plot(fig, results_dir, title)
     return fig
 
 
@@ -623,6 +661,7 @@ def plot_top3_selection_counts(
     y_label: str = "Count of Mentions in Top 3",
     height: int = 500,
     width: int = 1000,
+    results_dir: str | None = None,
 ) -> go.Figure:
     """
     Question: Which 3 voices are chosen the most out of 18?
@@ -708,6 +747,7 @@ def plot_top3_selection_counts(
         font=dict(size=11),
     )
 
+    _save_plot(fig, results_dir, title)
     return fig
 
 
@@ -719,6 +759,7 @@ def plot_speaking_style_trait_scores(
     title: str = "Speaking Style Trait Analysis",
     height: int = 500,
     width: int = 1000,
+    results_dir: str | None = None,
 ) -> go.Figure:
     """
     Plot scores for a single speaking style trait across multiple voices.
@@ -853,13 +894,15 @@ def plot_speaking_style_trait_scores(
         annotations=annotations,
         font=dict(size=11)
     )
+    _save_plot(fig, results_dir, title)
     return fig
 
 def plot_speaking_style_correlation(
     df: pl.DataFrame,
     style_color: str,
     style_traits: list[str],
-    title=f"Speaking style and voice scale 1-10 correlations"
+    title=f"Speaking style and voice scale 1-10 correlations",
+    results_dir: str | None = None,
 ) -> go.Figure:
     """
     Plots the correlation between Speaking Style Trait Scores (1-5) and Voice Scale (1-10) using a Bar Chart.
@@ -971,6 +1014,7 @@ def plot_speaking_style_correlation(
         showlegend=False
     )
     
+    _save_plot(fig, results_dir, title)
     return fig
 
 
@@ -978,7 +1022,8 @@ def plot_speaking_style_ranking_correlation(
     df: pl.DataFrame,
     style_color: str,
     style_traits: list[str],
-    title: str = None
+    title: str = None,
+    results_dir: str | None = None,
 ) -> go.Figure:
     """
     Plots the correlation between Speaking Style Trait Scores (1-5) and Voice Ranking Points (0-3).
@@ -1073,4 +1118,5 @@ def plot_speaking_style_ranking_correlation(
         showlegend=False
     )
     
+    _save_plot(fig, results_dir, title)
     return fig