Asset Panel builder

Types

PortfolioOptimisers.AbstractPanelFieldInput — Type
abstract type AbstractPanelFieldInput <: AbstractEstimator

Supertype of the raw, blank-carrying forms one Panel Field enters asset_panel in.

All concrete types holding one Panel Field's raw values, its metadata and its fill policy should subtype AbstractPanelFieldInput.

An input is not a PricesResult or a ReturnsResult, and it never becomes one. It holds the blanks, and asset_panel resolves them when it builds the Panel Field. No later step reads an unresolved panel. So the input is a plain argument of the builder, and not a preprocessing estimator. An estimator fitted inside a fold would need a PricesResult or a ReturnsResult that holds the unfilled panel, and the rule that every Panel Field is finite gives it none.

Interfaces

In order to implement a new concrete type that works seamlessly with the library, subtype AbstractPanelFieldInput and implement the following methods:

panel_input_is_static

  • panel_input_is_static(inp::AbstractPanelFieldInput) -> Bool: Whether the raw values carry no observation axis.

Arguments

  • inp: The concrete subtype instance.

Returns

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

panel_resolve

  • panel_resolve(inp::AbstractPanelFieldInput, amsk::Option{<:AbstractMatrix{Bool}} = nothing) -> Tuple: The Panel Field's values with every blank resolved, and the boolean array recording which cells were observed.

Arguments

  • inp: The concrete subtype instance.
  • amsk: The active mask (observations × assets), or nothing. An input type that reads no mask ignores it. An input type that reads it passes each asset's column to panel_fill.

Returns

  • vals::AbstractArray: The resolved values, in the raw input's own shape.
  • obs::AbstractArray{Bool}: Whether each raw cell was observed, the same shape as vals.

panel_input_field

  • panel_input_field(inp::AbstractPanelFieldInput, vals::AbstractArray, obs::BitArray) -> AbstractPanelField: Build the Panel Field from the resolved values, with obs as its observed mask unless the fill policy is nothing, which admits no blank and so records no mask.

Arguments

  • inp: The concrete subtype instance.
  • vals: The resolved values, as panel_resolve returned them.
  • obs: The observed cells, as panel_resolve returned them.

Returns

  • f::AbstractPanelField: The Panel Field.

panel_input_placeholder (optional)

  • panel_input_placeholder(inp::AbstractPanelFieldInput, amsk::Option{<:AbstractMatrix{Bool}}) -> Option{AbstractArray{Bool}}: The placeholder mask of the Panel Field, true at a cell whose resolved value holds no data, or nothing.

Arguments

  • inp: The concrete subtype instance.
  • amsk: The active mask (observations × assets), or nothing.

Returns

  • pmsk::Option{AbstractArray{Bool}}: The placeholder mask, the same size as the resolved values, or nothing.

The fallback returns nothing, so every value that the input's fill writes is data. asset_panel gives the mask to the Panel Field with panel_field_placeholder.

Related

source
PortfolioOptimisers.AbstractPanelFillAlgorithm — Type
abstract type AbstractPanelFillAlgorithm <: AbstractAlgorithm

Supertype of the policies that resolve a blank cell of a raw Panel Field.

All concrete types stating what a Panel Field's blank cell becomes should subtype AbstractPanelFillAlgorithm.

A blank never reaches a PricesResult or a ReturnsResult. asset_panel resolves every one of them, so every Panel Field comes out finite. nothing in the place of a policy is the default. It fills no cell, so a blank cell throws an error that names the Panel Field. Use it for a Panel Field that has no blank by construction. The policy gives the resolved value. The observed mask of the Panel Field records which cells the policy resolved. A value that the policy writes is data, and every reader reads it. The one exception is a placeholder, a value that the policy writes only because it has nothing to carry into the cell. The placeholder mask of the Panel Field marks it, and no reader reads it.

Interfaces

In order to implement a new concrete type that works seamlessly with the library, subtype AbstractPanelFillAlgorithm and implement the following methods:

panel_fill

  • panel_fill(alg::AbstractPanelFillAlgorithm, v::AbstractVector, act::Option{<:AbstractVector{Bool}}, name::AbstractString) -> Vector: One asset's column of one raw Panel Field, along the observation axis, with every blank resolved.

Arguments

  • alg: The concrete subtype instance.
  • v: One asset's raw values along the observation axis, blanks included.
  • act: The asset's column of the active mask, or nothing for a static Panel Field. A policy that reads no mask ignores it.
  • name: The Panel Field's name, displayed in an error message.

