The source files can be found in examples/.

Portfolio report

portfolio_report puts several predictions into one report. The report has an overview table with one row for each portfolio, and one entry for each prediction with its statistics, its weights and its figures. An entry also shows a finite allocation when you give one. write_report writes the report as Markdown, or as one HTML file that holds its style, its script and its figures. The HTML file opens in any browser with no network access.

This page builds one report from the three kinds of prediction:

  1. the best candidates of a grid search, each one predicted over a walk-forward path,
  2. a population of paths from a combinatorial cross-validation,
  3. one prediction on the last month, with a finite allocation of whole shares.
When to reach for this

Reach for a report when you want to compare many predictions side by side, or to give the results to someone who does not run Julia. Each figure and each statistic of the report comes from a function of the library, so a report shows nothing that you cannot compute yourself. Use performance_summary when you want the numbers alone.

using PortfolioOptimisers, CSV, TimeSeries, DataFrames, Clarabel, HiGHS, StatsPlots

1. The data

We use two years of daily prices. A short window keeps the report small, because a figure of a long daily series is large.

X = TimeArray(CSV.File(joinpath(@__DIR__, "..", "SP500.csv.gz")); timestamp = :Date)[(end - 252 * 2):end]rd = prices_to_returns(X)slv = Solver(; name = :clarabel, solver = Clarabel.Optimizer,             settings = Dict("verbose" => false),             check_sol = (; allow_local = true, allow_almost = true))rf = 4.2 / 100 / 252
0.0001666666666666667

We search the risk measure of a minimum-risk portfolio. The search scores each candidate on a walk-forward scheme with a training window of one year and a test window of one month. n_best = 3 keeps the three best candidates, best first, in ranked. The hyperparameter tuning example explains the search.

mr = MeanRisk(; obj = MinimumRisk(), opt = JuMPOptimiser(; slv = slv))wf = IndexWalkForward(252, 21)gs = GridSearchCrossValidation(["r" => [Variance(), ConditionalValueatRisk(),                                        ConditionalDrawdownatRisk(), UlcerIndex(),                                        MaximumDrawdown()]];                               r = MeanReturnRiskRatio(; rk = ConditionalValueatRisk(),                                                       rf = rf), cv = wf, n_best = 3)gs_res = search_cross_validation(mr, gs, rd)[nameof(typeof(e.r)) for e in gs_res.ranked]
3-element Vector{Symbol}:
 :ConditionalDrawdownatRisk
 :UlcerIndex
 :Variance

A search scores the candidates, but it keeps no prediction. We predict each ranked candidate over the same walk-forward scheme. Each prediction is a MultiPeriodPredictionResult, one path of consecutive test windows.

