PyIAML 1.0.0__py3-none-any.whl

iaml/plots/rocauc_plot.py

@@ -0,0 +1,96 @@
+"""[PLOT] ROC-AUC Plot"""
+from __future__ import annotations
+
+import textwrap
+import io
+from typing import TYPE_CHECKING
+import pandas as pd
+import matplotlib.pyplot as plt
+from sklearn.metrics import roc_curve, auc
+
+from ..metric_plot import MetricPlot, capture
+if TYPE_CHECKING:
+    from ..iaml_pipeline import IAMLPipeline
+
+
+class ROCAUCPlot(MetricPlot):
+    """[PLOT] ROC-AUC Plot"""
+
+    title: str = "Receiver Operating Characteristic - Area Under the Curve"
+    description: str = textwrap.dedent("""
+        The ROC-AUC (Receiver Operating Characteristic - Area Under the Curve) plot is a widely used 
+        tool to assess the performance of a classification model, especially in the healthcare domain. 
+        It provides a graphical representation of the model's ability to distinguish between classes, 
+        such as diagnosing the presence or absence of a medical condition.
+
+        The ROC curve shows the trade-off between the true positive rate (sensitivity) and false positive 
+        rate for different threshold values. The AUC score (Area Under the Curve) summarizes the performance 
+        into a single number, where a value of 1 indicates perfect classification, and 0.5 represents a 
+        model no better than random guessing.
+
+        For instance, in a medical setting, you might have a model predicting whether a patient has a 
+        certain disease or is healthy. The ROC curve would help evaluate how well the model can separate 
+        patients with the disease from those without. The closer the curve is to the top-left corner and 
+        the higher the AUC score, the better the model is at distinguishing between the conditions.
+
+        **Micro-average** and **macro-average** ROC curves are useful when dealing with multiclass classification 
+        problems (where there are more than two classes). 
+
+        - **Micro-average** ROC aggregates the contributions of all classes and calculates metrics globally 
+            by counting the total true positives, false positives, true negatives, and false negatives. 
+            It provides a single ROC curve by combining all classes, treating each decision as a binary one 
+            (one-vs-rest). This is useful when you care about the overall performance of the classifier across 
+            all categories.
+
+        - **Macro-average** ROC computes the ROC curve for each class separately and then averages the results. 
+            This gives equal weight to all classes, regardless of the number of samples. Macro-average is useful 
+            when you want to evaluate the model's performance on each class individually, giving each class the 
+            same importance, regardless of how often it appears in the dataset.
+
+        Doctors and data scientists use this visualization to ensure that the model performs well across 
+        different threshold values, making it a critical tool in situations where misdiagnosis could have 
+        serious consequences.
+        """)
+
+    @capture
+    def compute(
+        self,
+        estimator: IAMLPipeline,
+        X: pd.DataFrame,
+        y: pd.Series,
+        X_train: pd.DataFrame = None,
+        y_train: pd.Series = None,
+        **kwargs) -> MetricPlot:
+        self._binary_image = io.BytesIO()
+
+        pos_label = None
+        if y.dtype not in ['int', 'bool']:
+            pos_label = y.iloc[0] if isinstance(y, pd.Series) else y[0]
+
+        # Predict probabilities
+        y_prob = estimator.predict_proba(X)[:, 1]
+
+        # Compute ROC curve and AUC
+        fpr, tpr, _ = roc_curve(y, y_prob, pos_label=pos_label)
+        roc_auc = auc(fpr, tpr)
+
+        # Create the ROC plot
+        plt.figure()
+        plt.plot(fpr, tpr, color='blue', lw=2, label=f'ROC curve (AUC = {roc_auc:.2f})')
+        plt.plot([0, 1], [0, 1], color='grey', lw=2, linestyle='--', label='Random guess')
+        plt.xlim([0.0, 1.0])
+        plt.ylim([0.0, 1.05])
+        plt.xlabel('False Positive Rate')
+        plt.ylabel('True Positive Rate')
+        plt.title('Receiver Operating Characteristic')
+        plt.legend(loc='lower right')
+        plt.grid(True)
+
+        # Save plot to binary image
+        plt.savefig(self._binary_image, format='png')
+
+        return self
+
+    @classmethod
+    def suitable(cls, type_of_target: str) -> bool:
+        return type_of_target == 'binary'

