Time-dependent

PortfolioOptimisers.TimeDependent — Type
struct TimeDependent{__T_val, __T_default} <: AbstractEstimator

Changes one optimiser input from fold to fold of a cross-validation scheme.

A TimeDependent goes directly into the optimiser field that it changes, for example JuMPOptimiser(; lt = TimeDependent([...])). So the field names the target, and a field holds a static value or a schedule, never both. The fold loop finds a schedule only in a field of an optimiser. It does not find one inside another input, for example inside a Fees or a risk measure.

The field val is a vector or a function. Entry i of a vector is the complete value of the field at fold i. A function is called at each fold with the TimeDependentContext of the fold. It is a bare function, a bare function in a PreviousWeightsFunction, or a TimeDependentCallable.

A field that takes a vector of constraints takes the whole vector at each fold. So a schedule of constraint vectors is a vector of vectors, TimeDependent([[c₁ᵃ, c₁ᵇ], [c₂ᵃ, c₂ᵇ], …]). To change one constraint of a vector and keep the others, make the vector in a function, TimeDependent(ctx -> [dynamic(ctx), static]).

Fold i is fold i of the enumeration of split(cv, rd), and the schedule sets no other order. That order is the order of time for a walk-forward scheme and for a KFold with no shuffle. For a scheme whose enumeration is not an order of time, such as a combinatorial or a randomised scheme, a function can read the windows of its fold, ctx.train_idx[ctx.i] and ctx.test_idx[ctx.i].

A schedule has an effect only at a fold. An optimise with no fold replaces it with the value of the field outside every fold loop, see reset_time_dependent_estimator. That value is the static default of the field, or default when the schedule sets one. A required field, such as a field that holds an optimiser, has no static default. So a schedule in such a field must set default, else a solve with no fold throws a TimeDependentDefaultError.

A vector must have one entry for each fold of the scheme, and the fold loop checks the length after split. An entry can be nothing, which gives the field the value nothing at that fold.

The constructor stores a vector whose entries are all optimisers or precomputed results, OptE_Opt, as a Vector{OptE_Opt}. So a mixed schedule, which optimises at some folds and predicts at others, is admitted in a field that holds an optimiser by its element type, see TD_OptE_Opt. Else the vector is a Vector{Any}, which the field does not take.

A schedule and an Online do not wrap each other, because they resolve at different times. An Online resolves once, at the warm-up, because the step passes its sample buffer on to the next step. A schedule resolves at each fold. So val, an entry of val and default must not be an Online. The other order works: an estimator in an Online can hold schedules, which resolve at each fold after the warm-up.

Schedules do not nest. So val, an entry of val and default must not be a TimeDependent. An estimator that a schedule puts into a field can hold schedules in its own fields. Those resolve against the same fold after the swap.

To find the entry that ran at a fold, read the index of the fold. time_dependent_value reads val[ctx.i], so val[i] is the value at fold i. For a walk-forward scheme, a KFold with no shuffle and a Pipeline, fold i is also entry i of the MultiPeriodPredictionResult. MultipleRandomised and the combinatorial schemes put their predictions in a different order. For them, run split(cv, rd) again, and read the map from fold to path in its path_ids.

A function computes its value and selects no entry, so no index records its value. To get the value again, call the function with the context of the fold, or let a TimeDependentCallable write its value into one of its fields.

Fields

  • bind: Fold loop that resolves the schedule. :outermost, the default, selects the outermost fold loop over the estimator. :nearest selects the nearest fold loop around the field. In an inner estimator of a meta-optimiser, that is the cross-validation of the meta-optimiser, also when an outer fold loop runs the meta-optimiser.
  • default: Value of the field outside every fold loop. It replaces the static default that time_dependent_field_defaults gives for the field. NoDefault, the default, keeps the static default. A field with no static default needs this value.

Constructors

TimeDependent(val, bind::Symbol = :outermost; default = NoDefault())TimeDependent(; val::Union{AbstractVector, Base.Callable,                           PreviousWeightsFunction, TimeDependentCallable,                           TimeDependent}, bind::Symbol = :outermost,              default = NoDefault())

