Covariance Forecast Evaluation

covariance_forecast_evaluation scores a covariance forecast against the returns that come after it, one step at a time over a walk-forward. It runs through PortfolioOptimisers.fold_loop. A fold with a training window refits the estimator on that window, and a fold of an online walk-forward updates the estimator and reads its current estimate. The choice of walk-forward and of Online gives the four forms, an expanding or a rolling window, fitted in batch or online. A realised-quantity type, one of the types below, sets what the forecast is scored against. The evaluation subtracts from each test return the centre that the estimator used, such as the mean it fitted, and the loss of each step is a function of plain arrays.

PortfolioOptimisers.RealisedCovariance — Type
struct RealisedCovariance <: AbstractRealisedTarget

Judges a covariance forecast against the realised covariance of the returns that follow it.

This is the default target. It sums the outer products of the centred returns of the step, one per row. Under a Gaussian null the Mahalanobis ratio of the step then has variance $2 / (N h)$, smaller by a factor of $h$ than under HorizonReturn. The two targets cost the same to compute, so the default is the one with the smaller variance. It asks whether the forecast describes the dispersion of each observation.

Mathematical definition

\[\begin{align} \mathbf{S}_t &= \sum_{s=1}^{h} \boldsymbol{z}_{t+s} \boldsymbol{z}_{t+s}^\intercal\,, \\ \mathbb{E}\left[\mathbf{S}_t \mid \mathcal{F}_t\right] &= h\, \mathbf{\Sigma}_t\,. \end{align}\]

Where:

  • $\mathbf{S}_t$: Realised covariance of step $t$, formed from the centred returns that follow it.
  • $h$: Horizon of a step, the number of observations the forecast is judged on.
  • $\boldsymbol{z}_{t+s}$: Centred return of observation $t + s$, the return less the location the forecast is about.
  • $\mathbf{\Sigma}_t$: True conditional covariance of the returns that follow step $t$.
  • $\mathcal{F}_t$: Information available at step $t$.

The expectation holds when the $h$ returns are serially uncorrelated. It makes $\mathbf{S}_t / h$ a conditionally unbiased proxy of $\mathbf{\Sigma}_t$ for every distribution of the returns. At $h = 1$ the proxy has rank one and equals the proxy of HorizonReturn. A cell whose two assets share no finite row is zero, and its count is zero.

Examples

julia> RealisedCovariance()RealisedCovariance()

Related

source
PortfolioOptimisers.HorizonReturn — Type
struct HorizonReturn <: AbstractRealisedTarget

Judges a covariance forecast against the outer product of the return earned over the horizon.

It asks the question of a holder over the $h$ observations of the step. The return summed over the step is what a book held for the whole horizon earns, and its outer product is a rank-one proxy of $h\, \mathbf{\Sigma}_t$. Under a Gaussian null the Mahalanobis ratio of the step has variance $2 / N$ at every $h$, so this target is the noisier of the two at every horizon above one.

Mathematical definition

\[\begin{align} \boldsymbol{R}_t &= \sum_{s=1}^{h} \boldsymbol{z}_{t+s}\,, \\ \mathbf{S}_t &= \boldsymbol{R}_t \boldsymbol{R}_t^\intercal\,, \\ \mathbb{E}\left[\mathbf{S}_t \mid \mathcal{F}_t\right] &= h\, \mathbf{\Sigma}_t\,. \end{align}\]

Where:

  • $\boldsymbol{R}_t$: Return earned over the horizon of step $t$, summed over the finite observations of each asset.
  • $\mathbf{S}_t$: Realised covariance of step $t$, formed from the centred returns that follow it.
  • $h$: Horizon of a step, the number of observations the forecast is judged on.
  • $\boldsymbol{z}_{t+s}$: Centred return of observation $t + s$, the return less the location the forecast is about.
  • $\mathbf{\Sigma}_t$: True conditional covariance of the returns that follow step $t$.
  • $\mathcal{F}_t$: Information available at step $t$.

