README
gaussiananalytics
JavaScript library for analytical pricings of financial derivatives under (log)normal distribution assumptions.
Usage
Usage in Node.js
Please make sure to have a recent version of Node.js with npm installed, at least v13.2.0.
gaussiananalytics.js
is available from npm via
> npm install gaussiananalytics
Create a file mymodule.mjs
(notice the extension .mjs
which tells Node.js that this is an ES6 module) containing
import * as gauss from 'gaussiananalytics';
console.log(gauss.pdf(0));
and run it by
> node mymodule.mjs
0.3989422804014327
For more details on Node.js and ES6 modules please see https://nodejs.org/api/esm.html#esm_enabling.
Experiment in browser console
As gaussiananalytics.js
is published as an ES6 module you have to apply the following trick to play with it in your browser's dev console. First open the dev console (in Firefox press F12
) and execute
// dynamically import ES6 module and store it as global variable gauss
import('//unpkg.com/gaussiananalytics').then(m => window.gauss=m);
Afterwards, the global variable gauss
will contain the module and you can call exported functions on it, e.g.
gauss.eqBlackScholes(100, 100, 1.0, 0.2, 0.0, 0.02);
/* >
{
call: {
price: 8.916035060662303,
delta: 0.5792596877744174,
gamma: 0.019552134698772795
},
put: {
price: 6.935902391337827,
delta: 0.4207403122255826,
gamma: 0.019552134698772795
},
digitalCall: {
price: 0.49009933716779436,
delta: 0.019552134698772795,
gamma: 0.00019164976492052065
},
digitalPut: {
price: 0.4900993361389609,
delta: 0.019552134698772795,
gamma: 0.00019164976492052065
},
N_d1: 0.5792596877744174,
N_d2: 0.5000000005248086,
d1: 0.20000000000000004,
d2: 2.7755575615628914e17,
sigma: 0.2
}
*/
This should work at least for Firefox and Chrome.
API Documentation
Classes
 Bond
Couponpaying bond with schedule rolled from end. First coupon period is (possibly) shorter than later periods.
Constants
 irFrequency
Frequencies expressed as number of payments per year.
 irMinimumPeriod
Minimum period irRollFromEnd will create.
Functions
 pdf(x) ⇒
number
Probability density function (pdf) for a standard normal distribution.
 cdf(x) ⇒
number
Cumulative distribution function (cdf) for a standard normal distribution. Approximation by Zelen, Marvin and Severo, Norman C. (1964), formula 26.2.17.
 margrabesFormula(S1, S2, T, sigma1, sigma2, rho, q1, q2) ⇒
PricingResult
Margrabe's formula for pricing the exchange option between two risky assets.
See William Margrabe, The Value of an Option to Exchange One Asset for Another, Journal of Finance, Vol. 33, No. 1, (March 1978), pp. 177186.
 margrabesFormulaShort(S1, S2, T, sigma, q1, q2) ⇒
PricingResult
Margrabe's formula for pricing the exchange option between two risky assets. Equivalent to
margrabesFormula
but accepting only the volatility corresponding to the ratioS1/S2
instead of their individual volatilities. eqBlackScholes(S, K, T, sigma, q, r) ⇒
EqPricingResult
BlackScholes formula for a European vanilla option on a stock (asset class equity).
See Fischer Black and Myron Scholes, The Pricing of Options and Corporate Liabilities, The Journal of Political Economy, Vol. 81, No. 3 (May  June 1973), pp. 637654.
 fxBlackScholes(S, K, T, sigma, rFor, rDom) ⇒
PricingResult
BlackScholes formula for a European vanilla currency option (asset class foreign exchange). This is also known as the Garman–Kohlhagen model.
See Mark B. Garman and Steven W. Kohlhagen Foreign currency option values, Journal of International Money and Finance, Vol. 2, Issue 3 (1983), pp. 231237.
 irBlack76(F, K, T, sigma, r) ⇒
