# 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.

In [1]:

from dx import *

In [2]:

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.

In [3]:

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.

In [4]:

get_year_deltas(time_list)

Out[4]:

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.

In [5]:

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

In [6]:

ran

Out[6]:

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.

In [7]:

ran.mean()

Out[7]:

0.0

In [8]:

ran.std()

Out[8]:

1.0


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

In [9]:

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

In [10]:

ran

Out[10]:

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.

In [11]:

r = constant_short_rate('r', 0.05)

In [12]:

r.name

Out[12]:

'r'

In [13]:

r.short_rate

Out[13]:

0.05


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

In [14]:

r.get_forward_rates(time_list)

Out[14]:

([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.

In [15]:

r.get_discount_factors(time_list)

Out[15]:

([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.

In [16]:

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

Out[16]:

(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.

In [17]:

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)]

In [18]:

y = deterministic_short_rate('y', yields)

In [19]:

y.name

Out[19]:

'y'

In [20]:

y.yield_list

Out[20]:

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.

In [21]:

y.get_interpolated_yields(time_list)

Out[21]:

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.

In [22]:

y.get_forward_rates(time_list)

Out[22]:

([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))

In [23]:

y.get_discount_factors(time_list)

Out[23]:

([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.

In [24]:

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.

In [25]:

me.add_constant('initial_value', 100.)

In [26]:

me.add_constant('volatility', 0.25)


Lists of data are added via the add_list method.

In [27]:

me.add_list('dates', time_list)


The add_curve method does the same for curves.

In [28]:

me.add_curve('discount_curve_1', r)

In [29]:

me.add_curve('discount_curve_2', y)


The single data objects are stored in separate dictionary objects.

In [30]:

me.constants

Out[30]:

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

In [31]:

me.lists

Out[31]:

{'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)]}

In [32]:

me.curves

Out[32]:

{'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.

In [33]:

me.get_constant('volatility')

Out[33]:

0.25

In [34]:

me.get_list('dates')

Out[34]:

[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)]

In [35]:

me.get_curve('discount_curve_1')

Out[35]:

<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.

In [36]:

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

Out[36]:

([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])