quantskills/agent-quantspace/ml

ML

ML contains reusable model training, prediction, ML factor, and sparse fitting helpers. It should produce predictions, ranks, labels, or weight matrices; return accounting belongs in skills.backtest.

Install model dependencies with uv sync --extra ml.

Public API

from skills.ml.ml_engine import MLEngine, ModelPredictor
from skills.ml.ml_factor import MLFactorEngine, make_precomputed_factor
from skills.ml.lasso_tracker import lasso_track
from skills.ml.pca_fold import fit_fold_transform, make_regressor
from skills.ml.walk_forward import date_level_mask, expanding_purged_folds

Components

Recipes

ML rank factor for `ModularBacktester`

from skills.compute import indicators as I
from skills.ml.ml_factor import MLFactorEngine, make_precomputed_factor
engine = MLFactorEngine(
    data=panel_df,
    factor_configs=[
        {"func": I.trend_score_v2, "kwargs": {"period": 24}, "name": "trend"},
        {"func": I.cci, "kwargs": {"period": 48}, "name": "cci"},
    ],
    model_type="xgboost",
    train_mode="rolling",
)
rank_pivot = engine.generate()
ml_factor_fn = make_precomputed_factor(rank_pivot, name="ml_rank")

Expanding purged walk-forward folds

from skills.ml.walk_forward import date_level_mask, expanding_purged_folds
dates = panel.index.get_level_values("eob").unique()
folds = expanding_purged_folds(
    dates,
    min_train=250,
    retrain_step=370,
    purge=20,
)
for fold in folds:
    train_mask = date_level_mask(feature_panel.index, fold.train_dates)
    pred_mask = date_level_mask(feature_panel.index, fold.pred_dates)

Train-only PCA fold transform

from skills.ml.pca_fold import fit_fold_transform, make_regressor
transform = fit_fold_transform(train_X, pred_X, n_pca=50, random_state=42)
model = make_regressor("lasso")  # or "ols" / "rf" / "xgboost"
model.fit(transform.train_X, train_y)
pred = model.predict(transform.pred_X)

Cross-sectional expanding PCA model scores

from skills.compute.features import make_logdiff_panel_features
from strategies.cross_sectional.ml_rank import (
    expanding_pca_model_scores,
    expanding_pca_multi_model_scores,
)
features = make_logdiff_panel_features(panel)  # reuse across horizons
# Prefer multi-model so each fold's PCA is fit once:
results = expanding_pca_multi_model_scores(
    panel, models=("ols", "lasso", "rf", "xgboost"), horizon=20, features=features
)
# Or a single model:
result = expanding_pca_model_scores(panel, model="rf", horizon=20, features=features)
scores = result.scores
fold_metrics = result.fold_metrics
overall_metrics = result.overall_metrics

Lesson 07 workflow (18 ETF, equal-weight Top 3)

uv run python -m strategies.cross_sectional.workflows.run_lesson07_etf18_logdiff_pca_ml

Sparse index-tracking weights

from skills.ml.lasso_tracker import lasso_track
weights = lasso_track(
    etf_returns,
    index_returns,
    lookback=120,
    alpha=1e-5,
    rebalance_freq="M",
)

PyCaret classification

from skills.ml.ml_engine import MLEngine
engine = MLEngine(task="classification", model_name="xgboost")
model, metrics = engine.setup_and_train(train_df, target="label")
preds = engine.predict(test_df)

CLI command reference

<!-- BEGIN GENERATED: qs commands -->

Transport: --input-json FILE|-, --preview N, and --log-level LEVEL; flags override JSON. Use --print-template [FIELD] for fillable templates.

Shared parameter groups

PanelSource

OutputOptions

uv run qs ml factor-rank

Train MLFactorEngine on factor features and write cross-sectional ranks.

Priority: P1. Side effects: writes-output.

Shared parameters: PanelSource, OutputOptions.

Output data fields: rows, columns, oos_start_date, evaluation.

Inspect schemas: uv run qs schema ml.factor-rank (add --part input|output or --file-field FIELD).

uv run qs ml lasso-track

Rolling LASSO index-tracking weights.

Priority: P1. Side effects: writes-output.

Shared parameters: PanelSource, OutputOptions.

Output data fields: rows, columns, start, end, preview.

Inspect schemas: uv run qs schema ml.lasso-track (add --part input|output or --file-field FIELD).

uv run qs ml folds

Expanding walk-forward folds with label purge.

Priority: P1. Side effects: read-only.

Shared parameters: PanelSource.

Output data fields: dates, folds.

Inspect schemas: uv run qs schema ml.folds (add --part input|output or --file-field FIELD).

uv run qs ml pca-predict

Fit train-only PCA and a frozen regressor, then predict rows.

Priority: P1. Side effects: writes-output.

Shared parameters: OutputOptions.

Output data fields: rows, features, components, pca_explained_variance_sum.

Inspect schemas: uv run qs schema ml.pca-predict (add --part input|output or --file-field FIELD).

uv run qs ml train

Train a PyCaret MLEngine model and save it to the model registry.

Priority: P2. Side effects: writes-store.

Output data fields: dry_run, namespace, registry_dir, model_id, rows, features, cv_metrics_mean.

Inspect schemas: uv run qs schema ml.train (add --part input|output or --file-field FIELD).

uv run qs ml predict

Predict with a registry model.

Priority: P2. Side effects: writes-output.

Shared parameters: OutputOptions.

Output data fields: rows, task, columns.

Inspect schemas: uv run qs schema ml.predict (add --part input|output or --file-field FIELD).

<!-- END GENERATED: qs commands -->