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.

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

source

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.

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

source

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

source

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

source

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

source

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 per-asset risk contribution as a bar chart.

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

source

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 per-factor risk contribution as a bar chart, including the constant (idiosyncratic) term.

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

source

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

source

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

source

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.

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

source

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.

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

source

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.

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).

source

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.

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

source

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.

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

source

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.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

plot_clusters

source

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).

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

source

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(Σ)).

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

source

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.

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

source

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.

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

source

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.

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

source

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.

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.
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.

A single measure is evaluated 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.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

expected_risk

source

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

source

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

source

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}|.

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

MultiPeriodPredictionResult

source

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).

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

source

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).

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

source

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

source

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.

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

Implemented by PortfolioOptimisersPlotsExt (requires StatsPlots).

Related

source

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.

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

source

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.

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

source

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).

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

source

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

source

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.

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

source

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.

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

source

PortfolioOptimisers.relevant_assets — Function

relevant_assets(
    w::AbstractVector{<:Union{var"#s89", var"#s88"} where {var"#s89"<:Number, var"#s88"<:AbstractJuMPScalar}},
    M::Integer
) -> Tuple{Any, Any}
relevant_assets(
    w::AbstractVector{<:Union{var"#s89", var"#s88"} where {var"#s89"<:Number, var"#s88"<:AbstractJuMPScalar}},
    M::Integer,
    N_opt::Union{Nothing, Number}
) -> Tuple{Any, Any}

Select the top-N assets from a weight vector by absolute weight magnitude.

Arguments

w::VecNum: Portfolio weight vector.
M::Integer: Total number of assets (upper bound for N).
N_opt::Option{<:Number} = nothing: Asset-count specification. nothing auto-selects via number_effective_assets.

Returns

Tuple{Int, Vector{Int}}: (N, idx) where N is the number of selected assets and idx is a permutation vector sorted descending by |w|.

Details

When N_opt is nothing, N_eff = number_effective_assets(w).
When 0 < N_eff ≤ 1, N_eff is treated as a concentration threshold: N is the smallest index such that the cumulative normalised absolute weight covers at least 1 - N_eff of the total; falls back to M if no such index exists.
Otherwise N_eff is treated as a count: N = clamp(ceil(Int, N_eff), 1, M).

Related

number_effective_assets

source