Component Value at Risk (cVaR)
Calculate the Component Value at Risk (Component VaR) of each asset in a portfolio.
Component VaR allocates total portfolio VaR across its constituent assets, such that the allocations sum exactly back to the portfolio VaR - an “Euler” (or “fully consistent”) risk decomposition.
The formula is as follows (with the default distribution=”historic”):
\[\text{Component VaR}_{i} = \text{weight}_{i} \cdot \text{Marginal VaR}_{i}\] \[\operatorname{SUM}(\text{Component VaR}_{i}) = \text{Portfolio VaR}\]Where the weights are normalized to sum to 1 and Marginal VaR_i is that of get_marginal_value_at_risk: Beta_i * Portfolio VaR by default, or the exact derivative with distribution=”gaussian”.
Where Marginal VaR measures each asset’s risk sensitivity, Component VaR measures its actual contribution in the same units as portfolio VaR, making it directly usable to identify which holdings account for the largest share of portfolio risk.
Component VaR is the basis of risk budgeting: a holding with a 20% weight that accounts for 45% of the portfolio VaR stands out immediately, and a component with the opposite sign of the portfolio VaR marks a holding that hedges the rest. The components always add up to the portfolio VaR, but the beta-based allocation is exact only for normally (elliptically) distributed returns and an approximation for the historical distribution used by default.
For more information about the method, see the following sources:
- Garman, M.B. (1997). “Taking VaR to Pieces.” Risk, 10(10), 70-71.
- Litterman, R. (1996). “Hot Spots and Hedges.” Goldman Sachs Risk Management Series.
- Jorion, P. (2006). “Value at Risk: The New Benchmark for Managing Financial Risk.” 3rd ed., McGraw-Hill, Chapter 7.
Also known as: Component VaR, risk contribution.
Component Value at Risk (cVaR) in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_component_value_at_risk as shown below.
from financetoolkit import Toolkit
toolkit = Toolkit(
["VTI", "AGG", "GLD", "VNQ"],
api_key="FINANCIAL_MODELING_PREP_KEY",
start_date="2021-01-01",
end_date="2025-12-31",
)
toolkit.risk.get_component_value_at_risk(
weights={"VTI": 0.5, "AGG": 0.3, "GLD": 0.1, "VNQ": 0.1}
)
Or, after setting up the Finance Toolkit MCP, ask:
How much does each holding contribute to the Value at Risk of a portfolio of 50% VTI, 30% AGG, 10% GLD and 10% VNQ, based on returns from 2021 to 2025?
Which returns:
| Component VaR | |
|---|---|
| VTI | -0.0081 |
| AGG | -0.0008 |
| GLD | -0.0005 |
| VNQ | -0.0015 |
| Portfolio | -0.0109 |
Parameters
get_component_value_at_risk accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
weights | dict[str, float] | None | Portfolio weights keyed by ticker. Normalized internally to sum to 1. Defaults to None, which uses equal weights across every ticker in the Toolkit instance (excluding the “Portfolio” and “Benchmark” pseudo-tickers, if present). | {"AAPL": 0.6, "MSFT": 0.4} |
period | str | The data frequency (daily, weekly, monthly, quarterly, or yearly). Defaults to “daily”, since a whole-series estimate needs far more observations than a single quarter or year holds. | "weekly" |
column | str | The historical data column to use. Defaults to “Return”. | "Return" |
alpha | float | The tail probability (e.g., 0.05 for the 95% confidence level). Defaults to 0.05. | 0.01 |
distribution | str | The distribution to use for the underlying portfolio VaR calculation (historic, gaussian, cornish-fisher or studentt). Defaults to “historic”. | "studentt" |
rounding | int | None | The number of decimals to round the results to. Defaults to None. | 2 |