scentree 0.0.1__py3-none-any.whl

scentree/config/__init__.py

@@ -0,0 +1 @@
+explained_var = 0.8

scentree/dim_reduction/pca.py

@@ -0,0 +1,86 @@
+import numpy as np
+from numpy.typing import NDArray
+from pydantic import BaseModel, PrivateAttr
+from sklearn.decomposition import PCA
+from typing import cast, Optional, TypeVar
+
+R = TypeVar("R", bound="BasePCA")
+
+
+class BasePCA(BaseModel):
+    """
+    PCA wrapper around scikit-learn's PCA implementation.
+
+    This class encapsulates a scikit-learn PCA reducer and manages
+    it as an internal (non-validated, non-serialized) attribute.
+    """
+
+    _reducer: Optional[PCA] = PrivateAttr(default=None)
+
+    def transform(self, X: NDArray[np.float64]) -> NDArray[np.float64]:
+        """
+        Apply dimensionality reduction to a given matrix.
+
+        Args:
+            X (NDArray[np.float64]): Data to be reduced.
+
+        Raises:
+            RuntimeError: If the method has not been fitted previously
+                (i.e., `self._reducer` is None).
+
+        Returns:
+            NDArray[np.float64]: Data in the low-dimensional space.
+        """
+        if self._reducer is None:
+            raise RuntimeError("Model has not been fitted yet.")
+        return cast(NDArray[np.float64], self._reducer.transform(X))
+
+    def inverse_transform(self, X: NDArray[np.float64]) -> NDArray[np.float64]:
+        """
+        Apply inverse transformation to obtain data in the high-dimensional space.
+
+        Args:
+            X (NDArray[np.float64]): Data in the low-dimensional space.
+
+        Raises:
+            RuntimeError: If the method has not been fitted previously
+                (i.e., `self._reducer` is None).
+
+        Returns:
+            NDArray[np.float64]: Data in the low-dimensional space.
+        """
+        if self._reducer is None:
+            raise RuntimeError("Model has not been fitted yet.")
+        X_rec = cast(NDArray[np.float64], self._reducer.inverse_transform(X))
+        return X_rec
+
+    def fit_auto_components(
+        self,
+        X: NDArray[np.float64],
+        threshold: float,
+    ) -> NDArray[np.float64]:
+        """
+        Fit a PCA reducer automatically selecting the number of components
+        based on the explained variance threshold and transform the input data.
+
+        This method first fits a full PCA to compute the cumulative explained
+        variance. It then selects the smallest number of components such that
+        the cumulative variance exceeds the specified threshold. Finally, it
+        fits a PCA reducer with this number of components and transforms the data.
+
+        Args:
+            X (NDArray[np.float64]): Input feature matrix of shape (n_samples, n_features).
+            threshold (float): Desired cumulative explained variance ratio (between 0 and 1)
+                used to select the number of principal components.
+
+        Returns:
+            NDArray[np.float64]: Transformed input matrix with reduced dimensions based on
+                the automatically selected number of components.
+        """
+        pca_full = PCA()
+        pca_full.fit(X)
+        cumulative_variance = np.cumsum(pca_full.explained_variance_ratio_)
+        n_components_th = np.argmax(cumulative_variance >= threshold) + 1
+        self._reducer = PCA(n_components=n_components_th)
+        X_reduced = cast(NDArray[np.float64], self._reducer.fit_transform(X))
+        return X_reduced

scentree/estimators/estimator_orchestrator.py

