JavaScript library for analytical pricings of financial derivatives under (log)normal distribution assumptions.
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.
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.
Please make sure to have a recent version of Node.js with npm installed, at least v13.2.0.
Run npm install
in the top-level folder of this repository to create a development environment.
Then, npm run lint && npm run test
will run the linter and tests.
- Bond
Coupon-paying bond with schedule rolled from end. First coupon period is (possibly) shorter than later periods.
- irFrequency
Frequencies expressed as number of payments per year.
- irMinimumPeriod
Minimum period irRollFromEnd will create.
- 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, [scale]) ⇒
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, [scale]) ⇒
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, [scale]) ⇒
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, [scale]) ⇒
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, [scale]) ⇒
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) ⇒
PricingResult
Black 76 model for an option on a coupon-paying bond (asset class interest rates).
- irBlack76CapletFloorlet(floatingRate, K, sigma, spotCurve) ⇒
PricingResult
Black 76 model for a caplet / floorlet (asset class interest rates). Notional is retrieved from floatingRate.notional.
- irForwardLinearRate(floatingRate, discountCurve)
Calculates the linear forward rate given a floating cashflow and a discount curve.
- 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 cashflows, 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 no IRR can be found after maxiter iteration, an exception is thrown.
- PricingResult :
Object
- EqPricingResult :
PricingResult
- OptionPricingResult :
Object
- DiscountCurve ⇒
number
- SpotCurve ⇒
number
- SpotRate :
Object
- FixedCashflow :
Object
- FloatingCashflow :
Object
- Cashflow :
FixedCashflow
|FloatingCashflow
Coupon-paying bond with schedule rolled from end. First coupon period is (possibly) shorter than later periods.
Kind: global class
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
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 |
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) |
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) |
Calculates the bond duration given npv. There is no difference between Macaulay duration and Modified duration here as we use continuous yields for discounting.
Kind: instance method of Bond
Returns: number
- bond duration given npv
Param | Type | Default | Description |
---|---|---|---|
[npv] | number |
this.notional |
present value of the bond for yield calculation, defaults to 100% (i.e. notional) |
Frequencies expressed as number of payments per year.
Minimum period irRollFromEnd will create.
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 |
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, [scale]) ⇒ 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 | Default | 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 | |
[scale] | number |
1.0 |
scaling of all money amount and sensitivity results; think "number of options", but with fractional parts allowed |
margrabesFormulaShort(S1, S2, T, sigma, q1, q2, [scale]) ⇒ 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 | Default | 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 | |
[scale] | number |
1.0 |
scaling of all money amount and sensitivity results; think "number of options", but with fractional parts allowed |
eqBlackScholes(S, K, T, sigma, q, r, [scale]) ⇒ 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 | Default | 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 | |
[scale] | number |
1.0 |
scaling of all money amount and sensitivity results; think "number of options", but with fractional parts allowed |
fxBlackScholes(S, K, T, sigma, rFor, rDom, [scale]) ⇒ 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 | Default | 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 | |
[scale] | number |
1.0 |
scaling of all money amount and sensitivity results; think "number of options", but with fractional parts allowed |
irBlack76(F, K, T, sigma, r, [scale]) ⇒ 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 | Default | 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 | |
[scale] | number |
1.0 |
scaling of all money amount and sensitivity results; think "number of options", but with fractional parts allowed |
irBlack76BondOption(bond, K, T, sigma, spotCurve) ⇒ PricingResult
Black 76 model for an option on a coupon-paying bond (asset class interest rates).
Kind: global function
Returns: PricingResult
- prices of bond options
Param | Type | Description |
---|---|---|
bond | Bond |
underlying bond of the option |
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) |
irBlack76CapletFloorlet(floatingRate, K, sigma, spotCurve) ⇒ PricingResult
Black 76 model for a caplet / floorlet (asset class interest rates). Notional is retrieved from floatingRate.notional.
Kind: global function
Returns: PricingResult
- prices of caplet / floorlet
Param | Type | Description |
---|---|---|
floatingRate | FloatingCashflow |
underlying floating rate of the option |
K | number |
strike price of the option |
sigma | number |
volatility of the floating rate |
spotCurve | SpotCurve |
risk-less spot curve (used for forwards and discounting) |
Calculates the linear forward rate given a floating cashflow and a discount curve.
Kind: global function
Param | Type | Description |
---|---|---|
floatingRate | FloatingCashflow |
floating rate (notional is ignored) |
discountCurve | DiscountCurve |
discount curve used for forwards |
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.<Cashflow> |
future cashflows to be paid |
discountCurve | DiscountCurve |
discount curve (used for discounting and forwards) |
t | number |
time point of the forward (typically expressed in years) |
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 |
Calculates the internal rate of return (IRR) of the given series of cashflows, 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 no 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 |
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 |
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 |
logSimpleMoneyness | number |
logarithm of simple moneyness, i.e. ln(forward / strike) |
standardizedMoneyness | number |
standardized logSimpleMoneyness, i.e. ln(forward / strike) / (sigma * sqrt(T)) |
Kind: global typedef
Returns: number
- discount factor at time t
Param | Type | Description |
---|---|---|
t | number |
time (typically expressed in years) |
Kind: global typedef
Returns: number
- spot interest rate to time t
Param | Type | Description |
---|---|---|
t | number |
time (typically expressed in years) |
Kind: global typedef
Properties
Name | Type | Description |
---|---|---|
t | number |
time (typically expressed in years) |
rate | number |
spot rate to time t |
Kind: global typedef
Properties
Name | Type | Description |
---|---|---|
t | number |
time (typically expressed in years) |
value | number |
cash amount paid at t |
Kind: global typedef
Properties
Name | Type | Description |
---|---|---|
t | number |
fixing time |
T | number |
payment time, yearfraction is T - t |
notional | number |
notional amount that the rate fixed at will refer to |
Cashflow : FixedCashflow
| FloatingCashflow
Kind: global typedef
- introduce
FloatingCashflows
, supported byirForwardPrice
- implement
duration
method forBonds
- add
scale
parameter to option pricing functions - add
logSimpleMoneyness
andstandardizedMoneyness
to OptionPricingResult
- migrate from Travis-CI to GitHub Actions
- upgrade development dependencies
- 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
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
- 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
- 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 second-order sensitivity of option price to spot change)
- implement digital calls and puts for equity options
- assertions for parameter types and numerical ranges
- test for fx pricing symmetry under currency switching
- BREAKING CHANGE: rename
price
tocallPrice
in the result of Margrabe's formulas - implement
eqBlackScholes
(Black-Scholes formula for stock options) - implement
fxBlackScholes
(Black-Scholes formula for currency options)
- implement
margrabesFormula
andmargrabesFormulaShort
- first test cases for the correctness of Margrabe's formula implementation
cdf
(cumulative distribution function) for a standard normal distribution- test case for relationship between
cdf
andpdf
- extract normalizing constant for improved performance
- test pdf example values
- set up
eslint
linting (also on Travis CI)
- integrate API doc in README
- API doc in README can automatically be updated by running
npm run update-docs
- set up
.npmignore
- add first tests
- set up CI infrastructure with Travis CI for testing
pdf
(probability density function) for a standard normal distribution- First release on npm