The expectation holds when the $h$ returns are serially uncorrelated. At $h = 1$ the proxy equals the proxy of RealisedCovariance. A non-finite cell adds nothing to the sum, and the count of a cell is the number of rows at which both of its assets are finite.

Examples

julia> HorizonReturn()HorizonReturn()

Related

source
PortfolioOptimisers.CovarianceForecastEvaluationResult — Type
struct CovarianceForecastEvaluationResult{__T_dates, __T_test_idx, __T_horizon, __T_target, __T_x_src<:AbstractReturnsSource, __T_n_valid, __T_mahalanobis_ratio, __T_diagonal_ratio, __T_qlike, __T_frobenius, __T_standardised_return, __T_portfolio_qlike, __T_w, __T_sigma, __T_location} <: AbstractResult

The per-step diagnostics of a covariance forecast over a walk-forward, and its forecasts on request.

CovarianceForecastEvaluationResult is what covariance_forecast_evaluation returns. It keeps every diagnostic per step, four that read the forecast on its own and two per test portfolio. The summary, the comparison and the plots are verbs over it. It keeps the forecasts themselves only on request. A run of M steps over N assets holds N² × M numbers of forecasts against N × M diagonal ratios, and the online form is meant for a step at every observation.

Fields

  • dates: Label of each step, one entry per step. It is the timestamp of the first test row of the step when the returns data holds timestamps, and the index of that row otherwise.
  • test_idx: Test rows of each step, one window per step, in the order of the split.
  • horizon: Horizon of each step, the number of test rows that the evaluation judged the forecast on, one entry per step. Every entry is the test_size of the scheme under an index walk-forward, and the length of the calendar period under a date walk-forward.
  • target: Realised quantity that the evaluation judged the forecasts against.
  • x_src: The source of the returns that the evaluation read, DataSource or ExcessSource. An evaluation at x_src = nothing records DataSource(). The forecasts are forecasts of the returns in this frame, so covariance_forecast_portfolio reads its test rows in it.
  • n_valid: Number of active assets at each step, one entry per step. An active asset has a finite forecast variance, a finite location and at least one finite test return. A step with no active asset is unscored: its count is 0 and every diagnostic of the step is NaN.
  • mahalanobis_ratio: Mahalanobis ratio of each step, one entry per step. Its target value is one.
  • diagonal_ratio: Diagonal ratio of each asset at each step, steps × assets, and NaN where the asset was not active. Its target value is one.
  • qlike: QLIKE loss of each step, one entry per step. Lower is better, and only the difference between two forecasts is a reading.
  • frobenius: Frobenius loss of each step, one entry per step. Lower is better, and only the difference between two forecasts is a reading.
  • standardised_return: Standardised return of each test portfolio at each step, steps × portfolios. Mean zero and standard deviation one under a calibrated forecast.
  • portfolio_qlike: QLIKE loss of the variance of each test portfolio at each step, steps × portfolios. Lower is better.
  • w: Test portfolios as the caller gave them to the evaluation. nothing means inverse volatility per step, a vector is one portfolio, and a vector of vectors is several.
  • sigma: Forecast of each step, one assets × assets matrix per step, or nothing unless store_forecasts = true.
  • location: Location that the evaluation centred each forecast on, one assets × 1 vector per step, or nothing unless store_forecasts = true.

Constructors

CovarianceForecastEvaluationResult(    dates, test_idx, horizon, target, x_src, n_valid, mahalanobis_ratio, diagonal_ratio,    qlike, frobenius, standardised_return, portfolio_qlike, w, sigma, location) -> CovarianceForecastEvaluationResult

The arguments correspond to the fields of the struct, in the order of their declaration. The type is a Result, which covariance_forecast_evaluation builds and a caller reads. It has no keyword constructor, and it validates nothing of its own. The bound of x_src admits an AbstractReturnsSource alone, so a positional Bool builds no Result.

Related

