Gerber IQ covariance (a)

PortfolioOptimisers.BaseGerberIQCovariance — Type
abstract type BaseGerberIQCovariance <: BaseGerberCovariance

Abstract supertype for all Gerber IQ covariance estimators.

Every concrete or abstract type that implements a Gerber IQ covariance estimator must subtype BaseGerberIQCovariance. Gerber IQ is the Gerber Information Quality statistic.

The family adds two things to BaseGerberCovariance. It gives a co-movement the weight of the channel of the return plane that the co-movement falls in, not a count of one. It also discounts a co-movement by its age. GerberCovarianceAlgorithm states the Gerber statistic that these estimators reduce to, and this docstring does not repeat it.

Interfaces

A new subtype must follow the interface of AbstractCovarianceEstimator.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.
source
PortfolioOptimisers.GerberIQCovarianceAlgorithm — Type
abstract type GerberIQCovarianceAlgorithm <: AbstractAlgorithm

Abstract supertype for all Gerber IQ squeezing templates.

Every concrete or abstract type that implements a Gerber IQ squeezing template must subtype GerberIQCovarianceAlgorithm. A subtype goes in the kind field of a GerberIQCovariance estimator.

A squeezing template cuts the plane of the returns of two assets into channels. It gives the weight of a co-movement in each channel. The library ships the three templates of the source. In the order of the number of channels, they are:

Interfaces

To add a squeezing template, subtype GerberIQCovarianceAlgorithm with its boundaries and its weights as fields. Then implement these methods:

gerber_iq_weight

  • gerber_iq_weight(xi::Number, xj::Number, axi::Number, axj::Number, sci::Number, scj::Number, kind::MyGerberIQ) -> Number: The weight of one co-movement, from the channel of the template that the co-movement falls in.

Arguments

  • xi, xj: Returns of assets i and j.
  • axi, axj: Absolute returns of assets i and j.
  • sci, scj: Scaling factors of assets i and j.
  • kind: The instance of the subtype.

Returns

  • res::Number: Weight of the co-movement.

gerber_iq_assert_c_d

  • gerber_iq_assert_c_d(c::Number, kind::MyGerberIQ) -> Nothing: Compares the noise threshold c with each boundary of the template. It raises a DomainError when c is above a boundary.

Arguments

  • c: Noise threshold.
  • kind: The instance of the subtype.

Returns

  • nothing. The caller uses the method for its check alone.

clamp_gerber_iq_n (optional)

  • clamp_gerber_iq_n(kind::MyGerberIQ, alg::GerberCovarianceAlgorithm) -> MyGerberIQ: The template, with each weight lowered that alg needs lower. The fall-through returns kind unchanged.

Arguments

Returns

  • kind::MyGerberIQ: A new template, or kind when no weight needs a clamp.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Sections 3.3.3 to 3.3.5.
source
PortfolioOptimisers.clamp_gerber_iq_n — Function
clamp_gerber_iq_n(
    kind::GerberIQCovarianceAlgorithm,
    args...
) -> PartialGerberIQ{<:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number}

Returns a Gerber IQ squeezing template unchanged, for each pair of a template and a marker that needs no clamp.

Every pair of a template and a GerberCovarianceAlgorithm marker that this file does not clamp comes to this method. Two cases come to it:

  • Gerber0 and Gerber1 divide the net weighted count by a sum of the same weights. So the statistic is in $[-1, 1]$ for every template.
  • Under Gerber2, BasicGerberIQ needs no clamp. Its diagonal weights are 1 and n, and its one mixed weight n^2 is at most their geometric mean $\sqrt{n}$.

Arguments

Returns

  • kind: The input kind instance.

Related

source
clamp_gerber_iq_n(
    alg::PartialGerberIQ,
    _::Gerber2
) -> PartialGerberIQ{<:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number}

Lowers the mixed-magnitude weights of a PartialGerberIQ template, so that the Gerber2 statistic stays inside [-1, 1]. It does not make the matrix positive definite. The pdm field of the estimator does that.

Under Gerber2, the entry of a pair is the net sum pos - neg, divided by the geometric mean of the two diagonal projections of the pair. A projection compares an asset with itself. So the projection is always concordant, and it gives a same-magnitude weight. The Internet Appendix of [36] states a condition for a bound of one. Each weight that joins two distinct magnitude classes must be at most the geometric mean of the two same-magnitude weights of those classes. The source proves that the condition is necessary and sufficient for its own alternative statistic, in Equations A1 to A9.

That statistic sums its diagonal projections over the observations on which both assets cross. The Gerber2 of the library sums them over the observations on which the one asset crosses, which is a larger set. So for the library, the Cauchy-Schwarz inequality makes the condition sufficient. The condition stays necessary for the template as a whole, because a sample in which the two assets always cross together gives the denominator of the source. Six of the ten weights join two classes, and this method lowers each of them to its bound. With n1 = n4 = 0.2, an unclamped n7 = 1.0 gives 5.0, and the clamp makes it 1.0.

The four discordant weights need a case split. The template compares a concordant pair with dcp and dcn, and a discordant pair with ddp and ddn. So a return beyond a discordant boundary is not always beyond the concordant boundary that sets its diagonal class. When the two boundaries differ, the method uses the smaller of the two candidate weights. That bound holds for either class.

Note

The clamp is a necessary and sufficient condition on the template, and the statistic needs no other condition. sc needs no restriction, because Gerber2 computes its denominator in the units of the pair. The shipped defaults are exactly on the bound, so the clamp does not change them.

Mathematical definition

Let $h^{+}$ and $l^{+}$ be the diagonal weights of the two positive classes that a discordant channel can join. Let $h^{-}$ and $l^{-}$ be the diagonal weights of the two negative classes.

\[\begin{align} h^{+} &= \begin{cases} n_{4} & \delta_{d}^{+} \geq \delta_{c}^{+} \\ \min(n_{1}, n_{4}) & \text{otherwise} \end{cases}\,, &l^{+} &= \begin{cases} n_{1} & \delta_{d}^{+} \leq \delta_{c}^{+} \\ \min(n_{1}, n_{4}) & \text{otherwise} \end{cases}\,, \end{align}\]

The rule for $h^{-}$ and $l^{-}$ is the same, with $n_{5}$, $n_{2}$, $\delta_{d}^{-}$ and $\delta_{c}^{-}$. The six bounds are:

\[\begin{align} n_{7} &\leftarrow \min\left(n_{7},\, \sqrt{n_{1} n_{4}}\right)\,, & n_{8} &\leftarrow \min\left(n_{8},\, \sqrt{n_{2} n_{5}}\right)\,, \\ n_{6} &\leftarrow \min\left(n_{6},\, \sqrt{h^{+} h^{-}}\right)\,, & n_{9} &\leftarrow \min\left(n_{9},\, \sqrt{h^{+} l^{-}}\right)\,, \\ n_{10} &\leftarrow \min\left(n_{10},\, \sqrt{l^{+} h^{-}}\right)\,, & n_{3} &\leftarrow \min\left(n_{3},\, \sqrt{l^{+} l^{-}}\right)\,. \end{align}\]

Where:

  • $n_{1}$, $n_{4}$: Small and large positive concordant weights.
  • $n_{2}$, $n_{5}$: Small and large negative concordant weights.
  • $\delta_{c}^{\pm}$, $\delta_{d}^{\pm}$: The concordant boundaries dcp and dcn, and the discordant boundaries ddp and ddn.

Algorithm

  1. Resolve the four discordant diagonal weights hip, lop, hin and lon from the two pairs of boundaries.
  2. Replace n7 and n8, the weights of the two mixed concordant channels, with their bounds when they are above them. Each bound is the geometric mean of the two weights that the channel joins.
  3. Replace n3, n6, n9 and n10, the weights of the four discordant channels, in the same way. Each bound uses the resolved weights that the channel joins.
  4. Return a new PartialGerberIQ with the six lowered weights and with each other field unchanged.

Arguments

Returns

  • kind::PartialGerberIQ: A new template. The method allocates and never writes into alg.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Internet Appendix, Equations A1 to A9.
source
clamp_gerber_iq_n(
    alg::FullGerberIQ,
    _::Gerber2
) -> FullGerberIQ{_A, _B, _C, _D, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number, <:Number} where {_A, _B, _C, _D}

