PyIAML 1.0.0__py3-none-any.whl

iaml/actionables/imbalance/act_near_miss.py

@@ -0,0 +1,158 @@
+"""[STEP] Near Miss"""
+import inspect
+import textwrap
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from imblearn.under_sampling import NearMiss
+
+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 ActNearMiss(Actionable):
+    """[STEP] Near Miss"""
+
+    name: str = "Near Miss"
+    _description: str = textwrap.dedent('''\
+        NearMiss under-samples by keeping majority samples
+        that are closest to the minority class.''')
+    _description_long: str = textwrap.dedent('''\
+        NearMiss reduces class imbalance by selecting majority samples near
+        the minority class. Different versions use nearest-neighbor distances
+        to keep samples that are harder to separate from the minority class.''')
+    _usage: str = "Use when you want distance-based under-sampling on numeric data; compare ActRandomUnderSampler or ActSMOTE. Applicable to imbalanced binary or multiclass numeric datasets. Avoid when you have categorical/text/date features or need to retain most majority samples."
+    refs: list[dict[str, Any]] = []
+
+    def __init__(self):
+        self.configuration = {
+            'sampling_strategy': {
+                'description': 'Sampling strategy to reduce the majority class.',
+                'default': 'auto',
+                'categorical': ['auto', 'majority']
+            },
+            'version': {
+                'description': 'NearMiss version to use (1, 2, or 3).',
+                'default': 1,
+                'categorical': [1, 2, 3]
+            },
+            'n_neighbors': {
+                'description': 'Number of minority neighbors used to compute distances.',
+                'default': 3,
+                'range': [1, 20]
+            },
+            'n_neighbors_ver3': {
+                'description': 'Number of majority neighbors kept per minority sample for version 3.',
+                'default': 3,
+                'range': [1, 20]
+            }
+        }
+        self.resampler: NearMiss | None = None
+        self.categorical_columns: list[str] = []
+        self.numeric_columns: list[str] = []
+        self.imbalance_ratio: float = 0.0
+        self._effective_n_neighbors: int | None = None
+        self._effective_n_neighbors_ver3: 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.imbalance_ratio = 0.0
+        self._effective_n_neighbors = None
+        self._effective_n_neighbors_ver3 = 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
+
+        max_count = int(counts.max())
+        min_count = int(counts.min())
+        if max_count <= min_count or min_count <= 0:
+            return self
+
+        self.imbalance_ratio = 1.0 - (min_count / max_count)
+
+        n_neighbors = min(int(self.get_config('n_neighbors')), min_count)
+        n_neighbors = max(1, n_neighbors)
+        self._effective_n_neighbors = n_neighbors
+
+        n_neighbors_ver3 = min(int(self.get_config('n_neighbors_ver3')), max_count)
+        n_neighbors_ver3 = max(1, n_neighbors_ver3)
+        self._effective_n_neighbors_ver3 = n_neighbors_ver3
+
+        params = self.passthrough_parameters()
+        params['n_neighbors'] = n_neighbors
+        params['n_neighbors_ver3'] = n_neighbors_ver3
+
+        sig_params = inspect.signature(NearMiss).parameters
+        params = {key: value for key, value in params.items() if key in sig_params}
+
+        self.resampler = NearMiss(**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 NearMiss.
+
+        :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.max() > counts.min()

iaml/actionables/imbalance/act_random_over_sampling.py

@@ -0,0 +1,60 @@
+"""[STEP] Random Over Sampling"""
+import textwrap
+from typing import Any
+from imblearn.over_sampling import RandomOverSampler
+import pandas as pd
+from ...actionable import Actionable
+from ...dataset import Dataset
+from ...candidate import Candidate
+from ...decorators.all import is_step
+
+
+@is_step('imbalance')
+class ActRandomOverSampling(Actionable):
+    """[STEP] Random Over Sampling"""
+
+    name: str = "Random Over Sampling"
+    _description: str = textwrap.dedent('''\
+        RandomOverSampler is a tool that helps balance data by copying
+        and pasting samples from minority groups.''')
+    _description_long: str = textwrap.dedent('''\
+        RandomOverSampler is a technique used to handle imbalanced datasets.
+        It works by randomly copying and pasting samples from the minority class
+        (the group with fewer samples) until it has the same number of samples as the majority class.
+        This helps ensure that all classes are represented equally in the dataset.''')
+    _usage: str = "Use when you need a simple baseline to boost rare classes without synthesis; compare with ActSMOTE or ActADASYN. Applicable to imbalanced binary or multiclass classification tables. Avoid when oversampling risks overfitting or duplicates distort signal."
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 2012,
+            'name': 'Training and assessing classification rules with imbalanced data',
+            'authors': [
+                'Giovanna Menardi',
+                'Nicola Torelli'
+            ],
+            'doi': 'https://doi.org/10.1007/s10618-012-0295-5',
+            'publisher': 'Data Mining and Knowledge Discovery Vol.28 page 92--122'
+        }
+    ]
+
+    def __init__(self):
+        self.resampler: RandomOverSampler = None
+
+    def fit(self, dataset: Dataset): # pylint: disable=unused-argument
+        self.resampler = RandomOverSampler(sampling_strategy='minority')
+        self.resampler.fit(dataset.X, dataset.y)
+        return self
+
+    def resample(self, X: pd.DataFrame, y: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame]:
+        """Apply Random Over Sampling
+
+        :param pd.DataFrame X: Features to resample
+        :param pd.DataFrame y: Labels to resample
+        :return: Resampled X and y
+        """
+        return self.resampler.fit_resample(X, y)
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 1
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return dataset.type_of_target in ['binary', 'multiclass']

iaml/actionables/imbalance/act_random_under_sampler.py

