Asset sets matrix

PortfolioOptimisers.UniverseSets — Type
struct UniverseSets{__T_xkey, __T_uxkey, __T_tfkey, __T_utfkey, __T_cfkey, __T_ucfkey, __T_nikey, __T_dict} <: AbstractEstimator

Declares 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 in dict identifying the primary asset list. Required, and the axis a view slices.
  • uxkey: Key prefix for unique-entry asset group variants in dict.
  • tfkey: Key in dict of the time-series factor list, the columns of rd.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 in dict. The constructor checks it, and a view never recomputes it.
  • cfkey: Key in dict of 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 checks tfkey. 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 in dict. The constructor checks it, and a view never recomputes it.
  • nikey: Key in dict of 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 a UniverseSets that 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}) -> UniverseSets

Keywords correspond to the struct's fields.

Validation

  • !isempty(dict).
  • haskey(dict, xkey).
  • No one of xkey, uxkey, tfkey, utfkey, cfkey, ucfkey and nikey starts with another. The constructor makes the 42 ordered checks, and they also refuse two equal keys.
  • If a key in dict starts with the same value as xkey, length(dict[k]) == length(dict[xkey]).
  • If a key in dict starts with the same value as uxkey, there must be a corresponding key in dict where the uxkey prefix is replaced by the xkey prefix, and its length must equal length(dict[xkey]).
  • If a key in dict starts with the same value as tfkey, haskey(dict, tfkey) and length(dict[k]) == length(dict[tfkey]).
  • If a key in dict starts with the same value as utfkey, there must be a corresponding key in dict where the utfkey prefix is replaced by the tfkey prefix, and its length must equal length(dict[tfkey]).
  • If a key in dict starts with the same value as cfkey, haskey(dict, cfkey) and length(dict[k]) == length(dict[cfkey]).
  • If a key in dict starts with the same value as ucfkey, there must be a corresponding key in dict where the ucfkey prefix is replaced by the cfkey prefix, and its length must equal length(dict[cfkey]).
  • If dict carries nikey, its entries are unique, and none of them is also in dict[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 of dict to the selected assets, and rebuilds every uxkey-prefixed entry from the sliced partition that it names.
  • The view keeps the tfkey-, utfkey-, cfkey- and ucfkey-prefixed entries and every plain group unchanged. port_opt_view states why each axis is exempt.
  • The view drops the nikey entry, 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 with nikey.
  • 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

source
PortfolioOptimisers.AssetSetsMatrixEstimator — Type
struct AssetSetsMatrixEstimator{__T_val} <: AbstractConstraintEstimator

Names 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) -> AssetSetsMatrixEstimator

Keywords 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  1

Related

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

  1. Read the taxonomy column all_sets from sets.dict[smtx], through taxonomy_column.
  2. Check that all_sets has the length of the asset universe.
  3. Take unique_sets = unique(all_sets), the distinct group values in order of first appearance. Each value defines one group. The order of unique_sets is the order of the groups in the result.
  4. For each group val of unique_sets, write the indicator all_sets .== val into column i of a BitMatrix A. A is an assets × groups matrix.
  5. Return transpose(A). Its rows are the groups and its columns are the assets.

Arguments

  • smtx: The group name key to read from sets.dict.
  • sets: A UniverseSets that holds the asset universe and the groups.

Validation

  • haskey(sets.dict, smtx), through taxonomy_column.
  • length(sets.dict[smtx]) == length(sets.dict[sets.xkey]). Raises an AssertionError.

Returns

  • A: The transpose of a BitMatrix, of size (number of groups) × (number of assets), where A[i, j] == 1 if asset j is in group i. The orientation is groups × assets. The row order is unique(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  1

Related

source
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, or nothing.
  • args...: More positional arguments, which the method ignores.

Returns

  • smtx::Option{<:MatNum}: The input matrix or nothing, unchanged.

Related

source
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

Validation

Returns

  • A: The transpose of a BitMatrix, of size (number of groups) × (number of assets), as the group name key method returns it.

Related

source
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

Validation

  • The method of each entry checks that entry.

Returns

  • A: One result for each entry of smtx, in the order of smtx. Each result is what the method of its entry returns. A groups × assets transpose and an unchanged precomputed matrix can be in the same vector.

Related

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

  1. Read the values of the key from sets.dict, through taxonomy_column.
  2. Choose the input type. A Pair gives the forced type. Otherwise panel_input_kind chooses it from the values.
  3. Name the field with panel_input_name, unless name overrides it.
  4. Build the input with panel_input_build.

The vector form takes one step:

  1. Apply the scalar form to each entry.

Arguments

  • sets: The UniverseSets that holds the key.
  • key: The key, or key => InputType to force the type.
  • keys: A vector of either form. The vector form takes no name, levels or alg, 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 same asset_panel call.
  • name: The Panel Field name, or nothing to derive it from the key.
  • levels: The category levels, or nothing to 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 a KeyError.
  • Every value of the key is a string, or every value is a number, unless a Pair forces the type. Raises an ArgumentError.
  • levels is nothing when the input type is numeric. Raises an ArgumentError.
  • !isempty(keys) on the vector form. Raises an IsEmptyError.

Returns

  • The scalar form returns one AbstractPanelFieldInput. The vector form returns one input for each entry, in the order of keys.

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

source
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

  1. For a matrix, return view(smtx, :, i), the columns of the selected assets.
  2. 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: A groups × assets membership matrix, or a vector whose entries are each such a matrix or an AssetSetsMatrixEstimator.
  • 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 of smtx, in a concretely typed array.

Related

source

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