PyIAML 1.0.0__py3-none-any.whl

iaml/actionables/predictors/regressor/act_lasso_regressor.py

@@ -0,0 +1,103 @@
+"""[STEP] Lasso Regressor"""
+import textwrap
+from typing import Any
+from sklearn.linear_model import Lasso
+from ....predictor import Predictor
+from ....dataset import Dataset
+from ....candidate import Candidate
+from ....data_type import DataType
+from ....decorators.all import is_step
+
+
+@is_step('predictor', 'tabular', 'regressor')
+class ActLassoRegressor(Predictor):
+    """[STEP] Lasso Regressor"""
+
+    name: str = "Lasso Regressor"
+    _description: str = textwrap.dedent('''\
+        Lasso regression uses L1 regularization to shrink coefficients and
+        perform automatic feature selection in linear regression.''')
+    _description_long: str = textwrap.dedent('''\
+        Lasso (Least Absolute Shrinkage and Selection Operator) fits a linear
+        model while adding an L1 penalty to the loss. The penalty drives some
+        coefficients to zero, selecting a sparse set of features and improving
+        interpretability for tabular regression tasks.''')
+    _usage: str = "Use when you want sparse linear coefficients and feature selection; compare ActElasticNetRegressor or ActARDRegression for similar linear shrinkage. Applicable to numeric tabular regression with continuous targets. Avoid when effects are strongly nonlinear or dominated by categorical features."
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 1996,
+            'name': 'Regression Shrinkage and Selection via the Lasso',
+            'authors': [
+                'Robert Tibshirani'
+            ],
+            'doi': 'https://doi.org/10.1111/j.2517-6161.1996.tb02080.x',
+            'publisher': 'Journal of the Royal Statistical Society Series B'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration = {
+            'alpha': {
+                'description': 'Regularization strength.',
+                'default': 1.0,
+                'range': [1e-04, 10.0]
+            },
+            'fit_intercept': {
+                'description': 'Whether to fit the intercept term.',
+                'default': True,
+                'categorical': [True, False]
+            },
+            'max_iter': {
+                'description': 'Maximum number of iterations.',
+                'default': 1000,
+                'range': [100, 5000]
+            },
+            'tol': {
+                'description': 'Stopping criterion.',
+                'default': 0.0001,
+                'range': [1e-05, 0.1]
+            },
+            'selection': {
+                'description': 'Coordinate descent selection strategy.',
+                'default': 'cyclic',
+                'categorical': ['cyclic', 'random']
+            },
+            'positive': {
+                'description': 'Force coefficients to be positive.',
+                'default': False,
+                'categorical': [True, False]
+            },
+            'random_state': {
+                'description': 'Random state used when selection is "random".',
+                'default': 42
+            }
+        }
+        self.model: Lasso = None
+        self.columns: list[str] = []
+
+    def _select_features(self, X):
+        if self.columns and hasattr(X, 'columns'):
+            return X[self.columns]
+        return X
+
+    def fit(self, dataset: Dataset): # pylint: disable=unused-argument
+        self.columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if not self.columns:
+            self.columns = dataset.features
+
+        self.model = Lasso(**self.passthrough_parameters())
+        self.model.fit(self._select_features(dataset.X), dataset.y)
+        return self
+
+    def predict(self, X):
+        return super().predict(self._select_features(X))
+
+    def score(self, X, y=None, *args, **kwargs):
+        return self.model.score(self._select_features(X), y, *args, **kwargs)
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return dataset.type_of_target == 'continuous' \
+            and bool(dataset.get_columns_names_by_type(DataType.NUMERIC))
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5 # neutral

iaml/actionables/predictors/regressor/act_light_gbm_regressor.py

