Regime adjusted exp weighted variance

Types

PortfolioOptimisers.RegimeAdjustedMethod — Type
abstract type RegimeAdjustedMethod <: AbstractEstimator

Names how a regime statistic of standardised squared returns becomes the multiplier of a volatility.

The estimator scores each observation against the variance before it. The method turns the scores of one observation into one statistic. The regime state smooths that statistic, and the method turns the state into a volatility multiplier. This is the Volatility Regime Adjustment of [79], and RootMeanSquaredAdjusted is its statistic. The other methods replace the mean square with a statistic that one outlier moves less. They are the Short-Term Volatility Updating of [80].

Interfaces

To implement a new regime adjustment method, subtype RegimeAdjustedMethod and implement the methods below. RegimeAdjustedExpWeightedVariance calls regime_multiplier and the first form of get_regime_state, and RegimeAdjustedExpWeightedCovariance calls regime_multiplier and the second form.

A new method takes debias = nothing, the raw statistic. ExactDebias and LawDebias divide the statistic by the bias of the moment that the method reads. The library computes that bias for its own three methods alone, so the two constructors refuse a new method under either rule.

regime_multiplier

  • regime_multiplier(method::MyRegimeMethod, regime_state::Number) -> Number: Turns the smoothed regime state into the volatility multiplier. The estimator scales its variance or its covariance by the square of the multiplier.

get_regime_state

  • get_regime_state(method::MyRegimeMethod, z2::VecNum, min_val::Number) -> Number: Turns the standardised squared returns of the scored assets of one observation into the statistic that the regime state smooths.
  • get_regime_state(method::MyRegimeMethod, target::RegimeAdjustedTarget, stats::VecNum, n::Integer, min_val::Number) -> VecNum: Turns each statistic of the target, over n scored assets, into the value that the regime state smooths. The estimator smooths the mean of the values.

Examples

julia> struct MyRegimeMethod <: PortfolioOptimisers.RegimeAdjustedMethod endjulia> PortfolioOptimisers.regime_multiplier(::MyRegimeMethod, s::Number) = sqrt(max(s, 0));julia> function PortfolioOptimisers.get_regime_state(::MyRegimeMethod, z2::AbstractVector,                                                     ::Number)           return sum(z2) / length(z2)       end;julia> function PortfolioOptimisers.get_regime_state(::MyRegimeMethod,                                                     ::PortfolioOptimisers.RegimeAdjustedTarget,                                                     stats::AbstractVector, n::Integer, ::Number)           return stats ./ n       end;julia> X = [0.01 -0.02; -0.015 0.03; 0.02 -0.01; -0.005 0.012; 0.008 -0.02; -0.02 0.03];julia> kw = (; decay = 0.9, min_obs = 2, regime_min_obs = 1, debias = nothing);julia> var(RegimeAdjustedExpWeightedVariance(; regime_method = MyRegimeMethod(), kw...), X) ≈       var(RegimeAdjustedExpWeightedVariance(; regime_method = RootMeanSquaredAdjusted(), kw...),           X)truejulia> cov(RegimeAdjustedExpWeightedCovariance(; regime_method = MyRegimeMethod(), kw...), X) ≈       cov(RegimeAdjustedExpWeightedCovariance(; regime_method = RootMeanSquaredAdjusted(), kw...),           X)truejulia> RegimeAdjustedExpWeightedVariance(; regime_method = MyRegimeMethod())ERROR: ArgumentError: `RegimeAdjustedExpWeightedVariance.regime_method` is a `MyRegimeMethod`, and `RegimeAdjustedExpWeightedVariance.debias` is `ExactDebias()`. That rule divides the regime statistic by the bias of the moment that the method reads, and the library computes that bias for `RootMeanSquaredAdjusted`, `FirstMomentRegimeAdjusted` and `LogRegimeAdjusted` alone. Set `debias = nothing` for this method.[...]

Related

References

  • [79] J. Menchero, D. J. Orr and J. Wang. The Barra US Equity Model (USE4): Methodology Notes. Model Insight, MSCI (2011). Section 4.3.
  • [80] G. A. Paleologo. The Elements of Quantitative Investing. Wiley (2025). Section 6.3.3, Model 6.8 and Equations 6.9 to 6.11.
source
PortfolioOptimisers.LogRegimeAdjusted — Type
struct LogRegimeAdjusted{__T_x, __T_y, __T_kappa} <: RegimeAdjustedMethod

Scales the volatility by the exponential of half the smoothed mean log of the standardised squared returns.

The log compresses a large square, so one outlier moves this multiplier less than it moves the multiplier of RootMeanSquaredAdjusted. The constant $\kappa$ is the expectation of $\ln z^{2}$ when $z^{2}$ is a $\mathrm{Gamma}(x, y)$ variate. The defaults $x = 1/2$ and $y = 2$ make $z^{2}$ a $\chi^{2}(1)$ variate, the square of a standard normal return. The regime state is then a log variance ratio for every law, so the volatility multiplier is the exponential of half the state.

This is the Short-Term Volatility Updating of [80], Section 6.3.3. Model 6.8 scales a correctly calibrated return by $e^{x_{t}/2}$, so $\ln z^{2} - \kappa$ is an unbiased observation of the latent log variance ratio $x_{t}$. The smoothed state is the estimate $\hat{x}_{t}$ of the book, and the multiplier is its $e^{\hat{x}_{t}/2}$. The book reads the squared norm of the whole standardised vector of $m$ returns. Its $\kappa$ is the expectation of the log of the squared norm of a standard normal vector of $m$ entries. The book does not print a closed form, and the log of a $\chi^{2}_{m}$ variate has the expectation $\psi(m/2) + \ln 2$. This method reads each asset at $m = 1$ and takes the mean of the values. RegimeAdjustedExpWeightedCovariance with a MahalanobisTarget reads the norm of the book.

Mathematical definition

\[\begin{align} \kappa &= \psi(x) + \ln y\,, \\ g_{t} &= \frac{1}{n_{t}} \sum_{i \in \mathcal{A}_{t}} \ln \max(z_{i,t}^{2}, \varepsilon) - \kappa\,, \\ \mathrm{mult}(s) &= \exp(s / 2)\,. \end{align}\]

Where:

  • $\kappa$: Expectation of $\ln z^{2}$ for a $\mathrm{Gamma}(x, y)$ variate.
  • $\psi$: Digamma function.
  • $x$, $y$: Shape and scale of the law of $z^{2}$, the fields of the same names.
  • $g_{t}$: Regime statistic of observation $t$, which the regime state smooths.
  • $\mathcal{A}_{t}$, $n_{t}$: Scored assets of observation $t$, the assets whose returns the regime statistic reads, and their count.
  • $z_{i,t}^{2}$: Standardised squared return of asset $i$ at observation $t$, the squared deviation over the variance that the estimate before $t$ predicts.
  • $\varepsilon$: The min_val field of the estimator.
  • $\mathrm{mult}(s)$: Volatility multiplier of a regime state $s$. The estimator scales its variance or its covariance by the square of the multiplier.

RegimeAdjustedExpWeightedVariance states $\mathcal{A}_{t}$, $z_{i,t}^{2}$ and the smoothing of $g_{t}$. RegimeAdjustedExpWeightedCovariance replaces the mean over the assets with the log of the statistic of its RegimeAdjustedTarget, and $\kappa$ with the expectation of that log.