Lowers the mixed-magnitude weights of a FullGerberIQ template, so that the Gerber2 statistic stays inside [-1, 1]. It does not make the matrix positive definite. The pdm field of the estimator does that.

Under Gerber2, the entry of a pair is the net sum pos - neg, divided by the geometric mean of the two diagonal projections of the pair. A projection compares an asset with itself. So both returns fall in the same magnitude class, and the co-movement is always concordant. Thus exactly six of the twenty-one weights are on the diagonal, one for each class. They are n11, n4, n1, n2, n5 and n12. Each of the other fifteen weights joins two distinct classes, one weight for each unordered pair of classes, and C(6, 2) = 15. The discordant channels are among the fifteen.

The Internet Appendix of [36] states a condition for a bound of one. Each of the fifteen weights must be at most the geometric mean of the diagonal weights of the two classes that it joins. The source proves that the condition is necessary and sufficient for its own alternative statistic, in Equations A1 to A9. The Gerber2 of the library sums its projections over a larger set of observations. So for the library, the Cauchy-Schwarz inequality makes the condition sufficient, and the condition stays necessary for the template as a whole.

This method lowers all fifteen weights to that bound. A discordant channel follows the same rule, because both classes that it joins have a diagonal weight. A FullGerberIQ with n1 = n11 = 0.1 and n15 = 1.0 gives 10.0 with no clamp, and 1.0 with the clamp.

Note

The clamp is a necessary and sufficient condition on the template, and the statistic needs no other condition. sc needs no restriction, because Gerber2 computes its denominator in the units of the pair. Each shipped default meets the bound, so the clamp does not change a default.

Mathematical definition

Let $n_{k}$ be one of the fifteen mixed weights. Let $a$ and $b$ be the two classes that its channel joins, with the diagonal weights $n_{a}$ and $n_{b}$. Then:

\[\begin{align} n_{k} &\leftarrow \min\left(n_{k},\, \sqrt{n_{a} n_{b}}\right)\,. \end{align}\]

The fifteen channels, and the pair of classes that each channel joins, are:

\[\begin{align} n_{13} &: (n_{11}, n_{12})\,, & n_{14} &: (n_{4}, n_{11})\,, & n_{15} &: (n_{1}, n_{11})\,, \\ n_{16} &: (n_{2}, n_{12})\,, & n_{17} &: (n_{5}, n_{12})\,, & n_{18} &: (n_{2}, n_{11})\,, \\ n_{19} &: (n_{5}, n_{11})\,, & n_{20} &: (n_{4}, n_{12})\,, & n_{21} &: (n_{1}, n_{12})\,, \\ n_{3} &: (n_{1}, n_{2})\,, & n_{6} &: (n_{4}, n_{5})\,, & n_{7} &: (n_{1}, n_{4})\,, \\ n_{8} &: (n_{2}, n_{5})\,, & n_{9} &: (n_{4}, n_{2})\,, & n_{10} &: (n_{1}, n_{5})\,. \end{align}\]

Where:

  • $n_{1}$, $n_{4}$, $n_{11}$: Small, moderate and large positive concordant weights.
  • $n_{2}$, $n_{5}$, $n_{12}$: Small, moderate and large negative concordant weights.

Algorithm

  1. Read the six diagonal weights n1, n2, n4, n5, n11 and n12 from alg.
  2. Replace each of the fifteen mixed weights with its bound when it is above it. The table above gives the two classes of each bound.
  3. Return a new FullGerberIQ with the fifteen lowered weights, and with the six diagonal weights and the four boundaries unchanged.

Arguments

Returns

  • kind::FullGerberIQ: A new template. The method allocates and never writes into alg.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Internet Appendix, Equations A1 to A9.
source
PortfolioOptimisers.GerberIQEpsEstimator — Type
abstract type GerberIQEpsEstimator <: AbstractEstimator

Abstract supertype for all estimators of the delay of the Gerber IQ decay.

Every concrete or abstract type that implements an estimator of the Gerber IQ delay must subtype GerberIQEpsEstimator.

A subtype computes the delay of the temporal vector of the source. The delay is the number of periods before the last observation in which a co-movement keeps its full weight. The source names it $\varepsilon$, and it leaves the value to expert judgement or to an outer optimisation. The library adds a default formula, which gerber_iq_eps states.

Interfaces

To add a delay estimator, subtype GerberIQEpsEstimator and implement this method:

gerber_iq_eps

  • gerber_iq_eps(e::MyGerberIQEps, X::MatNum) -> Number: The delay, in periods, computed from X. A subtype that implements no method raises an ArgumentError that names the subtype.

Arguments

  • e: The instance of the subtype.
  • X: Returns matrix, observations × assets.

Returns

  • eps::Number: The delay.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.4.2.
source
PortfolioOptimisers.gerber_iq_eps — Function
gerber_iq_eps(e::Number, ::MatNum) -> Number
gerber_iq_eps(e::Function, X::MatNum) -> Number
gerber_iq_eps(e::Nothing, X::MatNum) -> Number
gerber_iq_eps(e::GerberIQEpsEstimator, X::MatNum)

Returns the delay e of the Gerber IQ decay. A rule in e computes the delay from X.

Mathematical definition

The default, nothing, computes the delay from the shape of the returns matrix alone.

\[\begin{align} \varepsilon &= \mathrm{round}\left(T - \frac{T}{N}\right)\,. \end{align}\]

Where:

  • $\varepsilon$: Delay. A co-movement of age $T - k$ keeps its full weight when $T - k \leq \varepsilon$.
  • $T$: Number of observations.
  • $N$: Number of assets.

The decay discounts an observation only when its index satisfies $k < T - \varepsilon$. So this default discounts about the oldest $T/N$ observations, and the other observations keep their full weight. The formula is the library's, not the formula of the source. The source states only that the delay is a whole number of periods, no larger than the lookback duration. It leaves the value to expert judgement or to an outer optimisation. Table 2 of [36] sets the delay to zero in the study of the source.

Algorithm

  1. Return the number unchanged when e is a Number.
  2. Call e(X) when e is a Function, and return its result.
  3. Read T and N from size(X) when e is nothing, and return round(Int, T - T / N).
  4. Throw an ArgumentError for a GerberIQEpsEstimator that implements no method of its own.

Arguments

  • e: The delay, or the rule that computes it.
    • ::Number: The method returns the number unchanged.
    • ::Function: A function that takes the data matrix X and returns a Number.
    • ::Nothing: The default. It returns round(Int, T - T / N), where T is the number of rows of X and N the number of columns.
    • ::GerberIQEpsEstimator: The fallback of the family, for a subtype that implements no method of its own. It always throws.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.

Validation

  • A GerberIQEpsEstimator subtype that implements no method raises an ArgumentError that names the subtype. Without the refusal, such a subtype gets the default delay in silence.

Returns

  • e::Number: The delay of the decay. The decay does not discount an observation that is no older than e periods. The delay is not the window duration $\tau$ of the source, which the estimator does not expose. The estimator reads the whole matrix, and the decay discounts its oldest rows.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.4.2, Equation 5.
source
PortfolioOptimisers.GerberIQGammaEstimator — Type
abstract type GerberIQGammaEstimator <: AbstractEstimator

Abstract supertype for all estimators of the rate of the Gerber IQ decay.

Every concrete or abstract type that implements an estimator of the Gerber IQ decay rate must subtype GerberIQGammaEstimator.

A subtype computes the decay rate of the temporal vector of the source. The decay applies this rate to a co-movement that is older than the delay. The source names the rate $\gamma$ and requires it to be positive. It leaves the value to expert judgement or to an outer optimisation. The library adds a default formula, which gerber_iq_gamma states.

Interfaces

To add a decay rate estimator, subtype GerberIQGammaEstimator and implement this method:

gerber_iq_gamma

  • gerber_iq_gamma(y::MyGerberIQGamma, X::MatNum) -> Number: The decay rate, computed from X. A subtype that implements no method raises an ArgumentError that names the subtype.

Arguments

  • y: The instance of the subtype.
  • X: Returns matrix, observations × assets.

Returns

  • gamma::Number: The decay rate.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.4.3.
source
PortfolioOptimisers.gerber_iq_gamma — Function
gerber_iq_gamma(y::Number, ::MatNum) -> Number
gerber_iq_gamma(y::Function, X::MatNum) -> Number
gerber_iq_gamma(y::Nothing, X::MatNum) -> Number
gerber_iq_gamma(y::GerberIQGammaEstimator, X::MatNum)

