Asset Panel builder: private API

Types

PortfolioOptimisers.AbstractAssetPanelEstimator — Type
abstract type AbstractAssetPanelEstimator <: AbstractEstimator

Abstract supertype for every producer that builds an AssetPanel at the point of use.

A producer is configuration, not data. FeatureDistance holds one in its ape slot, a view passes it through unchanged, and a fold fits it again on the prior of the subproblem. It answers one verb, asset_panel(ape, pr, rd, X), and returns a static AssetPanel that holds one TensorPanelField. A loadings matrix and a proximity matrix are each one quantity with a labelled second axis.

The family is open. A producer that reads a source that no member of the library reads defines a member and an asset_panel method for it.

nothing in the slot is not a member. It reads the panel that the ReturnsResult already holds, which is what the same verb answers for it.

Related

source

Functions

PortfolioOptimisers.panel_build_observations — Function
panel_build_observations(inputs::AbstractVector{<:AbstractPanelFieldInput},
                         amsk::Option{<:AbstractMatrix{Bool}},
                         emsk::Option{<:AbstractMatrix{Bool}}) -> Option{Int}

Return the observation count an asset_panel build takes, or nothing when the build is static.

The build is time-varying when an input carries an observation axis, or when a universe mask is given. An AssetPanel couples the masks to the shape, because they are nothing if and only if the panel is static. So a mask given with static inputs only asks for an observation axis, and the build does not refuse it. panel_field_lift lifts a static input of a time-varying build.

Algorithm

  1. Return the length of the observation axis of the first time-varying input, as observation_axis names it, when there is one.
  2. Otherwise return the length of the first axis of amsk, then of emsk, whichever is given.
  3. Otherwise return nothing, which is the static build.

Arguments

  • inputs: The raw Panel Fields.
  • amsk: The active mask, or nothing.
  • emsk: The estimation mask, or nothing.

Returns

  • T::Option{Int}: The observation count, or nothing for a static build.

Related

source
PortfolioOptimisers.panel_fill_array — Function
panel_fill_array(vals::AbstractArray, alg::Option{<:AbstractPanelFillAlgorithm}, name::AbstractString, amsk::Nothing)
panel_fill_array(vals::AbstractMatrix, alg::Option{<:AbstractPanelFillAlgorithm}, name::AbstractString, amsk::AbstractMatrix{Bool})
panel_fill_array(vals::AbstractArray{<:Any, 3}, alg::Option{<:AbstractPanelFillAlgorithm}, name::AbstractString, amsk::AbstractMatrix{Bool})

Resolve the blanks of one raw Panel Field, and return the filled array.

The fill runs per asset, along the observation axis. A point-in-time panel has blanks along this axis only. An asset lists late or delists, so its history has a head or a tail of blanks.

A time-varying raw Panel Field resolves each series of one asset with the active mask of that asset, so a directional fill never crosses an inactive stretch. A numeric or a categorical field is observations × assets, so a series is a column. A tensor field is assets × labels × observations, so a series is the last axis at one asset and one label.

A static raw Panel Field has no observation axis. Its two admitted policies resolve each cell on its own, so the function resolves the whole array as one flat run and gives it back its shape.

Algorithm

The method that Julia selects is the algorithm.

  1. amsk is nothing, so the raw Panel Field is static: resolve vec(vals) with panel_fill, and reshape the result.
  2. A matrix: resolve each column with panel_fill and the column of amsk for its asset.
  3. An array of rank three: resolve the series of each asset and each label with panel_fill and the column of amsk for its asset.

Arguments

  • vals: The raw values, blanks included.
  • alg: The fill policy.
  • name: The Panel Field's name, displayed in the error messages.
  • amsk: The active mask (observations × assets) of a time-varying raw Panel Field, as panel_input_mask returns it, or nothing for a static one.

Returns

  • filled::AbstractArray: The same size as vals, and free of blanks.

Related

source
PortfolioOptimisers.panel_directional_fill — Function
panel_directional_fill(
    v::AbstractVector,
    val,
    lim::Union{Nothing, Integer},
    order
) -> Any

Carry the last observed value along one traversal of the observation axis.

ForwardPanelFill and BackwardPanelFill both call this function. They differ only in the order in which they walk v, so each passes its own order.

Algorithm

  1. Start with no carried value and a run length of zero.
  2. Walk order. On an observed cell, take it as the carried value and reset the run to zero.
  3. On a blank cell, raise the run by one. Write the carried value when one exists and the run is within lim, and write val otherwise.

Arguments

  • v: One asset's raw values along the observation axis, blanks included.
  • val: The value a cell becomes when nothing can be carried into it.
  • lim: Longest run of consecutive blanks a value is carried across, or nothing for no limit.
  • order: The traversal order of the observation axis.

Returns

  • filled::Vector: The same length as v, and free of blanks. Its element type is the union of the element types of v and val. panel_value_eltype narrows it by the cells that it holds, so a column that carried no blank keeps its own type, and val widens it only where the fill wrote it.

Related

source
PortfolioOptimisers.panel_directional_source — Function
panel_directional_source(
    v::AbstractVector,
    lim::Union{Nothing, Integer},
    order
) -> Any

