Panel views: private API

PortfolioOptimisers.feature_row_indices — Function
feature_row_indices(pnl::Nothing, ts_new, ts_old) -> Colon
feature_row_indices(pnl::AssetPanel, ts_new, ts_old) -> Union{Colon, VecInt}

Recover the positional row indices of a time-varying AssetPanel from a timestamp window.

A Panel Field holds a plain array, so its observation axis follows the clock of the input data by position and not by timestamp. A routine that selects rows of X by timestamp calls this function to match the surviving timestamps back into the original clock, and the panel keeps the rows it finds. A surviving timestamp that is absent from that clock throws. Such a timestamp comes from an outer join that adds a row X never had. A positional slice past such a timestamp pairs each asset with the values of another period.

Two kinds of caller use it. At the price level, the clock is TimeSeries.timestamp(X) and the selection is a timestamp window. Where cross-validation assembles its folds, the clock is ReturnsResult.ts and the selection is a fold. There fold_row_indices recovers the rows of each fold from the timestamps that the fold's view of the returns holds. This is why ts must be unique. It is the key of the observation axis, and a repeated timestamp matches only its first position.

A static panel and an absent panel have no observation axis, so they return Colon and read no timestamp.

Algorithm

The method that Julia selects is the algorithm.

  1. pnl is nothing, or static: return Colon(). Neither has an observation axis, so the function reads no timestamp.
  2. pnl is time-varying: match ts_new into ts_old with matched_row_indices, giving the rows. That function throws when the selection kept no timestamp, or when a surviving timestamp is absent from the original clock.

Arguments

  • pnl: The Asset Panel, or nothing.
  • ts_new: The timestamps that survived the selection.
  • ts_old: The timestamps of the clock that the panel's observation axis follows.

Validation

When the panel is time-varying:

  • ts_new is not nothing. Raises an ArgumentError.
  • Every entry of ts_new appears in ts_old. Raises an ArgumentError.

Returns

  • rows::Union{Colon, Vector{Int}}: Colon() for a static or absent panel. Otherwise the position of each surviving timestamp in ts_old, in the order of ts_new.

Related

source
PortfolioOptimisers.matched_row_indices — Function
matched_row_indices(ts_new::Nothing, ts_old) -> Union{}
matched_row_indices(ts_new, ts_old) -> Vector{Int}

Match the surviving timestamps back into the original clock, and return the rows they hold.

feature_row_indices calls it for a time-varying AssetPanel, and listing_span_view calls it for a Listing Span. Both hold their observation axis parallel to the clock of the input data by position, so both recover their rows the same way.

Algorithm

The method that Julia selects is the algorithm.

  1. ts_new is nothing: throw. The selection kept no timestamp, so the function cannot name the rows to keep.
  2. Otherwise match ts_new into ts_old with indexin, giving rows. A timestamp that appears twice in ts_old matches its first position.
  3. Find the first entry of rows that indexin did not match, giving missed, and throw when there is one.
  4. Return rows as a Vector{Int}.

Arguments

  • ts_new: The timestamps that survived the selection.
  • ts_old: The timestamps of the clock that the observation axis follows.

Validation

  • ts_new is not nothing. Raises an ArgumentError.
  • Every entry of ts_new appears in ts_old. Raises an ArgumentError.

Returns

  • rows::Vector{Int}: The position of each surviving timestamp in ts_old, in the order of ts_new. An empty ts_new gives an empty vector.

Related

source
PortfolioOptimisers.panel_feature_names — Function
panel_feature_names(pnl::Union{Nothing, AssetPanel{Nothing}}) -> nothing
panel_feature_names(pnl::AssetPanel) -> Vector{String}

Name the columns an AssetPanel derives, without building the Feature Matrix.

A consumer that needs only the column names calls this function, which reads no value of the panel.

Algorithm

The method that Julia selects is the algorithm.

  1. pnl is nothing, or a panel with no Panel Field: return nothing.
  2. pnl is an AssetPanel with Panel Fields: read them in order into nz. For each field, append the names of its value columns, then the names of its observed-mask columns when the field has an observed mask.

Arguments

  • pnl: The Asset Panel, or nothing.

Returns

  • nz::Option{Vector{String}}: One name per derived column, in the column order of panel_feature_matrix, or nothing when there is no Panel Field.

Related

source
PortfolioOptimisers.label_positions — Function
label_positions(names, sel, what::AbstractString) -> typeof(sel)
label_positions(names, sel::Integer, what::AbstractString) -> UnitRange
label_positions(names, sel::Bool, what::AbstractString) -> Union{}
label_positions(names, sel::Union{Dates.AbstractTime, VecDate}, what::AbstractString) -> Union{}
label_positions(names::Nothing, sel::Union{AbstractString, VecStr}, what::AbstractString) -> Union{}
label_positions(names::AbstractVector, sel::Union{AbstractString, VecStr}, what::AbstractString) -> Vector{Int}

