Interest rate transformations

Overview

Transformations between nominal, effective and periodic interest rates can be realized using cashflows. This module implements the following functions:

• effrate: computes the effective interest rate given the nominal interest rate or the periodic interest rate.
• nomrate: computes the nominal interest rate given the effective interest rate or the periodic interest rate.
• perrate: computes the periodic interest rate given the effective interest rate or the nominal interest rate.

In addition, it is possible to compute discount and compounidng factors.

• to_discount_factor: Returns a list of discount factors calculated as 1 / (1 + r)^(t - t0).
• to_compound_factor: Returns a list of compounding factors calculated as (1 + r)^(t - t0).

Finally, also it is possible to compute a fixed equivalent rate given interest rate changing over time using equivalent_rate.

Functions in this module

cashflows.rate.effrate(nrate=None, prate=None, pyr=1)

Computes the effective interest rate given the nominal interest rate or the periodic interest rate.

Parameters:

• nrate (float, pandas.Series) – Nominal interest rate.
• prate (float, pandas.Series) – Periodic interest rate.
• pyr (int) – Number of compounding periods per year.

Returns:

Effective interest rate(float, pandas.Series).

Examples

In this example, the equivalent effective interest rate for a periodic monthly interest rate of 1% is computed.

>>> effrate(prate=1, pyr=12) 
12.68...

This example shows hot to compute the effective interes rate equivalent to a nominal interest rate of 10% with montlhy compounding.

>>> effrate(nrate=10, pyr=12) 
10.4713...

Also it is possible to use list for some arguments of the functions as it is shown bellow.

>>> effrate(prate=1, pyr=[3, 6, 12]) 
0     3.030100
1     6.152015
2    12.682503
dtype: float64

>>> effrate(nrate=10, pyr=[3, 6, 12]) 
0    10.337037
1    10.426042
2    10.471307
dtype: float64

>>> effrate(prate=[1, 2, 3], pyr=12) 
0    12.682503
1    26.824179
2    42.576089
dtype: float64

>>> effrate(nrate=[10, 12, 14], pyr=12) 
0    10.471307
1    12.682503
2    14.934203
dtype: float64

When a rate and the number of compounding periods (pyr) are vectors, they must have the same length. Computations are executed using the first rate with the first compounding and so on.

>>> effrate(nrate=[10, 12, 14], pyr=[3, 6, 12]) 
0    10.337037
1    12.616242
2    14.934203
dtype: float64

>>> effrate(prate=[1, 2, 3], pyr=[3, 6, 12]) 
0     3.030100
1    12.616242
2    42.576089
dtype: float64

Also it is possible to transform interest rate time series.

>>> nrate = interest_rate(const_value=12, start='2000-06', periods=12, freq='6M')
>>> prate = perrate(nrate=nrate)
>>> effrate(nrate = nrate) 
2000-06    12.36
2000-12    12.36
2001-06    12.36
2001-12    12.36
2002-06    12.36
2002-12    12.36
2003-06    12.36
2003-12    12.36
2004-06    12.36
2004-12    12.36
2005-06    12.36
2005-12    12.36
Freq: 6M, dtype: float64

>>> effrate(prate = prate) 
2000-06    12.36
2000-12    12.36
2001-06    12.36
2001-12    12.36
2002-06    12.36
2002-12    12.36
2003-06    12.36
2003-12    12.36
2004-06    12.36
2004-12    12.36
2005-06    12.36
2005-12    12.36
Freq: 6M, dtype: float64

cashflows.rate.equivalent_rate(nrate=None, erate=None, prate=None)

Returns the equivalent interest rate over a time period.

Parameters:

• nrate (TimeSeries) – Nominal interest rate per year.
• erate (TimeSeries) – Effective interest rate per year.
• prate (TimeSeries) – Periodic interest rate.

Returns:

float value.

Only one of the interest rate must be supplied for the computation.

Example