PricingResult
BlackScholes formula for European option on forward / future (asset class interest rates), known as the Black 76 model.
See Fischer Black The pricing of commodity contracts, Journal of Financial Economics, 3 (1976), 167179.
 irBlack76BondOption(bond, K, T, sigma, spotCurve)
Black 76 model for an option on a couponpaying bond (asset class interest rates).
 irForwardPrice(cashflows, discountCurve, t) ⇒
number
Calculates the forward price at time t for a series of cashflows. Cashflows before t are ignored (i.e. do not add any value).
 irRollFromEnd(start, end, frequency) ⇒
Array.<number>
Creates a payment schedule with payment frequency frequency that has last payment at end and no payments before start. First payment period is (possibly) shorter than later periods.
 irFlatDiscountCurve(flatRate) ⇒
DiscountCurve
Creates a DiscountCurve discounting with the constant flatRate.
 irLinearInterpolationSpotCurve(spotRates) ⇒
SpotCurve
Creates a SpotCurve by linearly interpolating the given points in time. Extrapolation in both directions is constant.
 irSpotCurve2DiscountCurve(spotCurve) ⇒
DiscountCurve
Turns a SpotCurve into a DiscountCurve. Inverse of irDiscountCurve2SpotCurve.
 irDiscountCurve2SpotCurve(discountCurve) ⇒
SpotCurve
Turns a DiscountCurve into a SpotCurve. Inverse of irSpotCurve2DiscountCurve.
 irInternalRateOfReturn(cashflows, [r0], [r1], [abstol], [maxiter]) ⇒
number
Calculates the internal rate of return (IRR) of the given series of cashflow, i.e. the flat discount rate (continuously compounded) for which the total NPV of the given cashflows is 0. The secant method is used. If not IRR can be found after maxiter iteration, an exception is thrown.
Typedefs
 PricingResult :
Object
 EqPricingResult :
PricingResult
 OptionPricingResult :
Object
 DiscountCurve ⇒
number
 SpotCurve ⇒
number
 SpotRate :
Object
 FixedCashflow :
Object
Bond
Couponpaying bond with schedule rolled from end. First coupon period is (possibly) shorter than later periods.
Kind: global class
new Bond(notional, coupon, start, end, frequency)
Creates an instance of a couponpaying bond.
Param  Type  Description 

notional  number 
notional payment, i.e. last cashflow and reference amount for notional 
coupon  number 
annual coupon relative to notional (i.e. 0.04 for 4%, not a currency amount) 
start  number 
start time of bond (schedule will be rolled from end) 
end  number 
end time of bond (time of notional payment) 
frequency  number 
number of payments per year 
Array.<FixedCashflow>
bond.cashflows ⇒ Cashflows of this bond as an array. Last coupon and notional payment are returned separately. For zero bonds (i.e. coupon === 0), only the notional payment is returned as cashflow.
Kind: instance property of Bond
number
bond.forwardDirtyPrice(discountCurve, t) ⇒ Calculates the forward price (dirty, i.e. including accrued interest) at time t for this bond.
Kind: instance method of Bond
Param  Type  Description 

discountCurve  DiscountCurve 
discount curve (used for discounting and forwards) 
t  number 
time for which the forward dirty price is to be calculated 
number
bond.dirtyPrice(discountCurve) ⇒ Calculates the current price (dirty, i.e. including accrued interest) for this bond.
Kind: instance method of Bond
Param  Type  Description 

discountCurve  DiscountCurve 
discount curve (used for discounting and forwards) 
number
bond.yieldToMaturity([npv]) ⇒ Calculates the bond yield given npv, i.e the flat discount rate (continuously compounded) for which the dirty price of the bond equals npv.
Kind: instance method of Bond
Returns: number
 bond yield given npv
Param  Type  Default  Description 

