Universe axis order: private API

PortfolioOptimisers.assert_universe_axis_order — Function
assert_universe_axis_order(est::Union{AbstractEstimator, AbstractAlgorithm}, rd::ReturnsResult) -> Nothing
assert_universe_axis_order(sets::UniverseSets, ax::UniverseAxes) -> Nothing

Assert that every UniverseSets on the asset axis of rd names the columns of rd, name for name and in order.

A name in sets.dict[sets.xkey] resolves to its position in that list, and the position indexes a column of the returns matrix. Nothing else ties the two lists. If they differ in order, a view, a bound or a group binds the wrong asset, and the fit still runs. If sets holds a name that rd does not have, the fit runs too. This function turns that silent wrong answer into an error.

The estimator method walks the tree of est and checks each universe that it finds. The walk follows the fields that asset_axis_fields names, because a universe in such a field names the columns of rd. A prior that fits a child on the factor returns names that child in factor_axis_fields, and the walk checks the universes of the child against rd.nf. The walk stops at these values:

  • A nested optimisation head, an OptimisationEstimator. A meta-optimiser gives each inner head returns data of its own, and the head checks its tree against that data at its own entry.
  • A TimeDependent schedule. Its entries resolve at each fold, against the universe of that fold.
  • A result, or any value that is not an estimator or an algorithm. A result is data, and it holds no configuration to resolve.

Algorithm

The method that Julia selects is the algorithm.

  1. sets is a UniverseSets: check the asset axis, sets.dict[sets.xkey] against ax.nx, and the factor axis, sets.dict[sets.tfkey] against ax.nf. An axis is skipped when ax holds no names for it, or when sets declares no key for it. A list that is === to the names of ax passes with no comparison.
  2. est is an estimator or an algorithm: walk the fields of est with universe_axis_children!, against the axes of rd from UniverseAxes. A UniverseSets is an estimator, and the walk checks it at its root as in step 1. An IdSet holds each universe that the walk checked, so a universe that many estimators share is checked once.

Arguments

  • sets: The universe to check, against the names ax. A universe passed with rd takes the method of an estimator, and the walk checks it at its root.
  • est: The estimator whose tree to check, such as a prior, an optimiser or an algorithm, or a universe. The walk does not stop at est itself, even when it is an optimisation head.
  • rd: The returns result to use.
  • ax: The names to check against, from UniverseAxes. The walk passes them, so that a child on the factor axis is checked against the factor names.

Validation

  • Each declared list has the length of the names of rd. A DimensionMismatch is thrown otherwise.
  • Each declared list equals the names of rd, in order. An ArgumentError is thrown otherwise.

Both messages come from universe_axis_msg, and name the first position where the lists differ.

Returns

  • nothing.

Examples

julia> rd = ReturnsResult(; nx = ["A", "C", "B"], X = [0.1 0.2 0.3; 0.4 0.5 0.6]);julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"]));julia> PortfolioOptimisers.assert_universe_axis_order(EqualWeighted(; sets = sets), rd)ERROR: ArgumentError: the asset universe declared under key `nx` does not describe the returns data: both have 3 assets but the order differs, first at position 2: `B` vs `C`. Position is the only link between a name and a column, so this attaches constraints, bounds and groups to the wrong asset rather than failing. Set `sets.dict["nx"]` to `rd.nx`, or slice the sets to match the data.[...]

Related

source
PortfolioOptimisers.universe_axis_msg — Function
universe_axis_msg(sets::UniverseSets, declared, names, axis, key, sym, nf) -> String

Build the error text of assert_universe_axis_order.

The text is the one of misaligned_axis_msg. One more sentence follows it when the list under the asset key is the list of the factor names nf. That is the shape of a universe that names the factors under the asset key, which a consumer of the factors once read. The sentence names the factor key, where the factors go.

Arguments

  • sets: The universe that the check refused.
  • declared, names, axis, key, sym: The arguments of misaligned_axis_msg.
  • nf: The names of the factor axis of the check, or nothing.

Returns

  • msg::String: The error text.

Related

source
PortfolioOptimisers.UniverseAxes — Type
struct UniverseAxes{__T_nx, __T_nf, __T_axis, __T_sym}

