An interview-ready, public replication framework for domestic commodity futures multi-factor research. It asks a practical CTA question: do term structure, trend, inventory, position, and volatility signals retain cross-sectional information after a liquid, dynamically changing commodity universe is imposed?
The code preserves the tested research formulas. The repository publishes only synthetic tests and compact aggregate evidence; it contains no private database, raw market data, vendor extract, credential, or licensed Orient report.
- The front-next term-structure portfolio recorded 13.0% annualised return, 7.1% annualised volatility, and 1.84 Sharpe over 2010-01-04 to 2022-02-28 before trading frictions.
- Its weekly Spearman IC mean was 0.071 across 571 signal dates in the available replication data.
- The 100-score term-structure blend recorded 11.8% annualised return and 1.65 Sharpe; multi-factor rows explicitly identify missing components rather than silently treating them as available.
These are in-sample replication outputs, not investable performance claims. Read limitations before interpreting them.
Figure language note: The five public figures are faithful, author-generated replication artifacts. Their original Chinese on-chart labels are intentionally preserved so that parameter grids, factor names, and visual evidence are not silently reinterpreted. English captions, surrounding narrative, tables, and documentation provide the companion explanation; the figures should therefore be read as bilingual artifacts, not as English-translated source data.
flowchart LR
A[Licensed market inputs] --> B[SQLite contract tables]
B --> C[Dynamic tradable universe]
C --> D[Five factor families]
D --> E[Friday quintile portfolios]
E --> F[Next-period returns, IC, and robustness]
F --> G[Aggregate public evidence]
The complete command map and data flow are in docs/architecture.md. The research design and formulas are in docs/methodology.md.
| Family | Examples | Public evidence |
|---|---|---|
| Term structure | main/sub-main carry, front/next carry, spot/main basis | summary CSVs and robustness grid |
| Momentum | price momentum, cumulative intraday step, signed volatility, rank trend | IC summary |
| Inventory | smoothed warehouse-receipt change | warehouse-receipt summary and robustness grid |
| Position | open-interest deviation and member-position variants | IC summary where available |
| Volatility | standard, EMA, Garman-Klass, Rogers-Satchell, Parkinson | IC summary and multi-factor evidence |
Python 3.11+ is required. Install the project and run the public test suite:
python -m pip install . "pytest>=8.0"
PYTHONPATH=. pytest -q tests
python scripts/run_pipeline.py --list-stagesFor a local SQLite schema and data-access rules, start with data/README.md. The documented scripts accept a local --db path; no download is initiated by the public dry-run command.
The curated results index records the source script, sample period, and replication status for every public table. The Chinese supplementary replication report is authored for this project and is included for context; it is not the original licensed research report.
The responsive project site is available in docs/index.html and is designed for GitHub Pages from /docs.
- No transaction costs, slippage, margin financing, price-limit effects, capacity constraints, or detailed roll execution costs are applied to the public headline metrics.
- Vendor coverage, spot mappings, warehouse receipts, and main-contract rules differ from a source report's proprietary inputs; some multi-factor components are unavailable and are labelled as missing.
- The sample is historical and the shown outputs are not an out-of-sample investment recommendation.
- Market and vendor data must be obtained and used under the applicable licences. This repository does not redistribute them.
The code and original publication materials in this repository are released under the MIT License. Third-party data and reports remain subject to their original licences and are not included.