PyIAML 1.0.0__py3-none-any.whl

iaml/actionables/features_preprocessing/act_pca.py

@@ -0,0 +1,77 @@
+"""
+[STEP] Decompose features with PCA
+"""
+import textwrap
+import pandas as pd
+from sklearn.decomposition import PCA
+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 ActPCA(Actionable):
+    """[STEP] Reduce dimensions with PCA"""
+
+    name: str = "PCA"
+    _description: str = "Apply PCA for dimensionality reduction over a list of columns"
+    _usage: str = "Use when you need fast linear dimensionality reduction for numeric features; consider ActKernelPCA or ActFastICA for nonlinear or independent components. Applicable to scaled numeric matrices. Avoid when features are categorical or you must keep original feature meaning."
+    _description_long: str = textwrap.dedent('''\
+        PCA, or Principal Component Analysis, is a dimensionality reduction technique.
+        It transforms the data into a set of linearly uncorrelated components, capturing
+        the maximum variance in the data with each successive component.
+        This method is unsupervised, meaning it does not require labeled data,
+        and is particularly useful for simplifying datasets while retaining
+        as much of the underlying structure as possible.
+    ''')
+
+    def __init__(self):
+        self.configuration = {
+            'n_components': {
+                'description': 'Number of components to keep.',
+                'default': 0.999,
+                'range': [0.5, 0.999]
+                },
+            'random_state': {
+                'description': 'Random State',
+                'default': 42
+                }
+            }
+
+        self.optimizable = True
+        self.preprocessor = None
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.preprocessor = None
+        if not _is_numeric_matrix(dataset.X):
+            return self
+
+        self.preprocessor = PCA(**self.passthrough_parameters())
+        self.preprocessor.fit(dataset.X)
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply PCA
+
+        :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_polynomial_features.py

@@ -0,0 +1,86 @@
+"""Experimental polynomial expansion, available only through an explicit import.
+
+Unbounded output dimensionality can exhaust memory during automatic exploration.
+Kept outside the default preprocessing stage; see docs/component_status.rst.
+"""
+import textwrap
+import pandas as pd
+from sklearn.preprocessing import PolynomialFeatures
+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('experimental')
+class ActPolynomialFeatures(Actionable):
+    """[STEP] Preprocess with PolynomialFeatures"""
+
+    name: str = "Preprocess with PolynomialFeatures"
+    _usage: str = "Use when you want explicit polynomial interactions for linear models; consider ActKernelPCA for projection-based nonlinearity. Applicable to numeric tabular features with moderate dimensionality. Avoid when feature count will explode or when ActKBinsDiscretizer is a better match."
+    _description: str = textwrap.dedent('''\
+        PolynomialFeatures creates new features by combining existing
+        features mathematically. It squares, cubes, and multiplies features to
+        create more complex patterns.''')
+    _description_long: str = textwrap.dedent('''\
+        PolynomialFeatures is a preprocessing technique that
+        generates new features based on polynomial relationships between existing
+        features. This helps capture non-linear relationships in the data that may
+        not be apparent from the original features alone. PolynomialFeatures is
+        particularly useful when you suspect the underlying relationship in your data
+        might not be straightforward or linear.''')
+
+    def __init__(self):
+        self.configuration = {
+            'include_bias': {
+                'description': 'If True (default), then include a bias \
+                    column, the feature in which all polynomial powers are zero',
+                'default': True
+                },
+            'interaction_only': {
+                'description': 'If True, only interaction features are produced',
+                'default': False
+                },
+            'degree': {
+                'description': 'Degree of the polynomial kernel.',
+                'default': 3,
+                'range': [2, 5]
+                }
+            }
+
+        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 = PolynomialFeatures(**self.passthrough_parameters())
+        self.preprocessor.fit(dataset.X)
+
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply PolynomialFeatures
+
+        :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:
+        return _is_numeric_matrix(dataset.X)

iaml/actionables/features_preprocessing/act_power_transformer.py

