Prices result

Types

A new type of price data subtypes AbstractPricesResult, has the fields X and pnl, and adds a method of port_opt_view.

PortfolioOptimisers.AbstractPricesResult — Type
abstract type AbstractPricesResult <: AbstractResult

Abstract supertype for all price-level data result types.

Every concrete type that holds price-level data subtypes AbstractPricesResult. PricesResult is the member the library builds. The fold generation of cross-validation, the pipeline and the price-level preprocessing steps dispatch on this supertype, as they dispatch on AbstractReturnsResult for returns-level data. No check enforces the interface below.

Interfaces

To implement a new price-level data type that a pipeline and a cross-validation fold can read, subtype AbstractPricesResult with these fields:

  • X: The asset prices, a TimeSeries.TimeArray of observations × assets. Fold generation reads its timestamps and its row count, and asset subset sampling reads its column count.
  • pnl: An AssetPanel over the assets of X, or nothing. Fold generation reads it together with X to find the assets that hold data.

Then implement the following method:

port_opt_view

  • port_opt_view(pr::MyPricesResult, i, j = :) -> MyPricesResult: Return pr on the observations at i and the assets at j.

A subtype that carries a panel subselects it together with X. A subtype that implements no method gets the fallback, which throws an ArgumentError.

Arguments

  • pr: The price-level data of the new type.
  • i: Indices or timestamps of the observations to keep.
  • j: Indices of the assets to keep.

Returns

  • pr::MyPricesResult: A value of the same type that holds only the selected observations and assets.

Related

source
PortfolioOptimisers.PricesResult — Type
struct PricesResult{__T_X, __T_F, __T_B, __T_E, __T_iv, __T_ivpa, __T_pnl, __T_span} <: AbstractPricesResult

Holds asset prices with optional factor, benchmark, Exogenous Series and implied volatility series, each a TimeSeries.TimeArray.

It is the price-level counterpart of ReturnsResult. The price-level preprocessing steps and prices_to_returns take it as input, and port_opt_view cuts it into the timestamp windows of pipeline cross-validation.

The asset price series X is the master clock. port_opt_view selects observation windows on X, and each other series keeps its rows at the timestamps that X keeps.

The Exogenous Series E holds level series that belong to no asset, for example a Currency Excess Index. price_ingestion aligns it by timestamp to the clock of X, and prices_to_returns converts it with the return rule of the assets. Its column names are the names that ReturnsResult carries in ne.

The AssetPanel pnl and the Listing Span span hold no timestamps, so no timestamp aligns them. A Panel Field can be a 3-dimensional array, a static panel has no observation axis, and a span can be two integers per asset. Their axes run parallel to X by position instead. The asset axis follows TimeSeries.colnames(X), and the observation axis of a time-varying panel follows TimeSeries.timestamp(X) row for row. A routine that drops an asset or an observation from X must drop it from pnl and span in the same step. port_opt_view does this: it views the panel with its own method, and the span with listing_span_view, and MissingDataFilter and prices_to_returns do it too.

Fields

  • X: Asset prices, observations × assets. It is the master clock of every timestamp window.
  • F: Optional factor prices, observations × factors.
  • B: Optional benchmark prices, observations × 1 or observations × assets.
  • E: Optional Exogenous Series, observations × series: level series that belong to no asset, such as a Currency Excess Index. prices_to_returns converts them to the Exogenous Series of the ReturnsResult.
  • iv: Optional implied volatilities, observations × assets. An absent value is NaN, and ImpliedVolatility removes the asset from its fit.
  • ivpa: Implied volatility risk premium adjustment, a positive number that every asset shares, or a vector of positive numbers with one entry per asset.
  • pnl: Optional AssetPanel that holds the Panel Fields of the universe and its two universe masks. It is not a TimeArray, and its axes run parallel to X by position.
  • span: Optional Listing Span, observations × assets, that states which assets are listed at each observation of the price clock. Its axes run parallel to X by position. It is a PortfolioOptimisers.ListingSpan when PriceIngestion derives it by the Span Rule, and any other AbstractMatrix{Bool} when a caller states their own listing calendar. It is nothing when the ingestion layer did not build the PricesResult.

