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

Validation

  • n >= 0 and N >= 0. Raises a DomainError.

Examples

julia> msk = PortfolioOptimisers.AllTrueMask(3, 2)AllTrueMask(3 × 2)julia> Matrix(msk)3×2 Matrix{Bool}: 1  1 1  1 1  1

Related

source
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) -> RepeatedObservations

Validation

  • n >= 1. Raises a DomainError.

Related

source

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

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

  1. pf is a vector: return panel_field_axes of its first Panel Field. The constructor checks that the vector is non-empty and that every field agrees.
  2. pf is nothing: return size(amsk).
  3. 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, or nothing.
  • amsk: The active mask, or nothing.
  • pnl: The Asset Panel, for the last form.

Validation

  • amsk is not nothing when pf is nothing. Raises an IsEmptyError.

Returns

  • ax::Tuple: (assets,) for a static panel, and (observations, assets) for a time-varying one.

Related

source
PortfolioOptimisers.features_are_assets — Function
features_are_assets(f::TensorPanelField, nx::Option{<:VecStr}) -> Bool
features_are_assets(f::AbstractPanelField, nx) -> Bool

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

  1. The field is not a tensor: return false.
  2. nx is nothing: return false. Input data that does not name its assets makes no claim.
  3. Return f.labels == nx.

Arguments

  • f: The Panel Field.
  • nx: The asset names of the input data, or nothing.

Returns

  • Bool.

Related

source
PortfolioOptimisers.panel_is_static — Function
panel_is_static(pnl::AssetPanel) -> Bool

Return 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

  1. Return true when the active mask is nothing.

Arguments

  • pnl: The Asset Panel.

Returns

  • static::Bool: true when the panel is static.

Related

source
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}) -> Type

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

  1. AbstractArray: the element type when it is concrete. Otherwise the promotion of the types that its cells carry, which is Union{} for an empty array.
  2. NumericPanelField and TensorPanelField: the type of their values.
  3. CategoricalPanelField: Union{}, which promotes away against every other type.
  4. A vector of Panel Fields: the promotion over the fields, and Float64 when 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

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

  1. A Panel Field with no label axis returns the single name "<name>::observed".
  2. A TensorPanelField reads its value column names from panel_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

source
PortfolioOptimisers.panel_groups_view — Function
panel_groups_view(::Nothing, j, sq::Bool) -> nothing
panel_groups_view(groups::VecStr, j, sq::Bool) -> VecStr

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

  1. groups is nothing: return nothing.
  2. sq is true: return groups[j].
  3. Otherwise: return groups.

Arguments

  • groups: The groups of the tensor Panel Field, or nothing.
  • j: Asset index.
  • sq: Whether the field is in the square case, from features_are_assets.

Returns

  • The groups of the viewed field, or nothing.

Related

source
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) -> SubArray

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

  1. A is nothing: return nothing.
  2. A is a vector: return view(A, j).
  3. A is a matrix: return view(A, i, j).

Arguments

  • A: The array to view, or nothing.
  • i: Observation index.
  • j: Asset index.

Returns

  • A view of A, or nothing.

Related

source
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) -> SubArray

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

  1. A is nothing: return nothing.
  2. A is a matrix, which is assets × labels: return view(A, j, k).
  3. A is a 3-dimensional array, which is assets × labels × observations: return view(A, j, k, i).

Arguments

  • A: The array to view, or nothing.
  • i: Observation index.
  • j: Asset index.
  • k: Label index.

Returns

  • A view of A, or nothing.

Related

source
PortfolioOptimisers.panel_mask_view — Function
panel_mask_view(msk::Nothing, i, j) -> nothing
panel_mask_view(msk::AbstractMatrix{Bool}, i, j) -> SubArray

View 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, or nothing.
  • i: Observation index.
  • j: Asset index.

Returns

  • A view of msk, or nothing.

Related

