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)

0.3.0 (2020-05-10)

• implement margrabesFormula and margrabesFormulaShort
• first test cases for the correctness of Margrabe's formula implementation

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