[npv]  number 
this.notional 
present value of the bond for yield calculation, defaults to 100% (i.e. notional) 
irFrequency
Frequencies expressed as number of payments per year.
irMinimumPeriod
Minimum period irRollFromEnd will create.
number
pdf(x) ⇒ Probability density function (pdf) for a standard normal distribution.
Kind: global function
Returns: number
 density of standard normal distribution
Param  Type  Description 

x  number 
value for which the density is to be calculated 
number
cdf(x) ⇒ Cumulative distribution function (cdf) for a standard normal distribution. Approximation by Zelen, Marvin and Severo, Norman C. (1964), formula 26.2.17.
Kind: global function
Returns: number
 cumulative distribution of standard normal distribution
Param  Type  Description 

x  number 
value for which the cumulative distribution is to be calculated 
PricingResult
margrabesFormula(S1, S2, T, sigma1, sigma2, rho, q1, q2) ⇒ Margrabe's formula for pricing the exchange option between two risky assets.
See William Margrabe, The Value of an Option to Exchange One Asset for Another, Journal of Finance, Vol. 33, No. 1, (March 1978), pp. 177186.
Kind: global function
Param  Type  Description 

S1  number 
spot value of the first asset 
S2  number 
spot value of the second asset 
T  number 
time to maturity (typically expressed in years) 
sigma1  number 
volatility of the first asset 
sigma2  number 
volatility of the second asset 
rho  number 
correlation of the Brownian motions driving the asset prices 
q1  number 
dividend yield of the first asset 
q2  number 
dividend yield of the second asset 
PricingResult
margrabesFormulaShort(S1, S2, T, sigma, q1, q2) ⇒ Margrabe's formula for pricing the exchange option between two risky assets.
Equivalent to margrabesFormula
but accepting only the volatility corresponding
to the ratio S1/S2
instead of their individual volatilities.
Kind: global function
See: margrabesFormula
Param  Type  Description 

S1  number 
spot value of the first asset 
S2  number 
spot value of the second asset 
T  number 
time to maturity (typically expressed in years) 
sigma  number 
volatility of the ratio of both assets 
q1  number 
dividend yield of the first asset 
q2  number 
dividend yield of the second asset 
EqPricingResult
eqBlackScholes(S, K, T, sigma, q, r) ⇒ BlackScholes formula for a European vanilla option on a stock (asset class equity).
See Fischer Black and Myron Scholes, The Pricing of Options and Corporate Liabilities, The Journal of Political Economy, Vol. 81, No. 3 (May  June 1973), pp. 637654.
Kind: global function
Param  Type  Description 

S  number 
spot value of the stock 
K  number 
strike price of the option 
T  number 
time to maturity (typically expressed in years) 
sigma  number 
volatility of the underlying stock 
q  number 
dividend rate of the underlying stock 
r  number 
riskless rate of return 
PricingResult
fxBlackScholes(S, K, T, sigma, rFor, rDom) ⇒ BlackScholes formula for a European vanilla currency option (asset class foreign exchange). This is also known as the Garman–Kohlhagen model.
See Mark B. Garman and Steven W. Kohlhagen Foreign currency option values, Journal of International Money and Finance, Vol. 2, Issue 3 (1983), pp. 231237.
Kind: global function
Returns: PricingResult
 prices in domestic currency
Param  Type  Description 

S  number 
spot value of the currency exchange rate; this has to be expressed in unit of domestic currency / unit of foreign currency 
K  number 
strike price of the option 
T  number 
time to maturity (typically expressed in years) 
sigma  number 
volatility of the currency exchange rate 
rFor  number 
riskless rate of return in the foreign currency 
rDom  number 
riskless rate of return in the domestic currency 
PricingResult
irBlack76(F, K, T, sigma, r) ⇒ BlackScholes formula for European option on forward / future (asset class interest rates), known as the Black 76 model.
See Fischer Black The pricing of commodity contracts, Journal of Financial Economics, 3 (1976), 167179.
Kind: global function
Returns: PricingResult
 prices of forward / future option
