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 holdsval.knob: The symbolic name of theResourceLimitsfield that raises the cap.
Validation
val <= cap, which raises aDomainErrorthat namesval,sym,capandknob.
Returns
nothing.
Related
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)and1 <= 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, andRESOURCE_LIMITSsets the cap.
Returns
nothing.
Related
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 anAbstractDict, aVecPairor anArrNum.sym: Symbolic name used in the error message.
Validation
!isempty(val), which raises anIsEmptyErrorthat namessym.
Returns
nothing.
Related
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
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.
- An
AbstractDictchecksall(isfinite, values(val)), so the method does not read the keys. - A
VecPairchecksall(isfinite, getindex.(val, 2)), so the second element of each pair is the value. - An
ArrNumchecksall(isfinite, val). - A
Pairchecksisfinite(val[2]). - A
Numberchecksisfinite(val).
Arguments
val: The value to check.sym: Symbolic name used in the error message.
Validation
- Every element of
valis finite, under the predicate that its type selects. ANaNand an infinity both breach it, and a breach raises aDomainError.
Returns
nothing.
Related
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.
- An
AbstractDictchecksall(x -> 0 <= x, values(val)), so the method does not read the keys. - A
VecPairchecksall(x -> 0 <= x[2], val), so the second element of each pair is the value. - An
ArrNumchecksall(x -> 0 <= x, val). - A
Pairchecks0 <= val[2]. - A
Numberchecks0 <= val.
Arguments
val: The value to check.sym: Symbolic name used in the error message.
Validation
- Every element of
valis non-negative, under the predicate that its type selects. A breach raises aDomainError.
Returns
nothing.
Related
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.
- An
AbstractDictchecksall(x -> 0 < x, values(val)), so the method does not read the keys. - A
VecPairchecksall(x -> 0 < x[2], val), so the second element of each pair is the value. - An
ArrNumchecksall(x -> 0 < x, val). - A
Pairchecks0 < val[2]. - A
Numberchecks0 < val.
Arguments
val: The value to check.sym: Symbolic name used in the error message.
Validation
- Every element of
valis strictly positive, under the predicate that its type selects. A breach raises aDomainError.
Returns
nothing.
Related
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
- Call
assert_nonempty, thenassert_finite, thenassert_nonneg, each onvalandval_sym. The calls run in this order, so the error names the first rule that the value breaks. - An
UnresolvedValue, ornothing, 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 aMethodError, 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])andval[2] >= 0.::Number:isfinite(val)andval >= 0.::Option{<:UnresolvedValue}: No rule, so the call always passes.
Returns
nothing.
Related
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
- Call
assert_nonempty, thenassert_finite, thenassert_gt0, each onvalandval_sym. The calls run in this order, so the error names the first rule that the value breaks. - An
UnresolvedValue, ornothing, 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 aMethodError, 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])andval[2] > 0.::Number:isfinite(val)andval > 0.::Option{<:UnresolvedValue}: No rule, so the call always passes.
Returns
nothing.
Related
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
- Call
assert_nonempty, thenassert_finite, each onvalandval_sym. The calls run in this order, so the error names the first rule that the value breaks. - An
UnresolvedValue, ornothing, 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 aMethodError, 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
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 aDimensionMismatchthat namesX_symand both sizes.
Returns
nothing.
Related
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 aDomainErrorthat namessymandval.::Option{<:UnresolvedValue}: No rule, so the call always passes.
Returns
nothing.
Related
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 aDomainErrorthat namessymandval.::Option{<:UnresolvedValue}: No rule, so the call always passes.
Returns
nothing.
Related
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 anIsNonFiniteError. The message gives the count of bad entries and the first bad index, and never a data value.
Returns
nothing.
Related
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
valisNaNor in[0, 1]. A breach raises aDomainErrorthat namessymand the count of the entries that break the rule.
Returns
nothing.
Related
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
valis below zero. A breach raises aDomainErrorthat namessymand the count of the negative entries.
Returns
nothing.
Related
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 oflo.lo_sym: The name ofloin the message.hi_sym: The name ofhiin the message.
Validation
size(lo) == size(hi). Otherwise, the function raises aDimensionMismatch.- No entry of
lois above the same entry ofhi. A breach raises aDomainErrorthat names both bounds.
Returns
nothing.
Related