docs: Write how-to-use section

Add how to use section with step-by-step descriptions.

Closes PR #2

Author: simicd

README.md

@@ -1,24 +1,87 @@
 # README
 ## Overview
-This Python package provides an implementation of the Smith-Wilson yield curve fitting algorithm for interpolations and extrapolations of zero-coupon bond rates. This algorithm is used for the extrapolation of [EIOPA risk-free term structures](https://eiopa.europa.eu/Publications/Standards/Technical%20Documentation%20(31%20Jan%202018).pdf) in the Solvency II framework. Details are available in the Technical Paper [QIS 5  Risk-free interest rates](https://eiopa.europa.eu/Publications/QIS/ceiops-paper-extrapolation-risk-free-rates_en-20100802.pdf). Examples of extrapolated yield curves including the parameters applied can be found [here](https://eiopa.europa.eu/Publications/Standards/EIOPA_RFR_20190531.zip).
+This Python package implements the Smith-Wilson yield curve fitting algorithm. It allows for interpolations and extrapolations of zero-coupon bond rates. This algorithm is used for the extrapolation of [EIOPA risk-free term structures](https://eiopa.europa.eu/Publications/Standards/Technical%20Documentation%20(31%20Jan%202018).pdf) in the Solvency II framework. Details are available in the Technical Paper [QIS 5  Risk-free interest rates](https://eiopa.europa.eu/Publications/QIS/ceiops-paper-extrapolation-risk-free-rates_en-20100802.pdf). Examples of extrapolated yield curves including the parameters applied can be found [here](https://eiopa.europa.eu/Publications/Standards/EIOPA_RFR_20190531.zip).
 <br /><br />
 
-## Implementation
-The algorithm has been implemented in vectorized form with numpy. This should guarantee good performance. All functions are in [core.py](https://github.com/simicd/smith-wilson-py/blob/master/smithwilson/core.py).
+## How to use the package
+1. To use the Smith-Wilson fitting algorithm, first import the Python package and specify the inputs. In the example below the inputs are zero-coupon rates with annual frequency up until year 25. The UFR is 2.9% and the convergence parameter alpha is 0.128562. The `terms` list defines the list of maturities, in this case `[1.0, 2.0, 3.0, ..., 25.0]`
+    ```py
+    import smithwilson as sw
+
+    # Input - Switzerland EIOPA spot rates with LLP of 25 years
+    # Source: https://eiopa.europa.eu/Publications/Standards/EIOPA_RFR_20190531.zip
+    #         EIOPA_RFR_20190531_Term_Structures.xlsx; Tab: RFR_spot_no_VA
+    rates = [-0.00803, -0.00814, -0.00778, -0.00725, -0.00652,
+             -0.00565, -0.0048, -0.00391, -0.00313, -0.00214,
+             -0.0014, -0.00067, -0.00008, 0.00051, 0.00108,
+             0.00157, 0.00197, 0.00228, 0.0025, 0.00264,
+             0.00271, 0.00274, 0.0028, 0.00291, 0.00309]
+    terms = [float(y + 1) for y in range(len(rates))] # [1.0, 2.0, ..., 25.0]
+    ufr = 0.029
+    alpha = 0.128562
+
+    ```
+
+1. Specify the targeted output maturities. This is the set of terms you want to get rates fitted by Smith-Wilson.
+   Expand the set of rates beyond the Last Liquid Point (e.g. extrapolate to 150 years with annual frequency):
+   ```py
+   # Extrapolate to 150 years
+   terms_target = [float(y + 1) for y in range(150)] # [1.0, 2.0, ..., 150.0]
+   ```
+
+   Alternatively, you can retrieve a different frequency (e.g. interpolate quarterly instead of annual):
+   ```py
+   # Interpolate to quarterly granularity
+   terms_target = [float(y + 1) / 4 for y in range(25*4)] # [0.25, 0.5, ..., 25.0]
+   ```
+
+   A combination of interpolation & extrapolation is possible, too. Same for sets of arbitrary maturities:
+   ```py
+   # Get rates for a well-specified set of maturities only
+   terms_target = [0.25, 0.5, 1.0, 2.0, 5.0, 10.0, 20.0, 50.0, 100.0]
+   ```
+
+1. Call the Smiwth-Wilson fitting algorithm. This returns the rates as numpy vector with each element corresponding to the maturity in `terms_target`
+   ```py
+   # Calculate fitted rates based on actual observations and two parametes alpha & UFR
+   fitted_rates = sw.fit_smithwilson_rates(rates_obs=rates, t_obs=terms,
+                                           t_target=terms_target, alpha=alpha, ufr=ufr)
+   ```
+
+1. To display the results and/or processing them it can be useful to turn them into a table, here using the pandas library:
+   ```py
+   # Ensure pandas package is imported
+   import pandas as pd
+
+   # ...
+
+   # Turn inputs & outputs into dataframe
+   observed_df = pd.DataFrame(data=rates, index=terms, columns=["observed"])
+   extrapolated_df = pd.DataFrame(data=fitted_rates, index=terms_target, columns=["extrapolated"])
+
+   # Combine and print dataframe
+   print(observed_df.join(extrapolated_df, how="outer"))
+   ```
+
+A complete example can be found in [main.py](https://github.com/simicd/smith-wilson-py/blob/master/main.py)
+<br /><br />
+
+## Algorithm
+The algorithm is fully vectorized and uses numpy, making it very performant. The code is in [core.py](https://github.com/simicd/smith-wilson-py/blob/master/smithwilson/core.py).
 
 The function `fit_smithwilson_rates()` expects following parameters:
-- Observed rates 
+- Observed rates
 - Observed maturities
 - Target maturities
-- Convergence parameter alpha 
+- Convergence parameter alpha
 - Ultimate forward rate (UFR)
 
-The observed rates and maturities are assumed to be before the Last LiquidPoint (LLP). The targeted maturity vector can
-contain both, more granular maturity structure (interpolation) or terms after the LLP (extrapolation).
+The observed rates and maturities are assumed to be before the Last Liquid Point (LLP). The targeted maturity vector can
+contain any set of maturities (e.g. more granular maturity structure (interpolation) or terms after the LLP (extrapolation)).
 <br /><br />
 
 
-The fitting algorithm of the Smith-Wilson method calculates first the Wilson-matrix (EIOPA, 2010, p. 16):
+The Smith-Wilson fitting algorithm calculates first the Wilson-matrix (EIOPA, 2010, p. 16):
 
     `W = e^(-UFR * (t1 + t2)) * (α * min(t1, t2) - 0.5 * e^(-α * max(t1, t2))
         * (e^(α * min(t1, t2)) - e^(-α * min(t1, t2))))`
@@ -34,10 +97,6 @@ With the Smith-Wilson parameter `ζ` and Wilson-matrix `W`, the zero-coupon bond
 In the last case, `t` can be any maturity vector, i.e. with additional maturities to extrapolate rates.
 <br /><br />
 
-## Usage
-To use the Smith-Wilson fitting algorithm import the Python package and call `fit_smithwilson_rates()` with the required parameters. An example can be found in [main.py](https://github.com/simicd/smith-wilson-py/blob/master/main.py)
-<br /><br />
-
 ## Sources
 [EIOPA (2010). QIS 5 Technical Paper; Risk-free interest rates – Extrapolation method](https://eiopa.europa.eu/Publications/QIS/ceiops-paper-extrapolation-risk-free-rates_en-20100802.pdf); p.11ff
 

main.py

@@ -4,26 +4,28 @@
 # Input - Switzerland EIOPA spot rates with LLP 25 years and extrapolation period of 150 years
 # Source: https://eiopa.europa.eu/Publications/Standards/EIOPA_RFR_20190531.zip
 #         EIOPA_RFR_20190531_Term_Structures.xlsx; Tab: RFR_spot_no_VA
-rates = [-0.00803, -0.00814, -0.00778, -0.00725, -0.00652,
-         -0.00565, -0.0048, -0.00391, -0.00313, -0.00214,
-         -0.0014, -0.00067, -0.00008, 0.00051, 0.00108,
-         0.00157, 0.00197, 0.00228, 0.0025, 0.00264,
-         0.00271, 0.00274, 0.0028, 0.00291, 0.00309]
-terms = [float(y + 1) for y in range(len(rates))] # 1.0, 2.0, ..., 25.0
+rates = [
+    -0.00803, -0.00814, -0.00778, -0.00725, -0.00652, -0.00565, -0.0048, -0.00391, -0.00313, -0.00214, -0.0014, -0.00067,
+    -0.00008, 0.00051, 0.00108, 0.00157, 0.00197, 0.00228, 0.0025, 0.00264, 0.00271, 0.00274, 0.0028, 0.00291, 0.00309
+]
+terms = [float(y + 1) for y in range(len(rates))]     # 1.0, 2.0, ..., 25.0
 ufr = 0.029
 alpha = 0.128562
 
 # Target - Extrapolate to 150 years
-terms_ext = [float(y + 1) for y in range(150)] # 1.0, 2.0, ..., 150.0
+terms_target = [float(y + 1) for y in range(150)]     # 1.0, 2.0, ..., 150.0
 
 # Calculate fitted rates based on actual observations and two parametes alpha & UFR
-rates_ext = sw.fit_smithwilson_rates(rates_obs=rates, t_obs=terms,
-                                     t_target=terms_ext, alpha=alpha, ufr=ufr)
+fitted_rates = sw.fit_smithwilson_rates(rates_obs=rates, t_obs=terms, t_target=terms_target, alpha=alpha, ufr=ufr)
 
 # Display Outputs
 # Create dictionary with maturity as key and rate as value
-observed = dict(zip(terms, rates))
-extrapolated = dict(zip(terms_ext, rates_ext.flatten()))
+extrapolated = dict(zip(terms_target, fitted_rates.flatten()))
+print(extrapolated)
 
-# Create and print dataframe
-print(pd.DataFrame({"Observed": observed, "Extrapolated": extrapolated}))
+# Create dataframe
+observed_df = pd.DataFrame(data=rates, index=terms, columns=["observed"])
+extrapolated_df = pd.DataFrame(data=fitted_rates, index=terms_target, columns=["extrapolated"])
+
+# Combie and print dataframe
+print(observed_df.join(extrapolated_df, how="outer"))

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name="smithwilson",
-    version="0.1.0",
+    version="0.2.0",
     author="Dejan Simic",
     author_email="dejan.simic",
     description="Implementation of the Smith-Wilson yield curve fitting algorithm in Python for interpolations and extrapolations of zero-coupon bond rates",

smithwilson/core.py

@@ -1,8 +1,9 @@
-
-from math import exp, log
+from math import log
 import numpy as np
+from typing import Union, List
+
 
-def calculate_prices(rates: np.ndarray, t: np.ndarray) -> np.ndarray:
+def calculate_prices(rates: Union[np.ndarray, List[float]], t: Union[np.ndarray, List[float]]) -> np.ndarray:
     """Calculate prices from zero-coupon rates
 
     Args:
@@ -13,10 +14,14 @@ def calculate_prices(rates: np.ndarray, t: np.ndarray) -> np.ndarray:
         Prices as vector of length n
     """
 
+    # Convert list into numpy array
+    rates = np.array(rates)
+    t = np.array(t)
+
     return np.power(1 + rates, -t)
 
 
-def ufr_discount_factor(ufr: float, t: np.ndarray) -> np.ndarray:
+def ufr_discount_factor(ufr: float, t: Union[np.ndarray, List[float]]) -> np.ndarray:
     """Calculate Ultimate Forward Rate (UFR) discount factors.
 
     Takes the UFR with a vector of maturities and returns for each of the
@@ -37,10 +42,14 @@ def ufr_discount_factor(ufr: float, t: np.ndarray) -> np.ndarray:
 
     # Convert annualized ultimate forward rate to log-return
     ufr = log(1 + ufr)
+
+    # Convert list into numpy array
+    t = np.array(t)
+
     return np.exp(-ufr * t)
 
 
-def wilson_function(t1: np.ndarray, t2: np.ndarray, alpha: float, ufr: float) -> np.ndarray:
+def wilson_function(t1: Union[np.ndarray, List[float]], t2: Union[np.ndarray, List[float]], alpha: float, ufr: float) -> np.ndarray:
     """Calculate matrix of Wilson functions
 
     The Smith-Wilson method requires the calculation of a series of Wilson
@@ -85,7 +94,7 @@ def wilson_function(t1: np.ndarray, t2: np.ndarray, alpha: float, ufr: float) ->
     return W
 
 
-def fit_parameters(rates: np.ndarray, t: np.ndarray, alpha: float, ufr: float) -> np.ndarray:
+def fit_parameters(rates: Union[np.ndarray, List[float]], t: Union[np.ndarray, List[float]], alpha: float, ufr: float) -> np.ndarray:
     """Calculate Smith-Wilson parameter vector ζ
 
     Given the Wilson-matrix, vector of discount factors and prices,
@@ -115,13 +124,13 @@ def fit_parameters(rates: np.ndarray, t: np.ndarray, alpha: float, ufr: float) -
     # Calculate vector of parameters (p. 17)
     # To invert the Wilson-matrix, conversion to type matrix is required
     zeta = np.matrix(W).I * (mu - P)
-    zeta = np.array(zeta) # Convert back to more general array type
+    zeta = np.array(zeta)     # Convert back to more general array type
 
     return zeta
 
 
-def fit_smithwilson_rates(rates_obs: np.ndarray, t_obs: np.ndarray, t_target: np.ndarray,
-                                alpha: float, ufr: float) -> np.ndarray:
+def fit_smithwilson_rates(rates_obs: Union[np.ndarray, List[float]], t_obs: Union[np.ndarray, List[float]],
+                          t_target: Union[np.ndarray, List[float]], alpha: float, ufr: float) -> np.ndarray:
     """Calculate zero-coupon yields with Smith-Wilson method based on observed rates.
 
     This function expects the rates and initial maturity vector to be
@@ -170,7 +179,7 @@ def fit_smithwilson_rates(rates_obs: np.ndarray, t_obs: np.ndarray, t_target: np
 
     # Price vector - equivalent to discounting with zero-coupon yields 1/(1 + r)^t
     # for prices where t_obs = t_target. All other matuirites are interpolated or extrapolated
-    P = ufr_disc - W @ zeta  # '@' in numpy is the dot product of two matrices
+    P = ufr_disc - W @ zeta     # '@' in numpy is the dot product of two matrices
 
     # Transform price vector to zero-coupon rate vector (1/P)^(1/t) - 1
-    return np.power(1/P, 1/t_target) - 1
+    return np.power(1 / P, 1 / t_target) - 1