Returns the rate y of the Gerber IQ decay. A rule in y computes the rate from X.

Mathematical definition

The default, nothing, computes the decay rate from the number of assets alone.

\[\begin{align} \gamma &= \frac{\ln 2}{N}\,. \end{align}\]

Where:

  • $\gamma$: Decay rate. A larger rate gives an old co-movement a smaller weight.
  • $N$: Number of assets.

The default is a half-life of $N$ periods. After the delay, the weight of a co-movement becomes half for every $N$ observations, because $\exp(-\gamma N) = 1/2$. The formula is the library's, not the formula of the source. The source requires only $\gamma > 0$, and it leaves the value to expert judgement or to an outer optimisation. Table 2 of [36] relates the rate to the half-life by $T_{1/2} = \ln 2 / \gamma$. This default uses that relation with $T_{1/2} = N$.

Algorithm

  1. Return the number unchanged when y is a Number.
  2. Call y(X) when y is a Function, and return its result.
  3. Return log(2) / size(X, 2) when y is nothing.
  4. Throw an ArgumentError for a GerberIQGammaEstimator that implements no method of its own.

Arguments

  • y: The decay rate, or the rule that computes it.
    • ::Number: The method returns the number unchanged.
    • ::Function: A function that takes the data matrix X and returns a Number.
    • ::Nothing: The default. It returns log(2) / size(X, 2).
    • ::GerberIQGammaEstimator: The fallback of the family, for a subtype that implements no method of its own. It always throws.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.

Validation

  • A GerberIQGammaEstimator subtype that implements no method raises an ArgumentError that names the subtype. Without the refusal, such a subtype gets the default rate in silence.

Returns

  • gamma::Number: The rate of the decay.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.4.3, Equation 5, and Table 2.
source
PortfolioOptimisers.GerberIQScalerEstimator — Type
abstract type GerberIQScalerEstimator <: AbstractEstimator

Abstract supertype for all threshold scalers of the Gerber IQ statistic.

Every concrete or abstract type that implements a Gerber IQ threshold scaler must subtype GerberIQScalerEstimator.

A subtype sets the units of the thresholds of a pair of assets. The source names four choices:

  • The volatility of each asset.
  • The mean of the two volatilities.
  • The larger of the two volatilities.
  • The smaller of the two volatilities.

The library ships the first choice as AssetVolatilityGerberIQScaler. nothing in the place of a scaler is the second choice, the default. The Function arm of GerberIQScaler gives the other two.

Interfaces

To add a scaler, subtype GerberIQScalerEstimator and implement this method:

gerber_iq_scaling

  • gerber_iq_scaling(sca::MyGerberIQScaler, sdi::Number, sdj::Number) -> (Number, Number): The scales of the thresholds of assets i and j, computed from their standard deviations. A subtype that implements no method raises an ArgumentError that names the subtype.

Arguments

  • sca: The instance of the subtype.
  • sdi, sdj: Standard deviations of assets i and j.

Returns

  • (sci, scj)::Tuple{Number, Number}: The scales of assets i and j.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.3.1, Section 4 and Table 2.
source
PortfolioOptimisers.GerberIQDecayEstimator — Type
abstract type GerberIQDecayEstimator <: AbstractEstimator

Abstract supertype for all Gerber IQ estimators that discount an observation by its age.

Every concrete or abstract type that implements a Gerber IQ decay must subtype GerberIQDecayEstimator.

A subtype is a non-increasing function of age. The source states that the age penalty can be any non-increasing function, and it uses the exponential form. ExpGerberIQDecay implements that form. A subtype is configuration, so it holds its parameters and never a Result. Two methods make a subtype work. regenerate_decay gives a value to each parameter that the caller did not set, and the functor returns the weight of one observation.

Interfaces

To add a Gerber IQ decay, subtype GerberIQDecayEstimator with its parameters as fields. Then implement these methods:

regenerate_decay

  • regenerate_decay(decay::GerberIQDecayEstimator, X::AbstractMatrix) -> GerberIQDecayEstimator: The decay with a number in each parameter. The method computes from X each parameter that the caller did not set.

Arguments

  • decay: The decay estimator to resolve.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.

Returns

  • decay::GerberIQDecayEstimator: An instance of the subtype with a number in each parameter. It can be decay itself when each parameter is already a number.

Functor

  • (decay::GerberIQDecayEstimator)(T::Number, k::Number) -> Number: The weight of observation k of T.

Arguments

  • T::Number: The number of observations.
  • k::Number: The index of the observation.

Returns

  • d::Number: The weight of observation k of T.

Examples

This example defines a Gaussian decay estimator.

julia> struct GaussianDecay{T} <: PortfolioOptimisers.GerberIQDecayEstimator           a::T           function GaussianDecay(a::Union{Nothing, Number})               if isa(a, Number)                   PortfolioOptimisers.@argcheck(a >= 0,                                                 DomainError(a, "`a` must be non-negative"))               end               return new{typeof(a)}(a)           end       endjulia> function GaussianDecay(; a::Union{Nothing, Number} = nothing)           return GaussianDecay(a)       endGaussianDecayjulia> function PortfolioOptimisers.regenerate_decay(decay::GaussianDecay{<:Number},                                                     ::AbstractMatrix)           return decay       endjulia> function PortfolioOptimisers.regenerate_decay(decay::GaussianDecay{Nothing},                                                     X::AbstractMatrix)           T = size(X, 1)           return GaussianDecay(; a = inv(log(T)))       endjulia> function (decay::GaussianDecay)(T::Number, k::Number)           m = T - k + 1           return exp(-m^2 / (2 * decay.a^2))       endjulia> cor(GerberIQCovariance(; decay = GaussianDecay()), [1.0 2.0; 0.3 0.7; 0.5 1.1])2×2 Matrix{Float64}: 1.0  1.0 1.0  1.0julia> cov(GerberIQCovariance(; decay = GaussianDecay()), [1.0 2.0; 0.3 0.7; 0.5 1.1])2×2 Matrix{Float64}: 0.13      0.240069 0.240069  0.443333

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.4.3.
source
PortfolioOptimisers.AssetVolatilityGerberIQScaler — Type
struct AssetVolatilityGerberIQScaler <: GerberIQScalerEstimator

Scales the thresholds of each asset by the volatility of that asset.

Each asset keeps its own units. So the scaler measures asset $i$ against $\sigma_i$ and asset $j$ against $\sigma_j$. Kendall's tau and the Gerber statistic use the same convention. With this choice, the Gerber IQ statistic reduces to the Gerber statistic, and gerber_IQ states that reduction. The default nothing gives both assets the mean of the two volatilities.

Mathematical definition

\[\begin{align} (s_i,\, s_j) &= (\sigma_i,\, \sigma_j)\,. \end{align}\]

Where:

  • $s_i$, $s_j$: Threshold scaling factors of the pair.
  • $\sigma_i$: Standard deviation of asset $i$.

Constructors

AssetVolatilityGerberIQScaler() -> AssetVolatilityGerberIQScaler

Examples

julia> AssetVolatilityGerberIQScaler()AssetVolatilityGerberIQScaler()

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.3.1 and Section 4.
source
PortfolioOptimisers.gerber_iq_scaling — Function
gerber_iq_scaling(sca::AssetVolatilityGerberIQScaler, sdi::Number, sdj::Number) -> (Number, Number)
gerber_iq_scaling(sca::Nothing, sdi::Number, sdj::Number) -> (Number, Number)
gerber_iq_scaling(sca::Function, sdi::Number, sdj::Number) -> (Number, Number)
gerber_iq_scaling(sca::GerberIQScalerEstimator, sdi::Number, sdj::Number)

Computes the scaling factors of the thresholds of a pair of assets in the Gerber IQ statistic.

The statistic multiplies each threshold of the pair by the factor that this function returns for the axis of the threshold. The thresholds are the noise threshold c and each boundary of the squeezing template. So the scaler sets the units in which a return is large.

A scaler is pair-separable when its first factor uses sdi alone and its second factor uses sdj alone. The thresholds of an asset are then the same for every partner. AssetVolatilityGerberIQScaler is pair-separable. The default nothing is not, because the mean of the pair changes with sdj. A Function can be either. Every scaler is safe under every marker. Gerber2 computes its denominator in the units of the pair through iq_add_diagonal. So when a scaler changes the class of an asset, the numerator and the denominator change together.