source
PortfolioOptimisers.CovarianceForecastStepResult — Type
struct CovarianceForecastStepResult{__T_n_valid, __T_mahalanobis_ratio, __T_diagonal_ratio, __T_qlike, __T_frobenius, __T_standardised_return, __T_portfolio_qlike} <: AbstractResult

The diagnostics of one step of a covariance forecast evaluation, from covariance_forecast_step.

covariance_forecast_evaluation collects one Result for each step into a CovarianceForecastEvaluationResult, and covariance_forecast_portfolio reads the two portfolio fields of each step. A caller who holds forecasts of their own reads the same fields. A step with no active asset is unscored: n_valid is 0 and every diagnostic is NaN.

Fields

  • n_valid: Count of the active assets of the step, the assets with a finite forecast variance, a finite location and at least one finite test return. 0 for an unscored step.
  • mahalanobis_ratio: Mahalanobis ratio of the step. The target is one.
  • diagonal_ratio: Diagonal ratio of each asset, assets × 1, and NaN outside the active assets. The target is one.
  • qlike: QLIKE loss of the step. Only a difference between two forecasts says which forecast is better.
  • frobenius: Frobenius loss of the step, over the cells with a positive count. Only a difference between two forecasts says which forecast is better.
  • standardised_return: Standardised return of each test portfolio, one entry per portfolio.
  • portfolio_qlike: QLIKE loss of the variance of each test portfolio, one entry per portfolio.

Constructors

CovarianceForecastStepResult(n_valid::Integer, mahalanobis_ratio::Number, diagonal_ratio::VecNum,                             qlike::Number, frobenius::Number, standardised_return::VecNum,                             portfolio_qlike::VecNum)CovarianceForecastStepResult(; n_valid::Integer, mahalanobis_ratio::Number,                             diagonal_ratio::VecNum, qlike::Number, frobenius::Number,                             standardised_return::VecNum, portfolio_qlike::VecNum)

The positional constructor checks the values. The keyword constructor takes each field by name, with no default, and calls it.

Validation

  • n_valid is not negative. Otherwise, the constructor raises a DomainError.
  • n_valid is at most length(diagonal_ratio), the count of assets. Otherwise, the constructor raises a DimensionMismatch.
  • standardised_return and portfolio_qlike hold one entry for each test portfolio, so they have the same length. Otherwise, the constructor raises a DimensionMismatch.
  • The keyword constructor refuses a value of another type than its signature states with a TypeError. The positional constructor checks only the types of its signature: the generic positional method that @concrete adds takes values of any other type, such as a Float64 count, with no check.

Related

source
PortfolioOptimisers.covariance_forecast_step — Function
covariance_forecast_step(sigma::MatNum, Z::MatNum, c::VecNum, w::Option{<:VecNum_VecVecNum}, target::AbstractRealisedTarget) -> CovarianceForecastStepResult

Score one covariance forecast against the returns realised after it.

This is the per-step kernel of covariance_forecast_evaluation. It takes bare arrays, so a caller who holds forecasts of their own can build the same Result by hand. The kernel reads the forecast on the assets that are active at the step, and centres the test rows on the location of the forecast. It then forms the realised matrix through the target and returns the diagnostics of the step in a CovarianceForecastStepResult. Four diagnostics read the forecast without a portfolio, and two more come once per test portfolio.

Mathematical definition