Returns

  • filled::Vector: The same length as v, and free of blanks.

ForwardPanelFill and BackwardPanelFill read act, so that no value crosses an inactive stretch.

panel_placeholder (optional)

  • panel_placeholder(alg::AbstractPanelFillAlgorithm, v::AbstractVector, act::Option{<:AbstractVector{Bool}}) -> AbstractVector{Bool}: Which blanks of one asset's column the policy resolves to a placeholder, a value that holds no data.

Arguments

  • alg: The concrete subtype instance.
  • v: One asset's raw values along the observation axis, blanks included.
  • act: The asset's column of the active mask, or nothing for a static Panel Field. A policy that reads no mask ignores it.

Returns

  • plc::AbstractVector{Bool}: The same length as v, true at a blank that the policy resolves to a placeholder.

The fallback marks no cell, so every value that a policy writes is data unless the policy defines this method. ForwardPanelFill and BackwardPanelFill define it, and their val is a placeholder.

An input checks the type of val against the type of its cells with assert_panel_fill_value, for the policies of the library only. A new policy needs no field val, and a new policy that carries one checks its type in its own constructor.

Related

source
PortfolioOptimisers.NumericPanelInput — Type
struct NumericPanelInput{__T_name, __T_vals, __T_alg} <: AbstractPanelFieldInput

Raw form of a Panel Field holding one numeric quantity per observation and asset.

Fields

  • name: The Panel Field's name, which names its column of a derived Feature Matrix.
  • vals: Raw values, blanks included, assets when static and observations × assets when time-varying. A blank is a missing, a nothing or a NaN.
  • alg: The policy that resolves the blanks, or nothing to refuse a blank.

Constructors

NumericPanelInput(;    name::AbstractString,    vals::AbstractArray,    alg::Option{<:AbstractPanelFillAlgorithm} = nothing) -> NumericPanelInput

Keywords correspond to the struct's fields.

Validation

  • !isempty(name).
  • !isempty(vals).
  • ndims(vals) is 1 or 2.
  • A fill policy that carries a val carries a number. See assert_panel_fill_value.

Examples

julia> NumericPanelInput(; name = "mcap", vals = [1.0 2.0; 3.0 4.0])NumericPanelInput  name ┼ String: "mcap"  vals ┼ 2×2 Matrix{Float64}   alg ┴ nothing

Related

source
PortfolioOptimisers.CategoricalPanelInput — Type
struct CategoricalPanelInput{__T_name, __T_vals, __T_levels, __T_alg} <: AbstractPanelFieldInput

Raw form of a Panel Field holding one category label per observation and asset.

Fields

  • name: The Panel Field's name, which prefixes each of its columns of a derived Feature Matrix.
  • vals: Raw labels, blanks included, assets when static and observations × assets when time-varying. A blank is a missing or a nothing.
  • levels: The category levels, in column order, or nothing to read them off the resolved labels in sorted order.
  • alg: The policy that resolves the blanks, or nothing to refuse a blank. When levels is given, a val that the policy writes must be one of them, or panel_input_field throws.

Constructors

CategoricalPanelInput(;    name::AbstractString,    vals::AbstractArray,    levels::Option{<:VecStr} = nothing,    alg::Option{<:AbstractPanelFillAlgorithm} = nothing) -> CategoricalPanelInput

Keywords correspond to the struct's fields.

Validation

Examples

julia> CategoricalPanelInput(; name = "sector", vals = ["T" "E"; "T" "E"])CategoricalPanelInput    name ┼ String: "sector"    vals ┼ 2×2 Matrix{String}  levels ┼ nothing     alg ┴ nothing

Related

source
PortfolioOptimisers.TensorPanelInput — Type
struct TensorPanelInput{__T_name, __T_vals, __T_axis, __T_labels, __T_groups, __T_alg} <: AbstractPanelFieldInput

Raw form of a Panel Field whose label axis, its second axis, carries its own labels, and optionally its own groups.

Fields

  • name: The Panel Field's name, which prefixes each of its columns of a derived Feature Matrix.
  • vals: Raw values, blanks included, assets × labels when static and assets × labels × observations when time-varying. A blank is a missing, a nothing or a NaN.
  • axis: Name of what the label axis, the second axis, represents, such as "factor".
  • labels: Labels of the label-axis entries, one per entry of the second axis of vals.
  • groups: Optional group of each label-axis entry, such as a Factor Family, one per label.
  • alg: The policy that resolves the blanks, or nothing to refuse a blank.

