Expected Risk: private API

PortfolioOptimisers.MatNum_Pr — Type
const MatNum_Pr = Union{MatNum, AbstractPriorResult, ReturnsResult}

Groups the three types that hold a returns matrix and that the value-level risk functions accept as their data argument.

A caller can hold a bare matrix, a prior result or a returns result, and each one carries the matrix that a risk measure is evaluated on. resolve_risk_inputs turns any of the three into the pair of a measure and a matrix, so one method of a function such as risk_contribution serves all three.

Related

source
PortfolioOptimisers.missing_returns_data_message — Function
missing_returns_data_message(r::AbstractBaseRiskMeasure)

Build the error message that refuses nothing as the returns data of a measure that reads a return series.

Two methods raise this refusal, one for a weight vector and one for a weight path, and both take the text from here. The message names the measure and the four calls that pass the returns data, two on a weight vector and two on an OptimisationResult.

Arguments

  • r: The measure that was given no returns data.

Returns

  • msg::String: The refusal message.

Related

source
PortfolioOptimisers.resolve_risk_inputs — Function
resolve_risk_inputs(r::BaseRM_VecBaseRM, X::MatNum_Pr)

Turn the data argument of a value-level function into the measure to evaluate and the returns matrix to evaluate it on.

The method depends on the type of X.

  • A prior result resolves the measure through factory and returns pr.X. A Deferred Quantity becomes a value, and a slot that the measure leaves unstated takes the field of the prior.
  • A ReturnsResult carries no moments, so the method returns rd.X. It binds every DataBenchmarkTracking of the measure to the benchmark of the rows, rd.B, with bind_data_benchmark, and changes nothing else.
  • A matrix returns the measure and the matrix unchanged.

Each entry point resolves once, not once for each evaluation. So risk_contribution fits a deferred covariance once, and not once for each of its 2N evaluations.

Arguments

  • r: Risk measure or vector of risk measures.
  • X::MatNum_Pr: Returns matrix, prior result or returns result.

Returns

  • (r, X)::Tuple: The resolved measure and the returns matrix.

Related

source
PortfolioOptimisers.difference_risk — Function
difference_risk(r::AbstractBaseRiskMeasure, wd::VecNum, w::VecNum, X::MatNum,
                fees::Option{<:Fees}) -> Number

Compute the risk of the weight difference wd on a return series that pays the fee of the portfolio w.

The independent mode of RiskTrackingRiskMeasure calls it with wd = w - wb. The model of that mode charges the fee once, on the portfolio, so the series that it tracks is the net return of the portfolio minus the gross return of the benchmark. This function reads the same series. expected_risk on wd charges the fee of wd instead, and wd is not a portfolio that pays a fee.

Mathematical definition

\[\begin{align} \boldsymbol{x} &= \mathbf{X}(\boldsymbol{w} - \boldsymbol{w}_b) - F(\boldsymbol{w})\,. \end{align}\]

Where:

  • $\boldsymbol{x}$: Return series $T \times 1$ that the tracked measure reads.
  • $\mathbf{X}$: Returns matrix $T \times N$.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{w}_b$: Benchmark portfolio weights vector $N \times 1$, the w of the tracking specification tr.
  • $F(\boldsymbol{w})$: Fee series $T \times 1$ of the portfolio, zero when fees is nothing. See calc_net_returns.

Algorithm

  1. A nothing fee returns expected_risk(r, wd, X), because the two series are equal without a fee.
  2. A measure that reads a return series, NetReturnsInput, reads $\boldsymbol{x}$.
  3. A measure that reads the weights alone, WeightsInput, reads wd and no fee.
  4. A moment measure resolves its observation weights against X with resolve_observation_weights. It reads $\boldsymbol{x}$ and takes its target from wd. So a per-asset target is $(\boldsymbol{w} - \boldsymbol{w}_b)^\intercal \boldsymbol{\mu}$ minus the mean fee of the portfolio w, from moment_target_fees, as in the model.
  5. A TrackingRiskMeasure takes the norm of $\boldsymbol{x}$ minus its own benchmark series.
  6. A nested RiskTrackingRiskMeasure recurses. The independent mode subtracts its own benchmark weights from wd. The dependent mode subtracts the risk of its own benchmark weights, which pay their own fee, as in the model.
  7. A RiskRatio and a NonOptimisationRiskRatio divide the results of their two sides. A MeanReturnRiskRatio divides the mean of $\boldsymbol{x}$, minus rf, by the result of its risk side, and an ExpectedReturnRiskRatio does the same with the expected return of wd minus the fee of the portfolio w. A vector side scalarises the results of its measures, each times its settings.scale, with the scalariser of the ratio. A VarianceSkewKurtosis reads wd and no fee. An ExpectedReturn reads the expected return of wd, minus the fee of the portfolio w, through resolved_expected_return.
  8. Any other WeightsReturnsFeesInput measure reads $\boldsymbol{x}$ through expected_risk_from_returns, which refuses a measure that cannot read a series.

