Prior Scenarios (b): private API
Functions
PortfolioOptimisers.scenario_fill — Function
scenario_fill(
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
mu::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
sigma::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
strict::Bool,
fill_limit::Union{Nothing, Real}
) -> Any
scenario_fill(
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
mu::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
sigma::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
strict::Bool,
fill_limit::Union{Nothing, Real},
named::Union{Nothing, AbstractSet{<:Integer}}
) -> Any
Return the returns matrix with the missing rows of every investable asset filled with zero, and say so above the fitting estimator's resolved fill_limit.
A mask-aware moment estimator answers a young asset from the observations it has, so the asset is investable and its returns column still carries a NaN at every row before it listed. Every consumer of a Prior Result reads that column — the JuMP model, the meta-optimisers and the value-level expected_* functions among them — so the fill is paid once, here, on the estimator's own pass, rather than at each of them.
A non-investable asset keeps its NaN column, so investable_mask is unchanged. mu, sigma and every other block are untouched, because the estimator computed them from the rows it saw.
The share the fill tests is per asset: the worst investable column's own count of filled entries over the number of observations. A matrix-wide denominator scales with the universe, so the column the notice exists to catch disappears inside it — one asset of a hundred whose column is seven-tenths invented is seven thousandths of the matrix, under any limit a caller would set. The matrix-wide share is reported in the message as context and trips nothing.
How much of the trade passes in silence is the fitting estimator's own answer, carried in its fill_limit field and resolved at the fit by resolve_fill_limit against the coverage floor of its arms — the share is a property of one fit, not of the session, so two priors in one program may answer differently. Under strict = false the trade is silent while the worst column's share stays at or below the resolved limit, and is named through strict_diagnostic above it. Under strict = true any fill refuses, whatever the limit holds.
Two mask-aware families reach this verb. The exponentially weighted family carries no CoveragePolicy, so a fill_limit of nothing names every fill there. The plain family is mask-aware exactly where a policy is set, and a policy derives a limit that never fires, so an available-case fit names nothing while it does what it was configured to do. A plain estimator with no policy never reaches this verb at all: under the whole-window rule, an asset it could not cover leaves the Coverage Universe and is not investable.
Algorithm
- Return
Xitself when every entry ofXis finite, which is every fit over a complete window. - Derive the Investable Mask from
muand the diagonal ofsigma, asinvestable_maskdoes, and find the pairs to fill withscenario_fill_pairs. ReturnXitself when there are none, which is a gap that belongs to a non-investable asset alone. - Narrow the pairs to report with
scenario_fill_report, which drops the assets a carry state has already named and is the identity when nothing remembers. Understrictthe narrowing is skipped, becausestrictrefuses any fill and must not depend on how often the estimator has been read out. - Count the reported pairs per asset, take the worst column's share of its own observations, and report through
strict_diagnosticwhenstrictholds, whenfill_limitisnothing, or when that share exceedsfill_limit. Record the assets just named withscenario_fill_remember!. - Return a copy of
Xwith zero written at each of the filled pairs — every one of them, not just the reported ones — and theNaNof every non-investable asset left where it is.
The notice fires once per asset, not once per step
named is what separates the batch call from the online one. A batch fit passes nothing, reports every fill it finds, and remembers nothing. A call of prior(pe) with no data on a folded prior passes the set its PriorCarryState carries, so a walk-forward names an asset at the step it lists and stays quiet afterwards instead of emitting the same notice at every one of two thousand steps. The fill itself is unchanged: every filled pair is written at every call, whatever the set holds. Under strict = true the first fill still throws.
Arguments
X: Asset returns,observations × assets.mu: The expected returns the estimator answered,NaNat a non-investable asset.sigma: The covariance the estimator answered,NaNon the diagonal at a non-investable asset.strict: Iftrue, any fill raises anArgumentError; iffalse, a fill above the share warns.fill_limit: The share of an investable column the fitting estimator accepts in silence, afterresolve_fill_limit, ornothingwhen it accepts none.named: The assets already named, written in place when a notice fires, ornothingwhen nothing remembers.
Validation
- The worst investable column's filled share is at or below
fill_limit, else a warning naming the assets is emitted, or anArgumentErrornaming them is raised understrict, which any fill raises. Afill_limitofnothingis at or below no share, so any fill is named.
Returns
X::MatNum: The returns matrix whose investable columns are finite.
Related