Constructors

TensorPanelInput(;    name::AbstractString,    vals::AbstractArray,    axis::AbstractString,    labels::VecStr,    groups::Option{<:VecStr} = nothing,    alg::Option{<:AbstractPanelFillAlgorithm} = nothing) -> TensorPanelInput

Keywords correspond to the struct's fields.

Validation

  • !isempty(name).
  • !isempty(vals).
  • ndims(vals) is 2 or 3.
  • size(vals, 2) == length(labels). The second axis of vals carries the labels, in the static shape and in the time-varying one.
  • A fill policy that carries a val carries a number. See assert_panel_fill_value.
  • TensorPanelField, which this input builds, checks axis, labels and groups.

Examples

julia> TensorPanelInput(; name = "beta", vals = ones(2, 1, 2), axis = "factor", labels = ["size"])TensorPanelInput    name ┼ String: "beta"    vals ┼ Array{Float64, 3}: [1.0; 1.0;;; 1.0; 1.0]    axis ┼ String: "factor"  labels ┼ Vector{String}: ["size"]  groups ┼ nothing     alg ┴ nothing

Related

source
PortfolioOptimisers.ConstantPanelFill — Type
struct ConstantPanelFill{__T_val} <: AbstractPanelFillAlgorithm

Resolves every blank cell to one constant.

This is the policy for a quantity whose absence has a value, such as a zero dividend before the first payment, or a residual category before a classification exists. So the value it writes is data. The observed mask marks the cell false, and every reader reads the value.

Fields

  • val: The value that every blank cell takes. It is a number for a numeric or a tensor Panel Field, and a level label for a categorical one.

Constructors

ConstantPanelFill(;    val::Union{Number, AbstractString} = 0.0) -> ConstantPanelFill

Keywords correspond to the struct's fields.

Validation

  • If val is a Number, isfinite(val). A non-finite fill would put an infinity into a Panel Field, which assert_panel_finite refuses.

Examples

julia> ConstantPanelFill()ConstantPanelFill  val ┴ Float64: 0.0

Related

source
PortfolioOptimisers.ForwardPanelFill — Type
struct ForwardPanelFill{__T_val, __T_lim} <: AbstractPanelFillAlgorithm

Resolves a blank cell to the nearest earlier observed value of the same asset.

This is the safe fill over a cross-validation fold. It looks backward along the observation axis, so a filled cell takes its value from an earlier row only. A fold that ends at a row reads no value of a later row.

A blank at observation t takes the value of the last observed cell s < t when t - s <= lim, or always when lim is nothing. Otherwise it takes val, and so does a leading blank, which has no earlier value to take. That val is a placeholder, not data. The placeholder mask marks the cell, and no reader reads it. A cell that the fill carries a value into holds data. See panel_placeholder.

The fill runs within each stretch of constant activity of the asset's active mask. No value crosses an inactive stretch, so an asset that delists and lists again does not carry the last value of its first listing into its second, and the run of blanks that lim counts restarts in each stretch.

Fields

  • val: The value that a blank takes when no earlier observed value reaches it.
  • lim: The most consecutive blanks that one observed value fills, or nothing for no limit. A blank further along the run takes val.

Constructors

ForwardPanelFill(;    val::Union{Number, AbstractString} = 0.0,    lim::Option{<:Integer} = nothing) -> ForwardPanelFill

Keywords correspond to the struct's fields.

Validation

  • If val is a Number, isfinite(val).
  • If lim is not nothing, lim > 0.

Examples

julia> ForwardPanelFill()ForwardPanelFill  val ┼ Float64: 0.0  lim ┴ nothing

Related

source
PortfolioOptimisers.BackwardPanelFill — Type
struct BackwardPanelFill{__T_val, __T_lim} <: AbstractPanelFillAlgorithm

Resolves a blank cell to the nearest later observed value of the same asset.

This policy looks forward, and it leaks across a fold boundary

asset_panel runs one time, over the whole history, and knows no fold. So a backward fill carries a value from an observation into an earlier one, and a fold that ends before the source row still reads the value of the source row. A cross-validation score over a panel built this way is optimistic, and the leak reaches back the length of the blank run. Use ForwardPanelFill for a Panel Field that a fold will read.

The library keeps the policy because a Panel Field can be built outside any fold, where no row reads a later one.

