High order factor Prior estimator: private API
PortfolioOptimisers.AbstractHiLoOrderPriorEstimator_F — Type
const AbstractHiLoOrderPriorEstimator_F = Union{AbstractLowOrderPriorEstimator_F,
AbstractHighOrderPriorEstimator_F}Groups the two families that require factor returns, one for each order.
A member of AbstractHiLoOrderPriorEstimator_F cannot fit without factor returns, at either order, and it answers true to needs_factor_returns. The checks at entry that look for a missing factor matrix call that predicate, not an isa test on this union. An estimator with an optional factor argument can hold a member of this union. The predicate reads the whole tree, and an isa test reads only the outer estimator.
Related
PortfolioOptimisers.coskewness_residuals — Function
coskewness_residuals(X::MatNum, me::AbstractExpectedReturnsEstimator)Build the residual coskewness matrix that a factor lift adds to its projected coskewness.
X is the residual matrix X - posterior_X, not the asset returns. The factor model assumes that the residuals have zero mean and are independent across assets. So each cross term of their coskewness is zero, and only the N third moments of the single assets remain.
The function does not remove the mean. The assumption of zero mean belongs to the factor model, and me gives the rule of the average, not a centre. When the residuals have a mean $c_i$ that is not zero, the remaining entries hold the raw third moment $\mathbb{E}[(\varepsilon_i + c_i)^3]$ and not the central third moment. The result is a coskewness only when the assumption holds.
Mathematical definition
\[(\hat{\mathbf{M}}_{3,\varepsilon})_{i,\,c} = \begin{cases} \mathbb{E}[\varepsilon_i^3]\,, & c = (i - 1)N + i\,, \\ 0\,, & \text{otherwise.} \end{cases}\]
Where:
- $\varepsilon_i$: Residual of asset $i$, column $i$ of
X. - $N$: Number of assets.
- $\hat{\mathbf{M}}_{3,\varepsilon}$: The $N \times N^2$ residual coskewness matrix,
sk_err.
Column $(i - 1)N + i$ of a coskewness matrix holds the products $\varepsilon_i \varepsilon_i$. In row $i$, this column is the one entry that independent residuals with zero mean can make different from zero.
Algorithm
- Take
N = size(X, 2)andN2 = N^2. - Cube each entry of the residuals, and call the result
X3. - Allocate
sk_err, anN × N2sparse zero matrix of the element type ofX3. - Take
idx, the range of linear indices1:(N2 + N + 1):(N2 * N). Julia stores anN × N2matrix column by column, so entryiofidxis the linear index of(i, (i - 1) * N + i). - Average the columns of
X3underme, and write theNvalues atidx.
Arguments
X: Residual return matrix (observations × assets).me: Expected returns estimator. The function averages the cubed residuals with it.
Returns
sk_err::SparseMatrixCSC:N × N²residual coskewness matrix.
Related
PortfolioOptimisers.cokurtosis_residuals — Function
cokurtosis_residuals(sigma::MatNum, X::MatNum, me::AbstractExpectedReturnsEstimator,
ex::FLoops.Transducers.Executor = FLoops.ThreadedEx())Build the residual cokurtosis matrix that a factor lift adds to its projected cokurtosis.
X is the residual matrix X - posterior_X, not the asset returns. sigma is the systematic covariance $\mathbf{B} \mathbf{\Sigma}_f \mathbf{B}^\intercal$, with no residual block. The caller removes the residual block, see factor_residual_config.
The function does not standardise the residuals. It writes each entry in closed form from sigma and from the second and fourth residual moments, e2 = mean(me, X .^ 2) and e4 = mean(me, X .^ 4). The closed form uses the assumption of the factor model. The residuals have zero mean, and they are independent of each other and of the factors. Under this assumption, each pattern of indices gives one branch of the loop. Only the pattern with four distinct indices gives zero.
Entry (i - 1) * N + k, (j - 1) * N + l of the result is the residual contribution to $\mathbb{E}[r_i r_k r_j r_l]$. The matrix is symmetric, so the function computes only the upper triangle, and writes each value to both places.
Mathematical definition
Write $r_i = s_i + \varepsilon_i$, with $s_i$ the systematic return and $\varepsilon_i$ the residual. The residual contribution is $\mathbb{E}[r_i r_k r_j r_l] - \mathbb{E}[s_i s_k s_j s_l]$. It depends on the four indices only through which of them are equal:
\[(\hat{\mathbf{\Sigma}}_{4,\varepsilon})_{(i-1)N+k,\;(j-1)N+l} = \begin{cases} 6 e_{2,a} \mathbf{\Sigma}_{aa} + e_{4,a}\,, & i = k = j = l = a\,, \\ 3 e_{2,a} \mathbf{\Sigma}_{ab}\,, & \text{three indices are } a \text{ and the fourth is } b\,, \\ e_{2,a} \mathbf{\Sigma}_{bb} + e_{2,b} \mathbf{\Sigma}_{aa} + e_{2,a} e_{2,b}\,, & \text{two pairs, } a \text{ and } b\,, \\ e_{2,a} \mathbf{\Sigma}_{bc}\,, & \text{one pair } a \text{, and singles } b \text{ and } c\,, \\ 0\,, & \text{all four distinct.} \end{cases}\]
Where:
- $e_{2,i} = \mathbb{E}[\varepsilon_i^2]$, $e_{4,i} = \mathbb{E}[\varepsilon_i^4]$: The second and fourth residual moments,
e2ande4. - $\mathbf{\Sigma}$: The systematic covariance,
sigma. - $N$: Number of assets.
- $\hat{\mathbf{\Sigma}}_{4,\varepsilon}$: The $N^2 \times N^2$ residual cokurtosis matrix,
kt_res.
A single $\varepsilon$ term has a mean of zero, and a single $s$ term is centred, which removes the terms of odd power. With four distinct indices, no $\varepsilon$ meets itself, so only this case is zero. A pattern with one pair and two single indices is not zero. The pair gives $e_{2,a}$, and the two single indices give their systematic covariance.
Algorithm
- Take
N = size(X, 2)andN2 = N^2. - Raise each entry of the residuals to the second and to the fourth power, and call the results
X2andX4. - Average the columns of each under
me, and call the resultse2ande4. - Allocate
kt_res, of size(N2, N2), in the promotion of the element types ofe4andsigma. - Run
exover theN2column pairs(j, l). For each column, read the row pairs(i, k), and skip the pair whenrow > col, which keeps the loop to the upper triangle. - Select the value
valfor(i, k, j, l)with the chain of branches of the closed form above. The chain tests the patterns with the most equal indices first, so each pattern gets to its own branch before a branch for fewer equal indices. - Write
valtokt_res[row, col]and tokt_res[col, row].
The executor changes only the order of the columns. One iteration of the loop writes each entry, so FLoops.SequentialEx() and FLoops.ThreadedEx() give bit-identical results.
Arguments
sigma: Systematic covariance matrix,N × N.X: Residual return matrix (observations × assets).me: Expected returns estimator. The function averages the squared and the fourth-power residuals with it.ex:FLoopsexecutor for the loop over theN²columns. The default isFLoops.ThreadedEx().
Returns
kt_res::Matrix:N² × N²residual cokurtosis matrix.
Related
PortfolioOptimisers.assert_cokurtosis_processor — Function
assert_cokurtosis_processor(kte::Nothing) -> nothing
assert_cokurtosis_processor(kte::CokurtosisEstimator) -> nothingCheck at construction that a HighOrderFactorPriorEstimator can read the processor of its cokurtosis estimator kte.
The prior processes the lifted cokurtosis for each value of rsd, so the check runs for each value of rsd. With this check, a type with no method of cokurtosis_processor fails in the constructor, and not at the fit.
Algorithm
- For
nothing, returnnothing. The prior lifts no cokurtosis. - For a
CokurtosisEstimator, get its processor fromcokurtosis_processor. The fallback of that verb refuses a type with no method of its own. - Check that the processor is
nothingor anAbstractMatrixProcessingEstimator.
Arguments
kte: Cokurtosis estimator, ornothing.
Validation
- The type of
ktehas a method ofcokurtosis_processor. AnArgumentErroris thrown otherwise. - The method returns
nothingor anAbstractMatrixProcessingEstimator. AnArgumentErroris thrown otherwise.
Returns
nothing.
Related
PortfolioOptimisers.assert_factor_comoment_residuals — Function
assert_factor_comoment_residuals(kte::Option{<:CokurtosisEstimator},
ske::Option{<:CoskewnessEstimator}) -> nothingCheck at construction that a HighOrderFactorPriorEstimator with rsd = true can read from kte and ske what its residual corrections need.
With this check, a co-moment estimator with no method fails in the constructor, and not at the fit.
Algorithm
- When
kteis notnothing, get its expected returns estimator fromcokurtosis_expected_returns, and check its type. Get its processor fromcokurtosis_processor, and check the repair of the processor withassert_matrix_processing_posdef. - When
skeis notnothing, get its expected returns estimator fromcoskewness_expected_returns, and check its type.
Arguments
kte: Cokurtosis estimator, ornothing.ske: Coskewness estimator, ornothing.
Validation
- The fallbacks of
cokurtosis_expected_returnsandcoskewness_expected_returnsrefuse a type with no method. AnArgumentErroris thrown. - Each method returns an
AbstractExpectedReturnsEstimator. AnArgumentErroris thrown otherwise. - The processor of
ktepassesassert_matrix_processing_posdef.
Returns
nothing.
Related
PortfolioOptimisers.show_fields — Method
show_fields(
_::HighOrderFactorPriorEstimator
) -> NTuple{6, Symbol}
Give every field of a HighOrderFactorPriorEstimator to print, except cache.
The state in cache changes at each step of an incremental fit, and it is not part of the configuration. Each site that prints the estimator also prints this state, unless this method leaves it out. Set set_show_nothing_fields!(:HighOrderFactorPriorEstimator, true) to print it.
Arguments
::HighOrderFactorPriorEstimator: Prior estimator. The method reads its type alone.
Returns
fields::Tuple: The names of the fields to print,(:pe, :kte, :ske, :ex, :rsd, :x_src).
Related