Asset Panel: private API
Types
PortfolioOptimisers.AllTrueMask — Type
struct AllTrueMask <: AbstractMatrix{Bool}Reads a universe mask that is true everywhere, storing no cell.
AllTrueMask is the shape that a gapless ingestion emits for both universe masks of an AssetPanel. Every asset is listed at every observation and every return is finite, so the mask is a constant. It stores two integers, not observations × assets bits. It answers size as (n, N) and getindex as true.
It is unexported, as PortfolioOptimisers.ListingSpan is. It owns the Base methods size, getindex, IndexStyle and show, and the public bound stays AbstractMatrix{Bool}. A method specialised on it, such as PortfolioOptimisers.panel_mask_vcat, is a fast path inside the library. An extension author cannot rely on it. A view of it is an ordinary SubArray over a lazy matrix, so port_opt_view slices it correctly and allocates no cell.
Elsewhere the library writes "all of them" as nothing, for example a nothing Coverage Universe or Investable Mask. A nothing mask on an AssetPanel already means that the panel is static, so it cannot also mean "all true".
Fields
n: Number of observations.
N: Number of assets.
Constructors
AllTrueMask(n::Integer, N::Integer) -> AllTrueMaskValidation
n >= 0andN >= 0. Raises aDomainError.
Examples
julia> msk = PortfolioOptimisers.AllTrueMask(3, 2)AllTrueMask(3 × 2)julia> Matrix(msk)3×2 Matrix{Bool}: 1 1 1 1 1 1Related
PortfolioOptimisers.RepeatedObservations — Type
struct RepeatedObservations{T, N, A} <: AbstractArray{T, N}Reads a static array as though it carried an observation axis, storing it once.
RepeatedObservations is the lazy lift. A static Panel Field input joins a time-varying AssetPanel through it, and the input is not copied n times. It stores the static array as parent, and it adds the observation axis where observation_axis puts it for the rank of the lift. A lifted vector answers size as (n, length(parent)), so R[t, i] reads parent[i] for every t. A lifted matrix answers size as (size(parent)..., n), so R[i, l, t] reads parent[i, l] for every t. A view of it is an ordinary SubArray, which port_opt_view slices like any other value array.
It is unexported. It owns the Base methods size, getindex, IndexStyle and show. One library method dispatches on it: PortfolioOptimisers.panel_values_vcat keeps a concatenation of equal lifts lazy.
Fields
parent: The static array, stored once.
n: Length of the observation axis.
Constructors
RepeatedObservations(parent::AbstractVector, n::Integer) -> RepeatedObservationsRepeatedObservations(parent::AbstractMatrix, n::Integer) -> RepeatedObservationsValidation
n >= 1. Raises aDomainError.
Related
Functions
PortfolioOptimisers.panel_axes — Function
panel_axes(pf::AbstractVector{<:AbstractPanelField},
amsk::Option{<:AbstractMatrix{Bool}}) -> Tuple
panel_axes(pf::Nothing, amsk::Option{<:AbstractMatrix{Bool}}) -> Tuple
panel_axes(pnl::AssetPanel) -> TupleRead the axes one AssetPanel is stated on.
The two universe masks are the defining content of the panel, and the Panel Fields are optional payload. So the function reads the axes from the fields when the panel has any, and from the active mask when it has none. The second case is common in the ingestion layer. A caller that holds only prices has no market capitalisation and no sector, and the panel that it emits states a universe and nothing else.
A panel with neither a Panel Field nor a mask carries nothing. The function refuses it, so that no reader must test an empty tuple.
Algorithm
The method that Julia selects is the algorithm. All methods apply the same rule.
pfis a vector: returnpanel_field_axesof its first Panel Field. The constructor checks that the vector is non-empty and that every field agrees.pfisnothing: returnsize(amsk).- An
AssetPanel: apply steps 1 and 2 to its own Panel Fields and active mask. Every consumer calls this form. The constructor calls the form with two arguments, because it has no panel yet.
Arguments
pf: The Panel Fields, ornothing.amsk: The active mask, ornothing.pnl: The Asset Panel, for the last form.
Validation
amskis notnothingwhenpfisnothing. Raises anIsEmptyError.
Returns
ax::Tuple:(assets,)for a static panel, and(observations, assets)for a time-varying one.
Related
PortfolioOptimisers.features_are_assets — Function
features_are_assets(f::TensorPanelField, nx::Option{<:VecStr}) -> Bool
features_are_assets(f::AbstractPanelField, nx) -> BoolReport whether one Panel Field's label axis is the asset axis, so a view must slice both.
True when the labels of a tensor Panel Field equal the asset names. A square phylogeny or adjacency matrix on a PricesResult or a ReturnsResult gives this field, an assets × assets block whose label $k$ reads "adjacent to asset $k$". A view that cuts the assets and not that axis keeps the columns over the full universe and the rows over the subset. The distance is then wrong, and no error shows it.
The fact is derived, never recorded. The function compares the names, not the axis lengths. Two equal counts do not state that the two axes mean the same thing. The comparison stays correct under repeated views, because the view cuts both name vectors by the same indices. A numeric or a categorical Panel Field has no label axis, so it is never square.
Algorithm
The method that Julia selects is the algorithm.
- The field is not a tensor: return
false. nxisnothing: returnfalse. Input data that does not name its assets makes no claim.- Return
f.labels == nx.
Arguments
f: The Panel Field.nx: The asset names of the input data, ornothing.
Returns
Bool.
Related
PortfolioOptimisers.panel_is_static — Function
panel_is_static(pnl::AssetPanel) -> BoolReturn whether an AssetPanel is the static shape.
The Panel Fields of a static panel carry no observation axis, and its masks are nothing. The constructor makes sure that the two go together, so either one gives the answer.
Algorithm
- Return
truewhen the active mask isnothing.
Arguments
pnl: The Asset Panel.
Returns
static::Bool:truewhen the panel is static.
Related
PortfolioOptimisers.panel_value_eltype — Function
panel_value_eltype(vals::AbstractArray) -> Type
panel_value_eltype(f::NumericPanelField) -> Type
panel_value_eltype(f::CategoricalPanelField) -> Type
panel_value_eltype(f::TensorPanelField) -> Type
panel_value_eltype(fs::AbstractVector{<:AbstractPanelField}) -> TypeReturn the numeric type a Panel Field carries, or the one a Feature Matrix over several of them stacks into.
The type comes from the values, never from a written type. A raw field arrives as Union{Missing, Float64}, as Union{Nothing, Float64} or as Any. The builder fills the blanks first, and the filled array keeps that element type. No cell of it carries the type, so the function reads the cells and promotes their types. A Float32 field resolves in Float32, a Union{Missing, Float64} field with filled blanks in Float64, and an integer field stays exact. An array that still holds a missing cell gives a type that holds Missing.
A categorical Panel Field contributes nothing. The library builds an indicator and does not read it, so the indicator carries no type of its own. It takes the type of the blocks that it is stacked beside. A Feature Matrix that stacks indicators alone has nothing to derive from, and stacks in Float64.
Algorithm
The method that Julia selects is the algorithm.
AbstractArray: the element type when it is concrete. Otherwise the promotion of the types that its cells carry, which isUnion{}for an empty array.NumericPanelFieldandTensorPanelField: the type of their values.CategoricalPanelField:Union{}, which promotes away against every other type.- A vector of Panel Fields: the promotion over the fields, and
Float64when none of them contributes a type.
Arguments
vals: The values.f: The Panel Field.fs: The Panel Fields a Feature Matrix stacks.
Returns
T::Type: The numeric type.
Related
PortfolioOptimisers.panel_field_observed_labels — Function
panel_field_observed_labels(f::AbstractPanelField) -> Vector{String}
panel_field_observed_labels(f::TensorPanelField) -> Vector{String}Return the names of the observed-mask columns one Panel Field contributes to a derived Feature Matrix.
The observed mask has the shape of the values, so the mask decides the count of its columns. A numeric and a categorical Panel Field have no label axis. Their mask gives one column, "<name>::observed", also when a categorical Panel Field has many levels. A tensor Panel Field keeps a label axis in its mask. Its mask gives one column per label, "<name>=<label>::observed", also when it has one label. The table of panel_dataframe uses the same names.
The separator is "::", and the value columns use "=". So a mask column does not have the name of a level of the same Panel Field.
Algorithm
The method that Julia selects is the algorithm.
- A Panel Field with no label axis returns the single name
"<name>::observed". - A
TensorPanelFieldreads its value column names frompanel_field_labels, and appends"::observed"to each of them.
Arguments
f: The Panel Field.
Returns
labels::Vector{String}: One name per observed-mask column.
Related
PortfolioOptimisers.panel_groups_view — Function
panel_groups_view(::Nothing, j, sq::Bool) -> nothing
panel_groups_view(groups::VecStr, j, sq::Bool) -> VecStrReturn the groups of a tensor Panel Field under an asset view.
A group belongs to one label. So in the square case the asset index cuts the groups as it cuts the labels, and otherwise the function returns the groups whole.
Algorithm
The method that Julia selects is the algorithm.
groupsisnothing: returnnothing.sqistrue: returngroups[j].- Otherwise: return
groups.
Arguments
groups: The groups of the tensor Panel Field, ornothing.j: Asset index.sq: Whether the field is in the square case, fromfeatures_are_assets.
Returns
- The groups of the viewed field, or
nothing.
Related
PortfolioOptimisers.panel_array_view — Function
panel_array_view(A::Nothing, i, j) -> nothing
panel_array_view(A::AbstractVector, i, j) -> SubArray
panel_array_view(A::AbstractMatrix, i, j) -> SubArrayView one label-free Panel Field array over the observations i and the assets j.
A NumericPanelField and a CategoricalPanelField carry no label axis, so the rank alone says which axes they have: a vector is static and its one axis is the assets, and a matrix is time-varying and its axes are the observations and the assets. A tensor Panel Field is viewed by panel_tensor_view instead, because it carries a label axis, and a time-varying one holds its observations last.
Algorithm
The method that Julia selects is the algorithm.
Aisnothing: returnnothing.Ais a vector: returnview(A, j).Ais a matrix: returnview(A, i, j).
Arguments
A: The array to view, ornothing.i: Observation index.j: Asset index.
Returns
- A view of
A, ornothing.
Related
PortfolioOptimisers.panel_tensor_view — Function
panel_tensor_view(A::Nothing, i, j, k) -> nothing
panel_tensor_view(A::AbstractMatrix, i, j, k) -> SubArray
panel_tensor_view(A::AbstractArray{<:Any, 3}, i, j, k) -> SubArrayView one TensorPanelField array over the observations i, the assets j and the labels k.
A tensor Panel Field keeps its assets on its first axis and its labels on its second, in both shapes, and a time-varying one keeps its observations on its last axis. The label index is a Colon for every field but the square one, whose labels are the assets. features_are_assets states when that holds.
Algorithm
The method that Julia selects is the algorithm.
Aisnothing: returnnothing.Ais a matrix, which isassets × labels: returnview(A, j, k).Ais a 3-dimensional array, which isassets × labels × observations: returnview(A, j, k, i).
Arguments
A: The array to view, ornothing.i: Observation index.j: Asset index.k: Label index.
Returns
- A view of
A, ornothing.
Related
PortfolioOptimisers.panel_mask_view — Function
panel_mask_view(msk::Nothing, i, j) -> nothing
panel_mask_view(msk::AbstractMatrix{Bool}, i, j) -> SubArrayView one universe mask of an AssetPanel over the observations i and the assets j.
Algorithm
The method that Julia selects is the algorithm. A static panel carries no mask, so there is nothing to view.
Arguments
msk: The mask, ornothing.i: Observation index.j: Asset index.
Returns
- A view of
msk, ornothing.
Related
PortfolioOptimisers.check_asset_panel — Function
check_asset_panel(pnl::Nothing, na, nobs, na_sym) -> nothing
check_asset_panel(pnl::AssetPanel, na, nobs, na_sym) -> nothingCheck an AssetPanel against the asset and observation axes of the PricesResult or the ReturnsResult that holds it.
The panel owns its own values, so this is the only check that the input data owes it: that the universe it describes is the universe of the input data.
Algorithm
The method that Julia selects is the algorithm.
pnlisnothing: the input data has no panel, so there is nothing to check.pnlis anAssetPanel: read its shape frompanel_axes, check the asset axis againstna, and check the observation axis againstnobswhen the panel is time-varying.
Arguments
pnl: The Asset Panel, ornothing.na: Asset count of the input data.nobs: Observation count of the input data.na_sym: Symbolic name of the asset axis, displayed in the error messages.
Validation
nais notnothing. Raises anIsNothingError.- The panel's asset axis is
na. Raises aDimensionMismatch. nobsis notnothingand matches the panel's observation axis, when the panel is time-varying. Raises anIsNothingErroror aDimensionMismatch.
Returns
nothing.
Related
PortfolioOptimisers.assert_panel_labels — Function
assert_panel_labels(labels::VecStr, sym::Sym_Str) -> nothingCheck that a label vector is non-empty, holds no empty entry, and holds no repeat.
Shared by every name vector a panel carries: the levels of a CategoricalPanelField, the labels of a TensorPanelField, and the Panel Field names of an AssetPanel. Each names a column of a derived Feature Matrix, or a Panel Field a consumer looks up, so a repeat makes one name mean two things.
Algorithm
- Check that
labelsis not empty. - Check that no entry is the empty string, naming the first offending position.
- Check that no entry repeats, naming the first repeated position.
Arguments
labels: The label vector to check.sym: Symbolic name of the vector, displayed in the error messages.
Validation
!isempty(labels). Raises anIsEmptyError.- No entry is empty. Raises an
ArgumentError. allunique(labels). Raises anArgumentError.
Returns
nothing.
Related
PortfolioOptimisers.assert_panel_feature_names — Function
assert_panel_feature_names(pf::AbstractVector{<:AbstractPanelField}) -> nothingCheck that no two columns of the Feature Matrix derived from the Panel Fields share a name.
Each Panel Field checks its own levels or labels, and the AssetPanel checks the Panel Field names. A derived name joins a Panel Field name to a level, a label or "::observed", so two Panel Fields with different names can derive one name. A numeric Panel Field "beta=size" and a tensor Panel Field "beta" with the label "size" both derive "beta=size", and a consumer that finds a column by its name then reads the wrong column. The constructor runs this check, so no panel exists without a valid Feature Matrix.
Algorithm
- Walk the Panel Fields in order. Read each one's value column names from
panel_field_labels, then its observed-mask column names frompanel_field_observed_labelswhen it carries a mask. This is the column order ofpanel_feature_matrix. - Record the Panel Field that gives each name first.
- Refuse the first name that a second column gives, and name the Panel Fields that give it.
Arguments
pf: The Panel Fields.
Validation
- Every derived column name is unique. Raises an
ArgumentError.
Returns
nothing.
Related
PortfolioOptimisers.assert_panel_field_name — Function
assert_panel_field_name(name::AbstractString) -> nothingCheck that a Panel Field's name is not empty.
panel_field finds a Panel Field by its name, so it cannot find a Panel Field with an empty name.
Algorithm
- Check that
nameis not empty.
Arguments
name: The Panel Field's name.
Validation
!isempty(name). Raises anIsEmptyError.
Returns
nothing.
Related
PortfolioOptimisers.assert_panel_field_shape — Function
assert_panel_field_shape(vals::AbstractArray, name::AbstractString, s::Integer, t::Integer) -> nothingCheck that a Panel Field's values are non-empty and carry the static or the time-varying rank.
A Panel Field takes one of two ranks, and which pair of ranks it takes depends on its kind: s is the static rank and t the time-varying one. The time-varying rank is the static one with the observation axis prepended, so the two always differ by one.
Algorithm
- Check that
valsis not empty. - Check that
ndims(vals)issort.
Arguments
vals: The Panel Field's values.name: The Panel Field's name, displayed in the error messages.s: The static rank.t: The time-varying rank.
Validation
!isempty(vals). Raises anIsEmptyError.ndims(vals) in (s, t). Raises aDimensionMismatch.
Returns
nothing.
Related
PortfolioOptimisers.assert_panel_field_mask — Function
assert_panel_field_mask(vals::AbstractArray, omsk::Nothing, name::AbstractString) -> nothing
assert_panel_field_mask(vals::AbstractArray, omsk::AbstractArray{Bool}, name::AbstractString) -> nothingCheck that a Panel Field's observed mask covers its values entry for entry.
The mask says which cells the raw source observed, and which a fill policy wrote. It is therefore the same shape as the values, down to a tensor Panel Field's label axis, which keeps the per-entry resolution the raw input carried.
Algorithm
The method that Julia selects is the algorithm.
omskisnothing: the Panel Field cannot blank, so there is nothing to check.omskis an array: check that its size matches the values.
Arguments
vals: The Panel Field's values.omsk: The observed mask, ornothing.name: The Panel Field's name, displayed in the error message.
Validation
size(omsk) == size(vals). Raises aDimensionMismatch.
Returns
nothing.
Related
PortfolioOptimisers.assert_panel_field_placeholder — Function
assert_panel_field_placeholder(omsk, pmsk::Nothing, name::AbstractString) -> nothing
assert_panel_field_placeholder(omsk, pmsk::AbstractArray{Bool}, name::AbstractString) -> nothingCheck that a Panel Field's placeholder mask marks only cells that the raw source did not observe.
A placeholder is the value that the builder stores in a blank that no fill reaches. Only a blank holds one, so an observed cell is never a placeholder, and a Panel Field that cannot blank holds none.
Algorithm
The method that Julia selects is the algorithm.
pmskisnothing: no cell holds a placeholder, so there is nothing to check.pmskis an array: check that the Panel Field carries an observed mask of the same size, and that no cell istruein both masks.
Arguments
omsk: The observed mask, ornothing.pmsk: The placeholder mask, ornothing.name: The Panel Field's name, displayed in the error message.
Validation
omskis notnothing. Raises anArgumentError.size(pmsk) == size(omsk). Raises aDimensionMismatch.!any(omsk .& pmsk). Raises anArgumentError.
Returns
nothing.
Related
PortfolioOptimisers.assert_panel_masks — Function
assert_panel_masks(ax::Tuple, amsk::Nothing, emsk::Nothing) -> nothing
assert_panel_masks(ax::Tuple, amsk, emsk) -> nothingCheck an Asset Panel's two universe masks against the shape its Panel Fields agreed on.
The masks are the one thing that says whether a panel is static: they are nothing if and only if its Panel Fields carry no observation axis. That rule is what makes the static shape a type parameter rather than a runtime branch, so a mask consumer dispatches on AssetPanel{PF, Nothing, Nothing} and never tests.
Algorithm
The method that Julia selects is the algorithm.
- Both masks are
nothing: check that the Panel Fields are static, that is, thataxnames one axis. - Otherwise: check that both masks are given, that the Panel Fields are time-varying, that both masks are
ax, and thatemskis a subset ofamsk.
Arguments
ax: The observation and asset axes the Panel Fields agreed on.amsk: The active mask, ornothing.emsk: The estimation mask, ornothing.
Validation
length(ax) == 1when the masks arenothing, andlength(ax) == 2otherwise. Raises aDimensionMismatch.- The masks are both
nothingor both given. Raises aDimensionMismatch. size(amsk) == size(emsk) == ax. Raises aDimensionMismatch.emskis a subset ofamsk. Raises anArgumentError.
Returns
nothing.
Related
PortfolioOptimisers.assert_panel_finite — Function
assert_panel_finite(vals::AbstractArray{<:Real}, name::AbstractString) -> nothingCheck that a Panel Field carries no non-finite value.
Each fill policy writes a finite value. In the builder, this check finds a non-finite cell that the raw input carried and that no policy touched. A NaN is a blank, and a fill policy resolves it. An infinity is not a blank, so is_panel_blank does not mark it, and no policy writes over it. The constructors of NumericPanelField and TensorPanelField run the same check, so a Panel Field made by hand holds no NaN either.
Algorithm
- Find the first non-finite cell.
- Throw when there is one, and name the Panel Field and the cell.
Arguments
vals: The resolved values.name: The Panel Field's name, displayed in the error message.
Validation
- Every cell is finite. Raises an
IsNonFiniteError.
Returns
nothing.
Related