Mathematical definition

\[\begin{align} (s_i,\, s_j) &= \begin{cases} (\sigma_i,\, \sigma_j) & \text{AssetVolatilityGerberIQScaler} \\ \left(\dfrac{\sigma_i + \sigma_j}{2},\, \dfrac{\sigma_i + \sigma_j}{2}\right) & \text{nothing} \end{cases}\,. \end{align}\]

Where:

  • $s_i$, $s_j$: Threshold scaling factors of the pair.
  • $\sigma_i$: Standard deviation of asset $i$.

nothing gives both assets the same units, so a volatile asset and a quiet asset have the same absolute threshold. AssetVolatilityGerberIQScaler gives each asset its own units. The source names both choices.

Algorithm

  1. Return (sdi, sdj) unchanged for AssetVolatilityGerberIQScaler.
  2. Compute (sdi + sdj) / 2 once for nothing, and return it for both axes.
  3. Call sca(sdi, sdj) for a Function, and return its result.
  4. Throw an ArgumentError for any other GerberIQScalerEstimator.

Arguments

  • sca: The threshold scaler.

    • ::AssetVolatilityGerberIQScaler: The method returns sdi and sdj unchanged, so each asset has the units of its own volatility.
    • ::Nothing: The default. The method returns the mean of sdi and sdj for both assets.
    • ::Function: A function that takes sdi and sdj and returns the two scaling factors.
    • ::GerberIQScalerEstimator: The fallback of the family, for a subtype that implements no method of its own. It always throws.
  • sdi: Standard deviation of asset i.

  • sdj: Standard deviation of asset j.

Validation

  • A GerberIQScalerEstimator subtype that implements no method raises an ArgumentError that names the subtype. Without the refusal, such a subtype gets the pair mean in silence.

Returns

  • scai::Number: The scaling factor of asset i.
  • scaj::Number: The scaling factor of asset j.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.3.1, Section 4 and Table 2.
source
PortfolioOptimisers.ExpGerberIQDecay — Type
struct ExpGerberIQDecay{__T_e, __T_y} <: GerberIQDecayEstimator

Exponential Gerber IQ temporal decay.

This decay is the age penalty of the source, Equation 5 of [36]. The age $m = T - k$ starts at the most recent observation. A co-movement that is no older than e periods keeps its full weight. The decay discounts an older co-movement at the rate y for each more period. Each field can be nothing. regenerate_decay then computes it from the returns matrix before the statistic runs.

Fields

  • e: Delay. A co-movement that is no older than e periods keeps its full weight. The source names it $\varepsilon$.
  • y: Decay rate. The decay discounts a co-movement at this rate for each period of age after e. The source names it $\gamma$.

Constructors

ExpGerberIQDecay(e::Option{<:GerberIQEps} = nothing,                 y::Option{<:GerberIQGamma} = nothing)

Keywords correspond to the struct's fields.

Validation

The constructor does not check a field that is not a Number, because that field is a rule, not a value. regenerate_decay resolves the rule, and this constructor then checks the resolved instance.

Functors

(decay::ExpGerberIQDecay)(T::Number, k::Number) -> Number

Computes the exponential decay of the Gerber IQ statistic.

Warning

Call the functor only when e and y are both numbers. Otherwise, call regenerate_decay first. A field that is nothing makes the functor raise a MethodError.

Mathematical definition

\[\begin{align} d &= \exp\left[-y \max(0, T - k - e)\right]\,. \end{align}\]

Where:

  • $T$: Number of observations.
  • $k$: Index of the observation.
  • $e$: Delay, the field e of the ExpGerberIQDecay.
  • $y$: Decay rate, the field y of the ExpGerberIQDecay.
  • $d$: Decay factor.

Arguments

  • T: Number of observations.
  • k: Index of the observation.

Returns

  • d: The decay factor.

Examples

julia> ExpGerberIQDecay()ExpGerberIQDecay  e ┼ nothing  y ┴ nothing

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.5, Equation 5.
source
PortfolioOptimisers.regenerate_decay — Function
regenerate_decay(decay::ExpGerberIQDecay, X::AbstractMatrix) -> ExpGerberIQDecay
regenerate_decay(decay::GerberIQDecayEstimator, X::AbstractMatrix) -> ExpGerberIQDecay

Returns a decay with a number in each parameter. The function computes from X each parameter that is not a number.

The function allocates, and it never writes into its argument. A decay estimator is configuration, and the library does not change it. So a resolved parameter goes into a new ExpGerberIQDecay. The function allocates nothing for an ExpGerberIQDecay whose two fields are already numbers. It then returns the same object. The caller must use the returned value, because the argument keeps the parameters that are not numbers.

Algorithm

  1. Return decay unchanged when it is an ExpGerberIQDecay whose e and y are both a Number.
  2. Otherwise resolve the delay e with gerber_iq_eps. For an ExpGerberIQDecay, the function gives it the field e. For each other subtype, it gives it nothing.
  3. Resolve the decay rate y in the same way with gerber_iq_gamma.
  4. Return a new ExpGerberIQDecay with e and y.

The fall-through does not know the fields of another subtype. So at step 2 it computes both parameters from X alone, and it returns an ExpGerberIQDecay in place of the subtype. A subtype that must keep its own form implements this function, as the # Interfaces section of GerberIQDecayEstimator states.

Arguments

  • decay: The decay estimator to resolve.
    • ::ExpGerberIQDecay: When both parameters are numbers, the function returns decay. Otherwise it returns a new ExpGerberIQDecay with the resolved parameters.
    • ::GerberIQDecayEstimator: The fall-through. It computes e and y from X with gerber_iq_eps and gerber_iq_gamma, and gives nothing as their first argument. A subtype of GerberIQDecayEstimator that implements no method gets this fall-through.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.

Returns

  • decay::ExpGerberIQDecay: The decay, with a number in each parameter.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.4.
source
PortfolioOptimisers.BasicGerberIQ — Type
struct BasicGerberIQ{__T_d, __T_n} <: GerberIQCovarianceAlgorithm

Squeezing template with one boundary and one weight for the whole return plane.

This template is the reduced template of the source. The results of the source use it, and it is the default of GerberIQCovariance.

Mathematical definition

\[\begin{align} \eta_{t,\,i,\,j} &= \begin{cases} 1 & d s_i \leq \lvert x_{t,\,i} \rvert \; \text{and} \; d s_j \leq \lvert x_{t,\,j} \rvert \\ n & \lvert x_{t,\,i} \rvert < d s_i \; \text{and} \; \lvert x_{t,\,j} \rvert < d s_j \\ n^2 & \text{otherwise} \end{cases}\,. \end{align}\]

Where:

  • $\eta_{t,\,i,\,j}$: Squeezing weight of the co-movement of assets $i$ and $j$ at observation $t$.
  • $x_{t,\,i}$: Return of asset $i$ at observation $t$.
  • $s_i$, $s_j$: Threshold scaling factors of the pair.
  • $d$: Significance threshold.
  • $n$: Squeezing weight.

The three cases are the tail, the body and the wing of the source. In the tail both returns are large, and in the body both returns are small. In the wing, one return is large and one return is small. Because $0 \leq n \leq 1$, the weights obey $n^2 \leq n \leq 1$. So a co-movement of two similar magnitudes counts no less than a co-movement of two different magnitudes. That order is the judgement of the source, and a template with one free weight cannot give a different order.

Section 3.3.5 of [36] gives the weights 1, η and η² to the tail, the body and the wing, with 0 ≤ η ≤ 1. Table 2 gives 2 to 3 as the typical range of the boundary. The defaults d = 2 and n = 0.5 are the choice of the library in those ranges. The figures of the source show no weight on the branches of the noise zone, where one asset is inside the noise threshold. Section 2 states only that a method can use such data or not. The library gives a co-movement there the weight of the channel that the same rule selects, as the diagram shows.

The body case happens only when $c < d$. The statistic drops a co-movement with both returns inside the noise threshold before the template. So at $c = d$ the band of n is empty, and only $1$ and $n^2$ occur.

