Asset Panel Estimators: private API
PortfolioOptimisers._proximity_features — Function
_proximity_features(
alg::Proximity,
sep::AbstractSeparationAlgorithm,
d::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
dmax::Number,
et::Type
) -> Matrix
Score a separation matrix under a decay, inside a budget.
This is the loop of the Proximity method of phylogeny_features. It is a function of its own because it reads the separations alone, and the structure, the estimator and the data play no part in it. A test hands it a disconnected separation matrix to reach the unreachable branch, because every structure that a shipped estimator builds is connected.
Algorithm
- Probe the decay over
0:dmaxthroughassert_separation_decay, before the pair loop. - Allocate
Z, of the element typeetand the size ofd, filled with zeros. - For each pair, read its separation
duv, and askis_relatedwhether it is inside the budget, givingrel. This test also rejects the sentinel of an unreachable pair, so it guards the next step. - Where
relholds, writeseparation_decay(dk, duv, dmax)intoZ[u, v], which is the form thatProximitystates. Where it does not hold, keep the zero of step 2.
Arguments
alg: Proximity algorithm that holds the decay.sep: Separation algorithm that measuredd, forwarded tois_related.d: Separation matrix fromseparation_matrix.dmax: Separation budget fromseparation_budget.et: Element type of the result.phylogeny_featurespasseseltype(X), so thatAngularDistkeeps its BLASgemmpath.
Returns
Z::Matrix: Squareassets × assetsfeature matrix.
Related
PortfolioOptimisers.panel_axis_labels — Function
panel_axis_labels(names::Nothing, n::Integer) -> Vector{String}
panel_axis_labels(names::VecStr, n::Integer) -> Vector{String}Name the label axis of a TensorPanelField that a producer builds, from the returns data or by position.
The field of a producer has a labelled label axis, and neither a loadings matrix nor a proximity matrix holds names for that axis. The returns data is the one place that holds them. rd.nx names the assets of a proximity field, and rd.nf names the factors of a loadings field. When the returns data gives no names, or a wrong number of them, the labels are the positions "1" to "n".
The function checks the count. A reduced or re-based L has fewer columns than the returns data has factors, and the names of the returns data then belong to other columns.
Algorithm
The method that Julia selects is the algorithm.
namesisnothing: return the positional labels.namesis a vector: return it asStrings when it holdsnnames, and the positional labels otherwise.
Arguments
names: The names that the returns data gives the axis, ornothing.n: Length of the axis to label.
Returns
labels::Vector{String}: One label per entry of the label axis.
Related
PortfolioOptimisers.returns_asset_names — Function
returns_asset_names(rd::Nothing) -> nothing
returns_asset_names(rd::AbstractReturnsResult) -> Option{<:VecStr}Read the asset names that label the label axis of a producer's field, or nothing.
The kernel hands a producer the two values that it received, pr and rd. Only rd names the assets, so this function reads rd, and returns nothing when there is none.
Algorithm
The method that Julia selects is the algorithm.
Arguments
rd: The returns data, ornothing.
Returns
nx::Option{<:VecStr}: The asset names, ornothing.
Related
PortfolioOptimisers.regression_factor_names — Function
regression_factor_names(rr::Regression{<:Any, Nothing, <:Any, <:Any},
rd::AbstractReturnsResult) -> Option{<:VecStr}
regression_factor_names(rr::CrossSectionalFactorModel, rd) -> Option{<:VecStr}
regression_factor_names(rr, rd) -> nothingRead the factor names that label the loadings axis of a RegressionPanel, or nothing.
The function reads a name wherever one exists for the axis that pr.rr.L spans. Otherwise panel_axis_labels labels the axis by position.
- A time-series
Regressionholds no factor names, so the names are thenfof the returns data. The function reads them only when the loadings axis is the factor axis of the returns data. That is aRegressionwhoseLis unset, so that its loadings are the rawM, with one column for each factor of the returns data. A reduced or re-basedLhas an axis of its own, and no data names it. - A
CrossSectionalFactorModelnames its own factors. The prior derives the raw axis from its Exposure Estimators and stores it asnfon the block. When the block holds a family re-basis,cs_diagnostic_factor_namesmaps that list onto the reduced axis, which is the axis thatLspans. So the names come from the block, and the function does not read the returns data.
Algorithm
The method that Julia selects is the algorithm. The Nothing type parameter of L selects the raw M. The swap(L, M) rule of Regression reads the same parameter.
Arguments
rr: The regression result that holds the loadings.rd: The returns data, ornothing.
Returns
nf::Option{<:VecStr}: The factor names, ornothing.
Related
PortfolioOptimisers.expand_investable_loadings — Function
expand_investable_loadings(L::MatNum, imsk::Nothing) -> (L, nothing)
expand_investable_loadings(L::MatNum, imsk::BitVector) -> (vals, omsk)Write the loadings that a RegressionPanel read on the Investable Mask back onto the full asset universe.
A prior fitted on a point-in-time Asset Panel writes NaN into the loadings of every asset outside its Investable Mask, and a Panel Field admits no NaN. So the producer reads the loadings on the mask, and this function expands them. Each asset outside the mask gets a zero row and a false observed mask. Every uncertainty set that a caller fits on its own on such a prior follows the same rule. The producer marks the row as a placeholder too: its placeholder mask is the negation of the observed mask, because no loading exists there.
A zero row is a placeholder, not a zero feature vector. A FeatureDistance reads no placeholder: a direct call refuses such an asset by name. An optimiser hands the producer the prior reduced to the mask, so a fit meets no such row. The selector "loadings" => :observed reads the mask as a column.
Mathematical definition
\[\begin{align} \mathbf{V}_{\mathcal{M},\,\cdot} &= \mathbf{L}\,, \\ \mathbf{V}_{i,\,\cdot} &= \boldsymbol{0}\,, \quad i \notin \mathcal{M}\,, \\ O_{i,\,j} &= \mathbb{1}\left[i \in \mathcal{M}\right]\,. \end{align}\]
Where:
- $\mathbf{V}$: Loadings over every asset, of size $N \times K$.
- $\mathbf{L}$: Loadings on the Investable Mask, of size $\lvert \mathcal{M} \rvert \times K$, with rows in the order of the assets.
- $\mathcal{M}$: Assets inside the Investable Mask.
- $O_{i,\,j}$: Entry $(i, j)$ of the observed mask, of the size of $\mathbf{V}$.
- $N$: Number of assets.
- $K$: Number of columns of the loadings.
The rows of $\mathbf{V}$ on the mask are $\mathbf{L}$, so a view of the expanded field at the mask gives back the reduced loadings. An optimiser on the full universe can therefore take a panel that was built on its own.
Algorithm
The method that Julia selects is the algorithm.
imskisnothing, or every asset is investable: the loadings are those of the full universe, and the field holds no mask.- Otherwise allocate a zero frame
valsineltype(L)over every asset, writeLinto the rows of the mask, and build the observed maskomsk,trueon those rows andfalseelsewhere.
Arguments
L: The loadings on the Investable Mask,investable assets × factors.imsk: The Investable Mask of the prior over every asset, ornothing.
Returns
vals::MatNum: The loadings over every asset.omsk::Option{<:AbstractMatrix{Bool}}: The observed mask of the same shape, ornothingwhen every asset is investable.
Related
PortfolioOptimisers.assert_producer_prior — Function
assert_producer_prior(ape::AbstractAssetPanelEstimator, pr::AbstractPriorResult) -> nothing
assert_producer_prior(ape::AbstractAssetPanelEstimator, pr) -> Union{}Check that a producer that reads a prior result received one, and name the call site when it did not.
A producer runs wherever the estimator that holds it runs, and one of those sites has no prior. Preselection fits from the returns alone, before a prior exists. The shortest public call, clusterise(cle, rd), also has none, because it puts the returns data in the pr slot. This function turns both into an error that names the site, in place of a field access on nothing or a MethodError.
Algorithm
The method that Julia selects is the algorithm. A prior result returns. Anything else, nothing and the returns data alike, raises.
Arguments
ape: The producer, named in the message.pr: The prior result, or the value in the prior slot.
Validation
isa(pr, AbstractPriorResult). Raises anIsNothingError.
Returns
nothing.
Related