Returns Source

abstract type AbstractReturnsSource <: AbstractAlgorithm

Abstract supertype for the source of the returns that a reader of the returns data fits on.

A reader of the returns is an estimator that receives the returns data rd and picks the matrix that it fits on: a prior, a clustering, phylogeny or centrality estimator, a factor regression, and the step of OnlinePortfolioSelection. Each reader holds its source in its x_src field, so no optimiser gives a source to it. The field is nothing when the caller states no source, and otherwise an instance of a concrete subtype. Dispatch on the value picks the matrix, see benchmark_relative_returns.

Each family of readers admits its own set of values, and its keyword constructor refuses a different value with assert_returns_source. A prior and the step of OnlinePortfolioSelection read no prior, so they refuse PriorSource().

All concrete types that name a source of the returns should subtype AbstractReturnsSource.

Interfaces

In order to implement a new concrete type that works seamlessly with the library, subtype AbstractReturnsSource and implement the following methods. A reader refuses a source that its admitted set does not name, see assert_returns_source, so a new source reaches only a reader whose keyword constructor admits it. A new source reads no benchmark gap: only ExcessSource drops the gap rows of a vector benchmark, see shared_series_view.

benchmarkrelativereturns

• benchmark_relative_returns(rd::ReturnsResult, x_src::AbstractReturnsSource) -> Option{<:MatNum}: The asset returns that a reader at x_src fits on.

Arguments

• rd: The returns data that the reader receives.
• x_src: The concrete subtype instance.

Returns

• X::Option{<:MatNum}: A matrix with the rows and the columns of rd.X, or nothing when rd holds no returns. The function does not modify rd.

source_frames

• source_frames(x_src::AbstractReturnsSource, path::AbstractString, raw::Bool) -> ReturnsFrames: The frames that an outermost reader at x_src adds to the group of its optimiser.

Arguments

• x_src: The concrete subtype instance.
• 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.
• raw: Whether the reader reads the raw returns data at x_src = nothing.

Returns

• fr::ReturnsFrames: PortfolioOptimisers.ReturnsFrames(true, String[]) when the source reads the Excess Frame, and PortfolioOptimisers.ReturnsFrames() otherwise.

Examples

julia> struct HalfSource <: PortfolioOptimisers.AbstractReturnsSource endjulia> PortfolioOptimisers.benchmark_relative_returns(rd::ReturnsResult, ::HalfSource) = rd.X / 2;julia> function PortfolioOptimisers.source_frames(::HalfSource, ::AbstractString, ::Bool)           return PortfolioOptimisers.ReturnsFrames()       end;julia> rd = ReturnsResult(; nx = ["A", "B"], X = [0.1 0.2; 0.3 0.4]);julia> benchmark_relative_returns(rd, HalfSource())2×2 Matrix{Float64}: 0.05  0.1 0.15  0.2

Related

• DataSource
• ExcessSource
• PriorSource
• benchmark_relative_returns
• source_frames
• assert_returns_source

struct DataSource <: AbstractReturnsSource

Makes a reader of the returns fit on the asset returns rd.X, as the caller gave them.

On a prior and on a graph reader, DataSource() reads the same matrix as x_src = nothing, but the caller states the choice. An optimiser that holds a reader of the Excess Frame warns about a reader at nothing that reads the raw returns, and it does not warn about a reader at DataSource(), see warn_raw_readers. On a regression reader, DataSource() always fits the regression on rd.X, where nothing first takes the loadings of the prior.

Related

• AbstractReturnsSource
• ExcessSource
• PriorSource
• benchmark_relative_returns

struct ExcessSource <: AbstractReturnsSource

Makes a reader of the returns fit on the returns in excess of the benchmark, rd.X - rd.B, the Excess Frame.

The returns data must carry a benchmark B, because no excess return exists without one. A vector benchmark gives one series for every asset, and a matrix benchmark gives one series for each asset. An optimiser drops each observation at which a vector benchmark has a gap when a reader of its group states ExcessSource(), so that every reader of the optimiser pairs the same observations, see shared_series_view.

Related

• AbstractReturnsSource
• DataSource
• PriorSource
• benchmark_relative_returns

struct PriorSource <: AbstractReturnsSource

Makes a reader of the returns read the Prior Result in place of the returns data.

A graph reader reads the returns of the prior, pr.X, in the frame that the prior fitted in. Under a factor prior pr.X is a reconstruction of the rank of the factors, and a scenario window cuts its rows. A regression reader takes the loadings of the prior, pr.rr, and refuses a Prior Result that holds none. A prior and the step of OnlinePortfolioSelection read no prior, so they refuse PriorSource().

Related

• AbstractReturnsSource
• DataSource
• ExcessSource

source_frames(x_src::ExcessSource, path::AbstractString, raw::Bool) -> ReturnsFrames
source_frames(x_src::Nothing, path::AbstractString, raw::Bool) -> ReturnsFrames
source_frames(x_src::Union{<:DataSource, <:PriorSource}, path::AbstractString,
              raw::Bool) -> ReturnsFrames

Return the frames of one outermost reader from the source that it states.

The method of reader_frames for a reader calls this function with its own x_src. A reader at PriorSource() reads the frame of the prior, so it never counts by itself.

Algorithm

The method that Julia selects is the algorithm.

1. ExcessSource(): the reader states the Excess Frame.
2. nothing: the reader is a raw reader at path when raw is true.
3. DataSource() or PriorSource(): the reader adds nothing to the group.

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.
• 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.
• raw: Whether the reader reads the raw returns data at x_src = nothing. It is true for a prior and a graph reader, and refit for a regression reader, see refits_regression.

Returns

• fr::ReturnsFrames: The frames of the reader.

Related

• reader_frames
• ReturnsFrames

returns_source(x) -> Option{<:AbstractReturnsSource}

Return the source that the reader x states, its x_src field.

The default method answers nothing, because a value that is not a reader of the returns states no source. Each family of readers adds a method that returns its field. assert_inner_reader reads the source through this function, so it accepts any value in a nesting field.

Arguments

• x: A reader of the returns, or any other value.

Returns

• x_src::Option{<:AbstractReturnsSource}: The source that x states, or nothing.

Related

• assert_inner_reader
• AbstractReturnsSource