Constructors

PricesResult(;    X::TimeSeries.TimeArray,    F::Option{<:TimeSeries.TimeArray} = nothing,    B::Option{<:TimeSeries.TimeArray} = nothing,    E::Option{<:TimeSeries.TimeArray} = nothing,    iv::Option{<:TimeSeries.TimeArray} = nothing,    ivpa::Option{<:Num_VecNum} = nothing,    pnl::Option{<:AssetPanel} = nothing,    span::Option{<:AbstractMatrix{Bool}} = nothing,) -> PricesResult

Keywords correspond to the struct's fields.

PricesResult is an entry point of integer data. A time array X, F, B, E or iv with an integer element type converts once to its floating-point type through float_if_integer, so every kernel downstream reads floating-point data. Every other element type stays.

Validation

  • !isempty(X), and allunique(TimeSeries.timestamp(X)).
  • If F is not nothing: !isempty(F).
  • If B is not nothing: !isempty(B), and size(values(B), 2) in (1, size(values(X), 2)).
  • If E is not nothing: !isempty(E).
  • If iv is not nothing: !isempty(iv), size(values(iv), 2) == size(values(X), 2), and every present value is finite and non-negative. An absent value is NaN, or missing on a PricesResult built by hand. See assert_nonneg_where_present.
  • If ivpa is not nothing: !isempty(ivpa), all(isfinite, ivpa) and all(x -> x > 0, ivpa). If ivpa is a vector: length(ivpa) == size(values(X), 2).
  • If pnl is not nothing: its asset axis has the length size(values(X), 2), and the observation axis of a time-varying panel has the length size(values(X), 1). See check_asset_panel.
  • If span is not nothing: size(span) == size(values(X)).

An empty series or an empty ivpa raises an IsEmptyError. A repeated timestamp raises an ArgumentError. A wrong width or a wrong shape raises a DimensionMismatch. A value outside its domain raises a DomainError.

Examples

julia> X = TimeArray(Date(2020, 1, 1):Day(1):Date(2020, 1, 3),                     [100.0 101.0; 102.0 103.0; 104.0 105.0], ["A", "B"]);julia> pr = PricesResult(; X = X);julia> size(values(pr.X))(3, 2)

Related

source

Functions

PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    pr::PricesResult,
    _::Colon,
    _::Colon
) -> PricesResult

Return the PricesResult on the observation window i and the assets j of the asset price series X.

Indexing a TimeArray copies its rows, so X, F, B, E and iv of the result are copies. ivpa, the Asset Panel and the Listing Span of the result can share memory with pr, and the call with two Colons returns pr itself.

The asset price series is the master clock. i selects rows of X, and the factor, benchmark, Exogenous Series and implied volatility series keep their rows at the timestamps that X keeps. The rows come back in clock order whatever the order of i, and a timestamp of i that X does not hold selects no row. j selects asset columns in the order it gives them, and its default is :. So a call that gives only i is an observation window over the whole universe.

The timestamps of i must compare with the timestamps of X, see assert_timestamp_type. A Date window of DateTime prices selects the observations at midnight. A DateTime window of zoned prices is refused with an error that names i.

The first index selects observations here. The two-argument method of ReturnsResult selects assets, so i names a different axis on the two types.

Algorithm

