Document and display the Ridge–XGBoost ensemble shadow portfolio

Author: HanSun103

README.md

@@ -282,12 +282,14 @@ frozen-snapshot contract, dashboard timestamps, model-overlap metrics, and gener
 The [GitHub Pages deployment guide](docs/GITHUB_PAGES_DEPLOYMENT.md) documents the public-data
 boundary, static-site publication, validation gate, and one-time repository configuration.
 
-The daily command first refreshes the latest prior Ridge and XGBoost portfolios against the
+The daily command first refreshes the latest prior Ridge, XGBoost, and available ensemble
+portfolios against the
 completed session. Yahoo's final hourly bar begins at 15:30, so the command requires that bar and
 retries five times at 60-second intervals if it is not available yet. It evaluates the frozen
 portfolios and refreshes both dashboard outputs before the longer tuning stage begins. It then
 requires an official daily price row for the decision date, independently tunes and refits Ridge
-and XGBoost, saves both new top-40 portfolios, writes
+and XGBoost, saves both new top-40 portfolios, freezes a separate temporally selected 25% Ridge /
+75% XGBoost percentile-rank ensemble shadow portfolio, writes
 `selection_stability_YYYY-MM-DD.json`, and refreshes both dashboards again. The stability report
 tracks same-day model overlap, day-over-day retention, top-10 persistence, rank correlation,
 entrants/exits, implied replacement, and multi-day consensus names. This ordering makes the

docs/LIVE_FORWARD_MONITOR.md

@@ -30,9 +30,12 @@ The command performs these steps in order:
    decision date.
 7. Tunes Ridge and XGBoost independently on temporal validation data, refits the selected
    configurations, and freezes both top-40 lists for the next evaluation session.
-8. Writes model-agreement, day-over-day selection-stability diagnostics, and candidate split
+8. Freezes a separate shadow portfolio by blending the two full-universe percentile rankings
+   with the historically selected 25% Ridge / 75% XGBoost weight and applying the same top-40
+   sector cap.
+9. Writes model-agreement, day-over-day selection-stability diagnostics, and candidate split
    features that are not yet eligible for model fitting.
-9. Rebuilds both dashboard outputs again so they include the newly frozen pending portfolios.
+10. Rebuilds both dashboard outputs again so they include the newly frozen pending portfolios.
 
 If final market data is unavailable, the command retries and then fails closed. It must not create a
 snapshot from a partial trading day.
@@ -84,8 +87,10 @@ decision date or its future return.
   into an earlier feature row.
 - Split features use only completed split events on or before the feature date. Upcoming splits
   require a separate timestamped announcement source and are not inferred from future event dates.
-- Ridge and XGBoost are displayed together; neither is chosen retrospectively using realized live
-  returns.
+- Ridge, XGBoost, and the shadow ensemble are displayed together; none is chosen retrospectively
+  using realized live returns.
+- The ensemble uses 25% Ridge / 75% XGBoost, selected by expanding historical OOS folds. Each fold's
+  reported weight used only earlier completed folds; no live realized return selected the weight.
 - The July 20 session is a setup/test observation. The official comparison baseline begins at the
   July 20 SPY close, and portfolio performance begins on July 21.
 
@@ -131,6 +136,9 @@ Generated outputs remain under the ignored `reports/live_forward/` directory:
 
 - dated Ridge and XGBoost snapshot directories with manifests, tuning results, predictions, and
   selected holdings;
+- dated `ridge_xgb_ensemble/` shadow snapshots with normalized component ranks, selected holdings,
+  and SHA-256 hashes of both source score files;
+- a model-aware `live_forward_results.csv` rebuilt from the canonical per-snapshot summaries;
 - intraday and close-to-close evaluation files for each frozen portfolio;
 - holding-level returns, benchmark-relative returns, and beat-SPY indicators for completed sessions;
 - `selection_stability_YYYY-MM-DD.json`;
@@ -144,9 +152,16 @@ one-time repository setting.
 Keep source code, configurations, tests, and documentation in Git. Do not commit cached prices,
 trained artifacts, generated reports, credentials, or temporary pytest directories.
 