Validation

  • If val is a vector: !isempty(val), and no entry is a TimeDependent or an Online.
  • val is not a TimeDependent, else an ArgumentError is thrown. The constructor has no method for a val that is not a vector, a function, a PreviousWeightsFunction or a TimeDependentCallable, such as an Online.
  • default is not a TimeDependent or an Online.
  • bind in (:outermost, :nearest).

Examples

julia> TimeDependent([Fees(; l = 0.001), Fees(; l = 0.002)])TimeDependent      val ┼ 2-element Vector{Fees}          │ Fees ⋯          │ Fees ⋯     bind ┼ Symbol: :outermost  default ┴ NoDefault()

Related

source
PortfolioOptimisers.TimeDependentContext — Type
struct TimeDependentContext{__T_i, __T_n, __T_rd, __T_train_idx, __T_test_idx, __T_w_prev, __T_path_id} <: AbstractResult

Describes one fold to the schedules that resolve against it.

It holds the position of the fold in the enumeration of split, and the data that a function in a schedule reads to compute its value. The field i indexes train_idx and test_idx, so ctx.train_idx[ctx.i] and ctx.test_idx[ctx.i] are the windows of the fold. The context sets no order other than the enumeration of the scheme.

The field rd is the input data of the fold loop, which can be a view of a subset of the assets. So a function reads the current universe and timestamps. An optimiser fold loop gives returns. The Pipeline fold loop gives the prices or returns that it received, before any step of the pipeline changes them.

The field w_prev holds weights only when the fold loop runs in sequence and a previous fold exists. The field path_id holds a value only under a scheme with many paths.

Fields

  • i: Index of the fold in the enumeration of split, from one. It indexes train_idx and test_idx.
  • n: Number of folds in the path.
  • rd: Input data of the fold loop, which can be a view of a subset of the assets.
  • train_idx: Training index vectors of the path, one for each fold.
  • test_idx: Test index vectors of the path, one for each fold.
  • w_prev: Portfolio weights of the previous fold when the fold loop runs in sequence, else nothing.
  • path_id: Identifier of the path under a scheme with many paths, else nothing.

Constructors

TimeDependentContext(;    i::Integer, n::Integer, rd::Prices_RR, train_idx, test_idx,    w_prev::Option{<:VecNum} = nothing, path_id::Option{<:Integer} = nothing) -> TimeDependentContext

Keywords correspond to the struct's fields.

Validation

  • 1 <= i <= n.

Related

source
PortfolioOptimisers.PreviousWeightsFunction — Type
struct PreviousWeightsFunction{__T_f} <: AbstractAlgorithm

States that a function in a schedule reads the weights of the previous fold.

No code can find out whether a bare function in a TimeDependent reads the previous weights. So a bare function gives false to needs_previous_weights, and its context holds w_prev only when another input makes the fold loop run in sequence. A function in a PreviousWeightsFunction gives true. Then the fold loop runs its folds in sequence, and the TimeDependentContext of each fold after the first holds w_prev.

Fields

  • f: Function that the fold loop calls at each fold as f(ctx::TimeDependentContext). It returns the value of the field at that fold.

Constructors

PreviousWeightsFunction(; f) -> PreviousWeightsFunction

Keywords correspond to the struct's fields.

Examples

julia> PreviousWeightsFunction(; f = identity)PreviousWeightsFunction  f ┴ typeof(identity): identity

Related

source
PortfolioOptimisers.NoDefault — Type
struct NoDefault <: AbstractAlgorithm

States that no value exists for a field outside every fold loop.

It has two uses.

  • As the default of a TimeDependent, it states that the schedule gives no value outside every fold loop. A solve with no fold then uses the static default of the field, see time_dependent_field_defaults.
  • As an entry of the time_dependent_field_defaults of an optimiser, it states that the field is required and has no static default. The fields that hold an optimiser are such fields. A schedule in one of them must carry its own default, else a solve with no fold throws a TimeDependentDefaultError.

Constructors

NoDefault() -> NoDefault

Examples

julia> NoDefault()NoDefault()

Related

source
PortfolioOptimisers.TimeDependentDefaultError — Type
struct TimeDependentDefaultError{__T_msg} <: PortfolioOptimisersError

Exception for a solve with no fold that reaches a schedule with no value outside every fold loop.

A TimeDependent is defined only over the folds of a cross-validation scheme. A field with a static default takes that default outside every fold loop, and no message is given. A required field, such as a field that holds an optimiser, has no static default. So its schedule must state the value outside every fold loop, as TimeDependent(val; default = x).