\[\begin{align} \mathbf{H}_{ij} &= \left\lvert \{ s : z_{t+s,i},\, z_{t+s,j} \text{ finite} \} \right\rvert\,, \\ m_t &= \frac{\operatorname{tr}\left(\left(\mathbf{H} \odot \hat{\mathbf{\Sigma}}_t\right)^{-1} \mathbf{S}_t\right)}{N}\,, \\ d_{t,i} &= \frac{(\mathbf{S}_t)_{ii}}{\mathbf{H}_{ii}\, (\hat{\mathbf{\Sigma}}_t)_{ii}}\,, \\ L^{\mathrm{QLIKE}}_t &= h \log\left|\hat{\mathbf{\Sigma}}_t\right| + N h\, m_t\,, \\ L^{\mathrm{F}}_t &= \sum_{i,j : \mathbf{H}_{ij} > 0} \left(\frac{(\mathbf{S}_t)_{ij}}{\mathbf{H}_{ij}} - (\hat{\mathbf{\Sigma}}_t)_{ij}\right)^2\,, \\ b_t &= \frac{\boldsymbol{w}^\intercal \boldsymbol{R}_t}{\sqrt{\boldsymbol{w}^\intercal \left(\mathbf{H} \odot \hat{\mathbf{\Sigma}}_t\right) \boldsymbol{w}}}\,, \\ L^{\mathrm{P}}_t &= \log\left(\boldsymbol{w}^\intercal \left(\mathbf{H} \odot \hat{\mathbf{\Sigma}}_t\right) \boldsymbol{w}\right) + \frac{\sum_{s=1}^{h} (\boldsymbol{w}^\intercal \boldsymbol{z}_{t+s})^2}{\boldsymbol{w}^\intercal \left(\mathbf{H} \odot \hat{\mathbf{\Sigma}}_t\right) \boldsymbol{w}}\,. \end{align}\]

Where:

  • $\mathbf{H}$: Pairwise count of the finite test observations of each pair of assets.
  • $\hat{\mathbf{\Sigma}}_t$: Covariance forecast formed at step $t$.
  • $\mathbf{S}_t$: Realised covariance of step $t$, formed from the centred returns that follow it.
  • $h$: Horizon of a step, the number of observations the forecast is judged on.
  • $N$: Number of assets.
  • $m_t$: Mahalanobis ratio of step $t$.
  • $d_{t,i}$: Diagonal ratio of asset $i$ at step $t$.
  • $L^{\mathrm{QLIKE}}_t$: QLIKE loss of step $t$.
  • $L^{\mathrm{F}}_t$: Frobenius loss of step $t$.
  • $b_t$: Standardised return of the test portfolio at step $t$.
  • $L^{\mathrm{P}}_t$: QLIKE loss of the test portfolio's variance at step $t$.
  • $\boldsymbol{R}_t$: Return earned over the horizon of step $t$, summed over the finite observations of each asset.
  • $\boldsymbol{z}_{t+s}$: Centred return of observation $t + s$, zero at a cell the asset did not trade.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.

With no gap in the test window $\mathbf{H} = h \mathbf{1}\mathbf{1}^\intercal$, and the forms reduce to $m_t = \operatorname{tr}(\hat{\mathbf{\Sigma}}_t^{-1} \mathbf{S}_t) / (N h)$, $d_{t,i} = (\mathbf{S}_t)_{ii} / (h (\hat{\mathbf{\Sigma}}_t)_{ii})$, $L^{\mathrm{QLIKE}}_t = h \log|\hat{\mathbf{\Sigma}}_t| + \operatorname{tr}(\hat{\mathbf{\Sigma}}_t^{-1} \mathbf{S}_t)$, $L^{\mathrm{F}}_t = \lVert \mathbf{S}_t / h - \hat{\mathbf{\Sigma}}_t \rVert_F^2$ and $b_t = \boldsymbol{w}^\intercal \boldsymbol{R}_t / \sqrt{h\, \boldsymbol{w}^\intercal \hat{\mathbf{\Sigma}}_t \boldsymbol{w}}$.

When the forecast is the true covariance, $\mathbb{E}[m_t] = \mathbb{E}[d_{t,i}] = 1$, and $b_t$ has mean zero and variance one, for every distribution of the returns. These moments hold under a gap too, because the count scales each cell of the forecast. With no gap and under Gaussian returns, $m_t$ times its degrees of freedom is chi-squared on them (target_dof). A ratio above one means that the forecast under-predicts the dispersion, in the metric of the forecast, and a ratio below one means that it over-predicts it.