In this example, the equivalent rate for a periodic interest rate of 10% is computed.

>>> equivalent_rate(prate=interest_rate([10]*5, start='2000Q1', freq='Q')) 
10.0...

cashflows.rate.nomrate(erate=None, prate=None, pyr=1)

Computes the nominal interest rate given the nominal interest rate or the periodic interest rate.

Parameters:

• erate (float, pandas.Series) – Effective interest rate.
• prate (float, pandas.Series) – Periodic interest rate.
• pyr (int) – Number of compounding periods per year.

Returns:

Nominal interest rate(float, pandas.Series).

Examples

>>> nomrate(prate=1, pyr=12) 
12.0

>>> nomrate(erate=10, pyr=[3, 6, 12]) 
0    9.684035
1    9.607121
2    9.568969
dtype: float64

>>> nomrate(erate=10, pyr=12) 
9.5689...

>>> nomrate(prate=1, pyr=[3, 6, 12]) 
0     3.0
1     6.0
2    12.0
dtype: float64

>>> nomrate(erate=[10, 12, 14], pyr=12) 
0     9.568969
1    11.386552
2    13.174622
dtype: float64

>>> nomrate(prate=[1, 2, 3], pyr=12) 
0    12.0
1    24.0
2    36.0
dtype: float64

When a rate and the number of compounding periods (pyr) are vectors, they must have the same length. Computations are executed using the first rate with the first compounding and so on.

>>> nomrate(erate=[10, 12, 14], pyr=[3, 6, 12]) 
0     9.684035
1    11.440574
2    13.174622
dtype: float64

>>> nomrate(prate=[1, 2, 3], pyr=[3, 6, 12]) 
0     3.0
1    12.0
2    36.0
dtype: float64

>>> prate = interest_rate(const_value=6.00, start='2000-06', periods=12, freq='6M')
>>> erate = effrate(prate=prate)
>>> nomrate(erate=erate)
2000-06    12.0
2000-12    12.0
2001-06    12.0
2001-12    12.0
2002-06    12.0
2002-12    12.0
2003-06    12.0
2003-12    12.0
2004-06    12.0
2004-12    12.0
2005-06    12.0
2005-12    12.0
Freq: 6M, dtype: float64

>>> nomrate(prate=prate)
2000-06    12.0
2000-12    12.0
2001-06    12.0
2001-12    12.0
2002-06    12.0
2002-12    12.0
2003-06    12.0
2003-12    12.0
2004-06    12.0
2004-12    12.0
2005-06    12.0
2005-12    12.0
Freq: 6M, dtype: float64

cashflows.rate.perrate(nrate=None, erate=None, pyr=1)

Computes the periodic interest rate given the nominal interest rate or the effective interest rate.

Parameters:

• nrate (float, pandas.Series) – Nominal interest rate.
• erate (float, pandas.Series) – Effective interest rate.
• pyr (int) – Number of compounding periods per year.

Returns:

Periodic interest rate(float, pandas.Series).

Examples

>>> perrate(nrate=10, pyr=12) 
0.8333...

>>> perrate(erate=10, pyr=12) 
0.7974...

>>> perrate(erate=10, pyr=[3, 6, 12]) 
0    3.228012
1    1.601187
2    0.797414
dtype: float64

>>> perrate(nrate=10, pyr=[3, 6, 12]) 
0    3.333333
1    1.666667
2    0.833333
dtype: float64

>>> perrate(erate=[10, 12, 14], pyr=12) 
0    0.797414
1    0.948879
2    1.097885
dtype: float64

>>> perrate(nrate=[10, 12, 14], pyr=12) 
0    0.833333
1    1.000000
2    1.166667
dtype: float64

When a rate and the number of compounding periods (pyr) are vectors, they must have the same length. Computations are executed using the first rate with the first compounding and so on.

>>> perrate(erate=[10, 12, 14], pyr=[3, 6, 12]) 
0    3.228012
1    1.906762
2    1.097885
dtype: float64

