PyIAML 1.0.0__py3-none-any.whl

iaml/actionables/features_preprocessing/act_fast_ica.py

@@ -0,0 +1,161 @@
+"""[STEP] Reduce dimensions with FastICA"""
+import textwrap
+import numpy as np
+import pandas as pd
+from sklearn.decomposition import FastICA
+from sklearn.utils.validation import check_array
+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 ActFastICA(Actionable):
+    """[STEP] Reduce dimensions with FastICA"""
+
+    name: str = "FastICA"
+    _description: str = "Apply FastICA to extract independent components from numeric features"
+    _description_long: str = textwrap.dedent('''\
+        FastICA is a linear decomposition technique that separates mixed signals
+        into statistically independent components. It can be used as a
+        dimensionality reduction step by projecting numeric features into a
+        smaller set of latent sources while keeping the transformation
+        deterministic and efficient.
+    ''')
+    _usage: str = "Use when linear independent components from mixed numeric signals are needed instead of ActKernelPCA. Applicable to continuous numeric features with enough samples. Avoid when samples or features are too few, or when ActFeatureAgglomeration is a better fit."
+
+    def __init__(self):
+        self.columns: list[str] = []
+        self.component_names: list[str] = []
+        self.preprocessor: FastICA | None = None
+
+        self.configuration = {
+            'n_components': {
+                'description': 'Number of independent components to estimate.',
+                'default': 10,
+                'range': [2, 2000]
+            },
+            'algorithm': {
+                'description': 'ICA algorithm to use.',
+                'default': 'parallel',
+                'categorical': ['parallel', 'deflation']
+            },
+            'whiten': {
+                'description': 'Whether to whiten data before applying ICA.',
+                'default': 'unit-variance',
+                'categorical': ['unit-variance', 'arbitrary-variance', False]
+            },
+            'fun': {
+                'description': 'Functional form of the G function.',
+                'default': 'logcosh',
+                'categorical': ['logcosh', 'exp', 'cube']
+            },
+            'max_iter': {
+                'description': 'Maximum number of iterations during optimization.',
+                'default': 200,
+                'range': [100, 1000]
+            },
+            'tol': {
+                'description': 'Convergence tolerance.',
+                'default': 0.0001,
+                'range': [1e-05, 0.01]
+            },
+            'random_state': {
+                'description': 'Random State',
+                'default': 42
+            }
+        }
+
+        self.optimizable: bool = True
+
+    @staticmethod
+    def _coerce_int(value: object, default: int) -> int:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return default
+
+    def _resolve_n_components(self, values: pd.DataFrame) -> int | None:
+        max_components = min(values.shape)
+        if max_components >= 2 and self.get_config('whiten'):
+            # Whitening can only use nonzero directions after centering.
+            numeric = check_array(values, dtype=[np.float64, np.float32])
+            max_components = int(np.linalg.matrix_rank(numeric - numeric.mean(axis=0)))
+        if max_components < 2:
+            return None
+        n_components = self._coerce_int(self.get_config('n_components'), max_components)
+        n_components = max(2, n_components)
+        return min(n_components, max_components)
+
+    def _build_transformer(self) -> FastICA:
+        params = self.passthrough_parameters()
+        params['n_components'] = int(params['n_components'])
+        params['max_iter'] = int(params['max_iter'])
+        params['tol'] = float(params['tol'])
+        return FastICA(**params)
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        self.preprocessor = None
+        self.component_names = []
+
+        if not self.columns or dataset.X.empty:
+            return self
+
+        values = dataset.X[self.columns]
+        if values.isna().any().any():
+            return self
+        n_components = self._resolve_n_components(values)
+        if n_components is None:
+            return self
+
+        self.configure('n_components', n_components) # pylint: disable=too-many-function-args
+        self.preprocessor = self._build_transformer()
+        self.preprocessor.fit(values)
+
+        self.component_names = [f"ica_{i}" for i in range(n_components)]
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply FastICA
+
+        :param pd.DataFrame X: DataFrame to transform
+        :return: Transformed dataset
+        """
+        if self.preprocessor is None or not self.columns:
+            return X
+
+        values = X[self.columns]
+        transformed = self.preprocessor.transform(values)
+        component_names = self.component_names or [
+            f"ica_{i}" for i in range(transformed.shape[1])
+        ]
+        ica_df = pd.DataFrame(transformed, columns=component_names, index=X.index)
+
+        X = X.drop(columns=self.columns)
+        return pd.concat([X, ica_df], axis=1)
+
+    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]
+        if values.isna().any().any():
+            return False
+        return min(values.shape) > 1
+
+    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]
+        if min(values.shape) <= 1:
+            return 0.0
+        n_features = values.shape[1]
+        n_samples = values.shape[0]
+        return min(1.0, n_features / max(1, n_samples))

iaml/actionables/features_preprocessing/act_feature_agglomeration.py

@@ -0,0 +1,90 @@
+"""[STEP] Decompose features with FeatureAgglomeration"""
+import textwrap
+import pandas as pd
+import numpy as np
+from sklearn.cluster import FeatureAgglomeration
+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 ActFeatureAgglomeration(Actionable):
+    """[STEP] Apply FeatureAgglomeration for dimensionality reduction"""
+    name: str = "FeatureAgglomeration"
+    _description: str = "Process FeatureAgglomeration algorithm over a set of features"
+    _description_long: str = textwrap.dedent('''\
+        FeatureAgglomeration is a clustering-based dimensionality reduction technique.
+        It groups similar features together using a hierarchical clustering approach,
+        which can help reduce the dimensionality of the dataset while preserving
+        essential information. This technique is unsupervised, meaning it does not
+        require labeled data, as it identifies clusters of features based on similarity.
+    ''')
+    _usage: str = "Use when you want to cluster highly correlated numeric features for dimensionality reduction, instead of ActKernelPCA or ActFastICA. Applicable to wide tabular data with many continuous features and no labels. Avoid when features are mostly categorical or you need interpretable original features."
+
+    def __init__(self):
+        self.configuration: dict = {
+            'n_clusters': {
+                'description': 'The number of clusters to find',
+                'default': 25,
+                'range': [2, 400]
+                },
+            'metric': {
+                'description': 'Metric used to compute the linkage.',
+                'default': 'euclidean',
+                'categorical': ['euclidean']
+                # 'categorical': ['euclidean', 'l1', 'l2', 'manhattan', 'cosine', 'precomputed']
+                },
+            'linkage': {
+                'description': 'Which linkage criterion to use.',
+                'default': 'ward',
+                'categorical': ['ward', 'complete', 'average', 'single']
+                # 'categorical': ['ward', 'complete', 'average', 'single']
+                },
+            'pooling_func': {
+                'description': 'Which linkage criterion to use.',
+                'default': np.mean,
+                'categorical': [np.mean, np.median, np.max]
+                }
+            }
+
+        self.optimizable: bool = True
+        self.preprocessor: FeatureAgglomeration | None = None
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        # pylint: disable=too-many-function-args
+        self.preprocessor = None
+        if not _is_numeric_matrix(dataset.X):
+            return self
+        self.configure('n_clusters', min(self.get_config('n_clusters'), dataset.X.shape[1]))
+
+        self.preprocessor = FeatureAgglomeration(**self.passthrough_parameters())
+        self.preprocessor.fit(dataset.X)
+
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply FeatureAgglomeration
+
+        :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_k_bins_discretizer.py

@@ -0,0 +1,207 @@
+"""[STEP] Discretize numeric features with KBinsDiscretizer"""
+import textwrap
+import pandas as pd
+from sklearn.preprocessing import KBinsDiscretizer
+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 ActKBinsDiscretizer(Actionable):
+    """[STEP] Discretize numeric features with KBinsDiscretizer"""
+
+    name: str = "KBins Discretizer"
+    _description: str = "Discretize numeric columns into uniform, quantile, or k-means bins"
+    _usage: str = "Use when you want numeric features binned for simpler models or outlier robustness, rather than ActLogTransformer or ActKernelPCA. Applicable to continuous numeric columns with more than one unique value. Avoid when fine-grained ordering or exact values must be preserved."
+    _description_long: str = textwrap.dedent('''\
+        KBinsDiscretizer converts continuous numeric features into discrete bins.
+        It can use uniform width bins, quantile-based bins, or k-means based bins.
+        The resulting bins can be returned as ordinal values or one-hot encoded
+        features, which may help models that prefer discrete inputs or benefit
+        from reduced sensitivity to outliers.
+    ''')
+
+    def __init__(self):
+        self.columns: list[str] = []
+        self.active_columns: list[str] = []
+        self.output_columns: list[str] = []
+        self.preprocessor: KBinsDiscretizer | None = None
+
+        self.configuration = {
+            'n_bins': {
+                'description': 'Number of bins to use for each numeric feature.',
+                'default': 5,
+                'range': [2, 50]
+            },
+            'encode': {
+                'description': 'Encoding method for the transformed bins.',
+                'default': 'ordinal',
+                'categorical': ['ordinal', 'onehot', 'onehot-dense']
+            },
+            'strategy': {
+                'description': 'Strategy used to define the widths of the bins.',
+                'default': 'quantile',
+                'categorical': ['uniform', 'quantile', 'kmeans']
+            },
+            'subsample': {
+                'description': 'Maximum number of samples used to estimate quantile bin edges.',
+                'default': 200000,
+                'range': [1000, 500000]
+            },
+            'random_state': {
+                'description': 'Random state used when strategy is kmeans.',
+                'default': 42
+            }
+        }
+
+        self.optimizable: bool = True
+
+    @staticmethod
+    def _coerce_int(value: object, default: int) -> int:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return default
+
+    @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 _resolve_n_bins(values: pd.DataFrame, base_bins: int) -> int | list[int]:
+        if values.empty:
+            return base_bins
+        unique_counts = values.nunique(dropna=True).astype(int)
+        per_feature_bins = [min(base_bins, max(2, count)) for count in unique_counts]
+        if not per_feature_bins:
+            return base_bins
+        if all(bins == per_feature_bins[0] for bins in per_feature_bins):
+            return per_feature_bins[0]
+        return per_feature_bins
+
+    def _feature_names(self) -> list[str]:
+        if self.output_columns:
+            return self.output_columns
+        if self.preprocessor is None:
+            return []
+        if hasattr(self.preprocessor, "get_feature_names_out"):
+            try:
+                return list(self.preprocessor.get_feature_names_out(self.active_columns))
+            except ValueError:
+                return []
+        if hasattr(self.preprocessor, "n_bins_"):
+            names: list[str] = []
+            for column, n_bins in zip(self.active_columns, self.preprocessor.n_bins_):
+                for idx in range(int(n_bins)):
+                    names.append(f"{column}_bin_{idx}")
+            return names
+        return []
+
+    def _build_transformer(self, n_samples: int, n_bins: int | list[int]) -> KBinsDiscretizer:
+        params = self.passthrough_parameters()
+        params['n_bins'] = n_bins
+        if 'subsample' in params:
+            subsample = self._coerce_int(params.get('subsample'), n_samples)
+            subsample = max(1, min(subsample, n_samples))
+            params['subsample'] = subsample
+        return KBinsDiscretizer(**params)
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        self.active_columns = []
+        self.output_columns = []
+        self.preprocessor = None
+
+        if not self.columns or dataset.X.empty:
+            return self
+
+        values = dataset.X[self.columns]
+        if values.isna().any().any():
+            return self
+        self.active_columns = self._select_active_columns(values)
+        if not self.active_columns:
+            return self
+
+        active_values = values[self.active_columns]
+        base_bins = self._coerce_int(self.get_config('n_bins'), 5)
+        base_bins = max(2, base_bins)
+        n_bins = self._resolve_n_bins(active_values, base_bins)
+
+        self.preprocessor = self._build_transformer(active_values.shape[0], n_bins)
+        self.preprocessor.fit(active_values)
+
+        if self.get_config('encode') in ('onehot', 'onehot-dense'):
+            self.output_columns = self._feature_names()
+        else:
+            self.output_columns = self.active_columns.copy()
+
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply KBinsDiscretizer
+
+        :param pd.DataFrame X: DataFrame to transform
+        :return: Transformed dataset
+        """
+        if self.preprocessor is None or not self.active_columns:
+            return X
+
+        values = X[self.active_columns]
+        transformed = self.preprocessor.transform(values)
+        encode = self.get_config('encode')
+
+        if encode == 'ordinal':
+            X[self.active_columns] = transformed
+            return X
+
+        X = X.reset_index(drop=True)
+        feature_names = self.output_columns or self._feature_names()
+
+        if hasattr(transformed, "toarray") and encode == 'onehot':
+            encoded_df = pd.DataFrame.sparse.from_spmatrix(
+                transformed,
+                columns=feature_names,
+                index=X.index
+            )
+        else:
+            if hasattr(transformed, "toarray"):
+                transformed = transformed.toarray()
+            encoded_df = pd.DataFrame(transformed, columns=feature_names, index=X.index)
+
+        X = X.drop(columns=self.active_columns)
+        return pd.concat([X, encoded_df], axis=1)
+
+    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]
+        if values.isna().any().any():
+            return False
+        if values.empty:
+            return False
+        unique_counts = values.nunique(dropna=True)
+        return bool((unique_counts > 1).any())
+
+    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]
+        if values.empty:
+            return 0.0
+        n_rows = max(1, values.shape[0])
+        unique_ratio = values.nunique(dropna=True) / n_rows
+        if unique_ratio.empty:
+            return 0.0
+        mean_ratio = float(unique_ratio.mean())
+        return min(1.0, mean_ratio * 2.0)