2. Framework Classes and Functions

This section explains the usage of some basic framework classes and functions of DX Analytics. Mainly some helper functions, the discounting classes and the market environment class used to store market data and other parameters/data needed to model, value and risk manage derivative instruments.

from dx import *

np.set_printoptions(precision=3)

2.1. Helper Functions

There are two helper functions used regulary:

• get_year_deltas: get a list of year deltas (decimal fractions) relative to first value in time_list
• sn_random_numbers: get an array of standard normally distributed pseudo-random numbers

2.1.1. get_year_deltas

Suppose we have a list object containing a number of datetime objects.

time_list = [dt.datetime(2015, 1, 1),
             dt.datetime(2015, 4, 1),
             dt.datetime(2015, 6, 15),
             dt.datetime(2015, 10, 21)]

Passing this object to the get_year_deltas functions yields a list of year fractions representing the time intervals between the dates given. This is sometimes used e.g. for discounting purposes.

get_year_deltas(time_list)

array([0.   , 0.247, 0.452, 0.803])

2.1.2. sn_random_numbers

Monte Carlo simulation of course relies heavily an the use of random numbers. The function sn_random_numbers is a wrapper function around the pseudo-random number generator of the NumPy library. It implements antithetic variates and moment matching as generic variance reduction techniques. It also allows to fix the seed value for the random number generator. The shape parameter is a tuple object of three integers.

ran = sn_random_numbers((2, 3, 4), antithetic=True,
                        moment_matching=True, fixed_seed=False)

ran

array([[[ 0.067, -1.202, -0.067,  1.202],
        [-0.245,  0.569,  0.245, -0.569],
        [-1.659,  0.647,  1.659, -0.647]],

       [[ 0.389, -1.974, -0.389,  1.974],
        [ 0.424, -1.451, -0.424,  1.451],
        [-0.79 ,  0.193,  0.79 , -0.193]]])

Using moment matching makes sure that the first and second moments match exactly 0 and 1, respectively.

ran.mean()

0.0

ran.std()

1.0

Setting the first value of the shape parameter to 1 yields a two-dimensional ndarray object.

ran = sn_random_numbers((1, 3, 4), antithetic=True,
                        moment_matching=True, fixed_seed=False)

ran

array([[-0.963,  0.494,  0.963, -0.494],
       [ 0.033,  1.412, -0.033, -1.412],
       [ 1.542, -0.676, -1.542,  0.676]])

2.2. Discounting Classes

In the risk-neutral valuation of derivative instrumente, discounting payoffs is a major task. The following discounting classes are implemented:

• constant_short_rate: fixed short rate
• deterministic_yield: deterministic yiels/term structure

2.2.1. constant_short_rate

The constant_short_rate class represents the most simple case for risk-neutral discounting. A discounting object is defined by instatiating the class and providing a name and a decimal short rate value only.

r = constant_short_rate('r', 0.05)

r.name

'r'

r.short_rate

0.05

The object has a method get_forward_rates to generate forward rates given, for instance, a list object of datetime objects.

r.get_forward_rates(time_list)

([datetime.datetime(2015, 1, 1, 0, 0),
  datetime.datetime(2015, 4, 1, 0, 0),
  datetime.datetime(2015, 6, 15, 0, 0),
  datetime.datetime(2015, 10, 21, 0, 0)],
 array([0.05, 0.05, 0.05, 0.05]))

Similarly, the method get_discount_factors returns discount factors for such a list object.

r.get_discount_factors(time_list)

([datetime.datetime(2015, 1, 1, 0, 0),
  datetime.datetime(2015, 4, 1, 0, 0),
  datetime.datetime(2015, 6, 15, 0, 0),
  datetime.datetime(2015, 10, 21, 0, 0)],
 array([0.961, 0.978, 0.988, 1.   ]))

You can also pass, for instance, an ndarry object containing year fractions.

r.get_discount_factors(np.array([0., 1., 1.5, 2.]),
                       dtobjects=False)

(array([0. , 1. , 1.5, 2. ]), array([0.905, 0.928, 0.951, 1.   ]))

2.2.2. deterministic_short_rate

The deterministic_short_rate class allows to model an interest rate term structure. To this end, you need to pass a list object of datetime and yield pairs to the class.

yields = [(dt.datetime(2015, 1, 1), 0.02),
          (dt.datetime(2015, 3, 1), 0.03),
          (dt.datetime(2015, 10, 15), 0.035),
          (dt.datetime(2015, 12, 31), 0.04)]

y = deterministic_short_rate('y', yields)

y.name

'y'

y.yield_list

array([[datetime.datetime(2015, 1, 1, 0, 0), 0.02],
       [datetime.datetime(2015, 3, 1, 0, 0), 0.03],
       [datetime.datetime(2015, 10, 15, 0, 0), 0.035],
       [datetime.datetime(2015, 12, 31, 0, 0), 0.04]], dtype=object)

