PyIAML 1.0.0__py3-none-any.whl

iaml/actionables/predictors/survival/act_aalen_additive_model.py

@@ -0,0 +1,83 @@
+"""Experimental Aalen adapter, available only through an explicit module import.
+
+Requires the optional, undeclared lifelines dependency. Parameter forwarding and
+the time-by-sample hazard output do not implement IAML's predictor contract yet.
+Excluded from automatic model selection; see docs/component_status.rst.
+"""
+import textwrap
+from typing import Any
+from lifelines import AalenAdditiveFitter
+import pandas as pd
+
+from ....predictor import Predictor
+from ....candidate import Candidate
+from ....dataset import Dataset
+from ....decorators.all import is_step
+
+
+@is_step('experimental')
+class ActAalenAdditiveFitter(Predictor):
+    """[STEP] Aalen's Additive Model for Survival Analysis"""
+
+    name: str = "AalenAdditiveFitter"
+    _usage: str = "Use when effects change over time and you want an additive alternative to ActCox. Applicable to tabular survival data with event/time and censoring. Avoid when hazards are time-constant or nonlinear interactions favor ActRandomSurvivalForest."
+    _description: str = textwrap.dedent('''\
+        Aalen's Additive Model is a semi-parametric survival analysis model
+        that estimates survival time as a function of covariates, using a linear combination
+        of time-varying covariate effects. The additive nature of the model allows it to
+        account for time-varying effects of covariates on the hazard function.''')
+    _description_long: str = textwrap.dedent('''\
+        Aalen's Additive Model is a flexible alternative to the Cox
+        Proportional Hazards model, providing time-varying covariate effects. The model
+        uses an additive approach to model the hazard function, making fewer assumptions
+        than proportional hazards models. It is particularly useful in situations where
+        covariate effects are expected to vary over time, and efficiently handles censored
+        data. The model estimates a baseline hazard function and additive contributions
+        of covariates, allowing for a more dynamic understanding of survival probabilities
+        over time.''')
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 2001,
+            'name': 'Aalen’s Additive Model',
+            'authors': [
+                'O. Borgan',
+                'J. Aalen',
+                'H. Fekjær'
+            ],
+            'doi': 'https://doi.org/10.1007/978-1-4757-3462-1_4',
+            'publisher': 'Survival and Event History Analysis, pages 109-142'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration: dict = {
+            'penalizer': {
+                'description': 'The penalizer controls the amount of L2 regularization.',
+                'default': 0.0,
+                'range': [0.0, 1.0],
+                'passthrough': False
+            }
+        }
+        self.model: AalenAdditiveFitter = None
+
+    def fit(self, dataset: Dataset):  # pylint: disable=unused-argument
+        self.model = AalenAdditiveFitter(
+            **self.passthrough_parameters()
+        )
+
+        y = pd.DataFrame(list(dataset.y), columns=['event', 'time'])
+        merged = dataset.X.reset_index(drop=True).join(y.reset_index(drop=True))
+        self.model.fit(merged, 'time', 'event')
+        return self
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return dataset.type_of_target == 'survival'
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5  # neutral
+
+    def predict(self, X: pd.DataFrame) -> list[float]:
+        results = self.model.predict_cumulative_hazard(X)
+        if hasattr(self, 'label_encoder'):
+            return self.label_encoder.inverse_transform(results)
+        return results

iaml/actionables/predictors/survival/act_cox.py

