gaussian-analytics

Library for analytical pricings of financial derivatives under (log)normal distribution assumptions

Usage no npm install needed!

<script type="module">
  import gaussianAnalytics from 'https://cdn.skypack.dev/gaussian-analytics';
</script>

README

gaussian-analytics

npm version Build status

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

Bond

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

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.

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.

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.

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.

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

Black 76 model for an option on a coupon-paying 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

Coupon-paying 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 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)

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)

0.3.0 (2020-05-10)

0.2.0 (2020-05-09)

  • cdf (cumulative distribution function) for a standard normal distribution
  • test case for relationship between cdf and pdf

0.1.3 (2020-05-09)

  • extract normalizing constant for improved performance
  • test pdf example values
  • set up eslint linting (also on Travis CI)

0.1.2 (2020-05-09)

  • integrate API doc in README
  • API doc in README can automatically be updated by running npm run update-docs
  • set up .npmignore

0.1.1 (2020-05-09)

  • add first tests
  • set up CI infrastructure with Travis CI for testing

0.1.0 (2020-05-09)

  • pdf (probability density function) for a standard normal distribution
  • First release on npm