GitHub

Returns Source: private API

PortfolioOptimisers.assert_returns_source — Function
assert_returns_source(x_src::Option{<:AbstractReturnsSource}, admitted::Tuple,
                      reader::Sym_Str, sym::Sym_Str = :x_src) -> Nothing

Assert that a reader of the returns admits its source.

Every reader holds the same field type, so the field type alone admits every value. The keyword constructor of each reader calls this function with the set of values that its family admits, DATA_RETURNS_SOURCES or ALL_RETURNS_SOURCES. The configuration alone decides the refusal, so the constructor refuses before a fit starts.

Arguments

  • 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.
  • admitted: The values of x_src that the reader admits.
  • reader: The name of the reader, for the error message.
  • sym: Symbolic name used in the error message.

Validation

  • x_src in admitted. An ArgumentError that names the field, the reader, the value and the admitted values is thrown otherwise.

Returns

  • nothing.

Examples

julia> PortfolioOptimisers.assert_returns_source(ExcessSource(),                                                 PortfolioOptimisers.DATA_RETURNS_SOURCES,                                                 :EmpiricalPrior) === nothingtrue

Related

source
PortfolioOptimisers.assert_inner_reader — Function
assert_inner_reader(x, field::Sym_Str, holder::Sym_Str) -> Nothing

Assert that a reader in a nesting field states no source of its own.

An inner reader receives a matrix from the estimator that holds it, and not the returns data. Examples are the pe and the re of a prior, and the network estimator of a centrality estimator. The holder reads the returns data and picks the matrix, so only the holder states the source. An inner reader keeps x_src = nothing, which means that the caller stated no source, so the refusal has no ambiguous case. The keyword constructor of the holder calls this function on each nesting field.

Arguments

  • x: The value in the nesting field. A value that is not a reader of the returns passes, see returns_source.
  • field: The name of the nesting field, for the error message.
  • holder: The name of the estimator that holds x, for the error message.

Validation

  • returns_source(x) === nothing. An ArgumentError that names the field and tells the caller to state the source on the holder is thrown otherwise.

Returns

  • nothing.

Related

source
PortfolioOptimisers.ReturnsFrames — Type
ReturnsFrames(excess::Bool, raw::Vector{String})
ReturnsFrames()

The frames that the readers of one group read, as the frame walk finds them.

A group is an optimiser and every reader in its slots, the readers inside its risk measures, constraints, uncertainty sets and losses included. The walk stops at an inner optimiser, a fallback and a leader, because each one is an optimiser with its own group. The walk answers two questions about a group: does a reader state ExcessSource, and which outermost readers state no source and read the raw returns data. warn_raw_readers reads both answers, and group_source reads the first. The constructor with no arguments gives the frames of a value that holds no reader.

Related

source
PortfolioOptimisers.join_path — Function
join_path(path::AbstractString, name) -> String

Return the path of the field name of the value at path, for the frame walk. The path of a field of the head itself is the name of the field.

Examples

julia> PortfolioOptimisers.join_path("", :pe)"pe"julia> PortfolioOptimisers.join_path("opt", :pe)"opt.pe"

Related

source
PortfolioOptimisers.reader_frames — Method
reader_frames(x, path::AbstractString, refit::Bool) -> ReturnsFrames
reader_frames(v::AbstractVector, path::AbstractString, refit::Bool) -> ReturnsFrames

Return the frames that x adds to the group of the head that holds it.

This is the verb of the frame walk. The default method answers that x adds nothing, which is correct for a value that holds no reader, and for an inner optimiser, a fallback and a leader, where the walk stops. A vector adds the frames of each element, at the path of its position. Two kinds of types add a method:

  • A reader of the returns returns source_frames(x.x_src, path, raw), see source_frames. It does not walk its own nesting fields, because an inner reader states no source, see assert_inner_reader.
  • A value that holds readers, such as a risk measure, a constraint, an uncertainty set or a loss, joins the frames of each field that can hold a reader with merge_frames, at the path that join_path gives.