Arguments

  • r: Tracked risk measure.
  • wd: Weight difference assets × 1.
  • w: Portfolio weights vector assets × 1.
  • X: Asset returns matrix observations × assets.
  • fees: Fee of the portfolio w, or nothing.

Returns

  • rk::Number: The risk of wd on the series $\boldsymbol{x}$.

Related

source
PortfolioOptimisers.original_returns — Function
original_returns(X::MatNum_Pr)

Return the returns matrix that the caller supplied, from the argument that holds it.

A prior result returns pr.original_X, a ReturnsResult returns its X, and a matrix returns itself. The three agree when the prior did not come from a factor model, because then pr.original_X === pr.X. A factor prior sets pr.X to the reconstruction F * transpose(M) .+ transpose(b), and the two differ.

resolve_factor_risk_inputs reads this matrix, and resolve_risk_inputs does not. expected_risk evaluates the return distribution that the prior states, which is pr.X. A factor attribution splits the risk into a factor part and a residual part. The reconstruction has no residual, so on it the residual part reports the share of the intercept and not the idiosyncratic risk.

Arguments

  • X::MatNum_Pr: Returns matrix, prior result, or returns result.

Returns

  • X::MatNum: The returns matrix the caller supplied.

Related

source
PortfolioOptimisers.resolve_factor_risk_inputs — Function
resolve_factor_risk_inputs(r::BaseRM_VecBaseRM, X::MatNum_Pr)

Turn the data argument of a factor attribution into the measure to evaluate and the returns matrix to evaluate it on.

The measure resolves as in resolve_risk_inputs, so a Deferred Quantity is fitted once and not once for each finite difference. The matrix is original_returns, not pr.X.

The two functions are separate because each answer is correct for its caller. A factor attribution needs the residual that the caller's returns carry, and every other caller of resolve_risk_inputs needs the distribution that the prior states.

Arguments

  • r: Risk measure or vector of risk measures.
  • X::MatNum_Pr: Returns matrix, prior result or returns result.

Returns

  • (r, X)::Tuple: The resolved measure and the returns matrix that the caller supplied.

Related

source
PortfolioOptimisers.source_loadings — Function
source_loadings(x_src::Option{<:AbstractReturnsSource},
                rr::Option{<:AbstractLoadingsRegressionResult},
                re::AbstractTimeSeriesRegressionEstimator)

Return the loadings of the prior that a regression reader takes under its source, or nothing when the reader fits its own.

The source of the reader decides, by the table of AbstractReturnsSource. A stated source that reads the returns data overrides the loadings of the prior, so a caller can fit the regression in a frame that differs from the frame of the prior.

The method that Julia selects is the algorithm.

  1. nothing: return rr. The reader fits its own loadings only when the prior holds none.
  2. PriorSource: return rr, and refuse rr === nothing.
  3. Every other source, DataSource and ExcessSource included: return nothing. The reader fits its loadings on the matrix that benchmark_relative_returns gives for its source.

Arguments

  • x_src: The source of the regression reader, returns_source(re).
  • rr: The loadings of the prior, or nothing when the prior holds none or the call gives no prior.
  • re: The regression reader, for the message of the refusal.

Validation

  • Under PriorSource(), !isnothing(rr). Throws an ArgumentError that names the three sources that fit the loadings on the returns data.

Returns

  • rr::Option{<:AbstractLoadingsRegressionResult}: The loadings to take, or nothing to fit re.

Related