A blank at observation t takes the value of the first observed cell s > t when s - t <= lim, or always when lim is nothing. Otherwise it takes val, and so does a trailing blank, which has no later value to take. That val is a placeholder, not data. The placeholder mask marks the cell, and no reader reads it. A cell that the fill carries a value into holds data. See panel_placeholder.

The fill runs within each stretch of constant activity of the asset's active mask. No value crosses an inactive stretch, so an asset that delists and lists again does not carry the first value of its second listing back into its first, and the run of blanks that lim counts restarts in each stretch.

Fields

  • val: The value that a blank takes when no later observed value reaches it.
  • lim: The most consecutive blanks that one observed value fills, or nothing for no limit. A blank further along the run takes val.

Constructors

BackwardPanelFill(;    val::Union{Number, AbstractString} = 0.0,    lim::Option{<:Integer} = nothing) -> BackwardPanelFill

Keywords correspond to the struct's fields.

Validation

  • If val is a Number, isfinite(val).
  • If lim is not nothing, lim > 0.

Examples

julia> BackwardPanelFill()BackwardPanelFill  val ┼ Float64: 0.0  lim ┴ nothing

Related

source

Functions

PortfolioOptimisers.asset_panel — Function
asset_panel(
    inputs::AbstractVector{<:AbstractPanelFieldInput};
    amsk::Option{<:AbstractMatrix{Bool}} = nothing,
    emsk::Option{<:AbstractMatrix{Bool}} = nothing
) -> AssetPanel

Build the AssetPanel that a PricesResult or a ReturnsResult holds, from the raw, blank-carrying form of each Panel Field.

This function builds the panel. It takes the raw values of each Panel Field with its fill policy, and it returns the panel alone. The panel owns the values, so the PricesResult or the ReturnsResult needs nothing else. The function resolves every blank, and every Panel Field comes out finite.

The result goes straight into the pnl keyword that PricesResult and ReturnsResult both have, ReturnsResult(; nx = nx, X = X, pnl = asset_panel(inputs)), and the same keyword reaches prices_to_returns.

The rank of the raw values marks a static input. An input whose values carry no observation axis is static, such as a fundamentals table or a sector classification with no history. A static input refuses ForwardPanelFill and BackwardPanelFill, because it has no observation axis to carry a value along.

A set of static inputs with no mask builds a static panel. A static input that meets a time-varying input, or a mask, is lifted. panel_build_observations reads the observation count of the build, and panel_field_lift wraps the static values in a RepeatedObservations, which stores them once and indexes the observation axis that observation_axis names for its rank. A lifted Panel Field keeps its observed mask and its placeholder mask, lifted in the same way.

Algorithm

  1. Check that inputs is not empty and that the Panel Field names are unique.
  2. Check each input's fill policy against its shape, with assert_panel_input_fill.
  3. Read the observation count the build takes, with panel_build_observations.
  4. Resolve every input with panel_resolve, which fills its blanks within each stretch of constant activity of amsk and records the observed cells, and build its Panel Field with panel_input_field. Give it the placeholder mask of panel_input_placeholder with panel_field_placeholder. Lift a static Panel Field of a time-varying build with panel_field_lift.
  5. Return the panel with no mask when the build is static.
  6. Otherwise fill in the masks that were not given, and return the panel. A missing active mask is all-true. A missing estimation mask is the active mask. The estimation mask is a subset of the active mask, and the whole active mask is the only subset that needs no more information. An all-true default would break the subset rule at the first inactive cell. The AssetPanel constructor checks that every Panel Field has one shape.

Arguments

  • inputs: The raw Panel Fields, in the order their columns are derived in.
  • amsk: The active mask (observations × assets), or nothing for all-true.
  • emsk: The estimation mask (observations × assets), or nothing for the active mask.

Validation

Returns

  • pnl::AssetPanel: The Asset Panel.

Examples

julia> pnl = asset_panel([NumericPanelInput(; name = "mcap", vals = [1.0, 2.0, 3.0]),                          CategoricalPanelInput(; name = "sector", vals = ["Fin", "Tech", "Fin"])]);julia> panel_feature_matrix(pnl)[1]3-element Vector{String}: "mcap" "sector=Fin" "sector=Tech"

Related

source
asset_panel(ape::Nothing, pr, rd::ReturnsResult, X) -> AssetPanel
asset_panel(ape::Nothing, pr::ReturnsResult, rd::Nothing, X) -> AssetPanel
asset_panel(ape::Nothing, pr, rd::Nothing, X) -> Union{}

