Base moments: private API
Abstract moment types and fallbacks
The abstract types below are the roots of the moment estimators. The functions are the steps that many moment estimators share, such as the refusal of a variance estimator in a covariance slot, the choice of the observation window and its weights, and the centring of the returns.
PortfolioOptimisers.AbstractExpectedReturnsAlgorithm — Type
abstract type AbstractExpectedReturnsAlgorithm <: AbstractAlgorithmAbstract supertype for all expected returns algorithm types.
Every concrete or abstract type that is an algorithm of an expected returns estimator must subtype AbstractExpectedReturnsAlgorithm.
Interfaces
A subtype needs no method of its own. An expected returns estimator holds the algorithm in a field and dispatches on its type. Define the methods on the expected returns estimator that uses the algorithm.
Related
PortfolioOptimisers.AbstractMomentAlgorithm — Type
abstract type AbstractMomentAlgorithm <: AbstractAlgorithmAbstract supertype for the forms of the deviations of a moment from its target.
The family holds two forms. FullMoment keeps every deviation, and SemiMoment keeps the deviations below the target. A moment estimator or a moment risk measure bounds its alg field to this type, and it implements each form. So the bound refuses in the constructor an algorithm that the verbs do not implement.
An algorithm that selects something other than a form of the deviations is not a member. The Gerber, Smyth-Broby and Gerber IQ algorithms and the shrinkage targets are orthogonal to the two forms, so they subtype AbstractAlgorithm directly.
Interfaces
A form holds no data, and no verb takes it alone. A moment estimator holds the form in its alg field, and each verb of the estimator dispatches on the type of that field. So a new form needs a method of each verb of every type that bounds alg to AbstractMomentAlgorithm, and a method of coverage_comoment_deviations.
Related
PortfolioOptimisers.assert_covariance_estimator — Function
assert_covariance_estimator(ce, name::Symbol) -> nothing
assert_covariance_estimator(ce::AbstractVarianceEstimator, name::Symbol)Refuses a variance estimator in a slot that calls Statistics.cov or Statistics.cor.
AbstractVarianceEstimator subtypes AbstractCovarianceEstimator, so a field bound to StatsBase.CovarianceEstimator accepts it. But a variance estimator computes one marginal variance for each asset and no relation between two assets, and its cov and cor throw a MethodError. The configuration alone decides that every call of the slot fails. So the inner constructor of each such slot calls this function, and the refusal comes at the construction.
A slot that calls only Statistics.var or Statistics.std does not call this function, because a variance estimator is the estimator that it reads.
Algorithm
The method that Julia selects is the algorithm.
- Every value that is not an
AbstractVarianceEstimatorpasses. A covariance estimator, a matrix andnothingare examples. - An
AbstractVarianceEstimatorraises anArgumentError.
Arguments
ce: The value of the slot.name: The name of the slot, for the error message.
Validation
ceis not anAbstractVarianceEstimator. Otherwise, the function raises anArgumentErrorthat names the slot and the type ofce.
Returns
nothing.
Related
PortfolioOptimisers.gap_fill_value — Method
gap_fill_value(ce::StatsBase.CovarianceEstimator) -> NumberReturn the value that replaces a gapped cell of a sample before the sample goes to ce.
A gapped sample has a non-finite cell because the asset was absent at that observation, and not because a computation failed. A consumer that holds such a sample and a covariance estimator cannot know which value the estimator needs. The consumer calls this function, and the value depends on the estimator alone.
When the value is finite, the consumer writes it over every gapped cell before it gives the sample to the estimator. The estimator then gets a complete sample and no mask. When the value is not finite, the consumer keeps the gaps. It gives the active mask that explains them to Statistics.cov(ce, X; dims, active_mask), and an estimator that returns a non-finite value must implement that method.
The fallback value is zero. A plain moment estimator refuses a gapped sample, and zero is the neutral value of a standardised series. An estimator that accepts gaps returns NaN. That one method is all that such an estimator adds to this function.
A covariance estimator can hold another covariance estimator, so the value is recursive:
- An estimator that gives the sample and its keywords to its inner estimator with no change returns the value of its inner estimator.
PortfolioOptimisersCovarianceandCorrelationCovarianceare two of them. So a wrapper around an estimator that accepts gaps keeps the gaps. - An estimator that reads the sample before it calls its inner estimator keeps the fallback.
Covarianceis one of them, because its expected returns estimator reads the sample. It refuses the gap itself, whatever its inner estimator returns. - A
Covariancewith aCoveragePolicyreads the gaps itself, over the observations of each pair, so it returnsNaN. A wrapper around it keeps the gaps.
Arguments
ce: Covariance estimator.
Returns
fv::Number: The value of a gapped cell. It is zero for a plain estimator andNaNfor an estimator that accepts gaps.
Related
PortfolioOptimisers.moment_window_and_weights — Function
moment_window_and_weights(
X::VecNum_MatNum,
w::Option{<:ObsWeights},
args...;
dims::Int = 1,
kwargs...
) -> (VecNum_MatNum, Option{<:StatsBase.AbstractWeights})
moment_window_and_weights(
X::VecNum_MatNum,
w::Option{<:ObsWeights},
window::VecInt;
dims::Int = 1,
kwargs...
) -> (VecNum_MatNum, Option{<:StatsBase.AbstractWeights})Apply the observation window to the data, and resolve the observation weights over the windowed data.
The function takes the view of X over the observations that window indexes, and resolves the observation weights over that view. The caller resolves window with get_window before the call, so an Int window is already a range here.
Algorithm
- Without a
window,Xpasses through unchanged, and step 3 resolves the weights over the whole of it. - With a
window, take the view ofXover those observations. For a matrix that isview(X, window, :)whendims == 1, andview(X, :, window)whendims == 2. For a vector it isview(X, window). Indexwto the same observations withnothing_scalar_array_getindex. - Resolve the observation weights with
get_observation_weights, overwand theXof the step above. - Return that
Xand the resolvedw.
Arguments
X: Data matrix or vector.w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.- Either:
args: More positional arguments, which the method ignores.window: Observation window. An integer selects the lastwindowobservations, and a vector of indices selects those observations.
dims: Dimension along which the computation runs. The function ignores it whenXis a vector.kwargs: More keyword arguments, which the method ignores.
Returns
X::VecNum_MatNum: The data over the window, or all of the data when there is no window.w::Option{<:StatsBase.AbstractWeights}: The resolved observation weights over the same observations.
Related
PortfolioOptimisers.weighted_centre — Function
weighted_centre(X::MatNum, me::AbstractExpectedReturnsEstimator,
w::Option{<:ObsWeights}; dims::Int = 1, mean = nothing,
kwargs...) -> Union{Number, ArrNum}Resolve the centre of a moment estimator with the same observation weights as its deviations.
The observation weights of a moment estimator apply to its centre, and not only to its deviations. This function holds that rule, so SimpleVariance, Covariance, Coskewness and Cokurtosis compute their centre in the same way.
Algorithm
- When
meanis notnothing, return it unchanged. Use the keyword for a centre thatwdoes not describe. - When
wisnothing, returnStatistics.mean(me, X; dims = dims, kwargs...). - Otherwise, rebuild
mewithwthroughfactory, so that the centre has the weights of the deviations. Return the mean of the rebuilt estimator.
Step 2 makes the function faster and does not change the value. w comes from a field, so its type selects the branch. Without step 2, a windowed loop rebuilds the estimator tree of me once for each window.
Arguments
X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.me: Expected returns estimator.w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.dims: Dimension along which the computation runs.mean: Optional precomputed centre of the data.kwargs...: More keyword arguments for the expected returns estimator.
Returns
mu::Union{Number, ArrNum}: The centre, weighted bywwhenwis notnothing.
Related
PortfolioOptimisers.demean_returns — Function
demean_returns(X::MatNum, me::AbstractExpectedReturnsEstimator; dims::Int = 1, mean = nothing,
kwargs...) -> MatNumSubtracts the mean of each asset from the returns in X.
The expected returns estimator me computes the mean, unless the caller gives mean.
Algorithm
- Resolve the centre
muwithweighted_centre. Whenmeanisnothing, the estimator computesmu. Otherwisemuismean. The estimator uses its own weights, and this function adds no weights. - Subtract
mufromXby broadcast, and return the result.dimsis the axis of the observations, and the estimator shapesmualong the other axis. The broadcast then subtracts one value for each asset from every observation of that asset.
Arguments
X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.me: Expected returns estimator.dims: Dimension along which the computation runs.mean: Optional precomputed centre of the data.kwargs...: More keyword arguments for the expected returns estimator.
Returns
X::MatNum: The demeaned returns matrix.
Related
PortfolioOptimisers.cov2cor_nan! — Function
cov2cor_nan!(sigma::MatNum, s::VecNum = sqrt.(LinearAlgebra.diag(sigma))) -> MatNumRescale a covariance matrix to its correlation matrix in place, with a NaN diagonal entry for each asset whose correlation is not defined.
The correlation of asset $i$ with itself is $\sigma_{ii} / (s_i s_i)$. A zero standard deviation, the one of a constant return, makes it $0 / 0$. A standard deviation that is not finite, the one of an asset outside the Coverage Universe, makes it NaN too. StatsBase.cov2cor! writes one on the whole diagonal, so it gives such an asset a correlation of one with itself and NaN with every other asset. This function writes the NaN back on the diagonal. The row of the asset is then NaN at every entry, as the row of an asset that a distance reader refuses is, see DistanceReaderRefusalError. A matrix holds no data, so the function cannot find a constant whose variance rounding left above zero. The cor of an estimator that reads the data marks such an asset, see constant_column_correlation!.
Algorithm
- Rescale
sigmawithStatsBase.cov2cor!ands. - Write
NaNon the diagonal wherevers[i]is zero or not finite, withundefined_correlation_diagonal!.
Arguments
sigma: Covariance-like or correlation-like matrixassets × assets.s: The standard deviations, the square roots of the diagonal ofsigmaby default.
Returns
rho::MatNum: The input matrix, rescaled in place to a correlation matrix.
Related
PortfolioOptimisers.undefined_correlation_diagonal! — Function
undefined_correlation_diagonal!(rho::AbstractMatrix, s::VecNum) -> AbstractMatrixWrite NaN on the diagonal entry of each asset whose correlation with itself is not defined, in a correlation matrix whose diagonal a rescale set to one.
The correlation of asset $i$ with itself is $\sigma_{ii} / (s_i s_i)$. It is $0 / 0$ when the scale s[i] is zero, and NaN when s[i] is not finite. A standard deviation and a variance are zero together and finite together, so s can hold either of them. The rescale of StatsBase writes one on such an entry, and the entries of the row off the diagonal are already NaN.
Algorithm
- For each
iwhoses[i]is zero or not finite, writes[i] / s[i]onrho[i, i]. The quotient isNaNin the number type ofs. - Return
rho.
Arguments
rho: The correlation matrix,assets × assets. It must be mutable.s: The standard deviations or the variances of the assets.
Returns
rho::AbstractMatrix: The input matrix, with aNaNdiagonal entry for each undefined correlation.
Related
PortfolioOptimisers.constant_column_correlation! — Function
constant_column_correlation!(rho::MatNum, X::MatNum, w::Option{<:VecNum} = nothing) -> MatNumWrite NaN on the row and the column of each constant column of X, after an estimator computed the correlation matrix rho of X.
The correlation of a constant return is 0 / 0 with every asset, itself included. The library gives such an asset a NaN row and column, its diagonal entry included, so a distance reader refuses it, see DistanceReaderRefusalError. An estimator does not always give that row:
StatsBase.corkendallandStatsBase.corspearmangiveNaNat every other column and one on the diagonal.- The Pearson correlation of
StatsBasesubtracts a mean that can differ from the constant by one unit in the last place. The variance of the column is then about1e-38, not zero, and its correlations are rounding noise, notNaN. Cash at a constant return of0.0005gives such a column.
So the test reads the data, not rho or a variance. With observation weights, it reads the observations of positive weight alone, because the weighted moments do not read the others.
Algorithm
- Take the rows of
Xwhose weight inwis positive, or every row whenwisnothing. - For each column
iofXwhose entries on those rows are all equal, writezero(T) / zero(T)on rowiand columniofrho, whereTis the element type ofrho. - Return
rho.
Arguments
rho: The correlation matrix,assets × assets. It must be mutable.X: The data matrix,observations × assets.w: The observation weights, ornothing.
Returns
rho::MatNum: The input matrix, with aNaNrow and column for each constant column.
Related
PortfolioOptimisers.mark_constant_correlation! — Function
mark_constant_correlation!(est::StatsBase.SimpleCovariance, ce::AbstractCovarianceEstimator,
rho::AbstractMatrix, X::MatNum,
w::Option{<:StatsBase.AbstractWeights}; dims::Int = 1,
kwargs...) -> AbstractMatrix
mark_constant_correlation!(est::StatsBase.CovarianceEstimator, ce::AbstractCovarianceEstimator,
rho::AbstractMatrix, X::MatNum,
w::Option{<:StatsBase.AbstractWeights}; dims::Int = 1,
mean = nothing, kwargs...) -> AbstractMatrixGive each constant return the NaN row and column of an undefined correlation, in the correlation matrix rho that the inner estimator est of ce computed from X.
The Pearson correlation of a constant return is 0 / 0 with every asset, itself included, so the library gives the asset a NaN row and column, see cov2cor_nan!. The method depends on est:
StatsBase.SimpleCovariance, the Pearson correlation. The mean of a constant can differ from the constant by one unit in the last place. The variance is then about1e-38, not zero, and the row holds rounding noise, notNaN. So the method tests the data withconstant_column_correlation!, on the observations of positive weight.- Any other estimator. An estimator such as a shrinkage defines the dependence of a constant, and keeps its values. Where its matrix holds a
NaN, the method reads the variancesvfrom the diagonal of the covariance of the same fit. It writesNaNon the diagonal entry of each zero variance withundefined_correlation_diagonal!, becauseStatsBasecomputes a correlation ascov2cor!(cov(...)), which writes one on its diagonal. A matrix with noNaNneeds no second fit.
Arguments
est: The inner estimatorce.ce. The method dispatches on it.ce: Covariance estimator.rho: The correlation matrix,assets × assets. It must be mutable where the method writes.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.w: The observation weights, ornothing.dims: Dimension along which the computation runs.mean: Optional precomputed centre of the data.kwargs...: More keyword arguments for the covariance of the second method.
Returns
rho::AbstractMatrix: The input matrix, with theNaNentries of each constant return.
Related
Windowed estimator generation
The five windowed estimators have one shape: WindowedExpectedReturns, WindowedVariance, WindowedCovariance, WindowedCoskewness and WindowedCokurtosis. Each wraps an inner estimator, keeps only the last observations of the sample, and passes every moment call to the inner estimator. The macro @windowed_estimator writes each of them from one declaration. It writes the struct, its constructor, its factory and port_opt_view methods, the methods that pass each moment call on, and their docstrings.
The entries below are the macro and the functions it calls when it expands. You use the five estimators, and never call these directly.
PortfolioOptimisers.WINDOWED_ESTIMATOR_KEYS — Constant
WINDOWED_ESTIMATOR_KEYSThe assignment keys that a @windowed_estimator body accepts, in addition to the one field::Type = default line. The macro refuses every other key at macro-expansion time, with a did_you_mean suggestion. So a mistyped key raises an error, and cannot make a wrong docstring or omit a forwarding method.
Related
PortfolioOptimisers.WINDOWED_ESTIMATOR_INPUTS — Constant
WINDOWED_ESTIMATOR_INPUTSThe input types that a forward entry of @windowed_estimator can declare. MatNum makes the matrix forwarding method and the Asset Panel forwarding method of the same generic. The matrix method passes dims and iv to windowed_preamble. VecNum makes the vector forwarding method.
Related
PortfolioOptimisers.@windowed_estimator — Macro
@windowed_estimator Name <: Super begin
field::FieldType = Default()
noun = "Noun"
forward = [generic(::MatNum; mean) => :ret_key, ...]
doctest = """..."""
endDeclare a windowed moment estimator, which applies an inner moment estimator to a window of observations.
The windowed estimator binds the observation weights to the window. The inner estimator computes the moment in the same way as without a window.
One call of the macro declares all the parts of the windowed estimator:
- The
@propagatable@concretestruct. Its fields are the inner estimator tagged@fprop @vprop,wtagged@wprop,window,rule, and acachetagged@fprop @vpropthat holds a partial-fit state. - The two constructors with their validation.
- One forwarding method for each
forwardentry, and one Asset Panel method for each matrix entry. - The
exportof the type, and every docstring.
The library has five nominal types and not one parametric Windowed{E}. Each type implements a different generic, and must subtype a different abstract estimator, such as AbstractCovarianceEstimator or CoskewnessEstimator. Dispatch across the library reads these supertypes, and a Julia struct cannot take its supertype from a type parameter. This macro keeps the five types the same in every other part.
Body
field::FieldType = Default(): The inner estimator. The field name is also itsfield_dictkey and the argument name of every generated method. So it must follow the naming convention of the library, which usesme,ce,ve,skeandkte.noun: The capitalised noun phrase of the moment, for example"Expected returns". All the generated prose uses it.forward: One mini-signature for each generic to forward, with theret_dictkeys of its return values. Ameanin the mini-signature makesmeana named keyword of the generated method. Without it,meangoes intokwargs...and from there towindowed_preamble.doctest: The body of thejldoctestblock of the# Examplessection, without its fences.
At macro-expansion time, the macro refuses an unknown key, a wrong forward entry, and an unknown key of field_dict or ret_dict. The error for an unknown key ends with a did_you_mean suggestion.
Algorithm
- Read
nameandsuperfrom the header. - Read the body once.
windowed_parse_fieldparses the onefield::Type = defaultline, and returnsfield,ftypeanddefault. Thenoun,forwardanddoctestlines bind their values. Any other key raises an error. - Parse every entry of
forwardwithwindowed_parse_forward, givingspecs. Append one:AssetPanelcopy of eachMatNumentry, so every matrix generic also gets its Asset Panel method. - Render one cross-reference per entry of
specswithwindowed_method_ref, givingrefs. - For each entry of
specs, build one documented forwarding method:windowed_method_docwrites its docstring, andwindowed_method_defwrites its body. Each method's# Relatedsection lists therefsof its siblings and not its own. - Build
structexpr, the@concretestruct. It declares the inner estimator tagged@fprop @vprop,wtagged@wprop,windowandrulewith no tag, andcachetagged@fprop @vprop, each with its livefield_dictlookup, and the inner constructor that validateswandwindow. When an entry ofspecsforwardscovorcor, the inner constructor also refuses a variance estimator as the inner estimator, with the check thatwindowed_relation_checkbuilds. - Build
kwctor, the keyword constructor, whose defaults aredefault,nothing,nothing,RollingWindow()andnothing. - Write the type's docstring with
windowed_type_doc, and attach it tostructexprwrapped in@propagatable @concrete. - Return the escaped block: the documented struct,
kwctor, the forwarding methods, and theexportofname.
Validation
- The header reads
Name <: Super, andNameis aSymbol. - The declaration body is a
begin ... endblock, and every line of it is an assignment. - At most one
field::Type = defaultline appears. - Every other key names an entry of
WINDOWED_ESTIMATOR_KEYS. An unknown key raises with asuggest_declared_keysuffix. - All four of
field::Type = default,noun,forwardanddoctestare present. nounanddoctestare string literals.forwardis a vector, and it declares at least one generic.- Every failure above raises an
ArgumentErrorthroughwindowed_estimator_error, at macro-expansion time.
Returns
ex::Expr: The escaped block that declares the whole family member.
Examples
@windowed_estimator WindowedVariance <: AbstractVarianceEstimator begin ve::AbstractVarianceEstimator = SimpleVariance() noun = "Variance" forward = [Statistics.var(::MatNum; mean) => :vararr, Statistics.var(::VecNum; mean) => :varnum] doctest = """ julia> WindowedVariance() ... """endRelated
PortfolioOptimisers.windowed_parse_field — Function
windowed_parse_field(ex) -> Tuple{Symbol, Any, Any}
Parse the field::Type = default line of a @windowed_estimator body into the field name of the inner estimator, its declared type, and its default in the keyword constructor.
The field name is also the field_dict key of the generated field docstring, and the argument name of every generated forwarding method. So it must follow the naming convention of the library, which uses me, ce, ve, ske and kte.
Algorithm
- Read the field name and its declared type from the left of the
=, givingnameandtype. - Check
nameagainstfield_dictwithwindowed_estimator_check_key. - Return
name,type, and the right of the=, which is the keyword-constructor default.
Arguments
ex: The onefield::Type = defaultline of the declaration body.
Validation
exreadsfield::Type = default. Any other shape raises.- The field name is a
Symbol. Any other name raises. - The field name names an entry of
field_dict.
Returns
(name, type, default): The field name, its declared type, and its keyword-constructor default.
Related
PortfolioOptimisers.windowed_parse_forward — Function
windowed_parse_forward(
ex
) -> Tuple{Any, Any, Bool, Vector{Symbol}}
Parse one forward entry of a @windowed_estimator body, such as generic(::MatNum; mean) => :ret_key. The parts are the forwarded generic, its input type, a flag for a mean keyword, and the ret_dict keys of its return values.
A mean in the mini-signature keeps mean out of the forwarded kwargs.... Without it, mean goes into kwargs... and from there to windowed_preamble.
Algorithm
- Split
exat the=>, giving the mini-signaturesigand the return keysrets. - Read the forwarded generic from the head of
sig, givinggen. - Read each argument of
sig. Ameankeyword setshas_mean. The one positional argument type setsinput. - Check
inputagainstWINDOWED_ESTIMATOR_INPUTS. - Check every entry of
retsagainstret_dictwithwindowed_estimator_check_key, and collect the entries intokeys_. - Return
gen,input,has_meanandkeys_.
Arguments
ex: One entry of theforwardvector of the declaration body.
Validation
exreadsgeneric(::Input[; mean]) => :ret_key, or=> (:k1, :k2)for a tuple return. Any other shape raises.- The left of the
=>is a call. meanis the only keyword that the mini-signature can name.- The mini-signature declares exactly one positional argument type.
- That type names an entry of
WINDOWED_ESTIMATOR_INPUTS. - Every return key is a quoted symbol, and names an entry of
ret_dict.
Returns
(gen, input, has_mean, keys_): The forwarded generic, its input type, whether the mini-signature namesmean, and theret_dictkeys of its return values.
Related
PortfolioOptimisers.windowed_relation_check — Function
windowed_relation_check(
field::Symbol,
specs
) -> Union{Nothing, Expr}
Build the check that the inner constructor of a generated windowed estimator runs on its inner estimator.
A windowed estimator that forwards cov or cor calls them on its inner estimator, and a variance estimator has neither. So its inner constructor refuses a variance estimator with assert_covariance_estimator. A windowed estimator that forwards only mean, var, std or a higher moment needs no such check. WindowedVariance holds a variance estimator on purpose.
Algorithm
- Read the last name of the generic of each entry of
specs. ForStatistics.cov, it iscov. For a bare name, it is the name itself. - When one of these names is
covorcor, return the callassert_covariance_estimator(field, :field). - Otherwise, return
nothing, which adds no statement to the constructor.
Arguments
field::Symbol: Name of the inner estimator's field.specs: The parsedforwardentries, aswindowed_parse_forwardreturns them.
Returns
check::Option{Expr}: The call to put in the inner constructor, ornothing.
Related
PortfolioOptimisers.windowed_estimator_check_key — Function
windowed_estimator_check_key(
key::Symbol,
dict::AbstractDict,
what::AbstractString
) -> Symbol
Check that key names an entry of dict. When it does not, raise an error that ends with a did_you_mean suggestion. The message names the table what.
Arguments
key::Symbol: The key the declaration wrote.dict::AbstractDict: The table the key must name an entry of.what::AbstractString: The name of that table. The message contains it.
Validation
haskey(dict, key). For a key that names no entry, the function raises throughwindowed_estimator_error, and the message ends with the suffix fromsuggest_declared_key.
Returns
key::Symbol: The key, unchanged, so a caller can check the key and bind it in one expression.
Related
PortfolioOptimisers.windowed_estimator_error — Function
windowed_estimator_error(msg::AbstractString)
Throw an ArgumentError at macro-expansion time for a wrong @windowed_estimator declaration.
Arguments
msg::AbstractString: The body of the message. The function puts@windowed_estimator:before it, so every message of the macro starts with the same prefix.
Validation
- The function always raises, so it never returns to its caller.
Related
PortfolioOptimisers.windowed_type_doc — Function
windowed_type_doc(
name::Symbol,
super,
field::Symbol,
ftype,
default,
noun::AbstractString,
doctest::AbstractString,
methods::Vector{String},
refuses_variance::Bool
) -> Expr
Build the type docstring of a generated windowed estimator as an interpolation AST.
The DocStringExtensions abbreviations and the dictionary lookups stay live, as in windowed_method_doc.
Algorithm
- Read the name of the inner estimator from
defaultintoinner_ref. For a call such asSimpleVariance(), the name is the head of the call. For a bare name, it is the name itself. - Start
partswith the liveDocStringExtensions.TYPEDEFabbreviation, the two summary sentences, the# Fieldsheading, and the liveDocStringExtensions.FIELDSabbreviation. - Push the
# Constructorssection and the keyword signature built fromname,field,ftypeanddefault. Then push the## Validationsubsection, with the liveval_dict[:oow]lookup and the window rule. Whenrefuses_varianceistrue, the liveval_dict[:ce_cov]lookup comes first. - Push the three propagation subsections,
## Propagated parameters,## View parametersand## Observation weight parameters. Each one namesfield,wandcacheas the tags of the generated struct declare them. - Push the
# Examplessection, fencingdoctestas ajldoctestblock. - Push the
# Relatedheading, the supertype,inner_ref, every entry ofmethods, the two window rules, and the four shared functions that the type implements:factory,port_opt_view,obs_weights_viewandwindowed_preamble. - Return
partswrapped inExpr(:string, ...), so every lookup stays live.
Arguments
name::Symbol: Name of the windowed estimator type.super: Its supertype.field::Symbol: Name of the inner estimator's field.ftype: Declared type of that field.default: Its keyword-constructor default.noun::AbstractString: The capitalised noun phrase of the moment. The generated prose uses it.doctest::AbstractString: The body of thejldoctestblock of the# Examplessection, without its fences.methods::Vector{String}: Cross-references to the generated methods of the type, fromwindowed_method_ref.refuses_variance::Bool:truewhen the type forwardscovorcor, so its inner constructor refuses a variance estimator throughassert_covariance_estimator.
Returns
doc::Expr: AnExpr(:string, ...)holding the docstring, with every abbreviation and lookup left unevaluated.
Related
PortfolioOptimisers.windowed_method_ref — Function
windowed_method_ref(
gen,
field::Symbol,
name::Symbol,
input::Symbol
) -> String
Render the generic(field::Name, X::Input) reference to one generated forwarding method. The # Related sections of the type and of the other generated methods use it.
The reference leaves out the keyword arguments. Documenter resolves an @ref by the positional signature of the method, and the positional types are enough to find one method. The panel method has a third positional argument, pnl::Option{<:AssetPanel}, after X::MatNum.
Arguments
gen: The forwarded generic.field::Symbol: Name of the inner estimator's field, which is also the argument name of the generated method.name::Symbol: Name of the windowed estimator type.input::Symbol: Input kind of the generated method,:MatNum,:VecNumor:AssetPanel.
Returns
ref::String: A Documenter cross-reference to the generated method. It links the code spangen(field::Name, X::Input)to that method.
Related
PortfolioOptimisers.windowed_method_sig — Function
windowed_method_sig(
gen,
field::Symbol,
name::Symbol,
input::Symbol,
has_mean::Bool
) -> String
Render the signature line of the docstring of one generated forwarding method.
Algorithm
- For the vector input, return
gen(field::Name, X::VecNum), with; mean = nothingwhenhas_meanis set. - Otherwise open
gen(field::Name, X::MatNum, addpnl::Option{<:AssetPanel}for the panel input, and add the keywords:dims, thenmeanwhenhas_meanis set, thenivfor the matrix input alone, thenkwargs.... The panel method takesivinkwargs....
Arguments
gen: The forwarded generic.field::Symbol: Name of the inner estimator's field, which is also the argument name of the generated method.name::Symbol: Name of the windowed estimator type.input::Symbol: Input kind of the generated method,:MatNum,:VecNumor:AssetPanel.has_mean::Bool:truewhen the method declares ameankeyword.
Returns
sig::String: The indented signature line.
Related
PortfolioOptimisers.windowed_method_doc — Function
windowed_method_doc(
gen,
field::Symbol,
name::Symbol,
input::Symbol,
has_mean::Bool,
ret_keys::Vector{Symbol},
noun::AbstractString,
siblings::Vector{String}
) -> Expr
Build the docstring for one generated forwarding method as an interpolation AST.
The function returns an Expr(:string, ...) and not a String, so each lookup of arg_dict and ret_dict stays a live part of the DocStr, as a hand-written $(arg_dict[:dims]) does.
Algorithm
- Build the signature line
sigwithwindowed_method_sig. The matrix signature hasdims,ivandkwargs..., and the vector signature has none of them. The panel signature haspnlafterX, and takesivinkwargs.... Each signature also hasmeanwhenhas_meanis set. - Start
partswithsig, the summary sentences, the steps of the algorithm of the generated method, and the arguments heading with its two prose bullets. The panel method has one more step, the cut of the panel. The summary names the generic and not the noun of the type, becausestdon aWindowedVariancecomputes a standard deviation and not a variance. - For the panel input, push the
arg_dict[:pnl_moment]lookup as a live expression. - For the matrix and panel inputs, push the
arg_dict[:dims]lookup. - When
has_meanis set, push themeanbullet. - For the matrix and panel inputs, push the
arg_dict[:oiv]lookup and thekwargs...bullet. - Push the returns heading, then one live
ret_dictlookup per entry ofret_keys. - Push the related heading, the type, every entry of
siblings, andwindowed_preamble. - Return
partswrapped inExpr(:string, ...), so every lookup stays live.
Arguments
gen: The forwarded generic.field::Symbol: Name of the inner estimator's field, which is also the argument name of the generated method.name::Symbol: Name of the windowed estimator type.input::Symbol: Input kind of the generated method,:MatNum,:VecNumor:AssetPanel.has_mean::Bool:truewhen the method declares ameankeyword.ret_keys::Vector{Symbol}: Theret_dictkeys documenting the return values.noun::AbstractString: The capitalised noun phrase of the moment. The generated prose uses it.siblings::Vector{String}: Cross-references to the other generated methods of the type, fromwindowed_method_ref.
Returns
doc::Expr: AnExpr(:string, ...)holding the docstring, with every dictionary lookup left unevaluated.
Related
PortfolioOptimisers.windowed_method_def — Function
windowed_method_def(
gen,
field::Symbol,
name::Symbol,
input::Symbol,
has_mean::Bool
) -> Expr
Build one generated forwarding method. The method resolves the window with windowed_preamble, and then calls the method of the inner estimator.
Algorithm
- Build the three field accesses that the body reads.
field.fieldis the inner estimator,field.wholds the observation weights, andfield.windowholds the window. - For the vector input, build a method whose only keyword is
mean, and only whenhas_meanis set. Its body bindsinnerand the windowedXwithwindowed_preamble, and returnsgenof the two. Return this method. - Build the keyword list of the signature. It holds
dims, thenmeanwhenhas_meanis set, thenivandkwargs.... The panel method names noiv. As in the panel methods of the moment verbs,ivcomes inkwargs..., and the preamble binds it from there. - Build the matching keyword list of the inner call. It has the same names, and passes each value on. It passes the windowed
iv, and the keywordskw, in which the two universe masks are cut to the window. - For the panel input, the positional arguments are
field,Xandpnl, and the body opens with the cut ofpnlto the window bywindowed_panel. For the matrix input, they arefieldandX. - Build the body: one call to
windowed_preamblethat bindsinner, the windowedX,ivandkw, then areturnofgenapplied toinner, thatX, and the cutpnlfor the panel input. - Return the whole
Expr(:function, ...).
Arguments
gen: The forwarded generic.field::Symbol: Name of the inner estimator's field, which is also the argument name of the generated method.name::Symbol: Name of the windowed estimator type.input::Symbol: Input kind of the generated method,:MatNum,:VecNumor:AssetPanel.has_mean::Bool:truewhen the method declares ameankeyword.
Returns
def::Expr: TheExpr(:function, ...)of the forwarding method.
Related
Available-case co-moments
An available-case fit estimates each asset from the rows where its return is finite and the asset is active. The two functions below build the block that the available-case coskewness and cokurtosis read. A co-moment reads every deviation from the mean with FullMoment, or only the negative deviations with SemiMoment, and coverage_comoment_deviations is the one step where the two differ.
PortfolioOptimisers.coverage_comoment_deviations — Function
coverage_comoment_deviations(alg::FullMoment, Xo::MatNum, mu::VecNum) -> MatNum
coverage_comoment_deviations(alg::SemiMoment, Xo::MatNum, mu::VecNum) -> MatNumCentres an available-case block on the mean of each asset, and clips the deviations when the moment algorithm is a semi-moment.
The two moment algorithms change only this step of a higher-order available-case fit, so coverage_comoment_block has one body for both. FullMoment keeps every deviation, and SemiMoment clips every positive deviation to zero. The plain path without a Coverage Policy does the same.
Arguments
alg: Moment algorithm of the estimator.Xo: The oriented block,observations × assets, whose invalid entries are still non-finite.mu: Each asset's available-case mean, over its own finite and active observations.
Returns
Y::MatNum: The deviations, non-finite whereverXois.
Related
PortfolioOptimisers.coverage_comoment_block — Function
coverage_comoment_block(
alg::AbstractMomentAlgorithm,
cvg::CoveragePolicy,
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
active_mask::Union{Nothing, AbstractMatrix{<:Bool}},
dims::Int64
) -> Tuple{Any, Any, Any, Any, Any, Union{Nothing, BitVector}}
Builds the pairwise expansions and the admission mask a higher-order available-case fit reads.
The available-case arms of coskewness and of cokurtosis both call this function. The third and the fourth co-moment differ only in the pair of expansions that they multiply. This function returns both expansions, and each order takes its own product. Neither order folds, so the function reads the whole block and keeps no state.
The function centres the deviations on the available-case mean of each asset, and then sets the invalid entries to zero. After this step, an observation at which an asset has no quote adds nothing to the numerator or to the denominator of a cell of that asset. The mask expansion zc is the same product over the mask, so the denominator of a cell is the number of observations at which every asset of that cell is valid.
Algorithm
- Read the valid entries, the per-asset available-case mean and the per-asset bookkeeping of the block with
coverage_valid_block. - Centre and clip the block with
coverage_comoment_deviations, and zero the invalid entries. - Take the valid mask as integers,
Mi. - Build the pairwise expansions
zof the deviations andzcof the mask, bothobservations × assets². - Admit the assets with
coverage_admission, against each asset's own observation count.
Arguments
alg: Moment algorithm of the estimator.cvg: The policy the estimator carries.X: Data matrix.active_mask: The active mask of the Asset Panel over the window, ornothing.dims: Dimension along which the computation runs.
Returns
(Xo, Y, Mi, z, zc, cmsk)::Tuple: The oriented block, the zeroed deviations, the valid mask as integers, the pairwise expansion of each, and the admitted assets ornothing.
Related