Time-dependent
PortfolioOptimisers.TimeDependent — Type
struct TimeDependent{__T_val, __T_default} <: AbstractEstimatorChanges 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
val: Vector with one value for each fold, in the order ofsplit, or a function of theTimeDependentContextof the fold. The function is a bare function, a bare function in aPreviousWeightsFunction, or aTimeDependentCallable.
bind: Fold loop that resolves the schedule.:outermost, the default, selects the outermost fold loop over the estimator.:nearestselects 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 thattime_dependent_field_defaultsgives 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
valis a vector:!isempty(val), and no entry is aTimeDependentor anOnline. valis not aTimeDependent, else anArgumentErroris thrown. The constructor has no method for avalthat is not a vector, a function, aPreviousWeightsFunctionor aTimeDependentCallable, such as anOnline.defaultis not aTimeDependentor anOnline.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
PortfolioOptimisers.TimeDependentContext — Type
struct TimeDependentContext{__T_i, __T_n, __T_rd, __T_train_idx, __T_test_idx, __T_w_prev, __T_path_id} <: AbstractResultDescribes 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 ofsplit, from one. It indexestrain_idxandtest_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, elsenothing.
path_id: Identifier of the path under a scheme with many paths, elsenothing.
Constructors
TimeDependentContext(; i::Integer, n::Integer, rd::Prices_RR, train_idx, test_idx, w_prev::Option{<:VecNum} = nothing, path_id::Option{<:Integer} = nothing) -> TimeDependentContextKeywords correspond to the struct's fields.
Validation
1 <= i <= n.
Related
PortfolioOptimisers.PreviousWeightsFunction — Type
struct PreviousWeightsFunction{__T_f} <: AbstractAlgorithmStates 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 asf(ctx::TimeDependentContext). It returns the value of the field at that fold.
Constructors
PreviousWeightsFunction(; f) -> PreviousWeightsFunctionKeywords correspond to the struct's fields.
Examples
julia> PreviousWeightsFunction(; f = identity)PreviousWeightsFunction f ┴ typeof(identity): identityRelated
PortfolioOptimisers.NoDefault — Type
struct NoDefault <: AbstractAlgorithmStates that no value exists for a field outside every fold loop.
It has two uses.
- As the
defaultof aTimeDependent, 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, seetime_dependent_field_defaults. - As an entry of the
time_dependent_field_defaultsof 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 owndefault, else a solve with no fold throws aTimeDependentDefaultError.
Constructors
NoDefault() -> NoDefaultExamples
julia> NoDefault()NoDefault()Related
PortfolioOptimisers.TimeDependentDefaultError — Type
struct TimeDependentDefaultError{__T_msg} <: PortfolioOptimisersErrorException 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
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
- When
td.valis a vector, applyfactory(x, args...)to each entryx. - When
td.defaultis notNoDefault, applyfactoryto it too. - Return a new schedule with the new values and the same
bind.
Related
PortfolioOptimisers.TimeDependentCallable — Type
abstract type TimeDependentCallable <: AbstractEstimatorAbstract 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 thatctxdescribes.
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 readsctx.w_prev. The fallback returnsfalse. Returntrueto make the fold loop run its folds in sequence, asPreviousWeightsFunctiondoes for a bare function.
Related
PortfolioOptimisers.TimeDependentConstraintCallable — Type
abstract type TimeDependentConstraintCallable <: TimeDependentCallableAbstract 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
PortfolioOptimisers.TimeDependentOptimiserCallable — Type
abstract type TimeDependentOptimiserCallable <: TimeDependentCallableAbstract 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
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(x::Any) -> Bool
needs_previous_weights(x::AbstractVector) -> BoolReturn 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
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
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
- When
td.valis aPreviousWeightsFunction, returntrue. - When
td.valis aTimeDependentCallable, return its ownneeds_previous_weights. - When
td.valis a vector, returntrueif any entry needs the previous weights, by the method ofneeds_previous_weightsfor the type of the entry. - Else return
false.
Related
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
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(x::Any) -> Bool
needs_previous_weights(x::AbstractVector) -> BoolReturn 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
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
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 ofpe,cle,wbandwf.
Related