How znzhao/etfregulus works
ETFRegulus is a framework for researching dynamic ETF allocation under market-regime signals and trading constraints. Its visible workflow is staged: fetch market and macro data, curate it onto trading sessions with quality checks, build features, then simulate allocations and assess results. The simulator applies risk and feasibility controls before next-open execution, with a ledger and holding locks tracking portfolio state. The README describes reinforcement learning, but the supplied tree has no evident policy or training implementation; source excerpts are partial, so uncertain module wiring is omitted.
Main entry points: stage.py Stage harness · simulator.py Portfolio simulator · builder.py Feature builder · runner.py Simulation runner
Components 27
Stage workflow
- Stage harness
src/cli/stage.py - Fetch stage
scripts/s01_fetch_data.py - Curation stage
scripts/s02_curate_data.py - Feature stage
scripts/s03_build_features.py - Simulation stage
scripts/s04_simulate.py - Baseline stage
scripts/s05_run_baselines.py - Typed configuration
src/config/loader.py
Market data
- Data fetch
src/data/fetch.py - Data curation
src/data/curate.py - Trading calendar
src/data/calendar.py - Feature builder
src/features/builder.py - ETF features
src/features/etf.py - Macro features
src/features/macro.py - Cross-sectional features
src/features/cross_sectional.py
Allocation simulation
- Baseline strategies
src/baselines/strategies.py - Portfolio simulator
src/sim/simulator.py - Simulation runner
src/sim/runner.py - Feasibility projector
src/constraints/projector.py - Risk envelope
src/constraints/risk_envelope.py - Trade execution
src/portfolio/execution.py - Holding locks
src/portfolio/lock_manager.py - Portfolio ledger
src/portfolio/ledger.py - Portfolio valuation
src/portfolio/valuation.py
Evaluation
- Performance metrics
src/evaluation/metrics.py
Other components
- Researcher
- Market data providers
- FRED
Connections 28
- Researcher → Stage harness: runs stages
- Stage harness → Fetch stage: dispatches
- Stage harness → Curation stage: dispatches
- Stage harness → Feature stage: dispatches
- Stage harness → Simulation stage: dispatches
- Stage harness → Baseline stage: dispatches
- Stage harness → Typed configuration: loads config
- Fetch stage → Data fetch: invokes
- Market data providers → Data fetch: provides data
- FRED → Data fetch: provides series
- Curation stage → Data curation: invokes
- Data curation → Trading calendar: aligns sessions
- Feature stage → Feature builder: invokes
- Feature builder → ETF features: builds ETF signals
- Feature builder → Macro features: builds macro signals
- Feature builder → Cross-sectional features: builds cross signals
- Baseline stage → Baseline strategies: selects weights
- Simulation stage → Simulation runner: invokes
- Simulation runner → Portfolio simulator: runs trajectory
- Baseline strategies → Portfolio simulator: supplies weights
- Portfolio simulator → Feasibility projector: projects targets
- Portfolio simulator → Risk envelope: prepares risk limits
- Portfolio simulator → Trade execution: executes targets
- Portfolio simulator → Holding locks: checks lock state
- Trade execution → Holding locks: checks sellability
- Trade execution → Portfolio ledger: updates holdings
- Portfolio simulator → Portfolio valuation: values portfolio
- Simulation runner → Performance metrics: summarizes results