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

  1. Read size(A) into mp and nq, and check both divisibility conditions.
  2. Take the block counts m = mp ÷ p and n = nq ÷ q.
  3. Allocate A_vec, of size (m * n, p * q).
  4. For each block column j from 0 to n - 1, build Aj. Row i + 1 of Aj is the vectorisation of the block in block row i and block column j of A.
  5. Write Aj into rows j * m + 1 to (j + 1) * m of A_vec.

Arguments

  • A: Input matrix of size (m * p, n * q), where m and n are integers.
  • p: Number of rows in each block.
  • q: Number of columns in each block.

Validation

  • size(A, 1) must be an integer multiple of p.
  • size(A, 2) must be an integer multiple of q.

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  16

Related

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.
source
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

  1. Take nsq = n^2.
  2. Set the row count m, the column range rg and the offset b from diag. When diag is true, they are m = n(n+1)/2, rg = 1:n and b = 0. Otherwise they are m = n(n-1)/2, rg = 2:n and b = 1.
  3. Fill v. Entry r of v is the position in $\mathrm{vec}(\mathbf{A})$ of entry r of the half-vectorisation. The offset b skips the entries above the diagonal. Under diag = false, it also skips the diagonal entry.
  4. Return the sparse matrix of size m × nsq that holds a one at each (r, v[r]).

Arguments

  • n: Size of the symmetric matrix.
  • diag: true to include the diagonal entries, false to drop them.

Returns

  • Sparse elimination matrix.

Related

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.
source
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$.

  1. Take nsq = n^2. Set the row count m, the column range rg and the offset b from diag, as elimination_matrix does.
  2. Read the columns in rg. Write the $\mathrm{vec}$ position of each entry of the half-vectorisation into v1. For each strictly lower entry, write its $\mathrm{vec}$ position into v2 and its row of the half-vectorisation into rows2.
  3. Remove the zero entries of v1, v2 and rows2. Step 2 did not write to these positions.
  4. When diag is true, 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.
  5. When diag is false, every row is off-diagonal. Return the sparse matrix that holds a two at each (r, v1[r]). This branch does not read v2 and rows2.

Arguments

  • n: Size of the symmetric matrix.
  • diag: true to include the diagonal entries, false to drop them.

Returns

  • Sparse summation matrix.

Related

References

  • [66] D. Cajas. Convex Optimization of Portfolio Kurtosis. Available at SSRN 4202967 (2022). Section 2, footnote 5.
source
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

  1. Check that n is positive.
  2. Take m = n(n+1)/2 and nsq = n^2.
  3. Read the columns once, and fill v1 and v2 in the same loop. v1 is the vector of column indices of duplication_matrix, and v2 is the vector of column indices of elimination_matrix.
  4. Build d, the sparse matrix of size nsq × m that holds a one at each (r, v1[r]).
  5. Build l, the sparse matrix of size m × nsq that holds a one at each (r, v2[r]).
  6. Build s as the product transpose(d) * d * l of the definition above. This is not the construction of summation_matrix.

Arguments

  • n: Size of the symmetric matrix.

Validation

  • n > 0.

Returns

  • D::SparseMatrixCSC{Int64, Int64}: Duplication matrix (n^2 × m), where m = 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  ⋅  ⋅  ⋅ ⋅  ⋅  ⋅  ⋅  ⋅  ⋅  ⋅  ⋅  1

Related

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.
source
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

  1. Take m = n(n+1)/2 and nsq = n^2.
  2. Fill v. Entry r of v is the position in $\mathrm{vech}(\mathbf{A})$ of the entry in row r of $\mathrm{vec}(\mathbf{A})$. For each column, the inner loops read the strictly upper part first, and then the lower part.
  3. When diag is true, return the sparse matrix of size nsq × m that holds a one at each (r, v[r]).
  4. When diag is false, count how many times each position occurs in v, and put the counts in counts.
  5. 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.
  6. Keep every row of $\mathrm{vec}(\mathbf{A})$ whose position step 5 kept, and put the pairs in filtered_rows and filtered_cols.
  7. Return the sparse matrix of size nsq × n(n-1)/2 that holds a one at each kept pair.