Under RealisedCovariance, $L^{\mathrm{QLIKE}}_t$ is $-2$ times the Gaussian log-likelihood of the returns of the step under the forecast, up to a constant. Under HorizonReturn at $h > 1$ it is not a log-likelihood, but it has the same expectation. $L^{\mathrm{F}}_t$ is the squared distance of the forecast from the per-cell proxy. With no gap, the true covariance minimises the expected value of each loss under any conditionally unbiased proxy. So either loss ranks two forecasts on the proxy as it would rank them on the truth. Under a gap this holds for $L^{\mathrm{F}}_t$ only, and the expected $L^{\mathrm{QLIKE}}_t$ can be lower at a forecast that is not the truth. The level of neither loss is a calibration reading on its own.

$L^{\mathrm{P}}_t$ is the univariate QLIKE of the variance of the portfolio. It reads the per-row portfolio returns, whichever target formed $\mathbf{S}_t$.

A step with no active asset has nothing to score: no asset has both a forecast and a realised return. That is valid input, for example a test window on a market holiday or a forecast still in its warm-up, so the kernel does not refuse it. It returns the step unscored, with n_valid = 0 and every diagnostic NaN. The step keeps its place, so each step of an evaluation stays the step of its fold, and the summary and the comparison read the scored steps only.

Algorithm

  1. Find the active subset a, the assets whose forecast variance and location are finite and which have at least one finite test return. For an empty subset, check the portfolios through resolve_forecast_weights and return the unscored step.
  2. Take the forecast on the active subset, giving sa = sigma[a, a].
  3. Centre the test rows of a on c[a], giving Zc. A non-finite cell stays non-finite.
  4. Form (S, H) through realised_target, and the effective forecast seff = H .* sa.
  5. Factor sa by Cholesky, giving ch.
  6. When every entry of H is equal, compute trace, the trace of seff⁻¹ S, through ch. Otherwise factor seff by Cholesky and compute trace through that factor.
  7. Read the Mahalanobis ratio m and the QLIKE loss qlike from ch and trace, the Frobenius loss frob over the cells with a positive count, and the diagonal ratio d of each active asset. d is NaN outside a.
  8. Replace each non-finite cell of Zc with zero, giving Zf, and sum each column of Zf, giving R.
  9. Resolve the test portfolios over a through resolve_forecast_weights, giving ws.
  10. For each portfolio, read the standardised return b from R, and the portfolio QLIKE pq from the per-row portfolio returns Zf * wk.

Arguments

  • sigma: The forecast, assets × assets. A NaN diagonal marks an inactive asset.
  • Z: The test rows, observations × assets. A non-finite cell is an observation that the asset did not trade.
  • c: The location the forecast is about, assets × 1.
  • w: The test portfolios on the full universe: nothing for inverse volatility over the active subset, a vector for one portfolio, a vector of vectors for several. Each is renormalised over the active subset.
  • target: The realised quantity.

Validation

  • sigma is square and Z, c and every portfolio of w have its width. A DimensionMismatch is thrown otherwise.
  • The forecast on the active subset is positive definite. A LinearAlgebra.PosDefException is thrown otherwise.

Returns

  • step::CovarianceForecastStepResult: The diagnostics of the step. n_valid is the count of active assets. mahalanobis_ratio, qlike and frobenius are scalars, diagonal_ratio is assets × 1, and standardised_return and portfolio_qlike hold one entry per portfolio. A step with no active asset is unscored: n_valid is 0 and every diagnostic is NaN.

Related

source
PortfolioOptimisers.partial_fit! — Method
partial_fit!(ce::AbstractCovarianceEstimator, rd::ReturnsResult)

Fold the observations of the returns data rd into a covariance estimator.

This is the ReturnsResult arity that online_folds, the online arm of the fold loop, calls for the two kinds of estimator that covariance_forecast_evaluation threads through it. A prior has a ReturnsResult arity of its own, partial_fit! over a ReturnsResult, which is the fold of every prior and the forward that the step of an optimiser makes. A covariance estimator folds rd.X in its own arity. When the Asset Panel varies in time, the method reads its active mask through step_active_mask and passes it as the active_mask keyword. That verb also refuses a mask that the step cannot carry.

