dragon-ml-toolbox 19.14.0__py3-none-any.whl → 20.0.0__py3-none-any.whl

ml_tools/ML_evaluation/_regression.py

@@ -0,0 +1,273 @@
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import seaborn as sns
+from sklearn.metrics import (
+    mean_squared_error,
+    mean_absolute_error,
+    r2_score, 
+    median_absolute_error,
+)
+from pathlib import Path
+from typing import Union, Optional
+
+from ..ML_configuration._metrics import (_BaseRegressionFormat,
+                                        FormatRegressionMetrics,
+                                        FormatMultiTargetRegressionMetrics)
+
+from ..path_manager import make_fullpath, sanitize_filename
+from .._core import get_logger
+from ..keys._keys import _EvaluationConfig
+
+
+_LOGGER = get_logger("Regression Metrics")
+
+
+__all__ = [
+    "regression_metrics",
+    "multi_target_regression_metrics"
+]
+
+
+DPI_value = _EvaluationConfig.DPI
+REGRESSION_PLOT_SIZE = _EvaluationConfig.REGRESSION_PLOT_SIZE
+
+
+def regression_metrics(
+    y_true: np.ndarray, 
+    y_pred: np.ndarray, 
+    save_dir: Union[str, Path],
+    config: Optional[FormatRegressionMetrics] = None
+):
+    """
+    Saves regression metrics and plots.
+
+    Args:
+        y_true (np.ndarray): Ground truth values.
+        y_pred (np.ndarray): Predicted values.
+        save_dir (str | Path): Directory to save plots and report.
+        config (RegressionMetricsFormat, optional): Formatting configuration object.
+    """
+    
+    # --- Parse Config or use defaults ---
+    if config is None:
+        # Create a default config if one wasn't provided
+        format_config = _BaseRegressionFormat()
+    else:
+        format_config = config
+    
+    # --- Resolve Font Sizes ---
+    xtick_size = format_config.xtick_size
+    ytick_size = format_config.ytick_size
+    base_font_size = format_config.font_size
+    
+    # --- Calculate Metrics ---
+    rmse = np.sqrt(mean_squared_error(y_true, y_pred))
+    mae = mean_absolute_error(y_true, y_pred)
+    r2 = r2_score(y_true, y_pred)
+    medae = median_absolute_error(y_true, y_pred)
+    
+    report_lines = [
+        "--- Regression Report ---",
+        f"  Root Mean Squared Error (RMSE): {rmse:.4f}",
+        f"  Mean Absolute Error (MAE):      {mae:.4f}",
+        f"  Median Absolute Error (MedAE):  {medae:.4f}",
+        f"  Coefficient of Determination (R²): {r2:.4f}"
+    ]
+    report_string = "\n".join(report_lines)
+    # print(report_string)
+
+    save_dir_path = make_fullpath(save_dir, make=True, enforce="directory")
+    # Save text report
+    report_path = save_dir_path / "regression_report.txt"
+    report_path.write_text(report_string)
+    _LOGGER.info(f"📝 Regression report saved as '{report_path.name}'")
+
+    # --- Save residual plot ---
+    residuals = y_true - y_pred
+    fig_res, ax_res = plt.subplots(figsize=REGRESSION_PLOT_SIZE, dpi=DPI_value)
+    ax_res.scatter(y_pred, residuals, 
+                   alpha=format_config.scatter_alpha, 
+                   color=format_config.scatter_color)
+    ax_res.axhline(0, color=format_config.residual_line_color, linestyle='--')
+    ax_res.set_xlabel("Predicted Values", labelpad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size)
+    ax_res.set_ylabel("Residuals", labelpad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size)
+    ax_res.set_title("Residual Plot", pad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size + 2)
+    
+    # Apply Ticks  
+    ax_res.tick_params(axis='x', labelsize=xtick_size)
+    ax_res.tick_params(axis='y', labelsize=ytick_size)
+    
+    ax_res.grid(True)
+    plt.tight_layout()
+    res_path = save_dir_path / "residual_plot.svg"
+    plt.savefig(res_path)
+    _LOGGER.info(f"📈 Residual plot saved as '{res_path.name}'")
+    plt.close(fig_res)
+
+    # --- Save true vs predicted plot ---
+    fig_tvp, ax_tvp = plt.subplots(figsize=REGRESSION_PLOT_SIZE, dpi=DPI_value)
+    ax_tvp.scatter(y_true, y_pred, 
+                   alpha=format_config.scatter_alpha, 
+                   color=format_config.scatter_color)
+    ax_tvp.plot([y_true.min(), y_true.max()], [y_true.min(), y_true.max()], 
+                linestyle='--', 
+                lw=2,
+                color=format_config.ideal_line_color)
+    ax_tvp.set_xlabel('True Values', labelpad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size)
+    ax_tvp.set_ylabel('Predictions', labelpad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size)
+    ax_tvp.set_title('True vs. Predicted Values', pad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size + 2)
+    
+    # Apply Ticks
+    ax_tvp.tick_params(axis='x', labelsize=xtick_size)
+    ax_tvp.tick_params(axis='y', labelsize=ytick_size)
+    
+    ax_tvp.grid(True)
+    plt.tight_layout()
+    tvp_path = save_dir_path / "true_vs_predicted_plot.svg"
+    plt.savefig(tvp_path)
+    _LOGGER.info(f"📉 True vs. Predicted plot saved as '{tvp_path.name}'")
+    plt.close(fig_tvp)
+    
+    # --- Save Histogram of Residuals ---
+    fig_hist, ax_hist = plt.subplots(figsize=REGRESSION_PLOT_SIZE, dpi=DPI_value)
+    sns.histplot(residuals, kde=True, ax=ax_hist, 
+                 bins=format_config.hist_bins, 
+                 color=format_config.scatter_color)
+    ax_hist.set_xlabel("Residual Value", labelpad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size)
+    ax_hist.set_ylabel("Frequency", labelpad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size)
+    ax_hist.set_title("Distribution of Residuals", pad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size + 2)
+    
+    # Apply Ticks
+    ax_hist.tick_params(axis='x', labelsize=xtick_size)
+    ax_hist.tick_params(axis='y', labelsize=ytick_size)
+    
+    ax_hist.grid(True)
+    plt.tight_layout()
+    hist_path = save_dir_path / "residuals_histogram.svg"
+    plt.savefig(hist_path)
+    _LOGGER.info(f"📊 Residuals histogram saved as '{hist_path.name}'")
+    plt.close(fig_hist)
+
+
+def multi_target_regression_metrics(
+    y_true: np.ndarray,
+    y_pred: np.ndarray,
+    target_names: list[str],
+    save_dir: Union[str, Path],
+    config: Optional[FormatMultiTargetRegressionMetrics] = None
+):
+    """
+    Calculates and saves regression metrics for each target individually.
+
+    For each target, this function saves a residual plot and a true vs. predicted plot.
+    It also saves a single CSV file containing the key metrics (RMSE, MAE, R², MedAE)
+    for all targets.
+
+    Args:
+        y_true (np.ndarray): Ground truth values, shape (n_samples, n_targets).
+        y_pred (np.ndarray): Predicted values, shape (n_samples, n_targets).
+        target_names (List[str]): A list of names for the target variables.
+        save_dir (str | Path): Directory to save plots and the report.
+        config (object): Formatting configuration object.
+    """
+    if y_true.ndim != 2 or y_pred.ndim != 2:
+        _LOGGER.error("y_true and y_pred must be 2D arrays for multi-target regression.")
+        raise ValueError()
+    if y_true.shape != y_pred.shape:
+        _LOGGER.error("Shapes of y_true and y_pred must match.")
+        raise ValueError()
+    if y_true.shape[1] != len(target_names):
+        _LOGGER.error("Number of target names must match the number of columns in y_true.")
+        raise ValueError()
+
+    save_dir_path = make_fullpath(save_dir, make=True, enforce="directory")
+    metrics_summary = []
+    
+    # --- Parse Config or use defaults ---
+    if config is None:
+        # Create a default config if one wasn't provided
+        format_config = _BaseRegressionFormat()
+    else:
+        format_config = config
+    
+    # ticks font sizes 
+    xtick_size = format_config.xtick_size
+    ytick_size = format_config.ytick_size
+    base_font_size = format_config.font_size
+
+    _LOGGER.debug("--- Multi-Target Regression Evaluation ---")
+
+    for i, name in enumerate(target_names):
+        # print(f"  -> Evaluating target: '{name}'")
+        true_i = y_true[:, i]
+        pred_i = y_pred[:, i]
+        sanitized_name = sanitize_filename(name)
+
+        # --- Calculate Metrics ---
+        rmse = np.sqrt(mean_squared_error(true_i, pred_i))
+        mae = mean_absolute_error(true_i, pred_i)
+        r2 = r2_score(true_i, pred_i)
+        medae = median_absolute_error(true_i, pred_i)
+        metrics_summary.append({
+            'Target': name,
+            'RMSE': rmse,
+            'MAE': mae,
+            'MedAE': medae,
+            'R2-score': r2,
+        })
+
+        # --- Save Residual Plot ---
+        residuals = true_i - pred_i
+        fig_res, ax_res = plt.subplots(figsize=REGRESSION_PLOT_SIZE, dpi=DPI_value)
+        ax_res.scatter(pred_i, residuals, 
+                       alpha=format_config.scatter_alpha, 
+                       edgecolors='k', 
+                       s=50,
+                       color=format_config.scatter_color) # Use config color
+        ax_res.axhline(0, color=format_config.residual_line_color, linestyle='--') # Use config color
+        ax_res.set_xlabel("Predicted Values", labelpad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size)
+        ax_res.set_ylabel("Residuals", labelpad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size)
+        ax_res.set_title(f"Residual Plot for '{name}'", pad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size + 2)
+        
+        # Apply Ticks
+        ax_res.tick_params(axis='x', labelsize=xtick_size)
+        ax_res.tick_params(axis='y', labelsize=ytick_size)
+        
+        ax_res.grid(True, linestyle='--', alpha=0.6)
+        plt.tight_layout()
+        res_path = save_dir_path / f"residual_plot_{sanitized_name}.svg"
+        plt.savefig(res_path)
+        plt.close(fig_res)
+
+        # --- Save True vs. Predicted Plot ---
+        fig_tvp, ax_tvp = plt.subplots(figsize=REGRESSION_PLOT_SIZE, dpi=DPI_value)
+        ax_tvp.scatter(true_i, pred_i, 
+                       alpha=format_config.scatter_alpha, 
+                       edgecolors='k', 
+                       s=50,
+                       color=format_config.scatter_color) # Use config color
+        ax_tvp.plot([true_i.min(), true_i.max()], [true_i.min(), true_i.max()], 
+                    linestyle='--', 
+                    lw=2,
+                    color=format_config.ideal_line_color) # Use config color
+        ax_tvp.set_xlabel('True Values', labelpad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size)
+        ax_tvp.set_ylabel('Predicted Values', labelpad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size)
+        ax_tvp.set_title(f"True vs. Predicted for '{name}'", pad=_EvaluationConfig.LABEL_PADDING, fontsize=base_font_size + 2)
+        
+        # Apply Ticks
+        ax_tvp.tick_params(axis='x', labelsize=xtick_size)
+        ax_tvp.tick_params(axis='y', labelsize=ytick_size)
+        
+        ax_tvp.grid(True, linestyle='--', alpha=0.6)
+        plt.tight_layout()
+        tvp_path = save_dir_path / f"true_vs_predicted_plot_{sanitized_name}.svg"
+        plt.savefig(tvp_path)
+        plt.close(fig_tvp)
+
+    # --- Save Summary Report ---
+    summary_df = pd.DataFrame(metrics_summary)
+    report_path = save_dir_path / "regression_report_multi.csv"
+    summary_df.to_csv(report_path, index=False)
+    _LOGGER.info(f"Full regression report saved to '{report_path.name}'")
+