source
PortfolioOptimisers.resolve_factor_regression — Function
resolve_factor_regression(re::AbstractLoadingsRegressionResult, rd::ReturnsResult,
                          pr::Option{<:AbstractPriorResult} = nothing)
resolve_factor_regression(re::AbstractTimeSeriesRegressionEstimator, rd::ReturnsResult,
                          pr::Option{<:AbstractPriorResult} = nothing)

Pick the factor loadings that a factor attribution decomposes against, from the three arguments re, pr and rd that can supply them.

A precomputed result is an answer that the caller states, so it needs no data. A regression estimator states the source of its loadings in its x_src field, and source_loadings reads that source. At x_src = nothing, the default, the loadings of a prior take precedence over a fit. They were fitted on pr.original_X, which is the matrix that the attribution measures the risk on, so the loadings and the returns agree. A stated source that reads the returns data always fits re.

re.x_srcThe function returns
nothingpr.rr, else a fit on rd.X
DataSourcea fit on rd.X
ExcessSourcea fit on rd.X - rd.B, the Excess Frame
PriorSourcepr.rr, and it refuses a prior that holds none

Algorithm

  1. When re is an AbstractLoadingsRegressionResult, return re.
  2. Return the loadings that source_loadings takes from pr.rr under the source of re, which returns_source reads, when they are not nothing.
  3. Otherwise fit re with refit_factor_regression.

Arguments

  • re::RegE_Reg: Regression result or estimator.
  • rd::ReturnsResult: Returns result carrying X and F.
  • pr::Option{<:AbstractPriorResult}: Prior result, or nothing when the caller passed a bare matrix.

Validation

Returns

  • rr::AbstractLoadingsRegressionResult: The factor loadings.

Related

source
PortfolioOptimisers.refit_factor_regression — Function
refit_factor_regression(re::AbstractTimeSeriesRegressionEstimator, rd::ReturnsResult,
                        pr::Option{<:AbstractPriorResult} = nothing)

Fit the factor loadings of a regression reader on the returns that its source names.

resolve_factor_regression and factor_space_regression call it when the source of re takes no loadings of a prior. The source x_src = returns_source(re) picks the matrix, as benchmark_relative_returns states: rd.X under nothing and DataSource, and rd.X - rd.B under ExcessSource.

Algorithm

  1. Check that rd.X and rd.F are present.
  2. Drop the observations of a Shared Series gap with shared_series_fit under x_src: a gap of the factor returns, and a gap of a vector benchmark under ExcessSource(). Each fixed observation weight in the tree of re loses the same observations.
  3. Read the asset returns with benchmark_relative_returns under x_src, giving X. Fit and return regression(re, X, rd.F).

Arguments

  • re::AbstractTimeSeriesRegressionEstimator: Regression reader to fit.
  • rd::ReturnsResult: Returns result carrying X and F.
  • pr::Option{<:AbstractPriorResult}: Prior result of the caller, or nothing. Only the message of the refusal reads it.

Validation

Returns

  • rr::AbstractLoadingsRegressionResult: The fitted loadings.

Related

source
PortfolioOptimisers.adjusted_risk — Function
adjusted_risk(ps::Nothing, q, r::AbstractBaseRiskMeasure, w::VecNum, X::MatNum,
              fees::Option{<:Fees}; kwargs...)
adjusted_risk(ps::Nothing, q, r::VarianceSkewKurtosis, w::VecNum, X::MatNum,
              fees::Option{<:Fees}; kwargs...)
adjusted_risk(ps::VecNum, qs::AbstractVector, rs::VecBaseRM, w::VecNum, X::MatNum,
              fees::Option{<:Fees}; kwargs...)

Evaluate the risk at w with the homogeneity correction applied to each measure, which is the function that risk_contribution differentiates.

The risk of each measure comes from linearised_risk. A measure whose value is a solve has the Worst-Case Distribution q at the unperturbed weights, and the function evaluates the expected loss under that distribution. That function has the same gradient at the unperturbed weights, and it holds no solver noise. Every other measure has q = nothing, and the function evaluates expected_risk.