Fields

  • msg: Error message that states the condition that caused the exception.

Constructors

TimeDependentDefaultError(msg)

Related

source
PortfolioOptimisers.factory — Method
factory(td::TimeDependent, args...) -> TimeDependent

Applies factory to each entry of a TimeDependent and to its default, and rebuilds the schedule.

A schedule can stay in place after the fold loop resolves the others, for example an element with bind = :nearest that the inner cross-validation of a meta-optimiser resolves. So the factory pass after the resolution must reach into it. A function schedule does not change, because its values do not exist yet. At its fold, it receives the context, which holds w_prev.

Algorithm

  1. When td.val is a vector, apply factory(x, args...) to each entry x.
  2. When td.default is not NoDefault, apply factory to it too.
  3. Return a new schedule with the new values and the same bind.

Related

source
PortfolioOptimisers.TimeDependentCallable — Type
abstract type TimeDependentCallable <: AbstractEstimator

Abstract supertype for the callable structs that compute the value of a schedule at each fold.

A subtype takes the place of a bare function in a TimeDependent, and holds its parameters as data. Because it is a type, it can declare that it reads the previous weights with a method of needs_previous_weights. A bare function needs the wrapper PreviousWeightsFunction for that.

A subtype can also record what it computed. A bare function ctx -> … selects no entry by index, so a later reader cannot recover its value at a fold. A functor can hold a mutable field, for example a vector, and write the value of fold ctx.i into it.

The family is divided by what the functor returns, and a subtype states that kind by its supertype. Subtype TimeDependentConstraintCallable when the value is a constraint value, and TimeDependentOptimiserCallable when the value is an optimiser. Only the second is admitted in a field that holds an optimiser before any fold runs, see TD_OptE_Opt. Do not subtype this root directly.

Interfaces

Subtype one of the two children, not this root, and implement the methods below.

The functor

  • (x::MySubtype)(ctx::TimeDependentContext): Returns the value of the field at the fold that ctx describes.

Arguments

  • x: The concrete subtype instance.
  • ctx: The context of the fold. It holds the index of the fold, the data of the fold loop, and the weights of the previous fold when the loop runs its folds in sequence.

Returns

  • The complete value of the field at that fold, of the kind that the supertype of the subtype states.

needs_previous_weights

  • needs_previous_weights(::MySubtype) -> Bool: States whether the functor reads ctx.w_prev. The fallback returns false. Return true to make the fold loop run its folds in sequence, as PreviousWeightsFunction does for a bare function.

Related

source
PortfolioOptimisers.TimeDependentConstraintCallable — Type
abstract type TimeDependentConstraintCallable <: TimeDependentCallable

Abstract supertype for the callable structs whose value at a fold is a constraint value.

A constraint value is any value of a TimeDependent that is not an optimiser, for example a budget, a set of weight bounds, a fee structure or a turnover limit. When the fold loop puts the value into its field, the keyword constructor of the optimiser that holds the field checks it.

A functor that returns an optimiser subtypes TimeDependentOptimiserCallable instead.

Interfaces

The methods are those of TimeDependentCallable: the functor (x::MySubtype)(ctx::TimeDependentContext), and the optional needs_previous_weights. This child adds no method. It states that the functor returns a constraint value.

Related

source
PortfolioOptimisers.TimeDependentOptimiserCallable — Type
abstract type TimeDependentOptimiserCallable <: TimeDependentCallable

Abstract supertype for the callable structs whose value at a fold is an optimiser.

The functor returns an OptE_Opt, so a TimeDependent that holds it is admitted in every field that holds an optimiser, see TD_OptE_Opt. The type states the kind of the value before any fold runs. A bare function ctx -> optimiser is admitted as a Base.Callable, and its value is checked only when the fold loop puts it into the field.

Interfaces

The methods are those of TimeDependentCallable: the functor (x::MySubtype)(ctx::TimeDependentContext), and the optional needs_previous_weights. This child adds no method. It states that the functor returns an OptE_Opt, and assert_time_dependent_optimiser checks the value when the fold loop puts it into the field.

Related

source
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(x::Any) -> Bool
needs_previous_weights(x::AbstractVector) -> Bool

