Returns result: private API

Types

PortfolioOptimisers.Prices_RR — Type
const Prices_RR = Union{AbstractReturnsResult, AbstractPricesResult}

Union of the two data levels cross-validation folds can be computed on: returns-level (AbstractReturnsResult) and price-level (AbstractPricesResult) data.

Fold generation needs only an observation count, from cv_nobs, and a timestamp vector, from cv_timestamps. So Base.split and n_splits accept either level. A split at the price level lets a Pipeline be cross-validated on its input rows, so its stateful preprocessing stays inside the fold.

Related

source

Functions

PortfolioOptimisers.check_names_and_returns_matrix — Function
check_names_and_returns_matrix(
    names::Union{Nothing, AbstractVector{<:AbstractString}},
    mat::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    names_sym::Symbol,
    mat_sym::Symbol
)

Check that a list of column names and the returns matrix it names are both given or both nothing, and that they agree in size.

ReturnsResult calls it for the asset, factor, benchmark and Exogenous Series pairs.

Arguments

  • names: The column names, or nothing.
  • mat: The returns matrix, observations × columns, or nothing.
  • names_sym: The name of the names argument, which the error messages print.
  • mat_sym: The name of the matrix argument, which the error messages print.

Validation

  • allunique(names), whenever names is not nothing. Raises an ArgumentError.

  • If either names or mat is not nothing:

    • !isnothing(names) and !isnothing(mat). Raises an IsNothingError.
    • !isempty(names) and !isempty(mat). Raises an IsEmptyError.
    • length(names) == size(mat, 2). Raises a DimensionMismatch.

Returns

  • nothing.

Related

source
PortfolioOptimisers.check_exogenous_series — Function
check_exogenous_series(
    ne::Union{Nothing, AbstractVector{<:AbstractString}},
    E::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    X::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    F::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    ts::Union{Nothing, AbstractVector{<:Dates.AbstractTime}}
)

Check the Exogenous Series of a ReturnsResult against its names and against the other series of the observation axis.

The Exogenous Series shares the observation axis with the asset, factor and benchmark returns, so it has their row count and one row per timestamp. It has no asset axis, so nothing else constrains it.

Arguments

  • ne: The names of the Exogenous Series, or nothing.
  • E: The Exogenous Series, observations × series, or nothing.
  • X: The asset returns, or nothing.
  • F: The factor returns, or nothing.
  • ts: The timestamps, or nothing.

Validation

  • The rules of check_names_and_returns_matrix for ne and E.
  • When E is given, size(E, 1) equals the row count of each of X and F that is given, and length(ts) when ts is given. Raises a DimensionMismatch.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_asset_panel_supplied — Function
assert_asset_panel_supplied(pnl::AssetPanel) -> AssetPanel
assert_asset_panel_supplied(pnl::Nothing) -> Union{}

Assert that the ReturnsResult that a FeatureDistance read holds an AssetPanel, and return it.

The pnl of a ReturnsResult is optional, so a ReturnsResult built without one gives nothing. This function turns that nothing into an error message. It returns the panel, so the caller makes one call for the check and the access.

Algorithm

The method that Julia selects is the algorithm. A panel returns itself, and nothing raises.

Arguments

  • pnl: The Asset Panel of the ReturnsResult, or nothing.

Validation

Returns

  • pnl::AssetPanel: The Asset Panel.

Related

source
PortfolioOptimisers.shared_series_rows — Function
shared_series_rows(rd::ReturnsResult, x_src::Option{<:AbstractReturnsSource}, rf::Bool)
    -> Option{Vector{Int}}

Find the observations of rd that a fit keeps when a Shared Series has a gap.

A Shared Series is a series that every asset reads at the same observation: a vector benchmark under ExcessSource, and each column of the factor returns of a fit that reads them. A gap in the series of one asset puts that asset outside the Coverage Universe, as coverage_mask states. A gap in a Shared Series at observation t leaves no asset a value at t: an excess return or a factor regression needs the shared value. So the fit drops observation t and keeps every asset. The drop removes no value that an asset still had.

The function reads a vector benchmark only under ExcessSource, and the factor returns only under rf, because a fit that does not read a series meets none of its gaps. An optimiser passes the source of its group, see group_source, so a raw reader of a group that reads the Excess Frame loses the same observations. A matrix benchmark is a series of one asset at each column, so its gaps go through benchmark_estimation_mask and the Coverage Universe, never through this function.

