Assertions: private API

The library checks each input where a constructor or a function receives it, a practice called defensive programming. Most of the functions below do one such check. A failed check throws an error that names the argument and the condition it failed, and assert_resource_cap also names the limit to raise.

PortfolioOptimisers.assert_resource_cap — Function
assert_resource_cap(val::Integer, cap::Integer, sym::Sym_Str, knob::Sym_Str)

Assert that an untrusted size val is not above the active cap cap of RESOURCE_LIMITS, and raise a DomainError when it is.

sym is the name of the field that the message reports, for example :n_sim. knob is the field of ResourceLimits to raise, for example :max_n_sim. The error tells the caller what the function refused, and how to allow it.

Arguments

  • val: The requested size.
  • cap: The active cap.
  • sym: The symbolic name of the field that holds val.
  • knob: The symbolic name of the ResourceLimits field that raises the cap.

Validation

  • val <= cap, which raises a DomainError that names val, sym, cap and knob.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_ep_grid_size — Function
assert_ep_grid_size(K::Integer)

Assert that K, the number of grid points of a grid formulation of a tail view, is odd, positive and not above the active cap max_ep_grid of RESOURCE_LIMITS.

Each grid point is one binary variable of the mixed-integer program that an upper-bound or equality view builds, and one dense row over the posterior probabilities. K is an untrusted size of the kind that assert_resource_cap checks. An odd K makes the centre of the grid a point of the grid. The two grid formulations state one rule, so both call this function.

Arguments

  • K: The requested number of grid points.

Validation

  • isodd(K) and 1 <= K <= RESOURCE_LIMITS[].max_ep_grid. Each grid point is one binary variable of the mixed-integer program that an upper-bound or equality view builds, and RESOURCE_LIMITS sets the cap.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_nonempty — Function
assert_nonempty(
    val::Union{AbstractDict, AbstractVector{<:Pair}, AbstractArray{<:Union{Number, AbstractJuMPScalar}}}
)
assert_nonempty(
    val::Union{AbstractDict, AbstractVector{<:Pair}, AbstractArray{<:Union{Number, AbstractJuMPScalar}}},
    sym::Union{AbstractString, Symbol}
)

Assert that val is non-empty.

A Pair or a Number input does nothing, because a scalar cannot be empty.

Arguments

  • val: The container to check. It is an AbstractDict, a VecPair or an ArrNum.
  • sym: Symbolic name used in the error message.

Validation

Returns

  • nothing.

Related

source
assert_nonempty(::Union{Number, Pair})
assert_nonempty(
    ::Union{Number, Pair},
    ::Union{AbstractString, Symbol}
)

Method of assert_nonempty for scalar inputs, which does nothing.

A Pair or a Number value cannot be empty.

Arguments

  • ::Union{Pair, Number}: The scalar value. The method does not read it.
  • ::Sym_Str = :val: The symbolic name. The method does not read it.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_finite — Function
assert_finite(val::AbstractDict)
assert_finite(
    val::AbstractDict,
    sym::Union{AbstractString, Symbol}
)

Assert that every element of val is finite.

Algorithm

The method that Julia selects on the type of val is the algorithm. Each method checks one predicate, and raises a DomainError that names sym and the predicate that failed.

  1. An AbstractDict checks all(isfinite, values(val)), so the method does not read the keys.
  2. A VecPair checks all(isfinite, getindex.(val, 2)), so the second element of each pair is the value.
  3. An ArrNum checks all(isfinite, val).
  4. A Pair checks isfinite(val[2]).
  5. A Number checks isfinite(val).

Arguments

  • val: The value to check.
  • sym: Symbolic name used in the error message.

Validation

  • Every element of val is finite, under the predicate that its type selects. A NaN and an infinity both breach it, and a breach raises a DomainError.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_nonneg — Function
assert_nonneg(val::AbstractDict)
assert_nonneg(
    val::AbstractDict,
    sym::Union{AbstractString, Symbol}
)

Assert that all elements of val are non-negative (>= 0).

Algorithm