@@ -0,0 +1,106 @@
+"""[STEP] Preprocess with PowerTransformer"""
+from typing import Any
+import textwrap
+import pandas as pd
+from sklearn.preprocessing import PowerTransformer
+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 ActPowerTransformer(Actionable):
+    """[STEP] Preprocess with PowerTransformer"""
+
+    name: str = "Preprocess with PowerTransformer"
+    _description: str = textwrap.dedent('''\
+        PowerTransformer changes data to make it more "bell-curve" shaped.
+        It uses special math tricks to flatten out irregular distributions and make the data
+        behave more like a normal distribution.''')
+    _description_long: str = textwrap.dedent('''\
+        PowerTransformer is a preprocessing technique that applies a power
+        transformation to make data more Gaussian-like. PowerTransformer is useful when you want to apply
+        machine learning models that assume normal distribution,
+        even if your original data doesn't meet this assumption.
+        It helps make your data more compatible with many common ML algorithms.''')
+    _usage: str = "Use when numeric features are skewed and need Gaussian-like scaling, instead of ActKernelPCA or ActFastICA. Applicable to continuous numeric data with unimodal, non-normal distributions. Avoid when data are categorical/one-hot, already near-normal, or highly multimodal."
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 1964,
+            'name': 'An Analysis of Transformations',
+            'authors': [
+                'G. E. P. Box',
+                'D. R. Cox'
+            ],
+            'doi': 'https://doi.org/10.1111/j.2517-6161.1964.tb00553.x',
+            'publisher': 'Journal of the Royal Statistical Society: Series B (Methodological), \
+                Vol.26, No.2 page 211--243'
+        },
+        {
+            'year': 2000,
+            'name': 'A New Family of Power Transformations to Improve Normality or Symmetry',
+            'authors': [
+                'In-Kwon Yeo',
+                'Richard A. Johnson'
+            ],
+            'doi': 'https://doi.org/10.1093/biomet/87.4.954',
+            'publisher': 'Oxford University Press, Biometrika Vol.87 No.4 page 954--959'
+        },
+    ]
+
+    def __init__(self):
+        self.configuration = {
+            'method': {
+                'description': 'The power transform method.',
+                'default': 'yeo-johnson',
+                'categorical': ['yeo-johnson', 'box-cox']
+                },
+            'standardize': {
+                'description': 'Set to True to apply zero-mean, \
+                    unit-variance normalization to the transformed output.',
+                'default': True
+                }
+            }
+
+        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 = PowerTransformer(**self.passthrough_parameters())
+        self.preprocessor.fit(dataset.X)
+
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply PowerTransformer
+
+        :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('method') == 'box-cox' and not (dataset.X < 0).any().any():
+            self.configure('method', 'yeo-johnson') # pylint: disable=too-many-function-args
+        return True

iaml/actionables/features_preprocessing/act_quantile_transformer.py