@@ -0,0 +1,201 @@
+"""[STEP] LightGBM Regressor"""
+import textwrap
+from typing import Any
+
+try:
+    from lightgbm import LGBMRegressor
+    from lightgbm.basic import LightGBMError
+    _LGBM_ERRORS: tuple[type[Exception], ...] = (LightGBMError,)
+except ImportError:  # pragma: no cover - optional dependency
+    LGBMRegressor = None  # type: ignore
+    _LGBM_ERRORS = tuple()
+
+from ....predictor import Predictor
+from ....dataset import Dataset
+from ....candidate import Candidate
+from ....data_type import DataType
+from ....decorators.all import is_step
+
+
+@is_step('predictor', 'tabular', 'regressor')
+class ActLightGBMRegressor(Predictor):
+    """[STEP] LightGBM Regressor"""
+
+    name: str = "LightGBM Regressor"
+    _description: str = textwrap.dedent('''\
+        LightGBMRegressor is a gradient boosting algorithm that builds
+        decision trees efficiently for regression tasks.''')
+    _description_long: str = textwrap.dedent('''\
+        LightGBMRegressor trains an ensemble of decision trees using histogram-based
+        splits and leaf-wise growth. It is designed to be fast while preserving
+        accuracy on tabular regression problems.''')
+    _usage: str = "Use when you want tabular regression with mixed numeric/categorical and a booster alternative to ActCatBoostRegressor. Applicable to medium/large datasets with nonlinear interactions. Avoid when data is tiny or you need a simple linear model like ActARDRegression."
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 2017,
+            'name': 'LightGBM: A Highly Efficient Gradient Boosting Decision Tree',
+            'authors': [
+                'Guolin Ke',
+                'Qi Meng',
+                'Thomas Finley',
+                'Taifeng Wang',
+                'Wei Chen',
+                'Weidong Ma',
+                'Qiwei Ye',
+                'Tie-Yan Liu'
+            ],
+            'doi': 'https://doi.org/10.48550/arXiv.1712.01005',
+            'publisher': 'Advances in Neural Information Processing Systems 30 (NeurIPS 2017)'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration = {
+            'boosting_type': {
+                'description': 'Type of boosting algorithm.',
+                'default': 'gbdt',
+                'categorical': ['gbdt', 'dart']
+            },
+            'n_estimators': {
+                'description': 'Number of boosting iterations.',
+                'default': 200,
+                'range': [50, 1000]
+            },
+            'learning_rate': {
+                'description': 'Shrinkage rate applied to each tree.',
+                'default': 0.1,
+                'range': [0.01, 1.0]
+            },
+            'num_leaves': {
+                'description': 'Maximum number of leaves in one tree.',
+                'default': 31,
+                'range': [7, 255]
+            },
+            'max_depth': {
+                'description': 'Maximum depth of a tree, -1 means no limit.',
+                'default': -1,
+                'categorical': [-1, 3, 5, 10, 15]
+            },
+            'min_child_samples': {
+                'description': 'Minimum number of data in one leaf.',
+                'default': 20,
+                'range': [5, 200]
+            },
+            'subsample': {
+                'description': 'Fraction of data to use for each boosting iteration.',
+                'default': 1.0,
+                'range': [0.5, 1.0]
+            },
+            'subsample_freq': {
+                'description': 'Frequency for subsampling, 0 means disabled.',
+                'default': 0,
+                'range': [0, 10]
+            },
+            'colsample_bytree': {
+                'description': 'Fraction of features used for each tree.',
+                'default': 1.0,
+                'range': [0.5, 1.0]
+            },
+            'reg_alpha': {
+                'description': 'L1 regularization.',
+                'default': 0.0,
+                'range': [0.0, 1.0]
+            },
+            'reg_lambda': {
+                'description': 'L2 regularization.',
+                'default': 0.0,
+                'range': [0.0, 1.0]
+            },
+            'random_state': {
+                'description': 'Random seed for reproducibility.',
+                'default': 42
+            },
+            'verbosity': {
+                'description': 'Controls the level of LightGBM verbosity.',
+                'default': -1,
+                'categorical': [-1, 0, 1]
+            }
+        }
+        self.model: LGBMRegressor = None
+        self.columns: list[str] = []
+        self.categorical_columns: list[str] = []
+        self._category_levels: dict[str, list] = {}
+
+    def _select_features(self, X):
+        if self.columns and hasattr(X, 'columns'):
+            return X[self.columns]
+        return X
+
+    def _prepare_features(self, X, fit: bool = False):
+        X_selected = self._select_features(X)
+        if not hasattr(X_selected, 'copy'):
+            return X_selected
+        X_prepared = X_selected.copy()
+        if self.categorical_columns:
+            for column in self.categorical_columns:
+                if column not in X_prepared.columns:
+                    continue
+                X_prepared[column] = X_prepared[column].astype('category')
+                if not fit and column in self._category_levels:
+                    X_prepared[column] = X_prepared[column].cat.set_categories(
+                        self._category_levels[column]
+                    )
+        if fit:
+            self._category_levels = {
+                column: list(X_prepared[column].cat.categories)
+                for column in self.categorical_columns
+                if column in X_prepared.columns and hasattr(X_prepared[column], 'cat')
+            }
+        return X_prepared
+
+    def fit(self, dataset: Dataset): # pylint: disable=unused-argument
+        if LGBMRegressor is None:
+            raise ImportError(
+                "lightgbm is required for ActLightGBMRegressor. "
+                "Install with: pip install lightgbm"
+            )
+
+        self.columns = dataset.get_columns_names_by_type(
+            [DataType.NUMERIC, DataType.CATEGORICAL]
+        )
+        if not self.columns:
+            self.columns = dataset.features
+        self.categorical_columns = dataset.get_columns_names_by_type(DataType.CATEGORICAL)
+
+        X_prepared = self._prepare_features(dataset.X, fit=True)
+        self.model = LGBMRegressor(**self.passthrough_parameters())
+
+        categorical_features = []
+        if self.categorical_columns and hasattr(X_prepared, 'columns'):
+            categorical_features = [
+                col for col in self.categorical_columns if col in X_prepared.columns
+            ]
+
+        try:
+            if categorical_features:
+                self.model.fit(
+                    X_prepared,
+                    dataset.y,
+                    categorical_feature=categorical_features
+                )
+            else:
+                self.model.fit(X_prepared, dataset.y)
+        except _LGBM_ERRORS as exc:
+            raise ValueError(f"LightGBMRegressor training failed: {exc}") from exc
+        return self
+
+    def predict(self, X):
+        return super().predict(self._prepare_features(X))
+
+    def score(self, X, y=None, *args, **kwargs):
+        return self.model.score(self._prepare_features(X), y, *args, **kwargs)
+
+    def suitable(self, dataset: Dataset) -> bool:
+        supported = dataset.get_columns_names_by_type(
+            [DataType.NUMERIC, DataType.CATEGORICAL]
+        )
+        return LGBMRegressor is not None and dataset.type_of_target in \
+            ['continuous'] and bool(supported)
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5 # neutral