The method that Julia selects on the type of val is the algorithm. Each method checks one predicate, and raises a DomainError that names sym and the predicate that failed.

  1. An AbstractDict checks all(x -> 0 <= x, values(val)), so the method does not read the keys.
  2. A VecPair checks all(x -> 0 <= x[2], val), so the second element of each pair is the value.
  3. An ArrNum checks all(x -> 0 <= x, val).
  4. A Pair checks 0 <= val[2].
  5. A Number checks 0 <= val.

Arguments

  • val: The value to check.
  • sym: Symbolic name used in the error message.

Validation

  • Every element of val is non-negative, under the predicate that its type selects. A breach raises a DomainError.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_gt0 — Function
assert_gt0(val::AbstractDict)
assert_gt0(
    val::AbstractDict,
    sym::Union{AbstractString, Symbol}
)

Assert that all elements of val are strictly positive (> 0).

Algorithm

The method that Julia selects on the type of val is the algorithm. Each method checks one predicate, and raises a DomainError that names sym and the predicate that failed.

  1. An AbstractDict checks all(x -> 0 < x, values(val)), so the method does not read the keys.
  2. A VecPair checks all(x -> 0 < x[2], val), so the second element of each pair is the value.
  3. An ArrNum checks all(x -> 0 < x, val).
  4. A Pair checks 0 < val[2].
  5. A Number checks 0 < val.

Arguments

  • val: The value to check.
  • sym: Symbolic name used in the error message.

Validation

  • Every element of val is strictly positive, under the predicate that its type selects. A breach raises a DomainError.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_nonempty_nonneg_finite_val — Function
assert_nonempty_nonneg_finite_val(
    val::Union{AbstractDict, VecPair, ArrNum, Pair, Number},
    val_sym::Union{Symbol,AbstractString} = :val
)
assert_nonempty_nonneg_finite_val(::Option{<:UnresolvedValue},
                                  ::Union{Symbol,AbstractString} = :val)

Check that the input value is non-empty, non-negative and finite.

Algorithm

  1. Call assert_nonempty, then assert_finite, then assert_nonneg, each on val and val_sym. The calls run in this order, so the error names the first rule that the value breaks.
  2. An UnresolvedValue, or nothing, selects the second method, which checks nothing. With that method, a caller can check an optional field, or a field that can hold a rule for the value, and write no branch. Each other type is a MethodError, so a form that a slot admits with no rule fails at construction.

Arguments

  • val: The input value to check.
  • val_sym: The symbolic name that the error messages show.

Validation

Each rule is the rule that the type of val selects in the three functions of step 1.

  • ::AbstractDict: !isempty(val), all(isfinite, values(val)), all(x -> x >= 0, values(val)).
  • ::VecPair: !isempty(val), all(isfinite, getindex.(val, 2)), all(x -> x[2] >= 0, val).
  • ::ArrNum: !isempty(val), all(isfinite, val), all(x -> x >= 0, val).
  • ::Pair: isfinite(val[2]) and val[2] >= 0.
  • ::Number: isfinite(val) and val >= 0.
  • ::Option{<:UnresolvedValue}: No rule, so the call always passes.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_nonempty_gt0_finite_val — Function
assert_nonempty_gt0_finite_val(
    val::Union{AbstractDict, VecPair, ArrNum, Pair, Number},
    val_sym::Union{Symbol,AbstractString} = :val
)
assert_nonempty_gt0_finite_val(::Option{<:UnresolvedValue},
                               ::Union{Symbol,AbstractString} = :val)

Check that the input value is non-empty, greater than zero, and finite.

Algorithm

  1. Call assert_nonempty, then assert_finite, then assert_gt0, each on val and val_sym. The calls run in this order, so the error names the first rule that the value breaks.
  2. An UnresolvedValue, or nothing, selects the second method, which checks nothing. With that method, a caller can check an optional field, or a field that can hold a rule for the value, and write no branch. Each other type is a MethodError, so a form that a slot admits with no rule fails at construction.

Arguments

  • val: The input value to check.
  • val_sym: The symbolic name that the error messages show.

