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

  1. Probe the decay over 0:dmax through assert_separation_decay, before the pair loop.
  2. Allocate Z, of the element type et and the size of d, filled with zeros.
  3. For each pair, read its separation duv, and ask is_related whether it is inside the budget, giving rel. This test also rejects the sentinel of an unreachable pair, so it guards the next step.
  4. Where rel holds, write separation_decay(dk, duv, dmax) into Z[u, v], which is the form that Proximity states. Where it does not hold, keep the zero of step 2.

Arguments

Returns

  • Z::Matrix: Square assets × assets feature matrix.

Related

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

  1. names is nothing: return the positional labels.
  2. names is a vector: return it as Strings when it holds n names, and the positional labels otherwise.

Arguments

  • names: The names that the returns data gives the axis, or nothing.
  • n: Length of the axis to label.

Returns

  • labels::Vector{String}: One label per entry of the label axis.

Related

source
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, or nothing.

Returns

  • nx::Option{<:VecStr}: The asset names, or nothing.

Related

source
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) -> nothing

Read 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 Regression holds no factor names, so the names are the nf of the returns data. The function reads them only when the loadings axis is the factor axis of the returns data. That is a Regression whose L is unset, so that its loadings are the raw M, with one column for each factor of the returns data. A reduced or re-based L has an axis of its own, and no data names it.
  • A CrossSectionalFactorModel names its own factors. The prior derives the raw axis from its Exposure Estimators and stores it as nf on the block. When the block holds a family re-basis, cs_diagnostic_factor_names maps that list onto the reduced axis, which is the axis that L spans. 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, or nothing.

Returns

  • nf::Option{<:VecStr}: The factor names, or nothing.

Related

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

  1. imsk is nothing, or every asset is investable: the loadings are those of the full universe, and the field holds no mask.
  2. Otherwise allocate a zero frame vals in eltype(L) over every asset, write L into the rows of the mask, and build the observed mask omsk, true on those rows and false elsewhere.

Arguments

  • L: The loadings on the Investable Mask, investable assets × factors.
  • imsk: The Investable Mask of the prior over every asset, or nothing.

Returns

  • vals::MatNum: The loadings over every asset.
  • omsk::Option{<:AbstractMatrix{Bool}}: The observed mask of the same shape, or nothing when every asset is investable.

Related

source
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

Returns

  • nothing.

Related

source