iaml/actionables/predictors/regressor/act_linear_regression.py

@@ -0,0 +1,43 @@
+"""
+[STEP]  Linear Regression
+"""
+import textwrap
+from typing import Any
+from sklearn.linear_model import LinearRegression
+from ....predictor import Predictor
+from ....dataset import Dataset
+from ....candidate import Candidate
+from ....decorators.all import is_step
+
+@is_step('predictor', 'tabular', 'fast_predictor', 'regressor', 'baseline_predictor')
+class ActLinearRegression(Predictor):
+    """[STEP] Linear Regression"""
+
+    name: str = "Linear Regression"
+    _description: str = textwrap.dedent('''\
+        LinearRegression is a machine learning algorithm that models the
+        relationship between input features and a continuous output variable using
+        a linear function.''')
+    _description_long: str = textwrap.dedent('''\
+        LinearRegression is a type of regression algorithm that models
+        the relationship between input features and a continuous output variable using
+        a linear function. It works by finding the best-fitting line or hyperplane
+        that minimizes the sum of the squared differences between the predicted
+        and actual output variables.''')
+    _usage: str = "Use when you need a fast linear baseline before ActElasticNetRegressor or ActDecisionTreeRegressor. Applicable to tabular regression with roughly linear relationships. Avoid when strong nonlinearity, interactions, or heavy regularization is needed."
+    refs: list[dict[str, Any]] = []
+
+    def __init__(self):
+        self.model: LinearRegression = None
+
+    def fit(self, dataset: Dataset): # pylint: disable=unused-argument
+        self.model = LinearRegression()
+        self.model.fit(dataset.X, dataset.y)
+
+        return self
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return dataset.type_of_target == 'continuous'
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5 # neutral

iaml/actionables/predictors/regressor/act_mlp_regressor.py