Arguments

  • n: Size of the symmetric matrix.
  • diag: true to include the diagonal entries, false to drop them.

Returns

  • Sparse duplication matrix.

Related

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.
source
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

  1. Return (nothing, nothing, nothing), and read no argument.

Arguments

  • args...: Any arguments. None is read.

Returns

  • (nothing, nothing, nothing)::Tuple{Nothing, Nothing, Nothing}.

Related

source
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

  1. Pass n to dup_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 of dup_elim_sum_matrices at dimension n.

Related

source
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

  1. Build D2, L2 and S2 when both co-moments are present. Build L2 and S2 alone when only the cokurtosis is present.
  2. Build the HighOrderPrior with the counts eoc. When the coskewness is present, set skmp to the processor of pe.ske, from coskewness_processor.
  3. Warn with assert_matched_coverage when 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, or nothing.
  • sk: The coskewness matrix, or nothing.
  • V: The negative spectral coskewness of sk, or nothing.
  • eoc: The effective counts (T_sk, T_kt) of the two co-moments, from high_order_moment_counts. It is (nothing, nothing) by default.

Validation

Returns

  • hop::HighOrderPrior: The high order prior result.

Related

source
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, or nothing.
  • kte: The cokurtosis estimator, or nothing.
  • w: The observation weights of the prior result, or nothing.
  • X: The rows that the co-moments read, observations × assets.
  • t: The number of rows that the prior result carries in X.
  • 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 field eoc.

Related

source
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...) -> Real

Return 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, or nothing.
  • w: The observation weights of the prior result, or nothing.
  • X: The rows that the co-moment reads, observations × assets.
  • kwargs...: The keywords of the fit of the co-moment, for effective_observation_count.

Returns

  • T_e::Real: The effective number of observations of the co-moment.

Related

source
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

  1. When w is nothing, return X and pnl with no change.
  2. Otherwise take t = size(X, 1) and s = length(w), and refuse s > t.
  3. When s == t, return X and pnl with no change.
  4. Otherwise take the rows (t - s + 1):t. Return the view of X over them, and the view of pnl over them from port_opt_view.

Arguments

  • w: The probabilities of the scenarios of the prior result, or nothing.
  • X: The returns that the caller passed (observations × assets), or the factor returns.
  • pnl: Optional AssetPanel, 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). A DimensionMismatch is thrown otherwise.

Returns

  • X′::MatNum: The rows of X that w weighs.
  • pnl′::Option{<:AssetPanel}: The Asset Panel over the same rows, or nothing.

Related

source
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

  1. When w is nothing, read the member with read_member.
  2. Otherwise cut X and pnl to the rows that w weighs, with scenario_rows.
  3. Give w to the member with factory, and call f on 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, cokurtosis or coskewness.
  • est: The member, or nothing.
  • w: The probabilities of the scenarios of the embedded prior result, or nothing.
  • X: The rows that the embedded prior folded.
  • pnl: The Asset Panel of the rows, or nothing.
  • kwargs...: Additional keyword arguments, forwarded to the verb.

Validation

Returns

  • val: The co-moment, in the shape that f returns.

Related

source
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², or nothing.
  • kt: The square cokurtosis matrix, assets² × assets², or nothing.
  • N: Number of assets.

Returns

  • msk::BitVector: true at each asset whose high order moments are finite.

Related

source
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

source
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

  1. At the first step, when pe.pe holds no state, refuse a member that holds one, with assert_cold_carry_entry.
  2. Fold rd and gaps into pe.pe with fold_prior_step.
  3. Take the rows of rd.X that gaps does not mark, and the same rows of the active mask of rd.pnl, with shared_series_member_rows. Fold them into pe.kte and pe.ske with fold_member.
  4. 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 of rd, true at an observation with a Shared Series gap, or nothing.

Validation

Returns

  • pe: The estimator, with its members folded.

Related

source

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).