scitex 2.0.0__py2.py3-none-any.whl → 2.1.0__py2.py3-none-any.whl

scitex/ai/plt/_plot_feature_importance.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-10-03 04:10:00 (ywatanabe)"
+# File: /ssh:sp:/home/ywatanabe/proj/scitex_repo/src/scitex/ml/plt/plot_feature_importance.py
+
+"""
+Plot feature importance from trained models.
+
+This module provides visualization functions for feature importance,
+supporting both single-fold and cross-validation summary plots.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Union
+import numpy as np
+import matplotlib.pyplot as plt
+import scitex as stx
+
+
+def plot_feature_importance(
+    importance: Union[np.ndarray, Dict[str, float]],
+    feature_names: Optional[List[str]] = None,
+    top_n: int = 20,
+    title: str = "Feature Importance",
+    xlabel: str = "Importance",
+    figsize: tuple = (10, 8),
+    spath: Optional[Union[str, Path]] = None,
+) -> plt.Figure:
+    """
+    Plot feature importance as a horizontal bar chart.
+
+    Parameters
+    ----------
+    importance : np.ndarray or Dict[str, float]
+        Feature importance values. If array, must match feature_names length.
+        If dict, keys are feature names and values are importances.
+    feature_names : List[str], optional
+        Names of features (required if importance is array)
+    top_n : int, default 20
+        Number of top features to display
+    title : str, default "Feature Importance"
+        Plot title
+    xlabel : str, default "Importance"
+        X-axis label
+    figsize : tuple, default (10, 8)
+        Figure size
+    spath : Union[str, Path], optional
+        Path to save the figure
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+        The figure object
+
+    Examples
+    --------
+    >>> from sklearn.ensemble import RandomForestClassifier
+    >>> import numpy as np
+    >>> X = np.random.rand(100, 5)
+    >>> y = np.random.randint(0, 2, 100)
+    >>> model = RandomForestClassifier().fit(X, y)
+    >>> fig = plot_feature_importance(
+    ...     model.feature_importances_,
+    ...     feature_names=['f1', 'f2', 'f3', 'f4', 'f5'],
+    ...     spath='feature_importance.jpg'
+    ... )
+    """
+    # Convert dict to arrays if needed
+    if isinstance(importance, dict):
+        feature_names = list(importance.keys())
+        importance = np.array(list(importance.values()))
+
+    # Validate inputs
+    if feature_names is None:
+        raise ValueError("feature_names must be provided when importance is an array")
+
+    if len(feature_names) != len(importance):
+        raise ValueError(
+            f"Length mismatch: {len(feature_names)} feature names "
+            f"but {len(importance)} importance values"
+        )
+
+    # Sort by importance
+    indices = np.argsort(importance)[::-1][:top_n]
+    sorted_importance = importance[indices]
+    sorted_names = [feature_names[i] for i in indices]
+
+    # Create figure
+    fig, ax = plt.subplots(figsize=figsize)
+
+    # Create horizontal bar plot
+    y_pos = np.arange(len(sorted_names))
+    ax.barh(
+        y_pos,
+        sorted_importance,
+        align="center",
+        alpha=0.8,
+        color="steelblue",
+        edgecolor="black",
+    )
+
+    # Format feature names (replace underscores, title case)
+    formatted_names = [
+        name.replace("_", " ").title() for name in sorted_names
+    ]
+
+    ax.set_yticks(y_pos)
+    ax.set_yticklabels(formatted_names, fontsize=9)
+    ax.invert_yaxis()  # Top feature at top
+    ax.set_xlabel(xlabel, fontsize=11, fontweight="bold")
+    ax.set_title(title, fontsize=13, fontweight="bold")
+    ax.grid(True, alpha=0.3, axis="x")
+
+    plt.tight_layout()
+
+    # Save if path provided
+    if spath:
+        spath_abs = Path(spath).resolve() if isinstance(spath, (str, Path)) else spath
+        stx.io.save(fig, str(spath_abs), use_caller_path=False)
+
+    return fig
+
+
+def plot_feature_importance_cv_summary(
+    all_importances: List[Dict[str, float]],
+    top_n: int = 20,
+    title: Optional[str] = None,
+    figsize: tuple = (12, 8),
+    spath: Optional[Union[str, Path]] = None,
+) -> plt.Figure:
+    """
+    Plot feature importance summary across cross-validation folds with error bars.
+
+    Parameters
+    ----------
+    all_importances : List[Dict[str, float]]
+        List of importance dictionaries from each fold
+    top_n : int, default 20
+        Number of top features to display
+    title : str, optional
+        Plot title (auto-generated if None)
+    figsize : tuple, default (12, 8)
+        Figure size
+    spath : Union[str, Path], optional
+        Path to save the figure
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+        The figure object
+
+    Examples
+    --------
+    >>> # After cross-validation
+    >>> all_importances = [
+    ...     {'feature1': 0.3, 'feature2': 0.7},
+    ...     {'feature1': 0.4, 'feature2': 0.6},
+    ... ]
+    >>> fig = plot_feature_importance_cv_summary(
+    ...     all_importances,
+    ...     spath='feature_importance_cv_summary.jpg'
+    ... )
+    """
+    if not all_importances:
+        raise ValueError("all_importances cannot be empty")
+
+    # Aggregate importances across folds
+    all_features = set()
+    for imp_dict in all_importances:
+        all_features.update(imp_dict.keys())
+
+    # Calculate mean and std for each feature
+    feature_stats = {}
+    for feature in all_features:
+        values = [imp_dict.get(feature, 0) for imp_dict in all_importances]
+        feature_stats[feature] = {
+            "mean": float(np.mean(values)),
+            "std": float(np.std(values)),
+        }
+
+    # Sort by mean importance and take top_n
+    sorted_features = sorted(
+        feature_stats.items(), key=lambda x: x[1]["mean"], reverse=True
+    )[:top_n]
+
+    # Extract data for plotting
+    names = [item[0] for item in sorted_features]
+    means = [item[1]["mean"] for item in sorted_features]
+    stds = [item[1]["std"] for item in sorted_features]
+
+    # Create figure
+    fig, ax = plt.subplots(figsize=figsize)
+
+    # Create horizontal bar plot with error bars
+    y_pos = np.arange(len(names))
+    ax.barh(
+        y_pos,
+        means,
+        xerr=stds,
+        align="center",
+        alpha=0.8,
+        color="steelblue",
+        edgecolor="black",
+        capsize=5,
+        error_kw={"linewidth": 2},
+    )
+
+    # Format feature names
+    formatted_names = [name.replace("_", " ").title() for name in names]
+
+    ax.set_yticks(y_pos)
+    ax.set_yticklabels(formatted_names, fontsize=9)
+    ax.invert_yaxis()
+    ax.set_xlabel("Mean Importance ± Std", fontsize=11, fontweight="bold")
+
+    # Auto-generate title if not provided
+    if title is None:
+        n_folds = len(all_importances)
+        title = f"Feature Importance (CV Summary, n={n_folds} folds)"
+
+    ax.set_title(title, fontsize=13, fontweight="bold")
+    ax.grid(True, alpha=0.3, axis="x")
+
+    plt.tight_layout()
+
+    # Save if path provided
+    if spath:
+        spath_abs = Path(spath).resolve() if isinstance(spath, (str, Path)) else spath
+        stx.io.save(fig, str(spath_abs), use_caller_path=False)
+
+    return fig
+
+
+def main(args):
+    """Demo feature importance plotting."""
+    from sklearn.ensemble import RandomForestClassifier
+    from sklearn import datasets
+
+    # Load iris dataset
+    iris = datasets.load_iris()
+    X = iris.data
+    y = iris.target
+    feature_names = iris.feature_names
+
+    # Train model
+    model = RandomForestClassifier(n_estimators=100, random_state=42)
+    model.fit(X, y)
+
+    # Plot single fold
+    fig = plot_feature_importance(
+        model.feature_importances_,
+        feature_names=feature_names,
+        title="Feature Importance (Iris Dataset)",
+        spath="plot_feature_importance_demo_single.jpg",
+    )
+
+    # Simulate CV results
+    all_importances = []
+    for i in range(5):
+        model_fold = RandomForestClassifier(n_estimators=100, random_state=i)
+        model_fold.fit(X, y)
+        importance_dict = {
+            name: float(imp)
+            for name, imp in zip(feature_names, model_fold.feature_importances_)
+        }
+        all_importances.append(importance_dict)
+
+    # Plot CV summary
+    fig = plot_feature_importance_cv_summary(
+        all_importances,
+        spath="plot_feature_importance_demo_cv.jpg",
+    )
+
+    print("Generated feature importance plots:")
+    print("  - plot_feature_importance_demo_single.jpg")
+    print("  - plot_feature_importance_demo_cv.jpg")
+
+    return 0
+
+
+def parse_args():
+    """Parse command line arguments."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Demo feature importance plotting")
+    return parser.parse_args()
+
+
+def run_main():
+    """Initialize scitex framework, run main function, and cleanup."""
+    global CONFIG, CC, sys, plt, rng
+
+    import sys
+    import matplotlib.pyplot as plt
+    import scitex as stx
+
+    args = parse_args()
+
+    CONFIG, sys.stdout, sys.stderr, plt, CC, rng = stx.session.start(
+        sys,
+        plt,
+        args=args,
+        file=__file__,
+        sdir_suffix=None,
+        verbose=False,
+        agg=True,
+    )
+
+    exit_status = main(args)
+
+    stx.session.close(
+        CONFIG,
+        verbose=False,
+        notify=False,
+        message="",
+        exit_status=exit_status,
+    )
+
+
+if __name__ == "__main__":
+    run_main()
+
+# EOF