@@ -0,0 +1,110 @@
+
+"""[STEP]  Cox"""
+import textwrap
+from typing import Any
+from sksurv.linear_model import CoxPHSurvivalAnalysis
+
+from ....predictor import Predictor
+from ....candidate import Candidate
+from ....dataset import Dataset
+from ....decorators.all import is_step
+
+
+@is_step('predictor', 'tabular', 'survival')
+class ActCox(Predictor):
+    """[STEP]  Cox"""
+
+    name: str = "CoxPHSurvivalAnalysis"
+    _description: str = textwrap.dedent('''\
+        CoxPHSurvivalAnalysis is a survival analysis algorithm
+        that estimates the effect of covariates on the likelihood of an event
+        occurring over time, using the Cox proportional hazards model.''')
+    _description_long: str = textwrap.dedent('''\
+        CoxPHSurvivalAnalysis is a survival analysis method
+        that models the relationship between multiple input features (covariates)
+        and the time until a particular event happens. The algorithm is based on
+        the Cox proportional hazards model, which assumes that the hazard or risk
+        of an event is a product of a baseline hazard and a factor that depends on
+        the covariates. This model is commonly used in medical research to study
+        how factors such as age, treatment, or health conditions influence survival
+        rates, or in engineering to predict equipment failure. Unlike many other
+        models, it doesn't predict the exact time of the event but estimates the
+        risk over time, handling cases where the event has not yet occurred (censored data).''')
+    _usage: str = "Use when you need a Cox model; compare ActCoxnetSurvivalAnalysis for regularization or ActRandomSurvivalForest for nonlinearity. Applicable to tabular survival data with censoring and proportional hazards. Avoid when hazards are non-proportional or interactions dominate."
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 1972,
+            'name': 'Regression models and life tables',
+            'authors': [
+                'D. R. Cox'
+            ],
+            'doi': 'https://doi.org/10.1111/j.2517-6161.1972.tb00899.x',
+            'publisher': 'Journal of the Royal Statistical Society. Series B, 34: page 187-220'
+        },
+        {
+            'year': 1974,
+            'name': 'Covariance Analysis of Censored Survival Data',
+            'authors': [
+                'N. E. Breslow'
+            ],
+            'doi': 'https://doi.org/10.2307/2287816',
+            'publisher': 'Biometrics, 30: page 89-99'
+        },
+        {
+            'year': 1977,
+            'name': 'The Efficiency of Cox’s Likelihood Function for Censored Data',
+            'authors': [
+                'B. Efron'
+            ],
+            'doi': 'https://doi.org/10.1007/978-0-387-75692-9_6',
+            'publisher': 'Journal of the American Statistical Association, 72: page 557-565'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration: dict = {
+            'alpha': {
+                'description': textwrap.dedent('''\
+                    Regularization strength. Higher values specify stronger
+                    regularization. alpha=0 means no regularization.'''),
+                'default': 1,
+                'range': [0, 100],
+                'passthrough': True
+            },
+            'ties': {
+                'description': textwrap.dedent('''\
+                    Method for handling tied event times in the data.
+                    "breslow" is the most common method.'''),
+                'default': 'breslow',
+                'categorical': ['breslow', 'efron']
+            },
+            'n_iter': {
+                'description': 'Maximum number of iterations for fitting the model.',
+                'default': 100,
+                'range': [1, 10000],
+                'passthrough': True
+            },
+            'tol': {
+                'description': textwrap.dedent('''\
+                    Tolerance for stopping criteria. Determines the precision
+                    of the solution.'''),
+                'default': 1e-09,
+                'range': [1e-12, 1e-03],
+                'passthrough': True
+            }
+        }
+        self.model: CoxPHSurvivalAnalysis = None
+
+    def fit(self, dataset: Dataset): # pylint: disable=unused-argument
+        self.model = CoxPHSurvivalAnalysis(
+            **self.passthrough_parameters()
+            )
+        X, y = dataset.to_survival()
+        self.model.fit(X, y)
+        return self
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return dataset.type_of_target == 'survival'
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5 # neutral

iaml/actionables/predictors/survival/act_coxnet_survival_analysis.py

@@ -0,0 +1,134 @@
+"""[STEP] Coxnet Survival Analysis"""
+import inspect
+import textwrap
+from typing import Any
+from sksurv.linear_model import CoxnetSurvivalAnalysis
+
+from ....predictor import Predictor
+from ....candidate import Candidate
+from ....dataset import Dataset
+from ....data_type import DataType
+from ....decorators.all import is_step
+
+
+@is_step('predictor', 'tabular', 'survival')
+class ActCoxnetSurvivalAnalysis(Predictor):
+    """[STEP] Coxnet Survival Analysis"""
+
+    name: str = "CoxnetSurvivalAnalysis"
+    _description: str = textwrap.dedent('''\
+        CoxnetSurvivalAnalysis fits a Cox proportional hazards model with
+        elastic-net regularization, combining L1 and L2 penalties to handle
+        high-dimensional survival data.''')
+    _description_long: str = textwrap.dedent('''\
+        CoxnetSurvivalAnalysis estimates a Cox proportional hazards model while
+        applying elastic-net regularization along a path of penalty strengths.
+        The L1 component encourages sparse feature selection, while the L2
+        component stabilizes coefficients when predictors are correlated. This
+        makes the model well suited for survival datasets with many variables
+        and right-censored observations.''')
+    _usage: str = "Use when you need regularized Cox with feature selection; compare ActCox or ActRandomSurvivalForest. Applicable to tabular survival data with many numeric, correlated predictors. Avoid when effects are highly nonlinear or inputs are mostly categorical."
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 2011,
+            'name': "Regularization Paths for Cox's Proportional Hazards Model \
+                via Coordinate Descent",
+            'authors': [
+                'Noah Simon',
+                'Jerome Friedman',
+                'Trevor Hastie',
+                'Robert Tibshirani'
+            ],
+            'doi': 'https://doi.org/10.18637/jss.v039.i05',
+            'publisher': 'Journal of Statistical Software, 39(5)'
+        },
+        {
+            'year': 2005,
+            'name': 'Regularization and Variable Selection via the Elastic Net',
+            'authors': [
+                'Hui Zou',
+                'Trevor Hastie'
+            ],
+            'doi': 'https://doi.org/10.1111/j.1467-9868.2005.00503.x',
+            'publisher': 'Journal of the Royal Statistical Society Series B'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration: dict = {
+            'l1_ratio': {
+                'description': 'Mixing parameter between L1 and L2 penalty.',
+                'default': 0.5,
+                'range': [0.0, 1.0]
+            },
+            'n_alphas': {
+                'description': 'Number of alpha values along the regularization path.',
+                'default': 100,
+                'range': [10, 200]
+            },
+            'alpha_min_ratio': {
+                'description': textwrap.dedent('''\
+                    Smallest alpha as a fraction of alpha_max for the regularization
+                    path.'''),
+                'default': 0.01,
+                'range': [1e-04, 1.0]
+            },
+            'max_iter': {
+                'description': 'Maximum number of coordinate descent iterations.',
+                'default': 1000,
+                'range': [100, 100000]
+            },
+            'tol': {
+                'description': 'Stopping criterion.',
+                'default': 1e-07,
+                'range': [1e-09, 1e-03]
+            },
+            'fit_baseline_model': {
+                'description': textwrap.dedent('''\
+                    Fit baseline hazard models to enable survival function
+                    predictions.'''),
+                'default': False,
+                'categorical': [True, False]
+            }
+        }
+        self.model: CoxnetSurvivalAnalysis = None
+        self.columns: list[str] = []
+
+    def _select_features(self, X):
+        if self.columns and hasattr(X, 'columns'):
+            return X[self.columns]
+        return X
+
+    def _model_parameters(self) -> dict[str, Any]:
+        params = self.passthrough_parameters()
+        sig_params = inspect.signature(CoxnetSurvivalAnalysis).parameters
+        return {key: value for key, value in params.items() if key in sig_params}
+
+    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 = CoxnetSurvivalAnalysis(**self._model_parameters())
+        X, y = dataset.to_survival()
+        self.model.fit(self._select_features(X), y)
+        return self
+
+    def predict(self, X):
+        return super().predict(self._select_features(X))
+
+    def predict_survival_function(self, X):
+        return super().predict_survival_function(self._select_features(X))
+
+    def predict_cumulative_hazard_function(self, X):
+        return super().predict_cumulative_hazard_function(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 == 'survival' \
+            and bool(dataset.get_columns_names_by_type(DataType.NUMERIC))
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5  # neutral

iaml/actionables/predictors/survival/act_extra_survival_trees.py

@@ -0,0 +1,101 @@
+"""[STEP] Extra Survival Trees"""
+import textwrap
+from typing import Any
+from sksurv.ensemble import ExtraSurvivalTrees
+
+from ....predictor import Predictor
+from ....candidate import Candidate
+from ....dataset import Dataset
+from ....decorators.all import is_step
+
+
+@is_step('predictor', 'tabular', 'survival')
+class ActExtraSurvivalTrees(Predictor):
+    """[STEP] Extra Survival Trees"""
+    name: str = "ExtraSurvivalTrees"
+    _usage: str = "Use when you want a randomized tree ensemble for survival, as an alternative to ActRandomSurvivalForest. Applicable to tabular censored survival data with nonlinear feature effects. Avoid when you need proportional-hazards interpretability like ActCox or data is very small."
+    _description: str = textwrap.dedent('''\
+        ExtraSurvivalTrees is an ensemble learning method for survival
+        analysis based on extremely randomized trees. It fits multiple decision trees
+        to the data, where each tree is built from a random subset of features and
+        splits are selected randomly. This method provides more variance reduction
+        and robustness, especially useful when dealing with high-dimensional or
+        sparse data.''')
+    _description_long: str = textwrap.dedent('''\
+        ExtraSurvivalTrees is a variant of ensemble learning for survival
+        analysis that uses extremely randomized trees. In this approach, multiple trees
+        are grown by selecting random subsets of features and splitting points.
+        Compared to other tree-based methods, this randomness helps reduce overfitting
+        and increases model robustness. The method is particularly useful for survival
+        datasets that contain complex, non-linear relationships between features.
+        ExtraSurvivalTrees handles censored data and can provide interpretable models
+        for survival time predictions.''')
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 2006,
+            'name': 'Extremely Randomized Trees',
+            'authors': [
+                'P. Geurts',
+                'D. Ernst',
+                'L. Wehenkel'
+            ],
+            'doi': 'https://doi.org/10.1007/s10994-006-6226-1',
+            'publisher': 'Machine Learning, 63(1), 3-42'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration: dict = {
+            'n_estimators': {
+                'description': 'The number of trees in the forest.',
+                'default': 100,
+                'range': [1, 1000],
+                'passthrough': True
+            },
+            'max_depth': {
+                'description': 'The maximum depth of the trees.',
+                'default': None,
+                'range': [1, None],
+                'passthrough': True
+            },
+            'min_samples_split': {
+                'description': 'The minimum number of samples required to split an internal node.',
+                'default': 2,
+                'range': [2, 20],
+                'passthrough': True
+            },
+            'min_samples_leaf': {
+                'description': 'The minimum number of samples required to be at a leaf node.',
+                'default': 1,
+                'range': [1, 20],
+                'passthrough': True
+            },
+            'max_features': {
+                'description': textwrap.dedent('''\
+                    The number of features to consider when looking for the
+                    best split.'''),
+                'default': "sqrt",
+                'categorical': ["sqrt", "log2", None],
+                'passthrough': True
+            },
+            'random_state': {
+                'description': 'Random seed (integer or None) for the estimator.',
+                'default': None,
+                'passthrough': True
+            }
+        }
+        self.model: ExtraSurvivalTrees = None
+
+    def fit(self, dataset: Dataset):  # pylint: disable=unused-argument
+        self.model = ExtraSurvivalTrees(
+            **self.passthrough_parameters()
+        )
+        X, y = dataset.to_survival()
+        self.model.fit(X, y)
+        return self
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return dataset.type_of_target == 'survival'
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5  # neutral

iaml/actionables/predictors/survival/act_fast_survival_svm.py

@@ -0,0 +1,102 @@
+"""[STEP] Fast Survival SVM"""
+import inspect
+import textwrap
+from typing import Any
+from sksurv.svm import FastSurvivalSVM
+
+from ....predictor import Predictor
+from ....candidate import Candidate
+from ....dataset import Dataset
+from ....data_type import DataType
+from ....decorators.all import is_step
+
+
+@is_step('predictor', 'tabular', 'survival')
+class ActFastSurvivalSVM(Predictor):
+    """[STEP] Fast Survival SVM"""
+
+    name: str = "FastSurvivalSVM"
+    _usage: str = "Use when you want a fast linear ranking model for survival risk, as a simpler alternative to ActCox. Applicable to right-censored tabular survival data with mostly numeric features. Avoid when nonlinear effects or interactions dominate; prefer ActRandomSurvivalForest."
+    _description: str = textwrap.dedent('''\
+        FastSurvivalSVM is a linear support vector machine for survival analysis
+        that learns a risk score using hinge-style ranking losses adapted to
+        censored data.''')
+    _description_long: str = textwrap.dedent('''\
+        FastSurvivalSVM optimizes a pairwise ranking objective so that samples
+        with earlier events receive higher risk scores. The loss is based on
+        hinge-style constraints adapted to right-censored observations, and a
+        rank_ratio parameter can blend ranking and regression terms. The model
+        is linear and efficient, making it suitable for larger tabular datasets
+        where fast, deterministic training is desired.''')
+
+    def __init__(self):
+        self.configuration: dict = {
+            'alpha': {
+                'description': textwrap.dedent('''\
+                    Regularization strength. Higher values enforce stronger
+                    regularization.'''),
+                'default': 1.0,
+                'range': [1e-04, 100.0]
+            },
+            'rank_ratio': {
+                'description': textwrap.dedent('''\
+                    Weighting between ranking and regression losses. 1.0 uses
+                    pure ranking; 0.0 uses pure regression.'''),
+                'default': 1.0,
+                'range': [0.0, 1.0]
+            },
+            'fit_intercept': {
+                'description': 'Whether to fit the intercept term.',
+                'default': True,
+                'categorical': [True, False]
+            },
+            'max_iter': {
+                'description': 'Maximum number of iterations for the optimizer.',
+                'default': 200,
+                'range': [10, 5000]
+            },
+            'tol': {
+                'description': 'Stopping tolerance.',
+                'default': 1e-05,
+                'range': [1e-08, 1e-02]
+            },
+            'random_state': {
+                'description': 'Random state for reproducibility.',
+                'default': 42
+            }
+        }
+        self.model: FastSurvivalSVM = None
+        self.columns: list[str] = []
+
+    def _select_features(self, X):
+        if self.columns and hasattr(X, 'columns'):
+            return X[self.columns]
+        return X
+
+    def _model_parameters(self) -> dict[str, Any]:
+        params = self.passthrough_parameters()
+        sig_params = inspect.signature(FastSurvivalSVM).parameters
+        return {key: value for key, value in params.items() if key in sig_params}
+
+    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 = FastSurvivalSVM(**self._model_parameters())
+        X, y = dataset.to_survival()
+        self.model.fit(self._select_features(X), 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 == 'survival' \
+            and bool(dataset.get_columns_names_by_type(DataType.NUMERIC))
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5  # neutral

iaml/actionables/predictors/survival/act_gradient_boosting_survival_analysis.py

@@ -0,0 +1,93 @@
+"""[STEP] Gradient Boosting Survival Analysis"""
+import textwrap
+from typing import Any
+from sksurv.ensemble import GradientBoostingSurvivalAnalysis
+
+from ....predictor import Predictor
+from ....candidate import Candidate
+from ....dataset import Dataset
+from ....decorators.all import is_step
+
+
+@is_step('predictor', 'tabular', 'survival', 'minimal_predictor')
+class ActGradientBoostingSurvivalAnalysis(Predictor):
+    """[STEP] Gradient Boosting Survival Analysis"""
+
+    name: str = "GradientBoostingSurvivalAnalysis"
+    _usage: str = "Use when you need non-linear survival modeling and ActCox underfits. Applicable to tabular time-to-event data with right-censoring. Avoid when you need simpler baselines or strong ensembles like ActRandomSurvivalForest."
+    _description: str = textwrap.dedent('''\
+        GradientBoostingSurvivalAnalysis is a survival analysis algorithm
+        that uses gradient boosting to model the risk of an event over time.
+        It fits an ensemble of regression trees to capture non-linear effects
+        and interactions in censored survival data.''')
+    _description_long: str = textwrap.dedent('''\
+        GradientBoostingSurvivalAnalysis extends gradient boosting to
+        time-to-event data by optimizing a survival-specific loss function.
+        The model builds an ensemble of shallow regression trees, each correcting
+        the errors of the previous ones, resulting in a flexible estimator for
+        complex covariate effects. It can handle right-censored observations and
+        is useful when proportional hazards assumptions are too restrictive.''')
+    refs: list[dict[str, Any]] = [
+        {
+            'year': 2010,
+            'name': 'Gradient boosting for survival analysis',
+            'authors': [
+                'Chen, Yifei',
+                'Jia, Zhenyu',
+                'Mercola, Dan',
+                'Xie, Xiaohui'
+            ],
+            'doi': 'https://doi.org/10.1155/2013/873595',
+            'publisher': 'Advances in Data Analysis, Data Handling and Business Intelligence, \
+                pages 239-248'
+        }
+    ]
+
+    def __init__(self):
+        self.configuration: dict = {
+            'n_estimators': {
+                'description': 'Number of boosting stages to be run.',
+                'default': 100,
+                'range': [1, 1000],
+                'passthrough': True
+            },
+            'learning_rate': {
+                'description': 'Learning rate shrinks the contribution of each tree by this value.',
+                'default': 0.1,
+                'range': [0.01, 1.0],
+                'passthrough': True
+            },
+            'max_depth': {
+                'description': 'The maximum depth of the individual trees.',
+                'default': 3,
+                'range': [1, 20],
+                'passthrough': True
+            },
+            'min_samples_split': {
+                'description': 'The minimum number of samples required to split an internal node.',
+                'default': 2,
+                'range': [2, 20],
+                'passthrough': True
+            },
+            'min_samples_leaf': {
+                'description': 'The minimum number of samples required to be at a leaf node.',
+                'default': 1,
+                'range': [1, 20],
+                'passthrough': True
+            }
+        }
+        self.model: GradientBoostingSurvivalAnalysis = None
+
+    def fit(self, dataset: Dataset):  # pylint: disable=unused-argument
+        self.model = GradientBoostingSurvivalAnalysis(
+            **self.passthrough_parameters()
+        )
+        X, y = dataset.to_survival()
+        self.model.fit(X, y)
+        return self
+
+    def suitable(self, dataset: Dataset) -> bool:
+        return dataset.type_of_target == 'survival'
+
+    def priorize(self, candidate: Candidate = None) -> float:
+        return 0.5  # neutral