wavetrainer

A library for automatically finding the optimal model within feature and hyperparameter space on time series models.

wavetrain

Dependencies 🌐

Python 3.11.6:

Raison D'être 💭

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 📐

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 📥

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 👀

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:

import wavetrainer 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"]

wavetrainer = wt.create("my_wavetrain")
wavetrainer = wavetrainer.fit(X, y=Y)

This will save it to the folder my_wavetrain.

Parallel trials

Passing n_jobs greater than 1 (or a negative value, which counts back from the number of CPUs as in joblib) runs the Optuna trials in that many worker processes. With n_jobs=1, the default, trials run one at a time in the calling process.

Workers are started with spawn, so a script that trains in parallel must guard its entry point with if __name__ == "__main__":.
Parallel studies are stored in study.journal next to study.db. The first parallel run on a column copies an existing study.db into the journal, and from then on the journal is used whatever n_jobs is. study.db and its sampler (renamed sampler.pkl.sqlite) are left as a backup.
The training frame is written once to a hidden .wavetrainer-frame-*.joblib file in the training folder and memory-mapped by the workers. It is removed when fit returns.
If a worker dies (for example, a segfault in native code), the failure is logged, its running trial is marked as failed, its remaining trials are given to a new worker, and training carries on.
Each worker gets its own GPU when there are at least as many GPUs as workers. Otherwise the workers train on the CPU. Saving the final model for each walk-forward fold runs in the calling process, on the GPU if it has one.

Load

To load a trainer (as well as its composite states):

import wavetrainer as wt

wavetrainer = wt.load("my_wavetrain")

Predict

To make a prediction from new data:

import wavetrainer as wt
import pandas as pd
import numpy as np

wavetrainer = 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 = wavetrainer.predict(X)

preds will now contain both the predictions and the probabilities associated with those predictions.

Debugging

Set the WAVETRAINER_DUMP_INFERENCE environment variable to snapshot the input frame of each CatBoost inference to a parquet file. It is unset (disabled) by default, since the write is expensive when predicting over many columns.

WAVETRAINER_DUMP_INFERENCE=1 writes to last_catboost_inference.parquet in the current directory.
WAVETRAINER_DUMP_INFERENCE=/path/to/file.parquet writes to that path.

Each write goes to a temporary file that is then atomically moved into place, so concurrent workers never leave a partially written file; the last complete write wins.

License 📝

The project is available under the MIT License.

Metadata

Release files for wavetrainer 0.3.27

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wavetrainer 0.3.27
File	Size	Uploaded
wavetrainer-0.3.27.tar.gz	75.5 kB	Oct 11, 2026	Details

Release files / wavetrainer-0.3.27.tar.gz

Download URL	wavetrainer-0.3.27.tar.gz
Size	75.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`53aecf28b3c3645be84831ec8ab416fc26778e95fd540f895341b06cf4bf16d1`
BLAKE2b-256 checksum How to use checksums	`5c1991e51b39ab7982054ce1cd3bcc60d75ce70b56f0d40c879520e939618c79`
Upload date	Oct 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.14.7`