Fields

  • x: Shape parameter of the log regime adjustment.
  • y: Scale parameter of the log regime adjustment.
  • kappa: Precomputed normalisation constant digamma(x) + log(y) for the log regime adjustment.

Constructors

LogRegimeAdjusted(;    x::Number = 0.5,    y::Number = 2.0) -> LogRegimeAdjusted

Keywords correspond to the struct's fields. The constructor derives the kappa field from x and y, so a caller cannot set it. Accessors.set, and so a search over x or y, computes kappa again from the new values, and it refuses a patch of kappa.

Validation

  • x > 0, and x is finite.
  • y > 0, and y is finite.

Examples

julia> LogRegimeAdjusted()LogRegimeAdjusted      x ┼ Float64: 0.5      y ┼ Float64: 2.0  kappa ┴ Float64: -1.2703628454614782

Related

References

  • [80] G. A. Paleologo. The Elements of Quantitative Investing. Wiley (2025). Section 6.3.3, pages 122 and 123, Model 6.8 and the estimate of the state.
source
PortfolioOptimisers.FirstMomentRegimeAdjusted — Type
struct FirstMomentRegimeAdjusted{__T_x} <: RegimeAdjustedMethod

Scales the volatility by the smoothed mean absolute standardised return over its expectation x.

The absolute value grows linearly in a return, so one outlier moves this multiplier less than it moves the multiplier of RootMeanSquaredAdjusted and more than it moves the multiplier of LogRegimeAdjusted. The default $x = \sqrt{2/\pi}$ is the expectation of $|z|$ for a standard normal $z$.

This is Equation 6.11 of [80], the linear form of the Short-Term Volatility Updating. The book divides the norm of the standardised vector of $m$ returns by $\sqrt{m}$, the limit of its expectation as $m$ grows. This method reads each asset at $m = 1$ and divides by the exact expectation $x$, 0.798 by default, where the book divides by 1. RegimeAdjustedExpWeightedCovariance divides the root of the statistic of its target by the exact expectation of that root. At $m = 5$ this is 2.128 against $\sqrt{5} = 2.236$.

Mathematical definition

\[\begin{align} g_{t} &= \frac{1}{x\, n_{t}} \sum_{i \in \mathcal{A}_{t}} \sqrt{z_{i,t}^{2}}\,, \\ \mathrm{mult}(s) &= s\,. \end{align}\]

Where:

  • $x$: Expectation of $|z|$ under correct calibration, the field of the same name.
  • $g_{t}$: Regime statistic of observation $t$, which the regime state smooths.
  • $\mathcal{A}_{t}$, $n_{t}$: Scored assets of observation $t$, the assets whose returns the regime statistic reads, and their count.
  • $z_{i,t}^{2}$: Standardised squared return of asset $i$ at observation $t$, the squared deviation over the variance that the estimate before $t$ predicts.
  • $\mathrm{mult}(s)$: Volatility multiplier of a regime state $s$. The estimator scales its variance or its covariance by the square of the multiplier.

RegimeAdjustedExpWeightedVariance states $\mathcal{A}_{t}$, $z_{i,t}^{2}$ and the smoothing of $g_{t}$. RegimeAdjustedExpWeightedCovariance replaces the mean over the assets with the root of the statistic of its RegimeAdjustedTarget, and $x$ with the expectation of that root.

Fields

  • x: First-moment normalisation constant for the regime adjustment.

Constructors

FirstMomentRegimeAdjusted(;    x::Number = sqrt(2 * inv(π))) -> FirstMomentRegimeAdjusted

Keywords correspond to the struct's fields.

Validation

  • x > 0, and x is finite.

Examples

julia> FirstMomentRegimeAdjusted()FirstMomentRegimeAdjusted  x ┴ Float64: 0.7978845608028654

Related

References

  • [80] G. A. Paleologo. The Elements of Quantitative Investing. Wiley (2025). Section 6.3.3, page 124, Equation 6.11.
source
PortfolioOptimisers.RootMeanSquaredAdjusted — Type
struct RootMeanSquaredAdjusted <: RegimeAdjustedMethod

Scales the volatility by the root of the smoothed mean of the standardised squared returns.

This is the Volatility Regime Adjustment of [79]. The statistic of one observation is the square of the cross-sectional bias statistic of Equation 4.3, and the multiplier is the root of its exponentially weighted mean, Equation 4.4. The specific-risk form, Equations 5.10 and 5.11, weighs each asset by its capitalisation, and this method weighs each asset equally. The recursion of the regime state starts at the first statistic. The square grows fastest in a return, so one outlier moves this multiplier more than it moves the multipliers of FirstMomentRegimeAdjusted and LogRegimeAdjusted.

Mathematical definition

\[\begin{align} g_{t} &= \frac{1}{n_{t}} \sum_{i \in \mathcal{A}_{t}} z_{i,t}^{2}\,, \\ \mathrm{mult}(s) &= \sqrt{\max(s, 0)}\,. \end{align}\]

Where:

  • $g_{t}$: Regime statistic of observation $t$, which the regime state smooths.
  • $\mathcal{A}_{t}$, $n_{t}$: Scored assets of observation $t$, the assets whose returns the regime statistic reads, and their count.
  • $z_{i,t}^{2}$: Standardised squared return of asset $i$ at observation $t$, the squared deviation over the variance that the estimate before $t$ predicts.
  • $\mathrm{mult}(s)$: Volatility multiplier of a regime state $s$. The estimator scales its variance or its covariance by the square of the multiplier.

RegimeAdjustedExpWeightedVariance states $\mathcal{A}_{t}$, $z_{i,t}^{2}$ and the smoothing of $g_{t}$. RegimeAdjustedExpWeightedCovariance replaces $g_{t}$ with the statistic of its RegimeAdjustedTarget over the count of the assets.

Related

References

  • [79] J. Menchero, D. J. Orr and J. Wang. The Barra US Equity Model (USE4): Methodology Notes. Model Insight, MSCI (2011). Section 4.3, Equations 4.3 to 4.5, and Section 5.3, Equations 5.10 to 5.12.
source
PortfolioOptimisers.RegimeAdjustedExpWeightedVariance — Type
struct RegimeAdjustedExpWeightedVariance{__T_decay, __T_min_obs, __T_hac_lags, __T_hac_floor, __T_regime_method, __T_regime_decay, __T_regime_min_obs, __T_regime_lohi_mult, __T_min_val, __T_centring, __T_debias, __T_cache} <: AbstractVarianceEstimator

Estimates the exponentially weighted variance of each asset, and scales it by one regime multiplier.

At each observation the estimator scores each asset by its squared return over the variance before it, z². Then it steps the variance. The regime state smooths a statistic of the scores with regime_decay. The report scales each variance by the square of regime_multiplier(regime_method, regime_state).

A regime_method of nothing turns the adjustment off. No regime state advances, so the multiplier stays at one, and the estimator is the plain exponentially weighted recursion. A consumer that reads a volatility, and not a risk figure that the regime scales, needs this form. EWVolatility is that consumer in the library.

Under debias = ExactDebias(), the default, the estimator divides z² by the bias that the inverse of an estimated variance puts in the moment that the method reads. It does not score an estimate of four terms or fewer. Under debias = nothing it scores the raw z².

