Gaussian-analytics NPM

gaussian-analytics

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.

gaussian-analytics.js is available from npm via

> npm install gaussian-analytics

Create a file mymodule.mjs (notice the extension .mjs which tells Node.js that this is an ES6 module) containing

import * as gauss from 'gaussian-analytics';

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 gaussian-analytics.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/gaussian-analytics').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.7755575615628914e-17,
  sigma: 0.2
}
 */

This should work at least for Firefox and Chrome.

API Documentation

Classes

Constants

Functions

Typedefs

Bond

Coupon-paying bond with schedule rolled from end. First coupon period is (possibly) shorter than later periods.

Kind: global class

Bond
- new Bond(notional, coupon, start, end, frequency)
- .cashflows ⇒ Array.<FixedCashflow>
- .forwardDirtyPrice(discountCurve, t) ⇒ number
- .dirtyPrice(discountCurve) ⇒ number
- .yieldToMaturity([npv]) ⇒ number

new Bond(notional, coupon, start, end, frequency)

Creates an instance of a coupon-paying 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

bond.cashflows ⇒ Array.<FixedCashflow>

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

bond.forwardDirtyPrice(discountCurve, t) ⇒ number

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

bond.dirtyPrice(discountCurve) ⇒ number

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)

bond.yieldToMaturity(npv) ⇒ number

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.

Kind: global constant

irMinimumPeriod

Minimum period irRollFromEnd will create.

Kind: global constant

pdf(x) ⇒ number

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

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.

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

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

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

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

eqBlackScholes(S, K, T, sigma, q, r) ⇒ EqPricingResult

Black-Scholes 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. 637-654.

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	risk-less rate of return

fxBlackScholes(S, K, T, sigma, rFor, rDom) ⇒ PricingResult

Black-Scholes 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. 231-237.

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	risk-less rate of return in the foreign currency
rDom	number	risk-less rate of return in the domestic currency

irBlack76(F, K, T, sigma, r) ⇒ PricingResult

Black-Scholes 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), 167-179.

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	risk-less rate of return

irBlack76BondOption(bond, K, T, sigma, spotCurve)

Black 76 model for an option on a coupon-paying 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	risk-less spot curve (used for forwards and discounting)

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

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)

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.

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)

irFlatDiscountCurve(flatRate) ⇒ DiscountCurve

Creates a DiscountCurve discounting with the constant flatRate.

Kind: global function

Param	Type
flatRate	number

irLinearInterpolationSpotCurve(spotRates) ⇒ SpotCurve

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

irSpotCurve2DiscountCurve(spotCurve) ⇒ DiscountCurve

Turns a SpotCurve into a DiscountCurve. Inverse of irDiscountCurve2SpotCurve.

Kind: global function

Param	Type	Description
spotCurve	SpotCurve	spot rate curve to be converted

irDiscountCurve2SpotCurve(discountCurve) ⇒ SpotCurve

Turns a DiscountCurve into a SpotCurve. Inverse of irSpotCurve2DiscountCurve.

Kind: global function

Param	Type	Description
discountCurve	DiscountCurve	discount curve to be converted

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.

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	1e-8	absolute tolerance to accept the current rate as solution
maxiter	number	100	maximum number of secant method iteration after which root finding aborts

PricingResult : Object

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

EqPricingResult : PricingResult

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

OptionPricingResult : Object

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

DiscountCurve ⇒ number

Kind: global typedef
Returns: number - discount factor at time t

Param	Type	Description
t	number	time (typically expressed in years)

SpotCurve ⇒ number

Kind: global typedef
Returns: number - spot interest rate to time t

Param	Type	Description
t	number	time (typically expressed in years)

SpotRate : Object

Kind: global typedef
Properties

Name	Type	Description
t	number	time (typically expressed in years)
rate	number	spot rate to time t

FixedCashflow : Object

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 (2020-06-24)

assert parameter types and numerical ranges of Bond irRollFromEnd, Bond.yieldToMaturity, cdf, pdf, irFlatDiscountCurve, irLinearInterpolationSpotCurve, irInternalRateOfReturn and curve conversion methods
ensure non-empty arrays in irLinearInterpolationSpotCurve and irInternalRateOfReturn
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 (2020-06-07)

implement irBlack76 (Black-Scholes formula for futures / forwards, particularly in interest rates)
implement irBlack76BondOption for specifically evaluating options on coupon-paying 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 (2020-05-30)

BREAKING CHANGE: move callPrice to call.price and putPrice to put.price on PricingResult objects; this will simplify the addition of greeks to results
implement delta and gamma (first- and second-order sensitivity of option price to spot change)
implement digital calls and puts for equity options

0.4.1 (2020-05-17)

assertions for parameter types and numerical ranges
test for fx pricing symmetry under currency switching

0.4.0 (2020-05-17)

BREAKING CHANGE: rename price to callPrice in the result of Margrabe's formulas
implement eqBlackScholes (Black-Scholes formula for stock options)
implement fxBlackScholes (Black-Scholes formula for currency options)