scitex/ai/plt/_plot_learning_curve.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "2025-10-02 19:50:54 (ywatanabe)"
+# File: /ssh:sp:/home/ywatanabe/proj/scitex_repo/src/scitex/ml/plt/plot_learning_curve.py
+# ----------------------------------------
+from __future__ import annotations
+import os
+__FILE__ = __file__
+__DIR__ = os.path.dirname(__FILE__)
+# ----------------------------------------
+# Time-stamp: "2024-03-12 19:52:48 (ywatanabe)"
+
+import argparse
+import re
+
+import numpy as np
+import pandas as pd
+import scitex
+from scitex.plt.color import str2hex
+
+
+def _prepare_metrics_df(metrics_df):
+    """Prepare metrics DataFrame with i_global as index."""
+    if metrics_df.index.name != "i_global":
+        try:
+            metrics_df = metrics_df.set_index("i_global")
+        except KeyError:
+            print(
+                "Error: The DataFrame does not contain a column named 'i_global'. "
+                "Please check the column names."
+            )
+        except Exception as e:
+            print(f"An unexpected error occurred: {e}")
+    metrics_df["i_global"] = metrics_df.index  # alias
+    return metrics_df
+
+
+def _configure_accuracy_axis(ax, metric_key):
+    """Configure y-axis for accuracy metrics."""
+    if re.search("[aA][cC][cC]", metric_key):
+        ax.set_ylim(0, 1)
+        ax.set_yticks([0, 0.5, 1.0])
+    return ax
+
+
+def _plot_training_data(ax, metrics_df, metric_key, linewidth=1, color=None):
+    """Plot training phase data as line."""
+    if color is None:
+        color = str2hex("blue")
+
+    is_training = scitex.str.search(
+        "^[Tt]rain(ing)?", metrics_df.step, as_bool=True
+    )[0]
+    training_df = metrics_df[is_training]
+
+    if len(training_df) > 0:
+        ax.plot(
+            training_df.index,
+            training_df[metric_key],
+            label="Training",
+            color=color,
+            linewidth=linewidth,
+        )
+        ax.legend()
+
+    return ax
+
+
+def _plot_validation_data(ax, metrics_df, metric_key, markersize=3, color=None):
+    """Plot validation phase data as scatter."""
+    if color is None:
+        color = str2hex("green")
+
+    is_validation = scitex.str.search(
+        "^[Vv]alid(ation)?", metrics_df.step, as_bool=True
+    )[0]
+    validation_df = metrics_df[is_validation]
+
+    if len(validation_df) > 0:
+        ax.scatter(
+            validation_df.index,
+            validation_df[metric_key],
+            label="Validation",
+            color=color,
+            s=markersize,
+            alpha=0.9,
+        )
+        ax.legend()
+    return ax
+
+
+def _plot_test_data(ax, metrics_df, metric_key, markersize=3, color=None):
+    """Plot test phase data as scatter."""
+    if color is None:
+        color = str2hex("red")
+
+    is_test = scitex.str.search("^[Tt]est", metrics_df.step, as_bool=True)[0]
+    test_df = metrics_df[is_test]
+
+    if len(test_df) > 0:
+        ax.scatter(
+            test_df.index,
+            test_df[metric_key],
+            label="Test",
+            color=color,
+            s=markersize,
+            alpha=0.9,
+        )
+        ax.legend()
+    return ax
+
+
+def _add_epoch_vlines(ax, metrics_df, color="grey"):
+    """Add vertical lines at epoch boundaries."""
+    epoch_starts = metrics_df[metrics_df["i_batch"] == 0].index.values
+    ax.vlines(
+        x=epoch_starts,
+        ymin=-1e4,
+        ymax=1e4,
+        linestyle="--",
+        color=color,
+    )
+    return ax
+
+
+def _select_epoch_ticks(metrics_df, max_n_ticks=4):
+    """Select representative epoch tick positions and labels."""
+    unique_epochs = metrics_df["i_epoch"].drop_duplicates().values
+    epoch_starts = (
+        metrics_df[metrics_df["i_batch"] == 0]["i_global"]
+        .drop_duplicates()
+        .values
+    )
+
+    if len(epoch_starts) > max_n_ticks:
+        selected_ticks = np.linspace(
+            epoch_starts[0], epoch_starts[-1], max_n_ticks, dtype=int
+        )
+        selected_labels = [
+            metrics_df[metrics_df["i_global"] == tick]["i_epoch"].iloc[0]
+            for tick in selected_ticks
+        ]
+    else:
+        selected_ticks = epoch_starts
+        selected_labels = unique_epochs
+    return selected_ticks, selected_labels
+
+
+def plot_learning_curve(
+    metrics_df,
+    keys,
+    title="Title",
+    max_n_ticks=4,
+    scattersize=3,
+    linewidth=1,
+    yscale="linear",
+    spath=None,
+):
+    """Plot learning curves from training metrics.
+
+    This is mainly used by scitex/ml/training/_LearningCurveLogger.py
+
+    Parameters
+    ----------
+    metrics_df : pd.DataFrame
+        DataFrame with columns: step, i_global, i_epoch, i_batch, and metric columns
+    keys : list of str
+        Metric names to plot
+    title : str
+        Plot title
+    max_n_ticks : int
+        Maximum number of ticks on x-axis
+    scattersize : float
+        Size of scatter points for validation/test
+    linewidth : float
+        Width of training line
+    yscale : str
+        Y-axis scale ('linear' or 'log')
+    spath : str, optional
+        Save path for the figure
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+        Figure containing learning curves
+
+    Example
+    -------
+    >>> print(metrics_df)
+    #                 step  i_global  i_epoch  i_batch      loss
+    # 0       Training         0        0        0  0.717023
+    # 1       Training         1        0        1  0.703844
+    # ...
+    # [123271 rows x 5 columns]
+    """
+    # Prepare data
+    metrics_df = _prepare_metrics_df(metrics_df)
+    selected_ticks, selected_labels = _select_epoch_ticks(metrics_df, max_n_ticks)
+
+    # Create subplots
+    fig, axes = scitex.plt.subplots(len(keys), 1, sharex=True, sharey=False)
+    axes = axes if len(keys) != 1 else [axes]
+
+    # Configure axes
+    axes[-1].set_xlabel("Iteration #")
+    fig.text(0.5, 0.95, title, ha="center")
+
+    # Plot each metric
+    for i_metric, metric_key in enumerate(keys):
+        ax = axes[i_metric]
+        ax.set_yscale(yscale)
+        ax.set_ylabel(metric_key)
+
+        # Configure axis for accuracy metrics
+        ax = _configure_accuracy_axis(ax, metric_key)
+
+        # Plot training data (line)
+        ax = _plot_training_data(
+            ax, metrics_df, metric_key, linewidth=linewidth
+        )
+
+        # Plot validation data (scatter)
+        ax = _plot_validation_data(
+            ax, metrics_df, metric_key, markersize=scattersize
+        )
+
+        # Plot test data if it exists (scatter)
+        if "Test" in metrics_df["step"].values:
+            ax = _plot_test_data(
+                ax, metrics_df, metric_key, markersize=scattersize
+            )
+
+    # Save if path provided
+    if spath is not None:
+        scitex.io.save(fig, spath, use_caller_path=True)
+
+    return fig
+
+
+def main(args):
+    """Demo learning curve plotting with synthetic data."""
+    import matplotlib.pyplot as plt
+    import numpy as np
+    import pandas as pd
+
+    # Create synthetic metrics data
+    n_epochs = 10
+    n_batches = 100
+    data = []
+    for i_epoch in range(n_epochs):
+        for i_batch in range(n_batches):
+            i_global = i_epoch * n_batches + i_batch
+            loss = 0.7 * np.exp(-i_global / 200) + 0.1 * np.random.rand()
+            acc = min(
+                0.95,
+                0.3
+                + 0.6 * (1 - np.exp(-i_global / 300))
+                + 0.05 * np.random.rand(),
+            )
+            data.append(
+                {
+                    "step": "Training",
+                    "i_global": i_global,
+                    "i_epoch": i_epoch,
+                    "i_batch": i_batch,
+                    "loss": loss,
+                    "accuracy": acc,
+                }
+            )
+        # Add validation metrics at epoch end
+        i_global = (i_epoch + 1) * n_batches - 1
+        val_loss = 0.75 * np.exp(-i_global / 200) + 0.15 * np.random.rand()
+        val_acc = min(
+            0.92,
+            0.25
+            + 0.6 * (1 - np.exp(-i_global / 300))
+            + 0.08 * np.random.rand(),
+        )
+        data.append(
+            {
+                "step": "Validation",
+                "i_global": i_global,
+                "i_epoch": i_epoch,
+                "i_batch": n_batches - 1,
+                "loss": val_loss,
+                "accuracy": val_acc,
+            }
+        )
+
+    metrics_df = pd.DataFrame(data)
+    keys = ["loss", "accuracy"]
+    fig = plot_learning_curve(
+        metrics_df,
+        keys,
+        title="Demo Learning Curve",
+        yscale="linear",
+        spath="learning_curve_demo.jpg",
+    )
+    return 0
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Demo learning curve plotting"
+    )
+    return parser.parse_args()
+
+
+def run_main() -> None:
+    """Initialize scitex framework, run main function, and cleanup."""
+    global CONFIG, CC, sys, plt, rng
+
+    import sys
+
+    import matplotlib.pyplot as plt
+    import scitex as stx
+
+    args = parse_args()
+
+    CONFIG, sys.stdout, sys.stderr, plt, CC, rng = stx.session.start(
+        sys,
+        plt,
+        args=args,
+        file=__FILE__,
+        sdir_suffix=None,
+        verbose=False,
+        agg=True,
+    )
+
+    exit_status = main(args)
+
+    stx.session.close(
+        CONFIG,
+        verbose=False,
+        notify=False,
+        message="",
+        exit_status=exit_status,
+    )
+
+
+if __name__ == "__main__":
+    run_main()
+
+# EOF