Algorithm

  1. Take the vector benchmark when x_src is ExcessSource and rd.B is a vector, see shared_benchmark, and the factor returns when rf is true.
  2. Return nothing when each of them is absent or finite at every observation.
  3. Otherwise keep each observation at which the benchmark is finite and every factor is finite.

Arguments

  • rd: The returns result to use.
  • x_src: The source of the returns that the fit reads, nothing or an AbstractReturnsSource. Only ExcessSource reads the benchmark: it subtracts B from the asset returns. An optimiser passes the source of its group, see group_source.
  • rf: true when the fit reads the factor returns of rd.

Returns

  • rows::Option{Vector{Int}}: The positions of the kept observations, empty when every observation has a gap, or nothing when the fit keeps every observation.

Related

source
PortfolioOptimisers.shared_benchmark — Function
shared_benchmark(B::VecNum, x_src::ExcessSource) -> VecNum
shared_benchmark(B, x_src::Option{<:AbstractReturnsSource}) -> Nothing

Return the benchmark of rd that is a Shared Series of the fit: a vector benchmark under ExcessSource, and nothing otherwise.

Algorithm

The method that Julia selects is the algorithm.

  1. A vector benchmark under ExcessSource: return B.
  2. Any other benchmark, or any other source: return nothing. A matrix benchmark is a series of one asset at each column, and a fit at another source does not read the benchmark.

Arguments

  • B: The benchmark of rd.
  • x_src: The source of the returns that the fit reads, nothing or an AbstractReturnsSource. Only ExcessSource reads the benchmark: it subtracts B from the asset returns. An optimiser passes the source of its group, see group_source.

Returns

  • b::Option{<:VecNum}: The vector benchmark, or nothing.

Related

source
PortfolioOptimisers.shared_series_view — Function
shared_series_view(rd::ReturnsResult, x_src::Option{<:AbstractReturnsSource}, rf::Bool)
    -> ReturnsResult

Return the returns data that a fit reads, with the observations of a Shared Series gap dropped.

This is the entry of each fit that reads a Shared Series. shared_series_rows finds the observations to keep, and port_opt_view cuts every field of rd at them: the asset returns, the factor returns, the benchmark, the Exogenous Series, the timestamps, the implied volatilities and the AssetPanel. So every reader after the entry sees the same observations. A reader that pairs the observations of a prior with the last observations of the returns data stays correct, because the prior and the reader read the same view.

Under ExcessSource, benchmark_estimation_mask then marks a gap of a matrix benchmark in the estimation mask, because the excess return of that cell does not exist.

An optimiser calls the function one time, before the solve, with the source of its group, see group_source. A prior, a regression and an uncertainty set that receive the returns data call it with their own source, and the view of the optimiser has no gap left for them.

The function is idempotent. A view with no gap left returns itself, so a meta-optimiser and the optimiser it nests can each call it.

The positions of the row key of a factor model block count the observations of the view, and its timestamps name them exactly.

Algorithm

  1. Find the kept observations with shared_series_rows.
  2. View rd at them, and refresh the estimation mask, with shared_series_cut.

Arguments

  • rd: The returns result to use.
  • x_src: The source of the returns that the fit reads, nothing or an AbstractReturnsSource. Only ExcessSource reads the benchmark: it subtracts B from the asset returns. An optimiser passes the source of its group, see group_source.
  • rf: true when the fit reads the factor returns of rd.

Validation

  • At least one observation is kept. An IsEmptyError is thrown otherwise.

Returns

  • rd::ReturnsResult: rd itself when the fit meets no gap, and otherwise its view.

Examples

julia> rd = ReturnsResult(; nx = ["A", "B"], X = [0.1 0.2; 0.3 0.4; 0.5 0.6], nb = ["BM"],                          B = [0.01, NaN, 0.03]);julia> PortfolioOptimisers.shared_series_view(rd, DataSource(), false) === rd  # no benchmark readtruejulia> PortfolioOptimisers.shared_series_view(rd, ExcessSource(), false).X2×2 view(::Matrix{Float64}, [1, 3], :) with eltype Float64: 0.1  0.2 0.5  0.6

Related

