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.
pnlisnothing, or static: returnColon(). Neither has an observation axis, so the function reads no timestamp.pnlis time-varying: matchts_newintots_oldwithmatched_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, ornothing.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_newis notnothing. Raises anArgumentError.- Every entry of
ts_newappears ints_old. Raises anArgumentError.
Returns
rows::Union{Colon, Vector{Int}}:Colon()for a static or absent panel. Otherwise the position of each surviving timestamp ints_old, in the order ofts_new.
Related
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.
ts_newisnothing: throw. The selection kept no timestamp, so the function cannot name the rows to keep.- Otherwise match
ts_newintots_oldwithindexin, givingrows. A timestamp that appears twice ints_oldmatches its first position. - Find the first entry of
rowsthatindexindid not match, givingmissed, and throw when there is one. - Return
rowsas aVector{Int}.
Arguments
ts_new: The timestamps that survived the selection.ts_old: The timestamps of the clock that the observation axis follows.
Validation
ts_newis notnothing. Raises anArgumentError.- Every entry of
ts_newappears ints_old. Raises anArgumentError.
Returns
rows::Vector{Int}: The position of each surviving timestamp ints_old, in the order ofts_new. An emptyts_newgives an empty vector.
Related
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.
pnlisnothing, or a panel with no Panel Field: returnnothing.pnlis anAssetPanelwith Panel Fields: read them in order intonz. 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, ornothing.
Returns
nz::Option{Vector{String}}: One name per derived column, in the column order ofpanel_feature_matrix, ornothingwhen there is no Panel Field.
Related
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.
selis not an integer, not a name, not a vector of names, not a timestamp and not a vector of timestamps: return it unchanged.selis oneBool: throw.selis one integern: returnn:n.selis a timestamp or a vector of timestamps: throw. A timestamp selects an observation, and this index selectswhat.selis a name or a vector of names, andnamesisnothing: throw. The input data carries no names to match.selis a name or a vector of names: put one name in a vector of one name. Match the vector intonameswithindexin, giving the positions. Throw when a name has no match, and name every such entry.
Arguments
names: The names of the axis thatselselects, ornothing.sel: The index of the view: one name or a vector of names, one integer or a vector of integer positions, a range or aColon.what: The name of the axis, such as"asset", for the messages.
Validation
selis not oneBool. Raises anArgumentError.selis not a timestamp and not a vector of timestamps. Raises anArgumentError.namesis notnothingwhenselis a name or a vector of names. Raises anArgumentError.- Every name of
selis innames. Raises anArgumentError.
Returns
idx:selunchanged, the rangesel:selof one integer, or the position of each name ofselinnames, in the order ofsel.
Related
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) -> NothingCheck 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.
TandSare bothDateorDateTime: returnnothing. Dates promotes the pair.SisNothing: returnnothing. No timestamp is given.- 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 <: SorS <: T, outside of the two cases above. Raises anArgumentErrorthat namessym,SandT.
Returns
nothing.
Related
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.
iis not an integer, not a timestamp, not a vector of timestamps, not a name and not a vector of names: return it unchanged.iis oneBool: throw.iis one integern: returnn:n.iis a name or a vector of names: throw. A name selects an asset or a factor, and this index selects observations.iis a timestamp or a vector of timestamps, andtsisnothing: throw. The returns carry no timestamps to match.iis a timestamp: check its type, and keep the positions oftsthat equali. Throw when no position equalsi.iis a vector of timestamps: check its element type. When that type is abstract, check the type of each entry. Sorti, and keep the position of each timestamp oftsthat the sorted vector holds, withinsorted.
Arguments
ts: The timestamps of the returns or of the prices, ornothing.i: The observation index of the view: a timestamp, a vector of timestamps, one integer, integer positions, a range or aColon.
Validation
iis not oneBool. Raises anArgumentError.iis not a name and not a vector of names. Raises anArgumentError.tsis notnothingwheniis a timestamp or a vector of timestamps. Raises anArgumentError.- The timestamps of
icompare withts, and so does each entry of a vectoriwhose element type is abstract. Raises anArgumentError. Seeassert_timestamp_type. tsholds the timestampi, wheniis one timestamp. Raises anArgumentError.
Returns
idx:iunchanged, the rangei:iof one integer, or the positions intsof the timestamps thatiholds, in clock order.
Related
PortfolioOptimisers.clock_selection — Function
clock_selection(ts::AbstractVector{T}, i::Vector{T}) where {T <: Dates.AbstractTime} -> Vector{T}
clock_selection(ts::AbstractVector, i::VecDate) -> AbstractVectorGive 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.
iis aVectorin the element type ofts: returni.- Otherwise: find the positions of
tsthatiselects withtimestamp_positions, and return the timestamps oftsat 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
icompare withts, outside of step 1. Raises anArgumentError. Seeassert_timestamp_type.
Returns
- The timestamps that index the
TimeArray:iitself in step 1, and the timestamps oftsthatiselects otherwise.
Related
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.
- The panel holds no Panel Field: return
(). - Otherwise: return
pnl.pf.
Arguments
pnl: The Asset Panel.
Returns
pf: The Panel Fields, or().
Related