PyIAML 1.0.0__py3-none-any.whl

iaml/actionables/features_selection/act_select_k_best.py

@@ -0,0 +1,181 @@
+"""[STEP] Select K Best Features."""
+import textwrap
+
+from collections.abc import Callable
+
+import pandas as pd
+from sklearn.feature_selection import SelectKBest, chi2, f_classif
+from sklearn.feature_selection import mutual_info_classif, mutual_info_regression
+
+from ...actionable import Actionable
+from ...candidate import Candidate
+from ...data_type import DataType
+from ...dataset import Dataset
+from ...decorators.all import is_step
+
+
+@is_step('features_selection')
+class ActSelectKBest(Actionable):
+    """[STEP] Select K Best Features."""
+
+    name: str = "Select K Best Features"
+    _usage: str = "Use when you want a fast univariate top-k filter instead of ActRFE or ActSelectFromModel. Applicable to numeric features with a labeled target; for continuous targets use mutual_info. Avoid when you need multivariate interactions, stability, or chi2 with negative values."
+    _description: str = textwrap.dedent('''\
+        Select the {k} best numeric features using {score_func} scoring.''')
+    _description_long: str = textwrap.dedent('''\
+        SelectKBest ranks features based on a scoring function and keeps only
+        the top k features. This step supports chi2, f_classif, and mutual_info
+        scoring to reduce dimensionality and keep the most informative
+        predictors for the target.''')
+
+    def __init__(self):
+        self.configuration = {
+            'score_func': {
+                'description': 'Score function used to rank features.',
+                'default': 'f_classif',
+                'categorical': ['chi2', 'f_classif', 'mutual_info']
+            },
+            'k': {
+                'description': 'Number of top features to keep.',
+                'default': 10,
+                'range': [1, 1000]
+            },
+            'random_state': {
+                'description': 'Random seed used for mutual_info scoring.',
+                'default': 42
+            }
+        }
+
+        self.optimizable: bool = True
+        self.columns: list[str] = []
+        self.selected_columns: list[str] = []
+        self.columns_to_drop: list[str] = []
+        self.selector: SelectKBest | None = None
+        self._scores: dict[str, float] = {}
+
+    def _resolve_score_func(self, dataset: Dataset) -> Callable | None:
+        score_func = self.get_config('score_func')
+        if score_func == 'chi2':
+            return chi2
+        if score_func == 'f_classif':
+            return f_classif
+        if score_func == 'mutual_info':
+            random_state = self.get_config('random_state')
+            if dataset.type_of_target == 'continuous':
+                return lambda X, y: mutual_info_regression(
+                    X, y, random_state=random_state
+                )
+            return lambda X, y: mutual_info_classif(
+                X, y, random_state=random_state
+            )
+        return None
+
+    def _resolve_k(self, max_features: int) -> int:
+        k_value = self.get_config('k')
+        try:
+            k_value = int(k_value)
+        except (TypeError, ValueError):
+            return 0
+
+        if max_features <= 0:
+            return 0
+
+        return max(1, min(k_value, max_features))
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        self.selected_columns = []
+        self.columns_to_drop = []
+        self.selector = None
+        self._scores = {}
+        self.explanations = []
+
+        if not self.columns or dataset.y is None:
+            return self
+        if dataset.X[self.columns].isna().any().any():
+            return self
+
+        k_value = self._resolve_k(len(self.columns))
+        if k_value < 1:
+            return self
+
+        score_func = self._resolve_score_func(dataset)
+        if score_func is None:
+            return self
+
+        if k_value != self.get_config('k'):
+            self.configure('k', k_value)  # pylint: disable=too-many-function-args
+
+        self.selector = SelectKBest(score_func=score_func, k=k_value)
+        self.selector.fit(dataset.X[self.columns], dataset.y)
+
+        support = self.selector.get_support()
+        self.selected_columns = list(pd.Index(self.columns)[support])
+        self.columns_to_drop = list(pd.Index(self.columns)[~support])
+
+        scores = self.selector.scores_
+        if scores is not None:
+            self._scores = {
+                column: float(score) if score is not None else float('nan')
+                for column, score in zip(self.columns, scores)
+            }
+
+        if self.columns_to_drop:
+            for column in self.columns_to_drop:
+                score = self._scores.get(column)
+                if score is None or pd.isna(score):
+                    self.explanations.append(
+                        f"Dropped column **`{column}`** because it was not in "
+                        f"the top **{k_value}** features."
+                    )
+                else:
+                    self.explanations.append(
+                        f"Dropped column **`{column}`** because it was not in "
+                        f"the top **{k_value}** features (score={score:.4f})."
+                    )
+
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Drop columns that were not selected.
+
+        :param pd.DataFrame X: DataFrame to transform.
+        :return: Transformed dataset.
+        """
+        if not self.columns_to_drop:
+            return X
+
+        drop_cols = [column for column in self.columns_to_drop if column in X.columns]
+        if not drop_cols:
+            return X
+        return X.drop(columns=drop_cols)
+
+    def suitable(self, dataset: Dataset) -> bool:
+        if dataset.y is None or dataset.type_of_target is None:
+            return False
+
+        columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if not columns or dataset.X.empty:
+            return False
+        if dataset.X[columns].isna().any().any():
+            return False
+
+        if self._resolve_k(len(columns)) < 1:
+            return False
+
+        score_func = self.get_config('score_func')
+        if dataset.type_of_target == 'continuous':
+            return score_func == 'mutual_info'
+
+        if dataset.type_of_target not in [
+            'binary', 'multiclass', 'multilabel-indicator'
+        ]:
+            return False
+
+        if score_func == 'chi2':
+            return not (dataset.X[columns] < 0).any().any()
+
+        return score_func in ['f_classif', 'mutual_info', 'chi2']
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5

iaml/actionables/features_selection/act_vif_selector.py

@@ -0,0 +1,130 @@
+"""[STEP] VIF Selector"""
+import textwrap
+
+import numpy as np
+import pandas as pd
+
+from ...actionable import Actionable
+from ...candidate import Candidate
+from ...data_type import DataType
+from ...dataset import Dataset
+from ...decorators.all import is_step
+
+
+@is_step('features_selection')
+class ActVIFSelector(Actionable):
+    """[STEP] VIF Selector"""
+
+    name: str = 'VIF Selector'
+    _description: str = textwrap.dedent('''\
+        Drop numeric columns with VIF above {threshold}.''')
+    _usage: str = "Use when reducing multicollinearity among numeric predictors, as a simpler alternative to ActRFE or ActSelectFromModel. Applicable to numeric tabular data with correlated features. Avoid when features are non-numeric, too few columns, or you need target-driven selection."
+    _description_long: str = textwrap.dedent('''\
+        Variance Inflation Factor (VIF) measures multicollinearity among
+        numeric predictors. This step computes VIF from the correlation
+        matrix and removes columns whose VIF exceeds the configured
+        threshold to improve model stability.''')
+
+    def __init__(self):
+        self.configuration = {
+            'threshold': {
+                'description': 'Drop columns with VIF greater than this value.',
+                'default': 10.0,
+                'range': [1.0, 1000.0]
+            }
+        }
+        self.columns: list[str] = []
+        self.to_drop: list[str] = []
+        self.vif_scores: dict[str, float] = {}
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        self.to_drop = []
+        self.vif_scores = {}
+        self.explanations = []
+
+        if len(self.columns) < 2 or dataset.X.empty:
+            return self
+
+        self.to_drop, self.vif_scores = self.__get_columns(dataset)
+
+        threshold = self.get_config('threshold')
+        for column in self.to_drop:
+            vif_value = self.vif_scores.get(column)
+            if vif_value is None or not np.isfinite(vif_value):
+                message = (
+                    f"Dropped column **`{column}`** because its VIF was not finite."
+                )
+            else:
+                message = (
+                    f"Dropped column **`{column}`** because its VIF ({vif_value:.2f}) "
+                    f"exceeded {threshold}."
+                )
+            self.explanations.append(message)
+
+        return self
+
+    def __get_columns(self, dataset: Dataset) -> tuple[list[str], dict[str, float]]:
+        columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if len(columns) < 2:
+            return [], {}
+
+        X_numeric = dataset.X[columns]
+        if X_numeric.empty:
+            return [], {}
+
+        X_numeric = X_numeric.replace([np.inf, -np.inf], np.nan)
+        X_numeric = X_numeric.dropna(axis=0, how='any')
+        if X_numeric.shape[0] < 2:
+            return [], {}
+
+        variances = X_numeric.var(ddof=0)
+        eligible_columns = variances[variances > 0].index.tolist()
+        if len(eligible_columns) < 2:
+            return [], {}
+
+        corr = X_numeric[eligible_columns].corr()
+        if corr.empty:
+            return [], {}
+
+        inv_corr = np.linalg.pinv(corr.values)
+        vif_values = np.diag(inv_corr)
+        vif_values = np.maximum(vif_values, 1.0)
+
+        vifs = {
+            column: float(vif)
+            for column, vif in zip(eligible_columns, vif_values)
+        }
+
+        threshold = self.get_config('threshold')
+        to_drop = [
+            column for column, vif in vifs.items()
+            if not np.isfinite(vif) or vif > threshold
+        ]
+
+        return to_drop, vifs
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Drop columns with high VIF from the DataFrame.
+
+        :param pd.DataFrame X: The dataset to transform.
+        :return: Transformed dataset without high VIF columns.
+        """
+        if not self.to_drop:
+            return X
+
+        drop_cols = [column for column in self.to_drop if column in X.columns]
+        if not drop_cols:
+            return X
+
+        return X.drop(columns=drop_cols)
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5
+
+    def suitable(self, dataset: Dataset) -> bool:
+        columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if len(columns) < 2 or dataset.X.empty:
+            return False
+
+        return bool(self.__get_columns(dataset)[0])

