Covariance forecast summary: private API

PortfolioOptimisers.covariance_ratio_band — Function
covariance_ratio_band(z::Number, omega::AbstractVector, nu::AbstractVector{<:Integer})

Return the half-width of the Gaussian band on the weighted mean of a calibration ratio.

The mean weights step $t$ by $\omega_t$, and the ratio of the step has variance $2 / \nu_t$ under a calibrated Gaussian forecast. covariance_step_weights states the formula. Under DofStepWeighting each term $\omega_t^2 / \nu_t$ is the integer $\nu_t$, so the variance is $2 / \sum_t \nu_t$ to the last bit.

Arguments

  • z: The quantile of the standard normal distribution at the level of the band.
  • omega: The weight of each step.
  • nu: The degrees of freedom of each step.

Returns

  • hw::Number: The half-width of the band.

Related

source
PortfolioOptimisers.assert_covariance_summary_fields — Function
assert_covariance_summary_fields(s::CovarianceForecastSummaryResult)

Check the fields of a CovarianceForecastSummaryResult that its constructor built.

The constructor builds the Result first and checks it here, so the check reads each field by its name and not by its position among twenty-seven arguments. A summary of one evaluation holds a number or a name in each field of an entry, and a summary of many evaluations holds one vector entry for each. n_steps gives the shape: an integer for one evaluation, and a vector otherwise. levels is the axis of the confidence levels, so exceedance is a vector over the levels for one evaluation, and evaluations × levels otherwise. The checks are the rules that covariance_forecast_summary states, so a summary that it builds always passes them.

Arguments

  • s: The summary to check.

Validation

  • 0 < alpha < 1, and 0 < l < 1 for each level l. Raises a DomainError.
  • Each field of an entry is not a vector when n_steps is an integer, and is a vector of length(n_steps) otherwise. exceedance has one entry per level for one evaluation, and the size evaluations × levels otherwise. Raises a DimensionMismatch.
  • Each evaluation scored at least one step, n_steps >= 1, and n_portfolios is not negative. Raises a DomainError.
  • Each exceedance rate is NaN or in $[0, 1]$, and no lower end of a band lies above its upper end, a NaN end passes. Raises a DomainError.

Returns

  • nothing.

Related

source
PortfolioOptimisers.covariance_summary_entry — Function
covariance_summary_entry(s::CovarianceForecastSummaryResult) -> CovarianceForecastSummaryResult

The summary of one covariance forecast evaluation, with scalar fields, from a summary of one evaluation with length-1 columns.

Each field becomes its entry 1 through first_summary_entry. levels is the axis of the confidence levels and not of the evaluations, so it stays as it is, and exceedance becomes a vector over the levels.

Arguments

  • s: The summary of the vector of one evaluation.

Returns

  • s1::CovarianceForecastSummaryResult: The summary with scalar fields.

Related

source
PortfolioOptimisers.summary_quantile — Function
summary_quantile(x::VecNum, p::Number)

Return the p quantile of a column of the summary, or NaN when the column holds a NaN.

Statistics.quantile throws on a NaN, and Statistics.median returns NaN. The summary reads a NaN as an undefined entry, so a percentile of a column that holds one is NaN, as the median of that column is. The bias statistic of a one-step evaluation is such a column, because the sample standard deviation of one step is NaN.

Arguments

  • x: The column.
  • p: The probability of the quantile.

Returns

  • q::Number: The quantile of x at p, or NaN.

Related

source
PortfolioOptimisers.covariance_forecast_names — Function
covariance_forecast_names(names::Nothing, n::Integer)
covariance_forecast_names(names::AbstractVector, n::Integer)

Name each covariance forecast evaluation of a summary or of a figure.

covariance_forecast_summary and the comparison figures of plot_covariance_calibration, plot_covariance_qlike and plot_covariance_exceedance read the names from this function. So a figure labels each evaluation with the name that the summary gives it. nothing gives "forecast_1", "forecast_2", and so on.

Arguments

  • names: A name per evaluation, or nothing.
  • n: The number of evaluations.

Validation

  • names has n entries when given. A DimensionMismatch is thrown otherwise.

Returns

  • nms::AbstractVector: One name per evaluation.

Related

source
PortfolioOptimisers.covariance_diagonal_mean — Function
covariance_diagonal_mean(cfer::CovarianceForecastEvaluationResult)

Mean of the diagonal ratio over the active assets of each step of a covariance forecast evaluation.

The diagonal ratio of an asset that was not active at a step is NaN, so the mean reads the finite entries of the row alone. A step with no active asset has no finite entry, and its mean is NaN. covariance_forecast_summary reads the mean of the scored steps, and plot_covariance_calibration reads its rolling form.

Arguments

Returns

  • dbar::VecNum: The mean of the diagonal ratio, one entry per step.

Related

source
PortfolioOptimisers.covariance_exceedance — Function
covariance_exceedance(cfer::CovarianceForecastEvaluationResult, q::Real)

Whether the Mahalanobis statistic of each step of a covariance forecast evaluation exceeds the chi-squared quantile of level q.

The Mahalanobis statistic of a step is its ratio times its degrees of freedom, which target_dof finds from the target, the active count and the horizon. Under a Gaussian null with no gap in the test window it is chi-squared on those degrees of freedom, so it exceeds the quantile at a rate of $1 - q$. covariance_forecast_summary reads the mean over the scored steps, and plot_covariance_exceedance reads its rolling form.

Mathematical definition

\[\begin{align} e_t &= \mathbb{1}\left[\nu_t\, m_t > \chi^2_{\nu_t}(q)\right]\,, \quad \nu_t = \operatorname{dof}(N_t, h_t)\,. \end{align}\]

Where:

  • $e_t$: Exceedance indicator of step $t$.
  • $\nu_t$: Degrees of freedom of the Mahalanobis statistic of step $t$ under a Gaussian null.
  • $m_t$: Mahalanobis ratio of step $t$.
  • $\chi^2_{\nu}(q)$: Quantile at level $q$ of the chi-squared distribution with $\nu$ degrees of freedom.
  • $N_t$: Number of active assets at step $t$.
  • $h$: Horizon of a step, the number of observations the forecast is judged on.

Arguments

Returns

  • e::VecNum: One entry per step, 1 where the statistic exceeds the quantile, 0 where it does not, and NaN at a step with no active asset.

Related

source
PortfolioOptimisers.loss_difference_test — Function
loss_difference_test(mt::AbstractMeanTestEstimator, d::VecNum, k::AbstractVector{Bool}, rng)
    -> MeanTestResult

Return the Mean Test of a loss difference against zero, over the entries that both sides scored.

covariance_forecast_compare and log_wealth_regret call it, so the two comparisons read one test. An entry outside k is one that a side did not score. It is missing, so it is in no pair, and the lag between two entries is their distance in the series, not in the subsequence of the scored entries. An entry inside k has a loss on both sides. A scored entry that is not finite is a defect of the data and not a missing entry, so the test answers NaN, as the mean of the difference does.

One entry is one step of a walk-forward, or one row of a return series, and two steps do not share a test row. So the data of one entry spans one entry, and the test reads a window of one.

Arguments

  • mt: The Mean Test.
  • d: The loss difference, one entry per step.
  • k: Whether both sides scored each step, one entry per entry of d.
  • rng: The generator of mean_test_rng.

Returns

Related

source