A complete first research run.

What the package does

The workbench loads validated CSV bars, calculates trailing features, fits an expanding-window ridge baseline, turns a forecast or simple momentum rule into exposure, and runs a single-asset cash/share account. It saves features, forecasts, equity, a trade ledger and a configuration report.

Portfolio helpers supply equal and inverse-volatility weights, caps and lagged portfolio returns. They are separate components: the command-line account engine is single asset.

Install and check it

Extract the ZIP, open a terminal in its folder and use Python 3.10 or newer.

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS / Linux:
# source .venv/bin/activate
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v

Run the installation fixture

python make_synthetic_fixture.py
python run_research.py --csv data/SYNTHETIC-fixture.csv --annualisation 252

The fixture is generated synthetic data. Its returns are an installation check. For real daily observations, 252 may be appropriate; for minute bars or event observations, choose and document a different annualisation.

Use one of the competition files

Download a price file from the data catalogue, then select a product present in that file. The included downloader can list files or retrieve a selected collection; it verifies recorded byte sizes and source hashes:

python download_data.py --list
python download_data.py --collection "Prosperity 2" --contains round_0 --out data

For a Prosperity 2 file containing AMETHYSTS, substitute the downloaded price file's path:

python run_research.py --csv prices.csv --schema prosperity --product AMETHYSTS --annualisation 1 --out results/proxy

This adapter uses the observed midpoint as a price proxy. It does not reproduce the competition exchange, fills, position limits or queues. An actual submission needs an edition-compatible exchange backtester.

Understand the outputs

• features.csv: trailing feature values, including warm-up gaps.
• forecasts.csv: out-of-sample ridge forecasts.
• equity.csv and trades.csv: the account and execution record.
• report.json: the configuration, checksum, costs and metrics.

The evaluation begins flat after 150 observations. Close-t decisions trade at open t+1; remaining positions close at the final close. Fees and adverse slippage apply to orders. The example excludes funding, borrow constraints, market impact and queue behaviour.

See the included README for module interfaces and additional limits. The tests check timing, account arithmetic, costs, short exposure, future-data independence, training-label separation and input validation.