cands = [cross_val_predict(e, rd, wf) for e in gs_res.ranked]
3-element Vector{MultiPeriodPredictionResult{Vector{PredictionResult{PredictionReturnsResult{SubArray{String, 1, Vector{String}, Tuple{Base.Slice{Base.OneTo{Int64}}}, true}, Vector{Float64}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, SubArray{Date, 1, Vector{Date}, Tuple{UnitRange{Int64}}, true}, Nothing, Nothing}, Nothing, UnitRange{Int64}}}, PredictionReturnsResult{SubArray{String, 1, Vector{String}, Tuple{Base.Slice{Base.OneTo{Int64}}}, true}, Vector{Float64}, Nothing, Nothing, Nothing, Nothing, Nothing, Nothing, Vector{Date}, Nothing, Nothing}, Nothing}}:
 MultiPeriodPredictionResult
  pred ┼ 12-element Vector{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 ┼ 252-element Vector{Float64}
       │     nf ┼ nothing
       │      F ┼ nothing
       │     nb ┼ nothing
       │      B ┼ nothing
       │     ne ┼ nothing
       │      E ┼ nothing
       │     ts ┼ 252-element Vector{Date}
       │     iv ┼ nothing
       │   ivpa ┴ nothing
    id ┼ nothing
   opt ┴ nothing

 MultiPeriodPredictionResult
  pred ┼ 12-element Vector{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 ┼ 252-element Vector{Float64}
       │     nf ┼ nothing
       │      F ┼ nothing
       │     nb ┼ nothing
       │      B ┼ nothing
       │     ne ┼ nothing
       │      E ┼ nothing
       │     ts ┼ 252-element Vector{Date}
       │     iv ┼ nothing
       │   ivpa ┴ nothing
    id ┼ nothing
   opt ┴ nothing

 MultiPeriodPredictionResult
  pred ┼ 12-element Vector{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 ┼ 252-element Vector{Float64}
       │     nf ┼ nothing
       │      F ┼ nothing
       │     nb ┼ nothing
       │      B ┼ nothing
       │     ne ┼ nothing
       │      E ┼ nothing
       │     ts ┼ 252-element Vector{Date}
       │     iv ┼ nothing
       │   ivpa ┴ nothing
    id ┼ nothing
   opt ┴ nothing

3. A population of paths

A walk-forward path is one history out of many. CombinatorialCrossValidation tests the best candidate on several paths, and the result is a PopulationPredictionResult. Its entry in the report gives one row for each path, and the distribution of each statistic over the paths.

ppred = cross_val_predict(gs_res.opt, rd,                          CombinatorialCrossValidation(; n_folds = 5, n_test_folds = 2))length(ppred.pred)
4

4. One fold and its allocation

We fit the best candidate on every row but the last month, and predict the last month. The result is a PredictionResult. DiscreteAllocation turns its weights into whole shares of a budget of $100,000 at the last prices. The finite allocation example explains the allocation.

train, test = train_test_split(rd; test_size = 21)res = optimise(gs_res.opt, train)pred = predict(res, test)mip_slv = Solver(; name = :highs, solver = HiGHS.Optimizer,                 settings = Dict("log_to_console" => false))alloc = optimise(DiscreteAllocation(; slv = mip_slv),                 FiniteAllocationInput(; w = res.w, prices = vec(values(X)[end, :]),                                       cash = 100_000.0))
DiscreteAllocationResult
    retcode ┼ OptimisationSuccess
            │   res ┴ nothing
  s_retcode ┼ OptimisationSuccess
            │   res ┴ Dict{Union{AbstractString, Symbol}, AbstractDict{Symbol}}: Dict{Union{AbstractString, Symbol}, AbstractDict{Symbol}}()
  l_retcode ┼ OptimisationSuccess
            │   res ┴ Dict{Union{AbstractString, Symbol}, AbstractDict{Symbol}}: Dict{Union{AbstractString, Symbol}, AbstractDict{Symbol}}()
     shares ┼ 20-element SubArray{Float64, 1, Matrix{Float64}, Tuple{Base.Slice{Base.OneTo{Int64}}, Int64}, true}
       cost ┼ 20-element SubArray{Float64, 1, Matrix{Float64}, Tuple{Base.Slice{Base.OneTo{Int64}}, Int64}, true}
          w ┼ 20-element SubArray{Float64, 1, Matrix{Float64}, Tuple{Base.Slice{Base.OneTo{Int64}}, Int64}, true}
       cash ┼ Float64: 14.937999999994645
       fees ┼ Float64: 0.0
    s_model ┼ A JuMP Model
            │ ├ solver: HiGHS
            │ ├ objective_sense: MIN_SENSE
            │ │ └ objective_function_type: AffExpr
            │ ├ num_variables: 5
            │ ├ num_constraints: 10
            │ │ ├ AffExpr in MOI.GreaterThan{Float64}: 1
            │ │ ├ Vector{AffExpr} in MOI.NormOneCone: 1
            │ │ ├ VariableRef in MOI.GreaterThan{Float64}: 4
            │ │ └ VariableRef in MOI.Integer: 4
            │ └ Names registered in the model
            │   └ :cerr, :cr, :fee, :r, :sc, :so, :u, :x, :z
    l_model ┼ A JuMP Model
            │ ├ solver: HiGHS
            │ ├ objective_sense: MIN_SENSE
            │ │ └ objective_function_type: AffExpr
            │ ├ num_variables: 17
            │ ├ num_constraints: 34
            │ │ ├ AffExpr in MOI.GreaterThan{Float64}: 1
            │ │ ├ Vector{AffExpr} in MOI.NormOneCone: 1
            │ │ ├ VariableRef in MOI.GreaterThan{Float64}: 16
            │ │ └ VariableRef in MOI.Integer: 16
            │ └ Names registered in the model
            │   └ :cerr, :cr, :fee, :r, :sc, :so, :u, :x, :z
         fb ┴ nothing

5. The report

portfolio_report takes the predictions as one vector and their names. The keywords that it does not use pass to performance_summary. We keep them in ps_kw: ppy annualises the daily figures, rf is the risk-free rate of one day, and measures adds two risk measures by name. groups labels each prediction, and the HTML file shows or hides the portfolios of each group. allocs gives the finite allocation of each prediction, or nothing.

default_report_figures gives the default figures when StatsPlots is loaded: overview_figures draws every prediction on one figure, and entry_figures draws one prediction. The fields take the names of the keywords of portfolio_report, so figs... passes both, and a keyword after it replaces one. A figure of your own is a pair caption => f. An entry figure calls f(pred), and a function that returns nothing adds no figure. Here the turnover figure draws a walk-forward path and skips the other two kinds of prediction.

turnover_figure(p::MultiPeriodPredictionResult) = plot_turnover(p)turnover_figure(::Any) = nothingfigs = default_report_figures()preds = [cands; ppred; pred]labels = ["search rank 1", "search rank 2", "search rank 3", "best, all paths",          "best, last month"]ps_kw = (; ppy = 252, rf = rf,         measures = [:cvar_95 => ConditionalValueatRisk(), :ulcer => UlcerIndex()])r = portfolio_report(preds; names = labels, title = "Minimum risk portfolios",                     groups = ["search", "search", "search", "population", "single fold"],                     allocs = [nothing, nothing, nothing, nothing, alloc], figs...,                     entry_figures = [figs.entry_figures; "Turnover" => turnover_figure],                     ps_kw...);

A Report shows itself as the whole HTML document, so the cell above ends with a semicolon. The next cell lists the sections of each entry. Only the single fold has an Allocation section.

[e.name => [s.title for s in e.sections] for e in r.entries]
5-element Vector{Pair{String, Vector{String}}}:
    "search rank 1" => ["Statistics", "Weights", "Figures"]
    "search rank 2" => ["Statistics", "Weights", "Figures"]
    "search rank 3" => ["Statistics", "Weights", "Figures"]
  "best, all paths" => ["Statistics", "Weights", "Figures"]
 "best, last month" => ["Statistics", "Weights", "Allocation", "Figures"]

The overview table of the report is the table of performance_summary with the same keywords, so the numbers of the report are the numbers that you compute yourself.

DataFrame(performance_summary(preds; names = labels, ps_kw...))
8×25 DataFrame
Rownamepathmemberdate0date1n_periodsann_returnann_volatilitysharpesharpe_stderrsortinocalmarmax_drawdowncvarexcess_rettracking_errorinformation_ratioturnovern_efflong_exposureshort_exposuregross_exposurenet_exposurecvar_95ulcer
StringUnion…NothingDateDateInt64Float64Float64Float64Float64Float64Float64Float64Float64Float64Float64Float64Float64Float64Float64Float64Float64Float64Float64Float64
1search rank 12021-12-292022-12-282520.0842720.1716980.24621.004430.3403290.60144-0.140117-0.0238902NaNNaNNaN0.5399454.5881.01.82428e-111.01.00.02389020.0548571
2search rank 22021-12-292022-12-282520.04781460.1713080.03394211.002350.04621140.341481-0.140021-0.0240736NaNNaNNaN0.5771875.210211.00.01.01.00.02407360.0564407
3search rank 32021-12-292022-12-282520.05363320.1621070.07176261.00250.09955340.423364-0.126684-0.0216715NaNNaNNaN0.2951287.594271.00.01.01.00.02167150.05536
4best, all paths12020-12-292022-12-285040.1923540.1427851.053010.7124331.517371.41895-0.135561-0.019872NaNNaNNaN0.5916443.674621.02.01748e-111.01.00.0198720.0415414
5best, all paths22020-12-292022-12-285040.1884970.1445071.013770.7113061.471.48456-0.126972-0.0196215NaNNaNNaN0.6939634.314281.05.01224e-121.01.00.01962150.0380844
6best, all paths32020-12-292022-12-285040.2255880.1433071.281080.7131721.874712.2707-0.0993473-0.0195037NaNNaNNaN0.4871984.556591.03.57201e-111.01.00.01950370.0290017
7best, all paths42020-12-292022-12-285040.1828040.1566840.8986520.7138761.274081.28399-0.142372-0.0222387NaNNaNNaN0.600184.726191.02.68774e-121.01.00.02223870.0414399
8best, last month2022-11-292022-12-2821-0.1012020.132251-1.082813.54592-1.45792-3.25882-0.0310549-0.0145689NaNNaNNaNNaN3.336241.02.49198e-111.01.00.01456890.0188111

6. Write the report

The extension of the path chooses the format. The figures are SVG images by default, and an SVG image holds every point of its series. PNG images keep the file small, so we write both files with PNG figures and print their sizes in MiB.

html = write_report("portfolio_report.html", r; figure_mime = MIME"image/png"())md = write_report("portfolio_report.md", r; figure_mime = MIME"image/png"())(html = filesize(html) / 2^20, md = filesize(md) / 2^20)
(html = 1.3171501159667969, md = 1.2361574172973633)

The Markdown file starts with the title and the overview table, and a figure is an image with its data in the link.

foreach(println, first(eachline(md), 6))
# Minimum risk portfolios

## Overview

*One row for each portfolio, path and member\. A click on a row shows its portfolio\.*

7. The report on this page

The frame below shows the HTML file that the cell above wrote. Choose a portfolio in the list at the top, or click its row of the overview, to open its entry. Click a column head to sort a table. Clear the box of a group to hide its portfolios, and use the theme button to change between light and dark. You can also open the report in its own tab.


This page was generated using Literate.jl.