+The consolidated result key is `(model, decision_date, evaluation date, horizon, benchmark)`.
+Including `model` prevents one same-session XGBoost observation from overwriting Ridge. If the
+table is missing or suspected to be stale, `rebuild_live_forward_results()` reconstructs it from
+the intact canonical snapshot JSON files; archived experimental variants are not mixed into the
+official live history.
+
 ## Interpretation boundary
 
-The live sample is currently too short for a performance claim. Compare Ridge, XGBoost, and SPY over
-many independent sessions, then report active return, Rank IC, turnover, drawdown, and uncertainty.
-Model overlap is diagnostically useful, but high consensus is neither necessary nor sufficient for
-outperformance.
+The live sample is currently too short for a performance claim. Compare Ridge, XGBoost, the
+predeclared ensemble, and SPY over many independent sessions, then report active return, turnover,
+drawdown, and uncertainty. Rank IC remains a component-model diagnostic; it is not available for
+the ensemble until paired historical out-of-sample scores are persisted. Model overlap is
+diagnostically useful, but high consensus is neither necessary nor sufficient for outperformance.

docs/experiments/2026-07-27-ridge-xgb-rank-ensemble.md

@@ -0,0 +1,44 @@
+# Ridge-XGBoost Rank Ensemble
+
+## Question
+
+Can Ridge's broad linear ranking and XGBoost's nonlinear top-tail selection be combined without
+using the live-forward outcomes to choose the blend?
+
+## Design
+
+- Inputs: paired Ridge and XGBoost OOS predictions retained by the v10 experiment.
+- Period: seven chronological outer folds from 2020-01-10 through 2023-06-30.
+- Rows: 45,484 ticker-date predictions.
+- Normalization: within-date percentile rank for each model.
+- Candidate Ridge weights: 0%, 25%, 50%, 75%, and 100%; XGBoost receives the remainder.
+- Selection rule: for each outer fold after the first, choose the weight with the best top-40 raw
+  excess return using only completed earlier OOS folds. The first fold uses 50/50.
+- Portfolio rule: 40 equal-weight names with the same 25% sector cap.
+
+This expanding prior-fold rule prevents the evaluated fold's realized returns from selecting its
+own weight.
+
+## Results
+
+| Model | Mean Rank IC | Top-40 excess per weekly observation |
+|---|---:|---:|
+| Ridge | 0.00560 | 0.1436% |
+| XGBoost ranker | 0.00222 | 0.2121% |
+| Earlier Ridge-LightGBM-XGBoost ensemble | 0.00142 | -0.0760% |
+| New temporal Ridge-XGBoost ensemble | 0.00188 | 0.1825% |
+
+After the first fold, the expanding history selected 25% Ridge / 75% XGBoost for every subsequent
+fold. Using all completed historical OOS folds, that is also the frozen weight for the next live
+shadow portfolio.
+
+## Conclusion
+
+Removing LightGBM repairs the earlier ensemble failure. The two-model blend improves top-40 excess
+over Ridge, but does not beat XGBoost's historical point estimate. It remains useful as a
+diversification challenger because it reduces reliance on XGBoost without discarding its stronger
+top-tail signal. The live test must determine whether that trade-off improves realized stability.
+
+No claim should be made from the weight-selection objective on all historical folds. The primary
+historical ensemble estimate is the expanding prior-fold result, and the live portfolio is evaluated
+only after it is frozen.

site/assets/dashboard.js

@@ -1,10 +1,10 @@
 {
   "schema_version": 1,
-  "generated_at_utc": "2026-07-27T21:49:58.674643+00:00",
+  "generated_at_utc": "2026-07-27T23:01:45.416516+00:00",
   "latest_decision_date": "2026-07-27",
-  "snapshot_count": 13,
+  "snapshot_count": 14,
   "evaluation_count": 11,
-  "dashboard_sha256": "8eef32a85c89066d74e51f15698a92cd733de04ca6cbb48cc29bddb6396b171b",
-  "dashboard_bytes": 236813,
+  "dashboard_sha256": "b33b26ce655ddef3a9eab8150a79977584de64bd7c47a45c7549a32c4ad1f906",
+  "dashboard_bytes": 243869,
   "source_policy": "sanitized_live_forward_outputs_only"
 }

site/data/dashboard.json

