PyIAML 1.0.0__py3-none-any.whl

iaml/actionables/features_preprocessing/act_k_means_features.py

@@ -0,0 +1,296 @@
+"""[STEP] Add KMeans distance/cluster features."""
+import textwrap
+import pandas as pd
+from sklearn.cluster import KMeans
+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_preprocessing')
+class ActKMeansFeatures(Actionable):
+    """[STEP] Add KMeans distance/cluster features."""
+
+    name: str = "KMeans Features"
+    _description: str = "Add KMeans distance and cluster assignment features"
+    _usage: str = "Use when numeric features may form clusters and you want distance/cluster signals (vs ActKernelPCA or ActFeatureAgglomeration). Applicable to numeric tables with enough rows for k clusters. Avoid when data are tiny, mostly categorical, or clustering adds noise."
+    _description_long: str = textwrap.dedent('''\
+        KMeans groups numeric observations into k clusters by minimizing the
+        within-cluster variance. This step fits KMeans on numeric features and
+        appends distance-to-centroid features and, optionally, the assigned
+        cluster label. These additional features can surface non-linear structure
+        in the numeric feature space for downstream models.
+    ''')
+
+    def __init__(self) -> None:
+        self.configuration = {
+            'n_clusters': {
+                'description': 'Number of clusters to form.',
+                'default': 8,
+                'range': [2, 200]
+            },
+            'init': {
+                'description': 'Initialization method.',
+                'default': 'k-means++',
+                'categorical': ['k-means++', 'random']
+            },
+            'n_init': {
+                'description': 'Number of time the k-means algorithm will be run.',
+                'default': 10,
+                'range': [1, 20]
+            },
+            'max_iter': {
+                'description': 'Maximum number of iterations per run.',
+                'default': 300,
+                'range': [50, 1000]
+            },
+            'tol': {
+                'description': 'Relative tolerance with regards to inertia.',
+                'default': 0.0001,
+                'range': [1e-05, 0.01]
+            },
+            'algorithm': {
+                'description': 'KMeans algorithm variant.',
+                'default': 'lloyd',
+                'categorical': ['lloyd', 'elkan']
+            },
+            'random_state': {
+                'description': 'Random state for reproducibility.',
+                'default': 42
+            },
+            'add_distances': {
+                'description': 'Whether to add distance-to-centroid features.',
+                'default': True,
+                'passthrough': False
+            },
+            'distance_mode': {
+                'description': 'Distance features to add: all or closest.',
+                'default': 'all',
+                'categorical': ['all', 'closest'],
+                'passthrough': False
+            },
+            'add_cluster_label': {
+                'description': 'Whether to add the cluster assignment feature.',
+                'default': True,
+                'passthrough': False
+            },
+            'feature_prefix': {
+                'description': 'Prefix for generated KMeans features.',
+                'default': 'kmeans',
+                'passthrough': False
+            }
+        }
+
+        self.columns: list[str] = []
+        self.active_columns: list[str] = []
+        self.preprocessor: KMeans | None = None
+        self.distance_feature_names: list[str] = []
+        self.label_column: str | None = None
+        self.feature_prefix: str = 'kmeans'
+        self.add_distances: bool = True
+        self.add_cluster_label: bool = True
+        self.distance_mode: str = 'all'
+        self.impute_values: pd.Series | None = None
+        self.optimizable: bool = True
+
+    @staticmethod
+    def _coerce_int(value: object, default: int) -> int:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return default
+
+    @staticmethod
+    def _coerce_bool(value: object, default: bool) -> bool:
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            lowered = value.strip().lower()
+            if lowered in ('1', 'true', 'yes', 'y'):
+                return True
+            if lowered in ('0', 'false', 'no', 'n'):
+                return False
+        return default
+
+    @staticmethod
+    def _coerce_str(value: object, default: str) -> str:
+        if value is None:
+            return default
+        text = str(value).strip()
+        return text or default
+
+    @staticmethod
+    def _resolve_distance_mode(value: object) -> str:
+        if value is None:
+            return 'all'
+        text = str(value).strip().lower()
+        if text in ('closest', 'min', 'nearest'):
+            return 'closest'
+        return 'all'
+
+    @staticmethod
+    def _select_active_columns(values: pd.DataFrame) -> list[str]:
+        if values.empty:
+            return []
+        unique_counts = values.nunique(dropna=True)
+        return [col for col in values.columns if unique_counts.get(col, 0) > 1]
+
+    @staticmethod
+    def _unique_name(name: str, reserved: set[str]) -> str:
+        if name not in reserved:
+            return name
+        idx = 1
+        candidate = f"{name}_{idx}"
+        while candidate in reserved:
+            idx += 1
+            candidate = f"{name}_{idx}"
+        return candidate
+
+    def _resolve_n_clusters(self, n_samples: int) -> int | None:
+        if n_samples < 2:
+            return None
+        n_clusters = self._coerce_int(self.get_config('n_clusters'), 8)
+        n_clusters = max(2, n_clusters)
+        return min(n_clusters, n_samples)
+
+    def _build_kmeans(self, n_clusters: int) -> KMeans:
+        params = self.passthrough_parameters()
+        params['n_clusters'] = int(n_clusters)
+        params['n_init'] = self._coerce_int(params.get('n_init'), 10)
+        params['max_iter'] = self._coerce_int(params.get('max_iter'), 300)
+        params['tol'] = float(params.get('tol', 0.0001))
+        try:
+            return KMeans(**params)
+        except TypeError:
+            params.pop('algorithm', None)
+            return KMeans(**params)
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        self.active_columns = []
+        self.preprocessor = None
+        self.distance_feature_names = []
+        self.label_column = None
+        self.impute_values = None
+        self.feature_prefix = self._coerce_str(self.get_config('feature_prefix'), 'kmeans')
+        self.add_distances = self._coerce_bool(self.get_config('add_distances'), True)
+        self.add_cluster_label = self._coerce_bool(self.get_config('add_cluster_label'), True)
+        self.distance_mode = self._resolve_distance_mode(self.get_config('distance_mode'))
+        self.explanations = []
+
+        if not self.columns or dataset.X.empty:
+            return self
+
+        values = dataset.X[self.columns]
+        self.active_columns = self._select_active_columns(values)
+        if not self.active_columns:
+            return self
+
+        if not self.add_distances and not self.add_cluster_label:
+            return self
+
+        active_values = values[self.active_columns]
+        n_clusters = self._resolve_n_clusters(active_values.shape[0])
+        if n_clusters is None:
+            return self
+
+        self.configure('n_clusters', n_clusters) # pylint: disable=too-many-function-args
+        self.impute_values = active_values.median(numeric_only=True)
+        active_values = active_values.fillna(self.impute_values)
+
+        self.preprocessor = self._build_kmeans(n_clusters)
+        self.preprocessor.fit(active_values)
+
+        reserved = set(dataset.X.columns)
+        if self.add_distances:
+            if self.distance_mode == 'closest':
+                name = self._unique_name(f"{self.feature_prefix}_cluster_dist", reserved)
+                self.distance_feature_names = [name]
+                reserved.add(name)
+            else:
+                self.distance_feature_names = []
+                for idx in range(n_clusters):
+                    name = self._unique_name(f"{self.feature_prefix}_cluster_{idx}_dist", reserved)
+                    self.distance_feature_names.append(name)
+                    reserved.add(name)
+
+        if self.add_cluster_label:
+            self.label_column = self._unique_name(f"{self.feature_prefix}_cluster", reserved)
+            reserved.add(self.label_column)
+
+        if self.add_distances and self.distance_feature_names:
+            self.explanations.append(
+                f"Added {len(self.distance_feature_names)} KMeans distance features."
+            )
+        if self.add_cluster_label and self.label_column:
+            self.explanations.append(
+                f"Added KMeans cluster label feature `{self.label_column}`."
+            )
+
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply KMeans distance/cluster features.
+
+        :param pd.DataFrame X: DataFrame to transform
+        :return: Transformed dataset
+        """
+        if self.preprocessor is None or not self.active_columns:
+            return X
+
+        if any(column not in X.columns for column in self.active_columns):
+            return X
+
+        values = X[self.active_columns]
+        if self.impute_values is not None:
+            values = values.fillna(self.impute_values)
+
+        if self.add_distances and self.distance_feature_names:
+            distances = self.preprocessor.transform(values)
+            if self.distance_mode == 'closest':
+                distances = distances.min(axis=1).reshape(-1, 1)
+            distance_df = pd.DataFrame(
+                distances,
+                columns=self.distance_feature_names,
+                index=X.index
+            )
+            X = pd.concat([X, distance_df], axis=1)
+
+        if self.add_cluster_label and self.label_column:
+            X[self.label_column] = self.preprocessor.predict(values)
+
+        return X
+
+    def suitable(self, dataset: Dataset) -> bool:
+        if dataset.X.empty:
+            return False
+        if not self._coerce_bool(self.get_config('add_distances'), True) \
+            and not self._coerce_bool(self.get_config('add_cluster_label'), True):
+            return False
+        columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if not columns:
+            return False
+        values = dataset.X[columns]
+        active = self._select_active_columns(values)
+        if not active:
+            return False
+        return self._resolve_n_clusters(values.shape[0]) is not None
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        if candidate is None:
+            return 0.0
+        dataset = candidate.dataset
+        if not self.suitable(dataset):
+            return 0.0
+        columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if not columns:
+            return 0.0
+        values = dataset.X[columns]
+        active = self._select_active_columns(values)
+        if not active:
+            return 0.0
+        n_samples = max(1, values.shape[0])
+        ratio = len(active) / n_samples
+        return min(1.0, 0.2 + ratio)

iaml/actionables/features_preprocessing/act_kernel_pca.py

@@ -0,0 +1,143 @@
+"""[STEP] Decompose features with KernelPCA"""
+import textwrap
+import pandas as pd
+from sklearn.decomposition import KernelPCA
+from ...actionable import Actionable
+from ...dataset import Dataset
+from ...candidate import Candidate
+from ...decorators.all import is_step
+
+
+def _is_numeric_matrix(values: pd.DataFrame) -> bool:
+    if values.empty:
+        return False
+    for column in values.columns:
+        if not pd.api.types.is_numeric_dtype(values[column]):
+            return False
+    return not values.isna().any().any()
+
+
+@is_step('features_preprocessing')
+class ActKernelPCA(Actionable):
+    """[STEP] Apply KernelPCA for dimensionality reduction"""
+    name = "KernelPCA"
+    _description = "Perform Kernel Principal Component Analysis (KernelPCA) on a dataset"
+    _description_long = textwrap.dedent('''\
+        KernelPCA is a dimensionality reduction technique that extends Principal Component Analysis (PCA)
+        using kernel methods. It projects data into a higher-dimensional space before performing PCA,
+        enabling it to capture complex, non-linear structures in the data. KernelPCA is useful for reducing
+        dimensionality while preserving intricate patterns and relationships within the data.
+    ''')
+    _usage = "Use when non-linear structure matters and linear reductions are insufficient; consider ActFastICA if you want independent components. Applicable to dense numeric, scaled features. Avoid when data is very large, sparse, or interpretability is required."
+
+    refs = [
+        {
+            'year': 1997,
+            'name': 'Kernel principal component analysis',
+            'authors': [
+                'Bernhard Schölkopf',
+                'Alexander Smola',
+                'Klaus-Robert Müller'    
+            ],
+            'doi': 'https://doi.org/10.1007/BFb0020217',
+            'publisher': 'Springer, Berlin, Heidelberg'
+        },
+        {
+            'year': 2003,
+            'name': 'Learning to find pre-images',
+            'authors': [
+                'Jason Weston',
+                'Bernhard Schölkopf',
+                'Gökhan Bakir'
+            ],
+            'doi': 'https://proceedings.neurips.cc/paper_files/paper/2003/file/ \
+                    ac1ad983e08ad3304a97e147f522747e-Paper.pdf',
+            'publisher': 'Advances in neural information processing systems 16 (2004) page 449--456'
+        },
+        {
+            'year': 2009,
+            'name': 'Finding structure with randomness: Probabilistic algorithms for constructing \
+                approximate matrix decompositions',
+            'authors': [
+                'Nathan Halko',
+                'Per-Gunnar Martinsson',
+                'Joel A. Tropp'
+            ],
+            'doi': 'https://doi.org/10.48550/arXiv.0909.4061',
+            'publisher': 'SIAM Rev., Survey and Review section, Vol.53, No.2 page 217--288'
+        },
+        {
+            'year': 2011,
+            'name': 'A randomized algorithm for the decomposition of matrices',
+            'authors': [
+                'Per-Gunnar Martinsson',
+                'Vladimir Rokhlin',
+                'Mark Tygert'
+            ],
+            'doi': 'https://doi.org/10.1016/j.acha.2010.02.003',
+            'publisher': 'Applied and Computational Harmonic Analysis, Vol.30, No.1 page 47--68'
+        }
+    ]
+    def __init__(self):
+        self.configuration = {
+            'kernel': {
+                'description': 'Kernel used for PCA.',
+                'default': 'rbf',
+                'categorical': ['poly', 'rbf', 'sigmoid', 'cosine']
+            },
+            'n_components': {
+                'description': 'Number of components to keep.',
+                'default': 100,
+                'range': [10, 2000]
+            },
+            'coef0': {
+                'description': textwrap.dedent('''\
+                    Independent term in poly and sigmoid kernels. Ignored by
+                    other kernels.'''),
+                'default': 1.0,
+                'range': [-1.0, 1.0]
+            },
+            'degree': {
+                'description': 'Degree for poly kernels. Ignored by other kernels.',
+                'default': 3,
+                'range': [2, 5]
+            },
+            'random_state': {
+                'description': 'Random State',
+                'default': 42
+            }
+        }
+        self.optimizable: bool = True
+        self.preprocessor: bool = None
+
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.preprocessor = None
+        if not _is_numeric_matrix(dataset.X):
+            return self
+        try:
+            self.preprocessor = KernelPCA(**self.passthrough_parameters())
+            self.preprocessor.fit(dataset.X)
+        except ValueError:
+            higher_gamma = 1 / dataset.X.shape[1] + 0.05
+            self.preprocessor = KernelPCA(gamma=higher_gamma, **self.passthrough_parameters())
+            self.preprocessor.fit(dataset.X)
+
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply KernelPCA
+
+        :param pd.DataFrame X: DataFrame to transform
+        :return: Transformed dataset
+        """
+
+        if self.preprocessor is None:
+            return X
+        return pd.DataFrame(self.preprocessor.transform(X))
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return _is_numeric_matrix(dataset.X)
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5