Resolve the AssetPanel a FeatureDistance with no producer measures.

nothing in the ape slot tells the kernel to read the panel that the ReturnsResult holds. The data reaches the kernel as the two keywords pr and rd, and this function selects the source by dispatch. A ReturnsResult in either slot gives its pnl. When both slots hold one, rd wins, because rd is the returns data. Pr_RR admits a ReturnsResult in the pr slot, and clusterise(cle, rd) and every Pipeline step pass it there. So the second method serves the shortest public call.

A prior result alone carries no panel, so the call raises an IsNothingError that names the two ways to supply one.

Algorithm

The method that Julia selects is the algorithm.

  1. rd is a ReturnsResult: answer rd.pnl.
  2. pr is a ReturnsResult and there is no rd: answer pr.pnl.
  3. Neither slot holds a ReturnsResult: raise.

Each of the first two checks that the ReturnsResult it read holds a panel, with assert_asset_panel_supplied.

Arguments

  • ape: nothing, which reads the panel of the ReturnsResult.
  • pr: Prior result or returns result. Both carry the asset returns matrix X, so either can supply it.
  • rd: The returns result to use.
  • X: Returns matrix of the subproblem. Unread here; a producer reads it.

Validation

Returns

  • pnl::AssetPanel: The Asset Panel that the ReturnsResult holds.

Related

source
asset_panel(df::DataFrames.DataFrame, mf::DataFrames.DataFrame;
            fields = nothing) -> AssetPanel

Read an AssetPanel from a table that panel_dataframe wrote and the manifest that panel_manifest wrote. This is the inverse of the export.

The two tables can go through any table format and come back, for example through CSV.jl or Arrow.jl, so a panel makes a round trip through a file with no file format of its own. Arrow.jl can map a file into memory, and a column selection before the read gives a subset of the Panel Fields.

The function reads the long and the wide layouts, and tells them apart by the "asset" column, which only the long layout holds. It does not read the single-field shape, which holds no mask.

  • A wide table holds every cell and both universe masks, so the panel comes back whole.
  • A long table holds only the rows where the active mask is true. The function makes the active mask from the rows that the table holds, and the manifest gives the axes. The value of a cell outside the universe does not come back. The cell gets zero, the first level of a categorical Panel Field, and false in each mask that the Panel Field carries. A Panel Field with no observed mask or no placeholder mask comes back with no such mask.

A read that masks the cells outside the universe gives the same answer before and after a long round trip, for example panel_field_values with inactive = NaN. A read that keeps those cells gets the new values. Two such reads are panel_field_values with its default inactive = nothing, and the wide layout of panel_dataframe.

The function compares names and labels as text, so a reader that types a column still matches the manifest. A reader that changes the text of a name does not match it: CSV.jl reads the asset name "007" as the integer 7. Read such a column as text. The manifest records whether each categorical column holds the levels or the codes, so the function reads the column as panel_dataframe wrote it.

The codes of a categorical column that holds the codes keep the integer type of the column, so Int32 codes come back as Int32 codes when the reader keeps the column type. A column that holds the levels carries no code type, and its codes are the positions of the levels, which are Int. See panel_code_eltype.

A static Panel Field that a time-varying panel lifts, see RepeatedObservations, comes back as an ordinary array with the same values.

Algorithm

  1. Read the axes and the Panel Field entries of the manifest with panel_manifest_axes and panel_manifest_fields. Keep the entries that fields names with panel_manifest_select.
  2. Tell the layout with panel_table_cells. In the long layout, it finds the cell of each row. In the wide layout, it checks the row count: one row on a static panel, one row per observation on a time-varying one.
  3. Read each Panel Field with panel_read_field. When no entry is kept, the panel holds pf = nothing.
  4. On a time-varying panel, read the masks. panel_active_mask reads the active mask. The estimation mask is the "emsk" column of a long table, and the "emsk@<asset>" columns of a wide one.
  5. Make the panel with the AssetPanel constructor, which checks it.

Arguments

  • df: The table, in the long or the wide layout of panel_dataframe.
  • mf: The manifest, from panel_manifest.
  • fields: One Panel Field name as a string, a collection of names, or nothing for all Panel Fields of the manifest.