iaml/actionables/imbalance/__init__.py

@@ -0,0 +1,10 @@
+"""Normalize and scaler Actionables"""
+from .act_random_over_sampling import ActRandomOverSampling
+from .act_smote import ActSMOTE
+from .act_borderline_smote import ActBorderlineSMOTE
+from .act_adasyn import ActADASYN
+from .act_smoteenn import ActSMOTEENN
+from .act_smote_tomek import ActSMOTETomek
+from .act_random_under_sampler import ActRandomUnderSampler
+from .act_tomek_links import ActTomekLinks
+from .act_near_miss import ActNearMiss

iaml/actionables/imbalance/act_adasyn.py

@@ -0,0 +1,150 @@
+"""[STEP] ADASYN"""
+import textwrap
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from imblearn.over_sampling import ADASYN
+
+from ...actionable import Actionable
+from ...candidate import Candidate
+from ...data_type import DataType
+from ...dataset import Dataset
+from ...decorators.all import is_step
+
+
+@is_step('imbalance')
+class ActADASYN(Actionable):
+    """[STEP] ADASYN"""
+
+    name: str = "ADASYN"
+    _description: str = textwrap.dedent('''\
+        ADASYN creates synthetic samples in hard to learn regions
+        to adaptively balance classes.''')
+    _description_long: str = textwrap.dedent('''\
+        ADASYN (Adaptive Synthetic Sampling) focuses on minority samples that are
+        difficult to learn. It generates more synthetic data where class overlap is
+        higher, improving decision boundaries while keeping runtime small.''')
+    _usage: str = "Use when numeric imbalance needs adaptive synthetic focus rather than ActSMOTE or ActRandomOverSampling. Applicable to binary or multiclass numeric features with sufficient minority samples. Avoid when categorical/text/date features exist or minority class is extremely small."
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 2008,
+            'name': 'ADASYN: Adaptive Synthetic Sampling Approach for Imbalanced Learning',
+            'authors': [
+                'Haibo He',
+                'Yang Bai',
+                'Edwardo A. Garcia',
+                'Sheng Ma'
+            ],
+            'doi': 'https://doi.org/10.1109/IJCNN.2008.4633969',
+            'publisher': 'IEEE International Joint Conference on Neural Networks'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration = {
+            'sampling_strategy': {
+                'description': 'Sampling strategy to balance classes.',
+                'default': 'auto',
+                'categorical': ['minority', 'auto']
+            },
+            'n_neighbors': {
+                'description': 'Number of nearest neighbors used to create synthetic samples.',
+                'default': 5,
+                'range': [1, 20]
+            },
+            'random_state': {
+                'description': 'Random seed used for reproducibility.',
+                'default': 42
+            }
+        }
+        self.resampler: ADASYN | None = None
+        self.categorical_columns: list[str] = []
+        self.numeric_columns: list[str] = []
+        self._effective_n_neighbors: int | None = None
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.resampler = None
+        self.categorical_columns = dataset.get_columns_names_by_type(DataType.CATEGORICAL)
+        self.numeric_columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        self._effective_n_neighbors = None
+
+        if dataset.X.empty or dataset.type_of_target not in ['binary', 'multiclass']:
+            return self
+
+        if dataset.y is None or len(dataset.y) == 0:
+            return self
+
+        unsupported = dataset.get_columns_names_by_type(
+            [DataType.TEXT, DataType.SHORT_TEXT, DataType.DATE]
+        )
+        if unsupported:
+            return self
+
+        if self.categorical_columns:
+            return self
+
+        if not self.numeric_columns:
+            return self
+
+        _, counts = np.unique(dataset.y, return_counts=True)
+        if len(counts) < 2:
+            return self
+
+        min_count = int(counts.min())
+        if min_count <= 1:
+            return self
+
+        max_neighbors = min_count - 1
+        n_neighbors = min(int(self.get_config('n_neighbors')), max_neighbors)
+        n_neighbors = max(1, n_neighbors)
+        self._effective_n_neighbors = n_neighbors
+
+        params = self.passthrough_parameters()
+        params['n_neighbors'] = n_neighbors
+
+        self.resampler = ADASYN(**params)
+        self.resampler.fit(dataset.X, dataset.y)
+        return self
+
+    def resample(self, X: pd.DataFrame, y: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame]:
+        """Apply ADASYN.
+
+        :param pd.DataFrame X: Features to resample
+        :param pd.DataFrame y: Labels to resample
+        :return: Resampled X and y
+        """
+        if self.resampler is None:
+            return X, y
+        return self.resampler.fit_resample(X, y)
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        if candidate is None or candidate.dataset.y is None:
+            return 0.0
+        y = candidate.dataset.y
+        if len(y) == 0:
+            return 0.0
+        _, counts = np.unique(y, return_counts=True)
+        if len(counts) < 2:
+            return 0.0
+        imbalance = 1.0 - (counts.min() / counts.max())
+        return float(min(1.0, max(0.0, imbalance)))
+
+    def suitable(self, dataset: Dataset) -> bool:
+        if dataset.type_of_target not in ['binary', 'multiclass']:
+            return False
+        if dataset.X.empty or dataset.y is None or len(dataset.y) == 0:
+            return False
+        if dataset.get_columns_names_by_type(DataType.CATEGORICAL):
+            return False
+        if not dataset.get_columns_names_by_type(DataType.NUMERIC):
+            return False
+        unsupported = dataset.get_columns_names_by_type(
+            [DataType.TEXT, DataType.SHORT_TEXT, DataType.DATE]
+        )
+        if unsupported:
+            return False
+        _, counts = np.unique(dataset.y, return_counts=True)
+        if len(counts) < 2:
+            return False
+        return counts.min() > 1