@@ -0,0 +1,245 @@
+import numpy as np
+from numpy.typing import NDArray
+from pydantic import BaseModel
+from scentree.estimators.ridge import RidgeEstimator
+from scentree.estimators.var import VarEstimator
+from sklearn.model_selection import BaseCrossValidator
+from tqdm.auto import tqdm
+from typing import Any, cast, ClassVar, List, Optional, Protocol, Self, Type, TypeVar, Union
+
+R = TypeVar("R", bound="EstimatorController")
+
+
+class EstimatorProtocol(Protocol):
+    """
+    Protocol defining the minimal interface required for an estimator.
+
+    This protocol standardizes the expected behavior for models that support
+    prediction, residual estimation, cross-validation fitting, in-sample and
+    out-of-sample estimation, and scoring.
+    """
+
+    def predict(self, X: NDArray[np.float64]) -> NDArray[np.float64]:
+        """Generate predictions.
+
+        Args:
+            X (NDArray[np.float64]): Input feature matrix for prediction.
+
+        Returns:
+            NDArray[np.float64]: Predicted target values.
+        """
+        ...
+
+    def estimate_residuals(self, X: NDArray[np.float64]) -> NDArray[np.float64]:
+        """
+        Estimate residuals.
+
+        Args:
+            X (NDArray[np.float64]): Input feature matrix for prediction. This
+                matrix is used as the true values.
+
+        Returns:
+            NDArray[np.float64]: Residuals.
+        """
+        ...
+
+    def fit_cv(
+        self,
+        X: NDArray[np.float64],
+        y: Optional[NDArray[np.float64]],
+        cv: Union[int, BaseCrossValidator],
+    ) -> Self:
+        """
+        Fit an estmator using cross-validation.
+
+        Args:
+            X (NDArray[np.float64]): Input feature matrix.
+            y (Optional[NDArray[np.float64]]): Target value.
+            cv (Union[int, BaseCrossValidator]): Number of folds (if int) or a
+                scikit-learn compatible cross-validator instance defining
+                the splitting strategy.
+
+        Returns:
+            Self: The fitted estimator instance.
+        """
+        ...
+
+    def in_sample_estimation(self, steps: int) -> NDArray[np.float64]:
+        """
+        Generate in sample estimations.
+
+        Args:
+            steps (int): Number of estimated values to provide.
+
+        Returns:
+            NDArray[np.float64]: Matrix containing the estimated values.
+        """
+        ...
+
+    def out_sample_estimation(self, steps: int) -> NDArray[np.float64]:
+        """
+        Generate out sample estimations.
+
+        Args:
+            steps (int): Number of estimated values to provide.
+
+        Returns:
+            NDArray[np.float64]: Matrix containing the estimated values.
+        """
+        ...
+
+    def get_score(self, X: NDArray[np.float64]) -> float:
+        """
+        Compute the score metric using the data provided.
+
+        Args:
+            X (NDArray[np.float64]): Matrix containing the features.
+
+        Returns:
+            float: The scoring measure.
+        """
+        ...
+
+
+class EstimatorController(BaseModel):
+    """Controller class for managing and selecting estimators.
+
+    This class provides a mechanism to manage multiple estimator types.
+    It trains each estimator using the provided data, evaluates their
+    performance based on the scoring measure.
+
+    Attributes:
+        estimator_classes (ClassVar[List[Type]]): A list of estimator classes to be
+            evaluated.
+        best_estimator (Optional[Any]): The best estimator.
+    """
+
+    estimator_classes: ClassVar[List[Type]] = [RidgeEstimator, VarEstimator]
+    best_estimator: Optional[Any] = None
+
+    def get_score(self, X: NDArray[np.float64], estimator: EstimatorProtocol) -> float:
+        """
+        Compute the score metric using the data provided.
+
+        Args:
+            X (NDArray[np.float64]): Matrix containing the features.
+            estimator (EstimatorProtocol): The estimator to be evaluated.
+
+        Returns:
+            float: The scoring measure.
+        """
+        score = estimator.get_score(X)
+        return score
+
+    def fit(
+        self: R,
+        X: NDArray[np.float64],
+        cv: Union[int, BaseCrossValidator] = 5,
+    ) -> R:
+        """Train an estimator.
+
+        Args:
+            X (NDArray[np.float64]): Input feature matrix for prediction.
+            cv (Union[int, BaseCrossValidator]): Cross-validation configuration.
+                Defaults to 5.
+
+        Raises:
+            ValueError: If no estimator is selected (i.e., `estimator_chosen` is None).
+
+        Returns:
+            EstimatorController: The fitted estimator.
+        """
+        best_score = None
+        estimator_chosen = None
+        iterator = tqdm(
+            self.estimator_classes,
+            desc="Evaluating estimators",
+            disable=False,
+        )
+        for EstimatorClass in iterator:
+            iterator.set_postfix(estimator=EstimatorClass.__name__)
+            # Instantiate the estimator
+            estimator = EstimatorClass()
+            estimator.fit_cv(X=X, cv=cv)
+            # Compute score
+            score = self.get_score(X=X, estimator=estimator)
+            if (best_score is None) or (best_score is not None and score < best_score):
+                estimator_chosen = estimator
+                best_score = score
+        # Evaluate the estimator in the test set
+        if estimator_chosen is None:
+            raise ValueError("`estimator_chosen` is None")
+        self.best_estimator = estimator_chosen
+        return self
+
+    def predict(self, X: NDArray[np.float64]) -> NDArray[np.float64]:
+        """Generate predictions.
+
+        Args:
+            X (NDArray[np.float64]): Input feature matrix for prediction.
+
+        Raises:
+            ValueError: If the estimator has not been previously fitted
+                (i.e., `self.best_estimator` is None).
+
+        Returns:
+            NDArray[np.float64]: Predicted target values.
+        """
+        if self.best_estimator is None:
+            raise ValueError("You must call `fit()` before `predict()`.")
+        return cast(NDArray[np.float64], self.best_estimator.predict(X))
+
+    def estimate_residuals(self, X: NDArray[np.float64]) -> NDArray[np.float64]:
+        """
+        Estimate residuals.
+
+        Args:
+            X (NDArray[np.float64]): Input feature matrix for prediction. This
+                matrix is used as the true values.
+
+        Raises:
+            ValueError: If the estimator has not been previously fitted
+                (i.e., `self.best_estimator` is None).
+
+        Returns:
+            NDArray[np.float64]: Residuals.
+        """
+        if self.best_estimator is None:
+            raise ValueError("You must call `fit()` before `estimate_residuals()`.")
+        return cast(NDArray[np.float64], self.best_estimator.estimate_residuals(X))
+
+    def in_sample_estimation(self, steps: int) -> NDArray[np.float64]:
+        """
+        Generate in sample estimations.
+
+        Args:
+            steps (int): Number of estimated values to provide.
+
+        Raises:
+            ValueError: If the estimator has not been previously fitted
+                (i.e., `self.best_estimator` is None).
+
+        Returns:
+            NDArray[np.float64]: Matrix containing the estimated values.
+        """
+        if self.best_estimator is None:
+            raise ValueError("You must call `fit()` before `in_sample_estimation()`.")
+        return cast(NDArray[np.float64], self.best_estimator.in_sample_estimation(steps))
+
+    def out_sample_estimation(self, steps: int) -> NDArray[np.float64]:
+        """
+        Generate out sample estimations.
+
+        Args:
+            steps (int): Number of estimated values to provide.
+
+        Raises:
+            ValueError: If the estimator has not been previously fitted
+                (i.e., `self.best_estimator` is None).
+
+        Returns:
+            NDArray[np.float64]: Matrix containing the estimated values.
+        """
+        if self.best_estimator is None:
+            raise ValueError("You must call `fit()` before `out_sample_estimation()`.")
+        return cast(NDArray[np.float64], self.best_estimator.out_sample_estimation(steps))