adjust_risk_contribution divides the risk of a measure by its degree of homogeneity under fees on the observations of X. The count of the rows of X gives the sum of the weights of an OWA weight builder. By Euler's theorem, the gradient of the divided risk, multiplied by the weights, then sums to the risk. A vector such as [Variance(), ConditionalValueatRisk()] holds a measure of degree 2 and a measure of degree 1, so the vector has no single degree. The function therefore corrects each element before it combines them. VarianceSkewKurtosis is a sum of three terms of the degrees 2, 3 and 4, so its method divides each term of variance_skew_kurtosis_terms by its own degree.

The chain-rule weights $p_k$ come from scalariser_element_weights, which the caller evaluates once at the unperturbed weights. The finite difference moves the risk of each element and keeps the weights, so a maximum or a minimum keeps the element that it picks at w. Under the sum, the maximum and the minimum, the gradient of $A$ times the weights then sums to $\sum_k p_k s_k R_k(\boldsymbol{w})$, which is the aggregate that expected_risk reports. Under the log-sum-exp scalariser the same sum is the softmax-weighted mean of the scaled risks, which is below the aggregate, because the log-sum-exp is not homogeneous.

Mathematical definition

\[\begin{align} A(\boldsymbol{w}) &= \sum_{k=1}^{n} p_k \, s_k \, \frac{R_k(\boldsymbol{w})}{d_k}\,. \end{align}\]

A single measure takes $n = 1$, $p_1 = 1$ and $s_1 = 1$, because a single measure ignores its scale.

Where:

  • $A(\boldsymbol{w})$: Homogeneity-adjusted risk.
  • $p_k$: Chain-rule weight of the $k$-th risk measure of a vector, the partial derivative of $S$ with respect to its $k$-th argument at $s_k R_k(\boldsymbol{w})$.
  • $s_k$: scale of the $k$-th risk measure of a vector, its weight in the combination.
  • $R_k(\boldsymbol{w})$: Element risk, the risk of the $k$-th risk measure of a vector.
  • $d_k$: Degree of homogeneity of the $k$-th risk measure of a vector.
  • $n$: Size of the vector of risk measures.

Arguments

  • ps: Chain-rule weights of a vector of measures, or nothing for a single measure.
  • q, qs: Worst-Case Distribution of the measure, or of each element of the vector, from element_worst_case_distributions.
  • r: Risk measure or vector of risk measures.
  • w::VecNum: Portfolio weights vector assets × 1.
  • X::MatNum: Returns matrix observations × assets.
  • fees: Optional Fees structure.

Returns

  • rk::Number: The homogeneity-adjusted risk.

Related

source
PortfolioOptimisers.finite_difference_gradient — Function
finite_difference_gradient(f, w::VecNum, delta::Number)

Compute the two-sided finite difference of a scalar function of the weights, with one entry for each asset.

risk_contribution and the fallback of risk_gradient share this function, and they give it different functions to differentiate. The contribution differentiates the homogeneity-adjusted risk, so that Euler's theorem gives the risk back. The gradient differentiates the risk itself.

Mathematical definition

\[\begin{align} g_i &= \frac{f(\boldsymbol{w} + \delta \boldsymbol{e}_i) - f(\boldsymbol{w} - \delta \boldsymbol{e}_i)}{2 \delta}\,. \end{align}\]

Where:

  • $g_i$: Entry $i$ of the finite-difference gradient.
  • $f$: Scalar function of the weights.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\delta$: Step of the finite difference.
  • $\boldsymbol{e}_i$: $i$-th unit vector.

Algorithm

  1. Copy w into both columns of the N × 2 work matrix ws, whose type promotes the type of w with the type of delta.
  2. For each asset i, add delta to entry i of the first column, and subtract delta from entry i of the second column.
  3. Set g[i] to the difference of f at the two columns, times id2 = inv(2 * delta).
  4. Restore entry i of both columns to w[i], and go to the next asset.

Arguments

  • f: Scalar function of a weight vector.
  • w::VecNum: Portfolio weights vector assets × 1.
  • delta::Number: Step of the finite difference.

Returns

  • g::Vector: The finite-difference gradient, one entry for each asset.

Related

source
PortfolioOptimisers.measure_gradient — Function
measure_gradient(r::AbstractBaseRiskMeasure, w::VecNum, X::MatNum, fees::Option{<:Fees}; delta::Number, kwargs...)
measure_gradient(r::Variance, w::VecNum, X::MatNum, fees::Option{<:Fees}; kwargs...)
measure_gradient(r::StandardDeviation, w::VecNum, X::MatNum, fees::Option{<:Fees}; kwargs...)
measure_gradient(r::MeanReturn, w::VecNum, X::MatNum, fees::Nothing; kwargs...)

