The source files can be found in examples/.
Calibrated risk measures: a rule in place of a number
alpha = 0.05 is a statement about the probability of the tail. It says nothing about the number of observations the tail holds. Over one year of daily data the 5% tail holds about 13 observations, and over five years it holds about 63. A number you state once means something different on every sample it meets, and a cross-validation over folds of unequal length meets a different sample on every fold.
A calibration slot takes either statement. It takes the number itself, and it takes a calibration rule, an object that computes the number from the prior result of the sample it is given. The rule runs inside factory, the function an optimiser calls once per fit, so a cross-validation recomputes the quantity on every fold, and the rest of the model stays the same.
Every alpha, beta and kappa of a risk measure, and every ambiguity radius and Esfahani-Kuhn tail weight, is a calibration slot.
This example shows the slot as you use it. Section 1 loads the data, and each section after it shows one use of a slot.
- A stated number and a rule side by side on the same measure.
- The refit per fold, over folds of unequal length.
- Three of the rules the library has, and the question that makes each one the right choice.
- The two slots that resolve together, where
alpharesolves first and its number reaches the $\kappa$ rule. - The two tail-decay rules, which estimate the tail of one sample per end and for both ends.
- A plain function as a rule, which needs no library type.
- The slot bounds, which refuse a rule of the wrong family at construction.
- The ambiguity radius and the tail weight of the distributionally robust measure.
The regularisation coefficients l1, linf, L2Regularisation and LpRegularisation are ambiguity radii too, and they take the same rule family. They belong to the regularisation example, which covers those slots. The three norm ceilings l2c, lpc and linfc of JuMPOptimiser bound a norm rather than price one, so they are a different quantity and take a family of their own, AbstractNormCeilingCalibrationAlgorithm. That example runs both families, and this one stays on the slots that sit on a risk measure.
using PortfolioOptimisers, PrettyTables, DataFrames, StatsBase, Statisticsnumfmt = (v, i, j) -> begin return isa(v, AbstractFloat) ? round(v; sigdigits = 4) : vend;resfmt = (v, i, j) -> begin if j == 1 return v else return isa(v, Number) ? "$(round(v*100, digits=3)) %" : v endend;1. Setting up
Five years of daily data give the training windows enough room to differ in length. A rule uses the length, so it gives a different number on each fold.
using CSV, TimeSeries, ClarabelX = TimeArray(CSV.File(joinpath(@__DIR__, "..", "SP500.csv.gz")); timestamp = :Date)[(end - 252 * 5):end]rd = prices_to_returns(X)println("size(rd.X) = $(size(rd.X))")slv = [Solver(; name = :clarabel1, solver = Clarabel.Optimizer, settings = Dict("verbose" => false), check_sol = (; allow_local = true, allow_almost = true)), Solver(; name = :clarabel2, solver = Clarabel.Optimizer, settings = Dict("verbose" => false, "max_step_fraction" => 0.95), check_sol = (; allow_local = true, allow_almost = true)), Solver(; name = :clarabel3, solver = Clarabel.Optimizer, settings = Dict("verbose" => false, "max_step_fraction" => 0.9), check_sol = (; allow_local = true, allow_almost = true))];size(rd.X) = (1260, 20)2. A stated number and a rule side by side
ConditionalValueatRisk takes alpha = 0.05, and it takes a rule that computes the number. The slot names the quantity and the end of the distribution, so the rule states the method alone. The other fields of the measure stay the same.
cvar_stated = ConditionalValueatRisk(; alpha = 0.05)cvar_rule = ConditionalValueatRisk(; alpha = CountOf(25))ConditionalValueatRisk
settings ┼ RiskMeasureSettings
│ scale ┼ Float64: 1.0
│ ub ┼ nothing
│ rke ┴ Bool: true
alpha ┼ CountOf
│ val ┴ Int64: 25
w ┴ nothing
The slot stores the rule itself, so the field gives back what you wrote.
cvar_rule.alphaCountOf
val ┴ Int64: 25
A CountOf in alpha states the tail's population rather than its probability: alpha = n / T leaves n observations in the tail whatever the sample length is.
A rule needs a prior result, because it takes the sample size and the moments from one. The number therefore appears when factory runs, which is the function the optimiser calls on the measure once it has fitted the prior.
pr = prior(EmpiricalPrior(), rd)println("resolved alpha over the whole sample = $(factory(cvar_rule, pr).alpha)")resolved alpha over the whole sample = 0.01984126984126984Call expected_risk on a matrix of returns and the rule has no prior result to read, so the call refuses the rule and names what to pass instead of guessing a number.
w0 = fill(inv(size(rd.X, 2)), size(rd.X, 2))try expected_risk(cvar_rule, w0, rd.X)catch e println(sprint(showerror, e))endArgumentError: `ConditionalValueatRisk.alpha` holds a Calibration Rule, a `CountOf`, and this entry point has no prior result to resolve it against. A rule reads the sample size, the moments and the effective observation weights, which a bare returns matrix does not carry. Pass the prior result itself — `expected_risk(r, w, pr, fees)` — or resolve the measure first with `factory(r, pr)`.Pass the prior result instead. The rule resolves, and the measure evaluates.
println("calibrated risk = $(expected_risk(cvar_rule, w0, pr))")println("stated risk = $(expected_risk(cvar_stated, w0, pr))")calibrated risk = 0.04445453434825809
stated risk = 0.0320962997991342053. The refit per fold
IndexWalkForward with expand_train = true grows the training window one test block at a time, so every fold trains on a window of a different length.
iwf = IndexWalkForward(252, 63; expand_train = true)iwf_res = split(iwf, rd)println("number of folds = $(length(iwf_res.train_idx))")number of folds = 16factory is the function the optimiser itself calls, so resolving a measure against a fold's own prior gives you the measure that fold optimises. This is how you get the number, because the library has no other function for it.
fold_prior(idx) = prior(EmpiricalPrior(), rd.X[idx, :])resolved(r, idx, key) = getproperty(factory(r, fold_prior(idx)), key)resolved (generic function with 1 method)The stated alpha is one number for every fold. The rule's alpha falls as the window grows, and the count of observations in the tail stays fixed.
fold_table = DataFrame(:fold => 1:length(iwf_res.train_idx), :T => length.(iwf_res.train_idx), :alpha_stated => fill(cvar_stated.alpha, length(iwf_res.train_idx)), :tail_count_stated => cvar_stated.alpha * length.(iwf_res.train_idx), :alpha_rule => [resolved(cvar_rule, idx, :alpha) for idx in iwf_res.train_idx])fold_table.tail_count_rule = fold_table.alpha_rule .* fold_table.Tpretty_table(fold_table; formatters = [numfmt])┌───────┬───────┬──────────────┬───────────────────┬────────────┬─────────────────┐
│ fold │ T │ alpha_stated │ tail_count_stated │ alpha_rule │ tail_count_rule │
│ Int64 │ Int64 │ Float64 │ Float64 │ Float64 │ Float64 │
├───────┼───────┼──────────────┼───────────────────┼────────────┼─────────────────┤
│ 1 │ 252 │ 0.05 │ 12.6 │ 0.09921 │ 25.0 │
│ 2 │ 315 │ 0.05 │ 15.75 │ 0.07937 │ 25.0 │
│ 3 │ 378 │ 0.05 │ 18.9 │ 0.06614 │ 25.0 │
│ 4 │ 441 │ 0.05 │ 22.05 │ 0.05669 │ 25.0 │
│ 5 │ 504 │ 0.05 │ 25.2 │ 0.0496 │ 25.0 │
│ 6 │ 567 │ 0.05 │ 28.35 │ 0.04409 │ 25.0 │
│ 7 │ 630 │ 0.05 │ 31.5 │ 0.03968 │ 25.0 │
│ 8 │ 693 │ 0.05 │ 34.65 │ 0.03608 │ 25.0 │
│ 9 │ 756 │ 0.05 │ 37.8 │ 0.03307 │ 25.0 │
│ 10 │ 819 │ 0.05 │ 40.95 │ 0.03053 │ 25.0 │
│ 11 │ 882 │ 0.05 │ 44.1 │ 0.02834 │ 25.0 │
│ 12 │ 945 │ 0.05 │ 47.25 │ 0.02646 │ 25.0 │
│ 13 │ 1008 │ 0.05 │ 50.4 │ 0.0248 │ 25.0 │
│ 14 │ 1071 │ 0.05 │ 53.55 │ 0.02334 │ 25.0 │
│ 15 │ 1134 │ 0.05 │ 56.7 │ 0.02205 │ 25.0 │
│ 16 │ 1197 │ 0.05 │ 59.85 │ 0.02089 │ 25.0 │
└───────┴───────┴──────────────┴───────────────────┴────────────┴─────────────────┘We put the measure into a MeanRisk unchanged. The cross-validation refits it on every fold, and nothing tells the optimiser that a slot holds a rule.
mr_rule = MeanRisk(; r = cvar_rule, opt = JuMPOptimiser(; slv = slv))mr_stated = MeanRisk(; r = cvar_stated, opt = JuMPOptimiser(; slv = slv))pred_rule = cross_val_predict(mr_rule, rd, iwf)pred_stated = cross_val_predict(mr_stated, rd, iwf)MultiPeriodPredictionResult
pred ┼ 16-element Vector{PredictionResult}
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
│ PredictionResult ⋯
mrd ┼ PredictionReturnsResult
│ nx ┼ 20-element SubArray{String, 1, Vector{String}, Tuple{Base.Slice{Base.OneTo{Int64}}}, true}
│ X ┼ 1008-element Vector{Float64}
│ nf ┼ nothing
│ F ┼ nothing
│ nb ┼ nothing
│ B ┼ nothing
│ ne ┼ nothing
│ E ┼ nothing
│ ts ┼ 1008-element Vector{Date}
│ iv ┼ nothing
│ ivpa ┴ nothing
id ┼ nothing
opt ┴ nothing
Both runs use the same folds, so the out-of-sample series are comparable.
var_rm = LowOrderMoment(; alg = SecondMoment())println("calibrated out-of-sample variance = $(expected_risk(var_rm, pred_rule))")println("stated out-of-sample variance = $(expected_risk(var_rm, pred_stated))")calibrated out-of-sample variance = 0.0001617552464810417
stated out-of-sample variance = 0.0001528012200803102We put the level the rule produced next to the out-of-sample risk of each run, fold by fold. The two runs differ only in the measure the folds priced.
fold_risk = DataFrame(:fold => 1:length(iwf_res.train_idx), :T => length.(iwf_res.train_idx), :alpha_rule => fold_table.alpha_rule, :risk_rule => expected_risk.(Ref(var_rm), pred_rule.pred), :risk_stated => expected_risk.(Ref(var_rm), pred_stated.pred))pretty_table(fold_risk; formatters = [numfmt])┌───────┬───────┬────────────┬───────────┬─────────────┐
│ fold │ T │ alpha_rule │ risk_rule │ risk_stated │
│ Int64 │ Int64 │ Float64 │ Float64 │ Float64 │
├───────┼───────┼────────────┼───────────┼─────────────┤
│ 1 │ 252 │ 0.09921 │ 8.257e-5 │ 6.592e-5 │
│ 2 │ 315 │ 0.07937 │ 3.79e-5 │ 3.671e-5 │
│ 3 │ 378 │ 0.06614 │ 7.018e-5 │ 7.204e-5 │
│ 4 │ 441 │ 0.05669 │ 4.592e-5 │ 4.382e-5 │
│ 5 │ 504 │ 0.0496 │ 0.00114 │ 0.00114 │
│ 6 │ 567 │ 0.04409 │ 0.0002424 │ 0.0002448 │
│ 7 │ 630 │ 0.03968 │ 0.0001013 │ 9.779e-5 │
│ 8 │ 693 │ 0.03608 │ 6.71e-5 │ 6.208e-5 │
│ 9 │ 756 │ 0.03307 │ 8.318e-5 │ 7.246e-5 │
│ 10 │ 819 │ 0.03053 │ 5.159e-5 │ 4.456e-5 │
│ 11 │ 882 │ 0.02834 │ 4.094e-5 │ 3.754e-5 │
│ 12 │ 945 │ 0.02646 │ 0.0001739 │ 0.0001048 │
│ 13 │ 1008 │ 0.0248 │ 7.724e-5 │ 7.74e-5 │
│ 14 │ 1071 │ 0.02334 │ 0.0002046 │ 0.0001911 │
│ 15 │ 1134 │ 0.02205 │ 8.97e-5 │ 8.215e-5 │
│ 16 │ 1197 │ 0.02089 │ 0.0001024 │ 9.313e-5 │
└───────┴───────┴────────────┴───────────┴─────────────┘We print the weights of the calibrated run, one column per fold.
pretty_table(hcat(DataFrame(:tickers => rd.nx), DataFrame(reduce(hcat, getproperty.(pred_rule.res, :w)), Symbol.(1:length(pred_rule.res)))); formatters = [resfmt])┌─────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
│ tickers │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 9 │ 10 │ 11 │ 12 │ 13 │ 14 │ 15 │ 16 │
│ String │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │ Float64 │
├─────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤
│ AAPL │ 1.264 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │
│ AMD │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │
│ BAC │ 0.0 % │ 1.588 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │
│ BBY │ 8.947 % │ 9.093 % │ 3.834 % │ 4.703 % │ 5.543 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.122 % │ 0.122 % │ 0.0 % │ 0.0 % │
│ CVX │ 0.0 % │ 0.0 % │ 10.285 % │ 4.262 % │ 1.929 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │
│ GE │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │
│ HD │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 3.854 % │ 3.854 % │ 0.0 % │ 0.0 % │
│ JNJ │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 1.871 % │ 0.0 % │ 0.0 % │ 0.0 % │ 4.298 % │ 4.298 % │ 4.298 % │ 0.0 % │ 0.0 % │ 3.198 % │ 3.198 % │
│ JPM │ 0.0 % │ 0.0 % │ 2.556 % │ 4.067 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │
│ KO │ 51.109 % │ 8.709 % │ 8.1 % │ 8.968 % │ 10.808 % │ 13.865 % │ 7.165 % │ 8.371 % │ 7.233 % │ 6.064 % │ 6.064 % │ 6.064 % │ 11.181 % │ 11.181 % │ 6.61 % │ 6.61 % │
│ LLY │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.335 % │ 2.648 % │ 2.648 % │ 2.648 % │ 0.0 % │ 0.0 % │ 0.217 % │ 0.217 % │
│ MRK │ 18.552 % │ 19.457 % │ 23.331 % │ 20.809 % │ 14.38 % │ 42.447 % │ 44.553 % │ 42.721 % │ 47.03 % │ 48.825 % │ 48.825 % │ 48.825 % │ 27.692 % │ 27.692 % │ 41.52 % │ 41.52 % │
│ MSFT │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │
│ PEP │ 2.579 % │ 17.383 % │ 21.305 % │ 26.964 % │ 29.443 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │
│ PFE │ 0.032 % │ 3.223 % │ 4.132 % │ 5.585 % │ 8.736 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 6.929 % │ 6.929 % │ 15.276 % │ 15.276 % │
│ PG │ 10.523 % │ 30.281 % │ 26.457 % │ 23.876 % │ 19.842 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.18 % │ 0.18 % │ 0.18 % │ 0.0 % │ 0.0 % │ 0.755 % │ 0.755 % │
│ RRC │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.489 % │ 0.489 % │ 0.489 % │ 2.082 % │ 2.082 % │ 4.791 % │ 4.791 % │
│ UNH │ 6.994 % │ 4.497 % │ 0.0 % │ 0.766 % │ 9.319 % │ 0.0 % │ 1.442 % │ 3.795 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 2.561 % │ 2.561 % │ 0.0 % │ 0.0 % │
│ WMT │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 41.817 % │ 46.84 % │ 45.113 % │ 45.402 % │ 37.495 % │ 37.495 % │ 37.495 % │ 45.578 % │ 45.578 % │ 27.633 % │ 27.633 % │
│ XOM │ 0.0 % │ 5.768 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │ 0.0 % │
└─────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘4. Three of the rules
The library has eleven rules over the five families. Five of them compute a significance level or a deformation parameter, and this section runs three of those five. Each answers a different question about the sample.
- A
CountOfanswers how many observations must the tail hold. It uses Kish's effective sample size when observation weights are stated, because a weighted tail has fewer independent observations than its row count suggests. RateSignificanceanswers how fast may the tail move outwards.alpha = c / sqrt(T)leavesc * sqrt(T)observations in the tail, which grows with the sample but more slowly than the sample does. That is the rate at which a sample mean's own error falls. It uses the same count as aCountOf, becausec * sqrt(T)counts the observations in the tail only whenTcounts the observations that the measure prices.EntropyBudgetanswers what may the deformation cost. Section 5 puts it on a $\kappa$ slot.
The deformation family has two more rules, and both answer a different question: how fast does this sample's tail decay. Each estimates a tail index and returns its reciprocal. HillTailDecay standardises every column by its own dispersion and keeps the sign of the end, so a skewed sample gives one number for the loss end and another for the gain end. RadialTailDecay whitens each observation with the covariance matrix and measures a distance, so it returns one number for both ends. Both fit any $\kappa$ slot, as EntropyBudget does, and section 6 runs both.
count_rule = ConditionalValueatRisk(; alpha = CountOf(25))rate_rule = ConditionalValueatRisk(; alpha = RateSignificance(; c = 1.5))rule_table = DataFrame(:fold => 1:length(iwf_res.train_idx), :T => length.(iwf_res.train_idx), :scenario_count => [resolved(count_rule, idx, :alpha) for idx in iwf_res.train_idx], :rate => [resolved(rate_rule, idx, :alpha) for idx in iwf_res.train_idx])rule_table.count_tail = rule_table.scenario_count .* rule_table.Trule_table.rate_tail = rule_table.rate .* rule_table.Tpretty_table(rule_table; formatters = [numfmt])┌───────┬───────┬────────────────┬─────────┬────────────┬───────────┐
│ fold │ T │ scenario_count │ rate │ count_tail │ rate_tail │
│ Int64 │ Int64 │ Float64 │ Float64 │ Float64 │ Float64 │
├───────┼───────┼────────────────┼─────────┼────────────┼───────────┤
│ 1 │ 252 │ 0.09921 │ 0.09449 │ 25.0 │ 23.81 │
│ 2 │ 315 │ 0.07937 │ 0.08452 │ 25.0 │ 26.62 │
│ 3 │ 378 │ 0.06614 │ 0.07715 │ 25.0 │ 29.16 │
│ 4 │ 441 │ 0.05669 │ 0.07143 │ 25.0 │ 31.5 │
│ 5 │ 504 │ 0.0496 │ 0.06682 │ 25.0 │ 33.67 │
│ 6 │ 567 │ 0.04409 │ 0.06299 │ 25.0 │ 35.72 │
│ 7 │ 630 │ 0.03968 │ 0.05976 │ 25.0 │ 37.65 │
│ 8 │ 693 │ 0.03608 │ 0.05698 │ 25.0 │ 39.49 │
│ 9 │ 756 │ 0.03307 │ 0.05455 │ 25.0 │ 41.24 │
│ 10 │ 819 │ 0.03053 │ 0.05241 │ 25.0 │ 42.93 │
│ 11 │ 882 │ 0.02834 │ 0.05051 │ 25.0 │ 44.55 │
│ 12 │ 945 │ 0.02646 │ 0.0488 │ 25.0 │ 46.11 │
│ 13 │ 1008 │ 0.0248 │ 0.04725 │ 25.0 │ 47.62 │
│ 14 │ 1071 │ 0.02334 │ 0.04583 │ 25.0 │ 49.09 │
│ 15 │ 1134 │ 0.02205 │ 0.04454 │ 25.0 │ 50.51 │
│ 16 │ 1197 │ 0.02089 │ 0.04336 │ 25.0 │ 51.9 │
└───────┴───────┴────────────────┴─────────┴────────────┴───────────┘Under the scenario count the tail population count_tail is flat, and under the rate rate_tail grows with the square root of T.
Observation weights move both rules. A measure that has w passes those weights to the rule, and both rules divide by Kish's effective sample size rather than by the row count. The effective size is the smaller of the two, so each weighted level is the higher.
obs_w = pweights(range(; start = 1, stop = 2, length = length(iwf_res.train_idx[1])))count_weighted = ConditionalValueatRisk(; alpha = count_rule.alpha, w = obs_w)rate_weighted = ConditionalValueatRisk(; alpha = rate_rule.alpha, w = obs_w)first_idx = iwf_res.train_idx[1]weight_table = DataFrame(:rule => ["CountOf", "RateSignificance"], :unweighted => [resolved(count_rule, first_idx, :alpha), resolved(rate_rule, first_idx, :alpha)], :weighted => [resolved(count_weighted, first_idx, :alpha), resolved(rate_weighted, first_idx, :alpha)])pretty_table(weight_table; formatters = [numfmt])┌──────────────────┬────────────┬──────────┐
│ rule │ unweighted │ weighted │
│ String │ Float64 │ Float64 │
├──────────────────┼────────────┼──────────┤
│ CountOf │ 0.09921 │ 0.1029 │
│ RateSignificance │ 0.09449 │ 0.09624 │
└──────────────────┴────────────┴──────────┘Both levels rise, because a weighted tail holds fewer independent observations than its rows. The level of the count rises in inverse proportion to the effective count, and the rate rises with its square root.
5. The two slots that resolve together
RelativisticValueatRisk has two calibration slots, alpha and kappa. EntropyBudget states the price of the deformation directly: RRM multiplies its dual variable by kappa_log(inv(alpha * T), kappa), and the rule returns the $\kappa$ that meets a stated value of that coefficient.
The rule therefore needs the alpha of the same measure. alpha resolves first, and the $\kappa$ rule uses the number it produced, so both slots resolve in one pass over the measure.
rlvar_rule = RelativisticValueatRisk(; alpha = CountOf(25), kappa = EntropyBudget(; target = -6.0))rlvar_stated = RelativisticValueatRisk(; alpha = 0.05, kappa = EntropyBudget(; target = -6.0))pair_table = DataFrame(:fold => 1:length(iwf_res.train_idx), :T => length.(iwf_res.train_idx), :alpha => [resolved(rlvar_rule, idx, :alpha) for idx in iwf_res.train_idx], :kappa => [resolved(rlvar_rule, idx, :kappa) for idx in iwf_res.train_idx], :kappa_stated_alpha => [resolved(rlvar_stated, idx, :kappa) for idx in iwf_res.train_idx])pretty_table(pair_table; formatters = [numfmt])┌───────┬───────┬─────────┬─────────┬────────────────────┐
│ fold │ T │ alpha │ kappa │ kappa_stated_alpha │
│ Int64 │ Int64 │ Float64 │ Float64 │ Float64 │
├───────┼───────┼─────────┼─────────┼────────────────────┤
│ 1 │ 252 │ 0.09921 │ 0.6371 │ 0.9727 │
│ 2 │ 315 │ 0.07937 │ 0.6371 │ 0.8428 │
│ 3 │ 378 │ 0.06614 │ 0.6371 │ 0.753 │
│ 4 │ 441 │ 0.05669 │ 0.6371 │ 0.6863 │
│ 5 │ 504 │ 0.0496 │ 0.6371 │ 0.6341 │
│ 6 │ 567 │ 0.04409 │ 0.6371 │ 0.5919 │
│ 7 │ 630 │ 0.03968 │ 0.6371 │ 0.5569 │
│ 8 │ 693 │ 0.03608 │ 0.6371 │ 0.5271 │
│ 9 │ 756 │ 0.03307 │ 0.6371 │ 0.5013 │
│ 10 │ 819 │ 0.03053 │ 0.6371 │ 0.4788 │
│ 11 │ 882 │ 0.02834 │ 0.6371 │ 0.4588 │
│ 12 │ 945 │ 0.02646 │ 0.6371 │ 0.4409 │
│ 13 │ 1008 │ 0.0248 │ 0.6371 │ 0.4248 │
│ 14 │ 1071 │ 0.02334 │ 0.6371 │ 0.4101 │
│ 15 │ 1134 │ 0.02205 │ 0.6371 │ 0.3967 │
│ 16 │ 1197 │ 0.02089 │ 0.6371 │ 0.3844 │
└───────┴───────┴─────────┴─────────┴────────────────────┘The kappa column is flat and the kappa_stated_alpha column is not. The coefficient depends on inv(alpha * T), and a scenario count fixes alpha * T at the count itself, so the budget gives the same deformation on every fold. A stated alpha lets alpha * T grow with the window, so the same budget gives a different deformation each time.
The rule has one check, and it is not a range check on the $\kappa$ it returns. With $u = 1/(\alpha T)$, the first argument of kappa_log above, the coefficient reaches only the band between $\ln(u)$ and $\sinh(\ln(u))$, so no $\kappa$ meets a target outside that band. The band moves with alpha and with the sample, and the refusal names both.
try resolved(RelativisticValueatRisk(; alpha = 0.05, kappa = EntropyBudget(; target = -1.5)), first_idx, :kappa)catch e println(sprint(showerror, e))endDomainError with -1.5:
`EntropyBudget.target` must lie in (-6.260317460317461, -2.5336968139574325), the band that `kappa_log(inv(alpha * T), kappa)` reaches over `kappa` in (0, 1) at `alpha = 0.05` and `T = 252`. No deformation parameter meets a target outside it, so the rule has nothing to return. The band moves with the sample, so a target that suits one fold need not suit another.6. The two tail-decay rules
HillTailDecay and RadialTailDecay ask the same question, how fast does this sample's tail decay, and they measure two different quantities to answer it. Each estimates a tail index and returns its reciprocal, which is the $\kappa$ whose deformed exponential decays at that rate.
RelativisticValueatRiskRange has a $\kappa$ slot at each end, so one measure gives both answers. Each end resolves a pair of its own. kappa_a uses alpha, and kappa_b uses beta.
hill_range = RelativisticValueatRiskRange(; kappa_a = HillTailDecay(), kappa_b = HillTailDecay())radial_range = RelativisticValueatRiskRange(; kappa_a = RadialTailDecay(), kappa_b = RadialTailDecay())hill_res = factory(hill_range, pr)radial_res = factory(radial_range, pr)decay_table = DataFrame(:rule => ["HillTailDecay", "RadialTailDecay"], :kappa_a => [hill_res.kappa_a, radial_res.kappa_a], :kappa_b => [hill_res.kappa_b, radial_res.kappa_b])pretty_table(decay_table; formatters = [numfmt])┌─────────────────┬─────────┬─────────┐
│ rule │ kappa_a │ kappa_b │
│ String │ Float64 │ Float64 │
├─────────────────┼─────────┼─────────┤
│ HillTailDecay │ 0.3748 │ 0.4097 │
│ RadialTailDecay │ 0.2438 │ 0.2438 │
└─────────────────┴─────────┴─────────┘The Hill row has two numbers, because the rule keeps the sign of the end and estimates the loss tail under kappa_a and the gain tail under kappa_b. The Radial row has one number twice, because the rule whitens each observation and measures a distance, and a distance has no sign. The two Hill numbers differ because the sample is skewed. A sample with no skew has one index at both ends, and two estimates of it then differ by their own noise alone.
println("pooled skewness = $(skewness(vec(pr.X)))")pooled skewness = 0.4329087335879439The Hill number is the tail index that the standardised columns share, estimated from the pool of every column's values, and the Radial number is the index of the whole cross-section's radius.
The rule refits per fold, as every other rule does. The two ends move apart by a different amount on every window, and which end has the heavier tail is a property of the window, not of the whole record.
decay_fold = DataFrame(:fold => 1:length(iwf_res.train_idx), :T => length.(iwf_res.train_idx), :kappa_a => [resolved(hill_range, idx, :kappa_a) for idx in iwf_res.train_idx], :kappa_b => [resolved(hill_range, idx, :kappa_b) for idx in iwf_res.train_idx])pretty_table(decay_fold; formatters = [numfmt])┌───────┬───────┬─────────┬─────────┐
│ fold │ T │ kappa_a │ kappa_b │
│ Int64 │ Int64 │ Float64 │ Float64 │
├───────┼───────┼─────────┼─────────┤
│ 1 │ 252 │ 0.3322 │ 0.3251 │
│ 2 │ 315 │ 0.3299 │ 0.3243 │
│ 3 │ 378 │ 0.3354 │ 0.317 │
│ 4 │ 441 │ 0.3403 │ 0.3303 │
│ 5 │ 504 │ 0.3405 │ 0.333 │
│ 6 │ 567 │ 0.4576 │ 0.4877 │
│ 7 │ 630 │ 0.4297 │ 0.497 │
│ 8 │ 693 │ 0.4205 │ 0.478 │
│ 9 │ 756 │ 0.419 │ 0.4682 │
│ 10 │ 819 │ 0.4089 │ 0.4523 │
│ 11 │ 882 │ 0.4028 │ 0.4418 │
│ 12 │ 945 │ 0.3961 │ 0.439 │
│ 13 │ 1008 │ 0.3942 │ 0.435 │
│ 14 │ 1071 │ 0.3869 │ 0.4289 │
│ 15 │ 1134 │ 0.3785 │ 0.4205 │
│ 16 │ 1197 │ 0.377 │ 0.4123 │
└───────┴───────┴─────────┴─────────┘The Radial rule refuses the first fold, because of the count. Both rules estimate the tail from the k most extreme values of a pool, and both refuse a k below kmin. The Hill pool holds T * N standardised values, and the radial pool holds T distances. The same minimum therefore binds N times harder on the radial side, and a one-year fold at alpha = 0.05 leaves it 13 distances.
try resolved(radial_range, first_idx, :kappa_a)catch e println(sprint(showerror, e))endDomainError with 13:
`RadialTailDecay` reads the largest `k = ceil(alpha * T) = 13` of the 252 radial distances, and `RadialTailDecay.kmin` puts the floor at 30. A Hill estimate over fewer order statistics moves from fold to fold for no reason in the data, and the deformation parameter moves with it. The radial series holds one entry per observation where the pool of `HillTailDecay` holds `N`, so the same floor binds harder here. Lengthen the sample, widen `alpha`, or lower `kmin` and take the noise.7. A plain function as a rule
The library runs a rule by calling it, so a callable struct and a plain function work the same way. A plain function is the rule that needs no library type, and it is the shortest way to state a one-off rule. The signature is (key, pr, w, slv, ctx):
key: name of the slot being resolved;pr: prior result the rule takes the sample size and the moments from;w: effective observation weights, ornothing;slv: effective solver, ornothing;ctx: aCalibrationContext, which holds what the slot's owner knows andkeydoes not: the significance level of a sibling slot, the series the owner prices, and the norm order of the constraint the quantity stands in. A rule that uses none of the three names the type and ignores it, as this one does.
key matters on a Range measure, where one function serves both ends and looks up its own budget for each.
tail_budget = Dict(:alpha => 25, :beta => 50)budgeted(key, pr, w, slv, ctx) = tail_budget[key] / size(pr.X, 1)vrr = ValueatRiskRange(; alpha = budgeted, beta = budgeted)vrr_res = factory(vrr, fold_prior(first_idx))println("alpha = $(vrr_res.alpha), beta = $(vrr_res.beta)")alpha = 0.0992063492063492, beta = 0.1984126984126984Every Range measure that has a beta defaults it to alpha. The rule states the method and the slot states the end, so one rule serves both ends, and beta is the same object as alpha.
An OrderedWeightsArrayRange has no beta. It mirrors its loss tail when you give no w2, so the gain tail is the reversal of the same builder and holds the same rule.
owa_range = OrderedWeightsArrayRange(; w1 = OrderedWeightsArrayConditionalValueatRisk(; alpha = count_rule.alpha))println("w2 is a $(typeof(owa_range.w2).name.name), same rule = $(owa_range.w2.inner.alpha === count_rule.alpha)")w2 is a ComposedFunction, same rule = true8. The slot bounds refuse a rule of the wrong family
Each slot's type bound names the one rule family that computes the quantity the slot holds. A deformation rule in a significance slot therefore fails at construction, before any data reaches the measure.
try ConditionalValueatRisk(; alpha = EntropyBudget(; target = -6.0))catch e println(sprint(showerror, e))endTypeError: in keyword argument alpha, expected Union{Function, Number, AbstractCountOrFraction, AbstractSignificanceCalibrationAlgorithm}, got a value of type EntropyBudget{Float64}A radius and a tail weight are two quantities as well, so each has a family of its own and each slot refuses the other's rule.
try DistributionallyRobustConditionalValueatRisk(; r = TailTermParity(; ratio = 1))catch e println(sprint(showerror, e))endTypeError: in keyword argument r, expected Union{Function, Number, AbstractAmbiguityRadiusCalibrationAlgorithm}, got a value of type TailTermParity{Int64}9. The ambiguity radius and the tail weight
DistributionallyRobustConditionalValueatRisk prices a ball of probability measures around the empirical one. Its r is the radius of that ball and its l is the weight of the tail term, and both are calibration slots beside alpha. So one measure can refit all three quantities per fold.
The library has four radius rules, and this section runs the two below.
ConcentrationRadiusis the Blanchet-Kang-Murthy form: a scale in the units of the returns times the square root of a chi-squared quantile over the sample size. A wider universe gives a wider ball at a fixed confidence level, and a longer sample shrinks it.scale = nothingtakes the average asset volatility from the prior result.RateRadiusisc / sqrt(T). The rate is the part of the form to trust andcis the part to calibrate, so you set a radius by cross-validating overc.
The other two answer a question these two do not. DimensionalRateRadius shrinks the ball at the rate the number of assets sets rather than at the square-root rate of the sample length, which is far slower over a wide universe. DualNormRadius uses the slot's own key, picks the ground metric that slot names, and returns the sampling error in it, so two slots of two different norms get two different numbers. Both fit any radius slot, as the two above do, and the regularisation example runs them, because the slots that separate them are the four penalty coefficients of JuMPOptimiser.
The tail-weight family has one rule, TailTermParity, which prices the tail term of the loss at a stated multiple of its mean term. A function you write works in the slot too, in the form section 7 shows.
drcvar = DistributionallyRobustConditionalValueatRisk(; alpha = count_rule.alpha, r = ConcentrationRadius(; confidence = 0.95), l = TailTermParity(; ratio = 1))drcvar_rate = DistributionallyRobustConditionalValueatRisk(; r = RateRadius(; c = 0.02))amb_table = DataFrame(:fold => 1:length(iwf_res.train_idx), :T => length.(iwf_res.train_idx), :alpha => [resolved(drcvar, idx, :alpha) for idx in iwf_res.train_idx], :concentration_r => [resolved(drcvar, idx, :r) for idx in iwf_res.train_idx], :rate_r => [resolved(drcvar_rate, idx, :r) for idx in iwf_res.train_idx], :l => [resolved(drcvar, idx, :l) for idx in iwf_res.train_idx])pretty_table(amb_table; formatters = [numfmt])┌───────┬───────┬─────────┬─────────────────┬───────────┬───────────┐
│ fold │ T │ alpha │ concentration_r │ rate_r │ l │
│ Int64 │ Int64 │ Float64 │ Float64 │ Float64 │ Float64 │
├───────┼───────┼─────────┼─────────────────┼───────────┼───────────┤
│ 1 │ 252 │ 0.09921 │ 0.005978 │ 0.00126 │ 0.0009744 │
│ 2 │ 315 │ 0.07937 │ 0.005344 │ 0.001127 │ 0.0151 │
│ 3 │ 378 │ 0.06614 │ 0.004756 │ 0.001029 │ 0.01419 │
│ 4 │ 441 │ 0.05669 │ 0.004467 │ 0.0009524 │ 0.01042 │
│ 5 │ 504 │ 0.0496 │ 0.004126 │ 0.0008909 │ 0.01657 │
│ 6 │ 567 │ 0.04409 │ 0.005057 │ 0.0008399 │ 0.005111 │
│ 7 │ 630 │ 0.03968 │ 0.005022 │ 0.0007968 │ 0.009213 │
│ 8 │ 693 │ 0.03608 │ 0.004737 │ 0.0007597 │ 0.01076 │
│ 9 │ 756 │ 0.03307 │ 0.004522 │ 0.0007274 │ 0.01259 │
│ 10 │ 819 │ 0.03053 │ 0.004299 │ 0.0006989 │ 0.01366 │
│ 11 │ 882 │ 0.02834 │ 0.00406 │ 0.0006734 │ 0.01435 │
│ 12 │ 945 │ 0.02646 │ 0.003849 │ 0.0006506 │ 0.0142 │
│ 13 │ 1008 │ 0.0248 │ 0.003691 │ 0.0006299 │ 0.01522 │
│ 14 │ 1071 │ 0.02334 │ 0.00357 │ 0.0006111 │ 0.01486 │
│ 15 │ 1134 │ 0.02205 │ 0.003488 │ 0.0005939 │ 0.01219 │
│ 16 │ 1197 │ 0.02089 │ 0.003376 │ 0.0005781 │ 0.01134 │
└───────┴───────┴─────────┴─────────────────┴───────────┴───────────┘The rate radius falls with every fold, because the window only grows. The concentration radius does not, because of its scale. scale = nothing takes the average asset volatility from the fold's own prior, so a window that takes in a more volatile period gives a wider ball even though it is longer. A radius is in the units of the returns, and the rule takes those units from the fold it is given.
The l column is a ratio of two scales the rule measures on the fold, so it moves with both. The numerator is the mean loss of the pooled cross-section, and the denominator is the mean per-column CVaR at the fold's own alpha. ratio = 1 therefore prices one tail term at one mean term. A fold whose mean return is near zero has a numerator near zero, and so a small l.
The measure optimises in the same way the calibrated CVaR did.
mr_drcvar = MeanRisk(; r = drcvar, opt = JuMPOptimiser(; slv = slv))pred_drcvar = cross_val_predict(mr_drcvar, rd, iwf)println("robust out-of-sample variance = $(expected_risk(var_rm, pred_drcvar))")robust out-of-sample variance = 0.0002023741308281577810. What to take away
- A calibration slot takes a number or a rule, and the other fields of the measure stay the same.
- The rule resolves inside
factory, so a cross-validation refits it per fold, and you get the number a fold produced withfactory(r, pr). - The rule states the question. A scenario count fixes the count of observations in the tail, a rate lets that count grow with the square root of the record, and an entropy budget fixes the price of a deformation.
alpharesolves before $\kappa$, in one pass. A scenario count onalphafixesalpha * T, so the same entropy budget gives the same $\kappa$ on every fold, and a statedalphadoes not.- The two tail-decay rules measure two different quantities.
HillTailDecayanswers per end, andRadialTailDecayanswers once for both. - A plain function of
(key, pr, w, slv, ctx)is a rule, which covers the one-off case in every family. - A slot names its quantity, and its type bound refuses a rule of another family at construction.
- The regularisation example runs the other two radius rules and the three norm ceilings of
JuMPOptimiser.DualNormRadiusgives a different radius to penalties of different norms, and the four penalty coefficients ofJuMPOptimiserare where those norms differ.
This page was generated using Literate.jl.