PyIAML 1.0.0__py3-none-any.whl

iaml/plots/kaplan_meier_comparison_plot.py

@@ -0,0 +1,89 @@
+"""
+[PLOT] Kaplan-Meier Model Comparison Survival Plot using sksurv
+"""
+from __future__ import annotations
+
+import textwrap
+import io
+from typing import TYPE_CHECKING
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+from sksurv.nonparametric import kaplan_meier_estimator
+from ..metric_plot import MetricPlot, capture
+from ..dataset import Dataset
+if TYPE_CHECKING:
+    from ..iaml_pipeline import IAMLPipeline
+
+
+class KaplanMeierModelComparisonPlot(MetricPlot):
+    """[PLOT] Kaplan-Meier Model Comparison Survival"""
+
+    title: str = "Kaplan-Meier Model Comparison"
+    description: str = textwrap.dedent("""
+        The Kaplan-Meier Model Comparison Plot is a diagnostic tool used to evaluate the performance of 
+        survival models by comparing predicted survival curves against the observed survival data.
+
+        This plot is particularly useful for assessing how well a model can predict the time-to-event 
+        outcome, such as time until death, disease recurrence, or failure. The observed Kaplan-Meier 
+        survival curve represents the true survival probability over time, while the model's predicted 
+        survival curves show the model's estimations.
+
+        The x-axis represents time, and the y-axis represents the survival probability. Ideally, 
+        the model-predicted survival curves should closely align with the observed Kaplan-Meier 
+        curve, indicating good model performance. Discrepancies between the two curves highlight 
+        areas where the model's predictions diverge from reality, signaling potential issues with 
+        the model's predictive ability.
+
+        Additionally, if possible, a Cox proportional hazards model is also trained to serve as 
+        a baseline. This allows for a better understanding of model performances, as the Cox model 
+        is a widely-used, interpretable model in survival analysis. By comparing more complex models 
+        to this baseline, it becomes easier to gauge the improvement (or lack thereof) in predictive 
+        accuracy.
+        """)
+
+    @capture
+    def compute( # pylint: disable=too-many-positional-arguments
+        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()
+
+        X_train, y_train = Dataset.fix_survival(X_train, y_train)
+        X, y = Dataset.fix_survival(X, y)
+
+        # Fit the Kaplan-Meier model on observed data
+        event, time = zip(*y)
+
+        # Observed data
+        time, survival_prob = kaplan_meier_estimator(event, time)
+        plt.step(time, survival_prob, where="post", label="Observed", color='blue')
+
+        # Current model
+        survival_predictions = estimator.predict_survival_function(X)
+
+        mean_survival_prob = np.mean([fn.y for fn in survival_predictions], axis=0)
+        mean_survival_time = survival_predictions[0].x
+
+        plt.step(mean_survival_time, mean_survival_prob,
+            where="post", label="Model prediction", color="green")
+
+        # Customize and save the plot
+        plt.title("Kaplan-Meier Curve vs Model Predicted Survival")
+        plt.xlabel("Time")
+        plt.ylabel("Survival Probability")
+        plt.ylim([0, 1])
+        plt.legend()
+
+        plt.savefig(self._binary_image, format='png')
+        plt.close()
+
+        return self
+
+    @classmethod
+    def suitable(cls, type_of_target: str) -> bool:
+        return type_of_target == 'survival'

iaml/plots/line_plot.py

@@ -0,0 +1,70 @@
+"""[PLOT] Line plot for descriptive statistics."""
+from __future__ import annotations
+
+import io
+import textwrap
+import pandas as pd
+import matplotlib.pyplot as plt
+
+from ..plot import StatisticPlot, capture
+
+
+def _plot_placeholder(message: str) -> None:
+    plt.figure()
+    plt.text(0.5, 0.5, message, ha='center', va='center')
+    plt.axis('off')
+
+
+class LinePlot(StatisticPlot):
+    """[PLOT] Line Plot."""
+
+    title: str = "Line plot"
+    description: str = textwrap.dedent("""\
+        The line plot compares the null count and count statistics across columns.
+        """)
+    group_by_feature: bool = False
+
+    @capture
+    def compute(self, dataframe: pd.DataFrame, **kwargs) -> 'LinePlot':
+        """Compute line plot statistics."""
+        self._binary_image = io.BytesIO()
+
+        if dataframe.empty:
+            _plot_placeholder("No statistics available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        if 'count' not in dataframe.index or 'null_count' not in dataframe.index:
+            _plot_placeholder("Count statistics not available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        columns_to_show = [
+            col for col in dataframe.columns
+            if isinstance(col, str) and col.endswith('_all')
+        ]
+        if columns_to_show:
+            labels = [col[:-4] for col in columns_to_show]
+        else:
+            columns_to_show = list(dataframe.columns)
+            labels = [str(col) for col in columns_to_show]
+
+        counts = dataframe.loc['count', columns_to_show]
+        null_counts = dataframe.loc['null_count', columns_to_show]
+        if counts.empty or null_counts.empty:
+            _plot_placeholder("Count statistics not available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        plt.figure()
+        plt.plot(labels, null_counts.values, marker='o', label='Null Count', color='red')
+        plt.plot(labels, counts.values, marker='s', label='Count', color='blue')
+        plt.title('Null Count vs Count')
+        plt.xlabel('Columns')
+        plt.ylabel('Value')
+        plt.legend()
+        plt.xticks(rotation=45)
+        plt.tight_layout()
+
+        plt.savefig(self._binary_image, format='png')
+        return self

iaml/plots/missingness_heatmap_plot.py

@@ -0,0 +1,203 @@
+"""[PLOT] Missingness heatmap 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 _plot_placeholder(message: str) -> None:
+    plt.figure()
+    plt.text(0.5, 0.5, message, ha='center', va='center')
+    plt.axis('off')
+
+
+def _missing_row_from_stats(dataframe: pd.DataFrame) -> pd.Series | None:
+    if dataframe.empty:
+        return None
+    if 'missing_rate' in dataframe.index:
+        row = dataframe.loc['missing_rate']
+    elif dataframe.shape[0] == 1:
+        row = dataframe.iloc[0]
+    else:
+        return None
+    if isinstance(row, pd.DataFrame):
+        if row.empty:
+            return None
+        row = row.iloc[0]
+    return row
+
+
+def _split_missing_column(column: Any) -> tuple[str, str]:
+    column_str = str(column)
+    if column_str.endswith('_all'):
+        return column_str[:-4], 'all'
+    if '_' in column_str:
+        base, label = column_str.rsplit('_', 1)
+        return base, label
+    return column_str, 'all'
+
+
+def _missing_frame_from_stats(
+    dataframe: pd.DataFrame,
+    dataset: Dataset | None,
+) -> pd.DataFrame | None:
+    row = _missing_row_from_stats(dataframe)
+    if row is None:
+        return None
+
+    if dataset is not None and dataset.type_of_target != 'survival':
+        columns = [
+            col for col in dataset.X.columns
+            if dataset.columns_types[col][1] not in (DataType.TEXT, DataType.SHORT_TEXT)
+        ]
+        if not columns:
+            return None
+        if dataset.type_of_target == 'continuous':
+            values = []
+            for col in columns:
+                values.append(row.get(col, np.nan))
+            return pd.DataFrame([values], index=['all'], columns=columns)
+
+        class_labels = list(pd.unique(dataset.y))
+        labels = ['all'] + [str(label) for label in class_labels]
+        data = np.full((len(labels), len(columns)), np.nan, dtype=float)
+        for col_idx, col in enumerate(columns):
+            for row_idx, label in enumerate(labels):
+                key = f"{col}_{label}"
+                data[row_idx, col_idx] = row.get(key, np.nan)
+        return pd.DataFrame(data, index=labels, columns=columns)
+
+    columns: list[str] = []
+    labels: list[str] = []
+    values: dict[tuple[str, str], float] = {}
+    for col_name, value in row.items():
+        base, label = _split_missing_column(col_name)
+        if base not in columns:
+            columns.append(base)
+        if label not in labels:
+            labels.append(label)
+        values[(label, base)] = value
+
+    if not columns or not labels:
+        return None
+
+    if 'all' in labels:
+        labels = ['all'] + [label for label in labels if label != 'all']
+
+    data = np.full((len(labels), len(columns)), np.nan, dtype=float)
+    for row_idx, label in enumerate(labels):
+        for col_idx, base in enumerate(columns):
+            data[row_idx, col_idx] = values.get((label, base), np.nan)
+    return pd.DataFrame(data, index=labels, columns=columns)
+
+
+def _missing_frame_from_dataset(dataset: Dataset) -> pd.DataFrame | None:
+    if dataset.type_of_target == 'survival':
+        return None
+
+    columns = [
+        col for col in dataset.X.columns
+        if dataset.columns_types[col][1] not in (DataType.TEXT, DataType.SHORT_TEXT)
+    ]
+    if not columns:
+        return None
+
+    frame = dataset.X[columns]
+    overall = frame.isna().mean(axis=0)
+
+    if dataset.type_of_target == 'continuous':
+        return pd.DataFrame([overall.to_numpy()], index=['all'], columns=columns)
+
+    grouped = frame.isna().groupby(dataset.y, sort=False).mean()
+    labels = list(pd.unique(dataset.y))
+    grouped = grouped.reindex(labels)
+    grouped.index = [str(label) for label in grouped.index]
+
+    overall_frame = pd.DataFrame([overall.to_numpy()], index=['all'], columns=columns)
+    return pd.concat([overall_frame, grouped])
+
+
+def _figure_size(n_cols: int, n_rows: int) -> tuple[float, float]:
+    width = float(min(14.0, max(5.0, 0.6 * n_cols + 2.5)))
+    height = float(min(10.0, max(3.5, 0.5 * n_rows + 2.0)))
+    return width, height
+
+
+class MissingnessHeatmapPlot(StatisticPlot):
+    """[PLOT] Missingness Heatmap Plot."""
+
+    name: str = "Missingness Heatmap"
+    _description: str = textwrap.dedent("""\
+        Missingness heatmaps summarize the percentage of missing values.
+        """)
+    _description_long: str = textwrap.dedent("""\
+        This plot displays a heatmap of missing rates per feature, optionally
+        broken down by class labels for classification datasets.
+        """)
+    refs: list[dict] = []
+
+    title: str = "Missingness heatmap"
+    description: str = textwrap.dedent("""\
+        The missingness heatmap shows missing value rates per feature.
+        """)
+    group_by_feature: bool = False
+
+    def __str__(self) -> str:
+        return 'missing_rate'
+
+    @capture
+    def compute(
+        self,
+        dataframe: pd.DataFrame,
+        dataset: Dataset | None = None,
+        base_name: str | None = None,
+        **kwargs,
+    ) -> 'MissingnessHeatmapPlot':
+        """Compute missingness heatmap statistics."""
+        self._binary_image = io.BytesIO()
+
+        missing_df = _missing_frame_from_stats(dataframe, dataset)
+        if missing_df is None and dataset is not None:
+            missing_df = _missing_frame_from_dataset(dataset)
+
+        if missing_df is None or missing_df.empty:
+            _plot_placeholder("Missingness statistics not available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        values = missing_df.to_numpy(dtype=float)
+        masked = np.ma.masked_invalid(values)
+        n_rows, n_cols = masked.shape
+        fig_size = _figure_size(n_cols, n_rows)
+        fig, ax = plt.subplots(figsize=fig_size)
+
+        image = ax.imshow(masked, cmap='Reds', vmin=0, vmax=1, aspect='auto')
+        plt.colorbar(image, ax=ax, fraction=0.046, pad=0.04, label='Missing rate')
+
+        ax.set_xticks(np.arange(n_cols))
+        ax.set_yticks(np.arange(n_rows))
+        ax.set_xticklabels([str(label) for label in missing_df.columns], rotation=45, ha='right')
+        ax.set_yticklabels([str(label) for label in missing_df.index])
+
+        title = "Missingness heatmap"
+        if base_name:
+            title = f"Missingness heatmap: {base_name}"
+        ax.set_title(title)
+        ax.set_xlabel('Features')
+        ax.set_ylabel('Group')
+
+        tick_size = 10 if n_cols <= 12 else 8 if n_cols <= 20 else 6
+        ax.tick_params(axis='both', which='major', labelsize=tick_size)
+
+        plt.tight_layout()
+        plt.savefig(self._binary_image, format='png')
+        return self

iaml/plots/outlier_plot.py

@@ -0,0 +1,217 @@
+"""[PLOT] Outlier 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 _plot_placeholder(message: str) -> None:
+    plt.figure()
+    plt.text(0.5, 0.5, message, ha='center', va='center')
+    plt.axis('off')
+
+
+def _outlier_row_from_stats(dataframe: pd.DataFrame, key: str) -> pd.Series | None:
+    if dataframe.empty:
+        return None
+    if key in dataframe.index:
+        row = dataframe.loc[key]
+    elif dataframe.shape[0] == 1:
+        row = dataframe.iloc[0]
+    else:
+        return None
+    if isinstance(row, pd.DataFrame):
+        if row.empty:
+            return None
+        row = row.iloc[0]
+    return row
+
+
+def _split_outlier_column(column: Any) -> tuple[str, str]:
+    column_str = str(column)
+    if column_str.endswith('_all'):
+        return column_str[:-4], 'all'
+    if '_' in column_str:
+        base, label = column_str.rsplit('_', 1)
+        return base, label
+    return column_str, 'all'
+
+
+def _outlier_frame_from_stats(
+    dataframe: pd.DataFrame,
+    dataset: Dataset | None,
+    key: str,
+) -> pd.DataFrame | None:
+    row = _outlier_row_from_stats(dataframe, key)
+    if row is None:
+        return None
+
+    if dataset is not None and dataset.type_of_target != 'survival':
+        numeric_columns = list(dataset.get_columns_names_by_type(DataType.NUMERIC))
+        if not numeric_columns:
+            return None
+        if dataset.type_of_target == 'continuous':
+            values = [row.get(col, np.nan) for col in numeric_columns]
+            return pd.DataFrame([values], index=['all'], columns=numeric_columns)
+
+        class_labels = list(pd.unique(dataset.y))
+        labels = ['all'] + [str(label) for label in class_labels]
+        data = np.full((len(labels), len(numeric_columns)), np.nan, dtype=float)
+        for col_idx, col in enumerate(numeric_columns):
+            for row_idx, label in enumerate(labels):
+                key_name = f"{col}_{label}"
+                data[row_idx, col_idx] = row.get(key_name, np.nan)
+        return pd.DataFrame(data, index=labels, columns=numeric_columns)
+
+    columns: list[str] = []
+    labels: list[str] = []
+    values: dict[tuple[str, str], float] = {}
+    for col_name, value in row.items():
+        base, label = _split_outlier_column(col_name)
+        if base not in columns:
+            columns.append(base)
+        if label not in labels:
+            labels.append(label)
+        values[(label, base)] = value
+
+    if not columns or not labels:
+        return None
+
+    if 'all' in labels:
+        labels = ['all'] + [label for label in labels if label != 'all']
+
+    data = np.full((len(labels), len(columns)), np.nan, dtype=float)
+    for row_idx, label in enumerate(labels):
+        for col_idx, base in enumerate(columns):
+            data[row_idx, col_idx] = values.get((label, base), np.nan)
+    return pd.DataFrame(data, index=labels, columns=columns)
+
+
+def _figure_size(n_cols: int) -> tuple[float, float]:
+    width = float(min(14.0, max(6.0, 0.7 * n_cols + 2.5)))
+    height = 4.5 if n_cols <= 8 else 5.5
+    return width, height
+
+
+class OutlierPlot(StatisticPlot):
+    """[PLOT] Outlier Plot."""
+
+    name: str = "Outlier Plot"
+    _description: str = textwrap.dedent("""\
+        Outlier plots show counts of outliers per column.
+        """)
+    _description_long: str = textwrap.dedent("""\
+        This plot visualizes outlier counts based on the 1.5*IQR rule for each
+        numeric column, optionally broken down by class labels.
+        """)
+    refs: list[dict] = []
+
+    title: str = "Outlier plot"
+    description: str = textwrap.dedent("""\
+        The outlier plot shows outlier counts per column using box/strip visuals.
+        """)
+    group_by_feature: bool = False
+
+    def __str__(self) -> str:
+        return 'outlier_count_iqr'
+
+    @capture
+    def compute(
+        self,
+        dataframe: pd.DataFrame,
+        dataset: Dataset | None = None,
+        base_name: str | None = None,
+        **kwargs,
+    ) -> 'OutlierPlot':
+        """Compute outlier plot statistics."""
+        self._binary_image = io.BytesIO()
+
+        outlier_key = str(self)
+        outlier_df = _outlier_frame_from_stats(dataframe, dataset, outlier_key)
+        if outlier_df is None or outlier_df.empty:
+            _plot_placeholder("Outlier statistics not available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        columns = [col for col in outlier_df.columns]
+        if not columns:
+            _plot_placeholder("Outlier statistics not available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        values_per_column: list[np.ndarray] = []
+        columns_to_plot: list[str] = []
+        for col in columns:
+            values = pd.to_numeric(outlier_df[col], errors='coerce').to_numpy(dtype=float)
+            values = values[np.isfinite(values)]
+            if values.size == 0:
+                continue
+            columns_to_plot.append(col)
+            values_per_column.append(values)
+
+        if not columns_to_plot:
+            _plot_placeholder("No numeric outlier statistics available")
+            plt.savefig(self._binary_image, format='png')
+            return self
+
+        fig, ax = plt.subplots(figsize=_figure_size(len(columns_to_plot)))
+        positions = np.arange(1, len(columns_to_plot) + 1)
+        ax.boxplot(
+            values_per_column,
+            positions=positions,
+            widths=0.55,
+            showfliers=False,
+            patch_artist=True,
+            boxprops={'facecolor': '#d9d9d9', 'edgecolor': '#555555'},
+            medianprops={'color': '#333333'},
+        )
+
+        labels = list(outlier_df.index)
+        n_labels = len(labels)
+        offsets = np.linspace(-0.18, 0.18, n_labels) if n_labels > 1 else np.array([0.0])
+        cmap = plt.get_cmap('tab10')
+        colors = cmap(np.linspace(0, 1, max(1, n_labels)))
+
+        for label_idx, label in enumerate(labels):
+            row_values = pd.to_numeric(
+                outlier_df.loc[label, columns_to_plot],
+                errors='coerce',
+            ).to_numpy(dtype=float)
+            mask = np.isfinite(row_values)
+            if not np.any(mask):
+                continue
+            x_positions = positions[mask] + offsets[label_idx]
+            y_values = row_values[mask]
+            ax.scatter(
+                x_positions,
+                y_values,
+                s=28,
+                color=colors[label_idx],
+                alpha=0.85,
+                label=str(label),
+                zorder=3,
+            )
+
+        ax.set_xticks(positions)
+        ax.set_xticklabels([str(col) for col in columns_to_plot], rotation=30, ha='right')
+        ax.set_ylabel('Outlier count')
+        title = "Outlier count (IQR)"
+        if base_name:
+            title = f"Outlier count (IQR): {base_name}"
+        ax.set_title(title)
+
+        if n_labels > 1:
+            ax.legend(title='Group', fontsize=8)
+
+        plt.tight_layout()
+        plt.savefig(self._binary_image, format='png')
+        return self