@@ -0,0 +1,104 @@
+"""[STEP] MLP Regressor"""
+from typing import Any
+import textwrap
+from sklearn.neural_network import MLPRegressor
+from ....predictor import Predictor
+from ....dataset import Dataset
+from ....candidate import Candidate
+from ....decorators.all import is_step
+
+@is_step('predictor', 'tabular', 'regressor')
+class ActMLPRegressor(Predictor):
+    """[STEP] MLP Regressor"""
+
+    name: str = "MLP Regressor"
+    _usage: str = "Use when nonlinear tabular regression needs a flexible MLP, beyond ActElasticNetRegressor or ActDecisionTreeRegressor. Applicable to continuous targets with mostly numeric, scaled features. Avoid when data are tiny, mostly categorical, or you need fast/transparent models."
+    _description: str = textwrap.dedent('''\
+        MLPRegressor is a machine learning algorithm that models the
+        relationship between input features and a continuous output variable using
+        a multi-layer perceptron neural network.''')
+    _description_long: str = textwrap.dedent('''\
+        MLPRegressor is a type of neural network algorithm that models
+        the relationship between input features and a continuous output variable using a
+        multi-layer perceptron (MLP) neural network.
+        It works by transforming the input features through one or more hidden
+        layers with non-linear activation functions, and then using a final layer with
+        a linear activation function to output a continuous value.''')
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 1989,
+            'name': 'Connectionist Learning Procedures',
+            'authors': [
+                'Geoffrey E. Hinton'
+            ],
+            'doi': 'https://doi.org/10.1016/0004-3702(89)90049-0',
+            'publisher': 'Artificial intelligence Vol. 40.1 page 185--234'
+        },
+        {
+            'year': 2010,
+            'name': 'Understanding the difficulty of training deep feedforward neural networks',
+            'authors': [
+                'Xavier Glorot',
+                'Yoshua Bengio'
+            ],
+            'doi': '',
+            'publisher': (
+                'Proceedings of the Thirteenth International Conference on '
+                'Artificial Intelligence and Statistics page 249--256'
+            )
+        }
+    ]
+
+    def __init__(self):
+        self.configuration = {
+            'activation': {
+                'description': 'Activation function for the hidden layer.',
+                'default': 'relu',
+                'categorical': ["tanh", "relu"]
+            },
+            'alpha': {
+                'description': textwrap.dedent('''\
+                    Strength of the L2 regularization term. The L2
+                    regularization term is divided by the sample size when
+                    added to the loss.'''),
+                'default': 0.0001,
+                'range': [1e-07, 0.1]
+            },
+            'hidden_layer_count': {
+                'description': 'Number of hidden layer',
+                'default': 1,
+                'range': [1, 4],
+                'passthrough': False
+            },
+            'node_per_layer': {
+                'description': 'Number of node per layer',
+                'default': 32,
+                'range': [16, 256],
+                'passthrough': False
+            },
+            'learning_rate_init': {
+                'description': 'Learning rate schedule for weight updates',
+                'default': 0.001,
+                'range': [0.0001, 0.5]
+            }
+        }
+
+        self.model: MLPRegressor = None
+
+    def fit(self, dataset: Dataset): # pylint: disable=unused-argument
+        self.model = MLPRegressor(
+            hidden_layer_sizes=[self.get_config('node_per_layer') \
+                for i in range(self.get_config('hidden_layer_count'))],
+            early_stopping=True,
+            max_iter=400,
+            **self.passthrough_parameters())
+
+        self.model.fit(dataset.X, dataset.y)
+
+        return self
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return dataset.type_of_target == "continuous"
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5 # neutral

iaml/actionables/predictors/regressor/act_poisson_regressor.py

@@ -0,0 +1,111 @@
+"""[STEP] Poisson Regressor"""
+import textwrap
+from typing import Any
+
+import numpy as np
+from sklearn.linear_model import PoissonRegressor
+
+from ....predictor import Predictor
+from ....dataset import Dataset
+from ....candidate import Candidate
+from ....data_type import DataType
+from ....decorators.all import is_step
+
+
+@is_step('predictor', 'tabular', 'regressor')
+class ActPoissonRegressor(Predictor):
+    """[STEP] Poisson Regressor"""
+
+    name: str = "Poisson Regressor"
+    _description: str = textwrap.dedent('''\
+        PoissonRegressor models count targets using a log link and a Poisson
+        likelihood to produce positive predictions.''')
+    _description_long: str = textwrap.dedent('''\
+        Poisson regression is a generalized linear model designed for
+        non-negative count data. It connects predictors to the expected
+        count through a log link, which keeps predictions positive and
+        is appropriate when variance grows with the mean.''')
+    _usage: str = "Use when modeling non-negative count targets with variance rising with mean, as a simpler option than ActElasticNetRegressor or ActDecisionTreeRegressor. Applicable to tabular numeric features with count outcomes. Avoid when targets are continuous, negative, or highly zero-inflated."
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 1972,
+            'name': 'Generalized Linear Models',
+            'authors': [
+                'John A. Nelder',
+                'Robert W. M. Wedderburn'
+            ],
+            'doi': 'https://doi.org/10.2307/2344614',
+            'publisher': 'Journal of the Royal Statistical Society, Series A'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration = {
+            'alpha': {
+                'description': 'L2 regularization strength.',
+                'default': 1.0,
+                'range': [1e-06, 10.0]
+            },
+            'fit_intercept': {
+                'description': 'Whether to fit the intercept term.',
+                'default': True,
+                'categorical': [True, False]
+            },
+            'max_iter': {
+                'description': 'Maximum number of iterations.',
+                'default': 100,
+                'range': [50, 2000]
+            },
+            'tol': {
+                'description': 'Stopping criterion.',
+                'default': 0.0001,
+                'range': [1e-06, 0.1]
+            },
+            'warm_start': {
+                'description': 'Reuse solution from the previous fit.',
+                'default': False,
+                'categorical': [True, False]
+            }
+        }
+        self.model: PoissonRegressor = None
+        self.columns: list[str] = []
+
+    def _select_features(self, X):
+        if self.columns and hasattr(X, 'columns'):
+            return X[self.columns]
+        return X
+
+    def _is_count_target(self, y) -> bool:
+        y_array = np.asarray(y)
+        if y_array.size == 0:
+            return False
+        if not np.issubdtype(y_array.dtype, np.number):
+            return False
+        if not np.isfinite(y_array).all():
+            return False
+        if (y_array < 0).any():
+            return False
+        return np.allclose(y_array, np.round(y_array), rtol=0, atol=1e-06)
+
+    def fit(self, dataset: Dataset): # pylint: disable=unused-argument
+        self.columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if not self.columns:
+            self.columns = dataset.features
+
+        self.model = PoissonRegressor(**self.passthrough_parameters())
+        self.model.fit(self._select_features(dataset.X), dataset.y)
+        return self
+
+    def predict(self, X):
+        return super().predict(self._select_features(X))
+
+    def score(self, X, y=None, *args, **kwargs):
+        return self.model.score(self._select_features(X), y, *args, **kwargs)
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return dataset.type_of_target == 'continuous' \
+            and bool(dataset.get_columns_names_by_type(DataType.NUMERIC)) \
+            and self._is_count_target(dataset.y)
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5 # neutral