The diagram shows the regions of BasicGerberIQ for c = 1 and d = 3.

  • A dashed line is the noise threshold c on one axis.
  • A co-movement in a dashed band has one return inside the noise zone. Gerber0 ignores it. Gerber1 adds it to the neutral sum, and Gerber2 adds the projection of the other asset to its denominator.
  • The statistic always drops a co-movement in the square around r0, where both returns are inside the noise zone.
  • A thin line is the zero of an axis.
  • A heavy line is a boundary of the template.
  • The label of a region is the weight of a co-movement in that region.
            4 ┬─────┰───────────┬─────┬─────┬───────────┰─────┐     ┌────    │  1  ┃    n^2    ╎     │     ╎    n^2    ┃  1  │  d ─┤      3 ┾━━━━━╋━━━━━━━━━━━┿━━━━━┿━━━━━┿━━━━━━━━━━━╋━━━━━┥     └────    │     ┃           ╎     │     ╎           ┃     │            2 ┤ n^2 ┃     n     ╎     │     ╎     n     ┃ n^2 │              │     ┃           ╎     │     ╎           ┃     │     ┌────  1 ┼╌╌╌╌╌╂╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┴╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╂╌╌╌╌╌┤     │        │     ┃           ╎           ╎           ┃     │ 2c ─┤ r_j  0 ┼─────╂───────────┤    r0     ├───────────╂─────┤     │        │     ┃           ╎           ╎           ┃     │     └──── -1 ┼╌╌╌╌╌╂╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┬╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╂╌╌╌╌╌┤              │     ┃           ╎     │     ╎           ┃     │           -2 ┤ n^2 ┃     n     ╎     │     ╎     n     ┃ n^2 │     ┌────    │     ┃           ╎     │     ╎           ┃     │  d ─┤     -3 ┾━━━━━╋━━━━━━━━━━━┿━━━━━┿━━━━━┿━━━━━━━━━━━╋━━━━━┥     └────    │  1  ┃    n^2    ┊     │     ╎    n^2    ┃  1  │           -4 ┼─────╀─────┬─────┼─────┼─────┼─────┬─────╀─────┤             -4    -3    -2    -1     0     1     2     3     4                                     r_i                 │     │        │           │        │     │                 └──┬──┘        └─────┬─────┘        └──┬──┘                    d                2c                 d

Fields

  • d: Significance threshold. A return that is d scaled units or more from zero is large. d has the units of the noise threshold c of GerberIQCovariance, and it must be at least c.
  • n: Squeezing weight, in [0, 1]. A co-movement of two large returns has the full weight of one. A co-movement of two small returns has the weight n, and a co-movement of one large and one small return has the weight n^2.

Constructors

BasicGerberIQ(; d::Number = 2.0, n::Number = 0.5)

Keywords correspond to the struct's fields.

Validation

Examples

julia> BasicGerberIQ()BasicGerberIQ  d ┼ Float64: 2.0  n ┴ Float64: 0.5

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.3.5, Figure 3.
source
PortfolioOptimisers.gerber_iq_assert_c_d — Function
gerber_iq_assert_c_d(c::Number, kind::BasicGerberIQ)

Checks that c <= kind.d, where c is the noise threshold and d is the significance threshold of a BasicGerberIQ.

The two parameters are on the same axis, in the same scaled units. c is the upper limit of the noise zone, and d is the lower limit of the significant zone. So the body of the template is the band c <= |x| < d. Section 3.3.2 of [36] defines the body of a quadrant by c < r* ≤ δ, which is the same band. When d is less than c, the band is empty. Each return outside the noise zone is then beyond d, and the template never selects the weight n.

Arguments

Validation

  • c <= kind.d, else a DomainError that names both values.

Returns

  • nothing. The caller uses the function for its check alone.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.3.2.
source
gerber_iq_assert_c_d(c::Number, kind::Union{PartialGerberIQ, FullGerberIQ}) -> Nothing

Checks that the noise threshold c is at most each boundary of a PartialGerberIQ or a FullGerberIQ.

c and each boundary are on the same axis, in the same scaled units. So c must be at most the innermost boundary. When a boundary is below c, the noise zone covers the band inside that boundary. The function checks each boundary in turn. The error names the boundary that fails, so the caller knows which of the four boundaries is wrong.

Arguments

Validation

  • c <= dcp, c <= dcn, c <= ddp and c <= ddn for a PartialGerberIQ, else a DomainError that names the boundary that fails.
  • c <= dp1, c <= dp2, c <= dn1 and c <= dn2 for a FullGerberIQ, else a DomainError that names the boundary that fails.

Returns

  • nothing. The caller uses the function for its check alone.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.3.2.
source
PortfolioOptimisers.gerber_iq_weight — Function
gerber_iq_weight(
    _::Number,
    _::Number,
    axi::Number,
    axj::Number,
    sci::Number,
    scj::Number,
    kind::BasicGerberIQ
) -> Any

Computes the weight of a co-movement from the channel of the BasicGerberIQ template that the co-movement falls in.

BasicGerberIQ states the closed form. The method does not read the signed returns, because the template is symmetric about both axes and uses the magnitudes alone.

Algorithm

  1. Scale the significance threshold to each axis, di = d * sci and dj = d * scj.
  2. Return one(n) when both absolute returns reach their scaled threshold.
  3. Return n when neither absolute return reaches it.
  4. Return n^2 otherwise. In this case, exactly one absolute return reaches its threshold.

Arguments

  • xi: Return of asset i. The method does not read it.
  • xj: Return of asset j. The method does not read it.
  • axi: Absolute return of asset i.
  • axj: Absolute return of asset j.
  • sci: Scaling factor of asset i.
  • scj: Scaling factor of asset j.
  • kind: The BasicGerberIQ template.

Returns

  • res::Number: Weight of the co-movement.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.3.5, Figure 3.
source
gerber_iq_weight(
    xi::Number,
    xj::Number,
    axi::Number,
    axj::Number,
    sci::Number,
    scj::Number,
    kind::PartialGerberIQ
) -> Any

Computes the weight of a co-movement from the channel of the PartialGerberIQ template that the co-movement falls in.

PartialGerberIQ states the channels. The method does not read the absolute returns, because this template uses the sign of each return as well as its size.

Algorithm

  1. Scale each of the four boundaries to each axis, to get the eight thresholds dcpi, dcni, ddpi, ddni and the four thresholds of asset j.
  2. Test the positive concordant quadrant from the largest channel. The result is n4 when both returns reach dcp, and n7 when one return reaches it and the other return is positive. The result is n1 when both returns are positive and below dcp.
  3. Test the negative concordant quadrant in the same way against dcn, for n5, n8 and n2.
  4. Test the two discordant quadrants against ddp and ddn. The result is n6 when both returns are beyond their boundaries, n9 or n10 when one return is beyond its boundary, and n3 when neither return is.
  5. Return zero(xi) when no channel matches. This happens only when a return is exactly zero.

The tests go from the largest channel inwards. The first match gives the result, so the method counts no co-movement twice.

Arguments

  • xi: Return of asset i.
  • xj: Return of asset j.
  • axi: Absolute return of asset i. The method does not read it.
  • axj: Absolute return of asset j. The method does not read it.
  • sci: Scaling factor of asset i.
  • scj: Scaling factor of asset j.
  • kind: The PartialGerberIQ template.

Returns

  • res::Number: Weight of the co-movement.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 2, Figure 1(b).
source
gerber_iq_weight(
    xi::Number,
    xj::Number,
    axi::Number,
    axj::Number,
    sci::Number,
    scj::Number,
    kind::FullGerberIQ
) -> Any

Computes the weight of a co-movement from the channel of the FullGerberIQ template that the co-movement falls in.

FullGerberIQ states the channels. The method does not read the absolute returns, because this template uses the sign of each return as well as its size.

Algorithm

  1. Scale each of the four boundaries to each axis, to get the eight thresholds dp1i, dp2i, dn1i, dn2i and the four thresholds of asset j.
  2. Test the six channels in which the return of asset i is large positive, for n11, n14, n15, n18, n19 and n13. The order of the return of asset j is large positive, moderate positive, small positive, small negative, moderate negative and large negative.
  3. Test the five other channels in which the return of asset i is moderate positive, for n4, n7, n9, n6 and n20.
  4. Test the four other channels in which the return of asset i is small positive, for n1, n3, n10 and n21.
  5. Test the three other channels in which the return of asset i is small negative, for n2, n8 and n16.
  6. Test the two other channels in which the return of asset i is moderate negative, for n5 and n17.
  7. Return n12 when both returns are large negative.
  8. Return zero(xi) when no channel matches. This happens only when a return is exactly zero.