Find, for each cell of one asset's column, the observed cell whose value a directional fill writes there.

The one walk behind panel_directional_fill and panel_directional_placeholder, so the values and the placeholders cannot disagree.

Algorithm

  1. Start with no carried cell and a run length of zero.
  2. Walk order. On an observed cell, take it as the carried cell, reset the run to zero, and record the cell itself.
  3. On a blank cell, raise the run by one. Record the carried cell when one exists and the run is within lim, and 0 otherwise.

Arguments

  • v: One asset's raw values along the observation axis, blanks included, with one-based indices.
  • lim: Longest run of consecutive blanks a value is carried across, or nothing for no limit.
  • order: The traversal order of the observation axis.

Returns

  • src::Vector{Int}: The same length as v. Entry i is the index of the observed cell that cell i takes its value from, and 0 where nothing reaches it, so the cell takes the placeholder val.

Related

source
PortfolioOptimisers.panel_directional_placeholder — Function
panel_directional_placeholder(
    v::AbstractVector,
    lim::Union{Nothing, Integer},
    order
) -> Any

Mark the cells of one asset's column that a directional fill resolves to its placeholder val.

A placeholder is a blank that no carried value reaches. It comes before the first observed cell of the walk, or further along a run of blanks than lim.

Arguments

  • v: One asset's raw values along the observation axis, blanks included.
  • lim: Longest run of consecutive blanks a value is carried across, or nothing for no limit.
  • order: The traversal order of the observation axis.

Returns

  • plc::BitVector: The same length as v, true at a placeholder.

Related

source
PortfolioOptimisers.panel_placeholder_array — Function
panel_placeholder_array(vals::AbstractArray, alg::Option{<:AbstractPanelFillAlgorithm}, amsk::Nothing) -> BitArray
panel_placeholder_array(vals::AbstractMatrix, alg::Option{<:AbstractPanelFillAlgorithm}, amsk::AbstractMatrix{Bool}) -> BitArray
panel_placeholder_array(vals::AbstractArray{<:Any, 3}, alg::Option{<:AbstractPanelFillAlgorithm}, amsk::AbstractMatrix{Bool}) -> BitArray

Mark the placeholders of one raw Panel Field, the cells that panel_fill_array resolves to a value that holds no data.

The walk is the one of panel_fill_array. A time-varying raw Panel Field marks each series of one asset with the active mask of that asset: a column of a matrix, and the last axis at one asset and one label of a tensor. A static one marks the whole array as one flat run.

Arguments

  • vals: The raw values, blanks included.
  • alg: The fill policy.
  • amsk: The active mask (observations × assets) of a time-varying raw Panel Field, as panel_input_mask returns it, or nothing for a static one.

Returns

Related

source
PortfolioOptimisers.panel_field_placeholder — Function
panel_field_placeholder(f::AbstractPanelField, pmsk::Nothing) -> AbstractPanelField
panel_field_placeholder(f::AbstractPanelField, pmsk::AbstractArray{Bool}) -> AbstractPanelField

Give a Panel Field the placeholder mask that panel_input_placeholder returns. nothing returns the Panel Field unchanged. Otherwise rebuild_struct builds the Panel Field again with the mask, through its keyword constructor, which checks the mask.

Related

source
PortfolioOptimisers.panel_field_lift — Function
panel_field_lift(f::NumericPanelField, n::Integer) -> NumericPanelField
panel_field_lift(f::CategoricalPanelField, n::Integer) -> CategoricalPanelField
panel_field_lift(f::TensorPanelField, n::Integer) -> TensorPanelField

Lift a static Panel Field onto n observations, lazily.

A static input that meets a time-varying one, or that meets the two universe masks, joins the panel at the panel's observation count. The values are wrapped in a RepeatedObservations, which stores them once. The observed mask and the placeholder mask are wrapped in the same way, so a cell that a fill policy wrote, or that holds a placeholder, keeps that state at every observation.

Algorithm

The method that Julia selects is the algorithm. Each kind rebuilds itself with its value array and its two masks wrapped in a RepeatedObservations, through panel_mask_lift.

Arguments

  • f: The static Panel Field.
  • n: Length of the observation axis to lift onto.

Returns

  • A Panel Field of the same kind, over n observations.

Related

source
PortfolioOptimisers.panel_activity_stretches — Function
panel_activity_stretches(
    act::AbstractVector{Bool}
) -> Vector{UnitRange{Int64}}

Split one asset's column of the active mask into its stretches of constant activity.

A directional fill runs within one stretch at a time, because an inactive stretch separates two listings of the asset, and a value of one listing says nothing about the other.

Algorithm

  1. Start a stretch at the first observation.
  2. Walk the observations. Close the stretch before each observation whose activity differs from the one before it, and start the next stretch there.
  3. Close the last stretch at the last observation.

Arguments

  • act: One asset's column of the active mask.

Returns

  • stretches::Vector{UnitRange{Int}}: The stretches, in order. Together they cover eachindex(act), and each one is active throughout or inactive throughout.

Related

