Covariance Matrices, Portfolio Variance, and Diversification

Install and import#

npm install fintech-algorithms

import { covarianceMatricesPortfolioVarianceAndDiversification } from "fintech-algorithms/foundations/financial-risk-and-performance-statistics/covariance-matrices-portfolio-variance-and-diversification";

Signature#

covarianceMatricesPortfolioVarianceAndDiversification(input)

Combines portfolio weights with a covariance matrix into portfolio variance, and isolates the share of it that comes from the off-diagonal terms.

Parameters#

Returns#

D00Output

portfolioVariance is the quadratic form of the weights against the matrix, floored at zero, portfolioVolatility its square root, covarianceContribution the amount by which it exceeds the sum of the squared weights times the diagonal variances, and weightsSum the total of the supplied weights.

Errors#

• When returns or benchmark is absent, empty, or holds a non-finite number — throws RangeError
• When returns and benchmark differ in length, or hold fewer than two observations — throws RangeError
• When frequency is zero or negative — throws RangeError
• When weights and covarianceMatrix are not square-aligned, or weights does not sum to one within 1e-12 — throws RangeError
• When the quadratic form comes out below -1e-12, so the matrix is not positive semi-definite — throws RangeError
• When confidence is absent, or outside the range zero to one — the engine reads it for every topic from A04 onward, including those that never use it — throws RangeError

Complexity: time O(n log n + k^2), space O(n).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

{
  "returns": [0.01, -0.02, 0.015, -0.01, 0.03],
  "benchmark": [0.008, -0.01, 0.012, -0.006, 0.02],
  "frequency": 252,
  "target": 0,
  "confidence": 0.8,
  "riskFree": 0.0001,
  "weights": [0.6, 0.4],
  "covarianceMatrix": [
    [0.04, 0.01],
    [0.01, 0.09]
  ]
}

Call#

covarianceMatricesPortfolioVarianceAndDiversification(input)

Returns#

object with 2 fields: portfolioVariance, portfolioVolatility

{
  "portfolioVariance": 0.033600000000000005,
  "portfolioVolatility": 0.18330302779823363
}

Diagrams#

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• Expected Shortfall — Basel Framework MAR33
• Mutual Fund Performance — William F. Sharpe
• Measures of Scale — NIST/SEMATECH e-Handbook
• Historical-example decision

The rest of the Financial Risk and Performance Statistics family#

• Volatility and Annualized VolatilityTakes the sample standard deviation of a return series and rescales it to an annual horizon by the square root of the observati…
• Downside Deviation and Target ShortfallMeasures dispersion of returns below a target only, so upside swings do not count as risk.
• Drawdown and Maximum DrawdownCompounds a return series into a wealth path and tracks how far that path sits below its own running peak.
• Loss Distributions and Loss QuantilesFlips a return series into losses, sorts them, and reads off the quantile at the requested confidence by linear interpolation b…
• Value at Risk IntuitionReads historical value at risk straight off the sorted loss series and counts how many observed losses ran past it.
• Expected Shortfall IntuitionAverages the losses that sit at or beyond the value-at-risk threshold, describing the tail rather than only its edge.
• Beta and Market-Relative RiskDivides the sample covariance between a return series and its benchmark by the benchmark's sample variance.
• Sharpe, Sortino, and Information Ratio IntuitionComputes three reward-per-unit-of-risk ratios from the same series, each dividing an average by a different notion of risk.
• Active Return and Tracking ErrorSubtracts the benchmark from the portfolio period by period, then reports the average and the annualized volatility of that dif…