Asset sets matrix
PortfolioOptimisers.UniverseSets — Type
struct UniverseSets{__T_xkey, __T_uxkey, __T_tfkey, __T_utfkey, __T_cfkey, __T_ucfkey, __T_nikey, __T_dict} <: AbstractEstimatorDeclares the universes a portfolio problem is written against, and any groupings or partitions of them.
Constraint generation and the estimator routines read it to expand group references, to map a group name to its member list, and to validate membership.
It declares every axis that it carries. xkey and uxkey are for assets, tfkey and utfkey for time-series factors, cfkey and ucfkey for cross-sectional factors, and nikey for the Non-Investable Axis. The asset axis is the primary axis. The constructor requires haskey(dict, xkey), and a view slices this axis. The factor axes are optional, because a problem with no factor model has no factor names. A consumer that needs a factor axis and does not find it throws when it reads the axis, not at construction.
The two factor families name different things, so there are two factor axes. A time-series regression fits one loading vector per asset over the observations, so its factors are the columns of rd.F, and a caller copies rd.nf into the dict under tfkey. A cross-sectional regression fits one loading vector per observation across the assets, so its factors are the exposures of the fit, and they exist only inside the fitted block. One axis for both gives one key two different lists on one problem. A consumer never chooses between the axes by hand. factor_axis_key reads the key from the loadings result that the consumer holds.
A key of dict that starts with xkey is a partition of the asset universe, so its group must have the length of dict[xkey]. asset_sets_matrix with NestedClustered reads such partitions.
A key that starts with uxkey is a unique-entry group. Its xkey-prefixed partition must exist in dict and have the length of the asset universe, and that partition maps each asset to one entry of the unique-entry group. Constraint generation can then write constraints over the unique entries, also inside a NestedClustered optimisation.
The tfkey and utfkey prefixes mean the same on the time-series factor axis, and cfkey and ucfkey mean the same on the cross-sectional axis. On the asset axis the prefixes let a view slice the partitions. An asset index never slices a factor axis, so on a factor axis the prefixes give only the length checks at construction. The constructor checks the two factor axes alike and never checks one against the other, so a problem can declare one, both or neither.
A taxonomy reaches the Asset Panel through panel_input, which reads one xkey-prefixed key as one Panel Field. The panel names its own columns, so no key declares a feature axis.
nikey declares the Non-Investable Axis, the names that the Investable Mask left out. A forced liquidation is priced on this axis. It differs from the other six keys in three ways.
- The entry of a fit writes it after it reduces an optimiser to the Investable Mask, and it overwrites a value that the caller wrote. Outside a fit, a value that the caller writes is the way to resolve a liquidation rate.
- Every view drops it. A sets that carries it was reduced by one entry of a fit for one problem, so a cluster of a nested optimisation cannot inherit the departures of its parent and charge them again.
- It has no prefixed partition and no unique-entry group, because its entries are unique by construction and a plain group already reaches it.
A key that matches none of the seven prefixes is a plain group. It expands by name on any axis, so a factor group and a group on the Non-Investable Axis need no code of their own.
Fields
xkey: Key indictidentifying the primary asset list. Required, and the axis a view slices.
uxkey: Key prefix for unique-entry asset group variants indict.
tfkey: Key indictof the time-series factor list, the columns ofrd.F, against which a time-series regression fits one loading vector per asset. Optional. A consumer that needs it and does not find it throws when it reads the axis.
utfkey: Key prefix for unique-entry time-series factor group variants indict. The constructor checks it, and a view never recomputes it.
cfkey: Key indictof the cross-sectional factor list, the exposures against which a cross-sectional regression fits one loading vector per observation. Optional, and the constructor checks it as it checkstfkey. It never checks the two axes against each other, so a problem can declare one, both or neither.
ucfkey: Key prefix for unique-entry cross-sectional factor group variants indict. The constructor checks it, and a view never recomputes it.
nikey: Key indictof the Non-Investable Axis, the names that the Investable Mask left out. Optional. The entry of a fit writes it, and a view drops it, so aUniverseSetsthat carries one was reduced by one entry of a fit for one problem. It names assets and has no prefixed partition, because its entries are unique by construction and a plain group already reaches it.
dict: Dictionary mapping group identifiers to member labels.
Constructors
UniverseSets(; xkey::AbstractString = "nx", uxkey::AbstractString = "ux", tfkey::AbstractString = "nf", utfkey::AbstractString = "uf", cfkey::AbstractString = "ncf", ucfkey::AbstractString = "ucf", nikey::AbstractString = "ni", dict::AbstractDict{<:AbstractString, <:Any}) -> UniverseSetsKeywords correspond to the struct's fields.
Validation
!isempty(dict).haskey(dict, xkey).- No one of
xkey,uxkey,tfkey,utfkey,cfkey,ucfkeyandnikeystarts with another. The constructor makes the 42 ordered checks, and they also refuse two equal keys. - If a key in
dictstarts with the same value asxkey,length(dict[k]) == length(dict[xkey]). - If a key in
dictstarts with the same value asuxkey, there must be a corresponding key indictwhere theuxkeyprefix is replaced by thexkeyprefix, and its length must equallength(dict[xkey]). - If a key in
dictstarts with the same value astfkey,haskey(dict, tfkey)andlength(dict[k]) == length(dict[tfkey]). - If a key in
dictstarts with the same value asutfkey, there must be a corresponding key indictwhere theutfkeyprefix is replaced by thetfkeyprefix, and its length must equallength(dict[tfkey]). - If a key in
dictstarts with the same value ascfkey,haskey(dict, cfkey)andlength(dict[k]) == length(dict[cfkey]). - If a key in
dictstarts with the same value asucfkey, there must be a corresponding key indictwhere theucfkeyprefix is replaced by thecfkeyprefix, and its length must equallength(dict[cfkey]). - If
dictcarriesnikey, its entries are unique, and none of them is also indict[xkey]. An asset is investable or it is not, and a name on both axes is priced twice, once as a holding and once as a forced exit.
View parameters
UniverseSets defines its own port_opt_view method rather than deriving one from field tags.
- The method reads the asset index alone. It ignores every further positional argument, because it slices no axis but the asset axis.
- The view slices every
xkey-prefixed entry ofdictto the selected assets, and rebuilds everyuxkey-prefixed entry from the sliced partition that it names. - The view keeps the
tfkey-,utfkey-,cfkey- anducfkey-prefixed entries and every plain group unchanged.port_opt_viewstates why each axis is exempt. - The view drops the
nikeyentry, because only the entry of a fit writes one. It matches the key exactly and not by prefix, so it keeps a plain group whose name starts withnikey. - The view keeps the seven key prefixes, so the viewed value declares the same axes as the original.
Examples
julia> UniverseSets(; xkey = "nx", dict = Dict("nx" => ["A", "B", "C"], "group1" => ["A", "B"]))UniverseSets xkey ┼ String: "nx" uxkey ┼ String: "ux" tfkey ┼ String: "nf" utfkey ┼ String: "uf" cfkey ┼ String: "ncf" ucfkey ┼ String: "ucf" nikey ┼ String: "ni" dict ┴ Dict{String, Vector{String}}: Dict("group1" => ["A", "B"], "nx" => ["A", "B", "C"])Related
PortfolioOptimisers.AssetSetsMatrixEstimator — Type
struct AssetSetsMatrixEstimator{__T_val} <: AbstractConstraintEstimatorNames the Universe Sets key whose groups become the rows of a binary asset-group membership matrix.
asset_sets_matrix reads the key from a UniverseSets. It returns one row for each distinct group value and one column for each asset. A row is the indicator of one group, and a sub-group constraint sums over the assets that the row marks.
Fields
val: Group name key for asset set membership matrix extraction.
Constructors
AssetSetsMatrixEstimator(; val::AbstractString) -> AssetSetsMatrixEstimatorKeywords correspond to the struct's fields.
Validation
!isempty(val).
Examples
julia> sets = UniverseSets(; xkey = "nx", dict = Dict("nx" => ["A", "B", "C"], "nx_sector" => ["Tech", "Tech", "Finance"]));julia> est = AssetSetsMatrixEstimator(; val = "nx_sector")AssetSetsMatrixEstimator val ┴ String: "nx_sector"julia> asset_sets_matrix(est, sets)2×3 transpose(::BitMatrix) with eltype Bool: 1 1 0 0 0 1Related
References
- [150] T.-J. Chang, N. Meade, J. E. Beasley and Y. M. Sharaiha. Heuristics for cardinality constrained portfolio optimisation. Computers & Operations Research 27, 1271–1302 (2000). Section 2.6, Equation 15.
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 9.1, Equations 9.2 to 9.4. It adds the row of indicator coefficients and the equality over a group.
PortfolioOptimisers.asset_sets_matrix — Function
asset_sets_matrix(
smtx::AbstractString,
sets::UniverseSets
) -> LinearAlgebra.Transpose{Bool, BitMatrix}
Build a binary asset-group membership matrix from a Universe Sets key.
The key smtx names a column of sets.dict that holds one group value for each asset. The matrix has one row for each distinct group value and one column for each asset of the universe. The entry [i, j] is one when asset j is in group i.
Algorithm
- Read the taxonomy column
all_setsfromsets.dict[smtx], throughtaxonomy_column. - Check that
all_setshas the length of the asset universe. - Take
unique_sets = unique(all_sets), the distinct group values in order of first appearance. Each value defines one group. The order ofunique_setsis the order of the groups in the result. - For each group
valofunique_sets, write the indicatorall_sets .== valinto columniof aBitMatrixA.Ais anassets × groupsmatrix. - Return
transpose(A). Its rows are the groups and its columns are the assets.
Arguments
smtx: The group name key to read fromsets.dict.sets: AUniverseSetsthat holds the asset universe and the groups.
Validation
haskey(sets.dict, smtx), throughtaxonomy_column.length(sets.dict[smtx]) == length(sets.dict[sets.xkey]). Raises anAssertionError.
Returns
A: Thetransposeof aBitMatrix, of size (number of groups) × (number of assets), whereA[i, j] == 1if assetjis in groupi. The orientation isgroups × assets. The row order isunique(sets.dict[smtx]), the distinct group values in order of first appearance.
Examples
julia> sets = UniverseSets(; xkey = "nx", dict = Dict("nx" => ["A", "B", "C"], "nx_sector" => ["Tech", "Tech", "Finance"]));julia> asset_sets_matrix("nx_sector", sets)2×3 transpose(::BitMatrix) with eltype Bool: 1 1 0 0 0 1Related
asset_sets_matrix(smtx::Option{<:MatNum}, args...)Return a precomputed membership matrix, or nothing, unchanged.
A caller can give the membership matrix itself in place of an AssetSetsMatrixEstimator. With this method, one call to asset_sets_matrix takes an estimator, a matrix, or nothing when no matrix is set.
Arguments
smtx: A precomputed membership matrix, ornothing.args...: More positional arguments, which the method ignores.
Returns
smtx::Option{<:MatNum}: The input matrix ornothing, unchanged.
Related
asset_sets_matrix(smtx::AssetSetsMatrixEstimator, sets::UniverseSets)Build the membership matrix from the group name key that smtx holds. The method calls:
asset_sets_matrix(smtx.val, sets)Arguments
smtx: AnAssetSetsMatrixEstimatorthat holds the group name key to read.sets: AUniverseSetsthat holds the asset universe and the groups.
Validation
- The group name key method of
asset_sets_matrixcheckssmtx.val.
Returns
A: Thetransposeof aBitMatrix, of size (number of groups) × (number of assets), as the group name key method returns it.
Related
asset_sets_matrix(smtx::VecMatNum_ASetMatE,
sets::UniverseSets)Apply asset_sets_matrix to each entry of the vector.
Each entry dispatches to its own method, so one vector can hold estimators and precomputed matrices together.
Arguments
smtx: A vector whose entries are each anAssetSetsMatrixEstimatoror a precomputed numeric matrix.sets: AUniverseSetsthat holds the asset universe and the groups.
Validation
- The method of each entry checks that entry.
Returns
A: One result for each entry ofsmtx, in the order ofsmtx. Each result is what the method of its entry returns. Agroups × assetstranspose and an unchanged precomputed matrix can be in the same vector.
Related
PortfolioOptimisers.panel_input — Function
panel_input(sets::UniverseSets, key::AbstractString; name = nothing, levels = nothing,
alg = nothing)
panel_input(sets::UniverseSets, key::Pair; name = nothing, levels = nothing,
alg = nothing)
panel_input(sets::UniverseSets, keys::AbstractVector)Convert a UniverseSets key into the raw Panel Field input that asset_panel reads.
A key is one vector over the asset axis, which is the static raw form of one Panel Field. A Universe Sets key enters an Asset Panel through this function. The values of the key select the input type. A key of strings becomes a CategoricalPanelInput, and a key of numbers becomes a NumericPanelInput. The function refuses a key that mixes the two, because it cannot know which reading the caller wants.
An entry key => InputType forces the input type, in the scalar form and in the vector form. For example, "nx_rating" => CategoricalPanelInput reads a numeric rating as a label, not as a number. No keyword sets the type, and the pair is the only way to force it.
panel_input_name names the field. A nested taxonomy has many keys, so it gives many fields. The vector form applies the same rule to each key.
The result is static, because a taxonomy has no observation axis. When asset_panel receives it with a time-varying input, it lifts the taxonomy to the observation axis as a field that is constant in time. One panel can thus hold a taxonomy and a table of fundamentals.
Algorithm
The scalar form takes four steps:
- Read the values of the key from
sets.dict, throughtaxonomy_column. - Choose the input type. A
Pairgives the forced type. Otherwisepanel_input_kindchooses it from the values. - Name the field with
panel_input_name, unlessnameoverrides it. - Build the input with
panel_input_build.
The vector form takes one step:
- Apply the scalar form to each entry.
Arguments
sets: TheUniverseSetsthat holds the key.key: The key, orkey => InputTypeto force the type.keys: A vector of either form. The vector form takes noname,levelsoralg, because each of them describes one field. Give a key that needs one of them to the scalar form, and pass both results to the sameasset_panelcall.name: The Panel Field name, ornothingto derive it from the key.levels: The category levels, ornothingto let the builder sort them. Only the categorical form takes levels.alg: The fill policy for the raw values.
Validation
haskey(sets.dict, key). Raises aKeyError.- Every value of the key is a string, or every value is a number, unless a
Pairforces the type. Raises anArgumentError. levelsisnothingwhen the input type is numeric. Raises anArgumentError.!isempty(keys)on the vector form. Raises anIsEmptyError.
Returns
- The scalar form returns one
AbstractPanelFieldInput. The vector form returns one input for each entry, in the order ofkeys.
Examples
julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"], "nx_sector" => ["Fin", "Tech", "Fin"]));julia> inp = panel_input(sets, "nx_sector");julia> inp.name"sector"julia> pnl = asset_panel([inp]);julia> panel_feature_matrix(pnl)[1]2-element Vector{String}: "sector=Fin" "sector=Tech"Related
PortfolioOptimisers.port_opt_view — Method
port_opt_view(smtx::MatNum, i, args...; kwargs...)
port_opt_view(smtx::VecMatNum_ASetMatE, i, args...; kwargs...)
port_opt_view(smtx::AbstractVector{<:AssetSetsMatrixEstimator}, i, args...; kwargs...)Take an asset view of an asset-group membership matrix, or of a vector of matrices and estimators.
The matrix method slices columns. It expects the groups × assets matrix that asset_sets_matrix returns, whose columns are the assets. An estimator holds a key and no data, and asset_sets_matrix reads the key after the view. The view of an estimator entry is thus the entry, unchanged.
Algorithm
- For a matrix, return
view(smtx, :, i), the columns of the selected assets. - For a vector, take the view of each entry through the method of that entry. Then narrow the element type with
concrete_typed_array_if_abstract.
Arguments
smtx: Agroups × assetsmembership matrix, or a vector whose entries are each such a matrix or anAssetSetsMatrixEstimator.i: The asset index or range to slice.args...: More positional arguments, which the method ignores.kwargs...: More keyword arguments, which the method ignores.
Returns
- For a matrix, a column view of size
groups × length(i). For a vector, one result per entry, in the order ofsmtx, in a concretely typed array.
Related
References
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
- [150]
- T.-J. Chang, N. Meade, J. E. Beasley and Y. M. Sharaiha. Heuristics for Cardinality Constrained Portfolio Optimisation. Computers & Operations Research 27, 1271–1302 (2000).