\n\n---\n\n### What is an economic scenario generator?\n\nAn economic scenario generator simulates the behavior of unpredictable financial markets like stocks, interest rates, or energy prices. It uses mathematical models called _stochastic processes_ to generate thousands of unique scenarios.\n\nWhat can you do with an economic scenario generator? Here are a few examples:\n\n\n Simulate an investment portfolio\n\n * Generate 1,000 correlated, daily stock prices\n * Construct a portfolio from the stocks\n * Plot the value of the portfolio over time, and calculate metrics like high, low, max drawdown, etc.\n\n\n\n Choose a mortgage\n\n * Generate 1,000 30-year, monthly scenarios of mortgage rates\n * Calculate the monthly payment for different loans under each scenario:\n - 30-year fixed (lock in the rate today for all 30 years)\n - 15-year fixed (lock in the rate today and pay over 15 years)\n - 10-year adjustable-rate (fixed rate for 10 years, then variable rate for 20 years\n - etc.\n * Determine which loan fits the best with your budget\n\n\n\n Plan for retirement\n\n * Generate 1,000 30-year, monthly scenarios of stock market data\n * Generate 1,000 30-year, monthly scenarios of bond fund data\n * Track your portfolio balance as a mix of investments in stocks and bonds\n * Each month, simulate a withdrawal from your portfolio and the growth from your investments\n * Adjust the withdrawal up or down and identify the types of markets that lead to the best and worst outcomes\n\n\n\n Protect your business\n\n * **Banks**: test whether loan portfolios are resilient to drops in interest rates and higher-than-expected customer refinancing\n * **Insurers**: test whether assets are sufficient to cover liabilities under a wide range of bond market scenarios\n * **Investment managers**: test the impact of market declines on revenue from account-based fees\n * **Small Businesses**: model customer demand correlated with the stock market to plan for potential downturns\n\n\n\n## Key Features of **_pyesg_**\n\n- Built on **numpy** for lightning fast scenario generation: 10,000+ scenarios in milliseconds\n- Dozens of stochastic processes available out of the box\n - Equity: Geometric Brownian Motion / Black Scholes, Heston\n - Interest rate: Vasicek, Cox-Ingersoll-Ross, Hull-White\n- Complete implementation of the American Academy of Actuaries stochastic interest rate generator that is **200 times faster** than the Excel version\n- Curve interpolation functions like Nelson-Siegel and Svensson models\n- Hundreds of unit tests and excellent code coverage\n- Open source software, free to use, copy, or modify under MIT license\n\n## Coming soon\n\n- More models!\n- Fit stochastic models using historical data\n- Built-in plotting methods\n- Scenario summary reports\n\n## Installing **_pyesg_**\n**_pyesg_** is available on PyPI, and can be installed with pip.\n\n```\npip install pyesg\n```\n\n## Usage\n\nAll models in **_pyesg_** are created and used nearly identically.\n\nFirst, create a model with its required parameters.\n\n```python\nimport pyesg\n\n# create a new model with the required parameters\nmodel = pyesg.GeometricBrownianMotion(mu=0.05, sigma=0.2)\n```\n\nGenerate scenarios by calling the `.scenarios` method. The example below, with 10,000 daily scenarios (2,520,000 values) took just **160 milliseconds** to run!\n\n\n Under the hood: model.scenarios()\n\nThis method generates scenarios, given the following arguments:\n\n- `x0` : the value or array of values each scenario starts with. For example, you might pass `100.0` to model a security with a current value of 100, or `[100.0, 90.0]` to model two scenarios with start values of 100 and 90.\n- `dt` : the length of each time step in the projection, in years. For example, you might pass `1/12` to model mothly timesteps, `1/52` to model weekly timesteps, `1/252` to model daily (trading day) timesteps, or `1` to model annual timesteps.\n- `n_scenarios` : the number of scenarios you want to generate. Often you can generate 10,000 scenarios in fractions of a second.\n- `n_steps` : the number of timesteps for each scenario. In combination with `dt`, this argument determines the total length of time a projection covers. For example, with `dt=1/52` and `n_steps=104`, the projection will cover two years with weekly timesteps. With `dt=1/12` and `n_steps=360`, the projection will cover 30 years with monthly timesteps.\n- `random_state` : an optional field that may be provided if you want to be able to reproduce pseudo-random numbers for each batch of scenarios. For example, `.scenarios(..., random_state=123)` will generate the exact same batch of scenarios every time.\n\n\n\n```python\nimport pyesg\n\n# instantiate a new model with the required parameters\nmodel = pyesg.GeometricBrownianMotion(mu=0.05, sigma=0.2)\n\n# prepare the arguments to generate scenarios. Here we'll\n# generate 10,000 scenarios with 252 daily (trading day)\n# time steps, for a one-year projection in total.\nx0 = 100.0 # the start value of our process\ndt = 1/252 # the length of each timestep in years\nn_scenarios = 10000 # the number of scenarios to generate\nn_steps = 252 # the number of time steps per scenario\nrandom_state = 123 # optional random_state for reproducibility\n\n# now we generate the scenarios; this outputs a numpy array. It will\n# have shape (10000, 253), which represents (scenarios, timesteps).\n# There are 253 timesteps because the initial value is included to start\nresults = model.scenarios(x0, dt, n_scenarios, n_steps, random_state)\n\n# array([[100. , 98.65207527, 97.12924873, ..., 111.3500094 ,\n# 112.00479028, 113.12444153],\n# [100. , 101.27637842, 100.8971646 , ..., 61.8709475 ,\n# 63.00222064, 62.22126261],\n# [100. , 100.37636067, 99.32267874, ..., 141.66969149,\n# 140.38291993, 138.91659076],\n# ...,\n# [100. , 99.42484152, 97.68732205, ..., 139.9306172 ,\n# 139.52301459, 139.05345463],\n# [100. , 100.75304745, 102.09894601, ..., 115.66615197,\n# 116.16385992, 118.06267759],\n# [100. , 101.24269853, 101.73381851, ..., 84.65843473,\n# 84.73018762, 85.09768131]])\n```\n\nAll models provide methods to evaluate their drift, diffusion, expectation, standard deviation, and more.\n\n```python\nimport pyesg\n\n# instantiate a new model with the required parameters\nmodel = pyesg.GeometricBrownianMotion(mu=0.05, sigma=0.2)\n\n# drift is the instantaneous drift of the process. For example,\n# if we start with x0=100, what is the instantaneous drift?\nmodel.drift(x0=100)\n# array([5.])\n\n# similarly we can measure the instantaneous diffusion\nmodel.diffusion(x0=100)\n# array([20.])\n\n# the expectation is the expected value of the process after\n# a given amount of time, dt. Here we calculate the expected\n# value of the process after one year.\nmodel.expectation(x0=100, dt=1.0)\n# array([105.])\n\n# the standard deviation is measured at a period of time too\nmodel.standard_deviation(x0=100, dt=1.0)\n# array([20.])\n```\n\n## Available Models\n\n### Equity\n\n\n Geometric Brownian Motion\n\n\n\n Heston Model\n\n\n### Interest Rate\n\n\n American Academy of Actuaries Interest Rate Generator\n\n\n\n Black-Derman-Toy\n\n\n\n Black-Karasinski\n\n\n\n Cox-Ingersoll-Ross\n\n\n\n Ho-Lee\n\n\n\n Ornstein-Uhlenbeck Process (Vasicek Model)\n\n\n### General\n\n\n Wiener Process\n\n\n## Curve Interpolators\n\nWe can almost always observe interest rates at key maturities, for example, bonds trading with maturies of 1, 2, 3, 5, 7, or 10 years. If we want to estimate the interest rate for an 8-year bond, we need to interpolate between the observed values. Simple techniques like linear interpolation are possible, but have certain obvious disadvantages - namely that the interest rate curve is non-linear. Instead, better techniques like the Nelson-Siegel and Nelson-Siegel-Svensson interpolators might give better results. Both interpolators are availabe in **_pyesg_**.\n\n```python\nimport numpy as np\nfrom pyesg import NelsonSiegelInterpolator, SvenssonInterpolator\nfrom pyesg.datasets import load_ust_historical\n\n# load a dataset of historical US Treasury rates, contained in pyesg.datasets\n# ust is a pandas dataframe of rates for various maturities, indexed by year and month\nust = load_ust_historical()\n\n# we will be interpolating rates from the file:\n# y - the observed US Treasury rate for the given maturity for a select observation date\n# X - the maturity of the bond measured in years\ny = ust.iloc[-10].values\nX = np.array([0.25, 0.5, 1, 2, 3, 5, 7, 10, 20, 30])\n\n# create Nelson-Siegel and Nelson-Siegel-Svensson interpolator objects\n# then fit both models using the historical data\nnelson_siegel = pyesg.NelsonSiegelInterpolator()\nsvensson = pyesg.SvenssonInterpolator()\nnelson_siegel.fit(X, y)\nsvensson.fit(X, y)\n\n# predict values for each maturity from 1 to 30 years\nnelson_siegel.predict(np.arange(1, 31, 1))\n# array([0.02033871, 0.02252733, 0.02403659, 0.02510373, 0.02587762,\n# 0.02645304, 0.02689131, 0.02723275, 0.02750438, 0.02772458,\n# 0.02790617, 0.02805818, 0.02818715, 0.02829786, 0.0283939 ,\n# 0.02847798, 0.02855218, 0.02861815, 0.02867718, 0.02873031,\n# 0.02877839, 0.02882209, 0.02886199, 0.02889857, 0.02893222,\n# 0.02896329, 0.02899205, 0.02901876, 0.02904362, 0.02906683])\n```\n\n
![](\"https://github.com/jason-ash/pyesg/blob/master/docs/images/pyesg.png\")
\n![\"License\"/](\"https://img.shields.io/apm/l/atomic-design-ui.svg?style=flat-square\")
\n \n \n ![\"Supported](\"https://img.shields.io/pypi/pyversions/pyesg.svg?style=flat-square\")
\n \n \n ![\"Pypi](\"https://img.shields.io/pypi/v/pyesg?color=light%20green&label=pypi%20package&style=flat-square\")
![\"Build](\"https://img.shields.io/github/workflow/status/jason-ash/pyesg/pyesg%20CI/master?style=flat-square\")
![\"Coverage\"/](\"https://img.shields.io/coveralls/github/jason-ash/pyesg?style=flat-square\")
![](\"https://github.com/jason-ash/pyesg/blob/master/docs/images/NelsonSiegel.png\")
\n