>>> perrate(nrate=[10, 12, 14], pyr=[3, 6, 12]) 
0    3.333333
1    2.000000
2    1.166667
dtype: float64

>>> nrate = interest_rate(const_value=12.0,  start='2000-06', periods=12, freq='6M')
>>> erate = effrate(nrate=nrate)
>>> perrate(erate=erate) 
2000-06    6.0
2000-12    6.0
2001-06    6.0
2001-12    6.0
2002-06    6.0
2002-12    6.0
2003-06    6.0
2003-12    6.0
2004-06    6.0
2004-12    6.0
2005-06    6.0
2005-12    6.0
Freq: 6M, dtype: float64

>>> perrate(nrate=nrate) 
2000-06    6.0
2000-12    6.0
2001-06    6.0
2001-12    6.0
2002-06    6.0
2002-12    6.0
2003-06    6.0
2003-12    6.0
2004-06    6.0
2004-12    6.0
2005-06    6.0
2005-12    6.0
Freq: 6M, dtype: float64

cashflows.rate.to_compound_factor(nrate=None, erate=None, prate=None, base_date=0)

Returns a list of compounding factors calculated as (1 + r)^(t - t0).

Parameters:

• nrate (TimeSeries) – Nominal interest rate per year.
• nrate – Effective interest rate per year.
• prate (TimeSeries) – Periodic interest rate.
• base_date (int, tuple) – basis time.

Returns:

Compound factor (list)

Example

In this example, a compound factor is computed for a interest rate expressed as nominal, periodic or effective interest rate.

>>> nrate = interest_rate(const_value=4, start='2000', periods=10, freq='Q')
>>> erate = effrate(nrate=nrate)
>>> prate = perrate(nrate=nrate)
>>> to_compound_factor(prate=prate, base_date=2) 
[0.980..., 0.990..., 1.0, 1.01, 1.0201, 1.030..., 1.040..., 1.051..., 1.061..., 1.072...]

>>> to_compound_factor(nrate=nrate, base_date=2) 
[0.980..., 0.990..., 1.0, 1.01, 1.0201, 1.030..., 1.040..., 1.051..., 1.061..., 1.072...]

>>> to_compound_factor(erate=erate, base_date=2) 
[0.980..., 0.990..., 1.0, 1.01, 1.0201, 1.030..., 1.040..., 1.051..., 1.061..., 1.072...]

cashflows.rate.to_discount_factor(nrate=None, erate=None, prate=None, base_date=None)

Returns a list of discount factors calculated as 1 / (1 + r)^(t - t0).

Parameters:

• nrate (pandas.Series) – Nominal interest rate per year.
• nrate – Effective interest rate per year.
• prate (pandas.Series) – Periodic interest rate.
• base_date (string) – basis time.

Returns:

pandas.Series of float values.

Only one of the interest rates must be supplied for the computation.

Example

In this example, a discount factor is computed for a interest rate expressed as nominal, periodic or effective interest rate.

>>> nrate = interest_rate(const_value=4, periods=10, start='2016Q1', freq='Q')
>>> erate = effrate(nrate=nrate)
>>> prate = perrate(nrate=nrate)
>>> to_discount_factor(nrate=nrate, base_date='2016Q3') 
[1.0201, 1.01, 1.0, 0.990..., 0.980..., 0.970..., 0.960..., 0.951..., 0.942..., 0.932...]

>>> to_discount_factor(erate=erate, base_date='2016Q3') 
[1.0201, 1.01, 1.0, 0.990..., 0.980..., 0.970..., 0.960..., 0.951..., 0.942..., 0.932...]

>>> to_discount_factor(prate=prate, base_date='2016Q3') 
[1.0201, 1.01, 1.0, 0.990..., 0.980..., 0.970..., 0.960..., 0.951..., 0.942..., 0.932...]