Each test contains both orders of the pair, so the result is symmetric in the two returns. The tests go from the largest class inwards. The first match gives the result, so the method counts no co-movement twice. The method can return each of the twenty-one weights.

Arguments

  • xi: Return of asset i.
  • xj: Return of asset j.
  • axi: Absolute return of asset i. The method does not read it.
  • axj: Absolute return of asset j. The method does not read it.
  • sci: Scaling factor of asset i.
  • scj: Scaling factor of asset j.
  • kind: The FullGerberIQ template.

Returns

  • res::Number: Weight of the co-movement.

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.3.4, Figure 2.
source
PortfolioOptimisers.PartialGerberIQ — Type
struct PartialGerberIQ{__T_dcp, __T_dcn, __T_ddp, __T_ddn, __T_n1, __T_n2, __T_n3, __T_n4, __T_n5, __T_n6, __T_n7, __T_n8, __T_n9, __T_n10} <: GerberIQCovarianceAlgorithm

Squeezing template with four boundaries, one for each sign of a return in a concordant and in a discordant co-movement.

This template is the sixteen-channel template of the source. Its boundary vector has four independent components, and it has ten distinct weights. BasicGerberIQ has one boundary and one weight, and FullGerberIQ has thirty-six channels.

Mathematical definition

Every boundary is scaled onto its own axis before it is compared with a return.

\[\begin{align} \delta_{i} &= \delta\, s_i\,. \end{align}\]

Where:

  • $\delta$: One of the four boundaries dcp, dcn, ddp and ddn.
  • $\delta_{i}$: That boundary on the axis of asset $i$.
  • $s_i$: Threshold scaling factor of asset $i$.

The four boundaries cut the plane into sixteen channels. The plane is symmetric about the line $x_i = x_j$, so the sixteen channels have ten distinct weights, n1 to n10. The template uses the signed return, not its magnitude, so it separates a pair by sign and by size. It compares a concordant pair of positive returns with dcp, and a concordant pair of negative returns with dcn. It compares a discordant pair with ddp and ddn. A co-movement in no named channel has the weight zero, which happens only when a return is exactly zero.

The boundaries dcp, dcn, ddp and ddn are the four components of the boundary vector of Figure 1(b) of [36]. The weights n1 to n10 have the numbers of its ten weights, channel by channel. The source leaves each value to expert judgement or to an outer optimisation. So the defaults are the library's, and so are the geometric-mean defaults of the mixed weights.

The diagram shows the regions of PartialGerberIQ for c = 1, dcp = 2, ddn = 2, ddp = 3 and dcn = 3.

  • A dashed line is the noise threshold c on one axis.
  • A co-movement in a dashed band has one return inside the noise zone. Gerber0 ignores it. Gerber1 adds it to the neutral sum, and Gerber2 adds the projection of the other asset to its denominator.
  • The statistic always drops a co-movement in the square around r0, where both returns are inside the noise zone.
  • A thin line is the zero of an axis.
  • A heavy line is a boundary of the template.
  • The label of a region is the weight of a co-movement in that region.
                         ddn                     dcp                       ┌──┴──┐                 ┌──┴──┐                       │     │                 │     │            4 ┬───────────┰─────┬─────┬─────┬─────┰───────────┐     ┌────    │    n6     ┃ n9  ╎     │     ╎     ┃           │ddp ─┤      3 ┾━━━━━━━━━━━╋━━━━━┿━━━━━┥     ╎ n7  ┃    n4     │     └────    │           ┃     ╎     │     ╎     ┃           │ ────┐            2 ┤    n10    ┃ n3  ╎     ┝━━━━━┿━━━━━╋━━━━━━━━━━━┥     ├─ dcp              │           ┃     ╎     │     ╎ n1  ┃    n7     │ ────┘     ┌────  1 ┼╌╌╌╌╌╌╌╌╌╌╌╂╌╌╌╌╌┼╌╌╌╌╌┴╌╌╌╌╌┼╌╌╌╌╌╂╌╌╌╌╌╌╌╌╌╌╌┤     │        │           ┃     ╎           ╎     ┃           │ 2c ─┤ r_j  0 ┼─────┰─────┸─────┤    r0     ├─────┸─────┰─────┤     │        │     ┃           ╎           ╎           ┃     │     └──── -1 ┼╌╌╌╌╌╂╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌┬╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╂╌╌╌╌╌┤              │     ┃           ╎     │     ╎    n3     ┃ n9  │ ────┐           -2 ┤ n8  ┃    n2     ╎     ┝━━━━━┿━━━━━━━━━━━╋━━━━━┥     ├─ ddn     ┌────    │     ┃           ╎     │     ╎           ┃     │ ────┘dcn ─┤     -3 ┾━━━━━╋━━━━━━━━━━━┿━━━━━┥     ╎    n10    ┃ n6  │     └────    │ n5  ┃    n8     ╎     │     ╎           ┃     │           -4 ┼─────╀─────┬─────┼─────┼─────┼─────┬─────╀─────┤             -4    -3    -2    -1     0     1     2     3     4                                     r_i                 │     │        │           │        │     │                 └──┬──┘        └─────┬─────┘        └──┬──┘                   dcn               2c                ddp

Fields

  • dcp: Boundary of a concordant co-movement of two positive returns. A positive return at dcp or above is large.
  • dcn: Boundary of a concordant co-movement of two negative returns. A negative return at -dcn or below is large.
  • ddp: Boundary of the positive return of a discordant co-movement, for either asset. A positive return at ddp or above is large.
  • ddn: Boundary of the negative return of a discordant co-movement, for either asset. A negative return at -ddn or below is large.
  • n1: Weight of a concordant co-movement of two small positive returns.
  • n2: Weight of a concordant co-movement of two small negative returns.
  • n3: Weight of a discordant co-movement of a small positive return with a small negative return.
  • n4: Weight of a concordant co-movement of two large positive returns.
  • n5: Weight of a concordant co-movement of two large negative returns.
  • n6: Weight of a discordant co-movement of a large positive return with a large negative return.
  • n7: Weight of a concordant positive co-movement of a small return with a large one.
  • n8: Weight of a concordant negative co-movement of a small return with a large one.
  • n9: Weight of a discordant co-movement whose positive return is large and whose negative return is small.
  • n10: Weight of a discordant co-movement whose positive return is small and whose negative return is large.

Constructors

PartialGerberIQ(; dcp::Number = 2.0, dcn::Number = dcp, ddp::Number = dcp,                  ddn::Number = dcp, n1::Number = 0.5, n2::Number = n1,                  n3::Number = sqrt(n1 * n2), n4::Number = 1.0, n5::Number = n4,                  n6::Number = sqrt(n4 * n5), n7::Number = sqrt(n1 * n4),                  n8::Number = sqrt(n2 * n5), n9::Number = sqrt(n4 * n2),                  n10::Number = sqrt(n1 * n5))

Keywords correspond to the struct's fields.

Only the four diagonal weights have a free default. n1, n2, n4 and n5 are the weights of the four magnitude classes. The default of each of the other six weights is the geometric mean of the diagonal weights of the two classes that its channel joins. clamp_gerber_iq_n enforces that bound under Gerber2. So the default template meets the bound for all values of the four diagonal weights. The four boundaries are equal by default, so the case split of that method on ddp and dcp changes no default.

Validation

Examples

julia> PartialGerberIQ()PartialGerberIQ  dcp ┼ Float64: 2.0  dcn ┼ Float64: 2.0  ddp ┼ Float64: 2.0  ddn ┼ Float64: 2.0   n1 ┼ Float64: 0.5   n2 ┼ Float64: 0.5   n3 ┼ Float64: 0.5   n4 ┼ Float64: 1.0   n5 ┼ Float64: 1.0   n6 ┼ Float64: 1.0   n7 ┼ Float64: 0.7071067811865476   n8 ┼ Float64: 0.7071067811865476   n9 ┼ Float64: 0.7071067811865476  n10 ┴ Float64: 0.7071067811865476

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 2, Figure 1(b), and Section 3.3.2.
source
PortfolioOptimisers.FullGerberIQ — Type
struct FullGerberIQ{__T_dp1, __T_dp2, __T_dn1, __T_dn2, __T_n1, __T_n2, __T_n3, __T_n4, __T_n5, __T_n6, __T_n7, __T_n8, __T_n9, __T_n10, __T_n11, __T_n12, __T_n13, __T_n14, __T_n15, __T_n16, __T_n17, __T_n18, __T_n19, __T_n20, __T_n21} <: GerberIQCovarianceAlgorithm

