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
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, ornothing.mat: The returns matrix,observations × columns, ornothing.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), whenevernamesis notnothing. Raises anArgumentError.If either
namesormatis notnothing:!isnothing(names)and!isnothing(mat). Raises anIsNothingError.!isempty(names)and!isempty(mat). Raises anIsEmptyError.length(names) == size(mat, 2). Raises aDimensionMismatch.
Returns
nothing.
Related
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, ornothing.E: The Exogenous Series,observations × series, ornothing.X: The asset returns, ornothing.F: The factor returns, ornothing.ts: The timestamps, ornothing.
Validation
- The rules of
check_names_and_returns_matrixforneandE. - When
Eis given,size(E, 1)equals the row count of each ofXandFthat is given, andlength(ts)whentsis given. Raises aDimensionMismatch.
Returns
nothing.
Related
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 theReturnsResult, ornothing.
Validation
!isnothing(pnl). Raises anIsNothingError.
Returns
pnl::AssetPanel: The Asset Panel.
Related
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
- Take the vector benchmark when
x_srcisExcessSourceandrd.Bis a vector, seeshared_benchmark, and the factor returns whenrfistrue. - Return
nothingwhen each of them is absent or finite at every observation. - 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,nothingor anAbstractReturnsSource. OnlyExcessSourcereads the benchmark: it subtractsBfrom the asset returns. An optimiser passes the source of its group, seegroup_source.rf:truewhen the fit reads the factor returns ofrd.
Returns
rows::Option{Vector{Int}}: The positions of the kept observations, empty when every observation has a gap, ornothingwhen the fit keeps every observation.
Related
PortfolioOptimisers.shared_benchmark — Function
shared_benchmark(B::VecNum, x_src::ExcessSource) -> VecNum
shared_benchmark(B, x_src::Option{<:AbstractReturnsSource}) -> NothingReturn 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.
- A vector benchmark under
ExcessSource: returnB. - 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 ofrd.x_src: The source of the returns that the fit reads,nothingor anAbstractReturnsSource. OnlyExcessSourcereads the benchmark: it subtractsBfrom the asset returns. An optimiser passes the source of its group, seegroup_source.
Returns
b::Option{<:VecNum}: The vector benchmark, ornothing.
Related
PortfolioOptimisers.shared_series_complete — Function
shared_series_complete(A::Nothing) -> Bool
shared_series_complete(A::VecNum_MatNum) -> BoolAnswer true when a Shared Series is absent, or finite at every observation.
Related
PortfolioOptimisers.shared_row_finite — Function
shared_row_finite(A::Nothing, t::Integer) -> Bool
shared_row_finite(A::VecNum, t::Integer) -> Bool
shared_row_finite(A::MatNum, t::Integer) -> BoolAnswer true when a Shared Series is absent, or finite at observation t. A matrix is finite at t when each of its columns is.
Related
PortfolioOptimisers.shared_series_length — Function
shared_series_length(b::VecNum, F::Option{<:MatNum}) -> Int
shared_series_length(b::Nothing, F::MatNum) -> IntReturn the number of observations of the Shared Series that shared_series_rows scans.
Related
PortfolioOptimisers.shared_series_view — Function
shared_series_view(rd::ReturnsResult, x_src::Option{<:AbstractReturnsSource}, rf::Bool)
-> ReturnsResultReturn 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
- Find the kept observations with
shared_series_rows. - View
rdat them, and refresh the estimation mask, withshared_series_cut.
Arguments
rd: The returns result to use.x_src: The source of the returns that the fit reads,nothingor anAbstractReturnsSource. OnlyExcessSourcereads the benchmark: it subtractsBfrom the asset returns. An optimiser passes the source of its group, seegroup_source.rf:truewhen the fit reads the factor returns ofrd.
Validation
- At least one observation is kept. An
IsEmptyErroris thrown otherwise.
Returns
rd::ReturnsResult:rditself 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.6Related
PortfolioOptimisers.shared_series_cut — Function
shared_series_cut(rd::ReturnsResult, x_src::Option{<:AbstractReturnsSource},
rows::Option{<:VecInt}) -> ReturnsResultReturn 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,nothingor anAbstractReturnsSource. OnlyExcessSourcereads the benchmark: it subtractsBfrom the asset returns. An optimiser passes the source of its group, seegroup_source.rows: The positions of the kept observations, ornothingwhen the fit keeps every observation.
Validation
- At least one observation is kept. An
IsEmptyErroris thrown otherwise.
Returns
rd::ReturnsResult:rditself whenrowsisnothingand no estimation mask changes, and otherwise its view.
Related
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.
rowsisnothing: returnest, because the fit keeps every observation.rowsis a vector: mark the kept observations in a mask ofTentries, and cutestwithobs_weights_viewat the mask. Each weights field goes throughobs_weights_index, which checks that a weight vector hasTentries.
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, fromshared_series_rows, ornothing.T: The number of observations of the full sample.
Validation
- Each fixed weight vector in the tree of
esthasTentries, asobserved_weightschecks. ADimensionMismatchthat nameswis 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.0Related
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
- Find the kept observations with
shared_series_rows. - When it keeps every observation, return
estand the data ofshared_series_cut. - Otherwise count the observations of the Shared Series, cut
estwithshared_series_estimator, and cutrdwithshared_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,nothingor anAbstractReturnsSource. OnlyExcessSourcereads the benchmark: it subtractsBfrom the asset returns. An optimiser passes the source of its group, seegroup_source.rf:truewhen the fit reads the factor returns ofrd.
Validation
- The rules of
shared_series_cutandshared_series_estimator.
Returns
est: The estimator at the kept observations.rd::ReturnsResult: The returns data at the kept observations.
Related
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,nothingor anAbstractReturnsSource. OnlyExcessSourcereads the benchmark: it subtractsBfrom the asset returns. An optimiser passes the source of its group, seegroup_source.rf:truewhen the fit reads the factor returns ofrd.
Returns
gaps::Option{BitVector}: One mark for each observation ofrd,trueat an observation with a gap, ornothingwhen no observation has one.
Related
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.
- No marks: return
rd. - Marks: return
nothingwhen every observation is marked, and the view ofrdat the unmarked observations otherwise.
Arguments
rd: The returns result to use.gaps: One mark for each observation ofrd,trueat an observation with a Shared Series gap, ornothing.
Returns
rd::Option{ReturnsResult}: The observations with no mark, ornothingwhen the step has none.
Related
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}}) -> ReturnsResultMark 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.
x_srcis notExcessSource, the benchmark is not a matrix, or the panel carries no mask: returnrd.- Return
rdwhen the benchmark is finite at every cell. - Otherwise set the estimation mask to
emsk .& isfinite.(B), and rebuildrdwith that panel.
Arguments
rd: The returns result to use.x_src: The source of the returns that the fit reads,nothingor anAbstractReturnsSource. OnlyExcessSourcereads the benchmark: it subtractsBfrom the asset returns. An optimiser passes the source of its group, seegroup_source.B: The benchmark ofrd.pnl: The Asset Panel ofrd.
Returns
rd::ReturnsResult:rditself, orrdwith the refreshed estimation mask.
Related