Initial release

CrossSectionCN: a China A-share companion to the Open Source Asset
Pricing project. Reimplements the documented cross-sectional return
predictor literature against A-share data under China-specific timing,
disclosure, and listing-board constraints.

- Data pipeline (ingest, normalize, intermediate, factor compute)
- Factor registry in factor_doc.csv
- Quarto site with per-factor detail pages, family rollups, return
  leaderboard, and monthly heatmap
- GitHub Actions workflow that rerenders and publishes the site from
  the committed JSON snapshots on every push

Author: yanpgwang

.env.example

@@ -0,0 +1,4 @@
+TUSHARE_TOKEN=
+CNCS_DATA_SOURCE=tushare
+CNCS_MAX_STOCKS=0
+CNCS_OHLCV_BATCH=25

.github/workflows/publish.yml

@@ -0,0 +1,64 @@
+name: Publish Quarto site to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "quarto/**"
+      - "reports/build_quarto_data.py"
+      - ".github/workflows/publish.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Render Quarto site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          version: 1.9.37
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      # build_quarto_data.py is intentionally self-contained: it depends only on
+      # the Python standard library and reads JSON files committed under
+      # quarto/_data/, so we don't need polars / pyarrow / tushare in CI.
+      - name: Generate factor pages and snippets
+        run: python -m reports.build_quarto_data
+
+      - name: Render Quarto site
+        working-directory: quarto
+        run: quarto render
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: quarto/_site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,18 @@
+pyData/
+*.parquet
+*.csv
+!factor_doc.csv
+__pycache__/
+*.pyc
+.pytest_cache/
+.env
+.venv/
+docs/
+*.egg-info/
+node_modules/
+quarto/_site/
+quarto/.quarto/
+quarto/_generated/
+quarto/factors/
+quarto/families/
+reference/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yanpeng Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,22 @@
+# CrossSectionCN
+
+A companion to the Open Source Asset Pricing project ([Chen and Zimmermann, 2022](https://www.openassetpricing.com/)) for the China A-share market.
+
+Site: <https://yanpgwang.github.io/CrossSectionCN/>
+
+This repository re-tests documented cross-sectional return predictors against China A-share data, following the documentation discipline of [OpenSourceAP/CrossSection](https://github.com/OpenSourceAP/CrossSection/): each signal carries a definition, literature attribution, expected return direction, portfolio construction rule, and a record of known data limitations. None of the original U.S.-market results are republished; every predictor is rebuilt under China-specific timing, disclosure, and listing-board constraints. The project is descriptive rather than prescriptive.
+
+Most readers will want the [site](https://yanpgwang.github.io/CrossSectionCN/); the repository is provided for inspection, citation, and contribution. The site is regenerated and published from the snapshots under `quarto/_data/` by the workflow in `.github/workflows/publish.yml`. Refreshing the underlying panel is a deliberate local operation, orchestrated by `master.py` and `reports/build_site_data.py`.
+
+## Acknowledgments
+
+This project follows the documentation structure of:
+
+- Chen, A. Y. and Zimmermann, T. (2022). Open source cross-sectional asset pricing. *Critical Finance Review*, 11 (2): 207–264. <https://www.openassetpricing.com/>
+- OpenSourceAP/CrossSection — reference implementation for the U.S. market. <https://github.com/OpenSourceAP/CrossSection/>
+
+No code or data from the source projects is redistributed.
+
+## License
+
+[MIT](LICENSE).

config.py

@@ -0,0 +1,40 @@
+"""ABOUTME: Global config for CrossSectionCN.
+ABOUTME: Paths, date ranges, universe filters."""
+import os
+from datetime import date
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+ROOT = Path(__file__).parent
+DATA_RAW_VENDOR = ROOT / "pyData" / "raw_vendor"
+DATA_CANONICAL = ROOT / "pyData" / "canonical"
+# Backward-compatible alias: existing intermediate/factor code reads canonical tables here.
+DATA_RAW = DATA_CANONICAL
+DATA_INTERMEDIATE = ROOT / "pyData" / "intermediate"
+DATA_FACTORS = ROOT / "pyData" / "factors"
+
+START_DATE = date(2010, 1, 1)
+END_DATE = date.today()
+
+UNIVERSE_EXCHANGES = ["SH", "SZ"]
+UNIVERSE_BOARDS = ["MAIN", "GEM", "STAR"]
+
+FACTOR_DOC_PATH = ROOT / "factor_doc.csv"
+
+DATA_SOURCE = os.environ.get("CNCS_DATA_SOURCE", "tushare").lower()
+TUSHARE_TOKEN = os.environ.get("TUSHARE_TOKEN") or os.environ.get("TS_TOKEN")
+
+# Dry-run / smoke: limit universe size (0 = no limit)
+MAX_STOCKS = int(os.environ.get("CNCS_MAX_STOCKS", "0") or "0")
+
+# Parallel-ish batch size for OHLCV downloads (symbols per HTTP batch call)
+OHLCV_BATCH = int(os.environ.get("CNCS_OHLCV_BATCH", "25") or "25")
+
+# Tushare official limits vary by endpoint/account; default leaves room below 500/min.
+TUSHARE_MAX_REQUESTS_PER_MINUTE = int(os.environ.get("CNCS_TUSHARE_RPM", "450") or "450")
+
+for d in (DATA_RAW_VENDOR, DATA_CANONICAL, DATA_INTERMEDIATE, DATA_FACTORS):
+    d.mkdir(parents=True, exist_ok=True)

data/__init__.py

@@ -0,0 +1 @@
+"""Raw + intermediate data pipeline."""

data/capabilities/tushare.yaml

@@ -0,0 +1,22 @@
+vendor: tushare
+capabilities:
+  daily_ohlcv: true
+  adjusted_prices: true
+  daily_valuation: true
+  pit_financials: partial
+  financial_actual_disclosure_date: true
+  historical_st: true
+  suspension_daily: true
+  index_membership: true
+  index_daily: true
+  snapshot_industry: true
+  pit_industry: false
+  intraday_quotes: false
+  tick_quotes: false
+  analyst_forecasts: partial
+  northbound_holdings: true
+  margin_trading: true
+  money_flow: true
+notes:
+  - "Tushare is the bootstrap open-source vendor, not the canonical architecture boundary."
+  - "Capabilities marked partial require factor-level documentation before use."

data/contracts/raw_tables.yaml

@@ -0,0 +1,130 @@
+tables:
+  - name: stock_basic
+    primary_key: [ts_code, list_status]
+    date_columns: [list_date, delist_date]
+    partition_keys: [snapshot_date]
+    unit_notes: "snapshot table; include listed, delisted, and paused names"
+    pit_available: false
+    incremental_key: snapshot_date
+    used_by: [universe, signal_master]
+    known_limitations: "Market/industry metadata may be current snapshot rather than PIT history."
+
+  - name: daily
+    primary_key: [ts_code, trade_date]
+    date_columns: [trade_date]
+    partition_keys: [trade_year, trade_month]
+    unit_notes: "amount is yuan in canonical raw."
+    pit_available: true
+    incremental_key: trade_date
+    used_by: [signal_master, price_predictors]
+    known_limitations: "Rows can be absent on non-trading or fully suspended days depending on source."
+
+  - name: adj_factor
+    primary_key: [ts_code, trade_date]
+    date_columns: [trade_date]
+    partition_keys: [trade_year, trade_month]
+    unit_notes: "close_adj = close * adj_factor."
+    pit_available: true
+    incremental_key: trade_date
+    used_by: [signal_master, returns]
+    known_limitations: "Adjustment factors can be restated after corporate actions."
+
+  - name: daily_basic
+    primary_key: [ts_code, trade_date]
+    date_columns: [trade_date]
+    partition_keys: [trade_year, trade_month]
+    unit_notes: "total_mv and circ_mv are 10k yuan in canonical raw unless normalized later."
+    pit_available: true
+    incremental_key: trade_date
+    used_by: [signal_master, valuation, liquidity]
+    known_limitations: "Some fields can be null for early or special securities."
+
+  - name: income
+    primary_key: [ts_code, report_period, notice_date, report_type]
+    date_columns: [report_period, notice_date, final_notice_date]
+    partition_keys: [report_year]
+    unit_notes: "statement original monetary units from source; keep source raw values for audit."
+    pit_available: true
+    incremental_key: notice_date
+    used_by: [pit_financials, profitability, valuation]
+    known_limitations: "Restatements and update flags need audit in later versions."
+
+  - name: balancesheet
+    primary_key: [ts_code, report_period, notice_date, report_type]
+    date_columns: [report_period, notice_date, final_notice_date]
+    partition_keys: [report_year]
+    unit_notes: "statement original monetary units from source; keep source raw values for audit."
+    pit_available: true
+    incremental_key: notice_date
+    used_by: [pit_financials, valuation, investment, quality]
+    known_limitations: "Equity and share-cap fields differ by source and availability."
+
+  - name: cashflow
+    primary_key: [ts_code, report_period, notice_date, report_type]
+    date_columns: [report_period, notice_date, final_notice_date]
+    partition_keys: [report_year]
+    unit_notes: "statement original monetary units from source; keep source raw values for audit."
+    pit_available: true
+    incremental_key: notice_date
+    used_by: [pit_financials, accruals, cashflow_predictors]
+    known_limitations: "Operating cashflow can be null for some report types."
+
+  - name: fina_indicator
+    primary_key: [ts_code, report_period, notice_date]
+    date_columns: [report_period, notice_date]
+    partition_keys: [report_year]
+    unit_notes: "derived financial ratios; definitions must be documented before predictor use."
+    pit_available: true
+    incremental_key: notice_date
+    used_by: [profitability, gross_profitability]
+    known_limitations: "Derived definitions and null patterns differ across sources."
+
+  - name: disclosure_date
+    primary_key: [ts_code, report_period]
+    date_columns: [report_period, notice_date]
+    partition_keys: [report_year]
+    unit_notes: "notice_date is the best available actual disclosure date."
+    pit_available: true
+    incremental_key: notice_date
+    used_by: [pit_financials]
+    known_limitations: "Appointment dates can be revised; actual disclosure date is preferred."
+
+  - name: stock_st
+    primary_key: [ts_code, trade_date, type]
+    date_columns: [trade_date]
+    partition_keys: [trade_year, trade_month]
+    unit_notes: "Historical ST flags."
+    pit_available: true
+    incremental_key: trade_date
+    used_by: [signal_master, universe_filters]
+    known_limitations: "Coverage should be verified on older years."
+
+  - name: suspend_d
+    primary_key: [ts_code, trade_date]
+    date_columns: [trade_date]
+    partition_keys: [trade_year, trade_month]
+    unit_notes: "Daily suspension flag."
+    pit_available: true
+    incremental_key: trade_date
+    used_by: [signal_master, tradability_flags]
+    known_limitations: "Intraday suspension timing is not modeled in v0.1."
+
+  - name: index_daily
+    primary_key: [index_symbol, trade_date]
+    date_columns: [trade_date]
+    partition_keys: [index_symbol, trade_year, trade_month]
+    unit_notes: "index ret is decimal return."
+    pit_available: true
+    incremental_key: trade_date
+    used_by: [signal_master, market_model]
+    known_limitations: "Default broad market index is 000300.SH unless configured."
+
+  - name: index_weight
+    primary_key: [index_code, ts_code, trade_date]
+    date_columns: [trade_date]
+    partition_keys: [index_code]
+    unit_notes: "Use latest rebalance before as-of date."
+    pit_available: true
+    incremental_key: trade_date
+    used_by: [universe_membership]
+    known_limitations: "Membership PIT requires as-of join by rebalance date."

data/downloads/__init__.py

@@ -0,0 +1 @@
+"""Scripts to populate ``pyData/raw`` from a :class:`data.sources.base.DataSource`."""