Class EwmaCovariance

java.lang.Object
com.quantfinlib.microstructure.EwmaCovariance
public final class EwmaCovariance extends Object
Streaming EWMA covariance matrix — the multi-asset risk picture that single-symbol volatility cannot see. RiskMetrics-style: one return vector per sampling interval, cov ← λ·cov + (1−λ)·rᵢrⱼ, with the classic zero-mean convention (intraday returns have negligible mean at these horizons; carrying decayed means would double the state for a correction smaller than the estimation noise — a documented choice, not an oversight).

Who consumes it. execution.PortfolioExecutor documents its capacity allocation as the diagonal approximation of multi-asset Almgren-Chriss; marginalContribution(double[], double[]) is the missing off-diagonal piece — feed the matrix via PortfolioExecutor.useRiskModel and scarce liquidity flows to the symbols whose remaining position contributes most to BASKET risk, not just to their own. minVarianceHedgeRatio(int, int) is the live hedge beta (cov/var) for cross hedging.

Discipline. The matrix stays positive-semidefinite because every update is a full-vector rank-1 outer product: a sample containing ANY non-finite return is dropped whole (updating only the clean pairs would break PSD and silently skew correlations). Each pair seeds from its first observation rather than ramping from 0. The lower triangle lives in one flat array — zero allocation per sample, O(n²) work, which at basket sizes (tens of symbols) on an interval cadence is microseconds. Single writer.

  • Constructor Summary

    Constructors
    Constructor
    Description
    EwmaCovariance(int symbols)
    RiskMetrics λ = 0.94.
    EwmaCovariance(int symbols, double lambda)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    correlation(int i, int j)
    Decayed correlation in [-1, 1]; 0 while either variance is 0.
    double
    covariance(int i, int j)
    Decayed covariance between two symbols (order-free).
    double
    marginalContribution(double[] weights, double[] out)
    Marginal contribution to portfolio risk: out[i] = wᵢ·(Σw)ᵢ / (w'Σw) — the fraction of total basket variance symbol i's position is responsible for (contributions sum to 1; a natural hedge contributes negatively).
    double
    minVarianceHedgeRatio(int target, int hedge)
    The live minimum-variance hedge ratio: hedge target with cov(target,hedge)/var(hedge) units of hedge — the streaming sibling of hedging.MinimumVarianceHedge. 0 while the hedge instrument's variance is unlearned.
    void
    onReturns(double[] returns)
    One sampling interval: every symbol's return over the interval that just closed (0 for a symbol that did not move — that IS its return).
    double
    portfolioVariance(double[] weights)
    w'Σw: portfolio variance of the (signed) weight vector.
    void
    readState(DataInput in)
    Restores the matrix.
    long
    samples()
     
    int
    symbols()
     
    double
    variance(int i)
    Decayed variance of one symbol.
    double
    volatility(int i)
    Decayed volatility (per √interval), 0 until learned.
    void
    writeState(DataOutput out)
    Persists the learned matrix — see persist.Checkpoint.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • EwmaCovariance

      public EwmaCovariance(int symbols, double lambda)
      Parameters:
      symbols - basket size (dense indices, fixed at construction)
      lambda - decay per sample, e.g. 0.94 (RiskMetrics daily convention; intraday intervals often want 0.97–0.99)

    • EwmaCovariance

      public EwmaCovariance(int symbols)
      RiskMetrics λ = 0.94.

  • Method Details

    • onReturns

      public void onReturns(double[] returns)
      One sampling interval: every symbol's return over the interval that just closed (0 for a symbol that did not move — that IS its return). A vector containing any non-finite entry is dropped entirely: a partial update would break positive-semidefiniteness, so a bad print on one symbol must not corrupt the whole matrix.
      Parameters:
      returns - length >= symbols; entries beyond the basket are ignored

    • covariance

      public double covariance(int i, int j)
      Decayed covariance between two symbols (order-free).

    • variance

      public double variance(int i)
      Decayed variance of one symbol.

    • volatility

      public double volatility(int i)
      Decayed volatility (per √interval), 0 until learned.

    • correlation

      public double correlation(int i, int j)
      Decayed correlation in [-1, 1]; 0 while either variance is 0.

    • portfolioVariance

      public double portfolioVariance(double[] weights)
      w'Σw: portfolio variance of the (signed) weight vector.

    • marginalContribution

      public double marginalContribution(double[] weights, double[] out)
      Marginal contribution to portfolio risk: out[i] = wᵢ·(Σw)ᵢ / (w'Σw) — the fraction of total basket variance symbol i's position is responsible for (contributions sum to 1; a natural hedge contributes negatively). All zeros while the portfolio variance is not positive — no risk picture, no signal.
      Returns:
      the portfolio variance w'Σw, so a caller gating on "is there a risk picture?" needs exactly one call — a separate portfolioVariance(double[]) probe would repeat the O(n²) pass this method already makes

    • minVarianceHedgeRatio

      public double minVarianceHedgeRatio(int target, int hedge)
      The live minimum-variance hedge ratio: hedge target with cov(target,hedge)/var(hedge) units of hedge — the streaming sibling of hedging.MinimumVarianceHedge. 0 while the hedge instrument's variance is unlearned.

    • symbols

      public int symbols()

    • samples

      public long samples()

    • writeState

      public void writeState(DataOutput out) throws IOException
      Persists the learned matrix — see persist.Checkpoint.
      Throws:
      IOException

    • readState

      public void readState(DataInput in) throws IOException
      Restores the matrix. Throws on a basket-size or version mismatch.
      Throws:
      IOException