Plotting

PortfolioOptimisers.plot_portfolio_cumulative_returns — Function

plot_portfolio_cumulative_returns(
    w::VecNum_VecVecNum,
    X::MatNum,
    fees::Option{<:Fees} = nothing;
    ts::AbstractVector = 1:size(X, 1),
    compound::Bool = false,
    kwargs...
) -> Plot
plot_portfolio_cumulative_returns(
    w::VecNum_VecVecNum,
    pr::Pr_RR,
    fees::Option{<:Fees} = nothing;
    ts::AbstractVector = 1:size(pr.X, 1),
    compound::Bool = false,
    kwargs...
) -> Plot
plot_portfolio_cumulative_returns(
    res::OptimisationResult,
    pr::Pr_RR;
    fees::Option{<:Fees} = nothing,
    compound::Bool = false,
    kwargs...
) -> Plot
plot_portfolio_cumulative_returns(
    res::OptimisationResult;
    fees::Option{<:Fees} = nothing,
    compound::Bool = false,
    kwargs...
) -> Plot
plot_portfolio_cumulative_returns(
    pred::Union{
                    <:PredictionResult,
                    <:MultiPeriodPredictionResult,
                    <:PopulationPredictionResult
                };
    compound::Bool = false,
    kwargs...
) -> Plot

Plot the cumulative returns of a portfolio.

A gapped panel reaches this figure only through the returns the caller hands it. A prediction arity is finite already, because the fold zeroed the Held Gap once in predict. A w, X or w, rd arity computes on the matrix the caller holds and checks nothing: X * w is NaN at a gap even where the weight is zero. Score a gapped panel through predict(res, rd) and plot the prediction.

Arguments

w: Portfolio weights vector or vector of weight vectors.
X: Asset returns matrix (observations × assets).
fees::Option{<:Fees} = nothing: Optional transaction fees.
ts::AbstractVector = 1:size(X, 1): Time axis labels.
compound::Bool = false: If true, compound cumulative returns; otherwise use simple cumulative sums.
pr: Prior or returns result; extracts X, ts, and nx automatically when available.
res::OptimisationResult: Extracts w and fees when available.
pred: Predicted portfolio results.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_asset_cumulative_returns — Function

plot_asset_cumulative_returns(
    w::VecNum,
    X::MatNum,
    fees::Option{<:Fees} = nothing;
    ts::AbstractVector = 1:size(X, 1),
    nx::AbstractVector = 1:size(X, 2),
    compound::Bool = false,
    N::Option{<:Number} = nothing,
    kwargs...
) -> Plot
plot_asset_cumulative_returns(w::VecNum, pr::Pr_RR, fees = nothing; compound, N, kwargs...) -> Plot
plot_asset_cumulative_returns(res::OptimisationResult[, pr]; compound, N, kwargs...) -> Plot
plot_asset_cumulative_returns(pred; compound, N, kwargs...) -> Plot

Plot the cumulative returns of individual assets, selecting the most relevant via N. Assets beyond the top N are aggregated into an "Others" series.

A per-asset line keeps its gap, which the backend draws as a break, and that break is the delisting. Read against a prediction the same line is flat, because the fold zeroed the Held Gap before the series was formed. The "Others" aggregate cannot keep a gap: one NaN poisons every date of the sum, at any weight, so it excludes a column that is not finite throughout, through finite_columns. The aggregate therefore describes the rest of the universe without the assets it cannot value.

Arguments

w: Portfolio weights vector.
X: Asset returns matrix (observations × assets).
fees::Option{<:Fees} = nothing: Optional transaction fees.
ts::AbstractVector = 1:size(X, 1): Time axis labels.
nx::AbstractVector = 1:size(X, 2): Asset names.
compound::Bool = false: If true, compound cumulative returns.
N::Option{<:Number} = nothing: Maximum number of assets to display individually. nothing auto-selects via number_effective_assets. A value in (0, 1] is treated as a cumulative weight threshold; a value > 1 as an asset count.
pr: Prior or returns result; extracts X, ts, and nx automatically.
res::OptimisationResult: Extracts w and fees when available.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_composition — Function

plot_composition(
    w::VecNum,
    nx::AbstractVector = 1:length(w);
    N::Option{<:Number} = nothing,
    kwargs...
) -> Plot
plot_composition(res::OptimisationResult, rd; N, kwargs...) -> Plot
plot_composition(res::OptimisationResult, pr; N, kwargs...) -> Plot
plot_composition(pred::PredictionResult; N, kwargs...) -> Plot
plot_composition(mpred::MultiPeriodPredictionResult; N, kwargs...) -> Plot
plot_composition(ppred::PopulationPredictionResult; N, kwargs...) -> Plot

Plot portfolio composition as a bar chart of asset weights. Assets beyond the top N are collapsed into an "Others" bar.

mpred / ppred overloads produce stacked-bar fold compositions via plot_stacked_bar_composition; N is accepted but not applied in those overloads.

Arguments

w: Portfolio weights vector.
nx::AbstractVector = 1:length(w): Asset names.
N::Option{<:Number} = nothing: Maximum number of assets to display. nothing auto-selects via number_effective_assets. A value in (0, 1] is treated as a cumulative weight threshold; a value > 1 as an asset count.
res::OptimisationResult: Extracts w when available.
rd::ReturnsResult: Extracts nx when available.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_stacked_bar_composition — Function

plot_stacked_bar_composition(
    w::VecNum_VecVecNum,
    nx::AbstractVector = 1:size(w, 1);
    kwargs...
) -> Plot
plot_stacked_bar_composition(res_vec::AbstractVector{<:OptimisationResult}, rd; kwargs...) -> Plot

Plot portfolio composition as a stacked bar chart. Accepts a matrix, a VecVecNum, or a vector of OptimisationResult.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_stacked_area_composition

PortfolioOptimisers.plot_stacked_area_composition — Function

plot_stacked_area_composition(
    w::VecNum_VecVecNum,
    nx::AbstractVector = 1:size(w, 1);
    kwargs...
) -> Plot
plot_stacked_area_composition(res_vec::AbstractVector{<:OptimisationResult}, rd; kwargs...) -> Plot

Plot portfolio composition as a stacked area chart. Accepts a matrix, VecVecNum, or a vector of OptimisationResult.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_stacked_bar_composition

PortfolioOptimisers.plot_risk_contribution — Function

plot_risk_contribution(
    r::BaseRM_VecBaseRM,
    w::VecNum,
    X::MatNum_Pr,
    fees::Option{<:Fees} = nothing;
    nx::AbstractVector = 1:length(w),
    delta::Number = 1e-6,
    marginal::Bool = false,
    percentage::Bool = false,
    N::Option{<:Number} = nothing,
    sca::Scalariser = SumScalariser(),
    kwargs...
) -> Plot
plot_risk_contribution(r, w, rd::ReturnsResult, fees = nothing; delta, marginal, percentage, N, sca, kwargs...) -> Plot
plot_risk_contribution(r, res::OptimisationResult, rd; delta, marginal, percentage, N, sca, kwargs...) -> Plot
plot_risk_contribution(r, res::OptimisationResult, pr; nx, delta, marginal, percentage, N, sca, kwargs...) -> Plot
plot_risk_contribution(r, pred::PredictionResult, fees = nothing; delta, marginal, percentage, N, sca, kwargs...) -> Plot

Plot per-asset risk contribution as a bar chart.

A fold

The fold-taking method reads the fold's target weights and the asset returns its Held Weights record kept, and it settles the fee against the fold's own length exactly as predict settled it. Under a Weight Drift the bars are exact to first order in the drift only, for the reason risk_contribution states.

A fold whose scheme set neither wd nor pws carries no record, so it kept no asset returns and the method raises. Pass the returns the fold was fitted on instead.

Arguments

r: Risk measure, or a vector of them combined by sca.
w: Portfolio weights vector.
X / rd / pr: Asset returns or prior result.
fees::Option{<:Fees} = nothing: Optional transaction fees.
nx::AbstractVector = 1:length(w): Asset names.
delta::Number = 1e-6: Finite-difference step size for risk_contribution. Must be > 0.
marginal::Bool = false: If true, compute marginal risk contribution; otherwise component.
percentage::Bool = false: If true, normalise contributions to percentages.
N::Option{<:Number} = nothing: Maximum number of assets to display.
sca::Scalariser = SumScalariser(): Scalariser combining the measures in r. Inert when r is a single measure. Pass res.sca to report the figure the optimisation ran under.

Multiplicity

The bars decompose one number, the scalarised aggregate, so the per-asset figures sum to the aggregate rather than to any one element. Under MaxScalariser and MinScalariser the decomposition is exact only where the argmax is unique; at a near-exact tie between two scaled measures the subgradient is a set and the bars are one admissible answer among several. See risk_contribution.

Validation

delta > 0.
If N is not nothing, N > 0.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_factor_risk_contribution — Function

plot_factor_risk_contribution(
    r::AbstractBaseRiskMeasure,
    w::VecNum,
    X::MatNum_Pr,
    fees::Option{<:Fees} = nothing;
    re::RegE_Reg = StepwiseRegression(),
    rd::ReturnsResult = ReturnsResult(),
    nf::Option{<:AbstractVector} = nothing,
    delta::Number = 1e-6,
    N::Option{<:Number} = nothing,
    sca::Scalariser = SumScalariser(),
    kwargs...
) -> Plot
plot_factor_risk_contribution(r, res::OptimisationResult, rd; re, delta, N, sca, kwargs...) -> Plot
plot_factor_risk_contribution(r, pred::PredictionResult, fees = nothing; re, delta, N, sca, kwargs...) -> Plot

Plot per-factor risk contribution as a bar chart, including the constant (idiosyncratic) term.

A fold

The fold-taking method is the twin of plot_risk_contribution's, and it builds the rd the loadings are fitted from out of the fold: the asset returns of its Held Weights record beside the factor block the fold carried. The same first-order caveat holds, and a fold that carries no record raises for the same reason.

Arguments

r: Risk measure, or a vector of them combined by sca.
w: Portfolio weights vector.
X / rd: Asset returns or returns result.
fees::Option{<:Fees} = nothing: Optional transaction fees.
re::RegE_Reg = StepwiseRegression(): Factor regression estimator.
rd::ReturnsResult = ReturnsResult(): Returns result providing factor names via rd.nf.
nf::Option{<:AbstractVector} = nothing: Factor names; overrides rd.nf when provided.
delta::Number = 1e-6: Finite-difference step size. Must be > 0.
N::Option{<:Number} = nothing: Maximum number of factors to display.
sca::Scalariser = SumScalariser(): Scalariser combining the measures in r. Inert when r is a single measure. Pass res.sca to report the figure the optimisation ran under.

Validation

delta > 0.
If N is not nothing, N > 0.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_dendrogram — Function

plot_dendrogram(
    clr::AbstractClusteringResult,
    nx::AbstractVector = 1:length(clr.res.order);
    dend_theme::Symbol = :Spectral,
    kwargs...
) -> Plot
plot_dendrogram(cle::HClE_HCl, X::MatNum, nx = 1:size(X,2); dims, kwargs...) -> Plot
plot_dendrogram(cle::HClE_HCl, pr::Pr_RR, nx = 1:size(pr.X,2); dims, kwargs...) -> Plot

Plot a hierarchical clustering dendrogram with coloured cluster regions.

Arguments

clr::AbstractClusteringResult: Precomputed clustering result.
cle::HClE_HCl: Clustering estimator; computes clustering from X or pr.X.
pr: AbstractPriorResult; extracts X and optionally nx.
nx: Asset names.
dend_theme::Symbol = :Spectral: Colour palette for cluster regions.
dims::Integer = 1: Dimension passed to clusterise.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

clusterise

PortfolioOptimisers.plot_clusters — Function

plot_clusters(
    clr::AbstractClusteringResult,
    nx::AbstractVector = 1:size(clr.S, 1);
    dend_theme::Symbol = :Spectral,
    hmap_theme::Symbol = :Spectral,
    color_func = x -> any(x .< 0) ? (-1, 1) : (0, 1),
    line_color = :black,
    line_width = 3,
    kwargs...
) -> Plot
plot_clusters(cle::HClE_HCl, X::MatNum, nx = 1:size(X,2); dims, kwargs...) -> Plot
plot_clusters(cle::HClE_HCl, pr::Pr_RR, nx = 1:size(pr.X,2); dims, kwargs...) -> Plot

Plot a reordered correlation/covariance heatmap with flanking dendrograms and coloured cluster boxes.

Arguments