source
PortfolioOptimisers.shared_series_cut — Function
shared_series_cut(rd::ReturnsResult, x_src::Option{<:AbstractReturnsSource},
                  rows::Option{<:VecInt}) -> ReturnsResult

Return the returns data at the observations rows that a fit keeps, with the estimation mask of a matrix benchmark refreshed.

This is the second half of shared_series_view. A caller that finds the kept observations by another rule, and needs them after the cut, passes them here. An optimiser does so, because it also drops the observations that the record of its prior result marks, and it maps the prior that it fits back through the same rows, see shared_series_solve.

Arguments

  • rd: The returns result to use.
  • x_src: The source of the returns that the fit reads, nothing or an AbstractReturnsSource. Only ExcessSource reads the benchmark: it subtracts B from the asset returns. An optimiser passes the source of its group, see group_source.
  • rows: The positions of the kept observations, or nothing when the fit keeps every observation.

Validation

  • At least one observation is kept. An IsEmptyError is thrown otherwise.

Returns

  • rd::ReturnsResult: rd itself when rows is nothing and no estimation mask changes, and otherwise its view.

Related

source
PortfolioOptimisers.shared_series_estimator — Function
shared_series_estimator(est, rows::Nothing, T::Integer) -> typeof(est)
shared_series_estimator(est, rows::VecInt, T::Integer)

Return the estimator that a fit reads after a Shared Series gap, with each observation weight of the dropped observations dropped.

shared_series_view drops the observations of a gap from every field of the returns data. An estimator can hold fixed observation weights, one for each observation of the full sample, at any depth of its tree: the weights of a covariance estimator inside a prior inside an optimiser, or the weights of a risk measure. observed_weights states the rule: an observation that the fit drops takes its weight with it, and the kept weights keep their type. So each fit that drops the rows also cuts the estimator that reads them, at the same rows.

A DynamicAbstractWeights keeps its value, because it resolves on the sample that the fit reads, which has no gap left.

Algorithm

The method that Julia selects is the algorithm.

  1. rows is nothing: return est, because the fit keeps every observation.
  2. rows is a vector: mark the kept observations in a mask of T entries, and cut est with obs_weights_view at the mask. Each weights field goes through obs_weights_index, which checks that a weight vector has T entries.

Arguments

  • est: The estimator of the fit: a prior, a regression, an uncertainty set, an optimiser, or a risk measure. Any other value comes back with no change.
  • rows: The positions of the kept observations, from shared_series_rows, or nothing.
  • T: The number of observations of the full sample.

Validation

  • Each fixed weight vector in the tree of est has T entries, as observed_weights checks. A DimensionMismatch that names w is thrown otherwise.

Returns

  • est: The estimator with each fixed weight vector cut to the kept observations.

Examples

julia> ce = Covariance(; w = aweights([1.0, 2.0, 3.0, 4.0]));julia> PortfolioOptimisers.shared_series_estimator(ce, [1, 3, 4], 4).w3-element AnalyticWeights{Float64, Float64, Vector{Float64}}: 1.0 3.0 4.0

Related

source
PortfolioOptimisers.shared_series_fit — Function
shared_series_fit(est, rd::ReturnsResult, x_src::Option{<:AbstractReturnsSource},
                  rf::Bool) -> Tuple{typeof(est), ReturnsResult}

Return the estimator and the returns data that a fit reads, with the observations of a Shared Series gap dropped from both.

This is shared_series_view for a fit that holds an estimator. The data loses the observations of the gap, and every fixed observation weight in the tree of est loses the same observations, through shared_series_estimator. A fit that needs the kept rows after the cut, to record them, calls the three functions itself.

Algorithm

  1. Find the kept observations with shared_series_rows.
  2. When it keeps every observation, return est and the data of shared_series_cut.
  3. Otherwise count the observations of the Shared Series, cut est with shared_series_estimator, and cut rd with shared_series_cut.

Arguments

  • est: The estimator of the fit.
  • rd: The returns result to use.
  • x_src: The source of the returns that the fit reads, nothing or an AbstractReturnsSource. Only ExcessSource reads the benchmark: it subtracts B from the asset returns. An optimiser passes the source of its group, see group_source.
  • rf: true when the fit reads the factor returns of rd.

Validation

Returns

  • est: The estimator at the kept observations.
  • rd::ReturnsResult: The returns data at the kept observations.

Related

