Asset Panel builder: private API
Types
PortfolioOptimisers.AbstractAssetPanelEstimator — Type
abstract type AbstractAssetPanelEstimator <: AbstractEstimatorAbstract 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
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
- Return the length of the observation axis of the first time-varying input, as
observation_axisnames it, when there is one. - Otherwise return the length of the first axis of
amsk, then ofemsk, whichever is given. - Otherwise return
nothing, which is the static build.
Arguments
inputs: The raw Panel Fields.amsk: The active mask, ornothing.emsk: The estimation mask, ornothing.
Returns
T::Option{Int}: The observation count, ornothingfor a static build.
Related
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.
amskisnothing, so the raw Panel Field is static: resolvevec(vals)withpanel_fill, and reshape the result.- A matrix: resolve each column with
panel_filland the column ofamskfor its asset. - An array of rank three: resolve the series of each asset and each label with
panel_filland the column ofamskfor 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, aspanel_input_maskreturns it, ornothingfor a static one.
Returns
filled::AbstractArray: The same size asvals, and free of blanks.
Related
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
- Start with no carried value and a run length of zero.
- Walk
order. On an observed cell, take it as the carried value and reset the run to zero. - On a blank cell, raise the run by one. Write the carried value when one exists and the run is within
lim, and writevalotherwise.
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, ornothingfor no limit.order: The traversal order of the observation axis.
Returns
filled::Vector: The same length asv, and free of blanks. Its element type is the union of the element types ofvandval.panel_value_eltypenarrows it by the cells that it holds, so a column that carried no blank keeps its own type, andvalwidens it only where the fill wrote it.
Related
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
- Start with no carried cell and a run length of zero.
- Walk
order. On an observed cell, take it as the carried cell, reset the run to zero, and record the cell itself. - On a blank cell, raise the run by one. Record the carried cell when one exists and the run is within
lim, and0otherwise.
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, ornothingfor no limit.order: The traversal order of the observation axis.
Returns
src::Vector{Int}: The same length asv. Entryiis the index of the observed cell that cellitakes its value from, and0where nothing reaches it, so the cell takes the placeholderval.
Related
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, ornothingfor no limit.order: The traversal order of the observation axis.
Returns
plc::BitVector: The same length asv,trueat a placeholder.
Related
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}) -> BitArrayMark 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, aspanel_input_maskreturns it, ornothingfor a static one.
Returns
plc::BitArray: The same size asvals,trueat a placeholder. Seepanel_placeholder.
Related
PortfolioOptimisers.panel_field_placeholder — Function
panel_field_placeholder(f::AbstractPanelField, pmsk::Nothing) -> AbstractPanelField
panel_field_placeholder(f::AbstractPanelField, pmsk::AbstractArray{Bool}) -> AbstractPanelFieldGive 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
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) -> TensorPanelFieldLift 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
nobservations.
Related
PortfolioOptimisers.panel_mask_lift — Function
panel_mask_lift(m::Nothing, n::Integer) -> nothing
panel_mask_lift(m::AbstractArray{Bool}, n::Integer) -> RepeatedObservationsLift one mask of a static Panel Field onto n observations, as panel_field_lift lifts its values. nothing stays nothing.
Related
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
- Start a stretch at the first observation.
- Walk the observations. Close the stretch before each observation whose activity differs from the one before it, and start the next stretch there.
- 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 covereachindex(act), and each one is active throughout or inactive throughout.
Related
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
- Return
nothingwhen the raw Panel Field is static. - Return an all-
truemask of the observation and asset axes of the raw values whenamskisnothing. - Otherwise check the shape of
amsk, and return it.
Arguments
inp: The raw Panel Field.amsk: The active mask (observations × assets), ornothing.
Validation
size(amsk)equals the observation and asset axes of the raw values of a time-varying input. Raises aDimensionMismatch.
Returns
act::Option{<:AbstractMatrix{Bool}}: The mask thatpanel_fill_arrayreads, ornothingfor a static input.
Related
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
- Return
truewhen the cell ismissingornothing. - Return
truewhen the cell is aNumberandisnanof it. - Return
falseotherwise.
Arguments
x: One raw cell.
Returns
blank::Bool: Whether the cell is blank.
Related
PortfolioOptimisers.assert_panel_fill — Function
assert_panel_fill(val::Union{Number, AbstractString}, lim::Option{<:Integer}) -> nothingCheck the terminal value and the run limit shared by the two directional fill policies.
Algorithm
- When
valis aNumber, check that it is finite. - When
limis notnothing, 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, ornothing.
Validation
isfinite(val)whenvalis aNumber. Raises anIsNonFiniteError.lim > 0whenlimis notnothing. Raises aDomainError.
Returns
nothing.
Related
PortfolioOptimisers.assert_panel_input — Function
assert_panel_input(name::AbstractString, vals::AbstractArray, s::Integer, t::Integer) -> nothingCheck the name and the raw values that every AbstractPanelFieldInput has.
Algorithm
- Check that
nameis not empty. - Check that
valsis not empty. - Check that
valshas the ranksof the static shape or the ranktof 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,1for a numeric or a categorical input and2for a tensor input.t: The rank of the time-varying shape,s + 1.
Validation
!isempty(name). Raises anIsEmptyError.!isempty(vals). Raises anIsEmptyError.ndims(vals) == s || ndims(vals) == t. Raises aDimensionMismatch.
Returns
nothing.
Related
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) -> nothingCheck 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.
nothing, and a policy that carries noval, such as a policy of the user, pass.- A policy of the library that carries a
valpasses whenval isa T, and throws otherwise.
Arguments
alg: The fill policy.T: The type of the cells of the raw Panel Field. It isAbstractStringfor a categorical input andNumberfor 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 aval. Raises anArgumentError.
Returns
nothing.
Related
PortfolioOptimisers.assert_panel_input_fill — Function
assert_panel_input_fill(inp::AbstractPanelFieldInput) -> nothingCheck 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
- Return when the raw Panel Field is time-varying.
- 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