clr::AbstractClusteringResult: Precomputed clustering result.
cle::HClE_HCl: Clustering estimator.
pr: AbstractPriorResult; extracts X and optionally nx.
nx: Asset names.
dend_theme::Symbol = :Spectral: Colour palette for dendrogram cluster fills.
hmap_theme::Symbol = :Spectral: Colour gradient for the heatmap.
color_func: Function mapping the matrix to a colour range (lo, hi).
line_color = :black: Colour of the cluster-border lines on the heatmap.
line_width = 3: Width of the cluster-border lines.
dims::Integer = 1: Dimension passed to clusterise.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_drawdowns — Function

plot_drawdowns(
    w::ArrNum,
    X::MatNum,
    fees::Option{<:Fees} = nothing;
    slv::Option{<:Slv_VecSlv} = nothing,
    ts::AbstractVector = 1:size(X, 1),
    compound::Bool = false,
    alpha::Number = 0.05,
    kappa::Number = 0.3,
    rw = nothing,
    kwargs...
) -> Plot
plot_drawdowns(w, rd::ReturnsResult, fees = nothing; slv, compound, alpha, kappa, rw, kwargs...) -> Plot
plot_drawdowns(res::OptimisationResult, rd; slv, compound, alpha, kappa, rw, kwargs...) -> Plot
plot_drawdowns(pred; slv, compound, alpha, kappa, rw, kwargs...) -> Plot
plot_drawdowns(mpred::MultiPeriodPredictionResult; slv, compound, alpha, kappa, rw, kwargs...) -> Plot
plot_drawdowns(ppred::PopulationPredictionResult; slv, compound, alpha, kappa, rw, kwargs...) -> Plot

Plot portfolio drawdown over time. Marks AverageDrawdown, UlcerIndex, DaR, CDaR and MaximumDrawdown with horizontal lines, plus EDaR and RLDaR when slv is provided.

A gapped panel reaches this figure only through the returns the caller hands it. A prediction arity is finite already, because the fold zeroed the Held Gap once in predict. A w, X or w, rd arity computes on the matrix the caller holds and checks nothing: X * w is NaN at a gap even where the weight is zero. Score a gapped panel through predict(res, rd) and plot the prediction.

Arguments

w: Portfolio weights.
X: Asset returns matrix (observations × assets).
fees::Option{<:Fees} = nothing: Optional transaction fees.
slv::Option{<:Slv_VecSlv} = nothing: Solver for EDaR / RLDaR lines (omitted when nothing).
ts::AbstractVector = 1:size(X, 1): Time axis labels.
compound::Bool = false: If true, use compound drawdowns.
alpha::Number = 0.05: Confidence level for DaR / CDaR / EDaR / RLDaR lines. Must satisfy 0 < alpha < 1.
kappa::Number = 0.3: Relativistic deformation parameter for RLDaR. Must satisfy 0 < kappa < 1.
rw: Optional observation weights for AverageDrawdown and UlcerIndex.

Validation

0 < alpha < 1.
0 < kappa < 1.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

drawdowns

PortfolioOptimisers.plot_measures — Function

plot_measures(
    w::VecNum_VecVecNum,
    pr::Pr_RR,
    fees::Option{<:Fees} = nothing;
    x::BaseRM_VecBaseRM = Variance(),
    y::BaseRM_VecBaseRM = ExpectedReturn(),
    z::Option{<:BaseRM_VecBaseRM} = nothing,
    c::BaseRM_VecBaseRM = ExpectedReturnRiskRatio(; rk=x, rt=ArithmeticReturn(), rf=0),
    slv::Option{<:Slv_VecSlv} = nothing,
    factory::Bool = true,
    kwargs...
) -> Plot
plot_measures(res_vec::AbstractVector{<:OptimisationResult}, pr = nothing; x, y, z, c, slv, fees, factory, kwargs...) -> Plot
plot_measures(ppred::PopulationPredictionResult; x, y, z, c, slv, factory, kwargs...) -> Plot

Scatter plot of risk/return measures across a collection of portfolio weight vectors.

Each axis is one expected_risk call, and that verb reduces to the Investable Mask at its own entry against a Prior Result, at the value-level door. So a gapped prior is handled one level below this figure, and no check is added here. A prediction arity is finite already, because the fold zeroed the Held Gap once in predict.

Arguments

w: Portfolio weights or vector of weight vectors.
pr: Prior or returns result.
x: Risk/return measure, or a vector of them, for the horizontal axis (default Variance()).
y: Risk/return measure, or a vector of them, for the vertical axis (default ExpectedReturn()).
z: Optional third measure, or vector of them, for 3-D scatter.
c: Colour-coding measure, or a vector of them (default Sharpe ratio derived from x).
slv::Option{<:Slv_VecSlv} = nothing: Solver passed to factory.
factory::Bool = true: If true, call factory on measures before evaluating.

Multiplicity

Each axis takes one measure or a vector of them, and a vector is collapsed to the single number the axis plots. There is no sca keyword here: an axis is evaluated by expected_risk with no scalariser named, so a bare vector on an axis takes SumScalariser, each element weighted by its own settings.scale.

A scalariser reaches an axis only through a wrapper's sca field — ExpectedReturnRiskRatio, MeanReturnRiskRatio or NonOptimisationRiskRatio — because a wrapper's field beats any keyword. The four axes are independent, so they may name different scalarisers. Per-axis x_sca, y_sca, … keywords were deliberately refused.

Note

This is a documented limitation, not an oversight: those wrappers are all ratios, so the plotting surface cannot express a MaxScalariser over a plain vector of risks. Scalarise it yourself with expected_risk and plot the numbers if you need that.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_histogram — Function

plot_histogram(
    w::ArrNum,
    X::MatNum,
    fees::Option{<:Fees} = nothing;
    slv::Option{<:Slv_VecSlv} = nothing,
    alpha::Number = 0.05,
    kappa::Number = 0.3,
    rw = nothing,
    points::Integer = 0,
    reference::Bool = true,
    kwargs...
) -> Plot
plot_histogram(w, rd::ReturnsResult, fees = nothing; slv, alpha, kappa, rw, points, reference, kwargs...) -> Plot
plot_histogram(res::OptimisationResult, rd; slv, alpha, kappa, rw, points, reference, kwargs...) -> Plot
plot_histogram(pred; slv, alpha, kappa, rw, points, reference, kwargs...) -> Plot
plot_histogram(mpred::MultiPeriodPredictionResult; slv, alpha, kappa, rw, points, reference, kwargs...) -> Plot
plot_histogram(ppred::PopulationPredictionResult; slv, alpha, kappa, rw, points, reference, kwargs...) -> Plot

Plot a histogram of portfolio returns with vertical risk-measure lines and an optional fitted Normal distribution.

A gapped panel reaches this figure only through the returns the caller hands it. A prediction arity is finite already, because the fold zeroed the Held Gap once in predict. A w, X or w, rd arity computes on the matrix the caller holds and checks nothing: X * w is NaN at a gap even where the weight is zero. Score a gapped panel through predict(res, rd) and plot the prediction.

Arguments

w: Portfolio weights.
X: Asset returns matrix (observations × assets).
fees::Option{<:Fees} = nothing: Optional transaction fees.
slv::Option{<:Slv_VecSlv} = nothing: Solver for EVaR / RLVaR lines (omitted when nothing).
alpha::Number = 0.05: Tail confidence level. Must satisfy 0 < alpha < 1.
kappa::Number = 0.3: Relativistic deformation parameter for RLVaR. Must satisfy 0 < kappa < 1.
rw: Optional observation weights for MAD, GMD, VaR, and CVaR.
points::Integer = 0: Number of PDF evaluation points. 0 auto-detects as ceil(Int, 4√T).
reference::Bool = true: If true, overlay a fitted Normal distribution curve.

Validation

0 < alpha < 1.
0 < kappa < 1.
points >= 0.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

PortfolioOptimisers.plot_network — Function

plot_network(
    pl::NwE_ClE_Cl,
    X::MatNum,
    nx::AbstractVector = 1:size(X, 2),
    w::Option{<:VecNum} = nothing;
    threshold::Number = 0,
    kwargs...
) -> Plot
plot_network(pl, pr::Pr_RR, w = nothing; nx, kwargs...) -> Plot
plot_network(pl, res::OptimisationResult; rd, nx, kwargs...) -> Plot

Plot the asset network (MST, PMFG, TMFG, or adjacency) as a graph using GraphRecipes.graphplot. Node size is uniform by default; pass w to scale node area proportionally to portfolio weight.

A non-investable asset is not drawn. The figure fits a phylogeny matrix on pr.X, and a plain moment estimator refuses a gapped sample, so the prior arity reduces itself, its names and its weights to the Investable Mask at its entry through investable_plot_view. The graph is the investable universe, and no edge of a dead asset is drawn. The bare X and ReturnsResult arities carry no moments, so no mask exists to derive and they compute on the matrix the caller holds.

Arguments

pl: Network or clustering estimator.
X: Asset returns matrix (observations × assets).
nx: Asset names.
w::Option{<:VecNum} = nothing: Optional portfolio weights for node sizing.
threshold::Number = 0: Adjacency entries with absolute value ≤ this are zeroed.
pr: Prior or returns result; extracts X and optionally nx.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots and GraphRecipes).

Related

phylogeny_matrix

PortfolioOptimisers.plot_centrality — Function

plot_centrality(
    cte::AbstractCentralityEstimator,
    X::MatNum,
    nx::AbstractVector = 1:size(X, 2);
    N::Option{<:Number} = nothing,
    percentage::Bool = false,
    kwargs...
) -> Plot
plot_centrality(cte, pr::AbstractPriorResult, nx = 1:size(pr.X,2); N, percentage, kwargs...) -> Plot
plot_centrality(cte, rd::ReturnsResult; N, percentage, kwargs...) -> Plot
plot_centrality(cte, res::OptimisationResult, rd; N, percentage, kwargs...) -> Plot

Bar chart of asset centrality scores, sorted in descending order.

A non-investable asset is not drawn. The figure fits a centrality vector on pr.X, and a plain moment estimator refuses a gapped sample, so the prior arity reduces to the Investable Mask at its entry through investable_plot_view. The axis is the investable universe. The bare X and ReturnsResult arities carry no moments, so no mask exists to derive and they compute on the matrix the caller holds.

Arguments

cte: Centrality estimator.
X: Asset returns matrix (observations × assets).
nx: Asset names.
N::Option{<:Number} = nothing: Maximum number of assets to display. nothing auto-selects via number_effective_assets. A value in (0, 1] is treated as a cumulative score threshold; a value > 1 as an asset count.
percentage::Bool = false: If true, normalise scores to sum to one.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

centrality_vector

PortfolioOptimisers.plot_correlation — Function

plot_correlation(X::MatNum, nx::AbstractVector = 1:size(X, 1); kwargs...) -> Plot
plot_correlation(pr::AbstractPriorResult, nx = 1:size(pr.sigma,1); kwargs...) -> Plot
plot_correlation(pr::AbstractPriorResult, rd::ReturnsResult; kwargs...) -> Plot
plot_correlation(res::OptimisationResult[, rd]; kwargs...) -> Plot
plot_correlation(pred::PredictionResult[, rd]; kwargs...) -> Plot

Standalone correlation (or covariance) heatmap without clustering or dendrograms. If the input contains a covariance matrix, it is normalised to a correlation matrix before plotting.

A non-investable asset is drawn rather than removed. It carries NaN down its row and its column of sigma, so those cells are blank, and the blank is the record of the gap. The colour limits of a correlation are fixed at (-1, 1), so one gap does not flatten the scale.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_clusters

PortfolioOptimisers.plot_mu — Function

plot_mu(
    mu::VecNum,
    nx::AbstractVector = 1:length(mu);
    N::Option{<:Number} = nothing,
    kwargs...
) -> Plot
plot_mu(pr::AbstractPriorResult[, nx]; N, kwargs...) -> Plot
plot_mu(pr::AbstractPriorResult, rd::ReturnsResult; N, kwargs...) -> Plot
plot_mu(res::OptimisationResult[, rd]; N, kwargs...) -> Plot
plot_mu(pred::PredictionResult[, rd]; N, kwargs...) -> Plot

Bar chart of per-asset expected returns (μ vector).

A non-investable asset is drawn rather than removed. It carries NaN in the prior's moments, so its bar is blank, and that blank is the record of the gap. The ranking reads finite_magnitudes, so the blank never takes the top slot from a live asset, and the frame is unchanged when the count does not truncate.

Arguments

mu: Expected returns vector.
nx: Asset names.
N::Option{<:Number} = nothing: Maximum number of assets to display. nothing auto-selects via number_effective_assets. A value in (0, 1] is treated as a cumulative return threshold; a value > 1 as an asset count.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_sigma

