Copula Simulation
Calibrate a bivariate copula (see get_copula_parameters) between ticker_a and ticker_b, and simulate joint scenarios from it.
When ticker_a/ticker_b are not given, every unique pair among the Toolkit’s tickers is calibrated and simulated instead, as columns grouped under a top-level (Ticker A, Ticker B) column per pair.
This is what a copula-based portfolio Monte Carlo simulation needs: draws that preserve the calibrated dependence structure – including tail dependence, for the “student-t”, “clayton” and “gumbel” families – rather than the (typically understated) joint crash risk a plain multivariate gaussian simulation would produce.
The formula is as follows (with the default copula=”gaussian” and empirical_margins=True):
\[(Z_{1},\; Z_{2}) \sim N(0,\; \left[\left[1,\; \text{Rho}\right],\; \left[\text{Rho},\; 1\right]\right])\] \[U = \Phi(Z_{1}),\;\; V = \Phi(Z_{2})\] \[\text{Simulated Return}\; A = \operatorname{Quantile}(A,\; U),\;\; \text{Simulated Return}\; B = \operatorname{Quantile}(B,\; V)\]Where Rho is fitted as in get_copula_parameters and Quantile is the empirical quantile (linear interpolation) of each asset’s own history. The Student-T copula scales (Z1, Z2) by √(v / W), with W ~ χ²(v), and maps them with the Student-T distribution function; the Clayton, Gumbel and Frank copulas draw U and T uniformly and solve C(V | U) = T for V.
Also known as: copula Monte Carlo, dependence simulation, scenario generation.
Copula Simulation in Python or via the MCP
Install the Finance Toolkit with:
pip install financetoolkit -U
Then call get_copula_simulation as shown below.
from financetoolkit import Toolkit
toolkit = Toolkit(
["HD", "LOW"],
api_key="FINANCIAL_MODELING_PREP_KEY",
start_date="2021-01-01",
end_date="2025-12-31",
)
toolkit.risk.get_copula_simulation("HD", "LOW", n_simulations=30).head(5)
Or, after setting up the Finance Toolkit MCP, ask:
Simulate 30 joint returns of Home Depot and Lowe's from a Gaussian copula fitted to their returns from 2021 to 2025 and show the first five.
Which returns:
| HD | LOW | |
|---|---|---|
| 0 | 0.0001 | -0.0073 |
| 1 | -0.012 | -0.0059 |
| 2 | 0.0332 | 0.0247 |
| 3 | 0.0001 | -0.0019 |
| 4 | 0.0038 | -0.0019 |
Parameters
get_copula_simulation accepts the following parameters.
| Parameter | Type | Description | Example |
|---|---|---|---|
ticker_a | str | The first asset. Defaults to None, meaning every unique pair of tickers in the Toolkit instance is used (requires ticker_b to also be None). | "AAPL" |
ticker_b | str | The second asset. Defaults to None, see ticker_a. | "MSFT" |
copula | str | The copula family to fit and simulate from, one of “gaussian”, “student-t”, “clayton”, “gumbel” or “frank”. Defaults to “gaussian”. | "clayton" |
period | str | The data frequency (daily, weekly, monthly, quarterly, or yearly). Defaults to “daily”, since a dependence estimate needs far more observations than a lower frequency provides – at “yearly” a decade of history is only ten observations. | "weekly" |
column | str | The historical data column to use. Defaults to “Return”. | "Return" |
n_simulations | int | The number of joint draws to simulate. Defaults to 10,000. | 5000 |
random_state | int | The seed for the random number generator. Defaults to 42. | 1 |
empirical_margins | bool | Whether to map the simulated pseudo-observations back to realistic returns via each asset’s own empirical (historical) quantile function. Defaults to True. When False, the raw pseudo-observations (each in (0, 1)) are returned instead. | False |
rounding | int | None | The number of decimals to round the results to. Defaults to None. | 2 |