Validation

  • The manifest is one that panel_manifest wrote. Raises an ArgumentError or a KeyError. See panel_manifest_axes and panel_manifest_fields.
  • The manifest holds every named Panel Field. Raises a KeyError.
  • The table holds each column that the manifest and fields name. Raises a KeyError.
  • A wide table has one row, or one row per observation. Raises a DimensionMismatch.
  • The "observation" column of a wide table names the observations of the manifest, as text and in order. Raises an ArgumentError. See panel_table_cells.
  • The rows of a long table name cells of the manifest, each once. See panel_long_cells.
  • No cell that the function reads is missing. Raises an ArgumentError.
  • The value columns of a Panel Field state a type. A long table with no row, read back by CSV.jl, types each column as Missing. Raises an ArgumentError. See panel_table_eltype.
  • The AssetPanel constructor and the constructor of each Panel Field check the result.

Returns

  • pnl::AssetPanel: The Asset Panel.

Examples

julia> pnl = AssetPanel(;                        pf = [NumericPanelField(; name = "mcap", vals = [1.0 2.0; 3.0 4.0]),                              CategoricalPanelField(; name = "sector",                                                    levels = ["Tech", "Energy", "Retail"],                                                    codes = [1 2; 1 1])], amsk = Bool[1 0; 1 1],                        emsk = Bool[1 0; 0 1]);julia> df = panel_dataframe(pnl; nx = ["A", "B"]);julia> mf = panel_manifest(pnl; nx = ["A", "B"]);julia> pnl2 = asset_panel(df, mf);julia> pnl2.amsk == pnl.amsk, pnl2.emsk == pnl.emsk(true, true)julia> panel_field(pnl2, "sector").levels3-element Vector{String}: "Tech" "Energy" "Retail"

Related

source
asset_panel(ape::RegressionPanel, pr, rd, X) -> AssetPanel
asset_panel(ape::PhylogenyPanel, pr, rd, X) -> AssetPanel

Build the static AssetPanel of a producer, at the point of use.

Each method returns a panel that holds one TensorPanelField, because a loadings matrix and a proximity matrix are each one quantity with a labelled second axis. The labels of the label axis come from the returns data or from the regression block where a name exists, and are positions otherwise. panel_axis_labels and regression_factor_names state the rule.

A producer runs on the prior and the returns of its own subproblem, so no view reads the panel that it builds, and a fold refits it. Called on its own, on a prior fitted on a point-in-time Asset Panel, a RegressionPanel reads the loadings on the Investable Mask of the prior and answers for the full universe. Outside the mask each asset gets a zero row and a false observed mask, so an optimiser can take the panel back. expand_investable_loadings states the rule.

Algorithm

A RegressionPanel takes seven steps:

  1. Check that a prior result reached the call, with assert_producer_prior.
  2. Check that the prior holds a regression, with assert_prior_regression.
  3. Reduce the prior to its Investable Mask through investable_mask and port_opt_view, giving prr, and read its loadings L. A prior fitted on a point-in-time Asset Panel writes NaN into the loadings of every asset outside its mask, and a Panel Field admits no NaN. Inside an optimiser the prior arrives reduced, and the view covers the whole universe.
  4. Count the assets on the mask whose loadings are not all finite, giving nnf, and refuse a count above zero. Such an asset has a finite moment and a loadings row that is not finite, which is a defect of the regression.
  5. Label the loadings axis with panel_axis_labels, from regression_factor_names.
  6. Expand the loadings back onto the full universe with expand_investable_loadings, giving vals and omsk.
  7. Return the panel that holds them as the field "loadings" on the axis "factor".

A PhylogenyPanel takes three steps:

  1. Grade the structure into an assets × assets matrix with phylogeny_features, giving Zp.
  2. Label the label axis with panel_axis_labels, from returns_asset_names.
  3. Return the panel that holds Zp as the field "proximity" on the axis "asset".

Arguments

  • ape: The producer.
  • pr: Prior result or returns result. Both carry the asset returns matrix X, so either can supply it.
  • rd: The returns result to use. Read for the axis names alone.
  • X: Returns matrix of the subproblem, observations × assets.

Validation

Returns

  • pnl::AssetPanel: A static Asset Panel that holds one tensor Panel Field.

Related

