{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#  Smith-Wilson Model Overview\n",
    "\n",
    "This Jupyter notebook shows you how to load the **smithwilson** model included in the **smithwilson** project. It also walks you through steps to create the same model from scratch.\n",
    "\n",
    "The Smith-Wilson model calculates extraporated interest rates using the Smith-Wilson method.\n",
    "\n",
    "The Smith-Wilson method is used for extraporating risk-free interest rates under the Solvency II framework. The method is described in details in *QIS 5 Risk-free interest rates – Extrapolation method*, [a technical paper](https://eiopa.europa.eu/Publications/QIS/ceiops-paper-extrapolation-risk-free-rates_en-20100802.pdf) issued by CEIOPS(the predecessor of EIOPA). The technical paper is available on [EIOPA's web site](https://eiopa.europa.eu/publications/qis/insurance/insurance-quantitative-impact-study-5/background-documents).\n",
    "Formulas and variables in this notebook are named consistently with the mathmatical symbols in the technical paper.\n",
    "\n",
    "This project is inspired by a pure Python implementation of Smith-Wilson\n",
    "yield curve fitting algorithm created by Dejan Simic.\n",
    "His original work can be found [on his github page](https://github.com/simicd/smith-wilson-py).\n",
    "\n",
    "[the technical paper]: https://eiopa.europa.eu/Publications/QIS/ceiops-paper-extrapolation-risk-free-rates_en-20100802.pdf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## About this notebook\n",
    "\n",
    "This notebook is included in **lifelib** package as part of the **smithwilson** project.\n",
    "\n",
    "If you're viewing this page as a static HTML page on https://lifelib.io, the same contents are also available [here on binder] as Jupyter notebook executable online (it may take a while to load). To run this notebook and get all the outputs below, Go to the **Cell** menu above, and then click **Run All**.\n",
    "\n",
    "[here on binder]: https://mybinder.org/v2/gh/fumitoh/lifelib/binder?filepath=lifelib%2Fprojects%2Fsmithwilson%2Fsmithwilson.ipynb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reading in the complete model\n",
    "\n",
    "The complete model is included under the **smithwilson** project in lifelib package. Load a model from `model` folder in your\n",
    "project folder by `modelx.read_model` function.\n",
    "The example blow shows how to do it.\n",
    "Note that you need two backslashes to separate folders:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import modelx as mx\n",
    "m = mx.read_model(\"model\")   #  Need 2 backslashes as a separator on Windows e.g. \"C:\\\\Users\\\\fumito\\\\model\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The model has only one space, named `SmithWilson`.\n",
    "The space contains a few cells:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s = m.SmithWilson\n",
    "s.cells"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It also contains references (refs),\n",
    "such as `spot_rates`, `N`, `UFR` and `alpha`.\n",
    "By default, these values are set equal to the values used in Dejan's\n",
    "reference model.\n",
    "The original source of the input data is Switzerland EIOPA spot rates with LLP 25 years available from the following URL.\n",
    "\n",
    "Source: https://eiopa.europa.eu/Publications/Standards/EIOPA_RFR_20190531.zip; EIOPA_RFR_20190531_Term_Structures.xlsx; Tab: RFR_spot_no_VA\n",
    "         \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.N"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.UFR"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.alpha"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.spot_rates"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`R` calculates the extrapoted spot rate for a give time index $i$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "[s.R[i] for i in range(10, 151, 10)]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For $i = 1,\\dots,N$, `R[i]` is the same as `spot_rates[i-1]`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "[s.spot_rates[i-1] for i in range(10, 26, 5)]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Building the Smith-Wilson model from scratch\n",
    "\n",
    "We now try to create the **smithwilson** model from scratch. \n",
    "The model we create is essentially the same as the model included in the **smithwilson** project, excpt for docstrings.\n",
    "\n",
    "Below are the steps to create the model.\n",
    "1. Create a model and space.\n",
    "2. Input values to as *references*.\n",
    "3. Define cells.\n",
    "4. Get the results.\n",
    "5. Save the model."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. Create a model and space\n",
    "\n",
    "First, we create an empty model named `smithwilson2`, and also an empty space named `SmithWilson` in the model. \n",
    "The following statement creates the model and space, and assign the space to a name `s2`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s2 = mx.new_model(name=\"smithwilson2\").new_space(name=\"SmithWilson\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Input values to as *references*\n",
    "\n",
    "In this step, we create *references* in the *SmithWilson* space, and assign input values to the *references*.\n",
    "We will create cells and define their formulas in the sapce in the next step, and those *references* are referred by the formulas of the cells. \n",
    "\n",
    "The values are taken from https://github.com/simicd/smith-wilson-py/blob/master/main.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Annual compound spot rates for time to maturities from 1 to 25 years\n",
    "s2.spot_rates = [\n",
    "    -0.00803, -0.00814, -0.00778, -0.00725, -0.00652,\n",
    "    -0.00565, -0.0048, -0.00391, -0.00313, -0.00214,\n",
    "    -0.0014, -0.00067, -0.00008, 0.00051, 0.00108,\n",
    "    0.00157, 0.00197, 0.00228, 0.0025, 0.00264,\n",
    "    0.00271, 0.00274, 0.0028, 0.00291, 0.00309]\n",
    "\n",
    "s2.N = 25   # Number of time to maturities.\n",
    "\n",
    "s2.alpha = 0.128562  # Alpha parameter in the Smith-Wilson functions\n",
    "\n",
    "ufr = 0.029    # Annual compound\n",
    "\n",
    "from math import log\n",
    "s2.UFR = log(1 + ufr) # Continuous compound UFR, 0.028587456851912472"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You also nee to import `log` and `exp` from `math` module for later use. \n",
    "We also use numpy later, so import `numpy` as `np`. \n",
    "These functions and module need to be accessible from cells in `SmithWilson` space,\n",
    "so assign them to refs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from math import log, exp\n",
    "import numpy as np\n",
    "\n",
    "s2.log = log\n",
    "s2.exp = exp\n",
    "s2.np = np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3. Define cells\n",
    "\n",
    "In the previous step, we have assigned all the necessary inputs in the *SmithWilson* space. In this step we move on to defining cells.\n",
    "\n",
    "We use `defcells` decorator to define cells from Python functions. `defcells` decorator creates cells in the *current* space, so confirm the *SmithWilson* space we just created is set to the *current* space by the following code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mx.cur_space()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The names of the cells below are set consistent with the mathmatical symbols in the technical paper.\n",
    "\n",
    "* `u(i)`: Time at each `i` in years. Time steps can be uneven. For the maturities of the zero coupon bonds with known prices $u_i$\n",
    "* `m(i)`: The market prices of the zero coupon bonds, $m_i$\n",
    "* `mu(i)`: Ultimate Forward Rate (UFR) discount factors, $\\mu_i$\n",
    "* `W(i, j)`: The Wilson functions, $W(t_i, u_j)$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@mx.defcells\n",
    "def u(i):\n",
    "    \"\"\"Time to maturities\"\"\"\n",
    "    return i"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@mx.defcells\n",
    "def m(i):\n",
    "    \"\"\"Observed zero-coupon bond prices\"\"\"\n",
    "    return (1 + spot_rates[i-1]) ** (-u[i])\n",
    "\n",
    "\n",
    "@mx.defcells\n",
    "def mu(i):\n",
    "    \"\"\"Ultimate Forward Rate (UFR) discount factors\"\"\"\n",
    "    return exp(-UFR * u[i])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@mx.defcells\n",
    "def W(i, j):\n",
    "    \"\"\"The Wilson functions\"\"\"\n",
    "\n",
    "    t = u[i]\n",
    "    uj = u[j]\n",
    "\n",
    "    return exp(-UFR * (t+uj)) * (\n",
    "            alpha * min(t, uj) - 0.5 * exp(-alpha * max(t, uj)) * (\n",
    "                    exp(alpha*min(t, uj)) - exp(-alpha*min(t, uj))))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We want to use Numpy's vector and matrix operations to solve for $\\zeta$,\n",
    "so we create a vector or matrix version of cells for each of `m`, `mu`, `W`.\n",
    "These cells have no parameter and return numpy arrays."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@mx.defcells\n",
    "def m_vector():\n",
    "    return np.array([m(i) for i in range(1, N+1)])\n",
    "\n",
    "@mx.defcells\n",
    "def mu_vector():\n",
    "    return np.array([mu(i) for i in range(1, N+1)])\n",
    "\n",
    "@mx.defcells\n",
    "def W_matrix():\n",
    "    return np.array(\n",
    "        [[W(i, j) for j in range(1, N+1)] for i in range(1, N+1)]\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`zeta_vector` cells carries out the matrix-vector calcuculation: $\\zeta = \\bf W^{-1}(\\bf m - {\\mu})$.\n",
    "\n",
    "`zeta` extracts from an element from `zeta_vector` for each `i` "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@mx.defcells\n",
    "def zeta_vector():\n",
    "    return np.linalg.inv(W_matrix()) @ (m_vector() - mu_vector())\n",
    "\n",
    "@mx.defcells\n",
    "def zeta(i):\n",
    "    return zeta_vector()[i-1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`P(i)` cells calculates bond prices from `mu`, `zeta` and `W`. The values of `P(i)` should be the same as those of `m(i)` for `i=1,...,N` .\n",
    "\n",
    "`R(i)` are the extaporated annual compound rates. The values of `R(i)` should be the same as those of `spot_rates[i-1]` for `i=1,...,N`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@mx.defcells\n",
    "def P(i):\n",
    "    \"\"\"Zero-coupon bond prices calculated by Smith-Wilson method.\"\"\"\n",
    "    return mu(i) + sum(zeta(j) * W(i, j) for j in range(1, N+1))\n",
    "\n",
    "\n",
    "@mx.defcells\n",
    "def R(i):\n",
    "    \"\"\"Extrapolated rates\"\"\"\n",
    "    return (1 / P(i)) ** (1 / u(i)) - 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4. Get the results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can check that the cells you define above exists in the `SmithWilson` space by getting the space's `cells` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s2.cells"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`R` cells calculates or holds the extraporated spot rates. You can see that for `i=1,...,25`, the values are the same ase the `sport_rates`.\n",
    "\n",
    "The code below outputs `R(i)` for `i=10, 15, 20, ..., 100`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "[s2.R[i] for i in range(10, 101, 5)]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5. Save the model"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can write the model by `write_model`. The model is written to files under the folder you specify as the second paramter. Later you can read the model by `read_model`.\n",
    "\n",
    "```python\n",
    "mx.write_model(mx.cur_model(), \"your_folder\")\n",
    "\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}