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

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

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

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

bond.dirtyPrice(discountCurve) ⇒ number

Calculates the current price (dirty, i.e. including accrued interest) for this bond.

Kind: instance method of Bond

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

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

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

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

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

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

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

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

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

Black 76 model for an option on a coupon-paying bond (asset class interest rates).

Kind: global function

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

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

irFlatDiscountCurve(flatRate) ⇒ DiscountCurve

Creates a DiscountCurve discounting with the constant flatRate.

Kind: global function

irLinearInterpolationSpotCurve(spotRates) ⇒ SpotCurve

Creates a SpotCurve by linearly interpolating the given points in time. Extrapolation in both directions is constant.

Kind: global function

irSpotCurve2DiscountCurve(spotCurve) ⇒ DiscountCurve

Turns a SpotCurve into a DiscountCurve. Inverse of irDiscountCurve2SpotCurve.

Kind: global function

irDiscountCurve2SpotCurve(discountCurve) ⇒ SpotCurve

Turns a DiscountCurve into a SpotCurve. Inverse of irSpotCurve2DiscountCurve.

Kind: global function

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

PricingResult : Object

Kind: global typedef
Properties

EqPricingResult : PricingResult

Kind: global typedef
Properties

OptionPricingResult : Object

Kind: global typedef
Properties

DiscountCurve ⇒ number

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

SpotCurve ⇒ number

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

SpotRate : Object

Kind: global typedef
Properties

FixedCashflow : Object

Kind: global typedef
Properties

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