source
PortfolioOptimisers.panel_fill — Function
panel_fill(::Nothing, v::AbstractVector, act::Option{<:AbstractVector{Bool}}, name::AbstractString) -> Vector
panel_fill(alg::ConstantPanelFill, v::AbstractVector, act::Option{<:AbstractVector{Bool}}, name::AbstractString) -> Vector
panel_fill(alg::ForwardPanelFill, v::AbstractVector, act::Nothing, name::AbstractString) -> Vector
panel_fill(alg::BackwardPanelFill, v::AbstractVector, act::Nothing, name::AbstractString) -> Vector
panel_fill(alg::Union{ForwardPanelFill, BackwardPanelFill}, v::AbstractVector, act::AbstractVector{Bool}, name::AbstractString) -> Vector

Resolve the blanks of one asset's column of one raw Panel Field, along the observation axis.

act is the asset's column of the active mask. A directional policy fills each stretch of constant activity on its own, so no value crosses an inactive stretch. Every other policy, and a directional one given act = nothing, ignores act and resolves the whole column.

Algorithm

The method that Julia selects is the algorithm, and the four differ in where the replacement comes from.

  1. nothing fills no cell. It throws when a cell is blank, and names the Panel Field and the position of the first blank in the column. Otherwise it returns the column unchanged.
  2. ConstantPanelFill replaces every blank by alg.val. The element type of the result is the union of the element types of v and alg.val for every column, so the columns of one Panel Field agree.
  3. ForwardPanelFill walks the observations in order and carries the last observed value. A blank at t takes the carried value from s when t - s <= alg.lim, and alg.val otherwise.
  4. BackwardPanelFill does the same walk in reverse order. This looks forward in time, and the docstring of the type states what that costs a fold.
  5. With a mask act, a directional policy splits the column into the stretches of constant activity with panel_activity_stretches, and resolves each stretch with its method for act = nothing.

Arguments

  • alg: The fill policy, or nothing to fill no cell.
  • v: One asset's raw values along the observation axis, blanks included.
  • act: The asset's column of the active mask, the same length as v, or nothing for no mask.
  • name: The Panel Field's name, displayed in the error message of nothing.

Validation

  • Under nothing, v carries no blank. Raises an ArgumentError.

Returns

  • filled::Vector: The same length as v, and free of blanks.

Related

source
PortfolioOptimisers.panel_placeholder — Function
panel_placeholder(alg::Option{<:AbstractPanelFillAlgorithm}, v::AbstractVector, act::Option{<:AbstractVector{Bool}}) -> AbstractVector{Bool}
panel_placeholder(alg::ForwardPanelFill, v::AbstractVector, act::Nothing) -> BitVector
panel_placeholder(alg::BackwardPanelFill, v::AbstractVector, act::Nothing) -> BitVector
panel_placeholder(alg::Union{ForwardPanelFill, BackwardPanelFill}, v::AbstractVector, act::AbstractVector{Bool}) -> BitVector

Mark the blanks of one asset's column that a fill policy resolves to a placeholder, a value that holds no data.

A value that a fill policy writes is data, and every reader reads it. ConstantPanelFill writes the value of the absence, and a directional fill carries an observed value. A directional fill that has nothing to carry into a cell writes its val there only because a Panel Field holds no blank. That val is a placeholder. The placeholder mask of the Panel Field records it, and no reader reads it.

Algorithm

The method that Julia selects is the algorithm.

  1. A policy that defines no method marks no cell, so every value that it writes is data. nothing writes no value, and ConstantPanelFill writes data.
  2. ForwardPanelFill and BackwardPanelFill mark the cells that panel_directional_placeholder marks, in their own order.
  3. With a mask act, a directional policy marks each stretch of constant activity on its own, as panel_fill fills it. Every other policy, and a directional one given act = nothing, ignores act.

Arguments

  • alg: The fill policy.
  • v: One asset's raw values along the observation axis, blanks included.
  • act: The asset's column of the active mask, the same length as v, or nothing for no mask.

Returns

  • plc::AbstractVector{Bool}: The same length as v, true at a placeholder.

Related

source
PortfolioOptimisers.panel_resolve — Function
panel_resolve(inp::NumericPanelInput, amsk::Option{<:AbstractMatrix{Bool}} = nothing) -> Tuple{Array, BitArray}
panel_resolve(inp::CategoricalPanelInput, amsk::Option{<:AbstractMatrix{Bool}} = nothing) -> Tuple{Array{String}, BitArray}
panel_resolve(inp::TensorPanelInput, amsk::Option{<:AbstractMatrix{Bool}} = nothing) -> Tuple{Array, BitArray}

Resolve one raw Panel Field's blanks, and record which of its cells were observed.

