Risk Estimators
The functions demonstrated below (that live in q.stats) estimate downside and tail risk from periodic returns. Every risk estimator returns a non-negative loss magnitude: 0.05 means a 5% loss. Estimator families are explicit in their names so historical and Gaussian assumptions cannot be confused.
historical_var = q.stats.historical_value_at_risk(returns, confidence=0.95)
historical_es = q.stats.historical_expected_shortfall(returns, confidence=0.95)
gaussian_var = q.stats.gaussian_value_at_risk(returns, confidence=0.95)
gaussian_es = q.stats.gaussian_expected_shortfall(returns, confidence=0.95)
evar = q.stats.entropic_value_at_risk(returns, confidence=0.95)
tce = q.stats.tail_conditional_expectation(returns, confidence=0.95)
maximum_loss = q.stats.maximum_observed_dollar_loss(returns, notional=1_000_000)
lpm_2 = q.stats.lower_partial_moment(returns, threshold=0.0, order=2)The input frequency defines the horizon. A result calculated from daily returns is a one-day risk estimate; a result calculated from weekly returns is a one-week estimate. These functions do not scale a result to another horizon.
A 95% Value at Risk of 2% is best read as: 2% is the estimated 95th percentile of one-period losses. Under the estimator’s assumptions, losses should exceed 2% in roughly 5% of periods. It does not mean that 2% is the largest possible loss, nor does it guarantee that exactly 5% of future periods will breach it.
Historical Value at Risk
historical_value_at_risk finds the requested loss percentile directly from the observed return history. It answers: where does the worst 5% of the observed distribution begin?
If daily historical VaR at 95% is 2%, the estimated one-day loss threshold is 2%: about 5% of periods in a comparable loss distribution are expected to lose 2% or more.
This is useful for setting a simple loss limit, comparing strategies on a common confidence level, and locating the start of the tail. It makes no normal distribution assumption, but it assumes the available history is relevant to the future. It says nothing about how large a loss can become after the threshold is crossed.
Historical Expected Shortfall
historical_expected_shortfall averages the worst 1 - confidence share of observed losses. It answers: when we are already in the bad tail, how much do we lose on average?
If daily historical expected shortfall at 95% is 3.5%, the average loss among the worst 5% of one-day outcomes is estimated to be 3.5%.
Expected shortfall adds the severity information that VaR omits. It is useful when two strategies have similar VaR but one has much larger losses beyond that point. The implementation includes fractional boundary mass, so the requested tail always represents exactly 1 - confidence of a finite sample.
Gaussian VaR and Expected Shortfall
gaussian_value_at_risk and gaussian_expected_shortfall estimate the same threshold and tail-average concepts after fitting a normal distribution from the sample mean and standard deviation.
A 95% Gaussian VaR of 1.8% means that the fitted normal model places 95% of one-period losses below 1.8% and 5% at or above it. A 95% Gaussian expected shortfall of 2.3% means the fitted model’s average loss within that worst 5% is 2.3%.
These estimators produce smooth estimates and can be useful with limited data or for model-based comparisons. Financial returns often have skewness, fat tails, and changing volatility, however, so a Gaussian model can understate extreme risk. Compare it with the historical estimates rather than treating the normal assumption as fact.
Tail Conditional Expectation
tail_conditional_expectation first finds historical VaR, then averages every observed loss at or beyond that threshold. It answers the same practical question as expected shortfall: what was the average loss when the VaR boundary was reached or breached?
If 95% historical VaR is 2% and tail conditional expectation is 3.7%, the observations that lost at least 2% lost 3.7% on average.
Unlike historical_expected_shortfall, this function includes all observations tied at the VaR threshold. The two measures are often equal for continuous data, but can differ when returns are rounded, repeated, or the tail contains a fractional observation. Prefer historical expected shortfall when you need an exact fixed-probability tail; use TCE when “all observations beyond this boundary” is the intended set.
Entropic Value at Risk
entropic_value_at_risk (EVaR) uses the exponential moments of the loss distribution to calculate a conservative upper bound on VaR. It gives more influence to severe losses and answers: what loss bound is implied when increasingly bad outcomes receive exponentially more weight?
If daily EVaR at 95% is 4.1%, the entropic bound for the 95% one-day loss quantile is 4.1%. This is a conservative risk bound, not a statement that the average bad-tail loss is 4.1%.
EVaR is useful when a coherent, tail-sensitive risk limit is preferred to a plain quantile. It is generally at least as large as VaR for the same empirical distribution and confidence. Its conservatism can make it less intuitive than VaR or expected shortfall, and its estimate still depends on the observed loss distribution.
Maximum Observed Dollar Loss
maximum_observed_dollar_loss converts the worst observed one-period percentage loss into currency using the supplied notional.
If the worst daily return was -6% and the notional is $1,000,000, maximum observed dollar loss is $60,000.
This gives an immediate historical worst-case amount for sizing and review. It is not a probabilistic estimate, a portfolio revaluation, or a stress test: a future loss can exceed the worst loss in the sample. See maximum drawdown for the different concept of the largest cumulative peak-to-trough decline.
Lower Partial Moment
lower_partial_moment measures how often and by how much returns fall below a chosen target \(\tau\):
\[ E[\max(\tau-R, 0)^n], \]
where \(n\) controls how strongly large shortfalls are penalized.
- Order 0 is the probability of missing the target. A value of 0.30 means 30% of periods returned less than \(\tau\).
- Order 1 is average shortfall across all periods, counting periods above the target as zero. A value of 0.006 means an average target shortfall of 0.6% per period.
- Order 2 is downside semivariance around the target. Large misses receive disproportionately more weight; its units are squared returns, so compare it across strategies rather than reading it directly as a percentage.
Lower partial moments are useful when risk means “failing to reach my target” rather than merely having volatile returns. Setting \(\tau=0\) measures downside relative to break-even; setting it to a required return measures failure relative to that objective. Order 2 is related to semivariance.
Choosing a measure
| Question | Measure |
|---|---|
| Where does the bad tail begin in observed data? | Historical VaR |
| How severe is the worst fixed share of observed outcomes? | Historical expected shortfall |
| What do those quantities look like under a normal model? | Gaussian VaR / expected shortfall |
| What happened in every observation at or beyond the VaR boundary? | Tail conditional expectation |
| What conservative tail-sensitive bound can I use? | EVaR |
| What was the worst observed loss in currency? | Maximum observed dollar loss |
| How often and how badly did returns miss a target? | Lower partial moment |
All of these are estimates, not guarantees. Use enough data to represent different market regimes, report the input horizon and confidence with every result, and supplement distribution estimates with scenario and stress tests.
These functions describe a return distribution. Holdings-aware component and marginal risk, stress scenarios, and liquidity adjustments live in q.portfolio.risk submodule.