iaml/actionables/predictors/regressor/act_quantile_regressor.py

@@ -0,0 +1,87 @@
+"""[STEP] Quantile Regressor"""
+import textwrap
+from typing import Any
+
+from sklearn.linear_model import QuantileRegressor
+
+from ....predictor import Predictor
+from ....dataset import Dataset
+from ....candidate import Candidate
+from ....data_type import DataType
+from ....decorators.all import is_step
+
+
+@is_step('predictor', 'tabular', 'regressor')
+class ActQuantileRegressor(Predictor):
+    """[STEP] Quantile Regressor"""
+
+    name: str = "Quantile Regressor"
+    _usage: str = "Use when you need conditional quantiles or asymmetric error control; choose over ActElasticNetRegressor for interval focus. Applicable to tabular regression with continuous targets and numeric inputs. Avoid when mean prediction is enough or nonlinear structure dominates."
+    _description: str = textwrap.dedent('''\
+        QuantileRegressor estimates a conditional quantile of a continuous target,
+        enabling interval-style predictions and asymmetric error handling.''')
+    _description_long: str = textwrap.dedent('''\
+        Quantile regression models a chosen quantile of the response rather than the
+        mean, which makes it useful for prediction intervals and robust modeling.
+        By selecting different quantiles, the model can describe the uncertainty
+        around the target distribution.''')
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 1978,
+            'name': 'Regression Quantiles',
+            'authors': [
+                'Roger Koenker',
+                'Gilbert Bassett Jr.'
+            ],
+            'doi': 'https://doi.org/10.2307/1913643',
+            'publisher': 'Econometrica'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration = {
+            'quantile': {
+                'description': 'Quantile to estimate between 0 and 1.',
+                'default': 0.5,
+                'range': [0.05, 0.95]
+            },
+            'alpha': {
+                'description': 'L1 regularization strength.',
+                'default': 1.0,
+                'range': [1e-06, 10.0]
+            },
+            'fit_intercept': {
+                'description': 'Whether to fit the intercept term.',
+                'default': True,
+                'categorical': [True, False]
+            }
+        }
+        self.model: QuantileRegressor = None
+        self.columns: list[str] = []
+
+    def _select_features(self, X):
+        if self.columns and hasattr(X, 'columns'):
+            return X[self.columns]
+        return X
+
+    def fit(self, dataset: Dataset): # pylint: disable=unused-argument
+        self.columns = dataset.get_columns_names_by_type(DataType.NUMERIC)
+        if not self.columns:
+            self.columns = dataset.features
+
+        self.model = QuantileRegressor(**self.passthrough_parameters())
+        self.model.fit(self._select_features(dataset.X), dataset.y)
+        return self
+
+    def predict(self, X):
+        return super().predict(self._select_features(X))
+
+    def score(self, X, y=None, *args, **kwargs):
+        return self.model.score(self._select_features(X), y, *args, **kwargs)
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return dataset.type_of_target == 'continuous' \
+            and bool(dataset.get_columns_names_by_type(DataType.NUMERIC))
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5 # neutral