Param  Type  Description 

F  number 
forward price of the underlying 
K  number 
strike price of the option 
T  number 
time to maturity (typically expressed in years) 
sigma  number 
volatility of the underlying forward price 
r  number 
riskless rate of return 
irBlack76BondOption(bond, K, T, sigma, spotCurve)
Black 76 model for an option on a couponpaying bond (asset class interest rates).
Kind: global function
Param  Type  Description 

bond  Bond 

K  number 
(dirty) strike price of the option 
T  number 
time to maturity (typically expressed in years) 
sigma  number 
volatility of the bond forward price 
spotCurve  SpotCurve 
riskless spot curve (used for forwards and discounting) 
number
irForwardPrice(cashflows, discountCurve, t) ⇒ Calculates the forward price at time t for a series of cashflows. Cashflows before t are ignored (i.e. do not add any value).
Kind: global function
Returns: number
 forward price of given cashflows
Param  Type  Description 

cashflows  Array.<FixedCashflow> 
future cashflows to be paid 
discountCurve  DiscountCurve 
discount curve (used for discounting and forwards) 
t  number 
time point of the forward (typicall expressed in years) 
Array.<number>
irRollFromEnd(start, end, frequency) ⇒ Creates a payment schedule with payment frequency frequency that has last payment at end and no payments before start. First payment period is (possibly) shorter than later periods.
Kind: global function
Returns: Array.<number>
 payment times
Param  Type  Description 

start  number 
start time of schedule (usually expressed in years) 
end  number 
end time of schedule (usually expressed in years) 
frequency  number 
number of payments per time unit (usually per year) 
DiscountCurve
irFlatDiscountCurve(flatRate) ⇒ Creates a DiscountCurve discounting with the constant flatRate.
Kind: global function
Param  Type 

flatRate  number 
SpotCurve
irLinearInterpolationSpotCurve(spotRates) ⇒ Creates a SpotCurve by linearly interpolating the given points in time. Extrapolation in both directions is constant.
Kind: global function
Param  Type  Description 

spotRates  Array.<SpotRate> 
individual spot rates used for interpolation; will be sorted automatically 
DiscountCurve
irSpotCurve2DiscountCurve(spotCurve) ⇒ Turns a SpotCurve into a DiscountCurve. Inverse of irDiscountCurve2SpotCurve.
Kind: global function
Param  Type  Description 

spotCurve  SpotCurve 
spot rate curve to be converted 
SpotCurve
irDiscountCurve2SpotCurve(discountCurve) ⇒ Turns a DiscountCurve into a SpotCurve. Inverse of irSpotCurve2DiscountCurve.
Kind: global function
Param  Type  Description 

discountCurve  DiscountCurve 
discount curve to be converted 
number
irInternalRateOfReturn(cashflows, [r0], [r1], [abstol], [maxiter]) ⇒ Calculates the internal rate of return (IRR) of the given series of cashflow, i.e. the flat discount rate (continuously compounded) for which the total NPV of the given cashflows is 0. The secant method is used. If not IRR can be found after maxiter iteration, an exception is thrown.
Kind: global function
Returns: number
 continuously compounded IRR
Param  Type  Default  Description 

cashflows  Array.<FixedCashflow> 
cashflows for which the IRR is to be calculated  
[r0]  number 
0 
first guess for IRR 
[r1]  number 
0.05 
second guess for IRR, may not be equal to r0 
[abstol]  number 
1e8 
absolute tolerance to accept the current rate as solution 
[maxiter]  number 
100 
maximum number of secant method iteration after which root finding aborts 
Object
PricingResult : Kind: global typedef
Properties
Name  Type  Description 

call  OptionPricingResult 
results for the call option 
put  OptionPricingResult 
results for the put optionCall 
digitalCall  OptionPricingResult 
results for digital call option 
digitalPut  OptionPricingResult 
results for digital put option 
N_d1  number 
cumulative probability of d1 
N_d2  number 
cumulative probability of d2 
d1  number 