An estimator that carries a SampleBufferState also takes rd.iv and rd.ivpa, and the buffer records them beside the rows. The call with no data gives them back to the batch verb, so a buffered ImpliedVolatility answers what a batch fit over the same rows answers. An exact fold keeps numbers alone, and no exact fold reads an implied volatility, so it does not take them. The batch fit of such an estimator ignores them too.

Algorithm

  1. Check that rd.X is not nothing.
  2. Read the active mask of the step through step_active_mask, giving amsk.
  3. Read the implied-volatility keywords of the state through step_implied_volatility_kwargs.
  4. Fold rd.X into ce through partial_fit!(ce, rd.X), with active_mask = amsk when amsk is not nothing, and with the keywords of step 3.

Arguments

  • ce: Covariance estimator.
  • rd: The returns data to fold, observations × assets.

Validation

  • rd.X is not nothing. An IsNothingError is thrown otherwise.
  • Everything step_active_mask refuses.

Returns

  • ce: The estimator, with the observations folded into its state.

Related

source
PortfolioOptimisers.covariance_forecast_evaluation — Function
covariance_forecast_evaluation(est::Union{AbstractCovarianceEstimator, AbstractPriorEstimator, Online},
                               rd::ReturnsResult, cv::WFCVER; w::Option{<:VecNum_VecVecNum} = nothing,
                               target::AbstractRealisedTarget = RealisedCovariance(),
                               store_forecasts::Bool = false,
                               x_src::Option{<:AbstractReturnsSource} = nothing) -> CovarianceForecastEvaluationResult

Evaluate a covariance forecast out of sample over a walk-forward, in batch or online.

The verb runs through the one fold loop of the library. At each fold the callback reads the forecast and its location off the estimator of the fold, and scores them on the test rows through covariance_forecast_step. That estimator is a refit over the training window when the fold carries one, and the threaded state under an Online Scheme. The four forms of the evaluation are compositions that the walk-forward and the Online wrapper already express:

  • expand_train = true gives the batch expanding form.
  • expand_train = false gives the batch rolling form.
  • OnlineIndexWalkForward(…) gives the online expanding form.
  • OnlineIndexWalkForward(…) with Online(est; max_history = w) gives the online rolling form.

The verb reads none of these settings. So the online run gives the rows of the batch expanding run fold for fold, to the tolerance of the estimator's own fold. The date form, the purge, and a listing or a delisting need no code of their own.

The verb is the outermost reader of the returns in the evaluation, because no estimator in the call receives the returns data of its own. So the verb states the source with x_src, and the estimator states none. With x_src = ExcessSource() the verb evaluates a forecast of the returns in excess of the benchmark, X - B, which is the covariance that a tracking-error portfolio reads. Every reader of the returns in the evaluation reads this one frame: the fit over a training window, the online step, and the test rows. So the verb gives the fold loop the returns data of prior_step_returns, which holds X - B in X and keeps B and every other field. A vector B is one benchmark, which benchmark_relative_returns subtracts from every asset. A matrix B holds one benchmark per asset. An ImpliedVolatility estimator reads the surface iv of the assets beside X - B, as a prior in the Excess Frame does, because the returns data holds no surface of the excess returns. Under ExcessSource a gap in a vector B leaves no asset an excess return at its observation, so the verb drops that observation from the returns data before it splits the folds, and the fixed observation weights of the same observation from est, with shared_series_fit, as every fit drops it. The Result records the frame that the verb read: DataSource for x_src = nothing, so two evaluations of one frame hold one value.

The loop receives the estimator as a configuration only. Under an Online Scheme it warms up one estimator on the first training window and folds the new rows of each fold into it. So the loop refuses an estimator that enters with a state or that cannot fold, with an error that names it. An estimator that cannot fold but has a cache field can be wrapped in Online, which folds it from a buffer. Each estimate made from the state is then a batch fit over the rows of the buffer. An estimator with no cache field has nowhere to carry a buffer, and Online refuses it.