Turn the names that select assets or factors in a view into the positions of those names.

port_opt_view of a ReturnsResult and of a PricesResult calls it on each index that names assets or factors, so a caller can select them by name or by position. An integer vector, a range and a Colon pass through unchanged.

One integer n gives the range n:n, and one name gives the position of that name in a vector. So the view keeps its matrix shape, as one timestamp in the observation index does, see timestamp_positions. Without this step, view(X, :, n) drops the asset axis, and the constructor of the view refuses the vector with an error that names a field and not the index.

One Bool is refused, as Julia refuses it in an index. Bool <: Integer, so the integer step would give true:true, and Julia reads a range of Bool as a mask. On an axis of one entry, true would then select that entry with no error. A vector of Bool, one entry for each position of the axis, passes through as a mask.

A name that the input data does not hold is refused. An integer past the end of an axis throws, and a name that selects nothing is the same mistake. If the view dropped the name, a misspelt ticker would give a smaller universe and no error.

Algorithm

The method that Julia selects is the algorithm.

  1. sel is not an integer, not a name, not a vector of names, not a timestamp and not a vector of timestamps: return it unchanged.
  2. sel is one Bool: throw.
  3. sel is one integer n: return n:n.
  4. sel is a timestamp or a vector of timestamps: throw. A timestamp selects an observation, and this index selects what.
  5. sel is a name or a vector of names, and names is nothing: throw. The input data carries no names to match.
  6. sel is a name or a vector of names: put one name in a vector of one name. Match the vector into names with indexin, giving the positions. Throw when a name has no match, and name every such entry.

Arguments

  • names: The names of the axis that sel selects, or nothing.
  • sel: The index of the view: one name or a vector of names, one integer or a vector of integer positions, a range or a Colon.
  • what: The name of the axis, such as "asset", for the messages.

Validation

  • sel is not one Bool. Raises an ArgumentError.
  • sel is not a timestamp and not a vector of timestamps. Raises an ArgumentError.
  • names is not nothing when sel is a name or a vector of names. Raises an ArgumentError.
  • Every name of sel is in names. Raises an ArgumentError.

Returns

  • idx: sel unchanged, the range sel:sel of one integer, or the position of each name of sel in names, in the order of sel.

Related

source
PortfolioOptimisers.assert_timestamp_type — Function
assert_timestamp_type(T::Type{<:Union{Dates.Date, Dates.DateTime}},
                      S::Type{<:Union{Dates.Date, Dates.DateTime}}, sym::Sym_Str) -> Nothing
assert_timestamp_type(T::Type, S::Type{Nothing}, sym::Sym_Str) -> Nothing
assert_timestamp_type(T::Type, S::Type, sym::Sym_Str) -> Nothing

Check that a timestamp of type S, which selects or bounds observations, compares with timestamps of type T.

A comparison of two timestamps of different types goes through the promotion of their types. Dates promotes a Date and a DateTime, so a Date selects the observations at midnight of DateTime timestamps. Other pairs do not promote. A DateTime and a ZonedDateTime of TimeZones.jl is such a pair. A naive time names no instant, so TimeZones.jl defines no conversion between the two, and its promotion rule for the pair raises an error, which stops the comparison fallback of Dates from a recursion. Without this check, the comparison fails with an error about promotion that does not name the argument.

Algorithm

The method that Julia selects is the algorithm.

  1. T and S are both Date or DateTime: return nothing. Dates promotes the pair.
  2. S is Nothing: return nothing. No timestamp is given.
  3. Otherwise: check that one type is a subtype of the other.

Arguments

  • T: The element type of the timestamps of the data.
  • S: The type of the timestamps that the caller gives.
  • sym: Symbolic name used in the error message.

Validation

  • T <: S or S <: T, outside of the two cases above. Raises an ArgumentError that names sym, S and T.

Returns

  • nothing.

Related

source
PortfolioOptimisers.timestamp_positions — Function
timestamp_positions(ts, i) -> typeof(i)
timestamp_positions(ts, i::Integer) -> UnitRange
timestamp_positions(ts, i::Bool) -> Union{}
timestamp_positions(ts, i::Union{AbstractString, VecStr}) -> Union{}
timestamp_positions(ts::Nothing, i::Union{Dates.AbstractTime, VecDate}) -> Union{}
timestamp_positions(ts::AbstractVector, i::Dates.AbstractTime) -> Vector{Int}
timestamp_positions(ts::AbstractVector, i::VecDate) -> Vector{Int}

Turn the timestamps that select observations in a view of a ReturnsResult or of a PricesResult into the positions of those observations.

port_opt_view of a ReturnsResult calls it on its observation index, so a caller can select the observations by timestamp or by position. The integer view of a PricesResult calls it on its integer index, and the timestamp view of a PricesResult calls it through clock_selection. An integer vector, a range and a Colon pass through unchanged.

