Propagatable
Utility functions
PortfolioOptimisers.@propagatable — Macro
@propagatable exprDefine a struct, and make its propagation methods from six field tags. The tags are independent, and a field can carry more than one:
@fprop(factory propagation): a call offactorycallsfactoryon each tagged field. It passes runtime values, such as observation weights, prior results and solvers, down the tree of composed structs. The macro always makes afactory(x, args...)method. When no field carries@fpropor@wprop, that method returnsx.@wprop(weights replacement): an incomingObsWeightsargument replaces each tagged observation-weights field through_wprop. When noObsWeightsis threaded, the field keeps its value. Use@wpropfor the weights field and@fpropfor sub-estimators. A weights field with the defaultnothingmust take the incoming weights, but@fpropkeeps anothingvalue.@vprop(view propagation): a view of the struct at an index selection callsport_opt_viewon each tagged field. The call recurses into composed children and views data arrays. The macro makes aport_opt_viewmethod only when at least one field carries@vprop. With it, the macro makes anasset_axis_fieldsmethod that names the tagged fields, because a field that the asset index views is a field on the asset axis.@pprop(prior selection): the prior method selects each tagged field against the field of the same name of a prior result, throughsel(getfield(x, :f), getproperty(pr, :f)).@cprop(context selection): the prior method selects each tagged field against a threaded optimiser value, a solver, that it finds by type, throughsel(getfield(x, :f), _ctx(args...)).@oprop(observation child): a cut of the observations throughobs_weights_viewrecurses into each tagged field. No other method reads the tag.
When at least one field carries @pprop or @cprop, the macro makes a second method, factory(x, pr::AbstractPriorResult, args...). This method selects the @pprop and @cprop fields as above. It threads pr into the fields that carry only @fprop, as factory(getfield(x, :f), pr, args...). A field with both @pprop and @fprop takes the prior selection in this method, because @pprop wins. Then the method calls resolve_deferred_quantities on the selected struct. That call returns the struct with no change when the type has no deferred slot and no method of its own. So the Deferred-Quantity resolution runs last, and a slot that holds a Deferred Quantity sees the solver, the observation weights and the children in their last state. This method is more specific than the general factory(x, args...), so Julia selects it for every call that passes a prior.
A field with no tag keeps its value in every method, whatever its type. A tag is explicit, and the author adds it by choice. Do not put @pprop and @cprop on one field, because a value comes from one source. The valid stacks are @pprop @fprop, for a sub-estimator, and @pprop @wprop, for a weights field.
Two results of the emitted code are contracts on the declaration. The library checks both where the author writes the struct, not at the first call:
- Every generated method builds the struct again as
StructName(; field = …)over all fields, with or without a tag. So every field name must also be a keyword of the outer constructor. Akwargs...slurp does not satisfy this, because it accepts the keyword and then discards it. - The prior method reads
getproperty(pr, :field), so every@ppropfield name must be a property of a prior result. Seeprior_result_property_pool.
The macro registers each declaration in PROPAGATABLE_CONTRACTS. check_propagatable_contracts checks the whole registry when the module is complete. A field name with a typing error fails at precompilation with a suggestion from suggest_declared_key. It does not wait to raise a MethodError at the first call of factory. forward_prior uses the same contract.
The set of tags is data. PROP_TAG_NAMES holds the rows, prop_tag_expr holds the field transform of each tag, and PROP_TAG_CHANNELS holds the gate and the tag precedence of each channel. So a new tag is a row of those tables and a stub macro. A new channel is also a row of PROP_TAG_CHANNELS, but it needs its own emission step in this macro, because each channel has its own method head.
The macro works with @concrete. Put @propagatable on the outside:
@propagatable @concrete struct MyMeasure <: RiskMeasure @pprop @wprop w # prior factory selects pr.w; ObsWeights factory fills w @pprop sigma # prior-selected from pr.sigma @fprop alg # threaded (recursed) with pr / args config # passed through unchanged function MyMeasure(w, sigma, alg, config) return new{typeof(w), typeof(sigma), typeof(alg), typeof(config)}(w, sigma, alg, config) endend@wprop gates two channels, and they do different operations on the same field. factory replaces the field with an incoming ObsWeights value. obs_weights_view indexes the value of the field at a set of observations. A weights field needs no second tag to join the view on the observation axis. The observation method also opens on a @fprop or an @oprop field, and it recurses into each of them, so a cut reaches a weights field at any depth of the tree.
The macro adds the generated factory, port_opt_view, asset_axis_fields and obs_weights_view methods to the functions of PortfolioOptimisers. So @propagatable also works for a type that an external package defines.
Base.@__doc__ forwards a docstring on the declaration to the struct.
Algorithm
- Find the struct with
propagatable_find_struct, which givesstruct_nodeandrebuild.rebuildputs a replacement struct back inside the same chain of wrapping macros. - Read
type_headandbodyfromstruct_node. Readstruct_namefromtype_headwithpropagatable_bare_name, which drops the type parameters and the supertype. - Parse the body with
propagatable_parse_body. It givestagged, the field names of each tag,all_fields, every declared field in declaration order, andnew_body, the body with no tags. - Build
new_structfromnew_body, andchainfromrebuild(new_struct).chainis the original declaration without the tags, so@concreteand Julia both see an ordinary struct. - Bind
POMODto the module that defines the macro, and qualify every emitted name with it. A bare name resolves in the module of the caller. There,function factory(…)declares a new function of the caller, and the method never gets toPortfolioOptimisers.factory. That failure gives no error, because the declaration compiles and the type never joins the propagation chain. - Emit the
factorymethod. Whenprop_channel_activeholds for thefactorychannel, the body is a call to the keyword constructor, with the pairs fromprop_channel_pairs. Otherwise, the body isx. The macro always emits this method, so a@propagatablestruct with no tags returns itself fromfactory. - When the
viewchannel is active, emitport_opt_view(x::StructName, i, args...). Its channel threadsibeforeargs.... Also emitasset_axis_fields(::StructName), which returns the names of the@vpropfields as a tuple of symbols. - When the
obschannel is active, emitobs_weights_view(x::StructName, i). Its channel threadsiand takes no tail. A@wprop, a@fpropor an@opropfield opens the channel. - When the
priorchannel is active, emitfactory(x::StructName, pr::AbstractPriorResult, args...; kwargs...). Its body selects every tagged field fromx, and then gives the selected struct toresolve_deferred_quantities, which makes the Deferred-Quantity resolution the last operation. A Deferred Quantity and a Calibration Rule see the solver, the observation weights and the children in the state that the optimisation gave them, and a rule can callERMorRRM. This method is more specific than the method of step 6, so Julia selects it for a call that threads a prior. - Build
pprop_tuple, the names of the@ppropfields as a tuple of quoted symbols. - Return one escaped block. It holds
Base.@__doc__ chain, so a docstring on the declaration gets to the struct. Then it holds the emitted methods, and last the call topropagatable_register!that records the type andpprop_tuple.
Steps 6 to 9 differ only in the method head and in the arguments that the channel threads. Each step reads its gate and its tag precedence from PROP_TAG_CHANNELS. A new tag is a row of the tables, a branch in prop_tag_expr and a stub macro, but a new channel also needs a new step here.
Related
PortfolioOptimisers.@fprop — Macro
@fprop fieldField tag for a @propagatable struct body. It marks a composed child for factory propagation. A call of factory on the struct calls factory on the field.
Algorithm
The tag never expands, because @propagatable runs first and removes it. The steps below tell what happens to the tagged field, not what this macro does.
propagatable_parse_bodypeels the tag off the field, records the field name under:fprop, and puts the stripped field into the struct body. Neither Julia nor a wrapped macro such as@concreteever sees the tag.prop_channel_activereads the recorded name. This tag gates thefactorychannel and theobschannel, and each active channel makes@propagatableemit one method.prop_channel_pairsbuilds the keyword pair of the field for each emitted method, andprop_tag_exprgives the value:factorychannel:factory(x.field, args...; kwargs...), which recurses into the child.obschannel:obs_weights_view(x.field, i), which recurses into the child on the observation axis.
The generated method builds the struct again with its keyword constructor, so every check of the constructor runs again on the propagated value.
Step 3 gives the meaning of the tag. The same tag has two transforms, because a channel decides what a tag means. The obs channel gates on @fprop, so a struct whose only tag is @fprop gets an obs_weights_view method. A cut of the observations then reaches a weights field at any depth of the tree, through every wrapper above it.
The body of this macro raises an error. Julia runs it only when the tag is outside a @propagatable struct body, where no macro removed it.
Related
PortfolioOptimisers.@vprop — Macro
@vprop fieldField tag for a @propagatable struct body. It marks the field for port_opt_view propagation. A view of the struct at an index selection calls port_opt_view on the field.
The tag is independent of @fprop. A field can carry both, as @fprop @vprop field, when it takes part in factory propagation and in view propagation.
Algorithm
The tag never expands, because @propagatable runs first and removes it. The steps below tell what happens to the tagged field, not what this macro does.
propagatable_parse_bodypeels the tag off the field, records the field name under:vprop, and puts the stripped field into the struct body. Neither Julia nor a wrapped macro such as@concreteever sees the tag.prop_channel_activereads the recorded name. This tag gates theviewchannel alone, and an active channel makes@propagatableemit one method.prop_channel_pairsbuilds the keyword pair of the field for each emitted method, andprop_tag_exprgives the value:view_child(x.field, i, args...). This isport_opt_view(x.field, i, args...)for every value except a precomputed optimisation result, which it keeps with no change. The channel forwards the threaded tail and no keywords.- The generated method builds the struct again with its keyword constructor, so every check of the constructor runs again on the propagated value.
Step 3 gives the meaning of the tag. @vprop is in one channel, so it has one transform and one meaning. The index that the method threads selects assets. The observation axis has its own verb, obs_weights_view.
The body of this macro raises an error. Julia runs it only when the tag is outside a @propagatable struct body, where no macro removed it.
Related
PortfolioOptimisers.@pprop — Macro
@pprop fieldField tag for a @propagatable struct body. It marks the field as prior-selected. A call factory(x, pr::AbstractPriorResult, …) sets the field to sel(getfield(x, :field), getproperty(pr, :field)). This is the value of the risk measure when it is not nothing, else the moment of the same name from the prior result.
A field can carry this tag together with @wprop or @fprop. For example, @pprop @wprop w gives a weights field a prior method and an ObsWeights method. @pprop wins in the prior method. Do not put this tag and @cprop on one field, because a value comes from one source. No check refuses the pair, and @pprop wins because it is first in the precedence of the prior channel.
Algorithm
The tag never expands, because @propagatable runs first and removes it. The steps below tell what happens to the tagged field, not what this macro does.
propagatable_parse_bodypeels the tag off the field, records the field name under:pprop, and puts the stripped field into the struct body. Neither Julia nor a wrapped macro such as@concreteever sees the tag.prop_channel_activereads the recorded name. This tag gates thepriorchannel alone, and an active channel makes@propagatableemit one method.prop_channel_pairsbuilds the keyword pair of the field for each emitted method, andprop_tag_exprgives the value:sel(x.field, getproperty(pr, :field)). The prior result gives the property of the same name as the field, so the tag names no source of its own.- The generated method builds the struct again with its keyword constructor, so every check of the constructor runs again on the propagated value.
Step 3 gives the meaning of the tag. @pprop is first in the precedence of the prior channel. So a field with @pprop and @fprop takes the prior transform on that channel and the factory transform on the factory channel.
The body of this macro raises an error. Julia runs it only when the tag is outside a @propagatable struct body, where no macro removed it.
Related
PortfolioOptimisers.@wprop — Macro
@wprop fieldField tag for a @propagatable struct body. It marks the field as an observation-weights slot. A call factory(x, w::ObsWeights, …) replaces the field with the incoming weights through _wprop. When no ObsWeights is threaded, the field keeps its value.
This tag is different from @fprop, which recurses into a sub-estimator and keeps a nothing value. A weights field has the default nothing, which means uniform weights, and it must take the incoming weights, which the nothing rule of @fprop does not do. Use @wprop for the weights field w, and @fprop for sub-estimators.
Algorithm
The tag never expands, because @propagatable runs first and removes it. The steps below tell what happens to the tagged field, not what this macro does.
propagatable_parse_bodypeels the tag off the field, records the field name under:wprop, and puts the stripped field into the struct body. Neither Julia nor a wrapped macro such as@concreteever sees the tag.prop_channel_activereads the recorded name. This tag gates thefactorychannel and theobschannel, and each active channel makes@propagatableemit one method.prop_channel_pairsbuilds the keyword pair of the field for each emitted method, andprop_tag_exprgives the value:factorychannel:_wprop(x.field, args...; kwargs...), which replaces the field with an incomingObsWeights, and keeps it when none is threaded.obschannel:obs_weights_index(x.field, i), which indexes the value of the field at the selected observations. An index keeps theAbstractWeightssubtype, and a view does not.
The generated method builds the struct again with its keyword constructor, so every check of the constructor runs again on the propagated value.
Step 3 gives the meaning of the tag. The two channels do different operations on the same field, so factory and obs_weights_view are not two names for one operation. One @wprop field gives the struct an obs_weights_view method, with no second tag.
A risk measure stacks @pprop @wprop on its weights field. The prior channel then selects the field against the weights of the prior result, and the obs channel indexes it.
The body of this macro raises an error. Julia runs it only when the tag is outside a @propagatable struct body, where no macro removed it.
Related
PortfolioOptimisers.@cprop — Macro
@cprop fieldField tag for a @propagatable struct body. It marks the field as context-selected. A call factory(x, pr::AbstractPriorResult, …) sets the field to sel(getfield(x, :field), _ctx(args...)). This is the value of the risk measure when it is not nothing, else the threaded optimiser value, a solver, that _ctx finds by type in the tail. The slv fields use this tag, because their source is a threaded argument and not the prior. Do not put this tag and @pprop on one field.
Algorithm
The tag never expands, because @propagatable runs first and removes it. The steps below tell what happens to the tagged field, not what this macro does.
propagatable_parse_bodypeels the tag off the field, records the field name under:cprop, and puts the stripped field into the struct body. Neither Julia nor a wrapped macro such as@concreteever sees the tag.prop_channel_activereads the recorded name. This tag gates thepriorchannel alone, and an active channel makes@propagatableemit one method.prop_channel_pairsbuilds the keyword pair of the field for each emitted method, andprop_tag_exprgives the value:sel(x.field, _ctx(args...))._ctxfinds the value by type in the threaded tail, so the source is an argument and not the prior result.- The generated method builds the struct again with its keyword constructor, so every check of the constructor runs again on the propagated value.
Step 3 gives the meaning of the tag. @cprop comes after @pprop in the precedence of the prior channel. If a field carries both, @pprop wins and the field ignores the context.
The body of this macro raises an error. Julia runs it only when the tag is outside a @propagatable struct body, where no macro removed it.
Related
PortfolioOptimisers.@oprop — Macro
@oprop fieldField tag for a @propagatable struct body. It marks a composed child that only the observation channel reads. A cut of the observations, through obs_weights_view, recurses into the child. factory, port_opt_view and the prior selection do not read the tag.
Use @oprop for a child that reads the observations of the sample, when the factory channel must not reach it. The prior of an optimiser is an example. factory(opt, w) passes the portfolio weights w to the fees of the optimiser, and not to its prior, but a cut of the observations must reach the observation weights of the prior. A child that factory reaches carries @fprop, which the obs channel reads too, so it needs no second tag.
Algorithm
The tag never expands, because @propagatable runs first and removes it. The steps below tell what happens to the tagged field, not what this macro does.
propagatable_parse_bodypeels the tag off the field, records the field name under:oprop, and puts the stripped field into the struct body. Neither Julia nor a wrapped macro such as@concreteever sees the tag.prop_channel_activereads the recorded name. This tag gates theobschannel alone, and an active channel makes@propagatableemit one method.prop_channel_pairsbuilds the keyword pair of the field for theobsmethod, andprop_tag_exprgives the valueobs_weights_view(x.field, i), which recurses into the child on the observation axis. Every other channel keeps the value of the field.- The generated method builds the struct again with its keyword constructor, so every check of the constructor runs again on the propagated value.
The body of this macro raises an error. Julia runs it only when the tag is outside a @propagatable struct body, where no macro removed it.
Related
PortfolioOptimisers.asset_axis_fields — Function
asset_axis_fields(x) -> Tuple{Vararg{Symbol}}Return the names of the fields of x whose values lie on the asset axis of the data that x reads.
A child on the asset axis reads the same columns as its parent, so a UniverseSets in that child must name the same assets. assert_universe_axis_order walks these fields to find each such universe. A child on another axis, such as the factor prior of a FactorPrior, which reads the factor returns, is not on this list.
Algorithm
The method that Julia selects is the algorithm.
- A
@propagatablestruct with at least one@vpropfield: return the names of its@vpropfields, in the order of the declaration. The macro makes this method. A@vpropfield is a field thatport_opt_viewviews at the asset index, so the tag already states that the field lies on the asset axis. - Any other value: return the names of the fields whose declared type can hold an estimator, an algorithm or a vector. A
@concretestruct records the type of each value in a type parameter, so a field that holds a number, a matrix or anothinggives no name. The answer comes from the type alone, so the compiler computes it once for each type.
A struct with no @vprop field, such as a struct with a hand-written view, takes step 2, which reads all of its children. If such a struct holds a child on another axis, it must define its own method of this function, which leaves that child out. Otherwise the check reads the universe of the child against the asset names, and refuses a correct universe.
Arguments
x: The estimator, algorithm or value to read.
Returns
fields::Tuple{Vararg{Symbol}}: The names of the fields on the asset axis.
Related
Summary statistics
Some estimators and constraints reduce a vector to one number, such as its minimum, mean, median or maximum. Each type below names one reduction, and some of them take observation weights. vec_to_real_measure applies the reduction to a vector.
PortfolioOptimisers.factory — Method
factory(a, args...; kwargs...) -> a
factory(a::AbstractArray{<:Union{Nothing, AbstractEstimator, AbstractAlgorithm,
AbstractResult, StatsBase.CovarianceEstimator}},
args...; kwargs...) -> AbstractArrayRebuild an estimator, an algorithm or a result with runtime values. These two methods are the leaf and the array step of the traversal.
factory and port_opt_view are the two propagation mechanisms of this library. factory passes runtime values, such as prior moments, observation weights and previous portfolio weights, down a tree of composed structs. port_opt_view passes an index selection, a subset of the assets, down the same tree.
factory is a traversal, so it owns the identity on every leaf, as fmap in Functors.jl and adapt_structure in Adapt.jl do. A value that has no method of its own comes back with no change: a data field, a scalar, nothing, a set of observation weights and a covariance estimator of StatsBase. So a @propagatable struct sends each @fprop field to factory directly, whatever the field holds.
The array method is the one forwarding contract for every propagation field that holds an array of estimators, algorithms, results or covariance estimators. It applies factory to each element, and it forwards args... and kwargs... with no change. A family that accepts an array of them needs no method of its own. A family that needs more than the forward defines its own, more specific method. A concrete element type, through concrete_typed_array_if_abstract, is an example. An array of data, such as a vector of numbers, is a leaf, and it comes back with no change and with no copy.
Algorithm
The leaf method:
- Return
awith no change, and dropargs...andkwargs.... This method is the leaf of the recursion. Because of it, a call of the verb on a type with no tags returns the value and raises no error.
The array method:
- For each element
aiofa, callfactoryonai, and forwardargs...andkwargs...with no change. - Collect the results into a new array of the shape of
a, in the order ofa, and return it.
A @propagatable struct always has a generated method that is more specific than the leaf method. If the struct has at least one @fprop or @wprop field, that method builds the struct again with its keyword constructor. It sends each @fprop field through factory and each @wprop field through _wprop. If the struct has no such field, that method returns x.
The leaf method does not fill a nothing field. A weights field that must take the incoming weights when it holds nothing carries @wprop, and it goes to _wprop.
Arguments
a: Any value, which the leaf method returns with no change. For the array method, an array of estimators, algorithms, results, covariance estimators ornothing, which it rebuilds one element at a time.args...: Positional arguments. The leaf method ignores them, and the array method forwards them.kwargs...: Keyword arguments. The leaf method ignores them, and the array method forwards them.
Returns
a: The input with no change, for the leaf method.v::AbstractArray: The rebuilt elements, in an array of the shape ofa, for the array method.
Examples
julia> factory(nothing, 1, 2; x = 3)julia> factory([1.0, 2.0], 1, 2; x = 3)2-element Vector{Float64}: 1.0 2.0julia> factory(MeanValue())MeanValue w ┴ nothingRelated
PortfolioOptimisers.factory — Method
factory(a, args...; kwargs...) -> a
factory(a::AbstractArray{<:Union{Nothing, AbstractEstimator, AbstractAlgorithm,
AbstractResult, StatsBase.CovarianceEstimator}},
args...; kwargs...) -> AbstractArrayRebuild an estimator, an algorithm or a result with runtime values. These two methods are the leaf and the array step of the traversal.
factory and port_opt_view are the two propagation mechanisms of this library. factory passes runtime values, such as prior moments, observation weights and previous portfolio weights, down a tree of composed structs. port_opt_view passes an index selection, a subset of the assets, down the same tree.
factory is a traversal, so it owns the identity on every leaf, as fmap in Functors.jl and adapt_structure in Adapt.jl do. A value that has no method of its own comes back with no change: a data field, a scalar, nothing, a set of observation weights and a covariance estimator of StatsBase. So a @propagatable struct sends each @fprop field to factory directly, whatever the field holds.
The array method is the one forwarding contract for every propagation field that holds an array of estimators, algorithms, results or covariance estimators. It applies factory to each element, and it forwards args... and kwargs... with no change. A family that accepts an array of them needs no method of its own. A family that needs more than the forward defines its own, more specific method. A concrete element type, through concrete_typed_array_if_abstract, is an example. An array of data, such as a vector of numbers, is a leaf, and it comes back with no change and with no copy.
Algorithm
The leaf method:
- Return
awith no change, and dropargs...andkwargs.... This method is the leaf of the recursion. Because of it, a call of the verb on a type with no tags returns the value and raises no error.
The array method:
- For each element
aiofa, callfactoryonai, and forwardargs...andkwargs...with no change. - Collect the results into a new array of the shape of
a, in the order ofa, and return it.
A @propagatable struct always has a generated method that is more specific than the leaf method. If the struct has at least one @fprop or @wprop field, that method builds the struct again with its keyword constructor. It sends each @fprop field through factory and each @wprop field through _wprop. If the struct has no such field, that method returns x.
The leaf method does not fill a nothing field. A weights field that must take the incoming weights when it holds nothing carries @wprop, and it goes to _wprop.
Arguments
a: Any value, which the leaf method returns with no change. For the array method, an array of estimators, algorithms, results, covariance estimators ornothing, which it rebuilds one element at a time.args...: Positional arguments. The leaf method ignores them, and the array method forwards them.kwargs...: Keyword arguments. The leaf method ignores them, and the array method forwards them.
Returns
a: The input with no change, for the leaf method.v::AbstractArray: The rebuilt elements, in an array of the shape ofa, for the array method.
Examples
julia> factory(nothing, 1, 2; x = 3)julia> factory([1.0, 2.0], 1, 2; x = 3)2-element Vector{Float64}: 1.0 2.0julia> factory(MeanValue())MeanValue w ┴ nothingRelated
PortfolioOptimisers.factory — Method
factory(a, args...; kwargs...) -> a
factory(a::AbstractArray{<:Union{Nothing, AbstractEstimator, AbstractAlgorithm,
AbstractResult, StatsBase.CovarianceEstimator}},
args...; kwargs...) -> AbstractArrayRebuild an estimator, an algorithm or a result with runtime values. These two methods are the leaf and the array step of the traversal.
factory and port_opt_view are the two propagation mechanisms of this library. factory passes runtime values, such as prior moments, observation weights and previous portfolio weights, down a tree of composed structs. port_opt_view passes an index selection, a subset of the assets, down the same tree.
factory is a traversal, so it owns the identity on every leaf, as fmap in Functors.jl and adapt_structure in Adapt.jl do. A value that has no method of its own comes back with no change: a data field, a scalar, nothing, a set of observation weights and a covariance estimator of StatsBase. So a @propagatable struct sends each @fprop field to factory directly, whatever the field holds.
The array method is the one forwarding contract for every propagation field that holds an array of estimators, algorithms, results or covariance estimators. It applies factory to each element, and it forwards args... and kwargs... with no change. A family that accepts an array of them needs no method of its own. A family that needs more than the forward defines its own, more specific method. A concrete element type, through concrete_typed_array_if_abstract, is an example. An array of data, such as a vector of numbers, is a leaf, and it comes back with no change and with no copy.
Algorithm
The leaf method:
- Return
awith no change, and dropargs...andkwargs.... This method is the leaf of the recursion. Because of it, a call of the verb on a type with no tags returns the value and raises no error.
The array method:
- For each element
aiofa, callfactoryonai, and forwardargs...andkwargs...with no change. - Collect the results into a new array of the shape of
a, in the order ofa, and return it.
A @propagatable struct always has a generated method that is more specific than the leaf method. If the struct has at least one @fprop or @wprop field, that method builds the struct again with its keyword constructor. It sends each @fprop field through factory and each @wprop field through _wprop. If the struct has no such field, that method returns x.
The leaf method does not fill a nothing field. A weights field that must take the incoming weights when it holds nothing carries @wprop, and it goes to _wprop.
Arguments
a: Any value, which the leaf method returns with no change. For the array method, an array of estimators, algorithms, results, covariance estimators ornothing, which it rebuilds one element at a time.args...: Positional arguments. The leaf method ignores them, and the array method forwards them.kwargs...: Keyword arguments. The leaf method ignores them, and the array method forwards them.
Returns
a: The input with no change, for the leaf method.v::AbstractArray: The rebuilt elements, in an array of the shape ofa, for the array method.
Examples
julia> factory(nothing, 1, 2; x = 3)julia> factory([1.0, 2.0], 1, 2; x = 3)2-element Vector{Float64}: 1.0 2.0julia> factory(MeanValue())MeanValue w ┴ nothingRelated
PortfolioOptimisers.factory — Method
factory(a, args...; kwargs...) -> a
factory(a::AbstractArray{<:Union{Nothing, AbstractEstimator, AbstractAlgorithm,
AbstractResult, StatsBase.CovarianceEstimator}},
args...; kwargs...) -> AbstractArrayRebuild an estimator, an algorithm or a result with runtime values. These two methods are the leaf and the array step of the traversal.
factory and port_opt_view are the two propagation mechanisms of this library. factory passes runtime values, such as prior moments, observation weights and previous portfolio weights, down a tree of composed structs. port_opt_view passes an index selection, a subset of the assets, down the same tree.
factory is a traversal, so it owns the identity on every leaf, as fmap in Functors.jl and adapt_structure in Adapt.jl do. A value that has no method of its own comes back with no change: a data field, a scalar, nothing, a set of observation weights and a covariance estimator of StatsBase. So a @propagatable struct sends each @fprop field to factory directly, whatever the field holds.
The array method is the one forwarding contract for every propagation field that holds an array of estimators, algorithms, results or covariance estimators. It applies factory to each element, and it forwards args... and kwargs... with no change. A family that accepts an array of them needs no method of its own. A family that needs more than the forward defines its own, more specific method. A concrete element type, through concrete_typed_array_if_abstract, is an example. An array of data, such as a vector of numbers, is a leaf, and it comes back with no change and with no copy.
Algorithm
The leaf method:
- Return
awith no change, and dropargs...andkwargs.... This method is the leaf of the recursion. Because of it, a call of the verb on a type with no tags returns the value and raises no error.
The array method:
- For each element
aiofa, callfactoryonai, and forwardargs...andkwargs...with no change. - Collect the results into a new array of the shape of
a, in the order ofa, and return it.
A @propagatable struct always has a generated method that is more specific than the leaf method. If the struct has at least one @fprop or @wprop field, that method builds the struct again with its keyword constructor. It sends each @fprop field through factory and each @wprop field through _wprop. If the struct has no such field, that method returns x.
The leaf method does not fill a nothing field. A weights field that must take the incoming weights when it holds nothing carries @wprop, and it goes to _wprop.
Arguments
a: Any value, which the leaf method returns with no change. For the array method, an array of estimators, algorithms, results, covariance estimators ornothing, which it rebuilds one element at a time.args...: Positional arguments. The leaf method ignores them, and the array method forwards them.kwargs...: Keyword arguments. The leaf method ignores them, and the array method forwards them.
Returns
a: The input with no change, for the leaf method.v::AbstractArray: The rebuilt elements, in an array of the shape ofa, for the array method.
Examples
julia> factory(nothing, 1, 2; x = 3)julia> factory([1.0, 2.0], 1, 2; x = 3)2-element Vector{Float64}: 1.0 2.0julia> factory(MeanValue())MeanValue w ┴ nothingRelated
PortfolioOptimisers.factory — Method
factory(a, args...; kwargs...) -> a
factory(a::AbstractArray{<:Union{Nothing, AbstractEstimator, AbstractAlgorithm,
AbstractResult, StatsBase.CovarianceEstimator}},
args...; kwargs...) -> AbstractArrayRebuild an estimator, an algorithm or a result with runtime values. These two methods are the leaf and the array step of the traversal.
factory and port_opt_view are the two propagation mechanisms of this library. factory passes runtime values, such as prior moments, observation weights and previous portfolio weights, down a tree of composed structs. port_opt_view passes an index selection, a subset of the assets, down the same tree.
factory is a traversal, so it owns the identity on every leaf, as fmap in Functors.jl and adapt_structure in Adapt.jl do. A value that has no method of its own comes back with no change: a data field, a scalar, nothing, a set of observation weights and a covariance estimator of StatsBase. So a @propagatable struct sends each @fprop field to factory directly, whatever the field holds.
The array method is the one forwarding contract for every propagation field that holds an array of estimators, algorithms, results or covariance estimators. It applies factory to each element, and it forwards args... and kwargs... with no change. A family that accepts an array of them needs no method of its own. A family that needs more than the forward defines its own, more specific method. A concrete element type, through concrete_typed_array_if_abstract, is an example. An array of data, such as a vector of numbers, is a leaf, and it comes back with no change and with no copy.
Algorithm
The leaf method:
- Return
awith no change, and dropargs...andkwargs.... This method is the leaf of the recursion. Because of it, a call of the verb on a type with no tags returns the value and raises no error.
The array method:
- For each element
aiofa, callfactoryonai, and forwardargs...andkwargs...with no change. - Collect the results into a new array of the shape of
a, in the order ofa, and return it.
A @propagatable struct always has a generated method that is more specific than the leaf method. If the struct has at least one @fprop or @wprop field, that method builds the struct again with its keyword constructor. It sends each @fprop field through factory and each @wprop field through _wprop. If the struct has no such field, that method returns x.
The leaf method does not fill a nothing field. A weights field that must take the incoming weights when it holds nothing carries @wprop, and it goes to _wprop.
Arguments
a: Any value, which the leaf method returns with no change. For the array method, an array of estimators, algorithms, results, covariance estimators ornothing, which it rebuilds one element at a time.args...: Positional arguments. The leaf method ignores them, and the array method forwards them.kwargs...: Keyword arguments. The leaf method ignores them, and the array method forwards them.
Returns
a: The input with no change, for the leaf method.v::AbstractArray: The rebuilt elements, in an array of the shape ofa, for the array method.
Examples
julia> factory(nothing, 1, 2; x = 3)julia> factory([1.0, 2.0], 1, 2; x = 3)2-element Vector{Float64}: 1.0 2.0julia> factory(MeanValue())MeanValue w ┴ nothingRelated