The method that Julia selects is the algorithm. The timestamp methods do the work, and the integer method sends the call to them.

  1. i and j are both Colon: return pr itself. No view is built.

  2. i is a vector of timestamps and j is a Colon: give i in a form that indexes X, with clock_selection. A Vector in the element type of the timestamps of X passes as it is, and another type goes through timestamp_positions. Then index X, F, B, E and iv by the timestamps i. Recover the rows of a time-varying Asset Panel from the kept timestamps with feature_row_indices, and view the panel on that observation axis with port_opt_view. A static panel has no observation axis and ignores the row index. View the Listing Span at the same timestamps with listing_span_view. Pass ivpa through unchanged, because the asset index does not reach it. Rebuild the PricesResult.

  3. i is a vector of timestamps and j is one asset position, one asset name, or a vector of asset positions or asset names:

    1. Replace i with the timestamps of X that it selects, as in step 2. Resolve the asset names of j to positions in the column names of X with label_positions. One position n becomes n:n, and one name becomes a vector of one position, so the view keeps its matrix shape. Positions pass through.
    2. Index X by the timestamps i, then keep the asset columns j.
    3. Index F and E by the timestamps i alone. j is an asset index, and the factors and the Exogenous Series are separate axes, so every column of each stays.
    4. Index B by the timestamps i. Keep its columns j when B holds one column per asset, and keep its single column otherwise. The test reads the width of B, because a shared benchmark has only one column to give.
    5. Index iv by the timestamps i and the asset columns j, and view ivpa at j.
    6. Recover the rows of a time-varying Asset Panel with feature_row_indices. View the panel at those rows and the assets j with port_opt_view, and give it the asset names. It then also cuts the label axis of a tensor Panel Field whose labels are the asset names, see features_are_assets.
    7. View the Listing Span at the kept timestamps and the assets j with listing_span_view.
    8. Rebuild the PricesResult.
  4. i is one integer, integer indices, a range, a Colon or one timestamp, and j is one integer, one asset name, integer indices, a range, a Colon or asset names: find the positions of i with timestamp_positions, read the timestamps of X at them, and call step 2 or step 3 with them. One integer n gives the positions n:n, and one timestamp gives the position of the one observation at it. A call such as port_opt_view(pr, 2:3) reaches this method. A timestamp or a vector of timestamps in j reaches it too, and step 3 refuses it with the message of label_positions, as the view of a ReturnsResult does.

  5. Any other call on an AbstractPricesResult: throw an ArgumentError that names the type of each index argument, the keyword arguments, and the two call shapes of the interface. A call with three indices or with a keyword argument reaches this step. So does a subtype that implements no method.

Arguments

  • pr: A PricesResult object.
  • i: Observation window into the rows of pr.X. Either integer positions (one Integer, an AbstractVector{<:Integer}, an AbstractRange, or a Colon), or timestamps (one Dates.AbstractTime, or an AbstractVector{<:Dates.AbstractTime}). One integer and one timestamp select one observation, and the view keeps its matrix shape.
  • j: Asset window into the columns of pr.X. One integer, integer indices, an AbstractRange, one asset name, a vector of asset names, or Colon for the whole universe. One integer and one name select one asset, and the view keeps its matrix shape. A Colon keeps every asset column of X, B and iv, and passes ivpa through unchanged.

Validation

  • A window that keeps no row raises the IsEmptyError of the PricesResult constructor.
  • The timestamps of i compare with the timestamps of X. Raises an ArgumentError. See assert_timestamp_type.
  • X holds the timestamp i, when i is one timestamp. Raises an ArgumentError. See timestamp_positions.
  • Every asset name of j is a column name of X. Raises an ArgumentError. See label_positions.
  • A call shape that step 5 takes raises an ArgumentError.

Returns

  • new_pr::PricesResult: The price data on the selected observations and assets. It is pr itself when i and j are both Colons.

Examples

julia> X = TimeArray(Date(2020, 1, 1):Day(1):Date(2020, 1, 3),                     [100.0 101.0; 102.0 103.0; 104.0 105.0], ["A", "B"]);julia> pr = PricesResult(; X = X);julia> pv = PortfolioOptimisers.port_opt_view(pr, 2:3);julia> first(timestamp(pv.X))2020-01-02julia> size(values(pv.X))(2, 2)julia> colnames(PortfolioOptimisers.port_opt_view(pr, 2:3, ["B"]).X)1-element Vector{Symbol}: :B

Related

source