iaml/plots/shap_plot.py

@@ -0,0 +1,187 @@
+"""[PLOT] Wrap Shap Plot """
+import textwrap
+import io
+from typing import Any
+import matplotlib.pyplot as plt
+import numpy as np
+import shap
+
+from ..plot import Plot
+
+
+class ShapPlot(Plot):
+    """[PLOT] Wrap Shap Plot
+
+    :param str plot_key: The kind of shap plot to use.
+    :param shap.Explanation | shap.Cohorts | dict[shap.Explanation] shaps_values: Values used
+            by the shap library to compute data.
+    :param optional \\*args: Additional parameters.
+    :param slice, optional ps: Used to slice shaps_values. Default is None.
+    :param optional scatter_feature: Used to select specific shaps_values. Default is None.
+    :param optional \\**kwargs: Additional parameters.
+    
+    """
+    def __init__(
+        self,
+        plot_key: str,
+        shaps_values: shap.Explanation | shap.Cohorts | dict[shap.Explanation],
+        *args,
+        ps: slice = None,
+        scatter_feature: Any | shap.Cohorts | None = None,
+        **kwargs) -> None:
+        self.key: str = plot_key
+        """The kind of shap plot to perform"""
+
+        if ps is None:
+            ps = slice(0, len(shaps_values))
+
+        if scatter_feature is None and plot_key == 'scatter':
+            scatter_feature = shaps_values.feature_names[0]
+
+        method, self.title, self.description = self.__plots_informations(plot_key, shaps_values)
+        self._binary_image = io.BytesIO()
+
+        if plot_key == 'scatter':
+            method(shaps_values[ps, scatter_feature], *args, show=False, **kwargs)
+        elif plot_key == 'force':
+            method(shaps_values[ps.start], *args, show=False, matplotlib=True, **kwargs)
+        elif plot_key == 'waterfall':
+            method(shaps_values[ps.start], *args, show=False, **kwargs)
+        else:
+            method(shaps_values[ps], *args, show=False, **kwargs)
+
+        plt.savefig(self._binary_image, bbox_inches='tight')
+        plt.close()
+
+    @classmethod
+    def all(
+        cls,
+        shaps_values: shap.Explanation | shap.Cohorts | dict[shap.Explanation],
+        *args,
+        **kwargs) -> list['ShapPlot']:
+        """Get instance for all kind of Shap Plot
+
+        :param shap.Explanation | shap.Cohorts | dict[shap.Explanation] shaps_values: Values used
+            by the shap library to compute data.
+        :param optional \\*args: Additional parameters.
+        :param optional \\**kwargs: Additional parameters.
+        
+        :return: list of computed ShapPlot.
+        """
+        plots = []
+        for key in ['force', 'waterfall', 'beeswarm', 'scatter', 'heatmap', 'bar']:
+            plots.append(cls(key, shaps_values, *args, **kwargs))
+
+        return plots
+
+    def __plots_informations(
+        self,
+        key: str,
+        shap_values: shap.Explanation | shap.Cohorts | dict[shap.Explanation]) -> tuple[str]:
+        """
+        Returns the title and description for various SHAP plot types in simple terms.
+
+        This function provides easy-to-understand explanations for SHAP plots, using 
+        examples from the medical field, to help non-experts interpret how machine learning 
+        models make predictions.
+
+        :param str key: The type of SHAP plot
+
+            * force
+            * waterfall
+            * beeswarm
+            * scatter
+            * heatmap
+            * bar
+        :param shap.Explanation | shap.Cohorts | dict[shap.Explanation] shap_values: Values used
+            by the shap library to compute data.
+        :return: A title and description of the SHAP plot type, explaining what it shows and how it 
+            relates to model predictions.
+        """
+        features = shap_values.feature_names
+        values = shap_values[0].values
+
+        match key:
+            case 'force':
+                force_shap, force_feature = max(zip(values, features), key=lambda v: abs(v[0]))
+                return (shap.plots.force,
+                    textwrap.dedent("""\
+                    SHAP Force Plot: Visualizing How Individual Factors Contribute to a Prediction
+                    """),
+                    textwrap.dedent(f"""\
+                    The force plot shows how different factors (e.g., age, cholesterol level, blood 
+                    pressure) push the model’s prediction for an individual patient. It explains 
+                    whether each factor increases or decreases the likelihood of a certain outcome, 
+                    such as a diagnosis of heart disease. Red arrows indicate factors increasing risk, 
+                    while blue arrows show those reducing risk. This plot helps interpret the specific 
+                    impact of each factor for a given prediction.
+                    
+                    Reading: For this prediction, `{force_feature}` impacts the final prediction 
+                    value by {force_shap:.3f}.
+                    """))
+            case 'waterfall':
+                force_shap, force_feature = max(zip(values, features), key=lambda v: abs(v[0]))
+                return (shap.plots.waterfall,
+                    textwrap.dedent("""\
+                    SHAP Waterfall Plot: Decomposing a Prediction into Its Components
+                    """),
+                    textwrap.dedent(f"""\
+                    The waterfall plot breaks down how each factor influences a single patient's 
+                    prediction by showing the cumulative effect of each factor. Starting from the 
+                    average prediction, it steps through each factor (e.g., age, medication history, 
+                    lab results) to show how the final prediction is reached. This helps in 
+                    understanding the main contributors to a prediction, such as a high blood 
+                    sugar level increasing the risk of diabetes.
+                    
+                    Reading: For this prediction, `{force_feature}` impacts the final prediction 
+                    value by {force_shap:.3f}.
+                    """))
+            case 'beeswarm':
+                return (shap.plots.beeswarm,
+                    textwrap.dedent("""\
+                    SHAP Beeswarm Plot: Identifying the Most Important Factors Across All Patients
+                    """),
+                    textwrap.dedent("""\
+                    The beeswarm plot highlights which factors are most important across all patients.
+                    Each dot represents a patient, with dots positioned based on the factor's impact 
+                    on the prediction (e.g., positive or negative impact on disease risk). For instance, 
+                    a cluster of red dots could show that high blood pressure consistently increases 
+                    heart disease risk. This plot helps find patterns and common trends in the data.
+                    """))
+            case 'scatter':
+                return (shap.plots.scatter,
+                    textwrap.dedent("""\
+                    SHAP Scatter Plot: Visualizing the Relationship Between a Factor and Prediction
+                    """),
+                    textwrap.dedent("""\
+                    The scatter plot shows the relationship between a specific factor (e.g., body mass index)
+                    and its SHAP value, which tells us how much it affects the model’s prediction. 
+                    By plotting multiple patients, this plot reveals how changes in a factor (like increasing
+                    BMI) can lead to higher or lower risk predictions (such as for heart disease).
+                    """))
+            case 'heatmap':
+                return (shap.plots.heatmap,
+                    "SHAP Heatmap: Understanding Factor Importance Across Multiple Patients",
+                    textwrap.dedent("""\
+                    The heatmap shows the impact of different factors for many patients, with color 
+                    intensity representing how strongly a factor influences the model's prediction. 
+                    For example, dark red may highlight that high cholesterol is a strong positive 
+                    predictor for heart disease in several patients. This plot helps you see which 
+                    factors are the most influential overall.
+                    """))
+            case 'bar':
+                mean_shap = np.abs(shap_values.values).mean(axis=0)
+                bar_shap, bar_feature = max(zip(mean_shap, features), key=lambda v: v[0])
+                return (shap.plots.bar,
+                    "SHAP Bar Plot: Ranking the Most Important Factors",
+                    textwrap.dedent(f"""\
+                    The bar plot ranks the factors by their overall importance in the model’s 
+                    predictions. Each bar represents a factor (e.g., age, smoking status, 
+                    cholesterol level) and shows how much it contributed to the model’s 
+                    decision-making process across all patients. This helps identify the key 
+                    factors driving predictions, such as high blood pressure being the most 
+                    influential predictor of heart disease.
+                    
+                    Reading: `{bar_feature}` has an absolute impact of {bar_shap:.3f}
+                    on the average final prediction value.
+                    """))