iaml/actionables/imbalance/act_borderline_smote.py

@@ -0,0 +1,171 @@
+"""[STEP] Borderline SMOTE"""
+import inspect
+import textwrap
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from imblearn.over_sampling import BorderlineSMOTE
+
+from ...actionable import Actionable
+from ...candidate import Candidate
+from ...data_type import DataType
+from ...dataset import Dataset
+from ...decorators.all import is_step
+
+
+@is_step('imbalance')
+class ActBorderlineSMOTE(Actionable):
+    """[STEP] Borderline SMOTE"""
+
+    name: str = "Borderline SMOTE"
+    _description: str = textwrap.dedent('''\
+        BorderlineSMOTE generates synthetic samples for minority points that
+        lie close to the decision boundary.''')
+    _description_long: str = textwrap.dedent('''\
+        BorderlineSMOTE is a SMOTE variant that targets minority samples in
+        the danger zone near the majority class. By focusing on boundary
+        samples, it can reduce noise introduced by oversampling safe regions.''')
+    _usage: str = "Use when minority points lie near the boundary and you want targeted oversampling vs ActSMOTE or ActRandomOverSampling. Applicable to numeric-only binary or multiclass datasets. Avoid when categorical/text/date features exist or the minority class is too small for neighbors."
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 2005,
+            'name': 'Borderline-SMOTE: A New Over-Sampling Method in Imbalanced Data Sets Learning',
+            'authors': [
+                'Hui Han',
+                'Wen-Yuan Wang',
+                'Bing-Huan Mao'
+            ],
+            'publisher': 'ICIC 2005, Lecture Notes in Computer Science Vol.3644 page 878--887'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration = {
+            'sampling_strategy': {
+                'description': 'Sampling strategy to balance classes.',
+                'default': 'minority',
+                'categorical': ['minority', 'auto']
+            },
+            'k_neighbors': {
+                'description': 'Number of nearest neighbors used to create synthetic samples.',
+                'default': 5,
+                'range': [1, 20]
+            },
+            'm_neighbors': {
+                'description': 'Number of neighbors used to detect borderline samples.',
+                'default': 10,
+                'range': [1, 20]
+            },
+            'kind': {
+                'description': 'Borderline variant to use when supported by imbalanced-learn.',
+                'default': 'borderline-1',
+                'categorical': ['borderline-1', 'borderline-2'],
+                'passthrough': False
+            },
+            'random_state': {
+                'description': 'Random seed used for reproducibility.',
+                'default': 42
+            }
+        }
+        self.resampler: BorderlineSMOTE | None = None
+        self.categorical_columns: list[str] = []
+        self.numeric_columns: list[str] = []
+        self._effective_k_neighbors: int | None = None
+        self._effective_m_neighbors: int | None = None
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.resampler = None
+        self.categorical_columns = dataset.get_columns_names_by_type(DataType.CATEGORICAL)
+        self.numeric_columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        self._effective_k_neighbors = None
+        self._effective_m_neighbors = None
+
+        if dataset.X.empty or dataset.type_of_target not in ['binary', 'multiclass']:
+            return self
+
+        if dataset.y is None or len(dataset.y) == 0:
+            return self
+
+        unsupported = dataset.get_columns_names_by_type(
+            [DataType.TEXT, DataType.SHORT_TEXT, DataType.DATE]
+        )
+        if unsupported:
+            return self
+
+        if self.categorical_columns:
+            return self
+
+        if not self.numeric_columns:
+            return self
+
+        _, counts = np.unique(dataset.y, return_counts=True)
+        if len(counts) < 2:
+            return self
+
+        min_count = int(counts.min())
+        if min_count <= 1:
+            return self
+
+        max_k = min_count - 1
+        k_neighbors = min(int(self.get_config('k_neighbors')), max_k)
+        k_neighbors = max(1, k_neighbors)
+        self._effective_k_neighbors = k_neighbors
+
+        total_count = int(len(dataset.y))
+        max_m = max(1, total_count - 1)
+        m_neighbors = min(int(self.get_config('m_neighbors')), max_m)
+        m_neighbors = max(1, m_neighbors)
+        self._effective_m_neighbors = m_neighbors
+
+        params = self.passthrough_parameters()
+        params['k_neighbors'] = k_neighbors
+        params['m_neighbors'] = m_neighbors
+        if 'kind' in inspect.signature(BorderlineSMOTE).parameters:
+            params['kind'] = self.get_config('kind')
+
+        self.resampler = BorderlineSMOTE(**params)
+        self.resampler.fit(dataset.X, dataset.y)
+        return self
+
+    def resample(self, X: pd.DataFrame, y: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame]:
+        """Apply Borderline SMOTE.
+
+        :param pd.DataFrame X: Features to resample
+        :param pd.DataFrame y: Labels to resample
+        :return: Resampled X and y
+        """
+        if self.resampler is None:
+            return X, y
+        return self.resampler.fit_resample(X, y)
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        if candidate is None or candidate.dataset.y is None:
+            return 0.0
+        y = candidate.dataset.y
+        if len(y) == 0:
+            return 0.0
+        _, counts = np.unique(y, return_counts=True)
+        if len(counts) < 2:
+            return 0.0
+        imbalance = 1.0 - (counts.min() / counts.max())
+        return float(min(1.0, max(0.0, imbalance)))
+
+    def suitable(self, dataset: Dataset) -> bool:
+        if dataset.type_of_target not in ['binary', 'multiclass']:
+            return False
+        if dataset.X.empty or dataset.y is None or len(dataset.y) == 0:
+            return False
+        if dataset.get_columns_names_by_type(DataType.CATEGORICAL):
+            return False
+        if not dataset.get_columns_names_by_type(DataType.NUMERIC):
+            return False
+        unsupported = dataset.get_columns_names_by_type(
+            [DataType.TEXT, DataType.SHORT_TEXT, DataType.DATE]
+        )
+        if unsupported:
+            return False
+        _, counts = np.unique(dataset.y, return_counts=True)
+        if len(counts) < 2:
+            return False
+        return counts.min() > 1