PortfolioOptimisers.plot_sigma — Function

plot_sigma(
    sigma::MatNum,
    nx::AbstractVector = 1:size(sigma, 1);
    variance::Bool = false,
    N::Option{<:Number} = nothing,
    kwargs...
) -> Plot
plot_sigma(pr::AbstractPriorResult[, nx]; variance, N, kwargs...) -> Plot
plot_sigma(pr::AbstractPriorResult, rd::ReturnsResult; variance, N, kwargs...) -> Plot
plot_sigma(res::OptimisationResult[, rd]; variance, N, kwargs...) -> Plot
plot_sigma(pred::PredictionResult[, rd]; variance, N, kwargs...) -> Plot

Bar chart of per-asset volatility (√diag(Σ)).

A non-investable asset is drawn rather than removed. It carries NaN on the diagonal of sigma, so its bar is blank, and that blank is the record of the gap. The ranking reads finite_magnitudes, so the blank never takes the top slot from a live asset, and the frame is unchanged when the count does not truncate.

Arguments

sigma: Covariance (or correlation) matrix.
nx: Asset names.
variance::Bool = false: If true, show variance (diag(Σ)) instead of standard deviation.
N::Option{<:Number} = nothing: Maximum number of assets to display. nothing auto-selects the top assets by volatility magnitude. A value > 1 is treated as an asset count.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_mu
plot_correlation

PortfolioOptimisers.plot_factor_loadings — Function

plot_factor_loadings(
    M::MatNum,
    nx::AbstractVector = 1:size(M, 1),
    nf::AbstractVector = 1:size(M, 2);
    kwargs...
) -> Plot
plot_factor_loadings(pr::AbstractPriorResult[, nx, nf]; kwargs...) -> Plot
plot_factor_loadings(pr::AbstractPriorResult, rd::ReturnsResult; kwargs...) -> Plot
plot_factor_loadings(res::OptimisationResult[, rd]; kwargs...) -> Plot
plot_factor_loadings(pred::PredictionResult[, rd]; kwargs...) -> Plot

Heatmap of the factor loadings matrix B (assets × factors) from a prior with a regression model. Uses a diverging colour scale centred at zero.

A non-investable asset is drawn rather than removed. It carries NaN down its row of the loadings, so that row is blank cells, and the blank is the record of the gap. The colour limits are finite_symmetric_clim, so one gap does not flatten the scale. The factor axis is unaffected: the gap is on the asset axis alone.

Requires that the prior carries a factor block, checked by assert_prior_regression: pr.rr must not be nothing. The matrix arity takes M directly and needs no prior.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_factor_sigma — Function

plot_factor_sigma(
    f_sigma::MatNum,
    nf::AbstractVector = 1:size(f_sigma, 1);
    kwargs...
) -> Plot
plot_factor_sigma(pr::AbstractPriorResult[, nf]; kwargs...) -> Plot
plot_factor_sigma(pr::AbstractPriorResult, rd::ReturnsResult; kwargs...) -> Plot
plot_factor_sigma(res::OptimisationResult[, rd]; kwargs...) -> Plot
plot_factor_sigma(pred::PredictionResult[, rd]; kwargs...) -> Plot

Correlation/covariance heatmap of the factor covariance matrix (pr.fpr.sigma). Behaves identically to plot_correlation but operates on the factor space.

The figure draws the factor axis, and a non-investable asset is on the asset axis, so a gap never reaches it. It needs neither a blank nor a reduction.

Requires that the prior carries a factor block, checked by assert_prior_regression: fpr travels with rr, so the check is on rr and establishes the whole block. The matrix arity takes f_sigma directly and needs no prior.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_eigenspectrum — Function

plot_eigenspectrum(
    sigma::MatNum;
    N_obs::Option{<:Integer} = nothing,
    reference::Bool = true,
    kwargs...
) -> Plot
plot_eigenspectrum(pr::AbstractPriorResult; reference, kwargs...) -> Plot
plot_eigenspectrum(pr::AbstractPriorResult, rd::ReturnsResult; reference, kwargs...) -> Plot
plot_eigenspectrum(res::OptimisationResult[, rd]; reference, kwargs...) -> Plot
plot_eigenspectrum(pred::PredictionResult[, rd]; reference, kwargs...) -> Plot

Bar chart of eigenvalues of the covariance/correlation matrix, sorted in descending order.

A non-investable asset is not drawn. eigvals(Symmetric(sigma)) refuses a NaN, so the prior arity reduces to the Investable Mask at its entry through investable_plot_view, and the spectrum is the spectrum of the investable block. The bare sigma arity computes on the matrix the caller holds, and a gap in it raises rather than reduces.

Arguments

sigma: Covariance or correlation matrix.
N_obs::Option{<:Integer} = nothing: Number of observations; enables Marchenko-Pastur overlay.
reference::Bool = true: If true and N_obs is provided, overlays the Marchenko-Pastur bulk upper bound λ₊ = σ̄²(1 + √(N/T))² as a reference line.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_correlation

PortfolioOptimisers.plot_rolling_measure — Function

plot_rolling_measure(
    r::BaseRM_VecBaseRM,
    w::VecNum,
    X::MatNum,
    fees::Option{<:Fees} = nothing;
    ts::AbstractVector = 1:size(X, 1),
    rolling::Integer = 0,
    sca::Scalariser = SumScalariser(),
    kwargs...
) -> Plot
plot_rolling_measure(r, w, rd::ReturnsResult, fees = nothing; rolling, sca, kwargs...) -> Plot
plot_rolling_measure(r, res::OptimisationResult, rd; rolling, sca, kwargs...) -> Plot
plot_rolling_measure(r, pred; rolling, sca, kwargs...) -> Plot
plot_rolling_measure(r, mpred::MultiPeriodPredictionResult; rolling, sca, kwargs...) -> Plot
plot_rolling_measure(r, ppred::PopulationPredictionResult; rolling, sca, kwargs...) -> Plot

Line plot of a risk or return measure evaluated over a rolling window of portfolio returns.

A gapped panel reaches this figure only through the returns the caller hands it. A prediction arity is finite already, because the fold zeroed the Held Gap once in predict. A w, X or w, rd arity computes on the matrix the caller holds and checks nothing: X * w is NaN at a gap even where the weight is zero. Score a gapped panel through predict(res, rd) and plot the prediction.

Arguments

r: Risk or return measure, or a vector of them combined by sca. May embed its own solver (e.g. EntropicValueatRisk(; slv=...)).
w: Portfolio weights.
X: Asset returns matrix (observations × assets).
fees::Option{<:Fees} = nothing: Optional transaction fees.
ts::AbstractVector = 1:size(X, 1): Time axis labels.
rolling::Integer = 0: Rolling window size. 0 auto-detects as ⌈√T⌉. Must be >= 0, and no longer than the return series.
sca::Scalariser = SumScalariser(): Scalariser combining the measures in r. Inert when r is a single measure.

Multiplicity

Each window plots one number, the scalarised aggregate. A vector does not become several lines.

The windows come from rolling_window_measure on the return series, rather than from a second copy of the rolling loop inside the extension. That verb scores each window through expected_risk_from_returns rather than as a functor: a vector is not callable, and defining a call method on AbstractVector would be piracy. Both arities take the same route, so the singular figure is unchanged.

Validation

rolling >= 0.
rolling no longer than the return series, else the DomainError rolling_window_measure raises on its own window. A longer rolling used to give an empty vector of risks and an empty plot.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_weight_stability — Function

plot_weight_stability(
    mpred::MultiPeriodPredictionResult;
    N::Option{<:Number} = nothing,
    kwargs...
) -> Plot
plot_weight_stability(ppred::PopulationPredictionResult; N, kwargs...) -> Plot

Box plot of per-asset weight distributions across cross-validation folds or population members.

Arguments

mpred::MultiPeriodPredictionResult: Walk-forward prediction result.
ppred::PopulationPredictionResult: Population prediction result; pools weights from all members.
N::Option{<:Number} = nothing: Maximum number of assets to display by mean absolute weight. nothing shows all assets. A value > 1 is treated as an asset count.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_cv_scores — Function

plot_cv_scores(
    scores::AbstractVector{<:Number},
    labels::AbstractVector = 1:length(scores);
    kwargs...
) -> Plot
plot_cv_scores(r::BaseRM_VecBaseRM, mpred::MultiPeriodPredictionResult; kwargs...) -> Plot
plot_cv_scores(r::BaseRM_VecBaseRM, ppred::PopulationPredictionResult; kwargs...) -> Plot

Bar chart of cross-validation scores (one bar per fold or population member).

Arguments

r: Risk or return measure, or a vector of them.

Each bar is one number, the scalarised aggregate for that fold or member. A vector does not become several bar series.

A sca keyword is not declared here; it rides kwargs... into expected_risk, so plot_cv_scores(r, mpred; sca = MaxScalariser()) works and a vector defaults to SumScalariser.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_turnover — Function

plot_turnover(
    w_series::AbstractVector{<:VecNum};
    ts::AbstractVector = 1:length(w_series),
    kwargs...
) -> Plot
plot_turnover(mpred::MultiPeriodPredictionResult; kwargs...) -> Plot

Line plot of portfolio turnover (L1 weight change) over time.

Turnover at step t is defined as ∑ |w_t − w_{t−1}|, and calc_turnover is what computes it. The first step has no predecessor, so the verb answers a NaN there and the plot drops it.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_prior — Function

plot_prior(
    pr::AbstractPriorResult,
    nx::AbstractVector = 1:length(pr.mu);
    N::Option{<:Number} = nothing,
    kwargs...
) -> Plot
plot_prior(pr::AbstractPriorResult, rd::ReturnsResult; N, kwargs...) -> Plot
plot_prior(res::OptimisationResult[, rd]; N, kwargs...) -> Plot
plot_prior(pred::PredictionResult[, rd]; N, kwargs...) -> Plot

Three-panel composite plot summarising a prior result:

Expected returns bar chart (plot_mu).
Asset volatility bar chart (plot_sigma).
Correlation heatmap (plot_correlation).

Every panel draws, so a non-investable asset is drawn rather than removed, and the three panels agree on the frame. Each panel's own docstring states what its blank means.

Arguments

pr::AbstractPriorResult: Prior result containing mu and sigma.
nx: Asset names.
N::Option{<:Number} = nothing: Forwarded to plot_mu and plot_sigma to limit displayed assets.
rd::ReturnsResult: Provides asset names via rd.nx when given.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_mu
plot_sigma
plot_correlation
LowOrderPrior

PortfolioOptimisers.plot_factor_mu — Function

plot_factor_mu(
    f_mu::VecNum,
    nf::AbstractVector = 1:length(f_mu);
    N::Option{<:Number} = nothing,
    kwargs...
) -> Plot
plot_factor_mu(pr::AbstractPriorResult[, nf]; N, kwargs...) -> Plot
plot_factor_mu(pr::AbstractPriorResult, rd::ReturnsResult; N, kwargs...) -> Plot
plot_factor_mu(res::OptimisationResult[, rd]; N, kwargs...) -> Plot
plot_factor_mu(pred::PredictionResult[, rd]; N, kwargs...) -> Plot

Bar chart of per-factor expected returns (pr.fpr.mu, from a factor model prior).

The figure draws the factor axis, and a non-investable asset is on the asset axis, so a gap never reaches it. It needs neither a blank nor a reduction.

Requires that the prior carries a factor block, checked by assert_prior_regression: fpr travels with rr, so the check is on rr and establishes the whole block. The vector arity takes f_mu directly and needs no prior.

Arguments

f_mu: Factor expected returns vector.
nf: Factor names.
N::Option{<:Number} = nothing: Maximum number of factors to display. nothing auto-selects via number_effective_assets.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_benchmark — Function

plot_benchmark(
    w::ArrNum,
    X::MatNum,
    B::VecNum_VecVecNum,
    fees::Option{<:Fees} = nothing;
    ts::AbstractVector = 1:size(X, 1),
    nb::Option{<:AbstractVector} = nothing,
    compound::Bool = false,
    kwargs...
) -> Plot
plot_benchmark(w, rd::ReturnsResult, fees = nothing; compound, kwargs...) -> Plot
plot_benchmark(res::OptimisationResult, rd; compound, kwargs...) -> Plot
plot_benchmark(pred::PredictionResult; compound, kwargs...) -> Plot
plot_benchmark(mpred::MultiPeriodPredictionResult; compound, kwargs...) -> Plot

Overlay portfolio cumulative returns against one or more benchmark return series from rd.B.

Arguments

