PyIAML 1.0.0__py3-none-any.whl

iaml/optimizers/random_optimizer.py

@@ -0,0 +1,101 @@
+
+"""
+Base class of IAML Optimizer. Optimizer receive a pool of Candidates, 
+optimize parameters and return a new pool of candidate
+"""
+from copy import deepcopy
+import random
+import time
+from ..candidate import Candidate
+from .optimizer import Optimizer
+from ..step import Step
+from ..logger import Logger
+
+class RandomOptimizer(Optimizer):
+    def __init__(self, duration:int=None, max_iterations=50):
+        """
+        Initialize the Random Search Optimizer.
+        :param candidates: List of Candidate objects to optimize.
+        :param max_iterations: Number of random samples to evaluate.
+        :param patience: Number of iterations without improvement before stopping.
+        """
+        self.max_iterations = max_iterations
+        self.current_iteration = 0
+        self.initial_modifier:float = 5
+        self.max_candidates = 40
+        self.first_candidates = None
+        
+    
+    def _randomize_hyperparameters(self, candidate):
+        """Randomly modifies the hyperparameters of a given candidate."""
+        for _, step in candidate.pipeline.steps:
+            for key, config in step.configuration.items():
+                # Get random values
+                
+                if type(config['value']) in [int, float]: # Numeric value ? Let's apply multiplier
+                    is_int = isinstance(config['value'], int)
+                    
+                    new_value = None
+                    if 'range' in config: # Random in range
+                        new_value = random.uniform(*config['range'])
+                    else: # Strong multiplier -> kind of random
+                        # Randomly choose a positive or negative editing
+                        if bool(random.getrandbits(1)):
+                            # Negative -> Multiply value by something between 0.01 and 1
+                            change_rate = random.uniform(0.01, 1)
+                            new_value = config['value']*change_rate 
+                        else:
+                            # Positive -> Multiply value by something between 1 
+                            # and the max modificator in configuration 
+                            change_rate = random.uniform(1, self.initial_modifier)
+                            new_value = config['value']*change_rate
+                    
+                    # Value was a int ? Round it to keep it int 
+                    if is_int: 
+                        new_value = round(new_value)
+                    
+                    if not self.__valide_config(config, new_value): 
+                        # Cancel is the new value is not correct.
+                        new_value = config['value']
+                
+                # Categorical value, choose randomly one of them
+                elif 'categorical' in config.keys():
+                    new_value = random.choice(config['categorical'])
+                elif isinstance(config['value'], bool): 
+                    # Bool value, choose randomly beetwen True and False
+                    new_value = random.choice([True, False])
+                else: # Other value ? Just keep it
+                    new_value = config['value']
+                
+                step.configure(key, new_value)
+                
+        return candidate
+    
+    def run(self, candidates):
+        """
+        Perform a single iteration of random search optimization.
+        :param evaluate_fn: Function that takes a Candidate object and returns a performance score.
+        """
+        candidates = candidates[0:self.max_candidates//2]
+        new_candidates = []
+        for candidate in candidates:
+            new_candidates.append(self._randomize_hyperparameters(deepcopy(candidate)))
+        
+        self.current_iteration += 1
+        return candidates + new_candidates
+    
+    @property
+    def finished(self) -> bool:
+        """
+        Does optimisation is finished ?
+
+        Returns:
+            bool: finished ?
+        """
+        return self.current_iteration >= self.max_iterations
+    
+    # Does the configuration is valid or not ?
+    def __valide_config(self, config:dict, value:any) -> bool:
+        if 'range' not in config.keys():
+            return True
+        return config['range'][0] <= value <= config['range'][1]

iaml/plot.py

@@ -0,0 +1,138 @@
+"""[PLOT] Parent of all others Plot, implement the default behavior"""
+from __future__ import annotations
+
+import base64
+from functools import wraps
+from typing import Any, TYPE_CHECKING
+
+import io
+import matplotlib.pyplot as plt
+import pandas as pd
+
+if TYPE_CHECKING:
+    from .iaml_pipeline import IAMLPipeline
+
+
+def capture(func) -> Any:
+    """A decorator to capture a matplotlib plot into a BytesIO object and return it
+    as binary data instead of showing it.
+    
+    :return: binary plot data.
+    """
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        ret = func(*args, **kwargs)
+        plt.close()
+        return ret
+
+    return wrapper
+
+
+class Plot:
+    """[PLOT] Parent of all others Plot, implement the default behavior"""
+
+    title: str = "Here is the plot title"
+    """Plot title"""
+
+    description: str = "Here is an explanation of how this plot work"
+    """Plot description"""
+
+    def __init__(self, *_):
+        self._binary_image: io.BytesIO = None
+        """The generated plot image"""
+
+    @property
+    def image(self) -> bytes:
+        """Get binary representation of the plot image
+
+        :raise AttributeError: Plot must be computed before.
+        :return: The image bytes.
+        """
+        if self._binary_image is not None:
+            return self._binary_image.getvalue()
+
+        raise AttributeError("Plot must be computed before")
+
+    @property
+    def b64_image(self) -> str:
+        """Get b64 representation of the plot image
+        
+        :return: b64 string image.
+        """
+        return base64.b64encode(self.image).decode()
+
+    def compute(
+        self,
+        estimator: IAMLPipeline,
+        X: pd.DataFrame,
+        y: pd.Series,
+        **kwargs) -> None:
+        """Compute plot given X, y. 
+        Must be overloaded by children classes
+        
+        :param IAMLPipeline estimator: The pipeline we compute the plot on.
+        :param pd.DataFrame X: The dataset we wanna compute plot on.
+        :param pd.Series y: The dataset target we wanna compute plot on.
+        :param optional \\**kwargs: Additional parameters for plotting.
+        """
+        raise NotImplementedError('Subclass must implement abstract method')
+
+    @classmethod
+    def suitable(cls, type_of_target: str) -> bool:  # pylint: disable=unused-argument
+        """
+        Evaluates whether the plot is relevant to the type of target to
+        predict.
+
+        :param str type_of_target: Type of target to predict.
+        :return: Whether the plot is relevant.
+        """
+        return False
+
+    def to_json(self, data_format: str='binary') -> dict[str, Any]:
+        """Convert plot into json with name, description and b64 image
+        
+        :param str data_format: Type of data we want. Can be 'binary' or 'b64'.
+        :raise AttributeError: Invalid data format.
+        :return: A dictonnary containing plot informations and data.
+        """
+        match data_format:
+            case 'binary':
+                data = self.image
+            case 'b64':
+                data = self.b64_image
+            case _:
+                raise AttributeError('Invalid data format')
+
+        return {'title': self.title,
+            'description': self.description,
+            'image': data}
+
+    def to_markdown(self) -> str:
+        """Return plot as markdown format
+        
+        :return: Markdown formatted plot.
+        """
+        return "\n\n".join([
+            f"# {self.title}",
+            self.description,
+            f"![{self.title}](data:image/png;base64,{self.b64_image})"
+        ])
+
+
+class StatisticPlot(Plot):
+    """Base class for descriptive statistics plots."""
+
+    enabled: bool = True
+    """Whether this plot should be considered for rendering."""
+
+    group_by_feature: bool = False
+    """Whether to build one plot per feature column."""
+
+    def compute(self, dataframe: pd.DataFrame, **kwargs) -> 'StatisticPlot':
+        """Compute plot given a descriptive statistics dataframe.
+
+        :param pd.DataFrame dataframe: The descriptive statistics dataframe.
+        :param optional \\**kwargs: Additional parameters for plotting.
+        :return: A StatisticPlot object.
+        """
+        raise NotImplementedError('Subclass must implement abstract method')

iaml/plots/__init__.py

@@ -0,0 +1,32 @@
+"""All plots"""
+
+# Classifier
+from .class_prediction_error_plot import ClassPredictionErrorPlot
+from .classification_report_plot import ClassificationReportPlot
+from .confusion_matrix_plot import ConfusionMatrixPlot
+from .rocauc_plot import ROCAUCPlot
+from .precision_recall_curve_plot import PrecisionRecallCurvePlot
+
+# Regressor
+from .residual_plot import ResidualsPlot
+from .prediction_error_plot import PredictionErrorPlot
+
+# Survival
+from .kaplan_meier_comparison_plot import KaplanMeierModelComparisonPlot
+from .cumulative_hazard_plot import CumulativeHazardModelComparisonPlot
+from .roc_dynamique_curve_plot import ROCDynamiqueCurvePlot
+from .shap_plot import ShapPlot
+
+# Descriptive statistics
+from .bar_plot import BarPlot
+from .line_plot import LinePlot
+from .histogram_plot import HistogramPlot
+from .box_plot import BoxPlot
+from .violin_plot import ViolinPlot
+from .density_plot import DensityPlot
+from .qq_plot import QQPlot
+from .correlation_heatmap_plot import CorrelationHeatmapPlot
+from .missingness_heatmap_plot import MissingnessHeatmapPlot
+from .pair_plot import PairPlot
+from .target_distribution_plot import TargetDistributionPlot
+from .outlier_plot import OutlierPlot

iaml/plots/bar_plot.py

@@ -0,0 +1,141 @@
+"""[PLOT] Bar plot for descriptive statistics."""
+from __future__ import annotations
+
+import io
+import textwrap
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+
+from ..plot import StatisticPlot, capture
+
+
+def _is_missing(value: object) -> bool:
+    if value is None:
+        return True
+    if isinstance(value, float) and pd.isna(value):
+        return True
+    return False
+
+
+def _infer_base_name(columns: list[str]) -> str:
+    for col in columns:
+        if isinstance(col, str) and col.endswith('_all'):
+            return col[:-4]
+    first = columns[0] if columns else ''
+    first_str = str(first)
+    return first_str.rsplit('_', 1)[0] if '_' in first_str else first_str
+
+
+def _column_label(column: str, base_name: str | None) -> str:
+    column_str = str(column)
+    base_name_str = str(base_name) if base_name is not None else None
+    if base_name_str:
+        if column_str == base_name_str:
+            return 'all'
+        prefix = f"{base_name_str}_"
+        if column_str.startswith(prefix):
+            return column_str[len(prefix):]
+    if column_str.endswith('_all'):
+        return 'all'
+    return column_str.rsplit('_', 1)[-1] if '_' in column_str else 'all'
+
+
+def _plot_placeholder(message: str) -> None:
+    plt.figure()
+    plt.text(0.5, 0.5, message, ha='center', va='center')
+    plt.axis('off')
+
+
+class BarPlot(StatisticPlot):
+    """[PLOT] Bar Plot."""
+
+    title: str = "Bar plot"
+    description: str = textwrap.dedent("""\
+        The bar plot shows descriptive statistics for categorical or numerical columns.
+        Categorical plots show value counts per class, while numerical plots show metrics
+        such as mean or variance per class.
+        """)
+    group_by_feature: bool = True
+
+    @capture
+    def compute(
+        self,
+        dataframe: pd.DataFrame,
+        base_name: str | None = None,
+        **kwargs) -> 'BarPlot':
+        """Compute bar plot statistics."""
+        self._binary_image = io.BytesIO()
+
+        if dataframe.empty:
+            _plot_placeholder("No statistics available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        base_name = base_name or _infer_base_name(list(dataframe.columns))
+
+        if 'value_counts' in dataframe.index and dataframe.loc['value_counts'].notna().any():
+            categories = []
+            seen = set()
+            for col in dataframe.columns:
+                values = dataframe.at['value_counts', col]
+                if _is_missing(values):
+                    continue
+                for cat, _ in values:
+                    if cat not in seen:
+                        seen.add(cat)
+                        categories.append(cat)
+
+            if not categories:
+                _plot_placeholder("No categorical statistics available")
+                plt.savefig(self._binary_image, format='png')
+                return self
+
+            labels = [_column_label(col, base_name) for col in dataframe.columns]
+            data = {cat: [] for cat in categories}
+            for col in dataframe.columns:
+                values = dataframe.at['value_counts', col]
+                value_dict = dict(values) if not _is_missing(values) else {}
+                for cat in categories:
+                    data[cat].append(value_dict.get(cat, 0))
+            df = pd.DataFrame(data, index=labels)
+
+            plt.figure()
+            x = np.arange(len(df.index))
+            width = min(0.8 / max(len(df.columns), 1), 0.2)
+            for i, category in enumerate(df.columns):
+                offset = (i - (len(df.columns) - 1) / 2) * width
+                plt.bar(x + offset, df[category], width, label=category)
+            plt.xticks(x, labels)
+            plt.legend()
+            plt.ylabel('Count')
+            plt.title(f'[CAT] {base_name} Statistics')
+            plt.tight_layout()
+        elif 'mean' in dataframe.index and dataframe.loc['mean'].notna().any():
+            numeric_df = dataframe.copy()
+            for row in ['mode', 'value_counts', 'null_count', 'count']:
+                if row in numeric_df.index:
+                    numeric_df = numeric_df.drop(index=row)
+            numeric_df = numeric_df.dropna(how='all')
+            if numeric_df.empty:
+                _plot_placeholder("No numeric statistics available")
+                plt.savefig(self._binary_image, format='png')
+                return self
+
+            labels = [_column_label(col, base_name) for col in numeric_df.columns]
+            x = np.arange(len(numeric_df.index))
+            width = min(0.8 / max(len(numeric_df.columns), 1), 0.25)
+            plt.figure()
+            for i, col in enumerate(numeric_df.columns):
+                offset = (i - (len(numeric_df.columns) - 1) / 2) * width
+                plt.bar(x + offset, numeric_df[col], width, label=labels[i])
+            plt.xticks(x, numeric_df.index, rotation=45, ha='right')
+            plt.legend()
+            plt.ylabel('Value')
+            plt.title(f'[NUM] {base_name} Statistics')
+            plt.tight_layout()
+        else:
+            _plot_placeholder("No statistics available for bar plot")
+
+        plt.savefig(self._binary_image, format='png')
+        return self

iaml/plots/box_plot.py

@@ -0,0 +1,166 @@
+"""[PLOT] Box 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 ..data_type import DataType
+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 _infer_base_name(columns: list[str]) -> str:
+    for col in columns:
+        if isinstance(col, str) and col.endswith('_all'):
+            return col[:-4]
+    first = columns[0] if columns else ''
+    first_str = str(first)
+    return first_str.rsplit('_', 1)[0] if '_' in first_str else first_str
+
+
+def _column_label(column: str, base_name: str | None) -> str:
+    column_str = str(column)
+    base_name_str = str(base_name) if base_name is not None else None
+    if base_name_str:
+        if column_str == base_name_str:
+            return 'all'
+        prefix = f"{base_name_str}_"
+        if column_str.startswith(prefix):
+            return column_str[len(prefix):]
+    if column_str.endswith('_all'):
+        return 'all'
+    return column_str.rsplit('_', 1)[-1] if '_' in column_str else column_str
+
+
+def _base_from_column(column: str) -> str:
+    column_str = str(column)
+    if column_str.endswith('_all'):
+        return column_str[:-4]
+    return column_str.rsplit('_', 1)[0] if '_' in column_str else column_str
+
+
+def _plot_placeholder(message: str) -> None:
+    plt.figure()
+    plt.text(0.5, 0.5, message, ha='center', va='center')
+    plt.axis('off')
+
+
+def _extract_box_stats(dataframe: pd.DataFrame, column: str) -> dict[str, float] | None:
+    required_rows = {
+        'min': 'whislo',
+        'max': 'whishi',
+        'quantile_0.25': 'q1',
+        'quantile_0.5': 'med',
+        'quantile_0.75': 'q3',
+    }
+    stats: dict[str, float] = {}
+    for row, key in required_rows.items():
+        if row not in dataframe.index:
+            return None
+        value = dataframe.at[row, column]
+        if _is_missing(value):
+            return None
+        try:
+            value = float(value)
+        except (TypeError, ValueError):
+            return None
+        if not np.isfinite(value):
+            return None
+        stats[key] = value
+    stats['fliers'] = []
+    return stats
+
+
+class BoxPlot(StatisticPlot):
+    """[PLOT] Box Plot."""
+
+    name: str = "Box Plot"
+    _description: str = textwrap.dedent("""\
+        Box plots summarize numeric distributions per class.
+        """)
+    _description_long: str = textwrap.dedent("""\
+        Box plots visualize min, quartiles, and max values for numeric columns
+        per class, using precomputed descriptive statistics.
+        """)
+    refs: list[dict] = []
+
+    title: str = "Box plot"
+    description: str = textwrap.dedent("""\
+        The box plot shows numerical distributions per class.
+        """)
+    group_by_feature: bool = True
+
+    def __str__(self) -> str:
+        return 'boxplot'
+
+    @capture
+    def compute(
+        self,
+        dataframe: pd.DataFrame,
+        base_name: str | None = None,
+        dataset: Dataset | None = None,
+        **kwargs) -> 'BoxPlot':
+        """Compute box plot statistics."""
+        self._binary_image = io.BytesIO()
+
+        if dataframe.empty:
+            _plot_placeholder("No statistics available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        base_name = base_name or _infer_base_name(list(dataframe.columns))
+
+        if dataset is not None:
+            numeric_columns = set(dataset.get_columns_names_by_type(DataType.NUMERIC))
+            if base_name in numeric_columns:
+                columns_to_show = [
+                    col for col in dataframe.columns
+                    if _base_from_column(col) == base_name
+                ]
+            else:
+                columns_to_show = [
+                    col for col in dataframe.columns
+                    if _base_from_column(col) in numeric_columns
+                ]
+        else:
+            columns_to_show = list(dataframe.columns)
+
+        if not columns_to_show:
+            _plot_placeholder("No numeric statistics available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        entries: list[dict[str, Any]] = []
+        for col in columns_to_show:
+            stats = _extract_box_stats(dataframe, col)
+            if stats is None:
+                continue
+            stats['label'] = _column_label(col, base_name)
+            entries.append(stats)
+
+        if not entries:
+            _plot_placeholder("No box plot statistics available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        plt.figure(figsize=(max(4.0, 0.9 * len(entries)), 4.0))
+        plt.bxp(entries, showfliers=False)
+        plt.ylabel('Value')
+        if base_name:
+            plt.title(f"Box plot: {base_name}")
+        plt.tight_layout()
+        plt.savefig(self._binary_image, format='png')
+        return self

iaml/plots/class_prediction_error_plot.py

@@ -0,0 +1,37 @@
+"""[PLOT] Class Prediction Error Plot"""
+import textwrap
+
+from yellowbrick.classifier import ClassPredictionError
+
+from ..metric_plot import MetricPlot, yellowbrick_plot
+
+
+@yellowbrick_plot(ClassPredictionError)
+class ClassPredictionErrorPlot(MetricPlot):
+    """[PLOT] Class Prediction Error Plot"""
+
+    title: str = "Prediction Error Plot"
+    description: str = textwrap.dedent("""
+        The Class Prediction Error is a visualization that helps understand how well a machine 
+        learning model is performing in predicting medical conditions or diagnoses. It shows 
+        both the correct predictions made by the model and the mistakes it makes for each condition.
+
+        For example, imagine you have a model that’s trained to identify different diseases 
+        from patient data, such as predicting whether someone has diabetes, hypertension, 
+        or is healthy. The Class Prediction Error plot would show, for each of these conditions, 
+        how many times the model correctly identified the disease and how many times it made a 
+        wrong prediction.
+
+        For instance, if the model predicts "diabetes" for a patient who actually has "hypertension," 
+        the plot will highlight this error. Similarly, it will also show how often the model 
+        correctly identifies "healthy" patients versus when it mistakenly predicts they have 
+        a disease.
+
+        This visualization is especially helpful for doctors and data scientists because it clearly 
+        shows where the model is making errors, making it easier to improve its accuracy, which is 
+        critical in healthcare where correct predictions can have a big impact on patient outcomes.
+        """)
+
+    @classmethod
+    def suitable(cls, type_of_target: str) -> bool:
+        return type_of_target in ['binary', 'multiclass', 'multilabel-indicator']

iaml/plots/classification_report_plot.py

@@ -0,0 +1,35 @@
+"""[PLOT] Classification Report Plot"""
+import textwrap
+
+from yellowbrick.classifier import ClassificationReport
+
+from ..metric_plot import MetricPlot, yellowbrick_plot
+
+
+@yellowbrick_plot(ClassificationReport)
+class ClassificationReportPlot(MetricPlot):
+    """[PLOT] Classification Report Plot"""
+
+    title: str = "Classification report"
+    description: str = textwrap.dedent("""
+        The Classification Report is a visual tool to evaluate the performance of a machine learning model 
+        on classification tasks, such as diagnosing medical conditions. This plot provides key metrics for 
+        each class (like diseases or health conditions) that the model is trained to identify.
+
+        It includes metrics such as precision, recall, F1-score, and support for each class. These metrics 
+        are essential to understanding how well the model is identifying true positives (correct diagnoses), 
+        minimizing false positives (incorrect diagnoses), and balancing between precision and recall.
+
+        For example, if you have a model classifying conditions like 'healthy', 'diabetes', and 'hypertension', 
+        the Classification Report plot will show you the precision (how many of the predicted conditions were correct), 
+        recall (how many actual conditions were correctly identified), and the F1-score (the harmonic mean of precision 
+        and recall). This is especially important in healthcare to ensure the model provides balanced and accurate results 
+        across all classes, improving both diagnosis and patient outcomes.
+
+        Doctors and data scientists use this visualization to easily compare the model's performance on different conditions, 
+        aiding in model refinement and ensuring robust diagnostic predictions.
+        """)
+
+    @classmethod
+    def suitable(cls, type_of_target: str) -> bool:
+        return type_of_target in ['binary', 'multiclass', 'multilabel-indicator']

iaml/plots/confusion_matrix_plot.py

@@ -0,0 +1,34 @@
+"""[PLOT] Confusion Matrix Plot"""
+import textwrap
+
+from yellowbrick.classifier import ConfusionMatrix
+
+from ..metric_plot import MetricPlot, yellowbrick_plot
+
+
+@yellowbrick_plot(ConfusionMatrix)
+class ConfusionMatrixPlot(MetricPlot):
+    """[PLOT] Confusion Matrix Plot"""
+
+    title: str = "Confusion Matrix"
+    description: str = textwrap.dedent("""
+        The Confusion Matrix is a powerful visualization tool used to assess how well a classification model 
+        is performing, particularly in identifying different medical conditions or diagnostic categories. 
+        It provides a clear breakdown of true positive, false positive, true negative, and false negative rates.
+
+        For example, in a healthcare setting, if a model is trained to classify whether a patient has 'diabetes', 
+        'hypertension', or is 'healthy', the Confusion Matrix will show how many times the model made correct predictions 
+        (true positives and true negatives) and where it made mistakes (false positives and false negatives).
+
+        Each row in the matrix represents the actual condition of the patient, and each column represents the predicted 
+        condition. This makes it easy to spot patterns in the model's predictions, such as whether it tends to misclassify 
+        one condition as another.
+
+        Doctors and data scientists rely on this plot to understand not only how often the model is right but also the 
+        types of errors it makes. This information is crucial in healthcare, where reducing misdiagnoses can significantly 
+        improve patient outcomes.
+        """)
+
+    @classmethod
+    def suitable(cls, type_of_target: str) -> bool:
+        return type_of_target in ['binary', 'multiclass', 'multilabel-indicator']