Portfolio Risk Monitoring¶
Overview
| Item | Description |
|---|---|
| Goal | Run portfolio-level risk reviews over multiple strategy backtest results with PortfolioRiskMonitor |
| Prerequisite | Running a Backtest |
1. Portfolio Risk Monitoring¶
PortfolioRiskMonitor answers one question: "if I run these strategies together, how risky is the combined portfolio?" It covers portfolio VaR, cross-strategy correlation, position concentration, and a four-level alert system (normal / yellow / red / kill-switch).
It works as a post-backtest review: run each strategy through run_backtest(), feed the returned result dicts into the monitor, then call daily_check() for a report. It is not a live intraday monitor — there is no update(), no callbacks, and no paper-trading hookup. The runnable end-to-end demo is examples/14_portfolio_risk.py.
1.1 Basic Usage¶
from eqlib import PortfolioRiskMonitor, RiskThresholds
monitor = PortfolioRiskMonitor() # default thresholds
# Backtest each strategy separately and register its result dict
result_a = run_backtest(initialize_a, start_date="2024-01-01", end_date="2024-12-31")
result_b = run_backtest(initialize_b, start_date="2024-01-01", end_date="2024-12-31")
monitor.add_strategy("trend", result_a)
monitor.add_strategy("mean_reversion", result_b)
report = monitor.daily_check()
print(report.alert_level) # AlertLevel.NORMAL / YELLOW / RED / KILL_SWITCH
print(report.triggers) # triggered alerts
print(report.recommendations) # suggested actions
add_strategy(name, backtest_result) requires a result dict with a non-empty recorded_values, otherwise it raises ValueError; reusing a name overwrites the entry and emits a UserWarning.
1.2 Threshold Configuration: RiskThresholds¶
from eqlib import PortfolioRiskMonitor, RiskThresholds
thresholds = RiskThresholds(
max_drawdown_yellow=0.15, # portfolio drawdown: yellow alert
max_drawdown_red=0.20, # portfolio drawdown: red alert
max_drawdown_kill=0.25, # portfolio drawdown: kill switch
correlation_yellow=0.60, # strategy correlation: yellow alert
correlation_red=0.75, # strategy correlation: red alert
correlation_kill=0.85, # strategy correlation: kill switch
single_stock_max=0.10, # max single-stock weight
single_sector_max=0.30, # max single-sector weight
small_cap_max=0.20, # max small-cap (< 5B CNY market cap) weight
var_confidence=0.95, # VaR confidence level
)
monitor = PortfolioRiskMonitor(thresholds=thresholds)
The table above lists every field with its default. Drawdown and correlation escalate through the three levels; concentration checks are plain threshold comparisons (see §1.6 for the trigger rules).
1.3 Portfolio VaR¶
var_amount, var_pct = monitor.portfolio_var(confidence=0.95)
print(f"Daily VaR: {var_amount:,.0f} CNY ({var_pct:.2%})")
Historical simulation: combine the strategies' daily return series weighted by latest portfolio value, then take the left-tail quantile. Reading: at 95% confidence, the chance of the portfolio losing more than this in a single day is about 5%.
Constraints:
- Each strategy needs at least 30 trading days of returns; shorter series are excluded and recorded in the internal issue list.
- If all strategies fall short, it returns
(nan, nan)— check withpd.isna(var_amount). confidencedefaults tothresholds.var_confidence.
For a single return series there is also eqlib.utils.value_at_risk(returns, confidence=0.05, method=...) with 'historical', 'parametric', and 'cornish_fisher' methods — cornish_fisher adjusts the normal assumption for sample skew and kurtosis, which fits fat-tailed A-share returns better. Note its confidence is the tail probability (0.05), the opposite direction of portfolio_var's confidence level (0.95).
1.4 Strategy Correlation Matrix¶
Returns a DataFrame of Pearson correlations with strategy names on both axes. With fewer than 2 strategies — or fewer than 2 strategies having 30+ days of data — it returns an empty DataFrame. Highly correlated strategies move together and the portfolio gets no diversification; daily_check() grades the maximum pairwise correlation against the §1.2 thresholds.
1.5 Concentration Risk¶
conc = monitor.concentration_risk()
print(conc["num_holdings"]) # number of holdings
print(conc["max_single_stock"]) # max single-stock weight
print(conc["top3_concentration"]) # combined weight of the top 3 holdings
Returned keys: max_single_stock, max_single_sector, small_cap_pct, num_holdings, top3_concentration. Data comes from each strategy result's context.portfolio (the position snapshot at backtest end).
Take two fields with a grain of salt:
max_single_sectorhas no sector data source — it conservatively equalsmax_single_stock.small_cap_pcthas no market-cap data source — it is always 0.0.
1.6 Daily Check and Kill Switch¶
daily_check() runs every metric above through the thresholds and returns a RiskReport:
| Field | Content |
|---|---|
timestamp |
Report time |
alert_level |
AlertLevel.NORMAL / YELLOW / RED / KILL_SWITCH |
triggers |
Triggered alert messages |
portfolio_var / portfolio_var_pct |
Portfolio VaR amount and percentage |
correlation_matrix |
Correlation matrix (None if insufficient) |
concentration |
Concentration dict (None if no holdings) |
regime |
Market regime: 'bull' / 'bear' / 'oscillation' / 'unknown' |
recommendations |
Suggested actions |
Level semantics: NORMAL when no condition triggered at all; any trigger (even "choppy market right now") means at least YELLOW; RED calls for human review; KILL_SWITCH means portfolio drawdown reached max_drawdown_kill or the maximum correlation reached correlation_kill — pause strategies and wait for manual confirmation. A single-stock weight beyond twice single_stock_max also escalates to RED.
check_kill_switch(report) translates the report into a list of action items; an empty list means no action needed:
from eqlib import check_kill_switch, AlertLevel
actions = check_kill_switch(report)
if report.alert_level == AlertLevel.KILL_SWITCH:
for action in actions:
print(action) # pause strategies / cut correlated positions by 50%, etc.
The regime field fetches the CSI 300 over the last 90 real calendar days via get_price to classify bull/bear — it is independent of the backtest window and requires network access; it returns 'unknown' when data is unavailable.
See the Portfolio Risk API Reference for full parameter documentation. The runnable end-to-end demo is examples/14_portfolio_risk.py.