w: Portfolio weights.
X: Asset returns matrix (observations × assets).
B: Benchmark return series or vector of series.
fees::Option{<:Fees} = nothing: Optional transaction fees.
ts::AbstractVector = 1:size(X, 1): Time axis labels.
nb::Option{<:AbstractVector} = nothing: Benchmark names.
compound::Bool = false: If true, compound cumulative returns for both portfolio and benchmarks.
rd::ReturnsResult: Provides B, ts, and nb; throws ArgumentError if rd.B is nothing.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_portfolio_cumulative_returns
ReturnsResult

PortfolioOptimisers.plot_coskewness — Function

plot_coskewness(
    sk::MatNum,
    nx::AbstractVector = 1:size(sk, 1);
    kwargs...
) -> Plot
plot_coskewness(pr::HighOrderPrior[, nx]; kwargs...) -> Plot
plot_coskewness(pr::HighOrderPrior, rd::ReturnsResult; kwargs...) -> Plot
plot_coskewness(res::OptimisationResult[, rd]; kwargs...) -> Plot
plot_coskewness(pred::PredictionResult[, rd]; kwargs...) -> Plot

Heatmap of the coskewness matrix (N × N²) from a HighOrderPrior. Uses a diverging colour scale centred at zero.

A non-investable asset is drawn rather than removed. It carries NaN down its row and every column of a pair it belongs to, so those cells are blank, and the blank is the record of the gap. The colour limits are finite_symmetric_clim, so one gap does not flatten the scale.

Requires that pr.sk is not nothing (i.e. the prior was estimated with higher moments).

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_cokurtosis — Function

plot_cokurtosis(
    kt::MatNum,
    nx::AbstractVector = 1:isqrt(size(kt, 1));
    heatmap::Bool = false,
    reference::Bool = true,
    kwargs...
) -> Plot
plot_cokurtosis(pr::HighOrderPrior[, nx]; heatmap, reference, kwargs...) -> Plot
plot_cokurtosis(pr::HighOrderPrior, rd::ReturnsResult; heatmap, reference, kwargs...) -> Plot
plot_cokurtosis(res::OptimisationResult[, rd]; heatmap, reference, kwargs...) -> Plot
plot_cokurtosis(pred::PredictionResult[, rd]; heatmap, reference, kwargs...) -> Plot

Eigenvalue spectrum of the cokurtosis matrix (N² × N²) from a HighOrderPrior.

The two arities of the figure take opposite sides of the same rule, because one draws and the other computes. Under heatmap = true the figure draws: a non-investable asset keeps its rows and its columns, they are blank cells, and the colour limits are finite_symmetric_clim so one gap does not flatten the scale. Under the default the figure computes: eigvals(Symmetric(kt)) refuses a NaN, so the prior arity reduces to the Investable Mask at its entry through investable_plot_view, and the spectrum is that of the investable block, which is Nᵢ² long rather than N². The bare kt arity computes on the matrix the caller holds, and a gap in it raises rather than reduces.

Arguments

kt: Cokurtosis matrix (N² × N²).
nx: Asset names.
heatmap::Bool = false: If true, show the raw heatmap instead (only recommended for small N).
reference::Bool = true: If true, overlays the mean eigenvalue as a reference line.

Requires that pr.kt is not nothing.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_portfolio_dashboard — Function

plot_portfolio_dashboard(
    res::OptimisationResult,
    rd::Pr_RR;
    ts = 1:size(rd.X, 1),
    nx = 1:size(rd.X, 2),
    r::AbstractBaseRiskMeasure = Variance(),
    slv::Option{<:Slv_VecSlv} = nothing,
    compound::Bool = false,
    N::Option{<:Number} = nothing,
    delta::Number = 1e-6,
    marginal::Bool = false,
    percentage::Bool = false,
    alpha::Number = 0.05,
    kappa::Number = 0.3,
    rw = nothing,
    kwargs...
) -> Plot

Four-panel composite plot for a single optimisation result:

Portfolio composition (plot_composition).
Cumulative returns (plot_portfolio_cumulative_returns).
Asset risk contribution (plot_risk_contribution).
Drawdowns (plot_drawdowns).

r selects the risk measure for panels 3 and 4 (default Variance()).

Note: panel 3 requires raw asset returns. Pass rd::ReturnsResult (original returns), not a PredictionResult, for the risk contribution panel.

Each panel takes its own side of the draw/compute rule, and this figure adds no rule of its own. Panel 1 draws a weight, which is zero at a non-investable asset. Panel 3 goes through risk_contribution, which reduces to the Investable Mask at its own entry against a Prior Result and expands the per-asset answer. Panels 2 and 4 compute on the returns the caller hands them, so a gapped panel is scored through predict(res, rd) first.

Arguments

res::OptimisationResult: Optimisation result.
rd::Pr_RR: Returns result or prior; extracts nx and ts from rd when ReturnsResult.
r: Risk measure for panels 3 and 4, or a vector of them combined by sca.
sca::Scalariser = SumScalariser(): Scalariser combining the measures in r, forwarded to panel 3. Inert when r is a single measure. Pass res.sca to match the optimisation.
slv: Solver for EDaR / RLDaR drawdown lines.
compound::Bool = false: If true, compound cumulative returns and drawdowns.
N::Option{<:Number} = nothing: Forwarded to composition and risk contribution panels.
delta::Number = 1e-6: Finite-difference step for risk contribution. Must be > 0.
marginal::Bool = false: Marginal vs component risk contribution.
percentage::Bool = false: Normalise risk contributions to percentages.
alpha::Number = 0.05: Confidence level for drawdown risk lines.
kappa::Number = 0.3: Relativistic parameter for RLDaR.
rw: Observation weights for drawdown risk measures.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_composition
plot_portfolio_cumulative_returns
plot_risk_contribution
plot_drawdowns

PortfolioOptimisers.plot_cv_dashboard — Function

plot_cv_dashboard(
    mpred::MultiPeriodPredictionResult;
    N::Option{<:Number} = nothing,
    compound::Bool = false,
    kwargs...
) -> Plot

Four-panel composite plot for a walk-forward cross-validation result:

Stacked-bar fold compositions (plot_composition).
Fold-shaded cumulative returns (plot_portfolio_cumulative_returns).
Turnover per fold (plot_turnover).
Weight stability box plot (plot_weight_stability).

Every panel reads a walk-forward prediction, whose fold zeroed its Held Gaps once in predict and whose weights are full length at every fold. So the four panels share one frame across folds, and this figure adds no rule of its own.

Arguments

mpred::MultiPeriodPredictionResult: Walk-forward prediction result.
N::Option{<:Number} = nothing: Forwarded to plot_weight_stability.
compound::Bool = false: Forwarded to plot_portfolio_cumulative_returns.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_efficient_frontier — Function

plot_efficient_frontier(
    res_vec::AbstractVector{<:OptimisationResult},
    pr::Pr_RR;
    x::BaseRM_VecBaseRM = Variance(),
    y::BaseRM_VecBaseRM = ExpectedReturn(),
    c::BaseRM_VecBaseRM = ExpectedReturnRiskRatio(; rk=x, rt=ArithmeticReturn(), rf=0),
    slv::Option{<:Slv_VecSlv} = nothing,
    fees::Option{<:Fees} = nothing,
    min_risk::Bool = true,
    max_score::Bool = true,
    factory::Bool = true,
    kwargs...
) -> Plot
plot_efficient_frontier(res_vec, rd::ReturnsResult; kwargs...) -> Plot
plot_efficient_frontier(w::VecVecNum, pr::Pr_RR; x, y, c, slv, fees, min_risk, max_score, factory, kwargs...) -> Plot
plot_efficient_frontier(res::OptimisationResult, pr::Pr_RR; fees, kwargs...) -> Plot
plot_efficient_frontier(res::OptimisationResult, rd::ReturnsResult; kwargs...) -> Plot

Sort a collection of portfolio results by risk (x), connect them with a line to trace the efficient frontier, and optionally annotate the minimum-risk and maximum-score portfolios.

Arguments

res_vec / w: Portfolio results or weight vectors.
pr / rd: Prior or returns result for risk evaluation.
x: Risk measure, or a vector of them, for the horizontal axis (default Variance()).
y: Return measure, or a vector of them, for the vertical axis (default ExpectedReturn()).
c: Colour-coding measure, or a vector of them (default Sharpe ratio derived from x).
slv::Option{<:Slv_VecSlv} = nothing: Solver passed to factory.
fees::Option{<:Fees} = nothing: Optional transaction fees.
min_risk::Bool = true: Overlay a star marker at the minimum-risk portfolio.
max_score::Bool = true: Overlay a star marker at the portfolio that maximises c.
factory::Bool = true: If true, call factory on measures before evaluating.

Multiplicity

Each axis takes one measure or a vector of them, collapsed to the single number the axis plots. As in plot_measures there is no sca keyword, so a bare vector on an axis takes SumScalariser, each element weighted by its own settings.scale. A scalariser reaches an axis only through a wrapper's own sca field, and the same documented limitation applies: those wrappers are ratios, so a MaxScalariser over a plain vector of risks cannot be expressed here.

The sort that orders the frontier, and the min_risk and max_score markers, all read the scalarised figure, so a vector x orders the frontier by the aggregate rather than by any one measure. The axis label lists the element measures joined by +, whichever scalariser produced the number.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_performance_summary — Function

plot_performance_summary(ps::PerformanceSummaryResult; kwargs...) -> Plot
plot_performance_summary(
    w::ArrNum,
    X::MatNum,
    fees::Option{<:Fees} = nothing;
    periods_per_year::Number = 252,
    alpha::Number = 0.05,
    compound::Bool = false,
    kwargs...
) -> Plot
plot_performance_summary(ret::VecNum; periods_per_year, alpha, compound, kwargs...) -> Plot
plot_performance_summary(w, rd::ReturnsResult, fees = nothing; alpha, compound, kwargs...) -> Plot
plot_performance_summary(res::OptimisationResult, rd; alpha, compound, kwargs...) -> Plot
plot_performance_summary(pred; alpha, compound, kwargs...) -> Plot
plot_performance_summary(mpred::MultiPeriodPredictionResult; alpha, compound, kwargs...) -> Plot

Bar chart of annualised portfolio performance metrics: annualised return, annualised volatility, Sharpe ratio, Sortino ratio, Calmar ratio, maximum drawdown %, and CVaR %.

Every method other than the first computes a PerformanceSummaryResult with performance_summary and renders it. The statistics are defined and validated there, not here, so a caller who wants the numbers rather than the bars can call performance_summary directly and needs no plotting package.

A gapped panel reaches this figure only through the returns the caller hands it. A prediction arity is finite already, because the fold zeroed the Held Gap once in predict. A w, X or w, rd arity computes on the matrix the caller holds and checks nothing: X * w is NaN at a gap even where the weight is zero. Score a gapped panel through predict(res, rd) and plot the prediction.

Arguments

ps: A PerformanceSummaryResult to render.
ret: Periodic portfolio returns vector.
w: Portfolio weights.
X: Asset returns matrix (observations × assets).
fees::Option{<:Fees} = nothing: Optional transaction fees.
periods_per_year::Number = 252: Trading periods per year used for annualisation.
alpha::Number = 0.05: Tail probability for CVaR. Must satisfy 0 < alpha < 1.
compound::Bool = false: If true, use compound cumulative returns for max drawdown.

Validation

Delegated to performance_summary.

0 < alpha < 1.
periods_per_year > 0.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_rolling_drawdowns — Function

plot_rolling_drawdowns(
    w::ArrNum,
    X::MatNum,
    fees::Option{<:Fees} = nothing;
    ts::AbstractVector = 1:size(X, 1),
    rolling::Integer = 0,
    compound::Bool = false,
    kwargs...
) -> Plot
plot_rolling_drawdowns(w, rd::ReturnsResult, fees = nothing; rolling, compound, kwargs...) -> Plot
plot_rolling_drawdowns(res::OptimisationResult, rd; rolling, compound, kwargs...) -> Plot
plot_rolling_drawdowns(pred; rolling, compound, kwargs...) -> Plot
plot_rolling_drawdowns(mpred::MultiPeriodPredictionResult; rolling, compound, kwargs...) -> Plot

Line plot of the rolling maximum drawdown over a sliding window.

A gapped panel reaches this figure only through the returns the caller hands it. A prediction arity is finite already, because the fold zeroed the Held Gap once in predict. A w, X or w, rd arity computes on the matrix the caller holds and checks nothing: X * w is NaN at a gap even where the weight is zero. Score a gapped panel through predict(res, rd) and plot the prediction.

Arguments