ml_tools/{_core/_ML_sequence_evaluation.py → ML_evaluation/_sequence.py}

@@ -11,14 +11,14 @@ from sklearn.metrics import (
 from pathlib import Path
 from typing import Union, Optional
 
-from ._path_manager import make_fullpath
-from ._logger import get_logger
-from ._script_info import _script_info
-from ._ML_configuration import SequenceValueMetricsFormat, SequenceSequenceMetricsFormat, _BaseSequenceValueFormat, _BaseSequenceSequenceFormat
-from ._keys import _EvaluationConfig
+from ..ML_configuration._metrics import FormatSequenceValueMetrics, FormatSequenceSequenceMetrics, _BaseSequenceValueFormat, _BaseSequenceSequenceFormat
 
+from ..keys._keys import _EvaluationConfig
+from ..path_manager import make_fullpath
+from .._core import get_logger
 
-_LOGGER = get_logger("Sequence Evaluation")
+
+_LOGGER = get_logger("Sequence Metrics")
 
 
 __all__ = [
@@ -35,7 +35,7 @@ def sequence_to_value_metrics(
     y_true: np.ndarray, 
     y_pred: np.ndarray, 
     save_dir: Union[str, Path],
-    config: Optional[SequenceValueMetricsFormat] = None
+    config: Optional[FormatSequenceValueMetrics] = None
 ):
     """
     Saves regression metrics and plots for sequence-to-value (many-to-one) tasks.
@@ -127,7 +127,7 @@ def sequence_to_sequence_metrics(
     y_true: np.ndarray, 
     y_pred: np.ndarray, 
     save_dir: Union[str, Path],
-    config: Optional[SequenceSequenceMetricsFormat] = None
+    config: Optional[FormatSequenceSequenceMetrics] = None
 ):
     """
     Saves per-step regression metrics for sequence-to-sequence (many-to-many) tasks.
@@ -220,6 +220,3 @@ def sequence_to_sequence_metrics(
     # --- Restore RC params ---
     plt.rcParams.update(original_rc_params)
 
-
-def info():
-    _script_info(__all__)

ml_tools/{_core/_ML_vision_evaluation.py → ML_evaluation/_vision.py}

@@ -11,20 +11,18 @@ from sklearn.metrics import (
     ConfusionMatrixDisplay
 )
 from pathlib import Path
-from typing import Union, Optional, List, Dict
+from typing import Union, Optional
 import json
 from torchmetrics.detection import MeanAveragePrecision
 
-from ._path_manager import make_fullpath
-from ._logger import get_logger
-from ._script_info import _script_info
-from ._keys import VisionKeys, _EvaluationConfig
-from ._ML_configuration import (BinarySegmentationMetricsFormat,
-                               MultiClassSegmentationMetricsFormat,
-                               _BaseSegmentationFormat)
+from ..ML_configuration._metrics import FormatBinarySegmentationMetrics, FormatMultiClassSegmentationMetrics, _BaseSegmentationFormat
 
+from ..path_manager import make_fullpath
+from .._core import get_logger
+from ..keys._keys import VisionKeys, _EvaluationConfig
 
-_LOGGER = get_logger("Vision Evaluation")
+
+_LOGGER = get_logger("Vision Metrics")
 
 
 __all__ = [
@@ -40,8 +38,8 @@ def segmentation_metrics(
     y_true: np.ndarray,
     y_pred: np.ndarray,
     save_dir: Union[str, Path],
-    class_names: Optional[List[str]] = None,
-    config: Optional[Union[BinarySegmentationMetricsFormat, MultiClassSegmentationMetricsFormat]] = None
+    class_names: Optional[list[str]] = None,
+    config: Optional[Union[FormatBinarySegmentationMetrics, FormatMultiClassSegmentationMetrics]] = None
 ):
     """
     Calculates and saves pixel-level metrics for segmentation tasks.
@@ -191,10 +189,10 @@ def segmentation_metrics(
 
 
 def object_detection_metrics(
-    preds: List[Dict[str, torch.Tensor]],
-    targets: List[Dict[str, torch.Tensor]],
+    preds: list[dict[str, torch.Tensor]],
+    targets: list[dict[str, torch.Tensor]],
     save_dir: Union[str, Path],
-    class_names: Optional[List[str]] = None,
+    class_names: Optional[list[str]] = None,
     print_output: bool=False
 ):
     """
@@ -283,6 +281,3 @@ def object_detection_metrics(
         _LOGGER.error(f"Failed to compute mAP: {e}")
         raise
 
-
-def info():
-    _script_info(__all__)

ml_tools/{_core → ML_evaluation_captum}/_ML_evaluation_captum.py

@@ -1,29 +1,21 @@
-from typing import Optional, List, Union
+from typing import Optional, Union
 from pathlib import Path
 import numpy as np
 import pandas as pd
 import matplotlib.pyplot as plt
 import torch
 from torch import nn
+from captum.attr import IntegratedGradients
+from captum.attr import visualization as viz
 
-from ._path_manager import make_fullpath, sanitize_filename
-from ._logger import get_logger
-from ._script_info import _script_info
-from ._keys import CaptumKeys
+from ..path_manager import make_fullpath, sanitize_filename
+from .._core import get_logger
+from ..keys._keys import CaptumKeys
 
 
 _LOGGER = get_logger("Captum")
 
 
-# --- Dependency Check ---
-try:
-    from captum.attr import IntegratedGradients
-    from captum.attr import visualization as viz
-    CAPTUM_AVAILABLE = True
-except ImportError:
-    CAPTUM_AVAILABLE = False
-
-
 __all__ = [
     "captum_feature_importance", 
     "captum_image_heatmap",
@@ -31,16 +23,12 @@ __all__ = [
     ]
 
 
-def _is_captum_available() -> bool:
-    """Returns True if captum is installed and importable."""
-    return CAPTUM_AVAILABLE
-
 
 def captum_feature_importance(model: nn.Module,
                               input_data: torch.Tensor,
-                              feature_names: Optional[List[str]],
+                              feature_names: Optional[list[str]],
                               save_dir: Union[str, Path],
-                              target_names: Optional[List[str]] = None,
+                              target_names: Optional[list[str]] = None,
                               n_steps: int = 50,
                               device: Union[str, torch.device] = 'cpu'):
     """
@@ -67,10 +55,6 @@ def captum_feature_importance(model: nn.Module,
     ### NOTE: 
     The internal batch size used by Captum will be set to the number of samples. If you run into OOM errors, consider reducing `n_samples`.
     """
-    if not CAPTUM_AVAILABLE:
-        _LOGGER.error("Captum is not installed. Please run `pip install captum` to use this feature.")
-        return
-
     # Ensure output directory exists
     save_dir_path = make_fullpath(save_dir, make=True, enforce="directory")
     
@@ -150,7 +134,7 @@ def _process_single_target(ig: 'IntegratedGradients', # type: ignore
                            inputs: torch.Tensor,
                            baseline: torch.Tensor,
                            target_index: Union[int, None],
-                           feature_names: Optional[List[str]],
+                           feature_names: Optional[list[str]],
                            save_dir: Path,
                            n_steps: int,
                            file_suffix: str):
@@ -250,7 +234,7 @@ def _process_single_target(ig: 'IntegratedGradients', # type: ignore
 def captum_image_heatmap(model: nn.Module,
                          input_data: torch.Tensor,
                          save_dir: Union[str, Path],
-                         target_names: Optional[List[str]] = None,
+                         target_names: Optional[list[str]] = None,
                          n_steps: int = 50,
                          device: Union[str, torch.device] = 'cpu'):
     """
@@ -270,10 +254,6 @@ def captum_image_heatmap(model: nn.Module,
                        Higher values increase accuracy but require more memory/time.
         device (str | torch.device): The device to run the calculation on.
     """
-    if not CAPTUM_AVAILABLE:
-        _LOGGER.error("Captum is not installed. Please run `pip install captum` to use this feature.")
-        return
-    
     save_dir_path = make_fullpath(save_dir, make=True, enforce="directory")
     device_obj = torch.device(device) if isinstance(device, str) else device
     
@@ -343,7 +323,7 @@ def captum_image_heatmap(model: nn.Module,
 def captum_segmentation_heatmap(model: nn.Module,
                                 input_data: torch.Tensor,
                                 save_dir: Union[str, Path],
-                                target_names: Optional[List[str]],
+                                target_names: Optional[list[str]],
                                 n_steps: int = 30,
                                 device: Union[str, torch.device] = 'cpu'):
     """
@@ -361,10 +341,6 @@ def captum_segmentation_heatmap(model: nn.Module,
         n_steps (int): Integration steps. Kept lower by default (30) for performance on high-res images.
         device (str | torch.device): Torch device.
     """
-    if not CAPTUM_AVAILABLE:
-        _LOGGER.error("Captum is not installed. Please run `pip install captum` to use this feature.")
-        return
-
     save_dir_path = make_fullpath(save_dir, make=True, enforce="directory")
     device_obj = torch.device(device) if isinstance(device, str) else device
     model.eval()
@@ -448,6 +424,3 @@ def captum_segmentation_heatmap(model: nn.Module,
             except Exception as e:
                 _LOGGER.error(f"Failed to generate heatmap for Sample {sample_idx}, Class {class_name}: {e}")
 
-
-def info():
-    _script_info(__all__)

ml_tools/{ML_evaluation_captum.py → ML_evaluation_captum/__init__.py}

@@ -1,10 +1,12 @@
-from ._core._ML_evaluation_captum import (
-    captum_feature_importance,
+from ._ML_evaluation_captum import (
+    captum_feature_importance, 
     captum_image_heatmap,
-    captum_segmentation_heatmap,
-    info
+    captum_segmentation_heatmap
 )
 
+from ._imprimir import info
+
+
 __all__ = [
     "captum_feature_importance", 
     "captum_image_heatmap",

ml_tools/ML_evaluation_captum/_imprimir.py

@@ -0,0 +1,10 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "captum_feature_importance", 
+    "captum_image_heatmap",
+    "captum_segmentation_heatmap"
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{_core → ML_finalize_handler}/_ML_finalize_handler.py

@@ -4,10 +4,9 @@ import numpy as np
 from typing import Union, Any, Optional
 from pathlib import Path
 
-from ._logger import get_logger
-from ._script_info import _script_info
-from ._path_manager import make_fullpath
-from ._keys import PyTorchCheckpointKeys, MagicWords
+from .._core import get_logger
+from ..path_manager import make_fullpath
+from ..keys._keys import PyTorchCheckpointKeys, MagicWords
 
 
 _LOGGER = get_logger("Finalized-File")
@@ -160,6 +159,3 @@ class FinalizedFileHandler:
         self._none_checker(self._sequence_length, PyTorchCheckpointKeys.SEQUENCE_LENGTH)
         return self._sequence_length
     
-
-def info():
-    _script_info(__all__)

ml_tools/ML_finalize_handler/__init__.py

@@ -0,0 +1,10 @@
+from ._ML_finalize_handler import (
+    FinalizedFileHandler
+)
+
+from ._imprimir import info
+
+
+__all__ = [
+    "FinalizedFileHandler"
+]

ml_tools/ML_finalize_handler/_imprimir.py

@@ -0,0 +1,8 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "FinalizedFileHandler"
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/ML_inference/__init__.py

@@ -0,0 +1,22 @@
+from ._dragon_inference import (
+    DragonInferenceHandler
+)
+
+from ._chain_inference import (
+    DragonChainInference
+)
+
+from ._multi_inference import (
+    multi_inference_regression,
+    multi_inference_classification,
+)
+
+from ._imprimir import info
+
+
+__all__ = [
+    "DragonInferenceHandler",
+    "DragonChainInference",
+    "multi_inference_regression",
+    "multi_inference_classification"
+]