Squeezing template with three magnitude classes for each sign of a return.

This template is the full template of the source, and the most general template of the family. Two boundaries on each side of zero put each return in a small, a moderate or a large class. So each axis has six bands, and the plane has thirty-six channels. The plane is symmetric about the line $x_i = x_j$, so the thirty-six channels have twenty-one distinct weights. The source states this count, and this type has twenty-one weight fields.

Mathematical definition

Every boundary is scaled onto its own axis before it is compared with a return.

\[\begin{align} \delta_{i} &= \delta\, s_i\,. \end{align}\]

Where:

  • $\delta$: One of the four boundaries dp1, dp2, dn1 and dn2.
  • $\delta_{i}$: That boundary on the axis of asset $i$.
  • $s_i$: Threshold scaling factor of asset $i$.

A return of asset $i$ is large positive at $dp1_i$ or above, moderate positive in $[dp2_i, dp1_i)$ and small positive in $(0, dp2_i)$. The three negative classes are the mirror about zero, with $dn2_i$ and $dn1_i$. The channel of a co-movement is the pair of classes of its two returns, and its weight is the field of that pair. A co-movement in no named channel has the weight zero, which happens only when a return is exactly zero.

Figure 2 of [36] shows the same thirty-six channels. The weights n1 to n21 have the numbers of its twenty-one weights, channel by channel. The four boundaries of the figure are these fields:

  • $\delta_{C^{+}}$, the inner positive boundary, is dp2.
  • $\delta_{D^{+}}$, the outer positive boundary, is dp1.
  • $\delta_{D^{-}}$, the inner negative boundary, is dn2.
  • $\delta_{C^{-}}$, the outer negative boundary, is dn1.

The source leaves each value to expert judgement or to an outer optimisation. So the defaults are the library's, and so are the geometric-mean defaults of the mixed weights.

The diagram shows the regions of FullGerberIQ for c = 1, dp2 = 2, dn2 = 2, dp1 = 3 and dn1 = 3. The constructor accepts the two boundaries of each sign in either order. It swaps them when necessary, so that dp1 >= dp2 and dn1 >= dn2.

  • A dashed line is the noise threshold c on one axis.
  • A co-movement in a dashed band has one return inside the noise zone. Gerber0 ignores it. Gerber1 adds it to the neutral sum, and Gerber2 adds the projection of the other asset to its denominator.
  • The statistic always drops a co-movement in the square around r0, where both returns are inside the noise zone.
  • A thin line is the zero of an axis.
  • A heavy line is a boundary of the template.
  • The label of a region is the weight of a co-movement in that region.
                         dn2                     dp2                       ┌──┴──┐                 ┌──┴──┐                       │     │                 │     │            4 ┬─────┰─────┰─────┬─────┬─────┬─────┰─────┰─────┐     ┌────    │ n13 ┃ n19 ┃ n18 ╎     │     ╎ n15 ┃ n14 ┃ n11 │dp1 ─┤      3 ┾━━━━━╋━━━━━╋━━━━━┿━━━━━┿━━━━━┿━━━━━╋━━━━━╋━━━━━┥     └────    │ n20 ┃ n6  ┃ n9  ╎     │     ╎ n7  ┃ n4  ┃ n14 │ ────┐            2 ┾━━━━━╋━━━━━╋━━━━━┿━━━━━┿━━━━━┿━━━━━╋━━━━━╋━━━━━┥     ├─ dp2              │ n21 ┃ n10 ┃ n3  ╎     │     ╎ n1  ┃ n7  ┃ n15 │ ────┘     ┌────  1 ┼╌╌╌╌╌╂╌╌╌╌╌╂╌╌╌╌╌┼╌╌╌╌╌┴╌╌╌╌╌┼╌╌╌╌╌╂╌╌╌╌╌╂╌╌╌╌╌┤     │        │     ┃     ┃     ╎           ╎     ┃     ┃     │ 2c ─┤ r_j  0 ┼─────╂─────╂─────┤    r0     ├─────╂─────╂─────┤     │        │     ┃     ┃     ╎           ╎     ┃     ┃     │     └──── -1 ┼╌╌╌╌╌╂╌╌╌╌╌╂╌╌╌╌╌┼╌╌╌╌╌┬╌╌╌╌╌┼╌╌╌╌╌╂╌╌╌╌╌╂╌╌╌╌╌┤              │ n16 ┃ n8  ┃ n2  ╎     │     ╎ n3  ┃ n9  ┃ n18 │ ────┐           -2 ┾━━━━━╋━━━━━╋━━━━━┿━━━━━┿━━━━━┿━━━━━╋━━━━━╋━━━━━┥     ├─ dn2     ┌────    │ n17 ┃ n5  ┃ n8  ╎     │     ╎ n10 ┃ n6  ┃ n19 │ ────┘dn1 ─┤     -3 ┾━━━━━╋━━━━━╋━━━━━┿━━━━━┿━━━━━┿━━━━━╋━━━━━╋━━━━━┥     └────    │ n12 ┃ n17 ┃ n16 ╎     │     ╎ n21 ┃ n20 ┃ n13 │           -4 ┼─────╀─────╀─────┼─────┼─────┼─────╀─────╀─────┤             -4    -3    -2    -1     0     1     2     3     4                                     r_i                 │     │        │           │        │     │                 └──┬──┘        └─────┬─────┘        └──┬──┘                   dn1               2c                dp1

Fields

  • dp1: Outer positive boundary. A positive return at dp1 or above is large. The constructor swaps dp1 and dp2 when necessary, so dp1 >= dp2 always holds.
  • dp2: Inner positive boundary. A positive return in [dp2, dp1) is moderate, and a positive return below dp2 is small.
  • dn1: Outer negative boundary. A negative return at -dn1 or below is large. The constructor swaps dn1 and dn2 when necessary, so dn1 >= dn2 always holds.
  • dn2: Inner negative boundary. A negative return in (-dn1, -dn2] is moderate, and a negative return above -dn2 is small.
  • n1: Weight of a concordant co-movement of two small positive returns.
  • n2: Weight of a concordant co-movement of two small negative returns.
  • n3: Weight of a discordant co-movement of a small positive return with a small negative return.
  • n4: Weight of a concordant co-movement of two moderate positive returns.
  • n5: Weight of a concordant co-movement of two moderate negative returns.
  • n6: Weight of a discordant co-movement of a moderate positive return with a moderate negative return.
  • n7: Weight of a concordant positive co-movement of a small return with a moderate one.
  • n8: Weight of a concordant negative co-movement of a small return with a moderate one.
  • n9: Weight of a discordant co-movement whose positive return is moderate and whose negative return is small.
  • n10: Weight of a discordant co-movement whose positive return is small and whose negative return is moderate.
  • n11: Weight of a concordant co-movement of two large positive returns.
  • n12: Weight of a concordant co-movement of two large negative returns.
  • n13: Weight of a discordant co-movement of a large positive return with a large negative return.
  • n14: Weight of a concordant positive co-movement of a moderate return with a large one.
  • n15: Weight of a concordant positive co-movement of a small return with a large one.
  • n16: Weight of a concordant negative co-movement of a small return with a large one.
  • n17: Weight of a concordant negative co-movement of a moderate return with a large one.
  • n18: Weight of a discordant co-movement whose positive return is large and whose negative return is small.
  • n19: Weight of a discordant co-movement whose positive return is large and whose negative return is moderate.
  • n20: Weight of a discordant co-movement whose positive return is moderate and whose negative return is large.
  • n21: Weight of a discordant co-movement whose positive return is small and whose negative return is large.

Constructors

FullGerberIQ(; dp1::Number = 2.0, dp2::Number = dp1, dn1::Number = dp1,               dn2::Number = dp1, n1::Number = 0.5, n2::Number = n1,               n3::Number = sqrt(n1 * n2), n4::Number = 0.75, n5::Number = n4,               n6::Number = sqrt(n4 * n5), n7::Number = sqrt(n1 * n4),               n8::Number = sqrt(n2 * n5), n9::Number = sqrt(n4 * n2),               n10::Number = sqrt(n1 * n5), n11::Number = 1.0, n12::Number = n11,               n13::Number = sqrt(n11 * n12), n14::Number = sqrt(n4 * n11),               n15::Number = sqrt(n1 * n11), n16::Number = sqrt(n2 * n12),               n17::Number = sqrt(n5 * n12), n18::Number = sqrt(n2 * n11),               n19::Number = sqrt(n5 * n11), n20::Number = sqrt(n4 * n12),               n21::Number = sqrt(n1 * n12))

