Asset Panel builder
Types
PortfolioOptimisers.AbstractPanelFieldInput — Type
abstract type AbstractPanelFieldInput <: AbstractEstimatorSupertype 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:truewhen 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), ornothing. An input type that reads no mask ignores it. An input type that reads it passes each asset's column topanel_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 asvals.
panel_input_field
panel_input_field(inp::AbstractPanelFieldInput, vals::AbstractArray, obs::BitArray) -> AbstractPanelField: Build the Panel Field from the resolved values, withobsas its observed mask unless the fill policy isnothing, which admits no blank and so records no mask.
Arguments
inp: The concrete subtype instance.vals: The resolved values, aspanel_resolvereturned them.obs: The observed cells, aspanel_resolvereturned 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,trueat a cell whose resolved value holds no data, ornothing.
Arguments
inp: The concrete subtype instance.amsk: The active mask (observations × assets), ornothing.
Returns
pmsk::Option{AbstractArray{Bool}}: The placeholder mask, the same size as the resolved values, ornothing.
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
PortfolioOptimisers.AbstractPanelFillAlgorithm — Type
abstract type AbstractPanelFillAlgorithm <: AbstractAlgorithmSupertype 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, ornothingfor 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 asv, 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, ornothingfor a static Panel Field. A policy that reads no mask ignores it.
Returns
plc::AbstractVector{Bool}: The same length asv,trueat 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
PortfolioOptimisers.NumericPanelInput — Type
struct NumericPanelInput{__T_name, __T_vals, __T_alg} <: AbstractPanelFieldInputRaw 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,assetswhen static andobservations × assetswhen time-varying. A blank is amissing, anothingor aNaN.
alg: The policy that resolves the blanks, ornothingto refuse a blank.
Constructors
NumericPanelInput(; name::AbstractString, vals::AbstractArray, alg::Option{<:AbstractPanelFillAlgorithm} = nothing) -> NumericPanelInputKeywords correspond to the struct's fields.
Validation
!isempty(name).!isempty(vals).ndims(vals)is1or2.- A fill policy that carries a
valcarries a number. Seeassert_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 ┴ nothingRelated
PortfolioOptimisers.CategoricalPanelInput — Type
struct CategoricalPanelInput{__T_name, __T_vals, __T_levels, __T_alg} <: AbstractPanelFieldInputRaw 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,assetswhen static andobservations × assetswhen time-varying. A blank is amissingor anothing.
levels: The category levels, in column order, ornothingto read them off the resolved labels in sorted order.
alg: The policy that resolves the blanks, ornothingto refuse a blank. Whenlevelsis given, avalthat the policy writes must be one of them, orpanel_input_fieldthrows.
Constructors
CategoricalPanelInput(; name::AbstractString, vals::AbstractArray, levels::Option{<:VecStr} = nothing, alg::Option{<:AbstractPanelFillAlgorithm} = nothing) -> CategoricalPanelInputKeywords correspond to the struct's fields.
Validation
!isempty(name).!isempty(vals).ndims(vals)is1or2.- If
levelsis notnothing, it passesassert_panel_labels. - A fill policy that carries a
valcarries a string. Seeassert_panel_fill_value.
Examples
julia> CategoricalPanelInput(; name = "sector", vals = ["T" "E"; "T" "E"])CategoricalPanelInput name ┼ String: "sector" vals ┼ 2×2 Matrix{String} levels ┼ nothing alg ┴ nothingRelated
PortfolioOptimisers.TensorPanelInput — Type
struct TensorPanelInput{__T_name, __T_vals, __T_axis, __T_labels, __T_groups, __T_alg} <: AbstractPanelFieldInputRaw 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 × labelswhen static andassets × labels × observationswhen time-varying. A blank is amissing, anothingor aNaN.
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 ofvals.
groups: Optional group of each label-axis entry, such as a Factor Family, one per label.
alg: The policy that resolves the blanks, ornothingto refuse a blank.
Constructors
TensorPanelInput(; name::AbstractString, vals::AbstractArray, axis::AbstractString, labels::VecStr, groups::Option{<:VecStr} = nothing, alg::Option{<:AbstractPanelFillAlgorithm} = nothing) -> TensorPanelInputKeywords correspond to the struct's fields.
Validation
!isempty(name).!isempty(vals).ndims(vals)is2or3.size(vals, 2) == length(labels). The second axis ofvalscarries the labels, in the static shape and in the time-varying one.- A fill policy that carries a
valcarries a number. Seeassert_panel_fill_value. TensorPanelField, which this input builds, checksaxis,labelsandgroups.
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 ┴ nothingRelated
PortfolioOptimisers.ConstantPanelFill — Type
struct ConstantPanelFill{__T_val} <: AbstractPanelFillAlgorithmResolves 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) -> ConstantPanelFillKeywords correspond to the struct's fields.
Validation
- If
valis aNumber,isfinite(val). A non-finite fill would put an infinity into a Panel Field, whichassert_panel_finiterefuses.
Examples
julia> ConstantPanelFill()ConstantPanelFill val ┴ Float64: 0.0Related
PortfolioOptimisers.ForwardPanelFill — Type
struct ForwardPanelFill{__T_val, __T_lim} <: AbstractPanelFillAlgorithmResolves 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, ornothingfor no limit. A blank further along the run takesval.
Constructors
ForwardPanelFill(; val::Union{Number, AbstractString} = 0.0, lim::Option{<:Integer} = nothing) -> ForwardPanelFillKeywords correspond to the struct's fields.
Validation
- If
valis aNumber,isfinite(val). - If
limis notnothing,lim > 0.
Examples
julia> ForwardPanelFill()ForwardPanelFill val ┼ Float64: 0.0 lim ┴ nothingRelated
PortfolioOptimisers.BackwardPanelFill — Type
struct BackwardPanelFill{__T_val, __T_lim} <: AbstractPanelFillAlgorithmResolves a blank cell to the nearest later observed value of the same asset.
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, ornothingfor no limit. A blank further along the run takesval.
Constructors
BackwardPanelFill(; val::Union{Number, AbstractString} = 0.0, lim::Option{<:Integer} = nothing) -> BackwardPanelFillKeywords correspond to the struct's fields.
Validation
- If
valis aNumber,isfinite(val). - If
limis notnothing,lim > 0.
Examples
julia> BackwardPanelFill()BackwardPanelFill val ┼ Float64: 0.0 lim ┴ nothingRelated
Functions
PortfolioOptimisers.asset_panel — Function
asset_panel(
inputs::AbstractVector{<:AbstractPanelFieldInput};
amsk::Option{<:AbstractMatrix{Bool}} = nothing,
emsk::Option{<:AbstractMatrix{Bool}} = nothing
) -> AssetPanelBuild 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
- Check that
inputsis not empty and that the Panel Field names are unique. - Check each input's fill policy against its shape, with
assert_panel_input_fill. - Read the observation count the build takes, with
panel_build_observations. - Resolve every input with
panel_resolve, which fills its blanks within each stretch of constant activity ofamskand records the observed cells, and build its Panel Field withpanel_input_field. Give it the placeholder mask ofpanel_input_placeholderwithpanel_field_placeholder. Lift a static Panel Field of a time-varying build withpanel_field_lift. - Return the panel with no mask when the build is static.
- 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-truedefault would break the subset rule at the first inactive cell. TheAssetPanelconstructor 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), ornothingfor all-true.emsk: The estimation mask (observations × assets), ornothingfor the active mask.
Validation
!isempty(inputs). Raises anIsEmptyError.- The Panel Field names are non-empty and unique. See
assert_panel_labels. - A static input carries no directional fill policy. See
assert_panel_input_fill. size(amsk)matches the observation and asset axes of each time-varying input. Seepanel_input_mask.- An input whose fill policy is
nothingcarries no blank. Seepanel_fill. - A numeric or a tensor input resolves to finite values. See
assert_panel_finite. - Each resolved label of a categorical input is one of its levels. See
panel_input_field. - The Panel Fields and the masks share one shape. See
AssetPanel.
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
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.
rdis aReturnsResult: answerrd.pnl.pris aReturnsResultand there is nord: answerpr.pnl.- 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 theReturnsResult.pr: Prior result or returns result. Both carry the asset returns matrixX, so either can supply it.rd: The returns result to use.X: Returns matrix of the subproblem. Unread here; a producer reads it.
Validation
- A
ReturnsResultis present, and it holds anAssetPanel. Raises anIsNothingError.
Returns
pnl::AssetPanel: The Asset Panel that theReturnsResultholds.
Related
asset_panel(df::DataFrames.DataFrame, mf::DataFrames.DataFrame;
fields = nothing) -> AssetPanelRead 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, andfalsein 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
- Read the axes and the Panel Field entries of the manifest with
panel_manifest_axesandpanel_manifest_fields. Keep the entries thatfieldsnames withpanel_manifest_select. - 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. - Read each Panel Field with
panel_read_field. When no entry is kept, the panel holdspf = nothing. - On a time-varying panel, read the masks.
panel_active_maskreads the active mask. The estimation mask is the"emsk"column of a long table, and the"emsk@<asset>"columns of a wide one. - Make the panel with the
AssetPanelconstructor, which checks it.
Arguments
df: The table, in the long or the wide layout ofpanel_dataframe.mf: The manifest, frompanel_manifest.fields: One Panel Field name as a string, a collection of names, ornothingfor all Panel Fields of the manifest.
Validation
- The manifest is one that
panel_manifestwrote. Raises anArgumentErroror aKeyError. Seepanel_manifest_axesandpanel_manifest_fields. - The manifest holds every named Panel Field. Raises a
KeyError. - The table holds each column that the manifest and
fieldsname. Raises aKeyError. - 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 anArgumentError. Seepanel_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 anArgumentError. - 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 anArgumentError. Seepanel_table_eltype. - The
AssetPanelconstructor 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
asset_panel(ape::RegressionPanel, pr, rd, X) -> AssetPanel
asset_panel(ape::PhylogenyPanel, pr, rd, X) -> AssetPanelBuild 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:
- Check that a prior result reached the call, with
assert_producer_prior. - Check that the prior holds a regression, with
assert_prior_regression. - Reduce the prior to its Investable Mask through
investable_maskandport_opt_view, givingprr, and read its loadingsL. A prior fitted on a point-in-time Asset Panel writesNaNinto the loadings of every asset outside its mask, and a Panel Field admits noNaN. Inside an optimiser the prior arrives reduced, and the view covers the whole universe. - 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. - Label the loadings axis with
panel_axis_labels, fromregression_factor_names. - Expand the loadings back onto the full universe with
expand_investable_loadings, givingvalsandomsk. - Return the panel that holds them as the field
"loadings"on the axis"factor".
A PhylogenyPanel takes three steps:
- Grade the structure into an
assets × assetsmatrix withphylogeny_features, givingZp. - Label the label axis with
panel_axis_labels, fromreturns_asset_names. - Return the panel that holds
Zpas the field"proximity"on the axis"asset".
Arguments
ape: The producer.pr: Prior result or returns result. Both carry the asset returns matrixX, 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
- A
RegressionPanelneeds a prior result that holds a regression. Raises anIsNothingError. - A
RegressionPanelneeds every loading inside the Investable Mask of the prior to be finite. Raises anIsNonFiniteErrorthat counts the assets whose loadings are not finite.
Returns
pnl::AssetPanel: A static Asset Panel that holds one tensor Panel Field.
Related
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) -> VectorResolve 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.
nothingfills 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.ConstantPanelFillreplaces every blank byalg.val. The element type of the result is the union of the element types ofvandalg.valfor every column, so the columns of one Panel Field agree.ForwardPanelFillwalks the observations in order and carries the last observed value. A blank atttakes the carried value fromswhent - s <= alg.lim, andalg.valotherwise.BackwardPanelFilldoes the same walk in reverse order. This looks forward in time, and the docstring of the type states what that costs a fold.- With a mask
act, a directional policy splits the column into the stretches of constant activity withpanel_activity_stretches, and resolves each stretch with its method foract = nothing.
Arguments
alg: The fill policy, ornothingto 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 asv, ornothingfor no mask.name: The Panel Field's name, displayed in the error message ofnothing.
Validation
- Under
nothing,vcarries no blank. Raises anArgumentError.
Returns
filled::Vector: The same length asv, and free of blanks.
Related
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}) -> BitVectorMark 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.
- A policy that defines no method marks no cell, so every value that it writes is data.
nothingwrites no value, andConstantPanelFillwrites data. ForwardPanelFillandBackwardPanelFillmark the cells thatpanel_directional_placeholdermarks, in their own order.- With a mask
act, a directional policy marks each stretch of constant activity on its own, aspanel_fillfills it. Every other policy, and a directional one givenact = nothing, ignoresact.
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 asv, ornothingfor no mask.
Returns
plc::AbstractVector{Bool}: The same length asv,trueat a placeholder.
Related
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.
- Fill the blanks with
panel_fill_array, over the mask thatpanel_input_maskreturns. - Derive the resolved element type from the filled cells, with
panel_value_eltype. - Walk the raw cells, recording which were observed and copying the filled value into the output.
- 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), ornothingfor all-true.
Validation
size(amsk)matches a time-varying input. Seepanel_input_mask.
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
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) -> TensorPanelFieldReturn 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.
NumericPanelInput: aNumericPanelFieldover the resolved values.CategoricalPanelInput: aCategoricalPanelFieldoverinp.levels. Wheninp.levelsisnothing, 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.TensorPanelInput: aTensorPanelFieldover 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, aspanel_resolvereturned them.obs: The observed mask, aspanel_resolvereturned 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
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}}) -> nothingReturn 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
- Mark the placeholders with
panel_placeholder_array, over the mask thatpanel_input_maskreturns. - Return
nothingwhen no cell is a placeholder.
Arguments
inp: The raw Panel Field.amsk: The active mask (observations × assets), ornothingfor all-true.
Returns
pmsk::Option{BitArray}: The placeholder mask, the same size as the raw values, ornothing.
Related
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) -> BoolReturn 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:truewhen the raw values carry no observation axis.
Related