Under centring = EstimatedCentring(), the default, the estimator takes each deviation from the normalised location of the returns before it. It divides each square by its exact factor, so the variance is unbiased from the second valid return whatever the mean. Under HAC the factor also reads the mean of each lagged product. Under centring = PreCentred() each return is its own deviation.

The estimator is mask-aware. A prior fitted with it keeps a young asset investable, and scenario_fill writes a zero in each row that the asset was missing. Every consumer of a Prior Result reads its returns matrix. A measure that reads the scenarios then reads a zero return where the asset had none, and it understates the risk of that asset over those rows. The variance stays the estimate that this recursion made from the rows that it saw.

The fill_limit field of the fitting prior is a share of the observations of the asset. A fill at or below it is silent, a fill above it warns, and strict refuses every fill. fill_limit defaults to nothing, and this family carries no CoveragePolicy to derive a limit from, so the fit warns about every fill.

The estimator is the Volatility Regime Adjustment of specific risk of [79], on an exponentially weighted variance. The log and the first-moment methods are the Short-Term Volatility Updating of [80]. The HAC adjustment is the estimator of [18], applied to each term of the recursion.

Mathematical definition

The variance of each asset steps on the observations where its return is valid:

\[\begin{align} q_{i,t} &= u_{i,t}^{2} + 2 \sum_{j=1}^{L} \left(1 - \frac{j}{L + 1}\right) u_{i,t}\, u_{i,t-j}\,, \\ v_{i,t} &= \lambda v_{i,t-1} + (1 - \lambda)\, q_{i,t}\,. \end{align}\]

Each observation scores the assets of $\mathcal{A}_{t}$ against the variance before it, and the regime state smooths the statistic of the method:

\[\begin{align} z_{i,t}^{2} &= \frac{u_{i,t}^{2}}{\beta(K_{i,t})\, v_{i,t-1} / (1 - \lambda^{K_{i,t}})}\,, \\ s_{t} &= \lambda_{r} s_{t-1} + (1 - \lambda_{r})\, g_{t}\,, \quad s_{t_{0}} = g_{t_{0}}\,. \end{align}\]

The report divides each variance by the weight that its zero seed leaves, and scales it by the square of the multiplier:

\[\begin{align} \hat{\sigma}_{i}^{2} &= m^{2}\, \frac{\max(v_{i,T}, 0)}{1 - \lambda^{K_{i,T}}}\,, \quad m = \mathrm{clamp}(\mathrm{mult}(s_{T}), l, h)\,. \end{align}\]