Return true if an entry of a TimeDependent vector reads the weights of the previous fold.

A turnover, a fee, a tracking input, a risk measure, a budget cost, an optimisation estimator or result, a constraint and a nested schedule each give their own method. A vector gives true if any of its elements does. Every other value, such as a number or a bare function, gives false, because no code can find out what a bare function reads.

Related

source
needs_previous_weights(
    opt::AbstractVector{<:Union{NonFiniteAllocationOptimisationEstimator, NonFiniteAllocationOptimisationResult, TimeDependent{<:AbstractVector{<:Union{NonFiniteAllocationOptimisationEstimator, NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}
) -> Any

Returns true if one element of a vector of optimisers needs the weights of the previous fold.

Related

source
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(td::TimeDependent) -> Bool

Returns true if a schedule reads the weights of the previous fold.

A bare function gives false, because no code can find out what it reads.

Algorithm

  1. When td.val is a PreviousWeightsFunction, return true.
  2. When td.val is a TimeDependentCallable, return its own needs_previous_weights.
  3. When td.val is a vector, return true if any entry needs the previous weights, by the method of needs_previous_weights for the type of the entry.
  4. Else return false.

Related

source
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(
    opt::AbstractVector{<:Union{NonFiniteAllocationOptimisationEstimator, NonFiniteAllocationOptimisationResult, TimeDependent{<:AbstractVector{<:Union{NonFiniteAllocationOptimisationEstimator, NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}
) -> Any

Returns true if one element of a vector of optimisers needs the weights of the previous fold.

Related

source
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(x::Any) -> Bool
needs_previous_weights(x::AbstractVector) -> Bool

Return true if an entry of a TimeDependent vector reads the weights of the previous fold.

A turnover, a fee, a tracking input, a risk measure, a budget cost, an optimisation estimator or result, a constraint and a nested schedule each give their own method. A vector gives true if any of its elements does. Every other value, such as a number or a bare function, gives false, because no code can find out what a bare function reads.

Related

source
PortfolioOptimisers.time_dependent_field_defaults — Function
time_dependent_field_defaults(opt)

Returns a NamedTuple of the static defaults of the optimiser fields that can hold a TimeDependent, for the fields whose default is not nothing.

reset_time_dependent_estimator reads it to replace the schedules in a solve with no fold. A field that the tuple does not list has the default nothing. A required field has no static default, and the fields that hold an optimiser are such fields. The tuple lists a required field with NoDefault. That is not a value of the field. It states that a schedule in the field must carry its own default. The fallback method returns an empty tuple.

Related

source
time_dependent_field_defaults(
    _::HierarchicalOptimiser
) -> @NamedTuple{pe::EmpiricalPrior{PortfolioOptimisersCovariance{Covariance{SimpleExpectedReturns{Nothing, Nothing, Nothing}, GeneralCovariance{SimpleCovariance, Nothing, Nothing}, FullMoment, Nothing, Nothing, Nothing}, MatrixProcessing{Posdef{UnionAll, @NamedTuple{}}, Nothing, Nothing, Nothing, NTuple{4, Symbol}}, Nothing}, SimpleExpectedReturns{Nothing, Nothing, Nothing}, Nothing, Nothing, Nothing, Nothing, Nothing}, cle::ClustersEstimator{PortfolioOptimisersCovariance{Covariance{SimpleExpectedReturns{Nothing, Nothing, Nothing}, GeneralCovariance{SimpleCovariance, Nothing, Nothing}, FullMoment, Nothing, Nothing, Nothing}, MatrixProcessing{Posdef{UnionAll, @NamedTuple{}}, Nothing, Nothing, Nothing, NTuple{4, Symbol}}, Nothing}, Distance{Nothing, CanonicalDistance}, HClustAlgorithm{Symbol}, OptimalNumberClusters{Nothing, SecondOrderDifference{StandardisedValue{MeanValue{Nothing}, StdValue{Nothing, Bool}}}}, Nothing}, wb::WeightBounds{Float64, Float64}, wf::IterativeWeightFinaliser{Int64}}

Return the value that each schedulable field of a HierarchicalOptimiser takes when no fold resolves it.

It returns hierarchical_optimiser_td_defaults, which the constructor also reads.

Returns

  • defaults::NamedTuple: The static default of pe, cle, wb and wf.

Related

source