Algorithm

  1. Check x_src and the source of est, check rd.X, and check that an Online at the root comes with an Online Scheme.
  2. Take the returns data that every reader reads, prior_step_returns(rd, x_src), giving rdb. It is rd unless x_src is ExcessSource.
  3. Split rdb by cv, giving train_idx and test_idx, and check that the folds are not shuffled.
  4. Run fold_loop over the n folds of rdb, giving steps. At each fold, read (sigma, c) through forecast_moments and score the test rows through covariance_forecast_step. When store_forecasts = true, add copies of sigma and c to the step record, because an online state writes its location in place.
  5. Stack the diagonal ratios, the standardised returns and the portfolio QLIKE losses of the steps into the matrices d, b and pq, one row per step.
  6. Label each step with the timestamp of its first test row, or with the index of that row when rd.ts is nothing, giving dates.
  7. Build the Result from the columns, the horizons length.(test_idx), target, the frame that the verb read and w. The frame is x_src, or DataSource when x_src is nothing.

Arguments

  • est: The covariance estimator, or the prior estimator whose sigma is the forecast. Under an Online Scheme either can be wrapped in Online, to fold from a buffer and, with max_history, over a rolling window.
  • rd: The returns result to use.
  • cv: The walk-forward, in its index or date form, or its split.
  • w: The test portfolios on the full universe. nothing means inverse volatility recomputed from the forecast of each step, a vector is one static portfolio, and a vector of vectors is several.
  • target: The realised quantity that the evaluation judges the forecasts against.
  • store_forecasts: Whether to keep the forecast and the location of every step in the Result, for covariance_forecast_portfolio.
  • x_src: The source of the returns that the evaluation fits, steps and scores the forecast on. nothing and DataSource read the asset returns rd.X. ExcessSource reads the returns in excess of the benchmark, rd.X - rd.B, the Excess Frame, which is the covariance that a tracking-error portfolio reads. The evaluation reads no prior, so it refuses PriorSource.

Validation

  • x_src is nothing, DataSource() or ExcessSource(), see assert_returns_source.
  • The source of est is nothing, because the verb picks the returns that it reads, see assert_inner_reader. An ArgumentError is thrown otherwise. A prior at x_src = ExcessSource() would subtract B from the returns that the verb already holds in the Excess Frame.
  • rd.X is not nothing. An IsNothingError is thrown otherwise.
  • The rules of benchmark_relative_returns.
  • The folds of the scheme are not shuffled, through assert_unshuffled_folds. An ArgumentError is thrown otherwise.
  • An Online at the root comes with an Online Scheme. An ArgumentError is thrown otherwise, because a batch fold would never seed the buffer.
  • Everything that covariance_forecast_step refuses at a step, and everything that the online arm of the fold loop refuses at entry under an Online Scheme.

Returns

  • cfer::CovarianceForecastEvaluationResult: The per-step diagnostics, and the forecasts when asked.

Related

source
PortfolioOptimisers.AbstractRealisedTarget — Type
abstract type AbstractRealisedTarget <: AbstractAlgorithm

Abstract supertype of the realised quantities that the evaluation judges a covariance forecast against.

The evaluation forms a covariance forecast $\hat{\mathbf{\Sigma}}_t$ at a step and judges it on the $h$ returns that follow the step. A member of this family chooses the statistic of those returns that stands in for the covariance they were drawn from. The two members the library defines take the realised covariance of the returns and the outer product of their sum. When the returns are serially uncorrelated, both statistics have the expectation $h\, \mathbf{\Sigma}_t$, and at $h = 1$ they are equal. So the member changes the variance of the per-step diagnostic and the question that it answers, but not its target.

All concrete subtypes should subtype AbstractRealisedTarget.

Interfaces

In order to implement a new concrete type that works seamlessly with the library, subtype AbstractRealisedTarget and implement the following methods:

Required method name

  • realised_target(target::AbstractRealisedTarget, Zc::MatNum) -> Tuple{MatNum, AbstractMatrix{<:Integer}}: Return the realised matrix of the centred test rows, and the count of rows over which each of its cells was formed.
  • target_dof(target::AbstractRealisedTarget, n::Integer, h::Integer) -> Integer: Return the degrees of freedom of the step's Mahalanobis statistic under a Gaussian null, for n active assets and a horizon of h.
  • target_step_dof(target::AbstractRealisedTarget, h::Integer) -> Integer: Return the degrees of freedom of one asset's, or one portfolio's, step ratio under a Gaussian null.

Arguments

  • target: The concrete subtype instance.
  • Zc: The centred test rows, observations × assets. A cell that an asset did not trade is non-finite.
  • n: The number of active assets at the step.
  • h: The horizon of the step.

Returns

  • S::MatNum: The realised matrix, assets × assets.
  • H::AbstractMatrix{<:Integer}: The count of rows at which both assets of each cell are finite.
  • dof::Integer: The degrees of freedom.

Examples

julia> RealisedCovariance()RealisedCovariance()

Related

source
PortfolioOptimisers.realised_target — Function
realised_target(target::RealisedCovariance, Zc::MatNum)
realised_target(target::HorizonReturn, Zc::MatNum)

Form the realised matrix of a step and the count of rows behind each of its cells.

These are the two methods of the AbstractRealisedTarget interface that the library defines. A non-finite cell of Zc is an observation that the asset did not trade. It adds nothing to the sum, and the count leaves it out. The count H holds, for each pair of assets, the number of rows at which both are finite. The kernel scales the forecast by it cell by cell, H ⊙ Σ̂, so a gap in the test window changes the target and not the reading.

Algorithm

  1. Mark the finite cells of Zc, giving fin.
  2. Replace each non-finite cell of Zc with zero, giving Zf.
  3. Under RealisedCovariance, form the realised matrix S = Zf' Zf. Under HorizonReturn, sum each column of Zf, giving R, and form S = R R'.
  4. Count the rows at which both assets of each pair are finite, giving H = fin' fin.

Arguments

  • target: The realised quantity.
  • Zc: The centred test rows, observations × assets.

Returns

  • S::MatNum: The realised matrix, assets × assets.
  • H::AbstractMatrix{<:Integer}: The pairwise count of finite rows.

Related

source
PortfolioOptimisers.target_dof — Function
target_dof(target::RealisedCovariance, n::Integer, h::Integer)
target_dof(target::HorizonReturn, n::Integer, h::Integer)

Degrees of freedom of a step's Mahalanobis statistic under a Gaussian null, by realised quantity.

The statistic is the trace of the whitened realised matrix. Under RealisedCovariance it has n * h degrees of freedom, because each of the h returns adds n whitened coordinates. Under HorizonReturn it has n, because the horizon return is one draw at every h. The summary reads the count to weight the steps of a run and to set the width of the band on the mean ratio. The exceedance rate reads it for its chi-squared threshold. Under a Gaussian null the statistic is chi-squared on this count when the test window has no gap, and only then.

Arguments

  • target: The realised quantity.
  • n: The number of active assets at the step.
  • h: The horizon of the step.

Returns

  • dof::Integer: The degrees of freedom.

Related

source
PortfolioOptimisers.target_step_dof — Function
target_step_dof(target::RealisedCovariance, h::Integer)
target_step_dof(target::HorizonReturn, h::Integer)

Degrees of freedom of one asset's, or one portfolio's, step ratio under a Gaussian null, by realised quantity.

The count is h under RealisedCovariance, one squared whitened coordinate per return. It is 1 under HorizonReturn, one draw at every h. The summary reads it to weight the steps of the diagonal ratio and to set the width of its band.

Arguments

  • target: The realised quantity.
  • h: The horizon of the step.

Returns

  • dof::Integer: The degrees of freedom.

Related

source