Where:

  • $u_{i,t}$: Deviation of the return of asset $i$ at observation $t$. Under EstimatedCentring it is taken from the location of the returns before $t$, the first return gives no term, and each square, in $q_{i,t}$ and in $z_{i,t}^{2}$, is divided by its exact factor, as ExpWeightedVariance states. Under PreCentred it is the return.
  • $q_{i,t}$: Term of the recursion. Where hac_lags is nothing, $L = 0$ and the term is $u_{i,t}^{2}$. A lag that reaches before the first observation of the asset gives no term.
  • $L$: hac_lags.
  • $v_{i,t}$: Raw exponentially weighted variance of asset $i$, seeded at zero.
  • $\lambda$: decay.
  • $\mathcal{A}_{t}$, $n_{t}$: Scored assets of observation $t$, the assets whose returns the regime statistic reads, and their count. An asset is scored where its return is valid, where it is in the estimation mask, where $K_{i,t}$ is at least min_obs, and where $v_{i,t-1}$ is at least min_val.
  • $z_{i,t}^{2}$: Standardised squared return of asset $i$ at observation $t$, the squared deviation over the variance that the estimate before $t$ predicts.
  • $K_{i,t}$: Count of the terms in $v_{i,t-1}$.
  • $\beta(K)$: Bias factor of regime_bias_table for the moment that the method reads, or one under debias = nothing. The inverse of an estimated variance is too large on average (Jensen's inequality). Without the factor, the mean of $z_{i,t}^{2}$ is 1.07 at a half-life of 10 and 1.017 at a half-life of 40. The factor is exact for this statistic. Under ExactDebias the estimator does not score an estimate of four terms or fewer, because the variance of $z_{i,t}^{2}$ is not finite there. A HAC estimate is a quadratic form with a banded weight matrix, and the table reads the spectrum of that matrix, so the factor is exact for it too. The estimator does not score an estimate with too few effective observations. On 10 independent normal assets over 4000 rows, at two lags and a half-life of 10, the mean squared multiplier of RootMeanSquaredAdjusted over 8 seeds is 0.999 with the factor and 1.140 without it.
  • $g_{t}$: Regime statistic of observation $t$, which the regime state smooths. The RegimeAdjustedMethod states it from the $z_{i,t}^{2}$ of $\mathcal{A}_{t}$. An observation that scores no asset leaves the state as it is.
  • $s_{t}$: Smoothed regime state after observation $t$. $t_{0}$ is the first observation that scores an asset.
  • $\lambda_{r}$: Decay of the regime state, the regime_decay field.
  • $\hat{\sigma}_{i}^{2}$: Regime-adjusted variance of asset $i$. It is NaN where $K_{i,T}$ is below min_obs, or where the asset is not active.
  • $m$: Multiplier of the report. It is one while fewer than regime_min_obs observations have scored an asset, and where regime_method is nothing.
  • $\mathrm{mult}(s)$: Volatility multiplier of a regime state $s$. The estimator scales its variance or its covariance by the square of the multiplier.
  • $l$, $h$: The two bounds of regime_lohi_mult. Where that field is nothing, no clamp runs.
  • $T$: Number of observations.

Fields

  • decay: Exponential decay factor for the exponentially weighted estimator.
  • min_obs: Minimum number of observations required before the estimator produces a valid result.
  • hac_lags: Optional number of lags for Heteroskedasticity and Autocorrelation Consistent (HAC) kernel correction of squared returns. If nothing, no HAC correction is applied.
  • hac_floor: Whether each HAC-adjusted square is floored at zero before it enters the variance recursion. On returns with no autocorrelation the floor makes the variance too large, by 16 % at two lags, so nothing, the default, keeps the recursion an unbiased quadratic form and floors only the variance that the estimator returns. PerTermHacFloor floors each square.
  • regime_method: Regime adjustment method that computes the regime statistic of each observation, or nothing for no regime adjustment.
  • regime_decay: Exponential decay factor of the regime state. A value above 2^(-1/138) ≈ 0.99499, which is a regime half-life above 138 observations, makes the regime state slow to follow the variance that it corrects. After the variance changes level, the multiplier keeps correcting a mismatch that the variance has already absorbed, so it can overshoot and act erratically. The estimator gives no warning, and it computes the same recursion at every value in (0, 1).
  • regime_min_obs: Count of regime observations that the estimator needs before it applies the regime multiplier. Before that count the multiplier is one.
  • regime_lohi_mult: Optional (lo, hi) bounds of the regime multiplier. If nothing, no clamp runs.
  • min_val: Minimum threshold to prevent division by zero or degenerate estimates.
  • centring: The location each deviation is taken from. EstimatedCentring, the default, estimates the location of each asset and divides each term by the bias that the estimate puts in it, so the moment is unbiased from the second valid return whatever the mean. PreCentred takes the returns as deviations from a mean of zero. ZeroStartCentring takes the location of a recursion from zero that is not divided by its weight.
  • debias: Whether the regime statistic corrects the bias of the estimate it reads. The inverse of an estimated variance is too large on average (Jensen's inequality). Under ExactDebias, the default, the statistic skips an estimate of n + 3 terms or fewer, for n directions. Where hac_lags is set, it also skips an estimate whose effective count of terms is n + 1 or fewer. It divides the rest by the bias factor that its regime_method reads. The diagonal target also divides its sum by the factor of its law, which reads the correlation of the assets and the noise of each estimate, for the first-moment and the log methods. LawDebias divides by the law of the estimate alone, and takes the deviation as independent of the estimate. nothing scores the raw statistic.

Constructors

RegimeAdjustedExpWeightedVariance(;    decay::Number             = exp2(-inv(40.0)),    min_obs::Integer          = round(Int, max(1, decay_half_life(decay))),    hac_lags::Option{<:Integer} = nothing,    hac_floor::Option{<:AbstractHacFloor} = nothing,    regime_method::Option{<:RegimeAdjustedMethod} = FirstMomentRegimeAdjusted(),    regime_decay::Number      = exp2(-2 / decay_half_life(decay)),    regime_min_obs::Integer   = round(Int, max(1, decay_half_life(decay) / 2)),    regime_lohi_mult::Option{<:Tuple{Number, Number}} = (0.7, 1.6),    min_val::Number           = 1e-12,    centring::AbstractCentring = EstimatedCentring(),    debias::Option{<:AbstractRegimeDebias} = ExactDebias(),    cache::Option{<:AbstractPartialFitState} = nothing) -> RegimeAdjustedExpWeightedVariance

Keywords correspond to the struct's fields.

Validation

  • 0 < decay < 1.
  • min_obs > 0.
  • If hac_lags is not nothing, hac_lags > 0.
  • 0 < regime_decay < 1.
  • regime_min_obs > 0.
  • If regime_lohi_mult is not nothing, 0 < regime_lohi_mult[1] < regime_lohi_mult[2].

Examples

julia> ce = RegimeAdjustedExpWeightedVariance();julia> ce.decay ≈ exp2(-inv(40.0))truejulia> ce.min_obs40

Related

References

  • [79] J. Menchero, D. J. Orr and J. Wang. The Barra US Equity Model (USE4): Methodology Notes. Model Insight, MSCI (2011). Section 5.3, Equations 5.10 to 5.12.
  • [80] G. A. Paleologo. The Elements of Quantitative Investing. Wiley (2025). Section 6.3.3, Model 6.8 and Equations 6.9 to 6.11.
  • [18] W. K. Newey and K. D. West. A simple, positive semi-definite, heteroskedasticity and autocorrelation consistent covariance matrix. Econometrica 55, 703–708 (1987). Equation 5.
source

Functions

PortfolioOptimisers.regime_multiplier — Function
regime_multiplier(
    _::LogRegimeAdjusted,
    regime_state::Number
) -> Any

Computes the volatility multiplier of the log regime adjustment method.

The regime state is a log variance ratio for every law of the squares, so the multiplier takes half of it. The estimator scales the variance by the square of the multiplier.

Arguments

  • ::LogRegimeAdjusted: Log regime adjustment method (unused).
  • regime_state::Number: Current smoothed regime state.

Returns

  • mult::Number: Volatility multiplier exp(regime_state / 2).

Related

source
regime_multiplier(
    _::FirstMomentRegimeAdjusted,
    regime_state::Number
) -> Number

Computes the volatility multiplier of the first-moment regime adjustment method.

Arguments

  • ::FirstMomentRegimeAdjusted: First-moment regime adjustment method (unused).
  • regime_state::Number: Current smoothed regime state.

Returns

  • mult::Number: Volatility multiplier, equal to regime_state.

Related

source
regime_multiplier(
    _::RootMeanSquaredAdjusted,
    regime_state::Number
) -> Any

Computes the volatility multiplier of the root-mean-squared regime adjustment method.

Arguments

  • ::RootMeanSquaredAdjusted: Root-mean-squared regime adjustment method (unused).
  • regime_state::Number: Current smoothed regime state.

Returns

  • mult::Number: Volatility multiplier sqrt(max(regime_state, 0)).

Related

source
PortfolioOptimisers.get_regime_state — Method
get_regime_state(
    _::RootMeanSquaredAdjusted,
    z2_valid::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
    _
) -> Any

Computes the statistic $g_{t}$ of the root-mean-squared adjustment, which the regime state smooths.

Arguments

  • ::RootMeanSquaredAdjusted: Root-mean-squared regime adjustment method (unused).
  • z2_valid::VecNum: Vector of valid (non-NaN) standardised squared returns.
  • ::Any: Ignored minimum value argument.

Returns

  • s::Number: Mean of z2_valid.

Related

source
PortfolioOptimisers.get_regime_state — Method
get_regime_state(
    method::FirstMomentRegimeAdjusted,
    z2_valid::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
    _
) -> Any

Computes the statistic $g_{t}$ of the first-moment adjustment, which the regime state smooths.

Arguments

  • method::FirstMomentRegimeAdjusted: First-moment regime adjustment method.
  • z2_valid::VecNum: Vector of valid (non-NaN) standardised squared returns.
  • ::Any: Ignored minimum value argument.

Returns

  • s::Number: Mean absolute standardised return over its expectation, mean(sqrt(max.(z², 0))) / method.x.

Related

source
PortfolioOptimisers.get_regime_state — Function
get_regime_state(
    method::LogRegimeAdjusted,
    z2_valid::AbstractVector{<:Union{Number, AbstractJuMPScalar}}
) -> Any
get_regime_state(
    method::LogRegimeAdjusted,
    z2_valid::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
    min_val::Number
) -> Any

Computes the statistic $g_{t}$ of the log adjustment, which the regime state smooths.

Arguments

  • method::LogRegimeAdjusted: Log regime adjustment method.
  • z2_valid::VecNum: Vector of valid (non-NaN) standardised squared returns.
  • min_val::Number: Floor of each square before its log.

Returns

  • s::Number: Mean log of the squares less its expectation, mean(log(max.(z², min_val))) - method.kappa.

Related

source
PortfolioOptimisers.regime_bias_table — Function
regime_bias_table(
    method::Union{RegimeAdjustedMethod, RegimeTermMoments},
    decay::Number,
    K::Integer
) -> Any
regime_bias_table(
    method::Union{RegimeAdjustedMethod, RegimeTermMoments},
    decay::Number,
    K::Integer,
    ::Nothing
) -> Any
regime_bias_table(
    method::Union{RegimeAdjustedMethod, RegimeTermMoments},
    decay::Number,
    K::Integer,
    ::Nothing,
    ::PreCentred
) -> Any
regime_bias_table(
    method::Union{RegimeAdjustedMethod, RegimeTermMoments},
    decay::Number,
    K::Integer,
    ::Nothing,
    ::PreCentred,
    ::Union{Nothing, AbstractRegimeDebias}
) -> Any

Computes the bias factor of a regime statistic that reads one estimated variance, for every count of observations from one to K.

An exponentially weighted variance estimate of $K$ observations is $\hat{v} = \sigma^{2} Q$, with $Q = \sum_{j} w_{j} z_{j}^{2}$ on correctly calibrated returns. The inverse of an estimate is too large on average (Jensen's inequality), and each RegimeAdjustedMethod reads its own moment of it, so regime_bias_factor names the factor of each method. The factors are exact, not asymptotic. At equal weights they agree with $K / (K - 2)$, with the ratio of gamma functions and with the digamma form to $10^{-12}$.

Mathematical definition

\[\begin{align} w_{j} &= c\, \lambda^{j}\,, \quad c = \frac{1 - \lambda}{1 - \lambda^{K}}\,, \\ \mathbb{E}[e^{-tQ}] &= G(2 c t)\,, \quad G(s) = \prod_{j=0}^{K-1} (1 + \lambda^{j} s)^{-1/2}\,. \end{align}\]

Where:

  • $w_{j}$: Normalised weight of the observation $j$ steps before the newest.
  • $\lambda$: decay.
  • $G$: Laplace transform of $Q$, on the scale $s = 2 c t$.

Algorithm

  1. Lay a grid of step $h = 1/10$ on $x = \ln s \in [-60, 50]$. The integrands are smooth on it and decay at both ends, the slowest as $e^{x/2}$ below, so the trapezoid rule on it agrees with a grid of step $1/200$ on $[-75, 60]$ to $1.1 \times 10^{-12}$ relative from $K = 5$, at half-lives of 2, 10 and 40.
  2. For each $K$, multiply $G$ by $(1 + \lambda^{K - 1} s)^{-1/2}$ on the log scale, so the whole table costs one pass.
  3. Evaluate the factor of the method with regime_bias_factor.

The mean of $Q^{-1}$ is finite from $K = 3$ and its variance from $K = 5$, so the estimator does not read an entry at $K \le 4$.

Arguments

  • method::Union{RegimeAdjustedMethod, RegimeTermMoments}: Regime adjustment method, which names the moment, or the table of the moments of one term.
  • decay::Number: Decay of the weights.
  • K::Integer: Largest count of observations in the table.
  • ::Nothing: No HAC lags. The slot lets a caller pass the hac_lags of an estimator.
  • ::PreCentred: The law of a pre-centred estimate, which this table holds. A pre-centred deviation is the return itself, so the terms do not share a location, and the table is exact.
  • ::Option{<:AbstractRegimeDebias}: Ignored debias rule: a pre-centred deviation does not depend on the estimate.

Returns

  • table::AbstractVector: The factor for each count from one to K, or the moments of RegimeTermMoments.

Related

source
regime_bias_table(
    method::Union{RegimeAdjustedMethod, RegimeTermMoments},
    decay::Number,
    K::Integer,
    hac_lags::Union{Integer, AbstractVector{<:Union{Number, AbstractJuMPScalar}}}
) -> Any
regime_bias_table(
    method::Union{RegimeAdjustedMethod, RegimeTermMoments},
    decay::Number,
    K::Integer,
    hac_lags::Union{Integer, AbstractVector{<:Union{Number, AbstractJuMPScalar}}},
    ::PreCentred
) -> Any
regime_bias_table(
    method::Union{RegimeAdjustedMethod, RegimeTermMoments},
    decay::Number,
    K::Integer,
    hac_lags::Union{Integer, AbstractVector{<:Union{Number, AbstractJuMPScalar}}},
    ::PreCentred,
    ::Union{Nothing, AbstractRegimeDebias}
) -> Any

Computes the bias factor of a regime statistic that reads one HAC-adjusted variance estimate, for every count of observations from one to K.

A HAC estimate of $K$ observations is $\hat{v} = \sigma^{2} Q$ with $Q = z^{\top} A z$, a quadratic form in the correctly calibrated returns. $A = c B$ is banded: the weight of each square on its diagonal, and the Bartlett weight $k_{i}$ times the weight of the newer return at lag $i$. Diagonalised, $Q$ has the law of a plain estimate whose weights are the eigenvalues $\mu$ of $A$, so its Laplace transform is $G(s) = \det(I + s B)^{-1/2}$ on the scale $s = 2 c t$, and regime_bias_factor reads it as it reads the transform of regime_bias_table. The exponential weights break the identity that makes the Bartlett estimate a sum of squares, so $A$ has negative eigenvalues from a count of 5 to 50, by the half-life, and $Q$ can fall below zero. There the moment of $Q^{-1}$ is not finite, and the table reads the moment of the positive part: past the minimum of $G$ the negative eigenvalues rule the transform, so the integral stops there.

Mathematical definition

\[\begin{align} B_{jj} &= \lambda^{j}\,, \quad B_{j, j+i} = B_{j+i, j} = \lambda^{j} k_{i}\,, \quad k_{i} = 1 - \frac{i}{L + 1}\,, \quad i = 1, \ldots, L\,. \end{align}\]

Where:

  • $j$: Index of an observation, from zero for the newest.
  • $\lambda$: decay.
  • $L$: hac_lags. Where hac_lags is a vector, $L$ is its length and $k_{i}$ its entries, such as the kernel of hac_row_kernel.

Algorithm

  1. Lay the grid of regime_bias_table.
  2. For each $K$, add one row of the banded LDLᵀ factorisation of $I + s B$ at every point of the grid with hac_ldl_row!, so $\ln G$ takes the log of the new pivot and the whole table costs one pass. A pivot that is not positive marks the point: past it, the determinant has crossed zero.
  3. Cut the transform at its minimum with hac_laplace!, and evaluate the factor of the method with regime_bias_factor.

Where the estimate is positive definite, the table agrees with the eigenvalues of $B$ on a grid of step $1/200$ on $[-75, 60]$ to $10^{-10}$, and with a Monte Carlo of 400 000 draws to its noise. Where it is not, the grid agrees with the finer one to $5 \times 10^{-7}$, and to $4 \times 10^{-4}$ at a half-life of 5 and five lags, where the estimate is negative in $6 \times 10^{-5}$ of draws.

Arguments

  • method::Union{RegimeAdjustedMethod, RegimeTermMoments}: Regime adjustment method, which names the moment, or the table of the moments of one term.
  • decay::Number: Decay of the weights.
  • K::Integer: Largest count of observations in the table.
  • hac_lags::Union{Integer, VecNum}: Count of HAC lags, or the weight of each lag.
  • ::PreCentred: The law of a pre-centred estimate, which this table holds. A pre-centred deviation is the return itself, so the terms do not share a location, and the table on the banded weight matrix is exact.
  • ::Option{<:AbstractRegimeDebias}: Ignored debias rule: a pre-centred deviation does not depend on the estimate.

Returns

  • table::AbstractVector: The factor for each count from one to K, or the moments of RegimeTermMoments.

Related

source
regime_bias_table(method, decay::Number, K::Integer, hac_lags, centring::AbstractCentring,
                  debias)

Computes the bias factor of a regime statistic for every count from one to K, on the law of centring.

The bias is a moment of the law of the deviations, so the table reads the law that centring_law names. ZeroStartCentring reads the table of PreCentred. A new centring that shares a law of the library returns that law, and needs no method of this verb.

A centring with a law of its own returns itself from centring_law, and adds a method of this verb with centring bound to its own type. Without that method this method raises a MethodError, because the law has no table.

Arguments

  • method::Union{RegimeAdjustedMethod, RegimeTermMoments}: Regime adjustment method, or the table of the moments of one term.
  • decay::Number: Decay of the weights.
  • K::Integer: Largest count of terms in the table.
  • hac_lags::Option{<:Union{Integer, VecNum}}: Count of HAC lags, the weight of each lag, or nothing.
  • centring::AbstractCentring: The centring of the estimator.
  • debias::Option{<:AbstractRegimeDebias}: The debias rule, ExactDebias by default.

Returns

  • table::AbstractVector: The factor for each count, or the moments of RegimeTermMoments.

Related

source
regime_bias_table(
    method::Union{RegimeAdjustedMethod, RegimeTermMoments},
    decay::Number,
    K::Integer,
    hac_lags::Union{Nothing, Integer},
    ::EstimatedCentring
) -> Any
regime_bias_table(
    method::Union{RegimeAdjustedMethod, RegimeTermMoments},
    decay::Number,
    K::Integer,
    hac_lags::Union{Nothing, Integer},
    ::EstimatedCentring,
    debias::Union{Nothing, AbstractRegimeDebias}
) -> Any

Computes the exact bias factor of a regime statistic for every count from one to K, where each deviation is taken from an estimated location.

The location of each deviation holds the returns before it, so the terms of the estimate share their returns, and the estimate is a quadratic form $Q = c\, x^{\top} M x$ in the returns with a dense $M$. The law of $Q$ is then not the law of the pre-centred table. The next deviation $u$ reads the same location, so $u$ and $Q$ are not independent either. Each part moves the factor. Without HAC the two parts nearly cancel: at a half-life of 10 the pre-centred factors are within $4 \times 10^{-4}$ of this table. With HAC they add: there the pre-centred root-mean-squared factor is 0.26 %, 0.58 % and 1.39 % too large at one, two and four lags, as a Monte Carlo of the estimator confirms. This table is exact for both parts.

The estimate after $K$ terms is $R_{K} = \lambda R_{K-1} + q_{K}$ before its normalisation, so the Laplace transform at $s$ after $K$ terms reads the transform at $\lambda s$ after $K - 1$ terms. On a lattice of step $|\ln \lambda|$ in $\ln s$ that is the next point below, and a Gaussian state carries the location and the last deviations at each point, so each count costs one step at each point.

Algorithm

  1. Make the lattice with estimated_bias_lattice.
  2. For each count up to $K_{h} = \lceil \ln \sqrt{\epsilon} / \ln \lambda \rceil$, advance the lattice with estimated_bias_count!, take the integrals with estimated_bias_integrals!, and the factor with estimated_bias_factor.
  3. Past $K_{h}$ the factor changes as $\lambda^{K}$, and so does the pre-centred one. Each count takes the pre-centred factor times the ratio of the two at $K_{h}$.

Where the estimate is positive definite, the table agrees with the eigenvalues of a dense $M$ on a grid of step $1/200$ to $10^{-12}$. Where it is not, the cut moves with the lattice, as in regime_bias_table, and the table agrees with that grid to $5 \times 10^{-5}$ at the first indefinite counts of a half-life of 10 and two lags, and to $10^{-9}$ from 20 counts. The rule of step 3 is within $2 \times 10^{-11}$ of the recursion at a half-life of 40 and two lags, and within $4 \times 10^{-9}$ at a half-life of 5 and four lags. The table to the saturation count costs 0.1 s at a half-life of 40 and two lags.

Arguments

  • method::Union{RegimeAdjustedMethod, RegimeTermMoments}: Regime adjustment method, or the table of the moments of one term.
  • decay::Number: Decay of the weights.
  • K::Integer: Largest count of terms in the table.
  • hac_lags::Option{<:Integer}: Count of HAC lags, or nothing.
  • ::EstimatedCentring: The centring of the estimator.
  • debias::Option{<:AbstractRegimeDebias}: The debias rule. ExactDebias, the default, reads the dependence of the deviation on the estimate, and LawDebias the law of the estimate alone.

Returns

  • table::AbstractVector: The factor for each count, or the moments of RegimeTermMoments.

Related

source
Statistics.var — Method
Statistics.var(
    ce::RegimeAdjustedExpWeightedVariance,
    X::MatNum;
    dims::Int = 1,
    estimation_mask::Option{<:AbstractMatrix{<:Bool}} = nothing,
    active_mask::Option{<:AbstractMatrix{<:Bool}} = nothing,
    kwargs...
) -> Vector{<:Number}

Compute the regime-adjusted exponentially weighted variance for each asset.

The method steps an online variance cache over the observations of X. After the last observation, it divides each variance by the weight that the zero seed leaves, and it scales the result by the square of the regime multiplier.

Arguments

  • ce: Regime-adjusted exponentially weighted variance estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • dims: Dimension along which the computation runs.
  • estimation_mask: Optional boolean matrix of the size of X. Where it is set, the regime state at observation i reads only the assets where estimation_mask[i, :] (or [:, i]) is true.
  • active_mask: Optional boolean matrix of the size of X. Where it is set, an asset that becomes inactive restarts its variance and its observation count from zero.
  • kwargs: More keyword arguments, which the method ignores.

Validation

  • dims in (1, 2).
  • If estimation_mask is not nothing, size(X) == size(estimation_mask).
  • If active_mask is not nothing, size(X) == size(active_mask).

Returns

  • var::Vector{<:Number}: Per-asset regime-adjusted exponentially weighted variance vector of length assets. The variance of an asset with fewer than ce.min_obs observations, or of an asset that is not active, is NaN.

Related

source
Statistics.var — Method
Statistics.var(ce::RegimeAdjustedExpWeightedVariance, X::MatNum,
               pnl::Option{<:AssetPanel}; dims::Int = 1, kwargs...) -> MatNum
Statistics.std(ce::RegimeAdjustedExpWeightedVariance, X::MatNum,
               pnl::Option{<:AssetPanel}; dims::Int = 1, kwargs...) -> MatNum
variance_series(ce::RegimeAdjustedExpWeightedVariance, X::MatNum,
                pnl::Option{<:AssetPanel}; dims::Int = 1, kwargs...) -> MatNum

Take the whole window, and read the two universe masks of the Asset Panel.

RegimeAdjustedExpWeightedVariance is mask-aware, so it overrides the reduce-and-expand root of its verb. Its recursion holds its own warm-up, its freeze on a holiday and its reset over an inactive period. So it returns its own frame over the whole window, and it does not take a clean block from coverage_reduction. An asset outside the Coverage Universe therefore keeps a number here, where a plain estimator gives NaN.

The panel is the third positional argument. The method unpacks it onto the active_mask and estimation_mask keywords of the two-argument method. No panel and a static panel both give the path with no mask.

Algorithm

  1. Read the two masks with panel_moment_masks.
  2. Delegate to the two-argument method with them on its keywords.

Arguments

  • ce: Covariance estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • pnl: Optional AssetPanel. The Coverage Universe of the fit comes from its active mask. If it is nothing, the rule reads only the finiteness of the returns.
  • dims: Dimension along which the computation runs.
  • kwargs...: Additional keyword arguments passed to the two-argument method.

Returns

  • sigma::MatNum: The variance, or the standard deviation, of every asset of the window.

Related

source
PortfolioOptimisers.partial_fit! — Method
partial_fit!(
    est::Union{AbstractEstimator, CovarianceEstimator},
    X::Union{AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, AbstractVector{<:Union{Number, AbstractJuMPScalar}}};
    dims,
    active_mask,
    estimation_mask,
    iv,
    ivpa
) -> Covariance{<:AbstractExpectedReturnsEstimator, <:CovarianceEstimator, <:AbstractMomentAlgorithm}

Folds observations into the sample buffer an estimator carries.

This is the buffering arm of partial_fit!. Each estimator that carries a SampleBufferState reaches this method. A family that folds exactly has methods of its own, and each of them narrows the cache type parameter of its estimator to the state of that fold. So a buffer never reaches them, and it reaches this method. The type of the state selects the route, and no method refuses the step.

The method covers both arms of the interface. The families that refuse the step also declare one method over both arms, and two narrower methods here would be ambiguous against each of them. So the body selects the arm by the type of X, and the compiler resolves that branch at each call site.

A buffer carries the per-observation masks beside the observations. So a CoveragePolicy mask goes through the wrapper as it goes through the accumulator of an estimator, and the call with no data gives it back to the batch verb. A wrapped estimator folded under a policy gives the answer of a batch fit over the same window under the same policy. The implied volatilities and ivpa go through the wrapper in the same way, so a wrapped estimator that reads them, such as an ImpliedVolatility inside a PortfolioOptimisersCovariance, gives the answer of a batch fit over the same rows.

Algorithm

  1. Read the buffer out of the cache field with assert_sample_buffer, which refuses an estimator that was never wrapped in Online.
  2. Fold a matrix, its masks and its implied volatilities through the block arm of partial_fit!, and a vector, its masks and its implied volatilities through the single-observation arm.
  3. Rebuild the estimator with the new buffer in cache through rebuild_struct, and return it.

Arguments

  • est: Estimator whose buffer is folded forward.
  • X: Observations to fold. A matrix holds one observation per row when dims == 1, and one per column when dims == 2. A vector is a single observation across the assets, and dims is ignored.
  • dims: Dimension along which the computation runs.
  • active_mask: The active mask of the block, of the shape of X, or of one entry per asset when X is one observation, or nothing.
  • estimation_mask: The estimation mask, on the same terms as active_mask.
  • iv: The implied volatilities, on the same terms as active_mask.
  • ivpa: The implied volatility risk premium adjustment, or nothing.

Validation

  • est carries a SampleBufferState. An ArgumentError is thrown otherwise.
  • The masks and iv, when they are not nothing, have the shape of X. A DimensionMismatch is thrown otherwise.
  • A buffer that holds observations receives the masks that it records, and it receives iv if and only if it records implied volatilities. An ArgumentError is thrown otherwise.
  • ivpa equals the adjustment that the first append pinned. An ArgumentError is thrown otherwise.
  • dims in (1, 2).

Returns

  • est: The estimator, with its cache field rebound to the buffer after the last observation.

Related

source
PortfolioOptimisers.partial_fit! — Method
partial_fit!(
    est::Union{AbstractEstimator, CovarianceEstimator},
    X::Union{AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, AbstractVector{<:Union{Number, AbstractJuMPScalar}}};
    dims,
    active_mask,
    estimation_mask,
    iv,
    ivpa
) -> Covariance{<:AbstractExpectedReturnsEstimator, <:CovarianceEstimator, <:AbstractMomentAlgorithm}

Folds observations into the sample buffer an estimator carries.

This is the buffering arm of partial_fit!. Each estimator that carries a SampleBufferState reaches this method. A family that folds exactly has methods of its own, and each of them narrows the cache type parameter of its estimator to the state of that fold. So a buffer never reaches them, and it reaches this method. The type of the state selects the route, and no method refuses the step.

The method covers both arms of the interface. The families that refuse the step also declare one method over both arms, and two narrower methods here would be ambiguous against each of them. So the body selects the arm by the type of X, and the compiler resolves that branch at each call site.

A buffer carries the per-observation masks beside the observations. So a CoveragePolicy mask goes through the wrapper as it goes through the accumulator of an estimator, and the call with no data gives it back to the batch verb. A wrapped estimator folded under a policy gives the answer of a batch fit over the same window under the same policy. The implied volatilities and ivpa go through the wrapper in the same way, so a wrapped estimator that reads them, such as an ImpliedVolatility inside a PortfolioOptimisersCovariance, gives the answer of a batch fit over the same rows.

Algorithm

  1. Read the buffer out of the cache field with assert_sample_buffer, which refuses an estimator that was never wrapped in Online.
  2. Fold a matrix, its masks and its implied volatilities through the block arm of partial_fit!, and a vector, its masks and its implied volatilities through the single-observation arm.
  3. Rebuild the estimator with the new buffer in cache through rebuild_struct, and return it.

Arguments

  • est: Estimator whose buffer is folded forward.
  • X: Observations to fold. A matrix holds one observation per row when dims == 1, and one per column when dims == 2. A vector is a single observation across the assets, and dims is ignored.
  • dims: Dimension along which the computation runs.
  • active_mask: The active mask of the block, of the shape of X, or of one entry per asset when X is one observation, or nothing.
  • estimation_mask: The estimation mask, on the same terms as active_mask.
  • iv: The implied volatilities, on the same terms as active_mask.
  • ivpa: The implied volatility risk premium adjustment, or nothing.

Validation

  • est carries a SampleBufferState. An ArgumentError is thrown otherwise.
  • The masks and iv, when they are not nothing, have the shape of X. A DimensionMismatch is thrown otherwise.
  • A buffer that holds observations receives the masks that it records, and it receives iv if and only if it records implied volatilities. An ArgumentError is thrown otherwise.
  • ivpa equals the adjustment that the first append pinned. An ArgumentError is thrown otherwise.
  • dims in (1, 2).

Returns

  • est: The estimator, with its cache field rebound to the buffer after the last observation.

Related

source
Statistics.var — Method
Statistics.var(
    ce::RegimeAdjustedExpWeightedVariance,
    state::RegimeAdjustedVarianceState;
    kwargs...
) -> Vector{<:Number}

Read the regime-adjusted variance out of a state held by hand.

This is regime_adjusted_variance under the public verb of the family. So a state that a caller keeps outside an estimator answers the same call as a state that the estimator holds. The method reads the state and never writes it.

Arguments

  • ce: Regime-adjusted exponentially weighted variance estimator.
  • state: Running state of an incremental fit.
  • kwargs: More keyword arguments, which the method ignores.

Returns

  • var::Vector{<:Number}: Per-asset regime-adjusted exponentially weighted variance vector of length assets. An asset with fewer than ce.min_obs observations is NaN.

Examples

julia> X = [0.01 -0.02; -0.015 0.03; 0.02 -0.01; -0.005 0.012];julia> ce = partial_fit!(RegimeAdjustedExpWeightedVariance(; decay = 0.9, min_obs = 2,                                                           regime_min_obs = 2), X);julia> isequal(var(ce, ce.cache), var(ce))true

Related

source
Statistics.var — Method
Statistics.var(ce::RegimeAdjustedExpWeightedVariance; kwargs...) -> Vector{<:Number}

Read the regime-adjusted variance out of the estimator's own state.

partial_fit! leaves the state in the cache field, and this one-argument form turns it into the variance. An estimator that has folded no observation carries no state, so the method refuses the call and does not return a zero.

Arguments

  • ce: Regime-adjusted exponentially weighted variance estimator that holds a state.
  • kwargs: More keyword arguments, which the method ignores.

Validation

  • ce.cache is not nothing. An ArgumentError is thrown otherwise.

Returns

  • var::Vector{<:Number}: Per-asset regime-adjusted exponentially weighted variance vector of length assets. An asset with fewer than ce.min_obs observations is NaN.

Examples

julia> X = [0.01 -0.02; -0.015 0.03; 0.02 -0.01; -0.005 0.012];julia> ce = partial_fit!(RegimeAdjustedExpWeightedVariance(; decay = 0.9, min_obs = 2,                                                           regime_min_obs = 2), X);julia> length(var(ce))2julia> var(RegimeAdjustedExpWeightedVariance())ERROR: ArgumentError: `ce` holds no partial-fit state, so there is nothing to read. Call `partial_fit!(ce, X)` first, or `var(ce, X)` for a fit over a whole sample.[...]

Related

source
Statistics.std — Method
Statistics.std(
    ce::RegimeAdjustedExpWeightedVariance,
    X::MatNum;
    dims::Int = 1,
    estimation_mask::Option{<:AbstractMatrix{<:Bool}} = nothing,
    active_mask::Option{<:AbstractMatrix{<:Bool}} = nothing,
    kwargs...
) -> Vector{<:Number}

Compute the regime-adjusted exponentially weighted standard deviation for each asset.

It is the root of Statistics.var(ce::RegimeAdjustedExpWeightedVariance, X::MatNum; dims::Int = 1, estimation_mask::Option{<:AbstractMatrix{<:Bool}} = nothing, active_mask::Option{<:AbstractMatrix{<:Bool}} = nothing, kwargs...). The variance is a non-negative exponentially weighted average scaled by a squared multiplier, so the root is real. An asset that var answers with NaN stays NaN.

Arguments

  • ce: Regime-adjusted exponentially weighted variance estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • dims: Dimension along which the computation runs.
  • estimation_mask: Optional boolean matrix of the size of X. Where it is set, the regime state at observation i reads only the assets where estimation_mask[i, :] (or [:, i]) is true.
  • active_mask: Optional boolean matrix of the size of X. Where it is set, an asset that becomes inactive restarts its variance and its observation count from zero.
  • kwargs: More keyword arguments, which the method ignores.

Validation

  • dims in (1, 2).
  • If estimation_mask is not nothing, size(X) == size(estimation_mask).
  • If active_mask is not nothing, size(X) == size(active_mask).

Returns

  • std::Vector{<:Number}: Per-asset regime-adjusted exponentially weighted standard deviation vector of length assets. The standard deviation of an asset with fewer than ce.min_obs observations, or of an asset that is not active, is NaN.

Examples

julia> X = [0.01 -0.02; -0.015 0.03; 0.02 -0.01; -0.005 0.012];julia> ce = RegimeAdjustedExpWeightedVariance(; decay = 0.9, min_obs = 2, regime_min_obs = 2);julia> isapprox(std(ce, X), sqrt.(var(ce, X)))true

Related

source
Statistics.std — Method
Statistics.std(
    ce::RegimeAdjustedExpWeightedVariance,
    state::RegimeAdjustedVarianceState;
    kwargs...
) -> Vector{<:Number}

Read the regime-adjusted standard deviation out of a state held by hand.

It is the root of Statistics.var(ce::RegimeAdjustedExpWeightedVariance, state::RegimeAdjustedVarianceState; kwargs...). So a state that a caller keeps outside an estimator answers the same call as a state that the estimator holds. The method reads the state and never writes it.

Arguments

  • ce: Regime-adjusted exponentially weighted variance estimator.
  • state: Running state of an incremental fit.
  • kwargs: More keyword arguments, which the method ignores.

Returns

  • std::Vector{<:Number}: Per-asset regime-adjusted exponentially weighted standard deviation vector of length assets. An asset with fewer than ce.min_obs observations is NaN.

Examples

julia> X = [0.01 -0.02; -0.015 0.03; 0.02 -0.01; -0.005 0.012];julia> ce = partial_fit!(RegimeAdjustedExpWeightedVariance(; decay = 0.9, min_obs = 2,                                                           regime_min_obs = 2), X);julia> isequal(std(ce, ce.cache), std(ce))true

Related

source
Statistics.std — Method
Statistics.std(ce::RegimeAdjustedExpWeightedVariance; kwargs...) -> Vector{<:Number}

Read the regime-adjusted standard deviation out of the estimator's own state.

partial_fit! leaves the state in the cache field, and this one-argument form turns it into the standard deviation. An estimator that has folded no observation carries no state, so the method refuses the call and does not return a zero.

Arguments

  • ce: Regime-adjusted exponentially weighted variance estimator that holds a state.
  • kwargs: More keyword arguments, which the method ignores.

Validation

  • ce.cache is not nothing. An ArgumentError is thrown otherwise.

Returns

  • std::Vector{<:Number}: Per-asset regime-adjusted exponentially weighted standard deviation vector of length assets. An asset with fewer than ce.min_obs observations is NaN.

Examples

julia> X = [0.01 -0.02; -0.015 0.03; 0.02 -0.01; -0.005 0.012];julia> ce = partial_fit!(RegimeAdjustedExpWeightedVariance(; decay = 0.9, min_obs = 2,                                                           regime_min_obs = 2), X);julia> length(std(ce))2julia> std(RegimeAdjustedExpWeightedVariance())ERROR: ArgumentError: `ce` holds no partial-fit state, so there is nothing to read. Call `partial_fit!(ce, X)` first, or `std(ce, X)` for a fit over a whole sample.[...]

Related

source
PortfolioOptimisers.merge_states — Method
merge_states(
    a::RegimeAdjustedVarianceState,
    b::RegimeAdjustedVarianceState
) -> Union{}

Refuses a pair of regime-adjusted states, because this family does not merge.

A merge needs the state of a block to be a sufficient statistic for what that block contributes, and this state is not one. The regime state reads the standardised squared return of each observation. That score divides by the running variance, and the running observation count gates it. So a block fitted from a cold start weighs its first observations differently from the same block fitted after another block. The exponentially weighted accumulator folds as $\lambda^{n_B} v_A + v_B$, but the regime state that scales it does not fold. A fit under EstimatedCentring also holds its running location, and a HAC fit holds its buffer of recent returns.

Fold the second block into the first with partial_fit!. A sequential fit is exact.

Arguments

  • a: The state of the first block of observations.
  • b: The state of the second block of observations.

Validation

  • a and b pass assert_mergeable_states, so a mismatched pair is named as such.
  • The method then refuses the pair with an ArgumentError, whatever it holds.

Returns

  • The method always throws, so it returns no value.

Examples

julia> X = [0.01 -0.02; -0.015 0.03; 0.02 -0.01; -0.005 0.012];julia> ce = partial_fit!(RegimeAdjustedExpWeightedVariance(; decay = 0.9, min_obs = 2,                                                           regime_min_obs = 2), X);julia> try           PortfolioOptimisers.merge_states(ce.cache, ce.cache)       catch err           err isa ArgumentError       endtrue

Related

source

References

[18]
W. K. Newey and K. D. West. A simple, positive semi-definite, heteroskedasticity and autocorrelation consistent covariance matrix. Econometrica 55, 703–708 (1987).
[79]
J. Menchero, D. J. Orr and J. Wang. The Barra US Equity Model (USE4): Methodology Notes (MSCI, 2011).
[80]
G. A. Paleologo. The Elements of Quantitative Investing (Wiley, 2025).