source
PortfolioOptimisers.check_asset_panel — Function
check_asset_panel(pnl::Nothing, na, nobs, na_sym) -> nothing
check_asset_panel(pnl::AssetPanel, na, nobs, na_sym) -> nothing

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

  1. pnl is nothing: the input data has no panel, so there is nothing to check.
  2. pnl is an AssetPanel: read its shape from panel_axes, check the asset axis against na, and check the observation axis against nobs when the panel is time-varying.

Arguments

  • pnl: The Asset Panel, or nothing.
  • 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

  • na is not nothing. Raises an IsNothingError.
  • The panel's asset axis is na. Raises a DimensionMismatch.
  • nobs is not nothing and matches the panel's observation axis, when the panel is time-varying. Raises an IsNothingError or a DimensionMismatch.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_panel_labels — Function
assert_panel_labels(labels::VecStr, sym::Sym_Str) -> nothing

Check 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

  1. Check that labels is not empty.
  2. Check that no entry is the empty string, naming the first offending position.
  3. 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 an IsEmptyError.
  • No entry is empty. Raises an ArgumentError.
  • allunique(labels). Raises an ArgumentError.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_panel_feature_names — Function
assert_panel_feature_names(pf::AbstractVector{<:AbstractPanelField}) -> nothing

Check 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

  1. Walk the Panel Fields in order. Read each one's value column names from panel_field_labels, then its observed-mask column names from panel_field_observed_labels when it carries a mask. This is the column order of panel_feature_matrix.
  2. Record the Panel Field that gives each name first.
  3. 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

source
PortfolioOptimisers.assert_panel_field_shape — Function
assert_panel_field_shape(vals::AbstractArray, name::AbstractString, s::Integer, t::Integer) -> nothing

Check 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

  1. Check that vals is not empty.
  2. Check that ndims(vals) is s or t.

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 an IsEmptyError.
  • ndims(vals) in (s, t). Raises a DimensionMismatch.

Returns

  • nothing.

Related

source
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) -> nothing

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

  1. omsk is nothing: the Panel Field cannot blank, so there is nothing to check.
  2. omsk is an array: check that its size matches the values.

Arguments

  • vals: The Panel Field's values.
  • omsk: The observed mask, or nothing.
  • name: The Panel Field's name, displayed in the error message.

Validation

  • size(omsk) == size(vals). Raises a DimensionMismatch.

Returns

  • nothing.

Related

source
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) -> nothing

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

  1. pmsk is nothing: no cell holds a placeholder, so there is nothing to check.
  2. pmsk is an array: check that the Panel Field carries an observed mask of the same size, and that no cell is true in both masks.

Arguments

  • omsk: The observed mask, or nothing.
  • pmsk: The placeholder mask, or nothing.
  • name: The Panel Field's name, displayed in the error message.

Validation

  • omsk is not nothing. Raises an ArgumentError.
  • size(pmsk) == size(omsk). Raises a DimensionMismatch.
  • !any(omsk .& pmsk). Raises an ArgumentError.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_panel_masks — Function
assert_panel_masks(ax::Tuple, amsk::Nothing, emsk::Nothing) -> nothing
assert_panel_masks(ax::Tuple, amsk, emsk) -> nothing

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

  1. Both masks are nothing: check that the Panel Fields are static, that is, that ax names one axis.
  2. Otherwise: check that both masks are given, that the Panel Fields are time-varying, that both masks are ax, and that emsk is a subset of amsk.

Arguments

  • ax: The observation and asset axes the Panel Fields agreed on.
  • amsk: The active mask, or nothing.
  • emsk: The estimation mask, or nothing.

Validation

  • length(ax) == 1 when the masks are nothing, and length(ax) == 2 otherwise. Raises a DimensionMismatch.
  • The masks are both nothing or both given. Raises a DimensionMismatch.
  • size(amsk) == size(emsk) == ax. Raises a DimensionMismatch.
  • emsk is a subset of amsk. Raises an ArgumentError.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_panel_finite — Function
assert_panel_finite(vals::AbstractArray{<:Real}, name::AbstractString) -> nothing

Check 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

  1. Find the first non-finite cell.
  2. 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

Returns

  • nothing.

Related

source