High Order Prior: private API
PortfolioOptimisers.block_vec_pq — Function
block_vec_pq(A::MatNum, p::Integer, q::Integer)Block vectorisation operator.
block_vec_pq cuts A into blocks of size (p, q), and writes the vectorisation of each block as one row of the result. get_kt_Akt_pm applies it to the square cokurtosis kt with p = q = N, and takes the eigendecomposition of the result for the kurtosis risk constraints.
Mathematical definition
Cut $\mathbf{A}$ into $m \times n$ blocks $\mathbf{A}_{ij}$ of size $p \times q$. The block vectorisation writes each block as one row, in the order of the block columns:
\[\mathcal{V}_{p,q}(\mathbf{A}) = \begin{bmatrix} \mathrm{vec}(\mathbf{A}_{11})^\intercal \\ \vdots \\ \mathrm{vec}(\mathbf{A}_{m1})^\intercal \\ \mathrm{vec}(\mathbf{A}_{12})^\intercal \\ \vdots \\ \mathrm{vec}(\mathbf{A}_{mn})^\intercal \end{bmatrix}\,.\]
Where:
- $\mathbf{A}_{ij}$: Block $(i, j)$ of $\mathbf{A}$. It holds rows $(i-1)p+1$ to $ip$ and columns $(j-1)q+1$ to $jq$.
- $\mathrm{vec}$: Column-major vectorisation.
- $m = \mathrm{size}(\mathbf{A}, 1) / p$, $n = \mathrm{size}(\mathbf{A}, 2) / q$: The counts of blocks.
Row $(j-1)m + i$ of the result is $\mathrm{vec}(\mathbf{A}_{ij})^\intercal$, so the index of the block column changes slowest. The order that changes the index of the block row slowest puts $\mathrm{vec}(\mathbf{A}_{12})^\intercal$ in row 2 of the example below, where this order puts $\mathrm{vec}(\mathbf{A}_{21})^\intercal$. The two orders agree when every block $\mathbf{A}_{ij}$ equals $\mathbf{A}_{ji}$. The square cokurtosis is such a matrix up to rounding, because its entry $\mathbb{E}[r_i r_k r_j r_l]$ does not change when $i$ and $j$ change places.
Algorithm
- Read
size(A)intompandnq, and check both divisibility conditions. - Take the block counts
m = mp ÷ pandn = nq ÷ q. - Allocate
A_vec, of size(m * n, p * q). - For each block column
jfrom0ton - 1, buildAj. Rowi + 1ofAjis the vectorisation of the block in block rowiand block columnjofA. - Write
Ajinto rowsj * m + 1to(j + 1) * mofA_vec.
Arguments
A: Input matrix of size(m * p, n * q), wheremandnare integers.p: Number of rows in each block.q: Number of columns in each block.
Validation
size(A, 1)must be an integer multiple ofp.size(A, 2)must be an integer multiple ofq.
Returns
A_vec::Matrix: Block vectorised matrix of size(m * n, p * q).
Examples
julia> A = [1 2 3 4; 5 6 7 8; 9 10 11 12; 13 14 15 16];julia> PortfolioOptimisers.block_vec_pq(A, 2, 2)4×4 Matrix{Int64}: 1 5 2 6 9 13 10 14 3 7 4 8 11 15 12 16Related
References
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Appendix A.1, Equation A.14. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
PortfolioOptimisers.elimination_matrix — Function
elimination_matrix(n::Int, diag::Bool = true)Construct the elimination matrix for a symmetric matrix of size n × n.
The elimination matrix L keeps the lower triangle of a matrix, which holds every distinct entry of a symmetric matrix. A HighOrderPrior holds it as L2 beside the square cokurtosis kt.
Mathematical definition
This identity defines $\mathbf{L}_n$, for every $\mathbf{A}$ of size $n \times n$:
\[\mathbf{L}_n \mathrm{vec}(\mathbf{A}) = \mathrm{vech}(\mathbf{A})\,.\]
With diag = false, the matrix also drops the diagonal. The source defines the matrix with the diagonal. The library adds the form without it.
\[\mathbf{L}_n^{-} \mathrm{vec}(\mathbf{A}) = \mathrm{vech}^{-}(\mathbf{A})\,.\]
Where:
- $\mathrm{vec}$: Column-major vectorisation, of length $n^2$.
- $\mathrm{vech}$: Half-vectorisation, which reads the lower triangle column by column, of length $n(n+1)/2$.
- $\mathrm{vech}^{-}$: The strictly lower triangle, read in the same order, of length $n(n-1)/2$.
The identity holds for every square $\mathbf{A}$, symmetric or not, because $\mathbf{L}_n$ reads the lower triangle alone. diag = false removes the $n$ rows that read the diagonal. The row count falls from $n(n+1)/2$ to $n(n-1)/2$, and the column count stays $n^2$.
Algorithm
- Take
nsq = n^2. - Set the row count
m, the column rangergand the offsetbfromdiag. Whendiagistrue, they arem = n(n+1)/2,rg = 1:nandb = 0. Otherwise they arem = n(n-1)/2,rg = 2:nandb = 1. - Fill
v. Entryrofvis the position in $\mathrm{vec}(\mathbf{A})$ of entryrof the half-vectorisation. The offsetbskips the entries above the diagonal. Underdiag = false, it also skips the diagonal entry. - Return the sparse matrix of size
m × nsqthat holds a one at each(r, v[r]).
Arguments
n: Size of the symmetric matrix.diag:trueto include the diagonal entries,falseto drop them.
Returns
- Sparse elimination matrix.
Related
duplication_matrixsummation_matrixdup_elim_sum_matrices: builds this matrix and the other two in one loop.
References
- [304] J. R. Magnus and H. Neudecker. The elimination matrix: some lemmas and applications. SIAM Journal on Algebraic Discrete Methods 1, 422–449 (1980). Section 3, Definition 3.1a.
PortfolioOptimisers.summation_matrix — Function
summation_matrix(n::Int, diag::Bool = true)Construct the summation matrix for a symmetric matrix of size n × n.
The summation matrix S reads the lower triangle of a symmetric matrix, and adds each off-diagonal entry once for each of its two places. A HighOrderPrior holds it as S2 beside the square cokurtosis kt, and the kurtosis risk constraints read S2 * kt * transpose(S2).
Mathematical definition
$\mathbf{S}_n$ is the elimination matrix, with each row multiplied by the number of places that $\mathbf{D}_n$ copies its entry to:
\[\mathbf{S}_n = \mathbf{D}_n^\intercal \mathbf{D}_n \mathbf{L}_n\,,\]
so that, for every symmetric $\mathbf{A}$ of size $n \times n$,
\[\boldsymbol{1}^\intercal \mathbf{S}_n \mathrm{vec}(\mathbf{A}) = \boldsymbol{1}^\intercal \mathrm{vec}(\mathbf{A})\,.\]
Where:
- $\mathbf{D}_n$: The duplication matrix of
duplication_matrix. - $\mathbf{L}_n$: The elimination matrix of
elimination_matrix. - $\boldsymbol{1}$: Vector of ones, of the length that the product next to it needs.
$\mathbf{S}_n$ reads the lower triangle. It multiplies each entry by the number of places that the entry has in $\mathrm{vec}(\mathbf{A})$, which is one for a diagonal entry and two for an off-diagonal entry. The sum identity above follows from this. It holds for a symmetric $\mathbf{A}$ alone, because $\mathbf{S}_n$ counts each lower entry in place of the upper entry that mirrors it.
The same construction with diag = false gives $\mathbf{S}_n^{-} = (\mathbf{D}_n^{-})^\intercal \mathbf{D}_n^{-} \mathbf{L}_n^{-}$. It multiplies each of its $n(n-1)/2$ rows by two. For a symmetric $\mathbf{A}$, its sum identity thus adds the off-diagonal entries alone, $\boldsymbol{1}^\intercal \mathbf{S}_n^{-} \mathrm{vec}(\mathbf{A}) = \boldsymbol{1}^\intercal \mathrm{vec}(\mathbf{A} - \mathrm{diag}(\mathbf{A}))$. The source defines the matrix with the diagonal. The library adds the form without it.
Algorithm
The function builds the product of the definition, and it does not build $\mathbf{D}_n$.
- Take
nsq = n^2. Set the row countm, the column rangergand the offsetbfromdiag, aselimination_matrixdoes. - Read the columns in
rg. Write the $\mathrm{vec}$ position of each entry of the half-vectorisation intov1. For each strictly lower entry, write its $\mathrm{vec}$ position intov2and its row of the half-vectorisation intorows2. - Remove the zero entries of
v1,v2androws2. Step 2 did not write to these positions. - When
diagistrue, return the sum of two sparse matrices. The first holds a one at each(r, v1[r]), and it is $\mathbf{L}_n$. The second holds a one at each(rows2[k], v2[k]), and it adds a second one to each off-diagonal row. - When
diagisfalse, every row is off-diagonal. Return the sparse matrix that holds a two at each(r, v1[r]). This branch does not readv2androws2.
Arguments
n: Size of the symmetric matrix.diag:trueto include the diagonal entries,falseto drop them.
Returns
- Sparse summation matrix.
Related
duplication_matrixelimination_matrixdup_elim_sum_matrices: builds this matrix and the other two in one loop. It computes this matrix as the product of the definition, not by the construction above.
References
- [66] D. Cajas. Convex Optimization of Portfolio Kurtosis. Available at SSRN 4202967 (2022). Section 2, footnote 5.
PortfolioOptimisers.dup_elim_sum_matrices — Function
dup_elim_sum_matrices(n::Int)Construct the duplication, elimination and summation matrices for a symmetric matrix of size n × n.
dup_elim_sum_matrices returns the duplication matrix D, the elimination matrix L and the summation matrix S. The high order priors store them as D2, L2 and S2 of a HighOrderPrior.
The three are the diag = true matrices of duplication_matrix, elimination_matrix and summation_matrix. This function builds them in one loop over the columns, not in three.
Mathematical definition
For every symmetric $\mathbf{A}$ of size $n \times n$:
\[\begin{align} \mathbf{D}_n \mathrm{vech}(\mathbf{A}) &= \mathrm{vec}(\mathbf{A})\,, \\ \mathbf{L}_n \mathrm{vec}(\mathbf{A}) &= \mathrm{vech}(\mathbf{A})\,, \\ \mathbf{S}_n &= \mathbf{D}_n^\intercal \mathbf{D}_n \mathbf{L}_n\,. \end{align}\]
Where:
- $\mathrm{vec}$: Column-major vectorisation, of length $n^2$.
- $\mathrm{vech}$: Half-vectorisation, which reads the lower triangle column by column, of length $n(n+1)/2$.
The third line gives $\boldsymbol{1}^\intercal \mathbf{S}_n \mathrm{vec}(\mathbf{A}) = \boldsymbol{1}^\intercal \mathrm{vec}(\mathbf{A})$. $\mathbf{S}_n$ reads the lower triangle, and it multiplies each off-diagonal entry by two, the number of its places in $\mathrm{vec}(\mathbf{A})$.
Algorithm
- Check that
nis positive. - Take
m = n(n+1)/2andnsq = n^2. - Read the columns once, and fill
v1andv2in the same loop.v1is the vector of column indices ofduplication_matrix, andv2is the vector of column indices ofelimination_matrix. - Build
d, the sparse matrix of sizensq × mthat holds a one at each(r, v1[r]). - Build
l, the sparse matrix of sizem × nsqthat holds a one at each(r, v2[r]). - Build
sas the producttranspose(d) * d * lof the definition above. This is not the construction ofsummation_matrix.
Arguments
n: Size of the symmetric matrix.
Validation
n > 0.
Returns
D::SparseMatrixCSC{Int64, Int64}: Duplication matrix (n^2 × m), wherem = n(n+1)/2.L::SparseMatrixCSC{Int64, Int64}: Elimination matrix (m × n^2).S::SparseMatrixCSC{Int64, Int64}: Summation matrix (m × n^2).
Examples
julia> D, L, S = PortfolioOptimisers.dup_elim_sum_matrices(3);julia> D9×6 SparseArrays.SparseMatrixCSC{Int64, Int64} with 9 stored entries: 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1julia> L6×9 SparseArrays.SparseMatrixCSC{Int64, Int64} with 6 stored entries: 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1julia> S6×9 SparseArrays.SparseMatrixCSC{Int64, Int64} with 6 stored entries: 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 2 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 2 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 2 ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ ⋅ 1Related
References
- [304] J. R. Magnus and H. Neudecker. The elimination matrix: some lemmas and applications. SIAM Journal on Algebraic Discrete Methods 1, 422–449 (1980). Section 3, Definitions 3.1a and 3.2a.
- [66] D. Cajas. Convex Optimization of Portfolio Kurtosis. Available at SSRN 4202967 (2022). Section 2, footnote 5.
PortfolioOptimisers.duplication_matrix — Function
duplication_matrix(n::Int, diag::Bool = true)Construct the duplication matrix for a symmetric matrix of size n × n.
The duplication matrix D maps the half-vectorisation of a symmetric matrix to its full vectorisation. A HighOrderPrior holds it as D2 beside the coskewness sk.
Mathematical definition
This identity defines $\mathbf{D}_n$, for every symmetric $\mathbf{A}$ of size $n \times n$:
\[\mathbf{D}_n \mathrm{vech}(\mathbf{A}) = \mathrm{vec}(\mathbf{A})\,.\]
With diag = false, the half-vectorisation drops the diagonal, and the identity gives the matrix with a zero diagonal. The source defines the matrix with the diagonal. The library adds the form without it.
\[\mathbf{D}_n^{-} \mathrm{vech}^{-}(\mathbf{A}) = \mathrm{vec}(\mathbf{A} - \mathrm{diag}(\mathbf{A}))\,.\]
Where:
- $\mathrm{vec}$: Column-major vectorisation, of length $n^2$.
- $\mathrm{vech}$: Half-vectorisation, which reads the lower triangle column by column, of length $n(n+1)/2$.
- $\mathrm{vech}^{-}$: The strictly lower triangle, read in the same order, of length $n(n-1)/2$.
- $\mathrm{diag}(\mathbf{A})$: The diagonal of $\mathbf{A}$, as a diagonal matrix.
Each row of $\mathbf{D}_n$ holds one entry, so the matrix copies entries and adds none. It copies a diagonal entry of $\mathbf{A}$ to one place and an off-diagonal entry to two. The product $\mathbf{D}_n^\intercal \mathbf{D}_n$ is the diagonal matrix of these counts, and summation_matrix applies it as a weight.
Algorithm
- Take
m = n(n+1)/2andnsq = n^2. - Fill
v. Entryrofvis the position in $\mathrm{vech}(\mathbf{A})$ of the entry in rowrof $\mathrm{vec}(\mathbf{A})$. For each column, the inner loops read the strictly upper part first, and then the lower part. - When
diagistrue, return the sparse matrix of sizensq × mthat holds a one at each(r, v[r]). - When
diagisfalse, count how many times each position occurs inv, and put the counts incounts. - Keep the positions that occur more than once. These are the off-diagonal positions. Number them again from one, and put the numbers in
cols. - Keep every row of $\mathrm{vec}(\mathbf{A})$ whose position step 5 kept, and put the pairs in
filtered_rowsandfiltered_cols. - Return the sparse matrix of size
nsq × n(n-1)/2that holds a one at each kept pair.
Arguments
n: Size of the symmetric matrix.diag:trueto include the diagonal entries,falseto drop them.
Returns
- Sparse duplication matrix.
Related
elimination_matrixsummation_matrixdup_elim_sum_matrices: builds this matrix and the other two in one loop.
References
- [304] J. R. Magnus and H. Neudecker. The elimination matrix: some lemmas and applications. SIAM Journal on Algebraic Discrete Methods 1, 422–449 (1980). Section 3, Definition 3.2a.
PortfolioOptimisers.dup_elim_sum_view — Method
dup_elim_sum_view(args...)Return three nothing values when the first argument is not a matrix.
This is the fallback of dup_elim_sum_view. It builds no matrix and reads no argument. The matrix method calls dup_elim_sum_matrices.
port_opt_view on a HighOrderPrior calls dup_elim_sum_view at two sites, with pr.kt as the first argument. It calls it only when pr holds D2 or S2. The constructor of HighOrderPrior refuses S2 without kt, and the estimators of the library set D2 only together with kt and sk. So no estimator of the library makes a HighOrderPrior that reaches this method. A HighOrderPrior that a caller builds by hand with D2 and no kt reaches it, because D2 is the one moment field that the constructor accepts alone.
This method takes a variable number of arguments, so it also answers each call whose count of arguments the matrix method does not take. For a matrix M, dup_elim_sum_view(M, n) reaches the matrix method, and dup_elim_sum_view(M, n, extra) reaches this method.
Algorithm
- Return
(nothing, nothing, nothing), and read no argument.
Arguments
args...: Any arguments. None is read.
Returns
(nothing, nothing, nothing)::Tuple{Nothing, Nothing, Nothing}.
Related
PortfolioOptimisers.dup_elim_sum_view — Method
dup_elim_sum_view(
_::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
n
) -> Tuple{SparseArrays.SparseMatrixCSC{Int64, Int64}, SparseArrays.SparseMatrixCSC{Int64, Int64}, SparseArrays.SparseMatrixCSC{Int64, Int64}}
Compute the duplication, elimination and summation matrices at the dimension that the caller gives.
This is the method of dup_elim_sum_view for a matrix as the first argument. The method uses the matrix for dispatch alone. The dimension is the second argument n, not a size of the matrix. port_opt_view on a HighOrderPrior needs this. It passes the full N^2 × N^2 cokurtosis of the prior result and the asset count of the subproblem. The method then builds the three matrices again at the smaller dimension, and does not cut them from the larger ones.
Algorithm
- Pass
ntodup_elim_sum_matrices, and return its three matrices.
Arguments
- The first argument: Any matrix. It selects this method, and the method does not read it.
n: Size of the symmetric matrix for which the method builds the three matrices.
Returns
(D, L, S)::Tuple{SparseMatrixCSC, SparseMatrixCSC, SparseMatrixCSC}: The three matrices ofdup_elim_sum_matricesat dimensionn.
Related
PortfolioOptimisers.assemble_high_order_prior — Function
assemble_high_order_prior(
pe::HighOrderPriorEstimator,
pr::AbstractPriorResult,
kt::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
sk::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
V
) -> HighOrderPrior{__T_pr, __T_kt, __T_D2, __T_L2, __T_S2, __T_sk, __T_V, __T_skmp, Nothing} where {__T_pr, __T_kt, __T_D2, __T_L2, __T_S2, __T_sk, __T_V, __T_skmp}
assemble_high_order_prior(
pe::HighOrderPriorEstimator,
pr::AbstractPriorResult,
kt::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
sk::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
V,
eoc::Tuple
) -> Union{HighOrderPrior{T, T1, T2, T3, T4, T5, Nothing, Nothing, Nothing} where {T, T1, T2, T3, T4, T5}, HighOrderPrior{T, T1, T2, T3, T4, T5, <:AbstractMatrix{var"#s166"}, Nothing, Nothing} where {T, T1, T2, T3, T4, T5, var"#s166"<:Union{Number, AbstractJuMPScalar}}, HighOrderPrior{T, T1, T2, T3, T4, T5, Nothing, <:AbstractMatrixProcessingEstimator, Nothing} where {T, T1, T2, T3, T4, T5}, HighOrderPrior{T, T1, T2, T3, T4, T5, <:AbstractMatrix{var"#s166"}, <:AbstractMatrixProcessingEstimator, Nothing} where {T, T1, T2, T3, T4, T5, var"#s166"<:Union{Number, AbstractJuMPScalar}}}
Build a HighOrderPrior from a low order prior result and the co-moments of the same fit.
Each fit of a HighOrderPriorEstimator ends here. The batch method calls this function after it computes the two co-moments over the returns of the caller. prior(pe) with no data calls it after it reads the two co-moments from their states. The structure matrices that a consumer needs depend only on which co-moments are present, so this one function holds the rule for both callers.
The function sizes D2, L2 and S2 from the full width of pr.X, which is the width of the expanded co-moments.
Algorithm
- Build
D2,L2andS2when both co-moments are present. BuildL2andS2alone when only the cokurtosis is present. - Build the
HighOrderPriorwith the countseoc. When the coskewness is present, setskmpto the processor ofpe.ske, fromcoskewness_processor. - Warn with
assert_matched_coveragewhen the co-moments hold fewer assets than the low order block.
Arguments
pe: High order prior estimator.pr: The low order prior result of the embedded estimator.kt: The square cokurtosis matrix, ornothing.sk: The coskewness matrix, ornothing.V: The negative spectral coskewness ofsk, ornothing.eoc: The effective counts(T_sk, T_kt)of the two co-moments, fromhigh_order_moment_counts. It is(nothing, nothing)by default.
Validation
- Every check of the constructor of
HighOrderPrior. assert_matched_coveragewarns when the co-moments hold fewer assets than the low order block. It does not throw.
Returns
hop::HighOrderPrior: The high order prior result.
Related
PortfolioOptimisers.high_order_moment_counts — Function
high_order_moment_counts(ske, kte, w, X::MatNum, t::Integer; kwargs...)
-> Tuple{Option{<:Real}, Option{<:Real}}State the effective number of observations of the coskewness and of the cokurtosis of a high order prior, in the form of the field eoc of a HighOrderPrior.
The co-moments are fitted by factory(ske, w) and factory(kte, w) over the rows X, so each is worth the count that its estimator states, through high_order_observation_count. A weighted estimator is worth the count of its weights, which are the weights w of the prior when the prior states them. The denoising step of each co-moment reads the same count. An entry equal to the t rows of the result is written as nothing, through moment_count_entry.
Arguments
ske: The coskewness estimator, ornothing.kte: The cokurtosis estimator, ornothing.w: The observation weights of the prior result, ornothing.X: The rows that the co-moments read,observations × assets.t: The number of rows that the prior result carries inX.kwargs...: The keywords that the prior gives to the fits of the co-moments.
Returns
eoc::Tuple: The entries(T_sk, T_kt)of the fieldeoc.
Related
PortfolioOptimisers.high_order_observation_count — Function
high_order_observation_count(est::Nothing, w, X::MatNum; kwargs...) -> Integer
high_order_observation_count(est::AbstractEstimator, w, X::MatNum; kwargs...) -> RealReturn the effective number of observations of a co-moment that factory(est, w) fits over the rows X.
A high order prior gives the weights w of its low order result to its co-moment estimators, so the count reads the estimator after that substitution, with effective_observation_count. With no estimator the prior fits no co-moment, and the count is size(X, 1).
Arguments
est: The coskewness or cokurtosis estimator, ornothing.w: The observation weights of the prior result, ornothing.X: The rows that the co-moment reads,observations × assets.kwargs...: The keywords of the fit of the co-moment, foreffective_observation_count.
Returns
T_e::Real: The effective number of observations of the co-moment.
Related
PortfolioOptimisers.scenario_rows — Function
scenario_rows(w::Nothing, X::MatNum, pnl::Option{<:AssetPanel})
scenario_rows(w::ObsWeights, X::MatNum, pnl::Option{<:AssetPanel})Cut the rows of X and of its Asset Panel to the scenarios that the probabilities w of a prior result weigh.
A prior result gives w on the rows of its own X, and it can hold fewer rows than the caller passed. A Scenario Cap keeps the last rows. A CrossSectionalFactorPrior drops the first rows, over which its Descriptors warm up. In both cases, w weighs the last length(w) rows of X. A high order estimator fits its co-moments on the X of the caller under w, so it needs these rows. When a prior result gives no w, it weighs every row the same, and the co-moments read every row.
Algorithm
- When
wisnothing, returnXandpnlwith no change. - Otherwise take
t = size(X, 1)ands = length(w), and refuses > t. - When
s == t, returnXandpnlwith no change. - Otherwise take the rows
(t - s + 1):t. Return the view ofXover them, and the view ofpnlover them fromport_opt_view.
Arguments
w: The probabilities of the scenarios of the prior result, ornothing.X: The returns that the caller passed (observations × assets), or the factor returns.pnl: OptionalAssetPanel, the panel that the returns data held. A wrapping prior forwards it unchanged, so that it can compose an estimator that is fitted on a panel. An estimator that reads no panel ignores it.
Validation
length(w) <= size(X, 1). ADimensionMismatchis thrown otherwise.
Returns
X′::MatNum: The rows ofXthatwweighs.pnl′::Option{<:AssetPanel}: The Asset Panel over the same rows, ornothing.
Related
PortfolioOptimisers.read_comoment — Function
read_comoment(f, est, w::Nothing, X::MatNum, pnl::Option{<:AssetPanel}; kwargs...)
read_comoment(f, est, w::ObsWeights, X::MatNum, pnl::Option{<:AssetPanel}; kwargs...)Read a co-moment of a HighOrderPriorEstimator out of its fold, under the probabilities of the scenarios of the embedded prior result.
When the prior result gives no w, it weighs every row the same. Then the function reads the member as read_member does: from its state when the member folded, or by a refit over the rows of the buffer. A prior result that gives a w, such as an entropy pooling prior or an opinion pooling prior, weighs its scenarios with it. A state folds the rows under equal weights, and it cannot read w. So the function refits the member under w in every case, as the batch fit does.
Algorithm
- When
wisnothing, read the member withread_member. - Otherwise cut
Xandpnlto the rows thatwweighs, withscenario_rows. - Give
wto the member withfactory, and callfon the result over the cut rows. The batch verb does not read the state of the member.
Arguments
f: The batch verb of the member,cokurtosisorcoskewness.est: The member, ornothing.w: The probabilities of the scenarios of the embedded prior result, ornothing.X: The rows that the embedded prior folded.pnl: The Asset Panel of the rows, ornothing.kwargs...: Additional keyword arguments, forwarded to the verb.
Validation
- Each condition that
scenario_rowsrefuses.
Returns
val: The co-moment, in the shape thatfreturns.
Related
PortfolioOptimisers.comoment_investable — Function
comoment_investable(
sk::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
kt::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
N::Integer
) -> BitVector
Read the diagonal entry of each asset in every co-moment that a HighOrderPrior holds, and return true at each asset where all of them are finite.
This is the high order part of the Investable Mask. For asset i, take the pair column j = (i - 1) * N + i. The entry sk[i, j] is the third central moment of asset i, and the entry kt[j, j] is its fourth central moment. Each is finite when the fit gave a value for that asset. investable_mask applies the same rule to the diagonal of sigma. A moment that the prior result does not hold removes no asset, so for a nothing moment every asset is true.
Arguments
sk: The coskewness matrix,assets × assets², ornothing.kt: The square cokurtosis matrix,assets² × assets², ornothing.N: Number of assets.
Returns
msk::BitVector:trueat each asset whose high order moments are finite.
Related
PortfolioOptimisers.assert_matched_coverage — Function
assert_matched_coverage(pr::HighOrderPrior)
Warn once when the co-moments of a fitted HighOrderPrior hold fewer assets than its low order block.
A CoveragePolicy is a field of one estimator. A caller can set one on the mean and the covariance of pe.pe, and leave pe.ske and pe.kte on the Coverage Universe. The library accepts this configuration. The low order moments then give a value for an asset that starts to list inside the window, and the co-moments do not. But the Investable Mask then removes these assets again, and the policy has no effect on the problem. The function does not refuse the configuration. It names the assets in a warning, as scenario_fill names the assets whose returns it fills with zeros.
The check runs once, at the fit. It does not run in investable_mask, which a fold loop calls at each entry to an optimiser.
Arguments
pr: The fitted high order prior.
Validation
- The co-moments hold every asset that the low order block holds. The function emits a warning that names the assets otherwise.
Returns
nothing.
Related
PortfolioOptimisers.fold_prior_step — Method
fold_prior_step(pe::HighOrderPriorEstimator, rd::ReturnsResult,
gaps::Option{<:AbstractVector{Bool}})Fold the observations of a ReturnsResult into a HighOrderPriorEstimator. The method passes rd and its marks to the embedded prior.
This is the method of fold_prior_step for an estimator that passes the fold on. partial_fit! over a ReturnsResult calls fold_prior_step for each prior. The outer prior keeps no rows, and its embedded prior keeps them. The route of the embedded prior decides which inputs of the step it accepts. The estimation mask and the Panel Fields get to it with no change, and it refuses each input that its route cannot accept. The estimator also folds pe.kte and pe.ske with fold_member. These folds are exact, and they read the active mask alone, which step_active_kwargs gives. They fold the observations that gaps does not mark, as the members of a carry do, see shared_series_member_rows.
Algorithm
- At the first step, when
pe.peholds no state, refuse a member that holds one, withassert_cold_carry_entry. - Fold
rdandgapsintope.pewithfold_prior_step. - Take the rows of
rd.Xthatgapsdoes not mark, and the same rows of the active mask ofrd.pnl, withshared_series_member_rows. Fold them intope.kteandpe.skewithfold_member. - Rebuild the estimator with its folded members, with
rebuild_struct, and return it.
Arguments
pe: The high order prior estimator.rd: The returns result to use.gaps: One mark for each observation ofrd,trueat an observation with a Shared Series gap, ornothing.
Validation
- Every condition that the fold of
pe.peoverrdchecks. - The rule of
assert_cold_carry_entryat the first step.
Returns
pe: The estimator, with its members folded.
Related
References
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
- [66]
- D. Cajas. Convex Optimization of Portfolio Kurtosis. Available at SSRN 4202967 (2022).
- [304]
- J. R. Magnus and H. Neudecker. The elimination matrix: some lemmas and applications. SIAM Journal on Algebraic Discrete Methods 1, 422–449 (1980).