scentree/estimators/ridge.py

@@ -0,0 +1,18 @@
+from scentree.estimators.scikit_base import SklearnEstimator
+from sklearn.base import BaseEstimator
+from sklearn.linear_model import Ridge
+from typing import Optional, Type
+
+
+class RidgeEstimator(SklearnEstimator):
+    """Wrapper for the scikit-learn `Ridge` regression estimator.
+
+    Args:
+    estimator_class (Optional[Type[BaseEstimator]]): Estimator class to wrap.
+        Defaults to `sklearn.linear_model.Ridge`.
+    """
+
+    def __init__(self, estimator_class: Optional[Type[BaseEstimator]] = None):
+        if estimator_class is None:
+            estimator_class = Ridge
+        super().__init__(estimator_class=estimator_class)

scentree/estimators/scikit_base.py

@@ -0,0 +1,255 @@
+import numpy as np
+from numpy.typing import NDArray
+from scentree.estimators.utils import get_default_parameters, get_hyperparameters_space
+from scentree.metrics.rmse import rmse
+from sklearn.base import BaseEstimator
+from sklearn.metrics import make_scorer
+from sklearn.model_selection import GridSearchCV, TimeSeriesSplit
+from sklearn.model_selection._split import _BaseKFold
+from typing import cast, Any, Dict, Optional, Type, TypeVar, Union
+
+R = TypeVar("R", bound="SklearnEstimator")
+
+
+class SklearnEstimator(BaseEstimator):
+    """
+    Wrapper class for scikit-learn estimators to integrate them into the Scentree framework.
+
+    This class provides a unified interface for working with scikit-learn estimators.
+    It allows dynamic instantiation of the estimator with default or custom hyperparameters,
+    and exposes standard scikit-learn methods such as `fit`, `predict`, `get_params`, and
+    `set_params`. This makes it easy to use any scikit-learn estimator in a consistent way
+    within the framework.
+
+    Attributes:
+        estimator_class (Type[Any]): The scikit-learn estimator class to wrap, e.g.,
+            `sklearn.linear_model.Ridge`.
+        estimator (Optional[Any]): Instance of the fitted estimator. This is set after
+            calling `fit`.
+        name (str): Name of the estimator class, derived from `estimator_class.__name__`.
+        hyperparameters (Dict[str, Any]): Dictionary of hyperparameter values used to
+            instantiate the estimator.
+        hyperparameters_space (Dict[str, List[Any]]): Dictionary defining the search
+            space for hyperparameters for tuning or optimization.
+        X_train_ (Optional[NDArray[np.float64]]): Optional attribute to store training data,
+            if needed for reference or internal operations.
+    """
+
+    def __init__(self, estimator_class: Type[Any]):
+        """
+        Initialize the SklearnEstimator wrapper with a given estimator class.
+
+        Args:
+            estimator_class (Type[Any]): The scikit-learn estimator class to wrap.
+        """
+        self.estimator = None
+        self.estimator_class = estimator_class
+        self.name = self.estimator_class.__name__
+        self.hyperparameters = get_default_parameters(estimator_class)
+        self.hyperparameters_space = get_hyperparameters_space(self.name)
+        self.X_train_: Optional[NDArray[np.float64]] = None
+
+    def fit(self: R, X: NDArray[np.float64], y: NDArray[np.float64]) -> R:
+        """Fit the wrapped Scikit-learn estimator to the training data.
+
+        Args:
+            X (NDArray[np.float64]): Input feature matrix for training.
+            y (NDArray[np.float64]): Target vector.
+
+        Returns:
+            R: The fitted wrapper instance.
+        """
+        self.estimator = self.estimator_class(**self.hyperparameters)
+        assert self.estimator is not None
+        self.estimator.fit(X, y)
+        self.X_train_ = X
+        return self
+
+    def predict(self, X: NDArray[np.float64]) -> NDArray[np.float64]:
+        """Generate predictions using the fitted Scikit-learn estimator.
+
+        Args:
+            X (NDArray[np.float64]): Input feature matrix for prediction.
+
+        Raises:
+            ValueError: If `fit()` has not been called before prediction.
+
+        Returns:
+            NDArray[np.float64]: Predicted target values.
+        """
+        if self.estimator is None:
+            raise ValueError("You must call `fit()` before `predict()`.")
+        return self.estimator.predict(X)
+
+    def get_params(self, deep: bool = True) -> Dict[str, Any]:
+        """Return the hyperparameters of the estimator.
+
+        Args:
+            deep (bool): Ignored parameter for compatibility with Scikit-learn.
+                Included for consistency with the BaseEstimator API.
+
+        Returns:
+            Dict[str, Any]: Dictionary of current hyperparameter values.
+        """
+        return {
+            "estimator_class": self.estimator_class,
+            "hyperparameters": self.hyperparameters,
+            "hyperparameters_space": self.hyperparameters_space,
+        }
+
+    def set_params(self: R, **params: Any) -> R:
+        """Set hyperparameter values for the estimator.
+
+        Args:
+            **params: Arbitrary keyword arguments of hyperparameters to update.
+
+        Returns:
+            R: The updated estimator instance (same type as self).
+        """
+        for key, value in params.items():
+            if hasattr(self, key):
+                setattr(self, key, value)
+            elif key in self.hyperparameters:
+                self.hyperparameters[key] = value
+            else:
+                raise ValueError(
+                    f"Invalid parameter '{key}' for {self.__class__.__name__}. "
+                    f"Valid parameters: constructor={list(self.__dict__.keys())}, "
+                    f"hyperparameters={list(self.hyperparameters.keys())}."
+                )
+        return self
+
+    def fit_cv(
+        self,
+        X: NDArray[np.float64],
+        cv: Union[int, _BaseKFold] = 5,
+    ) -> BaseEstimator:
+        """
+        Perform a Grid Search over the estimator's hyperparameters
+        and return a trained instance of the best model.
+
+        Args:
+            X (NDArray[np.float64]): Training feature matrix.
+            cv (int or BaseCrossValidator): Cross-validation strategy. Default is 5-fold.
+
+        Returns:
+            BaseEstimator: An instance of the estimator with the best
+            hyperparameters, already fitted to the training data.
+        """
+        # First of all, split data into two sets: feature and target.
+        # To begin with, only one lag is taken into account.
+        steps = X.shape[0]
+        feature = X[: (steps - 1), :]
+        target = X[1:, :]
+
+        # Define scoring, compatible with multi-output
+        scorer = make_scorer(rmse, greater_is_better=False)
+
+        if isinstance(cv, int):
+            cv_splitter = TimeSeriesSplit(n_splits=cv)
+        else:
+            cv_splitter = cv
+
+        # Create GridSearchCV
+        grid = GridSearchCV(
+            estimator=self.estimator_class(),
+            param_grid=self.hyperparameters_space,
+            scoring=scorer,
+            cv=cv_splitter,
+            n_jobs=-1,
+        )
+
+        # Fit the grid search
+        grid.fit(feature, target)
+
+        # Instantiate and fit the best estimator
+        self.hyperparameters = grid.best_params_
+        self.fit(feature, target)
+
+        return self
+
+    def in_sample_estimation(self, steps: int) -> NDArray[np.float64]:
+        """
+        Generate in sample estimations.
+
+        Args:
+            steps (int): Number of estimated values to provide.
+
+        Raises:
+            ValueError: If `fit()` has not been called before in_sample_estimation.
+
+        Returns:
+            NDArray[np.float64]: Matrix containing the estimated values.
+        """
+        if self.X_train_ is None:
+            raise ValueError("You must call `fit()` before `in_sample_estimation()`.")
+        estimated_values = self.predict(self.X_train_[-steps:, :])
+        return estimated_values
+
+    def out_sample_estimation(self, steps: int) -> NDArray[np.float64]:
+        """
+        Generate out sample estimations.
+
+        Args:
+            steps (int): Number of estimated values to provide.
+
+        Raises:
+            ValueError: If `fit()` has not been called before out_sample_estimation.
+
+        Returns:
+            NDArray[np.float64]: Matrix containing the estimated values.
+        """
+        if self.X_train_ is None:
+            raise ValueError("You must call `fit()` before `in_sample_estimation()`.")
+        estimated_values = np.full((steps, self.X_train_.shape[1]), np.nan)
+        current_data = np.reshape(self.X_train_[-1, :], shape=(1, -1))
+        for i_pred in range(steps):
+            current_estimation = np.reshape(self.predict(current_data), shape=(1, -1))
+            estimated_values[i_pred, :] = current_estimation
+            current_data = current_estimation
+        return estimated_values
+
+    def get_score(self, X: NDArray[np.float64]) -> float:
+        """
+        Compute the score metric using the data provided.
+
+        Args:
+            X (NDArray[np.float64]): Matrix containing the features.
+            estimator (EstimatorProtocol): The estimator to be evaluated.
+
+        Raises:
+            ValueError: If `fit()` has not been called before computing the score.
+            ValueError: If `X` does not have the correct shape (at least 2 samples).
+
+        Returns:
+            float: The scoring measure.
+        """
+        if self.X_train_ is None:
+            raise ValueError("You must call `fit()` before `get_score()`.")
+        if len(X.shape) != 2 or (len(X.shape) == 2 and X.shape[0] < 2):
+            raise ValueError("X must be of appropriate shape")
+        estimated_values = self.predict(X)
+        X_aligned = X[1:, :]
+        estimated_aligned = estimated_values[:-1, :]
+        return rmse(X_aligned, estimated_aligned)
+
+    def estimate_residuals(self, X: NDArray[np.float64]) -> NDArray[np.float64]:
+        """
+        Estimate residuals.
+
+        Args:
+            X (NDArray[np.float64]): Input feature matrix for prediction. This
+                matrix is used as the true values.
+
+        Raises:
+            ValueError: If `fit()` has not been called before computing the residuals.
+
+        Returns:
+            NDArray[np.float64]: Residuals.
+        """
+        if self.X_train_ is None:
+            raise ValueError("You must call `fit()` before `estimate_residuals()`.")
+        estimated_values = self.predict(X)
+        X_true = X[1:, :]
+        X_estimated = estimated_values[:-1, :]
+        return cast(NDArray[np.float64], X_true - X_estimated)