The method get_interpolated_yields implements an interpolation of the yield data and returns the interpolated yields given a list object of datetime objects.

y.get_interpolated_yields(time_list)

array([[datetime.datetime(2015, 1, 1, 0, 0), 0.019999999999999993,
        0.0840608597791612],
       [datetime.datetime(2015, 4, 1, 0, 0), 0.03283048934520345,
        0.02532998361805569],
       [datetime.datetime(2015, 6, 15, 0, 0), 0.035133049718591186,
        0.0007769642303797064],
       [datetime.datetime(2015, 10, 21, 0, 0), 0.03515012570984609,
        0.010083939037494674]], dtype=object)

In similar fashion, the methods get_forward_rates and get_discount_factors return forward rates and discount factors, respcectively.

y.get_forward_rates(time_list)

([datetime.datetime(2015, 1, 1, 0, 0),
  datetime.datetime(2015, 4, 1, 0, 0),
  datetime.datetime(2015, 6, 15, 0, 0),
  datetime.datetime(2015, 10, 21, 0, 0)],
 array([0.019999999999999993, 0.039076238730477456, 0.0354842801241053,
        0.04324490417008154], dtype=object))

y.get_discount_factors(time_list)

([datetime.datetime(2015, 1, 1, 0, 0),
  datetime.datetime(2015, 4, 1, 0, 0),
  datetime.datetime(2015, 6, 15, 0, 0),
  datetime.datetime(2015, 10, 21, 0, 0)],
 [0.9716610313922761, 0.9787638348236196, 0.9862902768276359, 1.0])

2.3. Market Environment

The market_environment class is used to collect relevant data for the modeling, valuation and risk management of single derivatives instruments and portfolios composed of such instruments. A market_environment object stores:

• constants: e.g. maturity date of option
• lists: e.g. list of dates
• curves: e.g. discounting objects

A market_environment object is instantiated by providing a name as a string object and the pricing date as a datetime object.

me = market_environment(name='me', pricing_date=dt.datetime(2014, 1, 1))

Constants are added via the add_constant method and providing a key and the value.

me.add_constant('initial_value', 100.)

me.add_constant('volatility', 0.25)

Lists of data are added via the add_list method.

me.add_list('dates', time_list)

The add_curve method does the same for curves.

me.add_curve('discount_curve_1', r)

me.add_curve('discount_curve_2', y)

The single data objects are stored in separate dictionary objects.

me.constants

{'initial_value': 100.0, 'volatility': 0.25}

me.lists

{'dates': [datetime.datetime(2015, 1, 1, 0, 0),
  datetime.datetime(2015, 4, 1, 0, 0),
  datetime.datetime(2015, 6, 15, 0, 0),
  datetime.datetime(2015, 10, 21, 0, 0)]}

me.curves

{'discount_curve_1': <dx.frame.constant_short_rate at 0x10e05e208>,
 'discount_curve_2': <dx.frame.deterministic_short_rate at 0x10e05e710>}

Data is retrieved from a market_environment object via the get_constant, get_list and get_curve methods and providing the respective key.

me.get_constant('volatility')

0.25

me.get_list('dates')

[datetime.datetime(2015, 1, 1, 0, 0),
 datetime.datetime(2015, 4, 1, 0, 0),
 datetime.datetime(2015, 6, 15, 0, 0),
 datetime.datetime(2015, 10, 21, 0, 0)]

me.get_curve('discount_curve_1')

<dx.frame.constant_short_rate at 0x10e05e208>

Retrieving, for instance, a discounting object you can in one step retrieve it and call a method on it.

me.get_curve('discount_curve_2').get_discount_factors(time_list)

([datetime.datetime(2015, 1, 1, 0, 0),
  datetime.datetime(2015, 4, 1, 0, 0),
  datetime.datetime(2015, 6, 15, 0, 0),
  datetime.datetime(2015, 10, 21, 0, 0)],
 [0.9716610313922761, 0.9787638348236196, 0.9862902768276359, 1.0])

Copyright, License & Disclaimer

© Dr. Yves J. Hilpisch | The Python Quants GmbH

DX Analytics (the “dx library” or “dx package”) is licensed under the GNU Affero General Public License version 3 or later (see http://www.gnu.org/licenses/).

DX Analytics comes with no representations or warranties, to the extent permitted by applicable law.

http://tpq.io | dx@tpq.io | http://twitter.com/dyjh

Quant Platform | http://pqp.io

Python for Finance Training | http://training.tpq.io

Certificate in Computational Finance | http://compfinance.tpq.io

Derivatives Analytics with Python (Wiley Finance) | http://dawp.tpq.io

Python for Finance (2nd ed., O’Reilly) | http://py4fi.tpq.io