w: Portfolio weights.
X: Asset returns matrix (observations × assets).
fees::Option{<:Fees} = nothing: Optional transaction fees.
ts::AbstractVector = 1:size(X, 1): Time axis labels.
rolling::Integer = 0: Window size. 0 auto-detects as ⌈√T⌉. Must be >= 0.
compound::Bool = false: If true, use compound drawdowns.

Validation

rolling >= 0.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

drawdowns
plot_drawdowns
plot_rolling_measure

PortfolioOptimisers.plot_cs_regression_r2 — Function

plot_cs_regression_r2(csfm::CrossSectionalFactorModel; kwargs...) -> Plot
plot_cs_regression_r2(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the weighted cross-sectional coefficient of determination of every observation.

The figure draws what cs_regression_r2 returns and computes nothing of its own. A prior result is forwarded through its rr field, which is the block the fit produced.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_cs_regression_adjusted_r2 — Function

plot_cs_regression_adjusted_r2(csfm::CrossSectionalFactorModel; kwargs...) -> Plot
plot_cs_regression_adjusted_r2(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the adjusted cross-sectional coefficient of determination of every observation.

The figure draws what cs_regression_adjusted_r2 returns and computes nothing of its own. A prior result is forwarded through its rr field, which is the block the fit produced.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_cs_regression_aic — Function

plot_cs_regression_aic(csfm::CrossSectionalFactorModel; kwargs...) -> Plot
plot_cs_regression_aic(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the Akaike information criterion of every cross-sectional fit.

The figure draws what cs_regression_aic returns and computes nothing of its own. A prior result is forwarded through its rr field, which is the block the fit produced.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_cs_regression_bic — Function

plot_cs_regression_bic(csfm::CrossSectionalFactorModel; kwargs...) -> Plot
plot_cs_regression_bic(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the Bayesian information criterion of every cross-sectional fit.

The figure draws what cs_regression_bic returns and computes nothing of its own. A prior result is forwarded through its rr field, which is the block the fit produced.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_cs_regression_t_stats — Function

plot_cs_regression_t_stats(
    csfm::CrossSectionalFactorModel;
    nf::Option{<:AbstractVector} = nothing,
    kwargs...
) -> Plot
plot_cs_regression_t_stats(
    pr::AbstractPriorResult;
    nf::Option{<:AbstractVector} = nothing,
    kwargs...
) -> Plot

Plot the t-statistic of every factor return, one series per factor.

The figure draws what cs_regression_t_stats returns and computes nothing of its own. The series are labelled by the factor names of the answer's axis, which cs_diagnostic_factor_names resolves, so a block that carries a family re-basis is labelled on the reduced axis.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
nf: Factor names of the answer's axis. nothing reads them off the block, and falls back to the position of the factor.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_cs_regression_t_stat_exceedance_rate — Function

plot_cs_regression_t_stat_exceedance_rate(
    csfm::CrossSectionalFactorModel;
    nf::Option{<:AbstractVector} = nothing,
    threshold::Number = 2,
    kwargs...
) -> Plot
plot_cs_regression_t_stat_exceedance_rate(
    pr::AbstractPriorResult;
    nf::Option{<:AbstractVector} = nothing,
    threshold::Number = 2,
    kwargs...
) -> Plot

Plot the fraction of observations at which each factor's t-statistic exceeds a threshold.

The figure draws what cs_regression_t_stat_exceedance_rate returns and computes nothing of its own. A reference line marks the rate a factor of no explanatory power would reach.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
nf: Factor names of the answer's axis. nothing reads them off the block, and falls back to the position of the factor.
threshold: Absolute t-statistic above which an observation counts as significant.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_exposure_vif — Function

plot_exposure_vif(
    csfm::CrossSectionalFactorModel;
    nf::Option{<:AbstractVector} = nothing,
    kwargs...
) -> Plot
plot_exposure_vif(
    pr::AbstractPriorResult;
    nf::Option{<:AbstractVector} = nothing,
    kwargs...
) -> Plot

Plot the variance inflation factor of every factor, one series per factor.

The figure draws what exposure_vif returns and computes nothing of its own. A reference line marks the value an orthogonal design reaches.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
nf: Factor names of the answer's axis. nothing reads them off the block, and falls back to the position of the factor.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_exposure_condition_number — Function

plot_exposure_condition_number(csfm::CrossSectionalFactorModel; kwargs...) -> Plot
plot_exposure_condition_number(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the condition number of the cross-sectional design of every observation.

The figure draws what exposure_condition_number returns and computes nothing of its own. The vertical axis is logarithmic, because the condition number of a nearly collinear design is many orders of magnitude above that of a well conditioned one.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_attribution_vol_contrib — Function

plot_attribution_vol_contrib(
    fa::FactorAttributionResult;
    by_family::Bool = false,
    rd::ReturnsResult = ReturnsResult(),
    nf::Option{<:AbstractVector} = nothing,
    N::Option{<:Number} = nothing,
    kwargs...
) -> Plot

Plot the volatility contribution of each factor, or of each factor family, as a bar chart.

The plot reads one FactorAttributionResult and computes nothing: the rows it draws are fa.fbd.vol_contrib, or fa.fmbd.vol_contrib under by_family, and it selects and orders the rows it shows. A family axis is present only when the factor model block names families, so by_family = true on a Result whose fmbd is nothing raises.

Arguments

fa: Factor attribution result.
by_family: Whether to draw the family axis rather than the factor axis.
rd: Returns result providing the factor names through rd.nf.
nf: Factor names; overrides rd.nf when provided. Inert under by_family, whose labels the Result carries.
N: Maximum number of rows to display, chosen by the magnitude of the value drawn. The rows shown keep the order of the axis, and the rest are not drawn.

Validation

If by_family is true, fa.fmbd is not nothing, else an ArgumentError is raised.
If N is not nothing, N > 0.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

factor_attribution
FactorAttributionResult
plot_attribution_mu_contrib
plot_attribution_exposure
plot_attribution_mu_vs_vol

PortfolioOptimisers.plot_attribution_mu_contrib — Function

plot_attribution_mu_contrib(
    fa::FactorAttributionResult;
    by_family::Bool = false,
    rd::ReturnsResult = ReturnsResult(),
    nf::Option{<:AbstractVector} = nothing,
    N::Option{<:Number} = nothing,
    z::Number = 1.96,
    kwargs...
) -> Plot

Plot the mean return contribution of each factor, or of each factor family, as a bar chart with error bars.

The plot reads one FactorAttributionResult and computes nothing beyond the half-width z * se it draws. The bars are fa.fbd.mu_contrib, or fa.fmbd.mu_contrib under by_family, and the error bars are the standard errors the Result carries. A Result fitted without se = true carries none, and the plot then draws the bars alone.

Arguments

fa: Factor attribution result.
by_family: Whether to draw the family axis rather than the factor axis.
rd: Returns result providing the factor names through rd.nf.
nf: Factor names; overrides rd.nf when provided. Inert under by_family, whose labels the Result carries.
N: Maximum number of rows to display, chosen by the magnitude of the value drawn. The rows shown keep the order of the axis, and the rest are not drawn.
z: Half-width of the error bar, in standard errors.

Validation

If by_family is true, fa.fmbd is not nothing, else an ArgumentError is raised.
If N is not nothing, N > 0.
z >= 0.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

factor_attribution
FactorAttributionResult
plot_attribution_vol_contrib
plot_attribution_exposure
plot_attribution_mu_vs_vol

PortfolioOptimisers.plot_attribution_exposure — Function

plot_attribution_exposure(
    fa::FactorAttributionResult;
    by_family::Bool = false,
    rd::ReturnsResult = ReturnsResult(),
    nf::Option{<:AbstractVector} = nothing,
    N::Option{<:Number} = nothing,
    kwargs...
) -> Plot

Plot the portfolio's exposure to each factor, or to each factor family, as a bar chart with its spread.

The plot reads one FactorAttributionResult and computes nothing: the bars are fa.fbd.exposure, or fa.fmbd.exposure under by_family, and the error bars are the spread of the per-observation exposure the Result carries. A predicted attribution reads one exposure and no history, so it carries no spread and the plot draws the bars alone.

Arguments

fa: Factor attribution result.
by_family: Whether to draw the family axis rather than the factor axis.
rd: Returns result providing the factor names through rd.nf.
nf: Factor names; overrides rd.nf when provided. Inert under by_family, whose labels the Result carries.
N: Maximum number of rows to display, chosen by the magnitude of the value drawn. The rows shown keep the order of the axis, and the rest are not drawn.

Validation

If by_family is true, fa.fmbd is not nothing, else an ArgumentError is raised.
If N is not nothing, N > 0.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

factor_attribution
FactorAttributionResult
plot_attribution_vol_contrib
plot_attribution_mu_contrib
plot_attribution_mu_vs_vol

PortfolioOptimisers.plot_attribution_mu_vs_vol — Function

plot_attribution_mu_vs_vol(
    fa::FactorAttributionResult;
    by_family::Bool = false,
    rd::ReturnsResult = ReturnsResult(),
    nf::Option{<:AbstractVector} = nothing,
    N::Option{<:Number} = nothing,
    kwargs...
) -> Plot

Plot the mean return contribution of each factor against its volatility contribution, as a labelled scatter.

The plot reads one FactorAttributionResult and computes nothing: each point is one row of the factor axis, or of the family axis under by_family, placed at its volatility contribution and its mean return contribution. It is where a reader sees which factor paid for the risk it carried.

Arguments

fa: Factor attribution result.
by_family: Whether to draw the family axis rather than the factor axis.
rd: Returns result providing the factor names through rd.nf.
nf: Factor names; overrides rd.nf when provided. Inert under by_family, whose labels the Result carries.
N: Maximum number of rows to display, chosen by the magnitude of the volatility contribution. The rest are not drawn.

Validation

If by_family is true, fa.fmbd is not nothing, else an ArgumentError is raised.
If N is not nothing, N > 0.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

factor_attribution
FactorAttributionResult
plot_attribution_vol_contrib
plot_attribution_mu_contrib
plot_attribution_exposure

PortfolioOptimisers.plot_exposure_correlation — Function

plot_exposure_correlation(
    csfm::CrossSectionalFactorModel;
    nf::Option{<:AbstractVector} = nothing,
    weighting = BenchmarkWeightMetric(),
    kwargs...
) -> Plot
plot_exposure_correlation(
    pr::AbstractPriorResult;
    nf::Option{<:AbstractVector} = nothing,
    weighting = BenchmarkWeightMetric(),
    kwargs...
) -> Plot

Plot the time-averaged correlation between every pair of factor exposures as a heatmap.

The figure draws what exposure_correlation returns and computes nothing of its own. The colour scale is fixed to the range of a correlation, so two figures of two models are read against the same scale.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
nf: Factor names of the answer's axis. nothing reads them off the block, and falls back to the position of the factor.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_cumulative_exposure_ic — Function

plot_cumulative_exposure_ic(
    csfm::CrossSectionalFactorModel;
    nf::Option{<:AbstractVector} = nothing,
    rank::Bool = true,
    reduced::Bool = false,
    kwargs...
) -> Plot
plot_cumulative_exposure_ic(
    pr::AbstractPriorResult;
    nf::Option{<:AbstractVector} = nothing,
    rank::Bool = true,
    reduced::Bool = false,
    kwargs...
) -> Plot

Plot the running sum of the information coefficient of every factor exposure, one series per factor.

The figure draws the running sum of what exposure_ic returns at a horizon of one observation, and computes nothing else of its own. A series that rises through the sample is an exposure that forecast the return, a flat series is one that carried no forecast, and a falling series is one whose forecast had the opposite sign.

A risk factor with an information coefficient near zero is not a bad risk factor. A risk factor is built to explain the covariance and not to predict the mean, so read plot_exposure_stability and the variance the factor contributes before you judge one.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
nf: Factor names of the answer's axis. nothing reads them off the block, and falls back to the position of the factor.
rank: Take the rank correlation when true, and the weighted correlation otherwise.
reduced: Map the exposures through the family re-basis of the block before the correlation.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_exposure_distribution — Function

plot_exposure_distribution(
    csfm::CrossSectionalFactorModel;
    factor::Integer = 1,
    observation::Option{<:Integer} = nothing,
    nf::Option{<:AbstractVector} = nothing,
    kwargs...
) -> Plot
plot_exposure_distribution(
    pr::AbstractPriorResult;
    factor::Integer = 1,
    observation::Option{<:Integer} = nothing,
    nf::Option{<:AbstractVector} = nothing,
    kwargs...
) -> Plot

Plot the cross-sectional distribution of one factor exposure as a histogram.

The figure draws one slice of the exposure history of the block and computes nothing of its own. observation selects one observation, and nothing pools every observation into one figure. The entries that are not finite are dropped, so the count of the figure is the coverage of the factor.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
factor: Position of the factor on the raw factor axis of the block.
observation: Position of the observation, or nothing to pool every observation.
nf: Factor names of the raw axis. nothing reads them off the block, and falls back to the position of the factor.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_exposure_dispersion — Function

plot_exposure_dispersion(
    csfm::CrossSectionalFactorModel;
    nf::Option{<:AbstractVector} = nothing,
    weighting = BenchmarkWeightMetric(),
    kwargs...
) -> Plot
plot_exposure_dispersion(
    pr::AbstractPriorResult;
    nf::Option{<:AbstractVector} = nothing,
    weighting = BenchmarkWeightMetric(),
    kwargs...
) -> Plot

Plot the weighted cross-sectional standard deviation of every factor exposure, one series per factor.

The figure draws what exposure_dispersion returns and computes nothing of its own. Read the series and not its level: the level follows the standardisation the exposures were built under, and the series shows the observation at which the panel changed.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
nf: Factor names of the answer's axis. nothing reads them off the block, and falls back to the position of the factor.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_exposure_stability — Function

plot_exposure_stability(
    csfm::CrossSectionalFactorModel;
    nf::Option{<:AbstractVector} = nothing,
    step::Integer = 21,
    weighting = BenchmarkWeightMetric(),
    kwargs...
) -> Plot
plot_exposure_stability(
    pr::AbstractPriorResult;
    nf::Option{<:AbstractVector} = nothing,
    step::Integer = 21,
    weighting = BenchmarkWeightMetric(),
    kwargs...
) -> Plot

Plot the stability of every factor exposure, one series per factor.

The figure draws what exposure_stability returns and computes nothing of its own. A reference line marks the value an exposure that keeps its ordering of the assets reaches.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
nf: Factor names of the answer's axis. nothing reads them off the block, and falls back to the position of the factor.
step: Number of observations between the two cross-sections.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_factor_model_summary — Function

plot_factor_model_summary(
    fs::FactorSummaryResult;
    nf::Option{<:AbstractVector} = nothing,
    kwargs...
) -> Plot
plot_factor_model_summary(
    csfm::CrossSectionalFactorModel;
    nf::Option{<:AbstractVector} = nothing,
    ppy::Number = 1,
    threshold::Number = 2,
    step::Integer = 21,
    weighting = BenchmarkWeightMetric(),
    coverage_weighting = RegressionWeightMetric(),
    kwargs...
) -> Plot
plot_factor_model_summary(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the columns of a factor model summary as a grouped bar chart, one group per column and one bar per factor.

The figure draws what factor_model_summary returns and computes nothing of its own. A column the summary carries as nothing is not drawn, and the title says so, so a block with no exposure history draws its four factor return columns alone.

The columns are not on one scale, and the figure rescales none of them. Read a column against its own factors and not against the column beside it.

Arguments

fs: A factor model summary.
csfm: A cross-sectional factor model block, which the figure summarises first.
pr: A prior result whose rr is such a block.
nf: Factor names of the raw factor axis. nothing reads them off the block, and falls back to the position of the factor.
ppy: Periods per year the summary annualises with.
threshold: Absolute t-statistic the exceedance rate counts against.
step: Number of observations between the two cross-sections the stability reads.
weighting: The AbstractOrthogonalityMetric the stability reads.
coverage_weighting: The AbstractOrthogonalityMetric whose positive weights are the universe of the coverage.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_factor_forecast_correlation — Function

plot_factor_forecast_correlation(
    f_sigma::MatNum,
    nf::AbstractVector = 1:size(f_sigma, 1);
    kwargs...
) -> Plot
plot_factor_forecast_correlation(
    pr::AbstractPriorResult,
    nf::Option{<:AbstractVector} = nothing;
    kwargs...
) -> Plot

Plot the forecast correlation of the factor returns as a heatmap.

The figure reads the factor covariance fpr.sigma of the prior result and rescales a copy of it to a correlation with StatsBase.cov2cor!. It is the forecast the prior carries, and not the realised correlation of the fitted factor return series, so it answers on the factor axis of the factor prior.

plot_factor_sigma draws the same matrix unscaled.

Arguments

f_sigma: Factor covariance matrix factors × factors.
pr: A prior result carrying a factor prior.
nf: Factor names. nothing falls back to the position of the factor.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.fpr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_factor_sigma
plot_factor_forecast_volatilities

PortfolioOptimisers.plot_factor_forecast_volatilities — Function

plot_factor_forecast_volatilities(
    f_sigma::MatNum,
    nf::AbstractVector = 1:size(f_sigma, 1);
    ppy::Number = 1,
    kwargs...
) -> Plot
plot_factor_forecast_volatilities(
    pr::AbstractPriorResult,
    nf::Option{<:AbstractVector} = nothing;
    ppy::Number = 1,
    kwargs...
) -> Plot

Plot the forecast volatility of every factor return as a horizontal bar chart, ordered from the smallest.

The figure reads the factor covariance fpr.sigma of the prior result and draws the square root of ppy times its diagonal. It is the forecast the prior carries, and not the realised volatility factor_model_summary reports.

Arguments

f_sigma: Factor covariance matrix factors × factors.
pr: A prior result carrying a factor prior.
nf: Factor names. nothing falls back to the position of the factor.
ppy: Periods per year the volatility is annualised with.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.fpr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_factor_forecast_correlation
factor_model_summary

PortfolioOptimisers.plot_factor_cumulative_returns — Function

plot_factor_cumulative_returns(
    csfm::CrossSectionalFactorModel;
    nf::Option{<:AbstractVector} = nothing,
    compound::Bool = false,
    kwargs...
) -> Plot
plot_factor_cumulative_returns(
    pr::AbstractPriorResult;
    nf::Option{<:AbstractVector} = nothing,
    compound::Bool = false,
    kwargs...
) -> Plot

Plot the cumulative return of every factor, one series per factor.

The figure draws cumulative_returns of each column of the factor return history csr.f, on the raw factor axis. An observation whose factor return is not finite contributes nothing to the running sum, so one absent cross-section breaks no series; this is the convention plot_cumulative_exposure_ic already follows.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
nf: Factor names of the raw factor axis. nothing reads them off the block, and falls back to the position of the factor.
compound: Whether the cumulative series compounds.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.
csfm.csr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_idio_calibration — Function

plot_idio_calibration(csfm::CrossSectionalFactorModel; kwargs...) -> Plot
plot_idio_calibration(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the cross-sectional standard deviation of the standardised idiosyncratic returns against the observation axis.

The figure draws what idio_calibration returns and computes nothing of its own. A dashed line marks the Gaussian reference of 1. A series that sits above the line is a fit whose specific risk is too small, and one that sits below it is a fit whose specific risk is too large.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_idio_tail_rate — Function

plot_idio_tail_rate(
    csfm::CrossSectionalFactorModel;
    threshold::Real = 3,
    kwargs...
) -> Plot
plot_idio_tail_rate(
    pr::AbstractPriorResult;
    threshold::Real = 3,
    kwargs...
) -> Plot

Plot the share of assets whose standardised idiosyncratic return exceeds a threshold, against the observation axis.

The figure draws what idio_tail_rate returns and computes nothing of its own. A dashed line marks the Gaussian reference $2 \Phi(-c)$, which is about 0.0027 at the default threshold. A series above the line is a fit whose standardised returns carry heavier tails than the normal law implies, which is ordinary for an equity universe.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
threshold: Absolute standardised return above which an asset enters the rate.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_idio_kurtosis — Function

plot_idio_kurtosis(csfm::CrossSectionalFactorModel; kwargs...) -> Plot
plot_idio_kurtosis(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the cross-sectional excess kurtosis of the standardised idiosyncratic returns against the observation axis.

The figure draws what idio_kurtosis returns and computes nothing of its own. A dashed line marks the Gaussian reference of 0. A positive series is a cross-section whose tails are heavier than the normal law implies.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_idio_skewness — Function

plot_idio_skewness(csfm::CrossSectionalFactorModel; kwargs...) -> Plot
plot_idio_skewness(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the cross-sectional skewness of the standardised idiosyncratic returns against the observation axis.

The figure draws what idio_skewness returns and computes nothing of its own. A dashed line marks the Gaussian reference of 0. A series that stays on one side of the line is a residual that carries a direction the factors did not take.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_idio_vol_ic — Function

plot_idio_vol_ic(csfm::CrossSectionalFactorModel; kwargs...) -> Plot
plot_idio_vol_ic(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the information coefficient of the predicted idiosyncratic volatility against the observation axis.

The figure draws what idio_vol_ic returns and computes nothing of its own. It carries no reference line: the series has no Gaussian reference, and a caller reads its level and its sign. A series that stays high is a fit that ranks specific risk across the assets well.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_idio_vol_residual_dependence — Function

plot_idio_vol_residual_dependence(csfm::CrossSectionalFactorModel; kwargs...) -> Plot
plot_idio_vol_residual_dependence(pr::AbstractPriorResult; kwargs...) -> Plot

Plot the residual dependence of the standardised idiosyncratic returns on the predicted volatility, against the observation axis.

The figure draws what idio_vol_residual_dependence returns and computes nothing of its own. A dashed line marks the reference of 0, which a well calibrated fit sits on. Read it beside plot_idio_vol_ic: a fit that ranks well and leaves no residual dependence carries a high information coefficient and a dependence near 0.

Arguments

csfm: A cross-sectional factor model block.
pr: A prior result whose rr is such a block.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

pr.rr is not nothing.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_forecast_cumulative_ic — Function

plot_forecast_cumulative_ic(
    fe::ForecastEvaluationResult,
    w::Option{<:MatNum} = nothing;
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot
plot_forecast_cumulative_ic(
    fe::ForecastEvaluationResult,
    csfm::CrossSectionalFactorModel;
    weighting = IdentityMetric(),
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot
plot_forecast_cumulative_ic(
    fes::AbstractVector{<:ForecastEvaluationResult},
    w::Option{<:MatNum} = nothing;
    names = nothing,
    rank::Bool = true,
    kwargs...
) -> Plot
plot_forecast_cumulative_ic(
    fes::AbstractVector{<:ForecastEvaluationResult},
    csfm::CrossSectionalFactorModel;
    weighting = IdentityMetric(),
    names = nothing,
    rank::Bool = true,
    kwargs...
) -> Plot

Plot the running sum of the information coefficient of a Return Forecast: both coefficients of one forecast, or one coefficient of several forecasts overlaid.

The figure draws the running sum of what forecast_ic returns and computes nothing else of its own. A series that rises through the sample is a forecast that ordered the cross-section, a flat series is one that carried no ordering, and a falling series is one whose ordering had the opposite sign. An evaluation date that carries no coefficient contributes nothing to the running sum, so one thin cross-section breaks no series.

The vector method is the comparison

A mean hides whether an edge was continuous or came from three dates, and a comparison of two means hides it twice. The vector method draws one series per evaluation on the dates the evaluations share, with a zero reference line, so the reader sees where in the sample each forecast earned its coefficient. It is the figure the length-2 ForecastSummaryResult is the table of, and it refuses evaluations that are not comparable with forecast_summary_assert_comparable, exactly as forecast_evaluation_summary does: two forecasts on different dates overlay nothing. One coefficient is drawn, named by rank, so that a figure of four forecasts carries four series and not eight. The threshold is each evaluation's own, for the reason forecast_summary_row states, and the comparability check makes it one number.

The figure takes the evaluation and not the block

Every figure of this group takes the ForecastEvaluationResult, where the cross-sectional diagnostics take the block. Those verbs read a block that is already fitted, so a figure that calls one costs nothing; here the Return Forecast history can cost a rolling refit through forecast_history, so a caller pairs once with forecast_evaluation and every figure reads that pairing. A weighting still reaches the figure the way it reaches the level-2 verbs: as a bare weight history positionally, or as the block whose AbstractOrthogonalityMetric resolves one.

Arguments

fe: The evaluation to draw, from forecast_evaluation.
fes: The evaluations to overlay, at least one, from forecast_evaluation.
w: Cross-sectional weight history observations × assets, on the axis of the forecast, or nothing for equal weights.
csfm: A cross-sectional factor model block, whose weight history weighting names.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
min_count: Least number of assets a cross-section needs before a coefficient of it is reported.
names: One name per evaluation, or nothing to number them.
rank: Overlay the Spearman coefficient when true, and the Pearson coefficient otherwise.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

The rules of forecast_ic.
The vector method: the rules of forecast_summary_assert_comparable and forecast_summary_names.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_forecast_rolling_ic — Function

plot_forecast_rolling_ic(
    fe::ForecastEvaluationResult,
    w::Option{<:MatNum} = nothing;
    rolling::Integer = 0,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot
plot_forecast_rolling_ic(
    fe::ForecastEvaluationResult,
    csfm::CrossSectionalFactorModel;
    weighting = IdentityMetric(),
    rolling::Integer = 0,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot

Plot the running mean of both information coefficients of a Return Forecast over a window.

The figure draws the mean of the last rolling evaluation dates of what forecast_ic returns, one series per coefficient. Where plot_forecast_cumulative_ic shows what the forecast earned over the whole sample, this shows where in the sample it earned it. An evaluation date that carries no coefficient is left out of the mean of every window it falls in, so the series is the mean of the dates that scored.

rolling follows plot_rolling_measure: 0 takes the square root of the number of evaluation dates, rounded up.

The figure takes the evaluation and not the block, for the reason plot_forecast_cumulative_ic states.

Arguments

fe: The evaluation to draw, from forecast_evaluation.
w: Cross-sectional weight history observations × assets, on the axis of the forecast, or nothing for equal weights.
csfm: A cross-sectional factor model block, whose weight history weighting names.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
rolling: Number of evaluation dates in the window, or 0 for the square root of their number.
min_count: Least number of assets a cross-section needs before a coefficient of it is reported.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

rolling resolves to a window in 1:length(fe.dates).
The rules of forecast_ic.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_forecast_cumulative_returns — Function

plot_forecast_cumulative_returns(
    fe::ForecastEvaluationResult;
    kinds = (:rank, :zscore),
    compound::Bool = false,
    kwargs...
) -> Plot
plot_forecast_cumulative_returns(
    fes::AbstractVector{<:ForecastEvaluationResult};
    names = nothing,
    kind::Symbol = :rank,
    compound::Bool = false,
    kwargs...
) -> Plot

Plot the cumulative return of the books a Return Forecast states on its own: both books of one forecast, or one book of several forecasts overlaid.

The figure draws the running sum of the return series of forecast_portfolio and computes nothing else of its own. Both books are centred and rescaled to the same gross exposure, so the two series are read against each other and against the same series of another forecast. An evaluation date whose cross-section carried no book is held flat, which is what plot_factor_cumulative_returns does to an absent factor return.

The vector method is the comparison, for the reason plot_forecast_cumulative_ic states: one series per evaluation on the dates the evaluations share, a zero reference line, and a refusal of evaluations that are not comparable with forecast_summary_assert_comparable. One book is drawn, named by kind, so that a figure of four forecasts carries four series and not eight.

The figure takes the evaluation and not the block, for the reason plot_forecast_cumulative_ic states.

Arguments

fe: The evaluation to draw, from forecast_evaluation.
fes: The evaluations to overlay, at least one, from forecast_evaluation.
kinds: The books to draw, each :rank or :zscore, as forecast_portfolio_weights names them.
kind: The one book to overlay, :rank or :zscore.
names: One name per evaluation, or nothing to number them.
compound: Whether the cumulative series compounds.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

The rules of forecast_portfolio.
The vector method: the rules of forecast_summary_assert_comparable and forecast_summary_names.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_forecast_quantile_returns — Function

plot_forecast_quantile_returns(
    fe::ForecastEvaluationResult;
    quantiles = (0.1,),
    compound::Bool = false,
    kwargs...
) -> Plot

Plot the cumulative top-minus-bottom spread of a Return Forecast, one series per quantile.

The figure draws the running sum of the spread series of forecast_quantile_spread and computes nothing else of its own. A spread that keeps rising as the tail narrows is a forecast whose ordering is sharpest at its ends, and one that flattens is a forecast whose ordering is spread across the whole cross-section. An evaluation date whose cross-section carried no spread is held flat.

The figure takes the evaluation and not the block, for the reason plot_forecast_cumulative_ic states.

Arguments

fe: The evaluation to draw, from forecast_evaluation.
quantiles: Tail fractions the spreads are cut at, each in (0, 0.5].
compound: Whether the cumulative series compounds.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

The rules of forecast_quantile_spread.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_forecast_calibration — Function

plot_forecast_calibration(
    fe::ForecastEvaluationResult,
    w::Option{<:MatNum} = nothing;
    bins::Integer = 10,
    kwargs...
) -> Plot
plot_forecast_calibration(
    fe::ForecastEvaluationResult,
    csfm::CrossSectionalFactorModel;
    weighting = IdentityMetric(),
    bins::Integer = 10,
    kwargs...
) -> Plot

Plot the calibration curve of a Return Forecast against the slope fitted through it.

The figure draws the curve of forecast_calibration as a scatter of the mean realised target of each bin against the mean forecast of that bin, and lays the zero-intercept slope of the same call over it. The two answer different questions: the curve says whether the relation is a straight line, and the slope says what multiplier maps the forecast onto realised units. A curve that sits below the slope at its right end is a forecast whose largest values are the least believable.

This is the one reading of a forecast a rescaling moves. The coefficients correlate and the books are rescaled to a fixed gross exposure, so both are invariant to the units the forecast is stated in; the slope is not, and that is what it is for.

The figure takes the evaluation and not the block, for the reason plot_forecast_cumulative_ic states.

Arguments

fe: The evaluation to draw, from forecast_evaluation.
w: Cross-sectional weight history observations × assets, on the axis of the forecast, or nothing for equal weights.
csfm: A cross-sectional factor model block, whose weight history weighting names.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
bins: Number of quantile bins the curve is cut into.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

The rules of forecast_calibration.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_forecast_ic_by_holding_period — Function

plot_forecast_ic_by_holding_period(
    fe::ForecastEvaluationResult,
    X::MatNum,
    w::Option{<:MatNum} = nothing;
    n::Integer = 10,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot
plot_forecast_ic_by_holding_period(
    fe::ForecastEvaluationResult,
    rd::ReturnsResult,
    csfm::CrossSectionalFactorModel;
    weighting = IdentityMetric(),
    n::Integer = 10,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot

Plot both mean information coefficients of a Return Forecast against the holding period.

The figure draws two columns of the table of forecast_holding_period against its period and computes nothing of its own. A column that holds as the window lengthens is a forecast about a slow quantity, and one that falls away is a forecast whose book must be turned over to capture it.

Every row of the table is read on one date set, so the figure is internally comparable and is not comparable to the same figure at another n. A caller who compares two depths draws the deeper one.

The figure takes the evaluation and not the block, for the reason plot_forecast_cumulative_ic states. The target history is the second argument for the same reason the verb takes it: a re-windowing needs the history the target was built from, and the evaluation carries only the matured target.

Arguments

fe: The evaluation to draw, from forecast_evaluation.
X: Target history observations × assets, on the axis of the forecast, from forecast_target_history.
rd: The carrier the target history is built from.
w: Cross-sectional weight history observations × assets, on the axis of the forecast, or nothing for equal weights.
csfm: A cross-sectional factor model block, whose weight history weighting names.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
n: Number of holding periods the table reaches.
min_count: Least number of assets a cross-section needs before a statistic of it is reported.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

The rules of forecast_holding_period.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_forecast_portfolio_by_holding_period — Function

plot_forecast_portfolio_by_holding_period(
    fe::ForecastEvaluationResult,
    X::MatNum,
    w::Option{<:MatNum} = nothing;
    n::Integer = 10,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot
plot_forecast_portfolio_by_holding_period(
    fe::ForecastEvaluationResult,
    rd::ReturnsResult,
    csfm::CrossSectionalFactorModel;
    weighting = IdentityMetric(),
    n::Integer = 10,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot

Plot the annualised return and the Sharpe ratio of both books against the holding period.

The figure draws four columns of the table of forecast_holding_period against its period and computes nothing of its own. It is the book-level reading of what plot_forecast_ic_by_holding_period shows at the coefficient level, and the two are read together: a coefficient that survives a longer window is only worth holding if the book built on it does too.

The four columns carry two units, so the axis is labelled Value and read column by column, which is what plot_factor_model_summary does with the same mix.

Every row of the table is read on one date set, so the figure is internally comparable and is not comparable to the same figure at another n.

The figure takes the evaluation and not the block, for the reason plot_forecast_cumulative_ic states.

Arguments

fe: The evaluation to draw, from forecast_evaluation.
X: Target history observations × assets, on the axis of the forecast, from forecast_target_history.
rd: The carrier the target history is built from.
w: Cross-sectional weight history observations × assets, on the axis of the forecast, or nothing for equal weights.
csfm: A cross-sectional factor model block, whose weight history weighting names.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
n: Number of holding periods the table reaches.
min_count: Least number of assets a cross-section needs before a statistic of it is reported.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

The rules of forecast_holding_period.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_forecast_ic_decay — Function

plot_forecast_ic_decay(
    fe::ForecastEvaluationResult,
    X::MatNum,
    w::Option{<:MatNum} = nothing;
    n::Integer = 10,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot
plot_forecast_ic_decay(
    fe::ForecastEvaluationResult,
    rd::ReturnsResult,
    csfm::CrossSectionalFactorModel;
    weighting = IdentityMetric(),
    n::Integer = 10,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot

Plot both mean information coefficients of a Return Forecast against the forward window.

The figure draws two columns of the table of forecast_decay against its period and computes nothing of its own. The windows are disjoint rather than cumulative, so the figure answers how long the forecast keeps forecasting: the first period is the horizon it was paired at, and a later period is the same forecast scored against a window it never saw.

Every row of the table is read on one date set, so the figure is internally comparable and is not comparable to the same figure at another n.

The figure takes the evaluation and not the block, for the reason plot_forecast_cumulative_ic states.

Arguments

fe: The evaluation to draw, from forecast_evaluation.
X: Target history observations × assets, on the axis of the forecast, from forecast_target_history.
rd: The carrier the target history is built from.
w: Cross-sectional weight history observations × assets, on the axis of the forecast, or nothing for equal weights.
csfm: A cross-sectional factor model block, whose weight history weighting names.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
n: Number of forward windows the table reaches.
min_count: Least number of assets a cross-section needs before a statistic of it is reported.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

The rules of forecast_decay.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

forecast_decay
plot_forecast_portfolio_decay
plot_forecast_ic_by_holding_period
ForecastEvaluationResult

PortfolioOptimisers.plot_forecast_portfolio_decay — Function

plot_forecast_portfolio_decay(
    fe::ForecastEvaluationResult,
    X::MatNum,
    w::Option{<:MatNum} = nothing;
    n::Integer = 10,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot
plot_forecast_portfolio_decay(
    fe::ForecastEvaluationResult,
    rd::ReturnsResult,
    csfm::CrossSectionalFactorModel;
    weighting = IdentityMetric(),
    n::Integer = 10,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot

Plot the annualised return and the Sharpe ratio of both books against the forward window.

The figure draws four columns of the table of forecast_decay against its period and computes nothing of its own. It is the book-level reading of what plot_forecast_ic_decay shows at the coefficient level.

The four columns carry two units, so the axis is labelled Value and read column by column.

Every row of the table is read on one date set, so the figure is internally comparable and is not comparable to the same figure at another n.

The figure takes the evaluation and not the block, for the reason plot_forecast_cumulative_ic states.

Arguments

fe: The evaluation to draw, from forecast_evaluation.
X: Target history observations × assets, on the axis of the forecast, from forecast_target_history.
rd: The carrier the target history is built from.
w: Cross-sectional weight history observations × assets, on the axis of the forecast, or nothing for equal weights.
csfm: A cross-sectional factor model block, whose weight history weighting names.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
n: Number of forward windows the table reaches.
min_count: Least number of assets a cross-section needs before a statistic of it is reported.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

The rules of forecast_decay.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

forecast_decay
plot_forecast_ic_decay
plot_forecast_portfolio_by_holding_period
ForecastEvaluationResult

PortfolioOptimisers.plot_forecast_factor_correlation — Function

plot_forecast_factor_correlation(
    fe::ForecastEvaluationResult,
    B::Arr3Num,
    w::Option{<:MatNum} = nothing;
    nf::Option{<:AbstractVector} = nothing,
    dates::AbstractVector{<:Integer} = axes(fe.alpha, 1),
    rank::Bool = false,
    min_count::Integer = fe.min_count,
    kwargs...
) -> Plot
plot_forecast_factor_correlation(
    fe::ForecastEvaluationResult,
    csfm::CrossSectionalFactorModel;
    nf::Option{<:AbstractVector} = nothing,
    weighting = IdentityMetric(),
    kwargs...
) -> Plot

Plot the contemporaneous correlation of a Return Forecast with every factor exposure.

The figure draws what forecast_factor_correlation returns and computes nothing of its own, one series per factor, on the rows dates names. Nothing here is forward looking: the correlation is taken on the date the forecast is stated, so the figure says what the forecast is, not what it earned, and it is drawn on every observation by default rather than on the evaluation grid; dates = fe.dates draws the grid. A series that sits near one is a forecast that restates an exposure the risk model already holds, and the return it earns is that factor's return under another name.

A neutralised forecast does not read zero here. The cross-sectional fit that neutralises it carries no intercept, so its residual is orthogonal to its target in the uncentred sense and keeps a correlation with it.

The figure takes the evaluation and not the block, for the reason plot_forecast_cumulative_ic states.

Arguments

fe: The evaluation to draw, from forecast_evaluation.
B: Exposure history observations × assets × factors, on the axis of the forecast.
w: Cross-sectional weight history observations × assets, on the axis of the forecast, or nothing for equal weights.
csfm: A cross-sectional factor model block, whose exposure history and weight history are read.
nf: Factor names of the answer's axis. nothing reads them off the block, and falls back to the position of the factor.
dates: Row indices of fe.alpha the correlation is read and drawn on. The default is every observation; fe.dates reads the evaluation grid.
rank: Take the rank correlation when true, and the weighted correlation otherwise.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
min_count: Least number of assets a cross-section needs before a correlation of it is reported.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

The rules of forecast_factor_correlation.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

PortfolioOptimisers.plot_forecast_evaluation_summary — Function

plot_forecast_evaluation_summary(fs::ForecastSummaryResult; kwargs...) -> Plot
plot_forecast_evaluation_summary(
    fes::AbstractVector{<:ForecastEvaluationResult},
    w::Option{<:MatNum} = nothing;
    names = nothing,
    bins::Integer = 10,
    quantiles = nothing,
    kwargs...
) -> Plot
plot_forecast_evaluation_summary(
    fes::AbstractVector{<:ForecastEvaluationResult},
    csfm::CrossSectionalFactorModel;
    weighting = IdentityMetric(),
    names = nothing,
    bins::Integer = 10,
    quantiles = nothing,
    kwargs...
) -> Plot
plot_forecast_evaluation_summary(
    fe::ForecastEvaluationResult,
    w::Option{<:MatNum} = nothing;
    kwargs...
) -> Plot
plot_forecast_evaluation_summary(
    fe::ForecastEvaluationResult,
    csfm::CrossSectionalFactorModel;
    kwargs...
) -> Plot

Plot a ForecastSummaryResult as a grouped bar chart, one series per forecast.

The figure draws the ten headline columns of the summary — both mean information coefficients and their information ratios, the annualised return and the Sharpe ratio of each book, the calibration slope and the mean coverage — with the statistic on the axis and the forecast as the series, which is the shape plot_factor_model_summary takes. A single evaluation is the length-1 case and a set of them is the comparison, exactly as the Result is.

The quantile-spread block is drawn when the summary carries one, as one bar group per quantile. A summary built with no quantile carries the block as nothing, and then the block is not drawn and the title says so.

The columns carry several units, so the axis is labelled Value and read group by group. The columns the summary carries that this figure does not draw are read off the Result, which prints all of them.

Arguments

fs: The summary to draw, from forecast_evaluation_summary.
fes: The evaluations to summarise and draw, at least one.
fe: One evaluation. It is drawn as the length-1 case.
w: Cross-sectional weight history observations × assets, on the axis of the forecasts, or nothing for equal weights.
csfm: A cross-sectional factor model block, whose weight history weighting names.
weighting: A member of AbstractOrthogonalityMetric. It names the weight history the block is read with.
names: One name per evaluation, or nothing to number them.
bins: Number of quantile bins the calibration curve cuts.
quantiles: Tail fractions the quantile spreads are cut at, each in (0, 0.5], or nothing for none.
kwargs...: Additional keyword arguments passed to the plotting backend.

Validation

The rules of forecast_evaluation_summary.

Returns

plt::Plot: The figure.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

const Arr3Num = AbstractArray{<:Union{<:Number, <:JuMP.AbstractJuMPScalar}, 3}

Alias for an abstract 3-dimensional array of numeric types or JuMP scalar types.

const ArrNum = AbstractArray{<:Union{<:Number, <:JuMP.AbstractJuMPScalar}}

Alias for an abstract array of numeric types or JuMP scalar types.

const MatNum = AbstractMatrix{<:Union{<:Number, <:JuMP.AbstractJuMPScalar}}

Alias for an abstract matrix of numeric types or JuMP scalar types.

const Option{T} = Union{Nothing, T}

Alias for an optional value of type T, which may be nothing.

const VecNum = AbstractVector{<:Union{<:Number, <:JuMP.AbstractJuMPScalar}}

Alias for an abstract vector of numeric types or JuMP scalar types.

const VecNum_VecVecNum = Union{<:VecNum, <:VecVecNum}

Alias for a union of a numeric vector or a vector of numeric vectors.

const VecVecNum = AbstractVector{<:VecNum}

Alias for an abstract vector of numeric vectors.

const RegE_Reg = Union{<:AbstractLoadingsRegressionResult,
                       <:AbstractTimeSeriesRegressionEstimator}

Alias for a loadings regression result or a time-series regression estimator.

const Slv_VecSlv = Union{<:Solver, <:VecSlv}

Alias for a single Solver or a vector of Solver objects.

abstract type AbstractClusteringResult <: AbstractPhylogenyResult

Abstract supertype for all clustering result types.

const NwE_ClE_Cl = Union{<:AbstractNetworkEstimator, <:ClE_Cl}

Alias for a network estimator or clustering estimator/result.

abstract type AbstractCentralityEstimator <: AbstractEstimator

Abstract supertype for all centrality estimator types.

const HClE_HCl = Union{<:ClustersEstimator{<:Any, <:Any,
                                           <:AbstractHierarchicalClusteringAlgorithm,
                                           <:Any},
                       <:Clusters{<:Clustering.Hclust, <:Any, <:Any, <:Any},
                       <:NetworkClustersEstimator{<:Any,
                                              <:AbstractHierarchicalClusteringAlgorithm}}

Alias for a hierarchical clustering estimator or result.

const Pr_RR = Union{<:AbstractPriorResult, <:ReturnsResult}

Groups the two carriers that hold an asset returns matrix X and a feature matrix Z.

abstract type AbstractBaseRiskMeasure <: AbstractEstimator

Abstract supertype for all risk measure estimators.

const BaseRM_VecBaseRM = Union{<:AbstractBaseRiskMeasure, <:VecBaseRM}

Argument bound for every value-level reader of a risk measure: one measure or several.

const MatNum_Pr = Union{<:MatNum, <:AbstractPriorResult, <:ReturnsResult}

Union of matrix-like types accepted as the data argument in risk_contribution and related functions.

struct ReturnsResult{__T_nx, __T_X, __T_nf, __T_F, __T_nb, __T_B, __T_ts, __T_iv, __T_ivpa, __T_pnl} <: AbstractReturnsResult

Stores the results of asset and factor returns calculations.

struct StepwiseRegression{__T_crit, __T_alg, __T_tgt} <: AbstractTimeSeriesRegressionEstimator

Estimates a loadings matrix by selecting a factor subset per asset, one factor at a time.

struct CrossSectionalFactorModel{__T_M, __T_L, __T_b, __T_csr, __T_Ms, __T_vs, __T_esigma, __T_rw, __T_bw, __T_nf, __T_fam, __T_fcb, __T_lag, __T_rf} <: AbstractLoadingsRegressionResult

Holds the loadings, the factor-orthogonal expected return and the fitted history of a factor model fitted per observation across the assets.

struct ForecastEvaluationResult{__T_alpha, __T_y, __T_umsk, __T_dates, __T_target, __T_horizon, __T_lag, __T_step, __T_min_count, __T_ppy} <: AbstractResult

The out-of-sample pairing of a Return Forecast with what happened next.

struct ForecastSummaryResult{__T_names, __T_spearman_mean_ic, __T_spearman_std_ic, __T_spearman_ic_ir, __T_spearman_t_stat, __T_spearman_hit_rate, __T_pearson_mean_ic, __T_pearson_std_ic, __T_pearson_ic_ir, __T_pearson_t_stat, __T_pearson_hit_rate, __T_rank_ann_return, __T_rank_ann_volatility, __T_rank_sharpe, __T_rank_hit_rate, __T_rank_mean_turnover, __T_zscore_ann_return, __T_zscore_ann_volatility, __T_zscore_sharpe, __T_zscore_hit_rate, __T_zscore_mean_turnover, __T_calibration_slope, __T_mean_alpha, __T_std_alpha, __T_mean_y, __T_std_y, __T_n_bins, __T_mean_coverage, __T_min_coverage, __T_mean_n_scored, __T_min_n_scored, __T_quantiles, __T_spread_ann_return, __T_spread_ann_volatility, __T_spread_sharpe, __T_spread_hit_rate, __T_ppy} <: AbstractResult

The headline statistics of one or more Return Forecast evaluations, one entry per forecast.

struct FactorSummaryResult{__T_ann_return, __T_ann_volatility, __T_sharpe, __T_autocorr, __T_mean_abs_t, __T_t_rate, __T_mean_vif, __T_stability, __T_coverage, __T_ppy} <: AbstractResult

The headline statistics of every factor of a cross-sectional factor model.

abstract type AbstractPriorResult <: AbstractResult

Abstract supertype for all prior result types.

struct HighOrderPrior{__T_pr, __T_kt, __T_D2, __T_L2, __T_S2, __T_sk, __T_V, __T_skmp, __T_fpr} <: AbstractPriorResult

Carries the coskewness and cokurtosis a high order prior estimator produced, over the low order prior it wraps.

struct BenchmarkWeightMetric <: AbstractOrthogonalityMetric

Names the benchmark weights as the cross-sectional weight source.

struct IdentityMetric <: AbstractOrthogonalityMetric

Names no weight source: every asset carries the same weight.

struct RegressionWeightMetric <: AbstractOrthogonalityMetric

Names the regression weights as the cross-sectional weight source.

struct Fees{__T_tn, __T_l, __T_s, __T_fl, __T_fs, __T_lq, __T_flq, __T_fa, __T_kwargs, __T_imsk} <: AbstractResult

Charges a portfolio a turnover fee, a long or short proportional fee, and a long or short fixed fee.

abstract type Scalariser <: AbstractEstimator

Abstract supertype for scalarisation strategies used to combine multiple risk measures into a single scalar value for optimisation.

struct SumScalariser <: NonHierarchicalScalariser

Adds the scaled risk measures together.

struct Variance{__T_settings, __T_sigma, __T_chol, __T_rc, __T_alg} <: RiskMeasure

Represents the portfolio variance using a covariance matrix.

abstract type OptimisationResult <: AbstractResult

Abstract supertype for portfolio optimisation result types.

struct MultiPeriodPredictionResult{__T_pred, __T_mrd, __T_id, __T_opt} <: AbstractPredictionResult

Stores predictions from multiple cross-validation folds as a single combined result.

struct PopulationPredictionResult{__T_pred} <: AbstractPredictionResult

Stores a collection of multi-period prediction results produced by a population-based cross-validation scheme (e.g. MultipleRandomised).

struct PredictionResult{__T_res, __T_rd, __T_hw} <: AbstractPredictionResult

Stores the result of a single cross-validation fold prediction.

struct ArithmeticReturn{__T_settings, __T_ucs, __T_mu} <: JuMPReturnsEstimator

Computes the portfolio return as the arithmetic mean return, the dot product of the expected returns and the weights.

struct ExpectedReturn{__T_settings, __T_rt} <: NonOptimisationRiskMeasure

Return-based risk measure.

struct ExpectedReturnRiskRatio{__T_settings, __T_rt, __T_rk, __T_sca, __T_rf} <: NonOptimisationRiskMeasure

Ratio-based risk measure.

struct PerformanceSummaryResult{__T_n_periods, __T_periods_per_year, __T_alpha, __T_compound, __T_ann_return, __T_ann_volatility, __T_sharpe, __T_sharpe_stderr, __T_sortino, __T_calmar, __T_max_drawdown, __T_cvar} <: AbstractResult

The headline performance statistics of a realised return series.

struct FactorAttributionResult{__T_sys, __T_idio, __T_unattr, __T_total, __T_fbd, __T_fmbd, __T_abd, __T_afc, __T_realised, __T_ppy} <: AbstractResult

Decomposes a portfolio's volatility and mean return over the factors, the factor families and the assets of a factor model.