source
PortfolioOptimisers.shared_series_gaps — Function
shared_series_gaps(rd::ReturnsResult, x_src::Option{<:AbstractReturnsSource}, rf::Bool)
    -> Option{BitVector}

Mark the observations of rd that have a gap in a Shared Series that the fit reads, for an online step.

A batch fit drops such an observation with shared_series_view. An online step cannot drop the row. An optimiser appends each observation to the buffer of its prior and to its Fold Context together, and optimise(opt) with no data rebuilds the returns data from both, row by row. So the step keeps the row in both, and the prior marks it in its buffer, see SampleBufferState. Every fit through the buffer then drops it with shared_series_buffer, and a carry fold leaves it out of its running moments. The marks are the complement of the rows of shared_series_rows.

Arguments

  • rd: The returns result to use.
  • x_src: The source of the returns that the fit reads, nothing or an AbstractReturnsSource. Only ExcessSource reads the benchmark: it subtracts B from the asset returns. An optimiser passes the source of its group, see group_source.
  • rf: true when the fit reads the factor returns of rd.

Returns

  • gaps::Option{BitVector}: One mark for each observation of rd, true at an observation with a gap, or nothing when no observation has one.

Related

source
PortfolioOptimisers.shared_series_step — Function
shared_series_step(rd::ReturnsResult, gaps::Nothing) -> ReturnsResult
shared_series_step(rd::ReturnsResult, gaps::AbstractVector{Bool}) -> Option{ReturnsResult}

Return the observations of an online step that a carry fold folds, with the observations that gaps marks dropped.

A carry fold computes running moments or histories from each observation. A batch fit drops an observation with a Shared Series gap at its entry, so the carry must not see it, while the buffer beside it keeps the row, see shared_series_gaps. port_opt_view cuts every field of rd at the same observations, as shared_series_view does.

Algorithm

The method that Julia selects is the algorithm.

  1. No marks: return rd.
  2. Marks: return nothing when every observation is marked, and the view of rd at the unmarked observations otherwise.

Arguments

  • rd: The returns result to use.
  • gaps: One mark for each observation of rd, true at an observation with a Shared Series gap, or nothing.

Returns

  • rd::Option{ReturnsResult}: The observations with no mark, or nothing when the step has none.

Related

source
PortfolioOptimisers.benchmark_estimation_mask — Function
benchmark_estimation_mask(rd::ReturnsResult, x_src::ExcessSource) -> ReturnsResult
benchmark_estimation_mask(rd::ReturnsResult, x_src::Option{<:AbstractReturnsSource})
    -> ReturnsResult
benchmark_estimation_mask(rd::ReturnsResult, B::Option{<:VecNum_MatNum},
                          pnl::Option{<:AssetPanel}) -> ReturnsResult
benchmark_estimation_mask(rd::ReturnsResult, B::MatNum,
                          pnl::AssetPanel{<:Any, <:AbstractMatrix{Bool},
                                          <:AbstractMatrix{Bool}}) -> ReturnsResult

Mark each gap of a matrix benchmark in the estimation mask of rd, for a fit that reads the excess returns.

Under ExcessSource the fit reads X - B. A matrix benchmark holds one series for each asset, so a gap in B[t, i] is a gap in the excess return of asset i at observation t, as a gap in X[t, i] is. The NaN of the excess return already puts the asset outside the Coverage Universe of a plain estimator. A reader of the estimation mask, a cross-sectional estimate, reads the mask and not the returns, so the function writes the gap into the mask. The ingestion layer derives the mask from X alone, because a fit at another source does not read B.

Algorithm

The method that Julia selects is the algorithm.

  1. x_src is not ExcessSource, the benchmark is not a matrix, or the panel carries no mask: return rd.
  2. Return rd when the benchmark is finite at every cell.
  3. Otherwise set the estimation mask to emsk .& isfinite.(B), and rebuild rd with that panel.

Arguments

  • rd: The returns result to use.
  • x_src: The source of the returns that the fit reads, nothing or an AbstractReturnsSource. Only ExcessSource reads the benchmark: it subtracts B from the asset returns. An optimiser passes the source of its group, see group_source.
  • B: The benchmark of rd.
  • pnl: The Asset Panel of rd.

Returns

  • rd::ReturnsResult: rd itself, or rd with the refreshed estimation mask.

Related

source