A vector of timestamps selects the observations that the clock holds, as the timestamp view of a PricesResult does. The rows come back in clock order whatever the order of i, and a timestamp that the clock does not hold selects no row. So a calendar range selects the trading days inside it. A window that keeps no row is refused by the ReturnsResult constructor, which refuses empty returns.

One timestamp selects the one observation at that timestamp, and it gives a vector of one position. One integer n gives the range n:n. So the view keeps its matrix shape, as a vector of one timestamp does. A timestamp that the clock does not hold is refused, because one timestamp names one observation and not a window. One Bool is refused, for the reason that label_positions gives.

The timestamps of i must compare with ts. assert_timestamp_type checks their types, so a DateTime selector of zoned timestamps raises an error that names i. When the element type of a vector i is abstract, such as Dates.AbstractTime, the check of that type passes, so the function also checks the type of each entry.

Algorithm

The method that Julia selects is the algorithm.

  1. i is not an integer, not a timestamp, not a vector of timestamps, not a name and not a vector of names: return it unchanged.
  2. i is one Bool: throw.
  3. i is one integer n: return n:n.
  4. i is a name or a vector of names: throw. A name selects an asset or a factor, and this index selects observations.
  5. i is a timestamp or a vector of timestamps, and ts is nothing: throw. The returns carry no timestamps to match.
  6. i is a timestamp: check its type, and keep the positions of ts that equal i. Throw when no position equals i.
  7. i is a vector of timestamps: check its element type. When that type is abstract, check the type of each entry. Sort i, and keep the position of each timestamp of ts that the sorted vector holds, with insorted.

Arguments

  • ts: The timestamps of the returns or of the prices, or nothing.
  • i: The observation index of the view: a timestamp, a vector of timestamps, one integer, integer positions, a range or a Colon.

Validation

  • i is not one Bool. Raises an ArgumentError.
  • i is not a name and not a vector of names. Raises an ArgumentError.
  • ts is not nothing when i is a timestamp or a vector of timestamps. Raises an ArgumentError.
  • The timestamps of i compare with ts, and so does each entry of a vector i whose element type is abstract. Raises an ArgumentError. See assert_timestamp_type.
  • ts holds the timestamp i, when i is one timestamp. Raises an ArgumentError.

Returns

  • idx: i unchanged, the range i:i of one integer, or the positions in ts of the timestamps that i holds, in clock order.

Related

source
PortfolioOptimisers.clock_selection — Function
clock_selection(ts::AbstractVector{T}, i::Vector{T}) where {T <: Dates.AbstractTime} -> Vector{T}
clock_selection(ts::AbstractVector, i::VecDate) -> AbstractVector

Give the timestamps that index a TimeArray whose clock is ts, for the observation index i of a view of a PricesResult.

getindex of a TimeArray takes only a Vector in the element type of its timestamps. It keeps the timestamps that the clock holds, in clock order. A Vector in that type therefore indexes the TimeArray as it is, and the type check of timestamp_positions has nothing to refuse. The integer view of a PricesResult and the price filters pass such a Vector. A search through timestamp_positions would only repeat the match of getindex, at up to twice the cost of the view. Another element type, a view or a range goes through timestamp_positions, which checks the type and matches across it. So a Date window of DateTime prices selects the observations at midnight.

Algorithm

The method that Julia selects is the algorithm.

  1. i is a Vector in the element type of ts: return i.
  2. Otherwise: find the positions of ts that i selects with timestamp_positions, and return the timestamps of ts at them.

Arguments

  • ts: The timestamps of the asset prices, the clock of the view.
  • i: The timestamps that select the observations of the view.

Validation

  • The timestamps of i compare with ts, outside of step 1. Raises an ArgumentError. See assert_timestamp_type.

Returns

  • The timestamps that index the TimeArray: i itself in step 1, and the timestamps of ts that i selects otherwise.

Related

source
PortfolioOptimisers.each_panel_field — Function
each_panel_field(pnl::AssetPanel{Nothing}) -> Tuple{}
each_panel_field(pnl::AssetPanel) -> AbstractVector{<:AbstractPanelField}

Give the Panel Fields of an AssetPanel for a loop or a comprehension that reports over them.

A panel that states its two masks alone holds pf = nothing, and nothing is not iterable. A report over the fields of such a panel, such as a coverage table or a count, has zero rows, so the function gives the empty tuple and the loop runs no iteration. The panel itself never stores an empty container.

Algorithm

The method that Julia selects is the algorithm.

  1. The panel holds no Panel Field: return ().
  2. Otherwise: return pnl.pf.

Arguments

  • pnl: The Asset Panel.

Returns

  • pf: The Panel Fields, or ().

Related

source