The active mask sets the stretches that a directional fill runs within.

Algorithm

The method that Julia selects is the algorithm, and the three differ only in the element type of the result. A categorical Panel Field resolves into String. A numeric and a tensor Panel Field resolve into the type of their filled cells, which panel_value_eltype derives. The element type of the raw array is a type such as Union{Missing, Float64}, Union{Nothing, Float64} or Any, and none of these is the type of the cells. The narrowing by the values removes the blank type from the resolved field, and it keeps a Float32 field in Float32.

  1. Fill the blanks with panel_fill_array, over the mask that panel_input_mask returns.
  2. Derive the resolved element type from the filled cells, with panel_value_eltype.
  3. Walk the raw cells, recording which were observed and copying the filled value into the output.
  4. Check that a numeric or a tensor Panel Field carries no non-finite value, with assert_panel_finite.

Arguments

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

Validation

Returns

  • vals::AbstractArray: The resolved values, the same size as the raw ones.
  • obs::BitArray: The observed mask, the same size as the raw values.

Related

source
PortfolioOptimisers.panel_input_field — Function
panel_input_field(inp::NumericPanelInput, vals, obs) -> NumericPanelField
panel_input_field(inp::CategoricalPanelInput, vals, obs) -> CategoricalPanelField
panel_input_field(inp::TensorPanelInput, vals, obs) -> TensorPanelField

Return the Panel Field a resolved raw Panel Field builds, deriving what the input left to be derived.

Algorithm

The method that Julia selects is the algorithm.

  1. NumericPanelInput: a NumericPanelField over the resolved values.
  2. CategoricalPanelInput: a CategoricalPanelField over inp.levels. When inp.levels is nothing, the levels are the distinct resolved labels in sorted order. The function reads the resolved labels and not the raw ones, so a level that only a fill policy writes gets a code. Each label is then encoded to the position of its level.
  3. TensorPanelInput: a TensorPanelField over the axis, the labels and the groups of the input.

The Panel Field holds the observed mask only when the fill policy is not nothing. A Panel Field that refuses a blank observed every cell, so its mask would record nothing.

Arguments

  • inp: The raw Panel Field.
  • vals: The resolved values, as panel_resolve returned them.
  • obs: The observed mask, as panel_resolve returned it.

Validation

  • Every resolved label of a categorical Panel Field is one of its levels. Raises an ArgumentError.

Returns

  • f::AbstractPanelField: The Panel Field.

Related

source
PortfolioOptimisers.panel_input_placeholder — Function
panel_input_placeholder(inp::NumericPanelInput, amsk::Option{<:AbstractMatrix{Bool}}) -> Option{BitArray}
panel_input_placeholder(inp::CategoricalPanelInput, amsk::Option{<:AbstractMatrix{Bool}}) -> Option{BitArray}
panel_input_placeholder(inp::TensorPanelInput, amsk::Option{<:AbstractMatrix{Bool}}) -> Option{BitArray}
panel_input_placeholder(inp::AbstractPanelFieldInput, amsk::Option{<:AbstractMatrix{Bool}}) -> nothing

Return the placeholder mask of the Panel Field that one raw Panel Field builds, or nothing when its fill writes no placeholder.

asset_panel gives the mask to the Panel Field with panel_field_placeholder. The last method is the fallback for an input type that defines none. Its fill writes no placeholder, so every value that it writes is data.

Algorithm

  1. Mark the placeholders with panel_placeholder_array, over the mask that panel_input_mask returns.
  2. Return nothing when no cell is a placeholder.

Arguments

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

Returns

  • pmsk::Option{BitArray}: The placeholder mask, the same size as the raw values, or nothing.

Related

source
PortfolioOptimisers.panel_input_is_static — Function
panel_input_is_static(inp::NumericPanelInput) -> Bool
panel_input_is_static(inp::CategoricalPanelInput) -> Bool
panel_input_is_static(inp::TensorPanelInput) -> Bool

Return whether a raw Panel Field carries no observation axis.

The rank of the raw values sets the shape. A numeric or a categorical input is assets when static and observations × assets when time-varying. A tensor input is assets × labels when static and assets × labels × observations when time-varying.

Algorithm

The method that Julia selects is the algorithm, and the three differ only in the rank the static shape takes.

Arguments

  • inp: The raw Panel Field.

Returns

  • static::Bool: true when the raw values carry no observation axis.

Related

source