Validation

Each rule is the rule that the type of val selects in the three functions of step 1.

  • ::AbstractDict: !isempty(val), all(isfinite, values(val)), all(x -> x > 0, values(val)).
  • ::VecPair: !isempty(val), all(isfinite, getindex.(val, 2)), all(x -> x[2] > 0, val).
  • ::ArrNum: !isempty(val), all(isfinite, val), all(x -> x > 0, val).
  • ::Pair: isfinite(val[2]) and val[2] > 0.
  • ::Number: isfinite(val) and val > 0.
  • ::Option{<:UnresolvedValue}: No rule, so the call always passes.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_nonempty_finite_val — Function
assert_nonempty_finite_val(
    val::Union{AbstractDict, VecPair, ArrNum, Pair, Number},
    val_sym::Union{Symbol,AbstractString} = :val
)
assert_nonempty_finite_val(::Option{<:UnresolvedValue},
                           ::Union{Symbol,AbstractString} = :val)

Check that the input value is non-empty and finite.

Algorithm

  1. Call assert_nonempty, then assert_finite, each on val and val_sym. The calls run in this order, so the error names the first rule that the value breaks.
  2. An UnresolvedValue, or nothing, selects the second method, which checks nothing. With that method, a caller can check an optional field, or a field that can hold a rule for the value, and write no branch. Each other type is a MethodError, so a form that a slot admits with no rule fails at construction.

Arguments

  • val: The input value to check.
  • val_sym: The symbolic name that the error messages show.

Validation

Each rule is the rule that the type of val selects in the two functions of step 1.

  • ::AbstractDict: !isempty(val), all(isfinite, values(val)).
  • ::VecPair: !isempty(val), all(isfinite, getindex.(val, 2)).
  • ::ArrNum: !isempty(val), all(isfinite, val).
  • ::Pair: isfinite(val[2]).
  • ::Number: isfinite(val).
  • ::Option{<:UnresolvedValue}: No rule, so the call always passes.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_matrix_issquare — Function
assert_matrix_issquare(X::MatNum, X_sym::Symbol = :X)

Assert that the input matrix is square.

Arguments

  • X: The input matrix to check.
  • X_sym: The symbolic name that the error messages show.

Validation

  • size(X, 1) == size(X, 2), which raises a DimensionMismatch that names X_sym and both sizes.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_unit_interval — Function
assert_unit_interval(val::Number, sym::Union{Symbol,AbstractString} = :val)
assert_unit_interval(::Option{<:UnresolvedValue}, ::Union{Symbol,AbstractString} = :val)

Assert that val lies strictly inside the open unit interval (0 < val < 1).

An UnresolvedValue, or nothing, selects the second method, which checks nothing. With that method, a caller can check a slot whose bound accepts more than a number and write no branch, as with assert_nonempty_gt0_finite_val. A Calibration Rule, an AbstractCalibrationAlgorithm, states no number at construction. The library checks the range later, when the rebuild runs, on the number that the rule returns. Each other type is a MethodError, so a form that a slot admits with no rule fails at construction.

Arguments

  • val: The value to check.
  • sym: Symbolic name used in the error message.

Validation

  • ::Number: 0 < val < 1, which raises a DomainError that names sym and val.
  • ::Option{<:UnresolvedValue}: No rule, so the call always passes.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_closed_unit_interval — Function
assert_closed_unit_interval(val::Number, sym::Union{Symbol,AbstractString} = :val)
assert_closed_unit_interval(::Option{<:UnresolvedValue}, ::Union{Symbol,AbstractString} = :val)

Assert that val lies inside the closed unit interval (0 <= val <= 1).

It is the closed form of assert_unit_interval. The two functions differ only in whether the ends belong to the interval. A template can turn a weight fully off, or give it its full value, so the weight reaches both ends and needs this rule and not the open one.

An UnresolvedValue, or nothing, selects the second method, which checks nothing, as in assert_unit_interval. Each other type is a MethodError.

