Vector to scalar measures

Summary statistics

PortfolioOptimisers.VectorToScalarMeasure — Type
abstract type VectorToScalarMeasure <: AbstractAlgorithm

Abstract 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: Reduces val to 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 a PanelFieldScorer with no bib of its own scores the assets with the measure. The fallback answers true, as for a statistic of location. Add a method that answers false for a statistic whose smaller values are better, as StdValue and VarValue do.

Arguments

  • measure: An instance of the concrete subtype.

Returns

  • bib::Bool: true when a bigger result is better.

Related

source
PortfolioOptimisers.MinValue — Type
struct MinValue <: VectorToScalarMeasure

Algorithm 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() -> MinValue

Examples

julia> PortfolioOptimisers.vec_to_real_measure(MinValue(), [1.2, 3.4, 0.7])0.7

Related

source
PortfolioOptimisers.MeanValue — Type
struct MeanValue{__T_w} <: VectorToScalarMeasure

Algorithm 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 vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, the computation is unweighted.

Constructors

MeanValue(;    w::Option{<:ObsWeights} = nothing,) -> MeanValue

Keywords correspond to the struct's fields.

Validation

  • If w is not nothing, !isempty(w).

Propagated parameters

factory passes its arguments on to this @wprop field:

Observation weight parameters

obs_weights_view indexes these fields to the selected observations:

Examples

julia> PortfolioOptimisers.vec_to_real_measure(MeanValue(), [1.2, 3.4, 0.7])1.7666666666666666

Related

source
PortfolioOptimisers.MedianValue — Type
struct MedianValue{__T_w} <: VectorToScalarMeasure

Algorithm 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 case w = 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 StatsBase defines 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 vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, the computation is unweighted.

Constructors

MedianValue(;    w::Option{<:ObsWeights} = nothing,) -> MedianValue

Keywords correspond to the struct's fields.

Validation

  • If w is not nothing, !isempty(w).

Propagated parameters

factory passes its arguments on to this @wprop field:

Observation weight parameters

obs_weights_view indexes these fields to the selected observations:

Examples

julia> PortfolioOptimisers.vec_to_real_measure(MedianValue(), [1.2, 3.4, 0.7])1.2

Related

source
PortfolioOptimisers.MaxValue — Type
struct MaxValue <: VectorToScalarMeasure

Algorithm 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() -> MaxValue

Examples

julia> PortfolioOptimisers.vec_to_real_measure(MaxValue(), [1.2, 3.4, 0.7])3.4

Related

source
PortfolioOptimisers.StdValue — Type
struct StdValue{__T_w, __T_corrected} <: VectorToScalarMeasure

Algorithm 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 w and the same corrected, whose four denominators VarValue states.

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 vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, the computation is unweighted.
  • corrected: If true, the estimator applies the Bessel correction. Statistics or StatsBase applies it, with the divisor that each weight type defines.

Constructors

StdValue(;    w::Option{<:ObsWeights} = nothing,    corrected::Bool = true,) -> StdValue

Keywords correspond to the struct's fields.

Validation

  • If w is not nothing, !isempty(w).

Propagated parameters

factory passes its arguments on to this @wprop field:

Observation weight parameters

obs_weights_view indexes these fields to the selected observations:

Examples

julia> PortfolioOptimisers.vec_to_real_measure(StdValue(), [1.2, 3.4, 0.7])1.4364307617610164

Related

source
PortfolioOptimisers.VarValue — Type
struct VarValue{__T_w, __T_corrected} <: VectorToScalarMeasure

Algorithm 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 corrected and the type of w together select.

$d$ takes one of four values:

  • w = nothing: $d = n - 1$ when corrected is true, and $d = n$ when it is false.
  • w::AnalyticWeights: $d = \sum w_{i} - \sum w_{i}^{2} / \sum w_{i}$ when corrected is true.
  • w::FrequencyWeights: $d = \sum w_{i} - 1$ when corrected is true.
  • w::ProbabilityWeights: $d = \left(\sum w_{i}\right)(m - 1) / m$ when corrected is true, 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 vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, the computation is unweighted.
  • corrected: If true, the estimator applies the Bessel correction. Statistics or StatsBase applies it, with the divisor that each weight type defines.

Constructors