Arguments

  • x: The value to walk: a reader of the returns, a value that holds readers, a vector of them, or any other value.
  • path: The path of the value from the head, for example "pe", "cle" or "r[2].pe". A warning names a reader by its path.
  • refit: Whether a regression reader at x_src = nothing in the group fits its regression on the raw returns data, see refits_regression.

Returns

  • fr::ReturnsFrames: The frames that x adds.

Related

source
PortfolioOptimisers.refits_regression — Method
refits_regression(pe) -> Bool

Answer true when a regression reader at x_src = nothing, in an optimiser whose prior is pe, fits its regression on the raw returns data.

A regression reader at nothing takes the loadings of the Prior Result when it holds them, and then it reads the frame of the prior. It fits on rd.X only when the Prior Result holds no loadings. So it counts as a raw reader only when the type of pe shows that the prior gives no loadings. The default method answers false: a precomputed Prior Result, and any value whose type does not show it, do not count. Each prior estimator that gives no loadings adds a method that answers true.

Arguments

  • pe: The prior of the optimiser: a prior estimator, a Prior Result, or nothing.

Returns

  • refit::Bool: Whether a regression reader at nothing fits on the raw returns data.

Related

source
PortfolioOptimisers.group_frames — Function
group_frames(head) -> ReturnsFrames

Return the frames of the group of head.

An optimiser, a Pipeline and an OnlinePortfolioSelection add a method. The method finds refit from the prior of the head with refits_regression, calls reader_frames on each slot that can hold a reader, and joins the answers with merge_frames. The default method answers that the head holds no reader.

Arguments

Returns

  • fr::ReturnsFrames: The frames of the group of head.

Related

source
group_frames(iv::InverseVolatility) -> ReturnsFrames

Walk the readers of an InverseVolatility head, for the warning of a forgotten raw reader and the gap rule of the head. The only reader of the head is its prior pe. field_frames walks every field, and the walk stops at the fallback.

Arguments

  • iv: The head.

Returns

  • fr::ReturnsFrames: The frames of the group of iv.

Related

source
group_frames(opt::NestedClustered) -> ReturnsFrames
group_frames(opt::Union{<:Stacking, <:SubsetResampling}) -> ReturnsFrames

Walk the readers of a meta-optimiser, for the warning of a forgotten raw reader and the gap rule of the head.

The group of a meta-optimiser is the head and every reader in its own slots: the prior pe, and the clustering cle of a NestedClustered. field_frames walks every field. The walk stops at the inner optimisers, the outer optimiser and the fallback, because each one is a head with its own group.

Arguments

  • opt: The meta-optimiser.

Returns

  • fr::ReturnsFrames: The frames of the group of opt.

Related

source
group_frames(opt::OnlinePortfolioSelection) -> ReturnsFrames
reader_frames(alg::AbstractOnlinePortfolioSelectionAlgorithm, path::AbstractString,
              refit::Bool) -> ReturnsFrames

Walk the group of an OnlinePortfolioSelection head, for the warning of a forgotten raw reader and the benchmark names that the state pins.

The group is the source of the step, the readers of each RiskLoss in the rule tree, and the readers of a ProgrammeAllocationSet on set. The step is the outermost reader of the rows, so at x_src = nothing it reads the raw returns data, and the walk names it by the type of the head. field_frames walks every field of the head and of each rule. A rule over rules walks its sub-rules, and a vector of rules walks each one. The walk stops at a leader and at the fallback, because each is a head with its own group. It stops at a forecaster and at a sample selector too: these read the frame of the step through head_frame_returns, so they are inner readers and state no source. A Risk Loss and a programme set walk their own fields under the refit rule of their own prior, see refits_regression.

Arguments

  • opt: The head.
  • alg: An Online Selection Rule.
  • path: The path of the value from the head, for example "pe", "cle" or "r[2].pe". A warning names a reader by its path.
  • refit: Whether a regression reader at x_src = nothing in the group fits its regression on the raw returns data, see refits_regression.