Arguments

  • val: The value to check.
  • sym: Symbolic name used in the error message.

Validation

  • ::Number: 0 <= val <= 1, which raises a DomainError that names sym and val.
  • ::Option{<:UnresolvedValue}: No rule, so the call always passes.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_all_finite — Function
assert_all_finite(val::ArrNum, sym::Sym_Str = :val)

Assert that every element of val is finite, and raise an IsNonFiniteError when one is not.

assert_finite checks the same predicate and raises a DomainError, as assert_nonneg and assert_gt0 do. This function raises an IsNonFiniteError, and it reports the position of the breach. With the position, a caller can find the bad entry, and the message does not quote the data.

This function guards the covariance estimators that compare returns with a threshold, GerberCovariance and SmythBrobyCovariance. Their comparisons X .>= sd and X .<= -sd give false for a NaN entry, with no message. The estimator then reads the NaN as "no co-movement", and gives a finite covariance that looks correct and is wrong. Clean the returns first with an asset selector, such as CompleteAssetSelector, or with MissingDataFilter. Those accept non-finite entries in a returns matrix, and an estimator that compares returns does not. The message reports the count of bad entries and the first bad index, and never a data value.

Arguments

  • val: The array to check.
  • sym: Symbolic name used in the error message.

Validation

  • all(isfinite, val), which raises an IsNonFiniteError. The message gives the count of bad entries and the first bad index, and never a data value.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_nan_or_closed_unit_interval — Function
assert_nan_or_closed_unit_interval(val::Num_ArrNum,
                                   sym::Union{Symbol,AbstractString} = :val)
assert_nan_or_closed_unit_interval(::Nothing, ::Union{Symbol,AbstractString} = :val)

Assert that each entry of val is NaN or lies inside the closed unit interval (0 <= x <= 1).

A Result holds NaN in a field that it cannot compute, such as the p-value of a series with too few entries, or the hit rate of a series with no finite entry. So the constructor of a Result checks a share or a probability with this function, and not with assert_closed_unit_interval, which refuses NaN. A number is one entry. A nothing is a column that the Result does not hold, so the second method checks nothing.

Arguments

  • val: The number or the array to check.
  • sym: Symbolic name used in the error message.

Validation

  • Each entry of val is NaN or in [0, 1]. A breach raises a DomainError that names sym and the count of the entries that break the rule.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_nan_or_nonneg — Function
assert_nan_or_nonneg(val::Num_ArrNum, sym::Union{Symbol,AbstractString} = :val)
assert_nan_or_nonneg(::Nothing, ::Union{Symbol,AbstractString} = :val)

Assert that no entry of val is negative. A NaN entry passes.

A Result holds NaN in a field that it cannot compute, such as the standard deviation of a series with fewer than two entries. So the constructor of a Result checks a deviation, a volatility or a turnover with this function, and not with assert_nonneg, which refuses NaN. A number is one entry. A nothing is a column that the Result does not hold, so the second method checks nothing.

Arguments

  • val: The number or the array to check.
  • sym: Symbolic name used in the error message.

Validation

  • No entry of val is below zero. A breach raises a DomainError that names sym and the count of the negative entries.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_ordered_bounds — Function
assert_ordered_bounds(lo::Num_ArrNum, hi::Num_ArrNum,
                      lo_sym::Union{Symbol,AbstractString} = :lo,
                      hi_sym::Union{Symbol,AbstractString} = :hi)

Assert that no lower bound lies above its upper bound, entry by entry. A pair with a NaN bound passes.

The two bounds of a confidence interval are the case. A test that cannot compute an interval gives NaN for both bounds, so the pair states no order to check.

Arguments

  • lo: The lower bounds, a number or an array.
  • hi: The upper bounds, of the shape of lo.
  • lo_sym: The name of lo in the message.
  • hi_sym: The name of hi in the message.

Validation

  • size(lo) == size(hi). Otherwise, the function raises a DimensionMismatch.
  • No entry of lo is above the same entry of hi. A breach raises a DomainError that names both bounds.

Returns

  • nothing.

Related

source