The names that a UniverseSets is checked against: the asset axis, the factor axis, and the labels of the asset axis for the error message.

This type is an implementation detail and is not intended for direct use. assert_universe_axis_order reads it.

Fields

  • nx: nx: The names of the columns that the asset key of a universe names.
  • nf: nf: The names of the factor axis, or nothing when there is none.
  • axis: axis: The name of the axis that nx comes from, for the error message.
  • sym: sym: The name of the field of the returns data that nx comes from, for the error message.

Constructors

UniverseAxes(rd::ReturnsResult) -> UniverseAxesUniverseAxes(ax::UniverseAxes, ::Val{:factor}) -> UniverseAxes

The method that Julia selects is the algorithm.

  1. rd: the asset key names rd.nx and the factor key names rd.nf.
  2. ax and Val(:factor): the axes of a child that a prior fits on the factor returns. The child reads the factor returns as its asset axis, so its asset key names ax.nf. The factor returns have no factor axis of their own, so nf is nothing.

Related

source
PortfolioOptimisers.factor_axis_fields — Function
factor_axis_fields(x) -> Tuple{Vararg{Symbol}}

Return the names of the fields of x that hold a child that x fits on the factor returns, or a universe of the factors.

The child reads the columns of the factor returns, so a UniverseSets in that child must name the factors of the returns data, in order. asset_axis_fields leaves such a child out, because the child is not on the asset axis. universe_axis_children! walks these fields against the factor names instead.

Algorithm

The method that Julia selects is the algorithm.

  1. A FactorPrior or a FactorBlackLittermanPrior: return (:pe,), its factor prior.
  2. An AugmentedBlackLittermanPrior: return (:f_pe,), its factor prior.
  3. A FactorRiskContribution: return (:sets,). The head solves for the factor weights, so the asset key of its universe names the factors of the returns data. Its method of asset_axis_fields leaves sets out for the same reason.
  4. Any other value: return ().

A CrossSectionalFactorPrior fits its factor prior on the factor returns that it estimates, and the returns data holds no names for those factors. So it is not on this list.

Arguments

  • x: The estimator to read.

Returns

  • fields::Tuple{Vararg{Symbol}}: The names of the fields on the factor axis.

Related

source
PortfolioOptimisers.universe_axis_children! — Function
universe_axis_children!(seen::IdSet{UniverseSets}, x, ax::UniverseAxes) -> Nothing

Walk the fields of an estimator, and check each UniverseSets in them on the axes ax, for assert_universe_axis_order.

universe_axis_visit! handles the value of each field.

Algorithm

  1. x is a UniverseSets that seen holds: return. Any other universe: add it to seen, and check it with assert_universe_axis_order. A universe at the root of the walk and a universe in a field both reach this method, because universe_axis_visit! walks an estimator with universe_axis_children!, and a universe is an estimator.
  2. Any other x: visit the value of each field of asset_axis_fields on ax.
  3. When ax.nf holds names, visit the value of each field of factor_axis_fields on the factor axes UniverseAxes(ax, Val(:factor)), see UniverseAxes, with a new IdSet. A universe on the factor axis names other columns than a universe on the asset axis, so the two do not share a set.

Arguments

  • seen: The universes that the walk checked.
  • x: The estimator whose fields to walk, or a universe to check.
  • ax: The axes, from UniverseAxes.

Validation

Returns

  • nothing.

Related

source
PortfolioOptimisers.universe_axis_visit! — Function
universe_axis_visit!(seen::IdSet{UniverseSets}, x, ax::UniverseAxes) -> Nothing

Handle one value of a field in the walk of universe_axis_children!.

Algorithm

The method that Julia selects on the type of x is the algorithm.

  1. An OptimisationEstimator or a TimeDependent: return, for the reasons that assert_universe_axis_order states.
  2. An estimator, an algorithm or a covariance estimator: walk it with universe_axis_children!. A UniverseSets is an estimator, and that method checks it.
  3. A vector of estimators or algorithms: visit each element.
  4. Any other value: return.

Arguments

  • seen: The universes that the walk checked.
  • x: The value of a field.
  • ax: The axes, from UniverseAxes.

Validation

Returns

  • nothing.

Related

source