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
MatNumAbstractPriorResultReturnsResultresolve_risk_inputs: Resolves each member to a measure and a matrix.risk_contribution
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
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
factoryand returnspr.X. A Deferred Quantity becomes a value, and a slot that the measure leaves unstated takes the field of the prior. - A
ReturnsResultcarries no moments, so the method returnsrd.X. It binds everyDataBenchmarkTrackingof the measure to the benchmark of the rows,rd.B, withbind_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
PortfolioOptimisers.difference_risk — Function
difference_risk(r::AbstractBaseRiskMeasure, wd::VecNum, w::VecNum, X::MatNum,
fees::Option{<:Fees}) -> NumberCompute 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
wof the tracking specificationtr. - $F(\boldsymbol{w})$: Fee series $T \times 1$ of the portfolio, zero when
feesisnothing. Seecalc_net_returns.
Algorithm
- A
nothingfee returnsexpected_risk(r, wd, X), because the two series are equal without a fee. - A measure that reads a return series,
NetReturnsInput, reads $\boldsymbol{x}$. - A measure that reads the weights alone,
WeightsInput, readswdand no fee. - A moment measure resolves its observation weights against
Xwithresolve_observation_weights. It reads $\boldsymbol{x}$ and takes its target fromwd. So a per-asset target is $(\boldsymbol{w} - \boldsymbol{w}_b)^\intercal \boldsymbol{\mu}$ minus the mean fee of the portfoliow, frommoment_target_fees, as in the model. - A
TrackingRiskMeasuretakes the norm of $\boldsymbol{x}$ minus its own benchmark series. - A nested
RiskTrackingRiskMeasurerecurses. The independent mode subtracts its own benchmark weights fromwd. The dependent mode subtracts the risk of its own benchmark weights, which pay their own fee, as in the model. - A
RiskRatioand aNonOptimisationRiskRatiodivide the results of their two sides. AMeanReturnRiskRatiodivides the mean of $\boldsymbol{x}$, minusrf, by the result of its risk side, and anExpectedReturnRiskRatiodoes the same with the expected return ofwdminus the fee of the portfoliow. A vector side scalarises the results of its measures, each times itssettings.scale, with the scalariser of the ratio. AVarianceSkewKurtosisreadswdand no fee. AnExpectedReturnreads the expected return ofwd, minus the fee of the portfoliow, throughresolved_expected_return. - Any other
WeightsReturnsFeesInputmeasure reads $\boldsymbol{x}$ throughexpected_risk_from_returns, which refuses a measure that cannot read a series.
Arguments
r: Tracked risk measure.wd: Weight differenceassets × 1.w: Portfolio weights vectorassets × 1.X: Asset returns matrixobservations × assets.fees: Fee of the portfoliow, ornothing.
Returns
rk::Number: The risk ofwdon the series $\boldsymbol{x}$.
Related
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
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
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.
nothing: returnrr. The reader fits its own loadings only when the prior holds none.PriorSource: returnrr, and refuserr === nothing.- Every other source,
DataSourceandExcessSourceincluded: returnnothing. The reader fits its loadings on the matrix thatbenchmark_relative_returnsgives for its source.
Arguments
x_src: The source of the regression reader,returns_source(re).rr: The loadings of the prior, ornothingwhen 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 anArgumentErrorthat names the three sources that fit the loadings on the returns data.
Returns
rr::Option{<:AbstractLoadingsRegressionResult}: The loadings to take, ornothingto fitre.
Related
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_src | The function returns |
|---|---|
nothing | pr.rr, else a fit on rd.X |
DataSource | a fit on rd.X |
ExcessSource | a fit on rd.X - rd.B, the Excess Frame |
PriorSource | pr.rr, and it refuses a prior that holds none |
Algorithm
- When
reis anAbstractLoadingsRegressionResult, returnre. - Return the loadings that
source_loadingstakes frompr.rrunder the source ofre, whichreturns_sourcereads, when they are notnothing. - Otherwise fit
rewithrefit_factor_regression.
Arguments
re::RegE_Reg: Regression result or estimator.rd::ReturnsResult: Returns result carryingXandF.pr::Option{<:AbstractPriorResult}: Prior result, ornothingwhen the caller passed a bare matrix.
Validation
- The rule of
source_loadings: underPriorSource(), a call with no prior loadings throws anArgumentError. - The rules of
refit_factor_regression, when the function fitsre.
Returns
rr::AbstractLoadingsRegressionResult: The factor loadings.
Related
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
- Check that
rd.Xandrd.Fare present. - Drop the observations of a Shared Series gap with
shared_series_fitunderx_src: a gap of the factor returns, and a gap of a vector benchmark underExcessSource(). Each fixed observation weight in the tree ofreloses the same observations. - Read the asset returns with
benchmark_relative_returnsunderx_src, givingX. Fit and returnregression(re, X, rd.F).
Arguments
re::AbstractTimeSeriesRegressionEstimator: Regression reader to fit.rd::ReturnsResult: Returns result carryingXandF.pr::Option{<:AbstractPriorResult}: Prior result of the caller, ornothing. Only the message of the refusal reads it.
Validation
!isnothing(rd.X)and!isnothing(rd.F). Throws anIsNothingErrorthat names the three argumentsre,prandrdthat can supply loadings.- The rules of
benchmark_relative_returns.
Returns
rr::AbstractLoadingsRegressionResult: The fitted loadings.
Related
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$:
scaleof 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, ornothingfor a single measure.q,qs: Worst-Case Distribution of the measure, or of each element of the vector, fromelement_worst_case_distributions.r: Risk measure or vector of risk measures.w::VecNum: Portfolio weights vectorassets × 1.X::MatNum: Returns matrixobservations × assets.fees: OptionalFeesstructure.
Returns
rk::Number: The homogeneity-adjusted risk.
Related
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
- Copy
winto both columns of theN × 2work matrixws, whose type promotes the type ofwwith the type ofdelta. - For each asset
i, adddeltato entryiof the first column, and subtractdeltafrom entryiof the second column. - Set
g[i]to the difference offat the two columns, timesid2 = inv(2 * delta). - Restore entry
iof both columns tow[i], and go to the next asset.
Arguments
f: Scalar function of a weight vector.w::VecNum: Portfolio weights vectorassets × 1.delta::Number: Step of the finite difference.
Returns
g::Vector: The finite-difference gradient, one entry for each asset.
Related
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 vectorassets × 1.X::MatNum: Returns matrixobservations × assets.fees: OptionalFeesstructure.delta::Number: Step of the finite difference.
Returns
g::Vector: The gradient, one entry for each asset.
Related
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
gammaof aLogSumExpScalariser, 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
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 vectorassets × 1.X::MatNum: Returns matrixobservations × assets.fees: OptionalFeesstructure.
Returns
ps::Option{<:VecNum}: One weight per element ofrs, ornothingfor a single measure.
Related