Returns

  • fr::ReturnsFrames: The frames of the group of opt, or the frames that alg adds.

Related

source
group_frames(pipe::Pipeline) -> ReturnsFrames
reader_frames(p::Pipeline, path::AbstractString, refit::Bool) -> ReturnsFrames

The frame walk of a Pipeline.

A Pipeline joins the group of its last optimiser, see pipeline_frames, and its constructor warns on that group with warn_raw_readers. A nested Pipeline is a step of an outer one, and the outer optimiser receives the value of its last step, so it adds the frames of that step.

Arguments

  • pipe, p: The pipeline.
  • path: The path of the value from the head, for example "pe", "cle" or "r[2].pe". A warning names a reader by its path.
  • refit: Whether a regression reader at x_src = nothing in the group fits its regression on the raw returns data, see refits_regression.

Returns

  • fr::ReturnsFrames: The frames of the group of pipe, or the frames of the last step of p at the path "<path>.steps[n]".

Related

source
PortfolioOptimisers.group_source — Function
group_source(fr::ReturnsFrames) -> Option{<:ExcessSource}
group_source(head) -> Option{<:ExcessSource}

Return the source that the gap rule of a group reads: ExcessSource() when a reader of the group states it, and nothing otherwise.

A head drops each observation at which a vector benchmark has a gap when a reader of its group states ExcessSource. A raw reader of the group loses the observations too, so every reader of the head pairs the same observations. The head passes the answer to shared_series_view in batch, and to shared_series_gaps in an online step. A Pipeline passes the answer for its group to each step of the group, see pipeline_gap_sources. The method on a head reads group_frames.

Arguments

  • fr: The frames of the group.
  • head: The value whose group the walk reads: an optimiser, a Pipeline or an OnlinePortfolioSelection.

Returns

  • x_src::Option{<:ExcessSource}: ExcessSource() or nothing.

Related

source
PortfolioOptimisers.gap_source — Function
gap_source(gsrc::ExcessSource, x_src) -> ExcessSource
gap_source(gsrc::Nothing, x_src) -> typeof(x_src)

Return the source that decides the gap drop of one reader in a group: the source of the group when it is ExcessSource, and the source of the reader otherwise.

A group drops a gap of a vector benchmark when any reader of it states ExcessSource(), see group_source. A group source of nothing drops nothing for the group, and the reader still drops by its own source. So the reader drops a gap when the group or the reader reads the Excess Frame. The answer decides only which observations the reader reads, never its frame.

Algorithm

The method that Julia selects is the algorithm.

  1. gsrc is ExcessSource(): return gsrc.
  2. gsrc is nothing: return x_src.

Arguments

Returns

  • src::Option{<:AbstractReturnsSource}: The source of the gap drop of the reader.

Examples

julia> PortfolioOptimisers.gap_source(ExcessSource(), DataSource())ExcessSource()julia> PortfolioOptimisers.gap_source(nothing, DataSource())DataSource()

Related

source
PortfolioOptimisers.warn_raw_readers — Function
warn_raw_readers(head, fr::ReturnsFrames = group_frames(head)) -> Nothing

Warn when the group of head holds a reader of the Excess Frame and a reader that states no source and reads the raw returns data.

The readers of one head can read different frames. A reader that states DataSource() beside a reader that states ExcessSource() is a mix that the caller chose, and it is silent. A reader at nothing that reads the raw returns beside a reader of the Excess Frame is a reader that the caller can have forgotten, so the head warns and then builds as configured. The configuration alone decides the warning, so the constructor of the head calls this function. A Pipeline passes the frames of its steps joined to the frames of its optimiser.

Each different mismatch logs one time. The message names the type of the head and the path of each raw reader, and it is the identity of the log record, so a head that a cross-validation builds again logs one time, and a different mismatch still logs.

Arguments

  • head: The value whose group the walk reads: an optimiser, a Pipeline or an OnlinePortfolioSelection.
  • fr: The frames of the group of head.

Returns

  • nothing.

Related

source