wavetrainer 0.0.1__tar.gz

wavetrainer-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Will Sackfield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wavetrainer-0.0.1/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.1
+Name: wavetrainer
+Version: 0.0.1
+Summary: A library for automatically finding the optimal model within feature and hyperparameter space.
+Home-page: https://github.com/8W9aG/wavetrain
+Author: Will Sackfield
+Author-email: will.sackfield@gmail.com
+License: MIT
+Keywords: machine-learning,ML,hyperparameter,features
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: optuna>=4.2.1
+Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: feature-engine>=1.8.3
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: numpy>=2.2.3
+Requires-Dist: scipy>=1.15.2
+Requires-Dist: catboost>=1.2.7
+Requires-Dist: venn-abers>=1.4.6
+Requires-Dist: mapie>=0.9.2
+Requires-Dist: shapiq>=1.2.2
+
+# wavetrainer
+
+<a href="https://pypi.org/project/wavetrain/">
+    <img alt="PyPi" src="https://img.shields.io/pypi/v/wavetrain">
+</a>
+
+A library for automatically finding the optimal model within feature and hyperparameter space on time series models.
+
+<p align="center">
+    <img src="wavetrain.png" alt="wavetrain" width="200"/>
+</p>
+
+## Dependencies :globe_with_meridians:
+
+Python 3.11.6:
+
+- [pandas](https://pandas.pydata.org/)
+- [optuna](https://optuna.readthedocs.io/en/stable/)
+- [scikit-learn](https://scikit-learn.org/)
+- [feature-engine](https://feature-engine.trainindata.com/en/latest/)
+- [tqdm](https://github.com/tqdm/tqdm)
+- [numpy](https://numpy.org/)
+- [scipy](https://scipy.org/)
+- [catboost](https://catboost.ai/)
+- [venn-abers](https://github.com/ip200/venn-abers)
+- [mapie](https://mapie.readthedocs.io/en/stable/)
+- [shapiq](https://github.com/mmschlk/shapiq)
+
+## Raison D'être :thought_balloon:
+
+`wavetrainer` aims to split out the various aspects of creating a good model into different composable pieces and searches the space of these different pieces to find an optimal model. This came about after doing code like this multiple times on multiple projects. This is specifically geared towards time series models, validating itself through walk-forward analysis.
+
+## Architecture :triangular_ruler:
+
+`wavetrainer` is an object orientated library. The entities are organised like so:
+
+* **Trainer**: A sklearn compatible object that can fit and predict data.
+    * **Reducer**: An object that can reduce the feature space based on heuristics.
+    * **Weights**: An object that adds weights to the features.
+    * **Selector**: An object that can select which features to include from the training set.
+    * **Calibrator**: An object that can calibrate the probabilities produced by the model.
+    * **Model**: An object that represents the underlying model architecture being used.
+    * **Windower**: An object that represents the lookback window of the data.
+
+## Installation :inbox_tray:
+
+This is a python package hosted on pypi, so to install simply run the following command:
+
+`pip install wavetrainer`
+
+or install using this local repository:
+
+`python setup.py install --old-and-unmanageable`
+
+## Usage example :eyes:
+
+The use of `wavetrainer` is entirely through code due to it being a library. It attempts to hide most of its complexity from the user, so it only has a few functions of relevance in its outward API.
+
+### Training
+
+To train a model:
+
+```python
+import wavetrain as wt
+import pandas as pd
+import numpy as np
+import random
+
+data_size = 10
+df = pd.DataFrame(
+    np.random.randint(0, 30, size=data_size),
+    columns=["X"],
+    index=pd.date_range("20180101", periods=data_size),
+)
+df["Y"] = [random.choice([True, False]) for _ in range(data_size)]
+
+X = df["X"]
+Y = df["Y"]
+
+wavetrain = wt.create("my_wavetrain")
+wavetrain = wavetrain.fit(X, y=Y)
+```
+
+This will save it to the folder `my_wavetrain`.
+
+### Load
+
+To load a trainer (as well as its composite states):
+
+```python
+import wavetrain as wt
+
+wavetrain = wt.load("my_wavetrain")
+```
+
+### Predict
+
+To make a prediction from new data:
+
+```python
+import wavetrain as wt
+import pandas as pd
+import numpy as np
+
+wavetrain = wt.load("my_wavetrain")
+data_size = 1
+df = pd.DataFrame(
+    np.random.randint(0, 30, size=data_size),
+    columns=["X"],
+    index=pd.date_range("20180101", periods=data_size),
+)
+X = df["X"]
+
+preds = wavetrain.predict(X)
+```
+
+`preds` will now contain both the predictions and the probabilities associated with those predictions.
+
+## License :memo:
+
+The project is available under the [MIT License](LICENSE).

wavetrainer-0.0.1/README.md

@@ -0,0 +1,121 @@
+# wavetrainer
+
+<a href="https://pypi.org/project/wavetrain/">
+    <img alt="PyPi" src="https://img.shields.io/pypi/v/wavetrain">
+</a>
+
+A library for automatically finding the optimal model within feature and hyperparameter space on time series models.
+
+<p align="center">
+    <img src="wavetrain.png" alt="wavetrain" width="200"/>
+</p>
+
+## Dependencies :globe_with_meridians:
+
+Python 3.11.6:
+
+- [pandas](https://pandas.pydata.org/)
+- [optuna](https://optuna.readthedocs.io/en/stable/)
+- [scikit-learn](https://scikit-learn.org/)
+- [feature-engine](https://feature-engine.trainindata.com/en/latest/)
+- [tqdm](https://github.com/tqdm/tqdm)
+- [numpy](https://numpy.org/)
+- [scipy](https://scipy.org/)
+- [catboost](https://catboost.ai/)
+- [venn-abers](https://github.com/ip200/venn-abers)
+- [mapie](https://mapie.readthedocs.io/en/stable/)
+- [shapiq](https://github.com/mmschlk/shapiq)
+
+## Raison D'être :thought_balloon:
+
+`wavetrainer` aims to split out the various aspects of creating a good model into different composable pieces and searches the space of these different pieces to find an optimal model. This came about after doing code like this multiple times on multiple projects. This is specifically geared towards time series models, validating itself through walk-forward analysis.
+
+## Architecture :triangular_ruler:
+
+`wavetrainer` is an object orientated library. The entities are organised like so:
+
+* **Trainer**: A sklearn compatible object that can fit and predict data.
+    * **Reducer**: An object that can reduce the feature space based on heuristics.
+    * **Weights**: An object that adds weights to the features.
+    * **Selector**: An object that can select which features to include from the training set.
+    * **Calibrator**: An object that can calibrate the probabilities produced by the model.
+    * **Model**: An object that represents the underlying model architecture being used.
+    * **Windower**: An object that represents the lookback window of the data.
+
+## Installation :inbox_tray:
+
+This is a python package hosted on pypi, so to install simply run the following command:
+
+`pip install wavetrainer`
+
+or install using this local repository:
+
+`python setup.py install --old-and-unmanageable`
+
+## Usage example :eyes:
+
+The use of `wavetrainer` is entirely through code due to it being a library. It attempts to hide most of its complexity from the user, so it only has a few functions of relevance in its outward API.
+
+### Training
+
+To train a model:
+
+```python
+import wavetrain as wt
+import pandas as pd
+import numpy as np
+import random
+
+data_size = 10
+df = pd.DataFrame(
+    np.random.randint(0, 30, size=data_size),
+    columns=["X"],
+    index=pd.date_range("20180101", periods=data_size),
+)
+df["Y"] = [random.choice([True, False]) for _ in range(data_size)]
+
+X = df["X"]
+Y = df["Y"]
+
+wavetrain = wt.create("my_wavetrain")
+wavetrain = wavetrain.fit(X, y=Y)
+```
+
+This will save it to the folder `my_wavetrain`.
+
+### Load
+
+To load a trainer (as well as its composite states):
+
+```python
+import wavetrain as wt
+
+wavetrain = wt.load("my_wavetrain")
+```
+
+### Predict
+
+To make a prediction from new data:
+
+```python
+import wavetrain as wt
+import pandas as pd
+import numpy as np
+
+wavetrain = wt.load("my_wavetrain")
+data_size = 1
+df = pd.DataFrame(
+    np.random.randint(0, 30, size=data_size),
+    columns=["X"],
+    index=pd.date_range("20180101", periods=data_size),
+)
+X = df["X"]
+
+preds = wavetrain.predict(X)
+```
+
+`preds` will now contain both the predictions and the probabilities associated with those predictions.
+
+## License :memo:
+
+The project is available under the [MIT License](LICENSE).

wavetrainer-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wavetrainer-0.0.1/setup.py

@@ -0,0 +1,42 @@
+"""Setup wavetrain."""
+from setuptools import setup, find_packages
+from pathlib import Path
+import typing
+
+readme_path = Path(__file__).absolute().parent.joinpath('README.md')
+long_description = readme_path.read_text(encoding='utf-8')
+
+
+def install_requires() -> typing.List[str]:
+    """Find the install requires strings from requirements.txt"""
+    requires = []
+    with open(
+        Path(__file__).absolute().parent.joinpath('requirements.txt'), "r"
+    ) as requirments_txt_handle:
+        requires = [
+            x
+            for x in requirments_txt_handle
+            if not x.startswith(".") and not x.startswith("-e")
+        ]
+    return requires
+
+
+setup(
+    name='wavetrainer',
+    version='0.0.1',
+    description='A library for automatically finding the optimal model within feature and hyperparameter space.',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
+    classifiers=[
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 3',
+    ],
+    keywords='machine-learning, ML, hyperparameter, features',
+    url='https://github.com/8W9aG/wavetrain',
+    author='Will Sackfield',
+    author_email='will.sackfield@gmail.com',
+    license='MIT',
+    install_requires=install_requires(),
+    zip_safe=False,
+    packages=find_packages()
+)

wavetrainer-0.0.1/tests/trainer_test.py

@@ -0,0 +1,38 @@
+"""Tests for the trainer class."""
+import datetime
+import random
+import tempfile
+import unittest
+
+import pandas as pd
+
+from wavetrainer.trainer import Trainer
+
+
+class TestTrainer(unittest.TestCase):
+
+    def test_trainer(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            trainer = Trainer(tmpdir, walkforward_timedelta=datetime.timedelta(days=1), trials=10)
+            x_data = [i for i in range(100)]
+            x_index = [datetime.datetime(2022, 1, 1) + datetime.timedelta(days=i) for i in range(len(x_data))]
+            df = pd.DataFrame(
+                data={
+                    "column1": x_data,
+                    "column2": [(x * random.random()) + random.random() for x in x_data],
+                    "column3": [(x / random.random()) - random.random() for x in x_data],
+                },
+                index=x_index,
+            )
+            y = pd.DataFrame(
+                data={
+                    "y": [x % 2 == 0 for x in x_data],
+                    "y2": [(x + 2) % 3 == 0 for x in x_data],
+                    "y3": [float(x) + 2.0 for x in x_data],
+                },
+                index=df.index,
+            )
+            trainer.fit(df, y=y)
+            df = trainer.transform(df)
+            print("df:")
+            print(df)

wavetrainer-0.0.1/wavetrainer/__init__.py

@@ -0,0 +1,10 @@
+"""The wavetrain main module."""
+
+from .create import create
+from .load import load
+
+__VERSION__ = "0.0.1"
+__all__ = (
+    "create",
+    "load",
+)

wavetrainer-0.0.1/wavetrainer/calibrator/__init__.py

@@ -0,0 +1 @@
+"""The wavetrain calibrator module."""

wavetrainer-0.0.1/wavetrainer/calibrator/calibrator.py

@@ -0,0 +1,17 @@
+"""The prototype calibrator class."""
+
+from ..fit import Fit
+from ..model.model import Model
+from ..params import Params
+
+
+class Calibrator(Params, Fit):
+    """The prototype calibrator class."""
+
+    def __init__(self, model: Model):
+        self._model = model
+
+    @classmethod
+    def name(cls) -> str:
+        """The name of the calibrator."""
+        raise NotImplementedError("name not implemented in parent class.")

wavetrainer-0.0.1/wavetrainer/calibrator/calibrator_router.py

@@ -0,0 +1,83 @@
+"""A calibrator class that routes to other calibrators."""
+
+import json
+import os
+from typing import Self
+
+import optuna
+import pandas as pd
+
+from ..model.model import Model
+from ..model_type import ModelType, determine_model_type
+from .calibrator import Calibrator
+from .mapie_calibrator import MAPIECalibrator
+from .vennabers_calibrator import VennabersCalibrator
+
+_CALIBRATOR_ROUTER_FILE = "calibrator_router.json"
+_CALIBRATOR_KEY = "calibrator"
+_CALIBRATORS = {
+    VennabersCalibrator.name(): VennabersCalibrator,
+    MAPIECalibrator.name(): MAPIECalibrator,
+}
+
+
+class CalibratorRouter(Calibrator):
+    """A router that routes to a different calibrator class."""
+
+    _calibrator: Calibrator | None
+
+    def __init__(self, model: Model):
+        super().__init__(model)
+        self._calibrator = None
+
+    @classmethod
+    def name(cls) -> str:
+        return "router"
+
+    def set_options(self, trial: optuna.Trial | optuna.trial.FrozenTrial) -> None:
+        pass
+
+    def load(self, folder: str) -> None:
+        with open(
+            os.path.join(folder, _CALIBRATOR_ROUTER_FILE), encoding="utf8"
+        ) as handle:
+            params = json.load(handle)
+            calibrator = _CALIBRATORS[params[_CALIBRATOR_KEY]](self._model)
+        calibrator.load(folder)
+        self._calibrator = calibrator
+
+    def save(self, folder: str) -> None:
+        calibrator = self._calibrator
+        if calibrator is None:
+            raise ValueError("calibrator is null.")
+        calibrator.save(folder)
+        with open(
+            os.path.join(folder, _CALIBRATOR_ROUTER_FILE), "w", encoding="utf8"
+        ) as handle:
+            json.dump(
+                {
+                    _CALIBRATOR_KEY: calibrator.name(),
+                },
+                handle,
+            )
+
+    def fit(
+        self,
+        df: pd.DataFrame,
+        y: pd.Series | pd.DataFrame | None = None,
+        w: pd.Series | None = None,
+    ) -> Self:
+        calibrator: Calibrator | None = None
+        if determine_model_type(df) == ModelType.REGRESSION:
+            calibrator = MAPIECalibrator(self._model)
+        else:
+            calibrator = VennabersCalibrator(self._model)
+        calibrator.fit(df, y=y, w=w)
+        self._calibrator = calibrator
+        return self
+
+    def transform(self, df: pd.DataFrame) -> pd.DataFrame:
+        calibrator = self._calibrator
+        if calibrator is None:
+            raise ValueError("calibrator is null.")
+        return calibrator.transform(df)

wavetrainer-0.0.1/wavetrainer/calibrator/mapie_calibrator.py

@@ -0,0 +1,60 @@
+"""A calibrator that implements MAPIE."""
+
+import os
+from typing import Self
+
+import joblib  # type: ignore
+import optuna
+import pandas as pd
+from mapie.regression import MapieRegressor  # type: ignore
+
+from ..model.model import PROBABILITY_COLUMN_PREFIX, Model
+from .calibrator import Calibrator
+
+_CALIBRATOR_FILENAME = "mapie.joblib"
+
+
+class MAPIECalibrator(Calibrator):
+    """A class that uses MAPIE as a calibrator."""
+
+    def __init__(self, model: Model):
+        super().__init__(model)
+        self._mapie = MapieRegressor(model.estimator, method="plus")
+
+    @classmethod
+    def name(cls) -> str:
+        return "mapie"
+
+    def set_options(self, trial: optuna.Trial | optuna.trial.FrozenTrial) -> None:
+        pass
+
+    def load(self, folder: str) -> None:
+        self._mapie = joblib.load(os.path.join(folder, _CALIBRATOR_FILENAME))
+
+    def save(self, folder: str) -> None:
+        joblib.dump(self._mapie, os.path.join(folder, _CALIBRATOR_FILENAME))
+
+    def fit(
+        self,
+        df: pd.DataFrame,
+        y: pd.Series | pd.DataFrame | None = None,
+        w: pd.Series | None = None,
+    ) -> Self:
+        mapie = self._mapie
+        if mapie is None:
+            raise ValueError("mapie is null")
+        if y is None:
+            raise ValueError("y is null")
+        mapie.fit(df.to_numpy(), y.to_numpy())
+        return self
+
+    def transform(self, df: pd.DataFrame) -> pd.DataFrame:
+        alpha = [0.05, 0.32]
+        _, y_pis = self._mapie.predict(df, alpha=alpha)
+        df = pd.DataFrame(data=None, index=df.index)
+        for i in range(y_pis.shape[1]):
+            for ii in range(y_pis.shape[2]):
+                df[f"{PROBABILITY_COLUMN_PREFIX}{alpha[i]}_{ii == 1}"] = (
+                    y_pis[:, i, ii].flatten().tolist()
+                )
+        return df

wavetrainer-0.0.1/wavetrainer/calibrator/vennabers_calibrator.py

@@ -0,0 +1,59 @@
+"""A calibrator that implements venn abers."""
+
+import os
+from typing import Self
+
+import joblib  # type: ignore
+import optuna
+import pandas as pd
+from venn_abers import VennAbers  # type: ignore
+
+from ..model.model import PROBABILITY_COLUMN_PREFIX, Model
+from .calibrator import Calibrator
+
+_CALIBRATOR_FILENAME = "vennabers.joblib"
+
+
+class VennabersCalibrator(Calibrator):
+    """A class that uses venn abers as a calibrator."""
+
+    def __init__(self, model: Model):
+        super().__init__(model)
+        self._vennabers = VennAbers()
+
+    @classmethod
+    def name(cls) -> str:
+        return "vennabers"
+
+    def set_options(self, trial: optuna.Trial | optuna.trial.FrozenTrial) -> None:
+        pass
+
+    def load(self, folder: str) -> None:
+        self._vennabers = joblib.load(os.path.join(folder, _CALIBRATOR_FILENAME))
+
+    def save(self, folder: str) -> None:
+        joblib.dump(self._vennabers, os.path.join(folder, _CALIBRATOR_FILENAME))
+
+    def fit(
+        self,
+        df: pd.DataFrame,
+        y: pd.Series | pd.DataFrame | None = None,
+        w: pd.Series | None = None,
+    ) -> Self:
+        vennabers = self._vennabers
+        if vennabers is None:
+            raise ValueError("vennabers is null")
+        if y is None:
+            raise ValueError("y is null")
+        prob_columns = [
+            x for x in df.columns.values if x.startswith(PROBABILITY_COLUMN_PREFIX)
+        ]
+        vennabers.fit(df[prob_columns].to_numpy(), y.to_numpy())
+        return self
+
+    def transform(self, df: pd.DataFrame) -> pd.DataFrame:
+        p_prime, _ = self._vennabers.predict_proba(df.to_numpy())
+        for i in range(p_prime.shape[1]):
+            prob = p_prime[:, i]
+            df[f"{PROBABILITY_COLUMN_PREFIX}{i}"] = prob
+        return df

wavetrainer-0.0.1/wavetrainer/create.py

@@ -0,0 +1,22 @@
+"""A function for creating a new trainer."""
+
+import datetime
+
+from .trainer import Trainer
+
+
+def create(
+    folder: str,
+    walkforward_timedelta: datetime.timedelta = datetime.timedelta(days=1.0),
+    test_size: float | datetime.timedelta | None = None,
+    validation_size: float | datetime.timedelta | None = None,
+    dt_column: str | None = None,
+) -> Trainer:
+    """Create a trainer."""
+    return Trainer(
+        folder,
+        walkforward_timedelta,
+        test_size=test_size,
+        validation_size=validation_size,
+        dt_column=dt_column,
+    )

wavetrainer-0.0.1/wavetrainer/exceptions.py

@@ -0,0 +1,5 @@
+"""Custom exceptions within wavetrain."""
+
+
+class WavetrainException(Exception):
+    """An exception that denotes that wavetrain should end the training early."""

wavetrainer-0.0.1/wavetrainer/fit.py

@@ -0,0 +1,30 @@
+"""A prototype class implementing a fit method."""
+
+from typing import Self
+
+import pandas as pd
+
+
+class Fit:
+    """The prototype fit class."""
+
+    def fit(
+        self,
+        df: pd.DataFrame,
+        y: pd.Series | pd.DataFrame | None = None,
+        w: pd.Series | None = None,
+    ) -> Self:
+        """Fit the dataframe."""
+        raise NotImplementedError("fit not implemented in parent class.")
+
+    def transform(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Transform the dataframe."""
+        raise NotImplementedError("transform not implemented in parent class.")
+
+    def fit_transform(
+        self,
+        df: pd.DataFrame,
+        y: pd.Series | pd.DataFrame | None = None,
+    ) -> pd.DataFrame:
+        """Fit and then trasnfrom the dataframe."""
+        return self.fit(df, y=y).transform(df)

wavetrainer-0.0.1/wavetrainer/load.py

@@ -0,0 +1,8 @@
+"""The function for loading the trainer state from disk."""
+
+from .trainer import Trainer
+
+
+def load(folder: str) -> Trainer:
+    """Loads the trainer from the folder."""
+    raise NotImplementedError("load isn't implemented.")

wavetrainer-0.0.1/wavetrainer/model/__init__.py

@@ -0,0 +1 @@
+"""The wavetrain model module."""