VarValue(;    w::Option{<:ObsWeights} = nothing,    corrected::Bool = true,) -> VarValue

Keywords correspond to the struct's fields.

Validation

  • If w is not nothing, !isempty(w).

Propagated parameters

factory passes its arguments on to this @wprop field:

Observation weight parameters

obs_weights_view indexes these fields to the selected observations:

Examples

julia> PortfolioOptimisers.vec_to_real_measure(VarValue(), [1.2, 3.4, 0.7])2.0633333333333335

Related

source
PortfolioOptimisers.SumValue — Type
struct SumValue <: VectorToScalarMeasure

Algorithm 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() -> SumValue

Examples

julia> PortfolioOptimisers.vec_to_real_measure(SumValue(), [1.2, 3.4, 0.7])5.3

Related

source
PortfolioOptimisers.ProdValue — Type
struct ProdValue <: VectorToScalarMeasure

Algorithm 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() -> ProdValue

Examples

julia> PortfolioOptimisers.vec_to_real_measure(ProdValue(), [1.2, 3.4, 0.7])2.856

Related

source
PortfolioOptimisers.ModeValue — Type
struct ModeValue <: VectorToScalarMeasure

Algorithm 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() -> ModeValue

Examples

julia> PortfolioOptimisers.vec_to_real_measure(ModeValue(), [1.2, 3.4, 0.7, 1.2])1.2

Related

source
PortfolioOptimisers.StandardisedValue — Type
struct StandardisedValue{__T_mv, __T_sv} <: VectorToScalarMeasure

Algorithm 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 mv gives.
  • $\hat{\sigma}$: The value that sv gives, 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

  1. Reduce val with mv, which gives m.
  2. Reduce val with sv, and pass m as the mean keyword, which gives s. So the deviation is always about the mean of step 1. Weights on mv and no weights on sv also change the denominator.
  3. Guard s:
    1. s is NaN: replace it with one(s).
    2. s is an exact zero: replace it with sqrt(eps(eltype(s))). On the constant vector [2.0, 2.0, 2.0], s is an exact zero, and the result is 1.342e8, which is 2 / sqrt(eps(Float64)). The test is an equality, so the step keeps a small positive s, and the result can be larger than this.
    3. Otherwise: keep s.
  4. 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(),) -> StandardisedValue

Keywords correspond to the struct's fields.

Propagated parameters

factory passes its arguments on to these @fprop fields:

  • mv: Updated through a recursive call of factory.
  • sv: Updated through a recursive call of factory.

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.37

Related

source
PortfolioOptimisers.vec_to_real_measure — Function
vec_to_real_measure(
    measure::Num_VecToScaM,
    val::Union{VecNum, NTuple{N, <:Number} where {N}};
    kwargs...
) -> Number

Reduce 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.

  1. measure is a Number: return it, and read nothing of val.
  2. measure is a Function: return measure(val).
  3. measure is a MinValue, a MaxValue, a SumValue or a ProdValue: return minimum, maximum, sum or prod of val.
  4. measure is a ModeValue: return StatsBase.mode of val.
  5. measure is a MeanValue or a MedianValue: return Statistics.mean or Statistics.median of val, with weights when the measure holds them. On the weighted branch, collect a tuple first, and resolve the weights against val with get_observation_weights. That call returns a StatsBase.AbstractWeights itself, and it evaluates a DynamicAbstractWeights on val.
  6. measure is a StdValue or a VarValue: return Statistics.std or Statistics.var of val, with corrected = measure.corrected, with weights when the measure holds them, and with kwargs.... The weighted branch resolves its weights as step 5 does. It returns NaN when the divisor of the weights is not positive, with weighted_moment_guard, as the unweighted branch does on one entry.
  7. measure is a StandardisedValue: 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 to val.
    • ::Number: The value to return, whatever val holds.
    • ::Function: The function to apply to val, as measure(val).
  • val: A vector or a tuple of real values to reduce. Every reduction accepts a tuple, and the weighted reductions collect it first, because Statistics needs an AbstractVector with its weights. The function ignores val when measure is a Number.

  • kwargs...: Keyword arguments for the reduction. Only the StdValue and VarValue reductions read them.

Returns

  • score::Number: The value that measure gives.

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.9

Related

source