Keywords correspond to the struct's fields.

Only the six diagonal weights have a free default. n1, n2, n4, n5, n11 and n12 are the weights of the six magnitude classes. The default of each of the other fifteen weights is the geometric mean of the diagonal weights of the two classes that its channel joins. clamp_gerber_iq_n enforces that bound under Gerber2. So the default template meets the bound for all values of the six diagonal weights, and the clamp never changes a default. A default from two mixed weights can let a sample of two assets give a correlation above 1.

Validation

The swap of the boundaries raises no error. The constructor orders dp1 and dp2 with extrema, and it orders dn1 and dn2 in the same way. So a caller who gives them in the other order gets a valid template.

Examples

julia> FullGerberIQ()FullGerberIQ  dp1 ┼ Float64: 2.0  dp2 ┼ Float64: 2.0  dn1 ┼ Float64: 2.0  dn2 ┼ Float64: 2.0   n1 ┼ Float64: 0.5   n2 ┼ Float64: 0.5   n3 ┼ Float64: 0.5   n4 ┼ Float64: 0.75   n5 ┼ Float64: 0.75   n6 ┼ Float64: 0.75   n7 ┼ Float64: 0.6123724356957945   n8 ┼ Float64: 0.6123724356957945   n9 ┼ Float64: 0.6123724356957945  n10 ┼ Float64: 0.6123724356957945  n11 ┼ Float64: 1.0  n12 ┼ Float64: 1.0  n13 ┼ Float64: 1.0  n14 ┼ Float64: 0.8660254037844386  n15 ┼ Float64: 0.7071067811865476  n16 ┼ Float64: 0.7071067811865476  n17 ┼ Float64: 0.8660254037844386  n18 ┼ Float64: 0.7071067811865476  n19 ┼ Float64: 0.8660254037844386  n20 ┼ Float64: 0.8660254037844386  n21 ┴ Float64: 0.7071067811865476

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.3.4, Figure 2.
source
PortfolioOptimisers.GerberIQCovariance — Type
struct GerberIQCovariance{__T_ve, __T_me, __T_pdm, __T_c, __T_decay, __T_oc, __T_sc, __T_kind, __T_alg, __T_ex, __T_cache} <: BaseGerberIQCovariance

Estimates a covariance matrix from the weighted and age-discounted co-movements of each pair of assets.

Four fields hold the parameters of the source. c is the noise threshold, and kind is the squeezing template that gives the weight of a co-movement. sc sets the units of the thresholds, and decay discounts a co-movement by its age. The source has no parameter for alg, because its statistic is the Gerber1 statistic alone. This estimator also gives Gerber0 and Gerber2 from the classic Gerber family. gerber_IQ states the three statistics and their reduction to the Gerber family.

The lookback duration $\tau$ of the source has no field. The estimator always reads each row of X, and decay discounts the oldest rows. This is the case $\tau = T - 1$ of the source.

Gerber1 is Equation 4 of [36]. Its numerator sums the signed, weighted and discounted contributions over the observations on which both assets leave the noise zone. Its denominator sums the weights over the observations on which at least one asset leaves it. Equation 5 is the discount. A direct evaluation of Equations 4 and 5 for BasicGerberIQ agrees with this estimator to machine precision.

The field oc states the effective number of observations of the matrix. The library adds it, and the source has no such parameter. A denoiser in a PortfolioOptimisersCovariance reads the ratio T / N, and it gets T from effective_observation_count. The decay gives the old rows less weight, so the matrix is worth fewer observations than X has rows. But the statistic is a ratio of weighted counts of co-movements over thresholds, and not a weighted moment, so no count follows from it. oc = nothing keeps T = size(X, 1). KishObservationCount gives the Kish count of the temporal weights decay(T, k), $k = 1, \ldots, T$.

The library takes Gerber0 and Gerber2 from the classic Gerber family. The Internet Appendix of the source states a third form, which the library does not ship. Equation 1 of the source drops a return with $\lvert r^{*} \rvert \leq c$, so a return exactly at the threshold is noise there. The library lets that return cross, which is the closed rule of the Gerber statistic. The source centres the returns on a location $r_0$ that the user chooses. The library centres them on the mean that me computes.

Fields

  • ve: Variance estimator.
  • me: Expected returns estimator.
  • pdm: Positive definite matrix estimator.
  • c: Noise threshold. A return less than c scaled units from zero is noise, and a return of exactly zero is noise for each c. The statistic drops a co-movement whose two returns are both noise. c must be at most each boundary of kind.
  • sc: Threshold scaler, a GerberIQScaler. It sets the units of the thresholds of each pair. nothing gives both assets of a pair the mean of their two standard deviations.
  • kind: Squeezing template, a GerberIQCovarianceAlgorithm. It gives the weight of a co-movement from the channel that the co-movement falls in.
  • alg: Gerber covariance algorithm.
  • ex: Parallel execution strategy.
  • cache: Optional partial-fit state. It is nothing until partial_fit! writes one. When the caller gives no data matrix, the batch verb of the estimator reads it. Each propagation channel does one thing with it. factory keeps it unchanged, because a factory call resolves the configuration, not the sample. port_opt_view copies the entries of the selected assets into a new state, so the viewed estimator holds the state of those assets alone. obs_weights_view removes it, because a state has no slice on the observation axis. Only a type with an observation-weights field has that channel. A type with no such field falls through to the identity method, so it keeps its state. A family whose state has no exact asset slice removes it on both axes and names the reason.

Constructors

GerberIQCovariance(; ve::StatsBase.CovarianceEstimator = SimpleVariance(),                     me::AbstractExpectedReturnsEstimator = SimpleExpectedReturns(),                     pdm::Option{<:AbstractPosdefEstimator} = Posdef(), c::Number = 0.5,                     decay::GerberIQDecayEstimator = ExpGerberIQDecay(),                     oc::Option{<:AbstractObservationCountAlgorithm} = nothing,                     sc::Option{<:GerberIQScaler} = nothing,                     kind::GerberIQCovarianceAlgorithm = BasicGerberIQ(),                     alg::GerberCovarianceAlgorithm = Gerber1(),                     ex::FLoops.Transducers.Executor = FLoops.Transducers.ThreadedEx(),                     cache::Option{<:AbstractPartialFitState} = nothing)

Keywords correspond to the struct's fields.

Validation

Warning

The constructor can replace kind. It gives the template to clamp_gerber_iq_n, which lowers some weights under Gerber2. So the stored template is not always the template that the caller gave. Read ce.kind, not the argument, when the exact weights matter.

Propagated parameters

factory passes its arguments on to these @fprop fields:

  • ve: Recursively updated through factory.
  • me: Recursively updated through factory.
  • decay: Recursively updated through factory.
  • alg: Recursively updated through factory.
  • cache: Carried unchanged through factory.

View parameters

port_opt_view takes the view of these @vprop fields at the selected indices:

Examples

julia> GerberIQCovariance()GerberIQCovariance     ve ┼ SimpleVariance        │          me ┼ SimpleExpectedReturns        │             │   w ┴ nothing        │           w ┼ nothing        │   corrected ┴ Bool: true     me ┼ SimpleExpectedReturns        │   w ┴ nothing    pdm ┼ Posdef        │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton        │   kwargs ┴ @NamedTuple{}: NamedTuple()      c ┼ Float64: 0.5  decay ┼ ExpGerberIQDecay        │   e ┼ nothing        │   y ┴ nothing     oc ┼ nothing     sc ┼ nothing   kind ┼ BasicGerberIQ        │   d ┼ Float64: 2.0        │   n ┴ Float64: 0.5    alg ┼ Gerber1()     ex ┴ Transducers.ThreadedEx{@NamedTuple{}}: Transducers.ThreadedEx()

Related

References

  • [36] S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025). Section 3.5, Equations 1 to 5, and the Internet Appendix.
source

References

[36]
S. Gerber, W. Smyth, H. Markowitz, Y. Miao, P. Ernst and P. Sargen. Squeezing financial noise: A novel approach to covariance matrix estimation. Available at SSRN 4986939 (2025).