Skip to content

Canonical Workflow: ElectionIndustryBeta

ElectionIndustryBeta is Q-agent's flagship end-to-end workflow. The authoritative worked walkthrough is the Golden Path; this page is the project reference that points to the files and commands used by that walkthrough.

The workflow demonstrates the full research lifecycle:

committed Polymarket probability series
    ->
research notebook
    ->
shared signal
    ->
LEAN strategy
    ->
ObjectStore diagnostics
    ->
post-analysis notebook

It is intentionally educational. The goal is to show how a hypothesis moves from data to notebook research to strategy code and diagnostics, not to claim a profitable trading signal.

What runs today

Stage Status Credentials needed
Research notebook Runs as-is None
Signal code Implemented None
LEAN strategy Implemented QuantConnect account for cloud backtest
Diagnostics notebook Implemented ObjectStore output from a backtest

The project uses a committed election probability file so the strategy does not need a live Polymarket API call during backtests.

Key files

MyProjects/ElectionIndustryBeta/
├── main.py
├── data/trump_prob.csv
├── domain/
│   ├── config.py
│   └── signals/election_beta.py
├── models/
│   ├── alpha.py
│   ├── portfolio.py
│   ├── execution.py
│   └── logger.py
├── research/pl_attribution.py
└── tools/refresh_trump_prob.py

Shared signal source:

MyProjects/shared/signals/election_beta.py

Research notebook:

infrastructure/marimo/notebooks/election_industry_returns.py

1. Refresh or inspect the Polymarket input

The committed strategy input is:

MyProjects/ElectionIndustryBeta/data/trump_prob.csv

It contains daily YES-token prices for the 2024 Trump election market. Because the 2024 election is over, the file is stable and committed for reproducibility.

To refresh it from the project tool:

cd MyProjects/ElectionIndustryBeta
python tools/refresh_trump_prob.py

For broader Polymarket research, use the full Polymarket pipeline, which has separate market-metadata and price-history steps.

2. Run the research notebook

python -m venv infrastructure/marimo/venv
source infrastructure/marimo/venv/bin/activate
pip install -r infrastructure/marimo/requirements.txt
marimo run infrastructure/marimo/notebooks/election_industry_returns.py --port 2719

The notebook loads trump_prob.csv, fetches ETF prices from yfinance, estimates each ETF's sensitivity to changes in election probability, and helps decide whether the effect is worth turning into a signal.

3. Review the shared signal

Signal logic lives in pure Python, outside LEAN:

MyProjects/shared/signals/election_beta.py

The project consumes that signal from:

MyProjects/ElectionIndustryBeta/domain/signals/election_beta.py

This demonstrates the Q-agent architecture rule: signal math belongs in the domain/ layer and should be testable without a LEAN algorithm instance.

4. Run the LEAN strategy

cd MyProjects
lean cloud push --project "ElectionIndustryBeta" --force
lean cloud backtest "ElectionIndustryBeta" --name "baseline"

The strategy:

  1. Loads the election probability series
  2. Pulls ETF return history
  3. Computes rolling election betas
  4. Longs the top-K positive-beta industries
  5. Shorts the bottom-K negative-beta industries
  6. Logs diagnostics to ObjectStore

5. Analyze ObjectStore outputs

pl_attribution.py reads three CSVs (daily_snapshots.csv, positions.csv, trades.csv). It looks for them locally first under MyProjects/storage/electionbeta/, then falls back to QuantBook().ObjectStore. A cloud backtest writes the artifacts to the cloud ObjectStore — it does not populate the local files, and a plain host-side marimo run venv has no QuantConnect research runtime to hit the fallback. So you must first pull the artifacts down to local storage:

cd MyProjects
mkdir -p storage/electionbeta
lean cloud object-store get \
  "electionbeta/daily_snapshots.csv" \
  "electionbeta/positions.csv" \
  "electionbeta/trades.csv" \
  --destination-folder storage/electionbeta
# Confirm the three CSVs landed at storage/electionbeta/<name>.csv
# (move them there if `get` nested them under the key path).

Then run the diagnostics notebook:

marimo run MyProjects/ElectionIndustryBeta/research/pl_attribution.py

Alternatively, run a local backtest (bash scripts/lean-backtest.sh "ElectionIndustryBeta"), which writes the CSVs straight into MyProjects/storage/electionbeta/, or open the notebook inside lean research where the QuantBook().ObjectStore fallback is available.

The diagnostics workflow is where you evaluate whether the backtest behavior matches the original hypothesis: P&L attribution, exposure, concentration, and realized performance.

Architecture map

main.py                     # composition root — wires the pieces
models/                     # orchestration: alpha, portfolio, execution, logging
domain/                     # pure signal/config logic
research/                   # diagnostics and post-analysis
data/                       # committed deterministic input for this project
tools/                      # refresh/maintenance scripts

See Architecture for the general layer rules and Golden Path for the full narrative walkthrough.

Why this workflow matters

Most quantitative finance repositories show only one piece of the research lifecycle. ElectionIndustryBeta connects the pieces:

data -> notebook -> signal -> LEAN strategy -> backtest -> diagnostics

That is the canonical Q-agent workflow pattern.