@@ -0,0 +1,135 @@
+"""[STEP] Random Under Sampling"""
+import inspect
+import textwrap
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from imblearn.under_sampling import RandomUnderSampler
+
+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 ActRandomUnderSampler(Actionable):
+    """[STEP] Random Under Sampling"""
+
+    name: str = "Random Under Sampling"
+    _description: str = textwrap.dedent('''\
+        RandomUnderSampler balances data by randomly removing
+        samples from the majority class.''')
+    _description_long: str = textwrap.dedent('''\
+        RandomUnderSampler reduces class imbalance by randomly dropping
+        samples from the majority class until class sizes are closer.
+        It is simple, fast, and keeps the original minority samples intact.''')
+    _usage: str = "Use when fast random majority downsampling is acceptable; compare ActNearMiss for guided removal. Applicable to binary or multiclass tabular data with a clear majority class. Avoid when minority data is scarce or information loss hurts; consider ActRandomOverSampling."
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 2012,
+            'name': 'Training and assessing classification rules with imbalanced data',
+            'authors': [
+                'Giovanna Menardi',
+                'Nicola Torelli'
+            ],
+            'doi': 'https://doi.org/10.1007/s10618-012-0295-5',
+            'publisher': 'Data Mining and Knowledge Discovery Vol.28 page 92--122'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration = {
+            'sampling_strategy': {
+                'description': 'Sampling strategy to reduce the majority class.',
+                'default': 'auto',
+                'categorical': ['auto', 'majority']
+            },
+            'random_state': {
+                'description': 'Random seed used for reproducibility.',
+                'default': 42
+            },
+            'replacement': {
+                'description': 'Sample with replacement when under-sampling.',
+                'default': False,
+                'categorical': [True, False]
+            }
+        }
+        self.resampler: RandomUnderSampler | None = None
+        self.feature_columns: list[str] = []
+        self.imbalance_ratio: float = 0.0
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.resampler = None
+        self.feature_columns = self.__candidate_columns(dataset)
+        self.imbalance_ratio = 0.0
+
+        if dataset.X.empty or not self.feature_columns:
+            return self
+        if dataset.type_of_target not in ['binary', 'multiclass']:
+            return self
+        if dataset.y is None or len(dataset.y) == 0:
+            return self
+
+        _, counts = np.unique(dataset.y, return_counts=True)
+        if len(counts) < 2:
+            return self
+
+        max_count = int(counts.max())
+        min_count = int(counts.min())
+        if max_count <= min_count:
+            return self
+
+        self.imbalance_ratio = 1.0 - (min_count / max_count)
+
+        params = self.passthrough_parameters()
+        sig_params = inspect.signature(RandomUnderSampler).parameters
+        params = {key: value for key, value in params.items() if key in sig_params}
+
+        self.resampler = RandomUnderSampler(**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 Random Under Sampling.
+
+        :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 not self.__candidate_columns(dataset):
+            return False
+        _, counts = np.unique(dataset.y, return_counts=True)
+        if len(counts) < 2:
+            return False
+        return counts.max() > counts.min()
+
+    def __candidate_columns(self, dataset: Dataset) -> list[str]:
+        columns = dataset.get_columns_names_by_type(list(DataType))
+        if len(columns) != dataset.X.shape[1]:
+            missing = [column for column in dataset.X.columns if column not in columns]
+            columns.extend(missing)
+        return columns

iaml/actionables/imbalance/act_smote.py

@@ -0,0 +1,162 @@
+"""[STEP] SMOTE"""
+import textwrap
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from imblearn.over_sampling import SMOTE, SMOTENC
+
+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 ActSMOTE(Actionable):
+    """[STEP] SMOTE"""
+
+    name: str = "SMOTE"
+    _usage: str = "Use when imbalanced classification needs synthetic minority samples; compare ActADASYN for adaptive oversampling. Applicable to binary or multiclass with numeric features (categoricals via SMOTENC). Avoid when non-classification, text/date-only, or minority count <= 1."
+    _description: str = textwrap.dedent('''\
+        SMOTE balances the minority class by creating synthetic samples
+        through interpolation.''')
+    _description_long: str = textwrap.dedent('''\
+        SMOTE (Synthetic Minority Over-sampling Technique) addresses class
+        imbalance by generating new minority samples between nearest neighbors.
+        This keeps the original data while reducing bias toward the majority class.''')
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 2002,
+            'name': 'SMOTE: Synthetic Minority Over-sampling Technique',
+            'authors': [
+                'Nitesh V. Chawla',
+                'Kevin W. Bowyer',
+                'Lawrence O. Hall',
+                'W. Philip Kegelmeyer'
+            ],
+            'doi': 'https://doi.org/10.1613/jair.953',
+            'publisher': 'Journal of Artificial Intelligence Research Vol.16 page 321--357'
+        }
+    ]
+
+    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]
+            },
+            'random_state': {
+                'description': 'Random seed used for reproducibility.',
+                'default': 42
+            }
+        }
+        self.resampler: SMOTE | SMOTENC | None = None
+        self.categorical_columns: list[str] = []
+        self.categorical_indices: list[int] = []
+        self.numeric_columns: list[str] = []
+        self._effective_k_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.categorical_indices = []
+        self._effective_k_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 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
+
+        params = self.passthrough_parameters()
+        params['k_neighbors'] = k_neighbors
+
+        if self.categorical_columns:
+            self.categorical_indices = [
+                dataset.X.columns.get_loc(column)
+                for column in self.categorical_columns
+                if column in dataset.X.columns
+            ]
+            if self.categorical_indices:
+                self.resampler = SMOTENC(
+                    categorical_features=self.categorical_indices,
+                    **params
+                )
+            else:
+                self.resampler = SMOTE(**params)
+        else:
+            self.resampler = SMOTE(**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 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 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