@@ -0,0 +1,114 @@
+"""[STEP] Preprocess with QuantileTransformer"""
+import textwrap
+import pandas as pd
+from sklearn.preprocessing import QuantileTransformer
+from ...actionable import Actionable
+from ...dataset import Dataset
+from ...candidate import Candidate
+from ...data_type import DataType
+from ...decorators.all import is_step
+
+
+@is_step('features_preprocessing')
+class ActQuantileTransformer(Actionable):
+    """[STEP] Preprocess with QuantileTransformer"""
+
+    name: str = "Preprocess with QuantileTransformer"
+    _description: str = textwrap.dedent('''\
+        QuantileTransformer remaps numeric features to a uniform or normal distribution,
+        reducing skew and making feature scales more comparable.''')
+    _description_long: str = textwrap.dedent('''\
+        QuantileTransformer estimates the empirical cumulative distribution for each
+        numeric feature and maps values to a chosen target distribution.
+        This non-linear transformation can reduce the impact of outliers and
+        produce more Gaussian-like features for models that benefit from it.''')
+    _usage: str = "Use when numeric features are skewed or unevenly scaled; compare ActKBinsDiscretizer. Applicable to continuous numeric columns before models preferring near-normal inputs. Avoid when original units or interpretability must stay, or data is very sparse; compare ActKernelPCA."
+
+    def __init__(self):
+        self.columns: list[str] = None
+        self.preprocessor: QuantileTransformer = None
+
+        self.configuration = {
+            'n_quantiles': {
+                'description': 'Number of quantiles to estimate.',
+                'default': 1000,
+                'range': [10, 1000]
+            },
+            'output_distribution': {
+                'description': 'Target distribution for the transformed data.',
+                'default': 'normal',
+                'categorical': ['uniform', 'normal']
+            },
+            'subsample': {
+                'description': 'Maximum number of samples used to estimate quantiles.',
+                'default': 100000,
+                'range': [1000, 200000]
+            },
+            'random_state': {
+                'description': 'Random state used when subsampling.',
+                'default': 42
+            },
+            'copy': {
+                'description': 'Set to False to perform transformation in-place when possible.',
+                'default': True,
+                'categorical': [True, False]
+            }
+        }
+
+        self.optimizable: bool = True
+
+    def _build_transformer(self, n_samples: int) -> QuantileTransformer:
+        params = self.passthrough_parameters()
+        n_samples = max(1, int(n_samples))
+        n_quantiles = int(params.pop('n_quantiles'))
+        subsample = int(params.pop('subsample'))
+        n_quantiles = max(1, min(n_quantiles, n_samples))
+        subsample = max(1, min(subsample, n_samples))
+        params['n_quantiles'] = n_quantiles
+        params['subsample'] = subsample
+        return QuantileTransformer(**params)
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if self.columns and not dataset.X.empty:
+            values = dataset.X[self.columns]
+            if values.isna().any().any():
+                self.preprocessor = None
+                return self
+            self.preprocessor = self._build_transformer(values.shape[0])
+            self.preprocessor.fit(values)
+        else:
+            self.preprocessor = None
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply QuantileTransformer
+
+        :param pd.DataFrame X: DataFrame to transform
+        :return: Transformed dataset
+        """
+        if self.preprocessor and self.columns:
+            X[self.columns] = self.preprocessor.transform(X[self.columns])
+        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 not values.isna().any().any()
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        if candidate is None:
+            return 0.0
+        columns = candidate.dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if not columns or candidate.dataset.X.empty:
+            return 0.0
+        values = candidate.dataset.X[columns]
+        if values.empty:
+            return 0.0
+        skewness = values.skew().abs().fillna(0.0)
+        if skewness.empty:
+            return 0.0
+        mean_skew = float(skewness.mean())
+        return min(1.0, mean_skew / 2.0)

iaml/actionables/features_preprocessing/act_rbf_sampler.py

@@ -0,0 +1,88 @@
+"""[STEP] Decompose features with RBFSampler"""
+from typing import Any
+import textwrap
+import pandas as pd
+from sklearn.kernel_approximation import RBFSampler
+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 ActRBFSampler(Actionable):
+    """[STEP] Approximate with RBFSampler"""
+
+    name: str = "Approximate with RBFSampler"
+    _usage: str = "Use when you want a fast nonlinear kernel approximation for numeric features, as a lighter alternative to ActKernelPCA. Applicable to dense tabular data where scaling is reasonable. Avoid when data are categorical heavy, very sparse, or when you need exact kernel features."
+    _description: str = textwrap.dedent('''\
+        RBFSampler is a tool that helps computers understand complex relationships
+        between things by turning them into simpler numbers.''')
+    _description_long: str = textwrap.dedent('''\
+        RBFSampler is a machine learning technique that transforms data into
+        a higher-dimensional space where it's easier for algorithms to find patterns.
+        It works by creating random projections of the original data onto a new set of axes.
+        This allows it to approximate the effects of a radial basis function kernel, which is a
+        mathematical way of measuring similarity between data points.''')
+    refs: list[dict[str, Any]] =[
+        {
+            'year': 2008,
+            'name': 'Weighted Sums of Random Kitchen Sinks: Replacing minimization with \
+                randomization in learning',
+            'authors': [
+                'Ali Rahimi',
+                'Benjamin Recht'
+            ],
+            'doi': None,
+            'publisher': 'Advances in Neural Information Processing Systems 21 page 1313--1320'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration = {
+            'n_components': {
+                'description': 'Number of components to keep.',
+                'default': 100,
+                'range': [50, 10000]
+            },
+            '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 = RBFSampler(**self.passthrough_parameters())
+        self.preprocessor.fit(dataset.X)
+
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply RBFSampler
+
+        :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:
+        return _is_numeric_matrix(dataset.X)

iaml/actionables/features_preprocessing/act_select_percentile.py

@@ -0,0 +1,112 @@
+"""[STEP] Decompose features with SelectPercentile"""
+
+import textwrap
+from collections.abc import Callable
+
+import pandas as pd
+from sklearn.feature_selection import SelectPercentile, chi2, f_classif
+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()
+
+
+def _resolve_score_func(value) -> Callable | None:
+    if callable(value):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered == 'chi2':
+            return chi2
+        if lowered == 'f_classif':
+            return f_classif
+    return None
+
+
+@is_step('features_preprocessing')
+class ActSelectPercentile(Actionable):
+    """[STEP] Preprocess with SelectPercentile"""
+
+    name: str = "Preprocess with SelectPercentile"
+    _usage: str = "Use when you need fast univariate feature selection by percentile, rather than ActKernelPCA. Applicable to non-negative features with classification targets (chi2 or f_classif). Avoid when you want feature engineering via clustering like ActKMeansFeatures."
+    _description: str  = textwrap.dedent('''\
+        SelectPercentile is a tool that helps choose important features from a
+        group of variables by looking at how well each one predicts the outcome.''')
+    _description_long: str  = textwrap.dedent('''\
+        SelectPercentile is a feature selection technique used in machine
+        learning. It works by assigning scores to each feature based on how well it predicts
+        the outcome. Then, it selects only the top-scoring percentage of features.
+        This helps reduce the number of variables while keeping the most informative ones.''')
+
+    def __init__(self):
+        self.configuration = {
+            'score_func': {
+                'description': 'function taking two arrays X and y, \
+                    and returning a pair of arrays',
+                'default': chi2,
+                'categorical': [chi2, f_classif]
+                },
+            'percentile': {
+                'description': 'Percent of features to keep.',
+                'default': 50.0,
+                'range': [1.0, 99.0]
+                }
+            }
+
+        self.optimizable: bool = True
+        self.preprocessor: SelectPercentile | None = None
+
+    def fit(self, dataset: Dataset) -> Actionable:
+        self.preprocessor = None
+        if dataset.y is None or not _is_numeric_matrix(dataset.X):
+            return self
+
+        score_func = _resolve_score_func(self.get_config('score_func'))
+        if score_func is None:
+            return self
+
+        params = self.passthrough_parameters()
+        params['score_func'] = score_func
+        self.preprocessor = SelectPercentile(**params)
+        self.preprocessor.fit(dataset.X, dataset.y)
+
+        return self
+
+    def transform(self, X: pd.DataFrame) -> pd.DataFrame:
+        """Apply SelectPercentile
+
+        :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:
+        # Negative values are not supported
+        if dataset.y is None or dataset.type_of_target is None:
+            return False
+        if not _is_numeric_matrix(dataset.X):
+            return False
+        score_func = _resolve_score_func(self.get_config('score_func'))
+        if score_func is None:
+            return False
+        if dataset.type_of_target not in [
+            'binary', 'multiclass', 'multilabel-indicator'
+        ]:
+            return False
+        if score_func == chi2:
+            return not (dataset.X < 0).any().any()
+        return True
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5