@@ -1372,6 +1372,7 @@ def validate_live_dashboard_site_command(site_dir: str) -> None:
 @click.option("--optuna-trials", default=50, show_default=True, type=int)
 @click.option("--ridge-optuna-trials", default=None, type=int)
 @click.option("--xgb-optuna-trials", default=None, type=int)
+@click.option("--ensemble-ridge-weight", default=0.25, show_default=True, type=float)
 @click.option("--optuna-timeout-seconds", default=1800, show_default=True, type=int)
 @click.option("--tuning-folds", default=5, show_default=True, type=int)
 @click.option("--close-retries", default=5, show_default=True, type=int)
@@ -1384,6 +1385,7 @@ def run_live_forward_daily_command(
     optuna_trials: int,
     ridge_optuna_trials: int | None,
     xgb_optuna_trials: int | None,
+    ensemble_ridge_weight: float,
     optuna_timeout_seconds: int,
     tuning_folds: int,
     close_retries: int,
@@ -1400,6 +1402,7 @@ def run_live_forward_daily_command(
     from .experiments.live_forward_test import (
         analyze_live_selection_stability,
         build_live_dashboard,
+        build_live_rank_ensemble,
         evaluate_live_forward_snapshot,
         generate_intraday_benchmark_report,
         latest_prior_model_snapshots,
@@ -1487,6 +1490,16 @@ def run_live_forward_daily_command(
         optuna_trials=xgb_optuna_trials or optuna_trials,
         **common,
     )
+    ensemble = build_live_rank_ensemble(
+        ridge["output"],
+        xgb["output"],
+        output_root=root / "ridge_xgb_ensemble",
+        ridge_weight=ensemble_ridge_weight,
+        holdings=holdings,
+        weight_selection_report=(
+            "docs/experiments/2026-07-27-ridge-xgb-rank-ensemble.md"
+        ),
+    )
     stability = analyze_live_selection_stability(root, decision)
     dashboard = build_live_dashboard(root)
     public_site = publish_live_dashboard(root, public_site_dir)
@@ -1499,6 +1512,7 @@ def run_live_forward_daily_command(
         "pretraining_public_site": pretraining_public_site["output_dir"],
         "ridge_output": ridge["output"],
         "xgb_output": xgb["output"],
+        "ensemble_output": ensemble["output"],
         "selection_stability": stability["output"],
         "dashboard": dashboard["dashboard"],
         "public_site": public_site["output_dir"],

site/data/manifest.json

@@ -96,7 +96,7 @@ def dashboard_site_assets() -> dict[str, str]:
 <section class="section panel"><div class="section-head"><div><h2>Experiment history</h2><p>Newest evaluated evidence is shown first. Filter the archive and sort any column as it grows.</p></div><div class="history-controls"><label>Browse by<select id="historyGroup"><option value="evaluation_date">Evaluation date</option><option value="model">Selected model</option></select></label><label id="historyValueLabel">Evaluation date<select id="historyValue"></select></label><label>Rows<select id="historyLimit"><option value="6">Latest 6</option><option value="12">Latest 12</option><option value="all">All matching</option></select></label></div></div><div id="historyTable"></div></section>
 </main><script id="dashboard-data" type="application/json">__DASHBOARD_PAYLOAD__</script><script>
 const snapshots=JSON.parse(document.getElementById('dashboard-data').textContent),startDate=document.getElementById('startDate'),endDate=document.getElementById('endDate'),stockDate=document.getElementById('stockDate'),stockModel=document.getElementById('stockModel'),historyGroup=document.getElementById('historyGroup'),historyValue=document.getElementById('historyValue'),historyLimit=document.getElementById('historyLimit'),refreshData=document.getElementById('refreshData'),STATE_KEY='live-forward-dashboard-state-v1';let savedState={};try{savedState=JSON.parse(localStorage.getItem(STATE_KEY)||'{}')}catch{}let historySort=savedState.historySort||{key:'evaluation_date',direction:'desc'},stockSort=savedState.stockSort||{key:'rank',direction:'asc'};function saveState(){const active=document.querySelector('[data-range].active');try{localStorage.setItem(STATE_KEY,JSON.stringify({startDate:startDate.value,endDate:endDate.value,range:active?.dataset.range||'custom',stockDate:stockDate.value,stockModel:stockModel.value,historyGroup:historyGroup.value,historyValue:historyValue.value,historyLimit:historyLimit.value,historySort,stockSort}))}catch{}}
-const COLORS={ridge:'#3156d3',xgb_ranker:'#0f9f8f',benchmark:'#d89614'},human=(v='')=>String(v).replaceAll('_',' ').replace(/\b\w/g,c=>c.toUpperCase()),modelName=v=>({ridge:'Ridge',xgb_ranker:'XGBoost ranker'}[v]||human(v)),fmtPct=v=>v==null||Number.isNaN(Number(v))?'n/a':(Number(v)*100).toFixed(2)+'%',fmtNum=(v,d=4)=>v==null||Number.isNaN(Number(v))?'n/a':Number(v).toFixed(d),cls=v=>Number(v)>=0?'pos':'neg';function barEndLabel(value){const parts=String(value).split(' ');if(parts.length<2)return String(value);const date=parts[0].slice(5),time=parts[1];if(time==='16:00:00')return`${date} 16:00`;if(time==='15:30:00')return`${date} 16:00`;const bits=time.split(':').map(Number);return`${date} ${String(bits[0]+1).padStart(2,'0')}:${String(bits[1]).padStart(2,'0')}`}
+const COLORS={ridge:'#3156d3',xgb_ranker:'#0f9f8f',ridge_xgb_ensemble:'#7559c7',benchmark:'#d89614'},human=(v='')=>String(v).replaceAll('_',' ').replace(/\b\w/g,c=>c.toUpperCase()),modelName=v=>({ridge:'Ridge',xgb_ranker:'XGBoost ranker',ridge_xgb_ensemble:'Ridge–XGBoost ensemble'}[v]||human(v)),fmtPct=v=>v==null||Number.isNaN(Number(v))?'n/a':(Number(v)*100).toFixed(2)+'%',fmtNum=(v,d=4)=>v==null||Number.isNaN(Number(v))?'n/a':Number(v).toFixed(d),cls=v=>Number(v)>=0?'pos':'neg';function barEndLabel(value){const parts=String(value).split(' ');if(parts.length<2)return String(value);const date=parts[0].slice(5),time=parts[1];if(time==='16:00:00')return`${date} 16:00`;if(time==='15:30:00')return`${date} 16:00`;const bits=time.split(':').map(Number);return`${date} ${String(bits[0]+1).padStart(2,'0')}:${String(bits[1]).padStart(2,'0')}`}
 function option(v,t){const e=document.createElement('option');e.value=v;e.textContent=t;return e}function evals(s){const a=[...(s.evaluations||[])];if(s.intraday)a.unshift({...s.intraday,horizon_label:'Intraday monitor',holdings:[]});return a}function chartEval(s){return s.intraday||(s.evaluations||[]).at(-1)||null}function monitorDate(s){const e=chartEval(s);return e?.monitor_date||e?.eval_date||e?.series?.[0]?.timestamp?.slice(0,10)||s.decision_date}
 const trackedModels=[...new Set(snapshots.filter(chartEval).map(s=>s.model_id))],dateModelCounts=new Map;snapshots.filter(chartEval).forEach(s=>{const d=monitorDate(s);if(!dateModelCounts.has(d))dateModelCounts.set(d,new Set);dateModelCounts.get(d).add(s.model_id)});const dates=[...dateModelCounts.entries()].filter(([,models])=>models.size===trackedModels.length).map(([d])=>d).sort();if(dates.length){startDate.value=dates.includes(savedState.startDate)?savedState.startDate:dates[0];endDate.value=dates.includes(savedState.endDate)?savedState.endDate:dates.at(-1);startDate.min=endDate.min=dates[0];startDate.max=endDate.max=dates.at(-1)}document.querySelectorAll('[data-range]').forEach(b=>b.classList.toggle('active',(savedState.range||'all')===b.dataset.range));if([...historyGroup.options].some(o=>o.value===savedState.historyGroup))historyGroup.value=savedState.historyGroup;if([...historyLimit.options].some(o=>o.value===savedState.historyLimit))historyLimit.value=savedState.historyLimit;
 function filtered(){return snapshots.filter(s=>{const d=monitorDate(s);return chartEval(s)&&(!startDate.value||d>=startDate.value)&&(!endDate.value||d<=endDate.value)})}