Compute the gradient of one resolved measure on a bare matrix.

The generic method takes the finite difference of linearised_risk at the Worst-Case Distribution of worst_case_distribution. For a measure whose value is not a solve, that is expected_risk. The methods for Variance, StandardDeviation and MeanReturn use the closed forms that risk_gradient states. A MeanReturn that is charged fees takes the generic method, because the fee is not linear in the weights. A StandardDeviation at a zero variance also takes the finite difference.

Arguments

  • r::AbstractBaseRiskMeasure: Resolved risk measure.
  • w::VecNum: Portfolio weights vector assets × 1.
  • X::MatNum: Returns matrix observations × assets.
  • fees: Optional Fees structure.
  • delta::Number: Step of the finite difference.

Returns

  • g::Vector: The gradient, one entry for each asset.

Related

source
PortfolioOptimisers.scalariser_gradient_weights — Function
scalariser_gradient_weights(sca::Option{<:SumScalariser}, vals::VecNum)
scalariser_gradient_weights(sca::MaxScalariser, vals::VecNum)
scalariser_gradient_weights(sca::MinScalariser, vals::VecNum)
scalariser_gradient_weights(sca::LogSumExpScalariser, vals::VecNum)

Compute the chain-rule weight of each element in the gradient of a scalarised aggregate, from the scaled risks of the elements.

The weight of an element is the partial derivative of the scalariser with respect to that element. SumScalariser and nothing give a weight of one to every element. MaxScalariser and MinScalariser give a weight of one to the earliest maximum or minimum, and zero to every other element. LogSumExpScalariser gives the softmax of $\gamma v_k$, which the method computes after it subtracts the maximum of vals, so that the exponentials do not overflow.

Mathematical definition

\[\begin{align} p_k^{\mathrm{sum}} &= 1\,, \\ p_k^{\mathrm{max}} &= \mathbf{1}\left[ k = \underset{j}{\arg\max} \, v_j \right]\,, \\ p_k^{\mathrm{min}} &= \mathbf{1}\left[ k = \underset{j}{\arg\min} \, v_j \right]\,, \\ p_k^{\mathrm{lse}} &= \frac{\exp(\gamma v_k)}{\sum_{j=1}^{n} \exp(\gamma v_j)}\,. \end{align}\]

Where:

  • $p_k$: Chain-rule weight of the $k$-th risk measure of a vector, the partial derivative of $S$ with respect to its $k$-th argument at $s_k R_k(\boldsymbol{w})$.
  • $v_k$: Scaled risk $s_k R_k(\boldsymbol{w})$ of the $k$-th risk measure of a vector.
  • $\gamma$: Smoothing parameter gamma of a LogSumExpScalariser, positive.
  • $n$: Size of the vector of risk measures.

Arguments

  • sca: Scalariser.
  • vals::VecNum: Scaled risks of the elements.

Returns

  • p::Vector: The chain-rule weight of each element.

Related

source
PortfolioOptimisers.scalariser_element_weights — Function
scalariser_element_weights(sca::Option{<:Scalariser}, r::AbstractBaseRiskMeasure, args...; kwargs...)
scalariser_element_weights(sca::Option{<:Scalariser}, rs::VecBaseRM, w::VecNum, X::MatNum,
                           fees::Option{<:Fees}; kwargs...)

Return the chain-rule weight of each element of a vector of risk measures at w, or nothing for a single measure.

The weights are scalariser_gradient_weights of the scaled values $s_k R_k(\boldsymbol{w})$, the values that expected_risk scalarises. risk_gradient and risk_contribution take them once, at the weights they are asked at, so the finite difference never moves the element that a maximum or a minimum picks.

Arguments

  • sca: Scalariser that combines the elements.
  • r, rs: One risk measure, or a vector of them.
  • w::VecNum: Portfolio weights vector assets × 1.
  • X::MatNum: Returns matrix observations × assets.
  • fees: Optional Fees structure.

Returns

  • ps::Option{<:VecNum}: One weight per element of rs, or nothing for a single measure.

Related

source