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) -> NothingAssert 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
TimeDependentschedule. 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.
setsis aUniverseSets: check the asset axis,sets.dict[sets.xkey]againstax.nx, and the factor axis,sets.dict[sets.tfkey]againstax.nf. An axis is skipped whenaxholds no names for it, or whensetsdeclares no key for it. A list that is===to the names ofaxpasses with no comparison.estis an estimator or an algorithm: walk the fields ofestwithuniverse_axis_children!, against the axes ofrdfromUniverseAxes. AUniverseSetsis an estimator, and the walk checks it at its root as in step 1. AnIdSetholds each universe that the walk checked, so a universe that many estimators share is checked once.
Arguments
sets: The universe to check, against the namesax. A universe passed withrdtakes 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 atestitself, even when it is an optimisation head.rd: The returns result to use.ax: The names to check against, fromUniverseAxes. 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. ADimensionMismatchis thrown otherwise. - Each declared list equals the names of
rd, in order. AnArgumentErroris 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
PortfolioOptimisers.universe_axis_msg — Function
universe_axis_msg(sets::UniverseSets, declared, names, axis, key, sym, nf) -> StringBuild 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 ofmisaligned_axis_msg.nf: The names of the factor axis of the check, ornothing.
Returns
msg::String: The error text.
Related
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, ornothingwhen there is none.
axis:axis: The name of the axis thatnxcomes from, for the error message.
sym:sym: The name of the field of the returns data thatnxcomes from, for the error message.
Constructors
UniverseAxes(rd::ReturnsResult) -> UniverseAxesUniverseAxes(ax::UniverseAxes, ::Val{:factor}) -> UniverseAxesThe method that Julia selects is the algorithm.
rd: the asset key namesrd.nxand the factor key namesrd.nf.axandVal(: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 namesax.nf. The factor returns have no factor axis of their own, sonfisnothing.
Related
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.
- A
FactorPrioror aFactorBlackLittermanPrior: return(:pe,), its factor prior. - An
AugmentedBlackLittermanPrior: return(:f_pe,), its factor prior. - 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 ofasset_axis_fieldsleavessetsout for the same reason. - 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
PortfolioOptimisers.universe_axis_children! — Function
universe_axis_children!(seen::IdSet{UniverseSets}, x, ax::UniverseAxes) -> NothingWalk 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
xis aUniverseSetsthatseenholds: return. Any other universe: add it toseen, and check it withassert_universe_axis_order. A universe at the root of the walk and a universe in a field both reach this method, becauseuniverse_axis_visit!walks an estimator withuniverse_axis_children!, and a universe is an estimator.- Any other
x: visit the value of each field ofasset_axis_fieldsonax. - When
ax.nfholds names, visit the value of each field offactor_axis_fieldson the factor axesUniverseAxes(ax, Val(:factor)), seeUniverseAxes, with a newIdSet. 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, fromUniverseAxes.
Validation
- The rules of
assert_universe_axis_order, for each universe that the walk finds.
Returns
nothing.
Related
PortfolioOptimisers.universe_axis_visit! — Function
universe_axis_visit!(seen::IdSet{UniverseSets}, x, ax::UniverseAxes) -> NothingHandle 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.
- An
OptimisationEstimatoror aTimeDependent: return, for the reasons thatassert_universe_axis_orderstates. - An estimator, an algorithm or a covariance estimator: walk it with
universe_axis_children!. AUniverseSetsis an estimator, and that method checks it. - A vector of estimators or algorithms: visit each element.
- Any other value: return.
Arguments
seen: The universes that the walk checked.x: The value of a field.ax: The axes, fromUniverseAxes.
Validation
- The rules of
assert_universe_axis_order, for each universe that the walk finds.
Returns
nothing.
Related