source
PortfolioOptimisers.panel_input_mask — Function
panel_input_mask(inp::AbstractPanelFieldInput, amsk::Option{<:AbstractMatrix{Bool}}) -> Option{<:AbstractMatrix{Bool}}

Return the active mask that the fill of one raw Panel Field reads, checked against the raw values.

A static raw Panel Field has no observation axis, so its fill reads no mask. A time-varying one with no mask reads an all-true mask, which is one stretch of activity for each asset, as asset_panel takes it.

Algorithm

  1. Return nothing when the raw Panel Field is static.
  2. Return an all-true mask of the observation and asset axes of the raw values when amsk is nothing.
  3. Otherwise check the shape of amsk, and return it.

Arguments

  • inp: The raw Panel Field.
  • amsk: The active mask (observations × assets), or nothing.

Validation

  • size(amsk) equals the observation and asset axes of the raw values of a time-varying input. Raises a DimensionMismatch.

Returns

  • act::Option{<:AbstractMatrix{Bool}}: The mask that panel_fill_array reads, or nothing for a static input.

Related

source
PortfolioOptimisers.is_panel_blank — Function
is_panel_blank(x) -> Bool

Return whether one raw cell of a Panel Field is blank.

A raw Panel Field carries its blanks in the convention of its source. A tabular source writes missing, and a document with an explicit null parses to nothing. A floating-point source writes NaN. The three are the same blank here.

Algorithm

  1. Return true when the cell is missing or nothing.
  2. Return true when the cell is a Number and isnan of it.
  3. Return false otherwise.

Arguments

  • x: One raw cell.

Returns

  • blank::Bool: Whether the cell is blank.

Related

source
PortfolioOptimisers.assert_panel_fill — Function
assert_panel_fill(val::Union{Number, AbstractString}, lim::Option{<:Integer}) -> nothing

Check the terminal value and the run limit shared by the two directional fill policies.

Algorithm

  1. When val is a Number, check that it is finite.
  2. When lim is not nothing, check that it is > 0.

Arguments

  • val: The value a cell becomes when the fill has nothing to carry into it.
  • lim: Longest run of consecutive blanks the fill carries a value across, or nothing.

Validation

  • isfinite(val) when val is a Number. Raises an IsNonFiniteError.
  • lim > 0 when lim is not nothing. Raises a DomainError.

Returns

  • nothing.

Related

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

Check the name and the raw values that every AbstractPanelFieldInput has.

Algorithm

  1. Check that name is not empty.
  2. Check that vals is not empty.
  3. Check that vals has the rank s of the static shape or the rank t of the time-varying shape.

Arguments

  • name: The Panel Field's name.
  • vals: The Panel Field's raw values.
  • s: The rank of the static shape, 1 for a numeric or a categorical input and 2 for a tensor input.
  • t: The rank of the time-varying shape, s + 1.

Validation

  • !isempty(name). Raises an IsEmptyError.
  • !isempty(vals). Raises an IsEmptyError.
  • ndims(vals) == s || ndims(vals) == t. Raises a DimensionMismatch.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_panel_fill_value — Function
assert_panel_fill_value(alg::Option{<:AbstractPanelFillAlgorithm}, T::Type, name::AbstractString) -> nothing
assert_panel_fill_value(alg::Union{ConstantPanelFill, ForwardPanelFill, BackwardPanelFill}, T::Type, name::AbstractString) -> nothing

Check that the val of a fill policy has the type of the cells of its raw Panel Field.

ConstantPanelFill, ForwardPanelFill and BackwardPanelFill carry a val, and the three default it to the number 0.0. A categorical input that took this default would gain a level named "0.0", and no error would show it when its levels are derived. A numeric or a tensor input that took a string val would fail only when the fill writes the string, with a conversion error that names no Panel Field. So each input refuses a val of the wrong type when it is constructed.

Algorithm

The method that Julia selects is the algorithm.

  1. nothing, and a policy that carries no val, such as a policy of the user, pass.
  2. A policy of the library that carries a val passes when val isa T, and throws otherwise.

Arguments

  • alg: The fill policy.
  • T: The type of the cells of the raw Panel Field. It is AbstractString for a categorical input and Number for a numeric or a tensor input.
  • name: The Panel Field's name, displayed in the error message.

Validation

  • alg.val isa T, for a policy of the library that carries a val. Raises an ArgumentError.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_panel_input_fill — Function
assert_panel_input_fill(inp::AbstractPanelFieldInput) -> nothing

Check that a static raw Panel Field does not carry a directional fill policy.

ForwardPanelFill and BackwardPanelFill carry the last observed value along the observation axis, and a static Panel Field has none. A carry along the asset axis would give asset k the value of asset k - 1, which no observation supports. So this check refuses the two policies. nothing and ConstantPanelFill resolve each cell on its own, and the check admits them.

Algorithm

  1. Return when the raw Panel Field is time-varying.
  2. Throw when its fill policy is directional.

Arguments

  • inp: The raw Panel Field.

Validation

  • The fill policy of a static raw Panel Field is not directional. Raises an ArgumentError.

Returns

  • nothing.

Related

source