iaml/plots/target_distribution_plot.py

@@ -0,0 +1,241 @@
+"""[PLOT] Target distribution plot for descriptive statistics."""
+from __future__ import annotations
+
+import io
+import textwrap
+from typing import Any
+
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+
+from ..dataset import Dataset
+from ..plot import StatisticPlot, capture
+
+
+def _is_missing(value: Any) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, float) and pd.isna(value):
+        return True
+    return False
+
+
+def _plot_placeholder(message: str) -> None:
+    plt.figure()
+    plt.text(0.5, 0.5, message, ha='center', va='center')
+    plt.axis('off')
+
+
+def _extract_target_column(dataframe: pd.DataFrame) -> str | None:
+    if dataframe.empty:
+        return None
+    for col in ('target', 'y', 'target_all', 'y_all'):
+        if col in dataframe.columns:
+            return col
+    if len(dataframe.columns) == 1:
+        return dataframe.columns[0]
+    return None
+
+
+def _extract_value_counts(value: Any) -> dict[str, float] | None:
+    if _is_missing(value):
+        return None
+    if isinstance(value, dict):
+        if any(key in value for key in ('counts', 'bins', 'bin_edges', 'hist', 'values')):
+            return None
+        counts: dict[str, float] = {}
+        for key, count in value.items():
+            if _is_missing(count):
+                continue
+            counts[str(key)] = float(count)
+        return counts or None
+    if isinstance(value, (list, tuple, np.ndarray, pd.Series)):
+        try:
+            items = list(value)
+        except TypeError:
+            return None
+        if not items:
+            return None
+        if all(isinstance(item, (list, tuple)) and len(item) == 2 for item in items):
+            counts = {}
+            for key, count in items:
+                if _is_missing(count):
+                    continue
+                counts[str(key)] = float(count)
+            return counts or None
+    return None
+
+
+def _histogram_from_values(values: np.ndarray) -> tuple[np.ndarray, np.ndarray] | None:
+    if values.size == 0:
+        return None
+    try:
+        numeric = values.astype(float)
+    except (TypeError, ValueError):
+        return None
+    numeric = numeric[np.isfinite(numeric)]
+    if numeric.size == 0:
+        return None
+    bins = int(np.sqrt(numeric.size))
+    bins = max(5, min(20, bins))
+    counts, bin_edges = np.histogram(numeric, bins=bins)
+    return counts, bin_edges
+
+
+def _extract_hist_data(value: Any) -> tuple[np.ndarray, np.ndarray] | None:
+    if _is_missing(value):
+        return None
+    if isinstance(value, dict):
+        if 'counts' in value and ('bins' in value or 'bin_edges' in value):
+            counts = np.asarray(value['counts'])
+            bins = np.asarray(value.get('bins', value.get('bin_edges')))
+            return counts, bins
+        if 'hist' in value and ('bins' in value or 'bin_edges' in value):
+            counts = np.asarray(value['hist'])
+            bins = np.asarray(value.get('bins', value.get('bin_edges')))
+            return counts, bins
+        if 'values' in value:
+            return _histogram_from_values(np.asarray(value['values']))
+    if isinstance(value, (list, tuple, np.ndarray, pd.Series)):
+        if isinstance(value, (list, tuple)) and len(value) == 2:
+            first = np.asarray(value[0])
+            second = np.asarray(value[1])
+            if first.ndim == 1 and second.ndim == 1:
+                if first.size == second.size + 1:
+                    return second, first
+                if second.size == first.size + 1:
+                    return first, second
+                if first.size == second.size and first.size > 0:
+                    bins = np.arange(first.size + 1)
+                    return first, bins
+        return _histogram_from_values(np.asarray(value))
+    return None
+
+
+def _plot_class_counts(counts: dict[str, float], title: str) -> None:
+    plt.figure()
+    labels = list(counts.keys())
+    values = np.asarray(list(counts.values()), dtype=float)
+    x = np.arange(len(labels))
+    plt.bar(x, values, color='tab:blue')
+    plt.xticks(x, labels, rotation=30, ha='right')
+    plt.ylabel('Count')
+    plt.title(title)
+    plt.tight_layout()
+
+
+def _plot_histogram(counts: np.ndarray, bins: np.ndarray, title: str) -> None:
+    if bins.size != counts.size + 1:
+        _plot_placeholder("Invalid histogram data")
+        return
+    plt.figure()
+    widths = np.diff(bins)
+    plt.bar(bins[:-1], counts, width=widths, align='edge', edgecolor='black')
+    plt.xlabel('Target')
+    plt.ylabel('Count')
+    plt.title(title)
+    plt.tight_layout()
+
+
+class TargetDistributionPlot(StatisticPlot):
+    """[PLOT] Target Distribution Plot."""
+
+    name: str = "Target Distribution"
+    _description: str = textwrap.dedent("""\
+        Target distribution plots summarize the target values.
+        """)
+    _description_long: str = textwrap.dedent("""\
+        This plot shows the distribution of the target variable. For regression tasks,
+        it renders a histogram of the target values. For classification tasks, it shows
+        counts per class label.
+        """)
+    refs: list[dict] = []
+
+    title: str = "Target distribution"
+    description: str = textwrap.dedent("""\
+        The target distribution plot shows the distribution of the target values.
+        """)
+    group_by_feature: bool = False
+
+    def __str__(self) -> str:
+        return 'target_distribution'
+
+    @capture
+    def compute(
+        self,
+        dataframe: pd.DataFrame,
+        dataset: Dataset | None = None,
+        base_name: str | None = None,
+        **kwargs,
+    ) -> 'TargetDistributionPlot':
+        """Compute the target distribution plot."""
+        self._binary_image = io.BytesIO()
+
+        title = "Target distribution"
+        if base_name:
+            title = f"Target distribution: {base_name}"
+
+        if not dataframe.empty:
+            target_col = _extract_target_column(dataframe)
+            row = None
+            row_key = str(self)
+            if row_key in dataframe.index:
+                row = dataframe.loc[row_key]
+            elif 'value_counts' in dataframe.index:
+                row = dataframe.loc['value_counts']
+            elif 'histogram' in dataframe.index:
+                row = dataframe.loc['histogram']
+
+            if isinstance(row, pd.DataFrame):
+                row = row.iloc[0] if not row.empty else None
+
+            if row is not None and target_col is not None:
+                value = row.get(target_col)
+                counts = _extract_value_counts(value)
+                if counts:
+                    _plot_class_counts(counts, title)
+                    plt.savefig(self._binary_image, format='png')
+                    return self
+
+                hist = _extract_hist_data(value)
+                if hist is not None:
+                    counts_arr, bins = hist
+                    _plot_histogram(
+                        np.asarray(counts_arr, dtype=float),
+                        np.asarray(bins, dtype=float),
+                        title,
+                    )
+                    plt.savefig(self._binary_image, format='png')
+                    return self
+
+        if dataset is None:
+            _plot_placeholder("Target distribution not available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        if dataset.type_of_target == 'survival':
+            _plot_placeholder("Target distribution not available for survival targets")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        y_values = pd.Series(dataset.y)
+        if dataset.type_of_target == 'continuous':
+            numeric = pd.to_numeric(y_values, errors='coerce').to_numpy()
+            numeric = numeric[np.isfinite(numeric)]
+            hist = _histogram_from_values(numeric)
+            if hist is None:
+                _plot_placeholder("No numeric target values available")
+            else:
+                counts_arr, bins = hist
+                _plot_histogram(counts_arr, bins, title)
+        else:
+            counts_series = y_values.value_counts(dropna=False)
+            if counts_series.empty:
+                _plot_placeholder("No target labels available")
+            else:
+                counts = {str(key): float(val) for key, val in counts_series.items()}
+                _plot_class_counts(counts, title)
+
+        plt.savefig(self._binary_image, format='png')
+        return self