d2  number 

sigma  number 
pricing volatility 
PricingResult
EqPricingResult : Kind: global typedef
Properties
Name  Type  Description 

digitalCall  OptionPricingResult 
results for digital (a.k.a. binary) call option 
digitalPut  OptionPricingResult 
results for digital (a.k.a. binary) put option 
Object
OptionPricingResult : Kind: global typedef
Properties
Name  Type  Description 

price  number 
price of the option 
delta  number 
delta, i.e. derivative by (first) underlying of the option 
gamma  number 
gamma, i.e. second derivative by (first) underlying of the option 
number
DiscountCurve ⇒ Kind: global typedef
Returns: number
 discount factor at time t
Param  Type  Description 

t  number 
time (typically expressed in years) 
number
SpotCurve ⇒ Kind: global typedef
Returns: number
 spot interest rate to time t
Param  Type  Description 

t  number 
time (typically expressed in years) 
Object
SpotRate : Kind: global typedef
Properties
Name  Type  Description 

t  number 
time (typically expressed in years) 
rate  number 
spot rate to time t 
Object
FixedCashflow : Kind: global typedef
Properties
Name  Type  Description 

t  number 
time (typically expressed in years) 
value  number 
cash amount paid at t 
History
0.6.1 (20200624)
 assert parameter types and numerical ranges of
Bond
irRollFromEnd
, Bond.yieldToMaturity,cdf
,pdf
,irFlatDiscountCurve
,irLinearInterpolationSpotCurve
,irInternalRateOfReturn
and curve conversion methods  ensure nonempty arrays in
irLinearInterpolationSpotCurve
andirInternalRateOfReturn
 do not modify spotRates passed to
irLinearInterpolationSpotCurve
 for zero bonds (i.e. coupon === 0), only the notional payment is returned as cashflow by Bond.cashflows
0.6.0 (20200607)
 implement
irBlack76
(BlackScholes formula for futures / forwards, particularly in interest rates)  implement
irBlack76BondOption
for specifically evaluating options on couponpaying bonds  implement
irForwardPrice
for calculation of forward prices for fixed cashflows  implement
irRollFromEnd
for creating regular payment schedules  implement
irInternalRateOfReturn
to solve for IRR using the secant method  implement class
Bond
with methods for obtaining cashflows, (forward) dirty price and yield to maturity  implement helper and conversion functions for dealing with spot and discount curves
0.5.0 (20200530)
 BREAKING CHANGE: move
callPrice
tocall.price
andputPrice
toput.price
onPricingResult
objects; this will simplify the addition of greeks to results  implement delta and gamma (first and secondorder sensitivity of option price to spot change)
 implement digital calls and puts for equity options
0.4.1 (20200517)
 assertions for parameter types and numerical ranges
 test for fx pricing symmetry under currency switching
0.4.0 (20200517)
 BREAKING CHANGE: rename
price
tocallPrice
in the result of Margrabe's formulas  implement
eqBlackScholes
(BlackScholes formula for stock options)  implement
fxBlackScholes
(BlackScholes formula for currency options)
0.3.0 (20200510)
 implement
margrabesFormula
andmargrabesFormulaShort
 first test cases for the correctness of Margrabe's formula implementation
0.2.0 (20200509)
cdf
(cumulative distribution function) for a standard normal distribution test case for relationship between
cdf
andpdf
0.1.3 (20200509)
 extract normalizing constant for improved performance
 test pdf example values
 set up
eslint
linting (also on Travis CI)
0.1.2 (20200509)
 integrate API doc in README
 API doc in README can automatically be updated by running
npm run updatedocs
 set up
.npmignore
0.1.1 (20200509)
 add first tests
 set up CI infrastructure with Travis CI for testing
0.1.0 (20200509)
pdf
(probability density function) for a standard normal distribution First release on npm