iaml/actionables/features_preprocessing/act_log_transformer.py

@@ -0,0 +1,122 @@
+"""[STEP] Apply log1p to skewed numeric features."""
+import textwrap
+import numpy as np
+import pandas as pd
+from ...actionable import Actionable
+from ...candidate import Candidate
+from ...dataset import Dataset
+from ...data_type import DataType
+from ...decorators.all import is_step
+
+
+@is_step('features_preprocessing')
+class ActLogTransformer(Actionable):
+    """[STEP] Apply log1p to skewed numeric features."""
+
+    name: str = "Log1p Transformer"
+    _description: str = "Apply log1p to highly skewed numeric columns"
+    _usage: str = "Use when numeric features are highly right-skewed and >= -1, often before ActKBinsDiscretizer or ActKernelPCA. Applicable to continuous numeric columns with long-tailed distributions. Avoid when values are <= -1 or already log/scale transformed."
+    _description_long: str = textwrap.dedent('''\
+        This step detects numeric features with strong positive skew
+        and applies a log1p (log(1+x)) transformation to compress
+        extreme values. The transformation is automatic and only
+        applied to columns that meet the skewness threshold and have
+        values above the configured minimum.
+    ''')
+
+    def __init__(self):
+        self.columns: list[str] = []
+
+        self.configuration = {
+            'skew_threshold': {
+                'description': 'Minimum skewness required to apply log1p.',
+                'default': 1.5,
+                'range': [0.5, 5.0]
+            },
+            'min_value': {
+                'description': 'Minimum allowed value for applying log1p.',
+                'default': 0.0,
+                'range': [-0.99, 1.0]
+            }
+        }
+
+        self.optimizable: bool = True
+
+    @staticmethod
+    def _coerce_float(value: object, default: float) -> float:
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            return default
+
+    def _resolve_skew_threshold(self) -> float:
+        threshold = self._coerce_float(self.get_config('skew_threshold'), 1.5)
+        if threshold < 0:
+            threshold = 0.0
+        return threshold
+
+    def _resolve_min_value(self) -> float:
+        min_value = self._coerce_float(self.get_config('min_value'), 0.0)
+        if min_value <= -1.0:
+            min_value = -0.999
+        return min_value
+
+    def _select_columns(self, values: pd.DataFrame) -> list[str]:
+        if values.empty:
+            return []
+        skewness = values.skew().fillna(0.0)
+        min_values = values.min(skipna=True)
+        threshold = self._resolve_skew_threshold()
+        min_value = self._resolve_min_value()
+        eligible = (skewness >= threshold) & (min_values >= min_value)
+        return [col for col in values.columns if bool(eligible.get(col, False))]
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.columns = []
+        columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if not columns or dataset.X.empty:
+            return self
+        values = dataset.X[columns]
+        self.columns = self._select_columns(values)
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply log1p
+
+        :param pd.DataFrame X: DataFrame to transform
+        :return: Transformed dataset
+        """
+        if not self.columns:
+            return X
+        columns = [col for col in self.columns if col in X.columns]
+        if not columns:
+            return X
+        min_value = self._resolve_min_value()
+        values = X[columns].clip(lower=min_value)
+        X[columns] = np.log1p(values)
+        return X
+
+    def suitable(self, dataset: Dataset) -> bool:
+        columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if not columns or dataset.X.empty:
+            return False
+        values = dataset.X[columns]
+        return bool(self._select_columns(values))
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        if candidate is None:
+            return 0.0
+        dataset = candidate.dataset
+        columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if not columns or dataset.X.empty:
+            return 0.0
+        values = dataset.X[columns]
+        selected = self._select_columns(values)
+        if not selected:
+            return 0.0
+        skewness = values[selected].skew().fillna(0.0)
+        threshold = self._resolve_skew_threshold()
+        if threshold <= 0:
+            return 1.0
+        mean_skew = float(skewness.mean()) if not skewness.empty else 0.0
+        return min(1.0, mean_skew / (threshold * 2.0))

iaml/actionables/features_preprocessing/act_nystroem.py

@@ -0,0 +1,100 @@
+"""[STEP] Decompose features with Nystroem"""
+import textwrap
+import pandas as pd
+from sklearn.kernel_approximation import Nystroem
+from ...actionable import Actionable
+from ...dataset import Dataset
+from ...candidate import Candidate
+from ...decorators.all import is_step
+
+
+def _is_numeric_matrix(values: pd.DataFrame) -> bool:
+    if values.empty:
+        return False
+    for column in values.columns:
+        if not pd.api.types.is_numeric_dtype(values[column]):
+            return False
+    return not values.isna().any().any()
+
+
+@is_step('features_preprocessing')
+class ActNystroem(Actionable):
+    """[STEP] Apply Nystroem method for dimensionality reduction"""
+
+    name: str = "Nystroem"
+    _description: str = "Apply the Nystroem method for dimensionality reduction \
+        over a list of columns"
+    _usage: str = "Use when you need a fast nonlinear kernel map approximation for large numeric data, as a lighter option than ActKernelPCA. Applicable to scaled continuous features with many rows. Avoid when you need independent components or tiny data where ActFastICA or ActKernelPCA is fine."
+    _description_long: str = textwrap.dedent('''\
+        The Nystroem method is a technique used for approximating kernel methods, 
+        which helps in reducing the computational cost of kernel-based algorithms.
+        It approximates a kernel map using a subset of the data, making it suitable
+        for large datasets. This approach enables dimensionality reduction by creating
+        a low-rank approximation of the original kernel matrix.
+    ''')
+
+    def __init__(self):
+        self.configuration = {
+            'kernel': {
+                'description': 'Kernel map to be approximated.',
+                'default': 'rbf',
+                'categorical': ["poly", "rbf", "sigmoid", "cosine", "chi2"]
+            },
+            'n_components': {
+                'description': 'Number of components to keep.',
+                'default': 100,
+                'range': [50, 10000]
+            },
+            'coef0': {
+                'description': 'Zero coefficient for polynomial and sigmoid kernels.',
+                'default': 0.0,
+                'range': [-1.0, 1.0]
+            },
+            'degree': {
+                'description': 'Degree of the polynomial kernel.',
+                'default': 3,
+                'range': [2, 5]
+            },
+            'gamma': {
+                'description': textwrap.dedent('''\
+                    Gamma parameter for the RBF, laplacian, polynomial,
+                    exponential chi2 and sigmoid kernels.'''),
+                'default': 0.1,
+                'range': [3.06e-05, 8.0]
+            },
+            'random_state': {
+                'description': 'Random State',
+                'default': 42
+            }
+        }
+        self.optimizable: bool = True
+        self.preprocessor: bool = None
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.preprocessor = None
+        if not _is_numeric_matrix(dataset.X):
+            return self
+        self.preprocessor = Nystroem(**self.passthrough_parameters())
+        self.preprocessor.fit(dataset.X)
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply Nystroem
+
+        :param pd.DataFrame X: DataFrame to transform
+        :return: Transformed dataset
+        """
+        if self.preprocessor is None:
+            return X
+        return pd.DataFrame(self.preprocessor.transform(X))
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5
+
+
+    def suitable(self, dataset: Dataset) -> bool:
+        if not _is_numeric_matrix(dataset.X):
+            return False
+        if self.get_config('kernel') == 'chi2' and not (dataset.X < 0).any().any():
+            self.configure('kernel', 'rbf') # pylint: disable=too-many-function-args
+        return True