scentree/estimators/utils.py

@@ -0,0 +1,50 @@
+from inspect import signature
+from typing import Any, Dict, List, Type
+
+
+HYPERPARAMETERS_SPACE: Dict[str, Dict[str, List[Any]]] = {
+    "Ridge": {
+        "alpha": [0.05, 0.06, 0.08, 0.1, 0.2, 0.25, 0.5, 0.7, 1, 2],
+        "max_iter": [100, 200, 300, 500, 1000],
+    },
+    "VAR": {"maxlags": [2, 5, 7, 10], "trend": ["n"]},
+}
+
+
+def get_hyperparameters_space(estimator_name: str) -> Dict[str, List[Any]]:
+    """Obtain the hyperparameters space for a given estimator.
+
+    Args:
+        estimator_name (str): Name of the estimator.
+
+    Returns:
+        dict: Dictionary with the range for each hyperparameter.
+    """
+    return HYPERPARAMETERS_SPACE.get(estimator_name, {})
+
+
+def get_default_parameters(class_chosen: Type, from_fit: bool = False) -> Dict[str, Any]:
+    """
+    Retrieve the default hyperparameters for a given estimator class.
+
+    This function inspects the constructor (`__init__`) or the `fit` method
+    of the specified estimator class and returns a dictionary containing
+    all parameters that have default values, excluding `self`.
+
+    Args:
+        class_chosen (Type): The estimator class to retrieve default parameters from.
+        from_fit (bool, optional): If True, retrieve defaults from the `fit` method
+            instead of the constructor. Defaults to False.
+
+    Returns:
+        Dict[str, Any]: A dictionary mapping parameter names to their default values.
+            Only parameters with default values are included.
+
+    """
+
+    target = class_chosen.fit if from_fit else class_chosen.__init__
+    sig = signature(target)
+    defaults = {
+        k: v.default for k, v in sig.parameters.items() if v.default is not v.empty and k != "self"
+    }
+    return defaults