Regime adjusted exp weighted variance
Types
PortfolioOptimisers.RegimeAdjustedMethod — Type
abstract type RegimeAdjustedMethod <: AbstractEstimatorNames 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, overnscored 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
LogRegimeAdjustedFirstMomentRegimeAdjustedRootMeanSquaredAdjustedRegimeAdjustedExpWeightedVarianceRegimeAdjustedExpWeightedCovariance
References
PortfolioOptimisers.LogRegimeAdjusted — Type
struct LogRegimeAdjusted{__T_x, __T_y, __T_kappa} <: RegimeAdjustedMethodScales 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_valfield 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 constantdigamma(x) + log(y)for the log regime adjustment.
Constructors
LogRegimeAdjusted(; x::Number = 0.5, y::Number = 2.0) -> LogRegimeAdjustedKeywords 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, andxis finite.y > 0, andyis finite.
Examples
julia> LogRegimeAdjusted()LogRegimeAdjusted x ┼ Float64: 0.5 y ┼ Float64: 2.0 kappa ┴ Float64: -1.2703628454614782Related
RegimeAdjustedMethodFirstMomentRegimeAdjustedRootMeanSquaredAdjustedRegimeAdjustedExpWeightedVariance
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.
PortfolioOptimisers.FirstMomentRegimeAdjusted — Type
struct FirstMomentRegimeAdjusted{__T_x} <: RegimeAdjustedMethodScales 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(π))) -> FirstMomentRegimeAdjustedKeywords correspond to the struct's fields.
Validation
x > 0, andxis finite.
Examples
julia> FirstMomentRegimeAdjusted()FirstMomentRegimeAdjusted x ┴ Float64: 0.7978845608028654Related
References
- [80] G. A. Paleologo. The Elements of Quantitative Investing. Wiley (2025). Section 6.3.3, page 124, Equation 6.11.
PortfolioOptimisers.RootMeanSquaredAdjusted — Type
struct RootMeanSquaredAdjusted <: RegimeAdjustedMethodScales 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.
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} <: AbstractVarianceEstimatorEstimates 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
EstimatedCentringit 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, asExpWeightedVariancestates. UnderPreCentredit is the return. - $q_{i,t}$: Term of the recursion. Where
hac_lagsisnothing, $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 leastmin_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_tablefor the moment that the method reads, or one underdebias = 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. UnderExactDebiasthe 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 ofRootMeanSquaredAdjustedover 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
RegimeAdjustedMethodstates 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_decayfield. - $\hat{\sigma}_{i}^{2}$: Regime-adjusted variance of asset $i$. It is
NaNwhere $K_{i,T}$ is belowmin_obs, or where the asset is not active. - $m$: Multiplier of the report. It is one while fewer than
regime_min_obsobservations have scored an asset, and whereregime_methodisnothing. - $\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 isnothing, 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. Ifnothing, 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, sonothing, the default, keeps the recursion an unbiased quadratic form and floors only the variance that the estimator returns.PerTermHacFloorfloors each square.
regime_method: Regime adjustment method that computes the regime statistic of each observation, ornothingfor no regime adjustment.
regime_decay: Exponential decay factor of the regime state. A value above2^(-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. Ifnothing, 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.PreCentredtakes the returns as deviations from a mean of zero.ZeroStartCentringtakes 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). UnderExactDebias, the default, the statistic skips an estimate ofn + 3terms or fewer, forndirections. Wherehac_lagsis set, it also skips an estimate whose effective count of terms isn + 1or fewer. It divides the rest by the bias factor that itsregime_methodreads. 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.LawDebiasdivides by the law of the estimate alone, and takes the deviation as independent of the estimate.nothingscores the raw statistic.
cache: Running state of an incremental fit, ornothingbefore the first call topartial_fit!. It is the one Result this estimator holds, and its type bound is the enforcement of that exception.Statistics.var(ce::RegimeAdjustedExpWeightedVariance)reads it, and a fit over a matrix ignores it.
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) -> RegimeAdjustedExpWeightedVarianceKeywords correspond to the struct's fields.
Validation
0 < decay < 1.min_obs > 0.- If
hac_lagsis notnothing,hac_lags > 0. 0 < regime_decay < 1.regime_min_obs > 0.- If
regime_lohi_multis notnothing,0 < regime_lohi_mult[1] < regime_lohi_mult[2].
Examples
julia> ce = RegimeAdjustedExpWeightedVariance();julia> ce.decay ≈ exp2(-inv(40.0))truejulia> ce.min_obs40Related
RegimeAdjustedMethodLogRegimeAdjustedFirstMomentRegimeAdjustedRootMeanSquaredAdjustedAbstractVarianceEstimatorpartial_fit!scenario_fillEmpiricalPrior
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.
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 multiplierexp(regime_state / 2).
Related
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 toregime_state.
Related
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 multipliersqrt(max(regime_state, 0)).
Related
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 ofz2_valid.
Related
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
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
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
- 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.
- For each $K$, multiply $G$ by $(1 + \lambda^{K - 1} s)^{-1/2}$ on the log scale, so the whole table costs one pass.
- 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 thehac_lagsof 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 toK, or the moments ofRegimeTermMoments.
Related
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. Wherehac_lagsis a vector, $L$ is its length and $k_{i}$ its entries, such as the kernel ofhac_row_kernel.
Algorithm
- Lay the grid of
regime_bias_table. - 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. - Cut the transform at its minimum with
hac_laplace!, and evaluate the factor of the method withregime_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 toK, or the moments ofRegimeTermMoments.
Related
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, ornothing.centring::AbstractCentring: The centring of the estimator.debias::Option{<:AbstractRegimeDebias}: The debias rule,ExactDebiasby default.
Returns
table::AbstractVector: The factor for each count, or the moments ofRegimeTermMoments.
Related
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
- Make the lattice with
estimated_bias_lattice. - For each count up to $K_{h} = \lceil \ln \sqrt{\epsilon} / \ln \lambda \rceil$, advance the lattice with
estimated_bias_count!, take the integrals withestimated_bias_integrals!, and the factor withestimated_bias_factor. - 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, ornothing.::EstimatedCentring: The centring of the estimator.debias::Option{<:AbstractRegimeDebias}: The debias rule.ExactDebias, the default, reads the dependence of the deviation on the estimate, andLawDebiasthe law of the estimate alone.
Returns
table::AbstractVector: The factor for each count, or the moments ofRegimeTermMoments.
Related
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 matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.dims: Dimension along which the computation runs.estimation_mask: Optional boolean matrix of the size ofX. Where it is set, the regime state at observationireads only the assets whereestimation_mask[i, :](or[:, i]) istrue.active_mask: Optional boolean matrix of the size ofX. 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_maskis notnothing,size(X) == size(estimation_mask). - If
active_maskis notnothing,size(X) == size(active_mask).
Returns
var::Vector{<:Number}: Per-asset regime-adjusted exponentially weighted variance vector of lengthassets. The variance of an asset with fewer thance.min_obsobservations, or of an asset that is not active, isNaN.
Related
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...) -> MatNumTake 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
- Read the two masks with
panel_moment_masks. - Delegate to the two-argument method with them on its keywords.
Arguments
ce: Covariance estimator.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.pnl: OptionalAssetPanel. The Coverage Universe of the fit comes from its active mask. If it isnothing, 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
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
- Read the buffer out of the
cachefield withassert_sample_buffer, which refuses an estimator that was never wrapped inOnline. - 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. - Rebuild the estimator with the new buffer in
cachethroughrebuild_struct, and return it.
Arguments
est: Estimator whose buffer is folded forward.X: Observations to fold. A matrix holds one observation per row whendims == 1, and one per column whendims == 2. A vector is a single observation across the assets, anddimsis ignored.dims: Dimension along which the computation runs.active_mask: The active mask of the block, of the shape ofX, or of one entry per asset whenXis one observation, ornothing.estimation_mask: The estimation mask, on the same terms asactive_mask.iv: The implied volatilities, on the same terms asactive_mask.ivpa: The implied volatility risk premium adjustment, ornothing.
Validation
estcarries aSampleBufferState. AnArgumentErroris thrown otherwise.- The masks and
iv, when they are notnothing, have the shape ofX. ADimensionMismatchis thrown otherwise. - A buffer that holds observations receives the masks that it records, and it receives
ivif and only if it records implied volatilities. AnArgumentErroris thrown otherwise. ivpaequals the adjustment that the first append pinned. AnArgumentErroris thrown otherwise.dims in (1, 2).
Returns
est: The estimator, with itscachefield rebound to the buffer after the last observation.
Related
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
- Read the buffer out of the
cachefield withassert_sample_buffer, which refuses an estimator that was never wrapped inOnline. - 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. - Rebuild the estimator with the new buffer in
cachethroughrebuild_struct, and return it.
Arguments
est: Estimator whose buffer is folded forward.X: Observations to fold. A matrix holds one observation per row whendims == 1, and one per column whendims == 2. A vector is a single observation across the assets, anddimsis ignored.dims: Dimension along which the computation runs.active_mask: The active mask of the block, of the shape ofX, or of one entry per asset whenXis one observation, ornothing.estimation_mask: The estimation mask, on the same terms asactive_mask.iv: The implied volatilities, on the same terms asactive_mask.ivpa: The implied volatility risk premium adjustment, ornothing.
Validation
estcarries aSampleBufferState. AnArgumentErroris thrown otherwise.- The masks and
iv, when they are notnothing, have the shape ofX. ADimensionMismatchis thrown otherwise. - A buffer that holds observations receives the masks that it records, and it receives
ivif and only if it records implied volatilities. AnArgumentErroris thrown otherwise. ivpaequals the adjustment that the first append pinned. AnArgumentErroris thrown otherwise.dims in (1, 2).
Returns
est: The estimator, with itscachefield rebound to the buffer after the last observation.
Related
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 lengthassets. An asset with fewer thance.min_obsobservations isNaN.
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))trueRelated
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.cacheis notnothing. AnArgumentErroris thrown otherwise.
Returns
var::Vector{<:Number}: Per-asset regime-adjusted exponentially weighted variance vector of lengthassets. An asset with fewer thance.min_obsobservations isNaN.
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
partial_fit!(ce::RegimeAdjustedExpWeightedVariance, X::MatNum; dims::Int = 1, estimation_mask::Option{<:AbstractMatrix{<:Bool}} = nothing, active_mask::Option{<:AbstractMatrix{<:Bool}} = nothing, kwargs...)Statistics.var(ce::RegimeAdjustedExpWeightedVariance, state::RegimeAdjustedVarianceState; kwargs...)RegimeAdjustedVarianceState
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 matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.dims: Dimension along which the computation runs.estimation_mask: Optional boolean matrix of the size ofX. Where it is set, the regime state at observationireads only the assets whereestimation_mask[i, :](or[:, i]) istrue.active_mask: Optional boolean matrix of the size ofX. 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_maskis notnothing,size(X) == size(estimation_mask). - If
active_maskis notnothing,size(X) == size(active_mask).
Returns
std::Vector{<:Number}: Per-asset regime-adjusted exponentially weighted standard deviation vector of lengthassets. The standard deviation of an asset with fewer thance.min_obsobservations, or of an asset that is not active, isNaN.
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)))trueRelated
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 lengthassets. An asset with fewer thance.min_obsobservations isNaN.
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))trueRelated
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.cacheis notnothing. AnArgumentErroris thrown otherwise.
Returns
std::Vector{<:Number}: Per-asset regime-adjusted exponentially weighted standard deviation vector of lengthassets. An asset with fewer thance.min_obsobservations isNaN.
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
partial_fit!(ce::RegimeAdjustedExpWeightedVariance, X::MatNum; dims::Int = 1, estimation_mask::Option{<:AbstractMatrix{<:Bool}} = nothing, active_mask::Option{<:AbstractMatrix{<:Bool}} = nothing, kwargs...)Statistics.std(ce::RegimeAdjustedExpWeightedVariance, state::RegimeAdjustedVarianceState; kwargs...)Statistics.var(ce::RegimeAdjustedExpWeightedVariance; kwargs...)
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
aandbpassassert_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 endtrueRelated
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).