Vector to scalar measures
Summary statistics
PortfolioOptimisers.VectorToScalarMeasure — Type
abstract type VectorToScalarMeasure <: AbstractAlgorithmAbstract supertype for algorithms that reduce a vector of real values to one real value.
A VectorToScalarMeasure reduces a vector of real numbers to a scalar, for example its minimum, mean, median or maximum. The constraint generation and the centrality constraints use these measures to reduce a metric of each asset to one value.
Interfaces
To implement a new vector-to-scalar measure, subtype VectorToScalarMeasure and implement this method:
Reduction method
vec_to_real_measure(measure::VectorToScalarMeasure, val::VecNum) -> Number: Reducesvalto a single scalar.
Arguments
measure: An instance of the concrete subtype.val: Vector of real values to reduce.
Returns
score::Number: The scalar result.
Orientation method
bigger_is_better(measure::VectorToScalarMeasure) -> Bool: Optional. States whether a bigger result is a better score, when aPanelFieldScorerwith nobibof its own scores the assets with the measure. The fallback answerstrue, as for a statistic of location. Add a method that answersfalsefor a statistic whose smaller values are better, asStdValueandVarValuedo.
Arguments
measure: An instance of the concrete subtype.
Returns
bib::Bool:truewhen a bigger result is better.
Related
PortfolioOptimisers.MinValue — Type
struct MinValue <: VectorToScalarMeasureAlgorithm that reduces a vector of real values to its minimum.
Mathematical definition
\[\begin{align} \mathrm{MinValue}(\boldsymbol{v}) &= \underset{i}{\min}\ v_{i}\,. \end{align}\]
Where:
- $\boldsymbol{v}$: The vector to reduce, of length $n$.
- $v_{i}$: Its $i$-th entry, $i = 1,\ldots,n$.
The reduction reads no weights. A call of factory with observation weights returns it with no change.
Constructors
MinValue() -> MinValueExamples
julia> PortfolioOptimisers.vec_to_real_measure(MinValue(), [1.2, 3.4, 0.7])0.7Related
PortfolioOptimisers.MeanValue — Type
struct MeanValue{__T_w} <: VectorToScalarMeasureAlgorithm that reduces a vector of real values to its mean, with or without weights.
Mathematical definition
\[\begin{align} \mathrm{MeanValue}(\boldsymbol{v}) &= \frac{1}{n} \sum_{i=1}^{n} v_{i}\,, &&w = \mathrm{nothing}\,, \\ \mathrm{MeanValue}(\boldsymbol{v}) &= \frac{\sum_{i=1}^{n} w_{i} v_{i}}{\sum_{i=1}^{n} w_{i}}\,, &&\mathrm{otherwise}\,. \end{align}\]
Where:
- $\boldsymbol{v}$: The vector to reduce, of length $n$.
- $v_{i}$: Its $i$-th entry, $i = 1,\ldots,n$.
- $w_{i}$: The $i$-th observation weight, from the field
w.
The weighted form divides by the total weight, so a weight vector multiplied by a positive constant gives the same value. w must have one entry for each entry of $\boldsymbol{v}$.
Fields
w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.
Constructors
MeanValue(; w::Option{<:ObsWeights} = nothing,) -> MeanValueKeywords correspond to the struct's fields.
Validation
- If
wis notnothing,!isempty(w).
Propagated parameters
factory passes its arguments on to this @wprop field:
w: Replaced with the incomingObsWeights.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
w: Indexed to the selected observations throughobs_weights_view.
Examples
julia> PortfolioOptimisers.vec_to_real_measure(MeanValue(), [1.2, 3.4, 0.7])1.7666666666666666Related
PortfolioOptimisers.MedianValue — Type
struct MedianValue{__T_w} <: VectorToScalarMeasureAlgorithm that reduces a vector of real values to its median, with or without weights.
Mathematical definition
\[\begin{align} \mathrm{MedianValue}(\boldsymbol{v}) &= Q_{\boldsymbol{v}}(0.5)\,, \\ \mathrm{MedianValue}(\boldsymbol{v}) &= Q_{\boldsymbol{v}, \boldsymbol{w}}(0.5)\,. \end{align}\]
Where:
- $\boldsymbol{v}$: The vector to reduce, of length $n$.
- $\boldsymbol{w}$: The observation weights, from the field
w. The first line is the casew = nothing. - $Q_{\boldsymbol{v}}(p)$: The $p$-quantile of $\boldsymbol{v}$.
- $Q_{\boldsymbol{v}, \boldsymbol{w}}(p)$: The weighted $p$-quantile of $\boldsymbol{v}$, as
StatsBasedefines it.
Both forms are quantiles, and both interpolate. Neither is an order statistic, so the result is not always an entry of $\boldsymbol{v}$. On a vector of even length, the unweighted form takes the average of the two middle entries. The weighted form interpolates between the two entries on each side of half the total weight.
Fields
w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.
Constructors
MedianValue(; w::Option{<:ObsWeights} = nothing,) -> MedianValueKeywords correspond to the struct's fields.
Validation
- If
wis notnothing,!isempty(w).
Propagated parameters
factory passes its arguments on to this @wprop field:
w: Replaced with the incomingObsWeights.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
w: Indexed to the selected observations throughobs_weights_view.
Examples
julia> PortfolioOptimisers.vec_to_real_measure(MedianValue(), [1.2, 3.4, 0.7])1.2Related
PortfolioOptimisers.MaxValue — Type
struct MaxValue <: VectorToScalarMeasureAlgorithm that reduces a vector of real values to its maximum.
Mathematical definition
\[\begin{align} \mathrm{MaxValue}(\boldsymbol{v}) &= \underset{i}{\max}\ v_{i}\,. \end{align}\]
Where:
- $\boldsymbol{v}$: The vector to reduce, of length $n$.
- $v_{i}$: Its $i$-th entry, $i = 1,\ldots,n$.
The reduction reads no weights. A call of factory with observation weights returns it with no change.
Constructors
MaxValue() -> MaxValueExamples
julia> PortfolioOptimisers.vec_to_real_measure(MaxValue(), [1.2, 3.4, 0.7])3.4Related
PortfolioOptimisers.StdValue — Type
struct StdValue{__T_w, __T_corrected} <: VectorToScalarMeasureAlgorithm that reduces a vector of real values to its standard deviation, with or without weights. The default corrected = true works without weights. With a plain StatsBase.Weights, it raises an ArgumentError, because that type declares no bias correction. Pass an AnalyticWeights, a FrequencyWeights or a ProbabilityWeights, or set corrected = false.
Mathematical definition
\[\begin{align} \mathrm{StdValue}(\boldsymbol{v}) &= \sqrt{\mathrm{VarValue}(\boldsymbol{v})}\,. \end{align}\]
Where:
- $\boldsymbol{v}$: The vector to reduce, of length $n$.
- $\mathrm{VarValue}(\boldsymbol{v})$: The variance under the same
wand the samecorrected, whose four denominatorsVarValuestates.
corrected selects the denominator of the variance, and the square root keeps that choice. Without weights, the default corrected = true divides by $n - 1$.
Fields
w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.
corrected: Iftrue, the estimator applies the Bessel correction.StatisticsorStatsBaseapplies it, with the divisor that each weight type defines.
Constructors
StdValue(; w::Option{<:ObsWeights} = nothing, corrected::Bool = true,) -> StdValueKeywords correspond to the struct's fields.
Validation
- If
wis notnothing,!isempty(w).
Propagated parameters
factory passes its arguments on to this @wprop field:
w: Replaced with the incomingObsWeights.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
w: Indexed to the selected observations throughobs_weights_view.
Examples
julia> PortfolioOptimisers.vec_to_real_measure(StdValue(), [1.2, 3.4, 0.7])1.4364307617610164Related
VectorToScalarMeasureMeanValueVarValue: the four denominators thatcorrectedand the type ofwselect.StandardisedValue: callsStatistics.stdwith ameankeyword, so the deviation is about the mean that itsmvgives.vec_to_real_measurefactoryobs_weights_view
PortfolioOptimisers.VarValue — Type
struct VarValue{__T_w, __T_corrected} <: VectorToScalarMeasureAlgorithm that reduces a vector of real values to its variance, with or without weights. A plain StatsBase.Weights declares no bias correction, so the default corrected = true with it raises an ArgumentError and returns no value. Pass one of the three weight types below that have a correction, or set corrected = false.
Mathematical definition
\[\begin{align} \mathrm{VarValue}(\boldsymbol{v}) &= \frac{1}{d} \sum_{i=1}^{n} w_{i} \left(v_{i} - \bar{v}\right)^{2}\,, \\ \bar{v} &= \frac{\sum_{i=1}^{n} w_{i} v_{i}}{\sum_{i=1}^{n} w_{i}}\,. \end{align}\]
Where:
- $\boldsymbol{v}$: The vector to reduce, of length $n$.
- $w_{i}$: The $i$-th observation weight. The unweighted case is $w_{i} = 1$.
- $\bar{v}$: The mean of $\boldsymbol{v}$ under those weights.
- $d$: The denominator, which
correctedand the type ofwtogether select.
$d$ takes one of four values:
w = nothing: $d = n - 1$ whencorrectedistrue, and $d = n$ when it isfalse.w::AnalyticWeights: $d = \sum w_{i} - \sum w_{i}^{2} / \sum w_{i}$ whencorrectedistrue.w::FrequencyWeights: $d = \sum w_{i} - 1$ whencorrectedistrue.w::ProbabilityWeights: $d = \left(\sum w_{i}\right)(m - 1) / m$ whencorrectedistrue, where $m$ is the count of non-zero weights.
With corrected = false, every weighted case takes $d = \sum w_{i}$.
The type of $\boldsymbol{w}$ selects $d$, not its values. So two weight vectors with the same values and different types give different variances.
Fields
w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.
corrected: Iftrue, the estimator applies the Bessel correction.StatisticsorStatsBaseapplies it, with the divisor that each weight type defines.
Constructors
VarValue(; w::Option{<:ObsWeights} = nothing, corrected::Bool = true,) -> VarValueKeywords correspond to the struct's fields.
Validation
- If
wis notnothing,!isempty(w).
Propagated parameters
factory passes its arguments on to this @wprop field:
w: Replaced with the incomingObsWeights.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
w: Indexed to the selected observations throughobs_weights_view.
Examples
julia> PortfolioOptimisers.vec_to_real_measure(VarValue(), [1.2, 3.4, 0.7])2.0633333333333335Related
PortfolioOptimisers.SumValue — Type
struct SumValue <: VectorToScalarMeasureAlgorithm that reduces a vector of real values to its sum.
Mathematical definition
\[\begin{align} \mathrm{SumValue}(\boldsymbol{v}) &= \sum_{i=1}^{n} v_{i}\,. \end{align}\]
Where:
- $\boldsymbol{v}$: The vector to reduce, of length $n$.
- $v_{i}$: Its $i$-th entry, $i = 1,\ldots,n$.
The reduction reads no weights. The weighted form of MeanValue is the weighted sum divided by the total weight, and a weighted sum is that value multiplied by the total weight.
Constructors
SumValue() -> SumValueExamples
julia> PortfolioOptimisers.vec_to_real_measure(SumValue(), [1.2, 3.4, 0.7])5.3Related
PortfolioOptimisers.ProdValue — Type
struct ProdValue <: VectorToScalarMeasureAlgorithm that reduces a vector of real values to its product.
Mathematical definition
\[\begin{align} \mathrm{ProdValue}(\boldsymbol{v}) &= \prod_{i=1}^{n} v_{i}\,. \end{align}\]
Where:
- $\boldsymbol{v}$: The vector to reduce, of length $n$.
- $v_{i}$: Its $i$-th entry, $i = 1,\ldots,n$.
The reduction reads no weights. One zero entry gives zero. The product of many entries below one underflows to zero, and the product of many entries above one overflows. So this reduction is for a short vector of values near one.
Constructors
ProdValue() -> ProdValueExamples
julia> PortfolioOptimisers.vec_to_real_measure(ProdValue(), [1.2, 3.4, 0.7])2.856Related
PortfolioOptimisers.ModeValue — Type
struct ModeValue <: VectorToScalarMeasureAlgorithm that reduces a vector of real values to its mode.
Mathematical definition
\[\begin{align} \mathrm{ModeValue}(\boldsymbol{v}) &= \underset{u \in \boldsymbol{v}}{\arg\max}\ \left| \left\{ i : v_{i} = u \right\} \right|\,. \end{align}\]
Where:
- $\boldsymbol{v}$: The vector to reduce, of length $n$.
- $u$: A value of $\boldsymbol{v}$.
- $\left| \cdot \right|$: The number of elements of a set.
When two values have the highest count, StatsBase.mode returns the first value that reaches that count. The result is a value of the input and never an average of two values. For example, [3.0, 1.0, 1.0, 3.0] gives 1.0. The comparison is exact equality, so this reduction is for a vector of repeated exact values, not for continuous values.
Constructors
ModeValue() -> ModeValueExamples
julia> PortfolioOptimisers.vec_to_real_measure(ModeValue(), [1.2, 3.4, 0.7, 1.2])1.2Related
PortfolioOptimisers.StandardisedValue — Type
struct StandardisedValue{__T_mv, __T_sv} <: VectorToScalarMeasureAlgorithm that reduces a vector of real values to its mean divided by its standard deviation, with or without weights. After a call of factory with weights, the reduction can raise an error. factory replaces the w field of both mv and sv with the incoming ObsWeights, and sv keeps its default corrected = true. With a plain StatsBase.Weights, that default raises an ArgumentError. Thread an AnalyticWeights, a FrequencyWeights or a ProbabilityWeights, or declare sv = StdValue(; corrected = false).
Mathematical definition
\[\begin{align} z &= \frac{\hat{\mu}}{\tilde{\sigma}}\,, \\ \tilde{\sigma} &= \begin{cases} 1 & \hat{\sigma} \ \mathrm{undefined} \\ \sqrt{\varepsilon} & \hat{\sigma} = 0 \\ \hat{\sigma} & \mathrm{otherwise} \end{cases}\,. \end{align}\]
Where:
- $z$: Standardised value.
- $\hat{\mu}$: The value that
mvgives. - $\hat{\sigma}$: The value that
svgives, about $\hat{\mu}$. - $\tilde{\sigma}$: The denominator after the guard.
- $\varepsilon$: Machine epsilon of the element type of $\hat{\sigma}$.
$\hat{\sigma}$ is undefined on a vector of one entry, because a corrected standard deviation needs two entries. The first case then gives $\tilde{\sigma} = 1$ and $z = \hat{\mu}$, so the reduction has a value on every non-empty vector.
Algorithm
- Reduce
valwithmv, which givesm. - Reduce
valwithsv, and passmas themeankeyword, which givess. So the deviation is always about the mean of step 1. Weights onmvand no weights onsvalso change the denominator. - Guard
s:sisNaN: replace it withone(s).sis an exact zero: replace it withsqrt(eps(eltype(s))). On the constant vector[2.0, 2.0, 2.0],sis an exact zero, and the result is1.342e8, which is2 / sqrt(eps(Float64)). The test is an equality, so the step keeps a small positives, and the result can be larger than this.- Otherwise: keep
s.
- Return
m / s.
Fields
mv: The mean measure of the numerator.
sv: The standard deviation measure of the denominator.
Constructors
StandardisedValue(; mv::MeanValue = MeanValue(), sv::StdValue = StdValue(),) -> StandardisedValueKeywords correspond to the struct's fields.
Propagated parameters
factory passes its arguments on to these @fprop fields:
Examples
julia> PortfolioOptimisers.vec_to_real_measure(StandardisedValue(), [1.2, 3.4, 0.7])1.2299003291330186julia> PortfolioOptimisers.vec_to_real_measure(StandardisedValue(), [0.37])0.37Related
PortfolioOptimisers.vec_to_real_measure — Function
vec_to_real_measure(
measure::Num_VecToScaM,
val::Union{VecNum, NTuple{N, <:Number} where {N}};
kwargs...
) -> NumberReduce a vector of real values to one real value with a measure.
vec_to_real_measure applies the reduction of the concrete subtype of VectorToScalarMeasure, such as the minimum, the mean, the median or the maximum, to a vector of real numbers. The constraint generation and the centrality constraints use it to reduce a metric of each asset to one value.
Algorithm
The method that Julia selects is the algorithm. measure names the reduction. The type parameter of a weighted measure names the branch, for example MeanValue{Nothing} or MeanValue{<:ObsWeights}. So the compiler selects the branch, and no code tests the field at run time.
measureis aNumber: return it, and read nothing ofval.measureis aFunction: returnmeasure(val).measureis aMinValue, aMaxValue, aSumValueor aProdValue: returnminimum,maximum,sumorprodofval.measureis aModeValue: returnStatsBase.modeofval.measureis aMeanValueor aMedianValue: returnStatistics.meanorStatistics.medianofval, with weights when the measure holds them. On the weighted branch,collecta tuple first, and resolve the weights againstvalwithget_observation_weights. That call returns aStatsBase.AbstractWeightsitself, and it evaluates aDynamicAbstractWeightsonval.measureis aStdValueor aVarValue: returnStatistics.stdorStatistics.varofval, withcorrected = measure.corrected, with weights when the measure holds them, and withkwargs.... The weighted branch resolves its weights as step 5 does. It returnsNaNwhen the divisor of the weights is not positive, withweighted_moment_guard, as the unweighted branch does on one entry.measureis aStandardisedValue: follow the algorithm of that type, which reduces two times and guards the denominator.
Because of step 1, a plain number is a valid measure. A caller that already has the value writes it where a reduction goes, and vec_to_real_measure needs no second signature.
Arguments
measure: One of three values.::VectorToScalarMeasure: The reduction to apply toval.::Number: The value to return, whatevervalholds.::Function: The function to apply toval, asmeasure(val).
val: A vector or a tuple of real values to reduce. Every reduction accepts a tuple, and the weighted reductionscollectit first, becauseStatisticsneeds anAbstractVectorwith its weights. The function ignoresvalwhenmeasureis aNumber.kwargs...: Keyword arguments for the reduction. Only theStdValueandVarValuereductions read them.
Returns
score::Number: The value thatmeasuregives.
Examples
julia> PortfolioOptimisers.vec_to_real_measure(MaxValue(), [1.2, 3.4, 0.7])3.4julia> PortfolioOptimisers.vec_to_real_measure(0.9, [1.2, 3.4, 0.7])0.9Related