Capability catalogue

This page lists what PortfolioOptimisers.jl can do, grouped by the job that each type or function does. Each entry links to its docstring, on a public API page, or on a private API page for a name outside the public API.

The documentation build writes this page with docs/generatecapabilitycatalogue.jl. The grouping comes from docs/capability_catalogue.jl. The description of an entry is the first sentence of its docstring, unless the catalogue gives the entry its own label. The build fails when a type that you can choose, such as an estimator or an algorithm, has no entry here.

The type hierarchy lists the same types by their supertypes.

Core abstractions

Every component of the library is one of three kinds. An estimator is a configuration, which names a method and holds its hyperparameters. An algorithm selects a behaviour, and you pass it to an estimator. A result holds what a computation returns. You choose the estimators and the algorithms, and you get the results back.

Every estimator, algorithm and result is immutable, so the library passes a value it computes at run time down a composed estimator by rebuilding that estimator.

• No-op factory function for constructing objects with a uniform interface. factory

Preprocessing

• Compute returns from the price carrier. prices_to_returns and ReturnsResult
• Holds asset prices with optional factor, benchmark and implied volatility series, each a TimeSeries.TimeArray. PricesResult

• Cut price or returns data into a training window of the first rows and a test window of the last rows. train_test_split, TrainTestSplit, and TrainTestSplitResult
• Return a ReturnsResult appropriate for benchmark-tracking optimisations. returns_result_picker

Matrix processing

• Projects a matrix to the nearest positive definite matrix, typically used for co-moment matrices. Posdef, posdef!, and posdef

• Removes the largest n principal components (market modes) from a covariance or correlation matrix. Detone, detone!, and detone
• Configures and applies matrix processing routines. MatrixProcessing, matrix_processing!, matrix_processing_step!, and matrix_processing

Regression models

A factor prior that regresses on a series of factor returns fits it with regression, which returns a Regression. ImpliedVolatilityRegression does not call it: it fits one of the regression targets below to each asset and predicts its realised volatility.

Regression targets

• Fits each response by ordinary least squares through GLM.LinearModel. LinearModel
• Fits each response by a generalised linear model through GLM.GeneralizedLinearModel. GeneralisedLinearModel

Regression types

Cross-sectional regression types

A cross-sectional regression fits one model per observation, across the assets. cross_sectional_regression runs it and returns a CrossSectionalRegression. cross_sectional_r2 and mean_cross_sectional_r2 score a fit.

• Fits one external regression model per observation across the assets. CrossSectionalTargetRegression

Cross-sectional regression weight policies

A weight policy sets the weight of each asset in the cross-sectional fit at one observation. A one-pass policy reads the cross-section alone. A two-pass policy also reads the residuals of a first fit.

• Weights an asset by a power of its market capitalisation, in one pass. MarketCapWeights
• Blends market capitalisation weights with inverse idiosyncratic variance weights, in two passes. BlendedInverseVarianceWeights

Cross-sectional regression diagnostics

A diagnostic of the cross-sectional fit reads the exposure history, the factor returns and the residuals. It returns a series over the observations or one value per factor. You can pass the histories as bare arrays, already aligned for the lag. Every function except cs_gram also takes a CrossSectionalFactorModel. From the model, it lags the exposures and applies the factor family basis itself. The section on the factor family basis below says what that basis does.

Cross-sectional exposure diagnostics

A diagnostic of the exposure history reads the exposures as the AssetPanel holds them, with no lag and with one column per named factor. It returns a matrix over the factors, a series over the observations, or one value per factor. The input is bare arrays or a CrossSectionalFactorModel. With a model, the correlation, stability, dispersion and coverage functions derive the cross-sectional weights from an AbstractOrthogonalityMetric. The information coefficient uses the weights of the regression, and its reduced keyword maps the exposures through the factor family basis.

Cross-sectional idiosyncratic diagnostics

A diagnostic of the idiosyncratic returns divides each residual of the fit by the volatility the fit predicted for it. It then reads the cross-section of those ratios one observation at a time. Each function takes the residuals and the predicted volatilities as two bare arrays. A CrossSectionalFactorModel holds both histories, and every function except standardised_idio_returns also accepts one. Neither history has one column per factor, so this group applies no lag and no factor family basis.

Factor model summary

The summary puts the diagnostics above into one table, with one row per named factor, before the factor family basis drops any. For each column it calls one function of the regression group or of the exposure group, and it aggregates the series over the observations. If the model holds no exposure history, every column that reads the exposures is nothing.

Descriptors

A descriptor is a value per asset and observation that is computed from the panel fields of an AssetPanel, such as a momentum or a book-to-price ratio. descriptor computes it from a descriptor estimator. Each named descriptor below is a constructor function for one of the general estimators. It fixes the panel fields, the window or the half-life, and a keyword overrides each value it fixes.

• Returns one numeric Panel Field unchanged, as a Descriptor. Passthrough

• Ratio of a Panel Field to the exponentially weighted mean of a second one, at every observation. DaysToCover

• Exponentially weighted sensitivity of the returns to a reference series, after the market is removed. EWMacroSensitivity
• Exponentially weighted sensitivity of the returns to the falls of the market, at every observation. EWDownsideBeta

Factor exposures

A factor exposure is the loading of one asset on one factor at one observation. factor_exposure computes it from an exposure estimator, which takes descriptors, one categorical panel field, the exposure of another factor, or only the active mask of the AssetPanel. An estimator for one factor returns an observations by assets matrix. The one-hot estimator returns one factor per level of its panel field.

• A Factor Exposure that is a fixed weighted combination of Descriptors. CompositeExposure
• A Factor Exposure derived from the Factor Exposure of another factor. DerivedExposure
• A Factor Exposure that expands one categorical Panel Field into one factor per level. OneHotExposure
• A Factor Exposure equal to one for every asset at every observation. ConstantExposure

Factor family basis

A factor family is a set of one-hot factors, such as the sectors, whose exposures are collinear with a global factor. One member of each family is therefore redundant, and the fit changes the basis before it runs. factor_family_basis drops one member of each family and returns the change of basis, which varies over time. After the fit, the factor returns of the smaller basis expand back to one return per named factor.

• Compact change of basis between the raw factor axis and the reduced axis a re-based Factor Family is fitted in. FactorFamilyBasis and factor_family_basis

Return forecasts

A return forecast is a prediction of the idiosyncratic return of each asset over the next period. return_forecast computes one from a return forecast estimator, which reads the descriptor scores and a fitted factor model, or takes a vector you state. Every fitted estimator starts from descriptor_scores. It winsorises and standardises each descriptor, can neutralise it against named factor exposures, and standardises it again. The forecast unit says what the descriptors forecast, the idiosyncratic return or the idiosyncratic Sharpe ratio. The estimator converts either one to a return.

• The shared recipe that turns Descriptors into cross-sectional scores. DescriptorScores and descriptor_scores
• A Return Forecast that the caller states. CustomValueReturnForecast
• A Return Forecast that is a fixed signed combination of Descriptor scores. FixedWeightedReturnForecast
• A Return Forecast that fits its Descriptor weights by exponentially weighted least squares. ExpWeightedReturnForecast
• A Return Forecast fitted by a regression target over every observation and asset at once. TargetReturnForecast
• The Descriptors forecast the idiosyncratic return itself. IdiosyncraticReturnUnit
• The Descriptors forecast the idiosyncratic return divided by the idiosyncratic volatility. IdiosyncraticSharpeUnit

Forecast evaluation

forecast_evaluation pairs each return forecast with the return it forecast, out of sample, and returns one result. Every statistic below is a function of that result. It accepts bare matrices as well as a fitted return forecast, so it scores a forecast from outside the library in the same way as one the library made.

Moment estimation

Expected returns

Overloads Statistics.mean.

• Computes the expected returns as the sample mean of the asset returns. SimpleExpectedReturns
• Computes the expected excess returns that a set of equilibrium weights implies, by reverse optimisation. EquilibriumExpectedReturns
• Subtracts a risk-free rate from the expected returns that a nested estimator computes. ExcessExpectedReturns

• Expected returns estimator that returns the asset standard deviations. StandardDeviationExpectedReturns
• Expected returns estimator that returns the asset variances. VarianceExpectedReturns
• Computes the expected returns as the per-asset median of the asset returns. MedianExpectedReturns
• Returns a caller-supplied value for each asset instead of estimating one from the data. CustomValueExpectedReturns
• Expected returns estimator that restricts computation to a rolling or indexed observation window. WindowedExpectedReturns
• Estimates expected returns by an exponentially weighted recursion that freezes on a holiday and resets on an inactive period. ExpWeightedExpectedReturns

• Reads the mean of a Prior as an expected-returns vector, so that any me slot can hold a prior estimator. PriorExpectedReturns

Variance and standard deviation

Overloads Statistics.var and Statistics.std.

• Computes the marginal variance and standard deviation, optionally weighted and optionally bias-corrected. SimpleVariance
• Variance estimator that restricts computation to a rolling or indexed observation window. WindowedVariance

Covariance and correlation

Overloads Statistics.cov and Statistics.cor.

• Adapts any StatsBase.CovarianceEstimator to the library's calling convention, carrying its observation weights alongside it. GeneralCovariance

• Measures linear and non-linear codependence from doubly-centred pairwise distance matrices. DistanceCovariance
• Measures co-movement in the lower tail: the share of an asset's worst returns that fall on the same dates as another's. LowerTailDependenceCovariance

• Estimates the covariance of a short window as a rank-one matrix along the principal direction of its price relatives. RankOneCovariance

• Convenience constructor. DenoiseCovariance
• Convenience constructor. DetoneCovariance

• Convenience constructor. ProcessedCovariance

• Runs any covariance estimator, then applies a matrix post-processing step to its result. PortfolioOptimisersCovariance
• Answers both cov and cor with the wrapped estimator's correlation matrix. CorrelationCovariance
• Covariance estimator that restricts computation to a rolling or indexed observation window. WindowedCovariance

Coskewness

Implements coskewness.

• Coskewness estimator that restricts computation to a rolling or indexed observation window. WindowedCoskewness

Cokurtosis

Implements cokurtosis.

• Cokurtosis estimator that restricts computation to a rolling or indexed observation window. WindowedCokurtosis

Windowed moments

Every windowed estimator wraps a base moment estimator and recomputes it over a subset of the observations. An integer window selects the last window observations, a vector selects the observations at those indices, and the default nothing selects them all.

Incremental fit

Some statistics have an exact update, in which the new value follows from a running state and one new observation. An estimator of such a statistic folds each new observation into its state, and it returns the statistic from the state without reading the sample again. The state is in the estimator's cache field. The sample mean, the sample variance and the full-moment sample covariance have an exact update. So do the FullMoment forms of Coskewness and Cokurtosis. The SemiMoment forms do not, because they clip each observation against a centre, and a new observation moves the centre.

Two functions fold an observation into the state. Each family of estimators implements partial_fit! as its fastest exact update, and the call can change the estimator you pass in. partial_fit returns a new estimator and leaves the one you pass in unchanged.

• Folds observations into an estimator's partial-fit state, and returns the estimator. partial_fit!
• Folds observations into a copy of an estimator's partial-fit state, and returns the estimator that carries the copy. partial_fit

An estimator of a statistic with no exact update keeps the observations it has seen instead, and it runs the batch computation over them to return the statistic. Online gives the estimator that store of observations. It applies once, at the warm-up before the first fold, and no Online wrapper remains in the estimator after that. Its max_history sets the largest number of observations the store keeps, and so the window of the fit. A wrapped estimator returns the batch statistic over the last max_history observations, and the scenario risk measures such as the conditional value at risk use the same rows. The store replaces the exact update of a statistic that has one, so the cap applies to it too. An estimator you leave unwrapped uses its exact update and stays fitted over every observation so far.

• Declares that an estimator takes the online step from a buffer of the observations it has seen. Online

Coverage policy

By default, a moment estimator fits on the assets whose return is finite, and which the active mask of the AssetPanel marks as listed, at every observation of its window. This set of assets is the coverage universe. The rule keeps or drops each asset whole, so over an expanding window it can never admit an asset that lists after the first observation. A CoveragePolicy in the estimator's cvg field replaces the rule with available-case estimation, for that estimator alone. The estimator fits each entry of the result on the observations at which every asset of that entry is finite and active, and each entry has its own number of observations. An asset enters the result where its share of observations reaches min_coverage. The cvg field is nothing by default, and the estimator then fits on the coverage universe and writes NaN for every other asset.

The policy's alg field says what happens to an asset after it is delisted, with one type per rule. If your rule is none of the three below, write a new subtype of the family and implement its two functions, fold_inactive! and admits.

Distance matrices

Implements distance and cor_and_dist.

• Pairs a distance algorithm with an optional integer power, and applies it to a correlation matrix or to the data. Distance
• Measures how differently two assets relate to the whole universe, by applying a metric to a distance matrix. DistanceDistance

Each distance estimator takes one of the distance matrix algorithms below.

• Turns a signed correlation into a distance by $\sqrt{(1 - \rho) / 2}$. SimpleDistance
• Turns the magnitude of a correlation into a distance by $\sqrt{1 - \lvert\rho\rvert}$. SimpleAbsoluteDistance
• Turns the magnitude of a correlation into an unbounded distance by $-\log\lvert\rho\rvert$. LogDistance
• Turns a non-negative codependence into a distance by $\sqrt{1 - \rho}$, without halving. CorrelationDistance

• Selects the distance algorithm that matches the covariance estimator it is given. CanonicalDistance

Feature distances

A feature matrix describes the assets by their exposures, memberships, loadings or adjacencies, not by their returns. A feature distance turns it into a distance matrix directly, with no correlation matrix between the two.

Similarity matrices

A similarity matrix algorithm turns a distance matrix into a similarity matrix and reads nothing else. distance_to_similarity applies it. FeatureDistance picks one from its metric through default_similarity. The triangulated maximally filtered graph (TMFG) that DBHT and LoGo use takes its own.

The TMFG cannot take a negative weight. It therefore accepts only an AbstractNonNegativeSimilarityMatrixAlgorithm, and it throws an error at construction for AngularSimilarity. Two of the algorithms it accepts need a condition on the distance matrix, which assert_similarity_domain checks. ComplementSimilarity needs D <= 1, and MaximumDistanceSimilarity needs a finite D.

• Takes the linear complement $1 - D$, the exact counterpart of a metric that is itself one minus a similarity. ComplementSimilarity
• Recovers a correlation from a normalised angular distance by $\cos(\pi D)$. AngularSimilarity
• Subtracts the squared distance from a ceiling placed above the largest squared distance. MaximumDistanceSimilarity
• Maps a distance of any magnitude into $(0,\,1]$ by $e^{-D}$. ExponentialSimilarity
• Applies $e^{-c D^{p}}$, adding a scale and an exponent to the exponential transformation. GeneralExponentialSimilarity

Phylogeny

PortfolioOptimisers.jl uses the relationships between assets in three ways. They drive the clustering optimisers, they constrain the weights, and they measure how related the assets of a portfolio are.

Clustering

Phylogeny constraints and the clustering optimisers cluster the assets through ClustersEstimator, Clusters and clusterise. Most of the clustering algorithms come from Clustering.jl.

• Get the vector of cluster indices for each point. assignments

Hierarchical

• Builds a dendrogram by merging the two nearest clusters until one remains. HClustAlgorithm

Non-hierarchical

The hierarchical clustering optimisers cannot use a non-hierarchical clustering algorithm. Phylogeny constraints and NestedClustered can.

• Partitions assets into k groups by Lloyd's algorithm, with no dendrogram. KMeansAlgorithm

Networks

Adjacency matrices

An adjacency matrix records which assets are related, from a clustering or from a graph. phylogeny_matrix computes it, and a PhylogenyResult holds it.

• Turns a return matrix into a clustering of the asset universe. ClustersEstimator and Clusters
• Clusters assets by the pseudo-distances that a network's structure induces. NetworkClustersEstimator
• Group assets by clustering them, and keep the best-scoring member of each cluster. ClusterGroups

Centrality and phylogeny measures

• Fallback no-op for returning a validated centrality vector result as-is. centrality_vector
• Compute the weighted average centrality for a network and centrality algorithm. average_centrality
• Compute the asset phylogeny score for a set of weights and a phylogeny matrix. asset_phylogeny

Cluster trees

Hierarchical clustering makes a tree of ClusterNodes. to_tree builds the tree, and pre_order and is_leaf walk it.

• Collects each leaf's id, which for a leaf is its asset index. PreorderTreeByID

Optimisation constraints

The traditional optimisers, which build a JuMP problem, take the constraints below. The naive and clustering optimisers take weight bounds only. The entropy pooling priors take views, which are constraints on the posterior. You can state each constraint by hand, or derive its values from data with a type such as AbstractEstimatorValueAlgorithm or UniformValues.

You can state a constraint through its estimator, or directly as its result type. An estimator can name assets and groups of assets in key-value pairs. UniverseSets declares those assets and groups, and the library maps the names onto the assets with name_to_val! and replace_group_by_assets.

• Equation parsing parse_equation and ParsingResult
• Return an assembled LinearConstraint, nothing, or a vector of assembled constraints unchanged. linear_constraints, LinearConstraintEstimator, PartialLinearConstraint, and LinearConstraint

• No-op fallback for risk budget constraint generation. risk_budget_constraints, RiskBudgetEstimator, and RiskBudget
• Generate phylogeny-based portfolio constraints from an estimator or result. phylogeny_constraints, centrality_constraints, SemiDefinitePhylogenyEstimator, SemiDefinitePhylogeny, IntegerPhylogenyEstimator, IntegerPhylogeny, and CentralityConstraint
• Generate portfolio weight bounds constraints from a WeightBoundsEstimator and asset set. weight_bounds_constraints, WeightBoundsEstimator, and WeightBounds
• Declares the universes a portfolio problem is written against, and any groupings or partitions of them. UniverseSets

• Construct a binary asset-group membership matrix from asset set groupings. asset_sets_matrix and AssetSetsMatrixEstimator
• Propagate or pass through buy-in threshold portfolio constraints. threshold_constraints, ThresholdEstimator, and Threshold

Prior statistics

Many optimisations and constraints use prior statistics, which prior computes.

Uncertainty sets

An uncertainty set on the expected returns or on the covariance makes an optimisation less sensitive to noise and to errors in the estimates. Any optimisation that uses one of the two quantities accepts a set on it. ucs, mu_ucs and sigma_ucs build the sets.

The first two shapes of set are a box and an ellipsoid.

• Holds the element-wise lower and upper bounds of a box uncertainty set on a mean vector or on a covariance matrix. BoxUncertaintySet and BoxUncertaintySetAlgorithm

A third shape holds the worst-case variance of a covariance set as a quadratic penalty on the weights, so the optimisation stays a second-order cone programme and needs no semidefinite constraint.

• Holds a worst-case variance penalty as a radius, a diagonal metric square root and a basis of the directions the penalty spares. CompactCovarianceUncertaintySet

A fourth shape is the image of a norm ball under a geometry map of any rank, for the expected returns or for the covariance. A set that is flat in the directions a factor model does not span then needs no full-rank shape matrix. An ellipsoid you already built converts to it with one Cholesky factorisation.

• NormBallUncertaintySet and NormBallUncertaintySetAlgorithm, which take the same scaling algorithms as the ellipsoid and apply them to the geometry map through k_norm_ball

Several estimators build the sets. The next two build a box, an ellipsoid or a norm ball.

• Fits a box or an ellipsoidal uncertainty set from the sampling laws that normal returns imply: the mean is normal and the covariance is Wishart. NormalUncertaintySet

The next estimator builds a box only.

• Fits a box uncertainty set by widening the prior statistics by a fixed fraction of their own absolute value. DeltaUncertaintySet

The library states a quintile portfolio as an uncertainty set on the characteristic vector, not as an optimiser of its own.

One estimator reads no returns at all. It receives the fitted prior of its optimisation, and it limits both of its sets to the directions that the factor model of the prior does not span.

Turnover

The turnover is the absolute difference, asset by asset, between the current weights and a vector of benchmark weights. You can use it as a constraint, as the base of a fee, or as a risk measure. turnover_constraints, TurnoverEstimator and Turnover implement it.

Fees

Every optimisation except BudgetedHindsightPath can include fees, the naive ones too. A finite allocation takes them in its input, FiniteAllocationInput. calc_fees and calc_asset_fees compute the fees of a portfolio and of each asset, which you can subtract from the expected returns. The proportional and turnover rates apply in every period, and the two fixed amounts apply one time for the whole holding period. calc_total_fees and calc_total_asset_fees therefore give the cost over a horizon you state.

• Resolve the name-keyed fee fields of a FeesEstimator against a universe, giving a Fees of plain per-asset vectors. fees_constraints
• Compute the fixed portfolio fees for the assets the portfolio holds. calc_fixed_fees and calc_asset_fixed_fees
• Charge the whole cost of holding a portfolio for T periods. calc_total_fees and calc_total_asset_fees

• Spreads the one-off terms of a fee, the fixed charges fl, fs and flq, evenly over a holding period. AmortisedFees
• Charges the one-off terms of a fee, the fixed charges fl, fs and flq, on the first observation of a return series. FirstObservationFees

Portfolio returns and drawdowns

Many risk measures and analyses need the returns, the cumulative returns and the drawdowns of a portfolio, in total and per asset. calc_net_returns, calc_net_asset_returns, cumulative_returns and drawdowns compute them. calc_turnover computes the trading that a path of weights needs, which is the value of the quantity that Turnover bounds.

You can also score a window on the weights a fund holds, which move with the returns of their assets while no trade happens. The series is then the wealth ratio of those drifted holdings.

The realised series of a fold can also charge the two fixed fees on a schedule of its own. The scheme states that schedule in its fa field. It replaces the schedule of the fee itself, and it has no effect on the fit.

• Grows each position at its own asset return and holds no trade in between, so the weights drift and the series is the wealth ratio of the drifted holdings. SelfFinancingDrift

Tracking

A tracking constraint keeps a portfolio close to a benchmark, which can be an index, an indicator or another portfolio.

norm_error computes the error with one of the norms below.

The distance can also be a difference of risk, measured against a WeightsTracking benchmark, in place of a norm of the difference of returns. Two methods compute it.

Risk measures

The sections below group the risk measures by the optimisations that accept them.

The fields of a risk measure that come from the prior, mu, sigma, kt and sk, take either the value or the estimator that computes it, a DeferredQuantity. The optimisation evaluates the estimator on its own prior, so the value is refitted in each cross-validation fold and in each subset of a meta optimiser. A matrix you pass in stays the same. A measure with two or more such fields can instead name one prior estimator in pe, and one fit then fills every field you leave empty.

Calibration

A tail probability and a deformation parameter also take a rule in place of the number. The field fixes the quantity and the end of the distribution, so you write only the rule. The optimisation evaluates the rule on its own prior, as it does a deferred estimator. The type of each field accepts the one family of rules that computes its quantity. It takes a callable estimator of that family, a plain function of (key, pr, w, slv, ctx), or the number. Five rules ship. Two compute a significance level, and three compute a deformation parameter. Forty fields over twenty-seven risk measures and weight builders take a rule, and they are every alpha and beta and every kappa, kappa_a and kappa_b. The two inner integration bounds of the tail Gini family, alpha_i and beta_i, are starting points and not quantities to estimate. They keep their numbers, and each fold checks the bound 0 < alpha_i < alpha < 1 against the calibrated alpha.

A significance rule reads the length of the sample. Where the count it states is a count of observations, it reads the effective weights of the observations. A deformation rule reads the probability of its own end of the distribution, which it gets in the CalibrationContext that the owner of the field builds. One deformation rule spends a stated entropy budget on the length of the sample. The other two estimate the tail index of the sample and return its reciprocal. One of them standardises each column and returns a value per end, so a skewed sample gives two numbers. The other whitens each observation with the covariance matrix and returns one number for both ends.

A rule that reads the shape of a series needs to know which series. A drawdown measure is computed on the drawdown series of the portfolio, not on its returns, and the key of the field does not say which. The measure therefore states its series in the CalibrationContext, beside the significance level. The two tail rules then read the drawdown series of each column in place of the column itself. The pooled rule pools those series. The radial rule whitens their rows with the covariance matrix of the same drawdown series, because a prior result holds no moment of the drawdowns. If you run a rule by hand, build the context with a series, such as AbsoluteDrawdownSeries(), as the measure would.

• Computes a significance level from a count of observations, so that the tail keeps the same number of scenarios whatever the sample length becomes. ScenarioCount
• Computes a significance level that shrinks with the square root of the sample length. RateSignificance
• Computes the Kaniadakis deformation parameter that makes a relativistic measure spend a stated entropy budget. EntropyBudget
• Computes the Kaniadakis deformation parameter whose tail decays at the rate the sample's own tail decays at. HillTailDecay
• Computes the Kaniadakis deformation parameter whose tail decays at the rate the sample's radial series decays at. RadialTailDecay
• Names the returns themselves, the columns of pr.X unchanged. ReturnsSeries
• Names the absolute drawdown series of a column, which absolute_drawdown_vec builds. AbsoluteDrawdownSeries
• Names the relative drawdown series of a column, which relative_drawdown_vec builds. RelativeDrawdownSeries

An ambiguity radius also takes a rule. A radius applies to no end of the distribution, so one type bound serves every radius field. The fields are the four regularisation coefficients of JuMPOptimiser and the radii of the distributionally robust risk measures. Four rules ship, and all four compute a radius. Two shrink the ball at the rate of the square root of the sample length. The third shrinks it at a rate that the number of assets sets, which is much slower over a wide universe.

• Computes an ambiguity radius from the concentration of measure, so that the ball shrinks as the sample grows. ConcentrationRadius
• Computes an ambiguity radius that shrinks with the square root of the sample length. RateRadius
• Computes an ambiguity radius that shrinks at the dimensional rate a Wasserstein ball earns, not at the square-root rate. DimensionalRateRadius

Those three return the same number for every field, but the eight radius fields do not all measure distance in one norm. The fourth rule reads the key of the field, picks the ground metric that the field names, and returns the sampling error of the empirical measure in that metric. As a result, the l1 and linf coefficients of one optimiser get two different values.

• Computes an ambiguity radius in the ground metric that the slot it stands in names, so that two slots of two different norms get two different numbers. DualNormRadius

The tail weight of an Esfahani-Kuhn loss has a family of its own. One rule ships for it, and it sets the tail term of the loss to a stated multiple of its mean term. A tail weight you state has no unit, but its effect depends on the scale of the sample, so one number gives a different trade-off at each sampling frequency. The rule reads the probability of its own field, which it gets in the same context.

• Computes the Esfahani-Kuhn tail weight that prices the tail term of the loss at a stated multiple of its mean term. TailTermParity

A norm ceiling is a different quantity from a radius and has a family of its own. Neither family is accepted in the field of the other. A radius is the coefficient of a norm penalty in the objective. A ceiling bounds that norm in a constraint. The bound sets a floor on the effective number of assets. The three norm-constraint fields of JuMPOptimiser, l2c, lpc and linfc, take one. One rule ships. It keeps a stated fraction of the assets effective, so the floor changes with the assets of the prior. The order of the norm belongs to the constraint and not to the rule, so each constraint gives the rule its own order before the field is evaluated.

• Computes a norm ceiling that holds a stated fraction of the universe effective, so that the floor refits whenever the universe changes. EffectiveAssetFloor

Risk measures for traditional optimisation

Each is a subtype of RiskMeasure. Every JuMP optimisation estimator that takes a risk measure accepts it, and so do hierarchical risk parity and hierarchical equal risk contribution.

• Measures the portfolio standard deviation, the square root of the variance. StandardDeviation
• Uncertainty set variance UncertaintySetVariance, which is the variance outside traditional optimisation

• Composite risk measure combining variance, skewness, and kurtosis into a single expression. VarianceSkewKurtosis

• Measures the Drawdown-at-Risk (DaR), the uncompounded drawdown that the portfolio exceeds with probability alpha. DrawdownatRisk
• Measures the Conditional Value-at-Risk (CVaR), the average loss over the worst alpha fraction of the portfolio returns. ConditionalValueatRisk
• Distributionally Robust Conditional Value at Risk DistributionallyRobustConditionalValueatRisk, which is the conditional value at risk outside traditional optimisation
• Measures the spread between the two tails of the portfolio returns, the CVaR of the losses plus the CVaR of the gains. ConditionalValueatRiskRange
• Distributionally Robust Conditional Value at Risk Range DistributionallyRobustConditionalValueatRiskRange, which is the conditional value at risk range outside traditional optimisation
• Measures the Conditional Drawdown-at-Risk (CDaR), the average of the worst alpha fraction of the uncompounded drawdowns. ConditionalDrawdownatRisk
• Distributionally Robust Conditional Drawdown at Risk DistributionallyRobustConditionalDrawdownatRisk, which is the conditional drawdown at risk outside traditional optimisation
• Represents the Entropic Value-at-Risk (EVaR) risk measure. EntropicValueatRisk
• Represents the Entropic Value-at-Risk Range (EVaR Range) risk measure. EntropicValueatRiskRange
• Represents the Entropic Drawdown-at-Risk (EDaR) risk measure. EntropicDrawdownatRisk
• Measures the Relativistic Value-at-Risk (RLVaR), the worst expected loss over a Kaniadakis entropy ball about the sample distribution. RelativisticValueatRisk
• Measures the spread of the returns as the sum of the Relativistic Value-at-Risk of the losses and that of the gains. RelativisticValueatRiskRange
• Measures the Relativistic Drawdown-at-Risk (RLDaR), the Relativistic Value-at-Risk of the absolute drawdown series of the portfolio. RelativisticDrawdownatRisk

• Represents the Average Drawdown risk measure. AverageDrawdown
• Represents the Ulcer Index risk measure. UlcerIndex
• Represents the Maximum Drawdown risk measure. MaximumDrawdown

• Represents the Worst Realisation risk measure. WorstRealisation
• Represents the Range risk measure. Range
• Represents the Turnover risk measure. TurnoverRiskMeasure

• Represents the Power Norm Value-at-Risk (PNVaR) risk measure. PowerNormValueatRisk
• Represents the Power Norm Value-at-Risk Range (PNVaRRange) risk measure. PowerNormValueatRiskRange
• Represents the Power Norm Drawdown-at-Risk (PNDaR) risk measure. PowerNormDrawdownatRisk
• Represents a generic Value-at-Risk range risk measure that combines any pair of XatRisk-type measures applied to the loss and gain sides of the return distribution. GenericValueatRiskRange
• Measures how far the risk of a portfolio is from the risk of a benchmark portfolio, under any risk measure. RiskTrackingRiskMeasure
• Risk measure that contributes no risk. NoRisk

Risk measures for hierarchical optimisation

Each is a subtype of HierarchicalRiskMeasure, and only the hierarchical optimisation estimators accept it.

• Measures the Relative Drawdown-at-Risk, the compounded drawdown that the portfolio exceeds with probability alpha. RelativeDrawdownatRisk
• Measures the Relative Conditional Drawdown-at-Risk, the average of the worst alpha fraction of the compounded drawdowns. RelativeConditionalDrawdownatRisk
• Represents the Relative Entropic Drawdown-at-Risk (Relative EDaR) risk measure for hierarchical optimisation. RelativeEntropicDrawdownatRisk
• Measures the Relative Relativistic Drawdown-at-Risk, the Relativistic Value-at-Risk of the compounded drawdown series, for hierarchical optimisation. RelativeRelativisticDrawdownatRisk
• Represents the Relative Average Drawdown risk measure for hierarchical optimisation. RelativeAverageDrawdown
• Represents the Relative Ulcer Index risk measure for hierarchical optimisation. RelativeUlcerIndex
• Represents the Relative Maximum Drawdown risk measure for hierarchical optimisation. RelativeMaximumDrawdown
• Represents the Relative Power Norm Drawdown-at-Risk (Relative PNDaR) risk measure for hierarchical optimisation. RelativePowerNormDrawdownatRisk
• Represents a risk ratio risk measure for hierarchical portfolio optimisation. RiskRatio
• Represents the Equal Risk Measure for hierarchical portfolio optimisation. EqualRisk
• Represents the Median Absolute Deviation (MAD) risk measure for hierarchical portfolio optimisation. MedianAbsoluteDeviation

Non-optimisation risk measures

These risk measures can return a negative value, so no optimisation accepts them on their own. You can use them as performance metrics. Skewness enters an optimisation only as the skewness term of VarianceSkewKurtosis.

• Represents a simple mean return measure for use in non-optimisation contexts. MeanReturn
• Represents the Third Central Moment risk measure. ThirdCentralMoment
• Represents the standardised Skewness risk measure. Skewness
• Return-based risk measure. ExpectedReturn
• Ratio-based risk measure. ExpectedReturnRiskRatio
• Represents a mean return to risk ratio measure. MeanReturnRiskRatio
• Represents a non-optimisation risk ratio measure. NonOptimisationRiskRatio

Performance metrics

Every function here that takes a risk measure also takes a vector of them. The sca keyword takes a Scalariser, which combines the vector into one number. All four scalarisers work here, MinScalariser included, because these functions combine numbers and build no model expression. A function that also reads a return takes one return term or a vector of them, and sums them at the weights of the terms. No scalariser applies to the returns. A result holds the risk measure and the scalariser of its optimisation, so expected_risk(res.r, res.w, res.pr; sca = res.sca) gives the optimised value and you name neither one.

• Compute the expected value of a risk measure. expected_risk
• Compute the effective number of assets of a portfolio, the inverse of the Herfindahl-Hirschman index of its weights. number_effective_assets

• Compute the expected risk of a measure from a precomputed net-return series. expected_risk_from_returns
• Compute the risk of a portfolio over each rolling window of the returns matrix, at constant weights. rolling_window_measure
• Sort the successful paths in a PopulationPredictionResult by their expected risk under r. sort_by_measure
• Compute the expected risk-adjusted return ratio for a portfolio. expected_ratio and expected_risk_ret_ratio
• Compute the risk-adjusted ratio information criterion (SRIC) for a portfolio. expected_sric and expected_risk_ret_sric
• Compute Brinson performance attribution aggregated per asset class [3]. brinson_attribution
• Summarise a realised return series as a PerformanceSummaryResult. performance_summary and PerformanceSummaryResult

Portfolio optimisation

optimise runs an optimisation. It takes an optimisation estimator and returns a result.

Naive

These return a NaiveOptimisationResult.

• Allocates each asset a weight inversely proportional to its volatility, or to its variance when sq = true. InverseVolatility
• Allocates the same weight to every asset of the Coverage Universe of the window. EqualWeighted
• Draws portfolio weights at random from a Dirichlet distribution with concentration alpha. RandomWeighted
• Holds the weights it was handed, and solves nothing. PreviousWeights
• The best constant rebalanced portfolio in hindsight, from Cover's fixed point with no solver, BestConstantRebalancedPortfolio. For the exact portfolio, or for one with bounds, use MeanRisk with LogarithmicReturn and MaximumReturn

Naive optimisation features

• Resolves weight bounds written in asset or group names against a universe. WeightBoundsEstimator, UniformValues, and WeightBounds

Online portfolio selection

Online portfolio selection updates the weights after each new price relative, which is the price of each asset divided by its price one period before. Most of its rules need no solver. You choose a rule and hold it in OnlinePortfolioSelection. A batch fit runs the rule over every row of the window in order, from the start weights, and returns the weights for the next period. An online fit returns the weights the rule reached after its last update.

• Updates its allocation from each realised price relative through the Online Selection Rule on alg. OnlinePortfolioSelection

Traditional

These optimisations build a JuMP problem through JuMPOptimiser, which holds every constraint they support.

Objective function optimisations

These optimisations take one of the objective functions below.

• Configures one solver backend, its attributes, and the statuses its solutions must reach. Solver
• Main JuMP-based portfolio optimiser configuration. JuMPOptimiser

Risk budgeting optimisations

These optimisations find the weights at which each asset, or each factor, contributes the share of risk that a risk budget vector states.

Traditional optimisation features

• Abstract supertype for a term that the user adds to the objective of the JuMP model. CustomJuMPObjective
• Abstract supertype for a constraint that the user writes into the JuMP model. CustomJuMPConstraint
• Resolves weight bounds written in asset or group names against a universe. WeightBoundsEstimator, UniformValues, and WeightBounds

• Holds the linear constraint equations to parse, and the universe key their names resolve against. LinearConstraintEstimator and LinearConstraint
• Bundles a network source with the centrality algorithm that scores its assets. CentralityEstimator

• Names the per-asset turnover bounds, for turnover_constraints to align to a universe. TurnoverEstimator and Turnover
• Names the per-asset fee rates, for fees_constraints to align to a universe. FeesEstimator and Fees
• Bounds how far the portfolio return series may drift from a benchmark return series. TrackingError
• Caps how many related assets may be held at once, refitting the structure from returns. IntegerPhylogenyEstimator and SemiDefinitePhylogenyEstimator

• Custom constraint
• Number of effective assets

• Estimator type for normalised constant relative risk aversion (CRRA) OWA weights. NormalisedConstantRelativeRiskAversion

Clustering optimisation

Clustering optimisations split the assets into clusters from their relationships, and optimise the clusters in a hierarchy or one at a time.

• Holds the prior, the clustering, the bounds and the fees that a hierarchical optimiser shares with its siblings. HierarchicalOptimiser

Hierarchical clustering optimisation

These optimisations split the assets into a hierarchy of clusters, compute the risk of each cluster, and combine the clusters by the hierarchy.

Each result holds the risk measures and the scalarisers of its optimisation, after the optimisation resolved them. It holds its other fields in an embedded HierarchicalResult, which you reach as res.hr, or one field at a time as res.w, res.pr and so on.

• Hierarchical Risk Parity HierarchicalRiskParity returns a HierarchicalRiskParityResult
• Hierarchical Equal Risk Contribution HierarchicalEqualRiskContribution returns a HierarchicalEqualRiskContributionResult
• Holds the fields that the results of hierarchical risk parity and hierarchical equal risk contribution share. HierarchicalResult

Hierarchical clustering optimisation features

• Resolves weight bounds written in asset or group names against a universe. WeightBoundsEstimator, UniformValues, and WeightBounds
• Names the per-asset fee rates, for fees_constraints to align to a universe. FeesEstimator and Fees

Schur complementary optimisation

Schur complementary hierarchical risk parity interpolates between hierarchical risk parity and mean-variance optimisation through one parameter, gamma. At gamma = 0 it is hierarchical risk parity, and a larger gamma moves it towards mean variance. It adjusts the weights of each group of assets with the Schur complement of the covariance matrix, which puts back the covariance between the groups that hierarchical risk parity ignores.

• Schur Complementary Hierarchical Risk Parity SchurComplementHierarchicalRiskParity returns a SchurComplementHierarchicalRiskParityResult

Schur complementary optimisation features

• Resolves weight bounds written in asset or group names against a universe. WeightBoundsEstimator, UniformValues, and WeightBounds
• Names the per-asset fee rates, for fees_constraints to align to a universe. FeesEstimator and Fees

Nested clusters optimisation

Nested clustered optimisation splits the N assets into C clusters and optimises each cluster as a portfolio of its own. The inner weights go into an N × C matrix. Each column is one cluster, and it holds the weights of one synthetic asset. An asset has a non-zero weight only in the column of its own cluster. Each row of the matrix then holds one non-zero value, and each column holds as many non-zero values as its cluster has assets.

There are two ways to get the returns of the synthetic assets:

1. Multiply the T × N matrix of asset returns by the N × C matrix of weights. The product is a T × C matrix of returns, where T is the number of observations.
2. Run a cross-validation prediction for each cluster, which gives one vector of returns per cluster. Put the vectors side by side in a Y × C matrix, where Y ≤ T because the cross-validation can leave out part of the history.

The outer estimator optimises the synthetic assets on that matrix of returns, which gives a C × 1 vector of weights, one per cluster. The weights of the assets are the product of the N × C matrix and that C × 1 vector, an N × 1 vector.

• Nested Clustered NestedClustered returns a NestedClusteredResult

Nested clusters optimisation features

• Any features supported by the inner and outer estimators.
• Resolves weight bounds written in asset or group names against a universe. WeightBoundsEstimator, UniformValues, and WeightBounds
• Names the per-asset fee rates, for fees_constraints to align to a universe. FeesEstimator and Fees

• Cross validation predictor for the outer estimator

Ensemble optimisation

Stacking works like nested clustered optimisation, but it does not split the assets. You give it a list of inner estimators, and each one optimises every asset. Each column of the N × C matrix then holds the weights of one inner estimator, so the matrix has no fixed pattern of zeros. The rest of the procedure is the same.

• Stacking Stacking returns a StackingResult

Ensemble optimisation features

• Any features supported by the inner and outer estimators.
• Names the per-asset fee rates, for fees_constraints to align to a universe. FeesEstimator and Fees
• Resolves weight bounds written in asset or group names against a universe. WeightBoundsEstimator, UniformValues, and WeightBounds

• Cross validation predictor for the outer estimator

Subset resampling optimisation

Subset resampling draws random subsets of the assets, as MultipleRandomised cross-validation does, and optimises each subset with the optimiser you give it. The weight of each asset is its mean weight over all subsets, with a weight of zero in each subset that does not hold it.

• SubsetResampling returns a SubsetResamplingResult

Subset resampling optimisation features

• Any features supported by the inner estimator.
• Names the per-asset fee rates, for fees_constraints to align to a universe. FeesEstimator and Fees
• Resolves weight bounds written in asset or group names against a universe. WeightBoundsEstimator, UniformValues, and WeightBounds

Finite allocation optimisation

A finite allocation turns the weights of another optimisation into whole numbers of shares, at the latest prices, with a stated amount of cash. Its answer is the allocation closest to those weights that the cash can buy, not an optimum of its own.

• Greedy Allocation portfolio optimiser. GreedyAllocation

Cross validation

• Prediction on data the fit did not see, PredictionReturnsResult, PredictionResult, MultiPeriodPredictionResult and PopulationPredictionResult, through predict(res::NonFiniteAllocationOptimisationResult, rd::ReturnsResult) and fit_and_predict
• Union of the values that the scorer field of OptimisationCrossValidation accepts: a PredictionScorer or a plain function. PredictionCrossValScorer, NearestQuantilePrediction, and quantile_by_measure
• Run cross-validated portfolio optimisation and return predictions over all folds. cross_val_predict
• Fit optimisation estimator opt on returns data rd, and predict over the same data. fit_predict
• Return the number of cross-validation splits (folds) that would be produced by cv for the given returns data rd. n_splits
• Find the optimal (n_folds, n_test_folds) pair for combinatorial cross-validation by minimising a weighted cost that balances the average training size against the number of test paths. optimal_number_folds

A scheme scores each fold under an evaluation convention. SelfFinancingDrift scores the series of a fold on the weights the fund holds, not on the weights the optimiser chose, and the fold then holds a HeldWeightsResult. A walk-forward can also pass those held weights to the next fold.

• Thread the weights a fold held after its last observation into the fold that follows it. DriftedWeights
• Records what a fold actually held, so a reader can recover the weight path of that fold. HeldWeightsResult

• Wraps a cross-validation scheme and an optional scorer to form a complete optimisation cross-validation pipeline. OptimisationCrossValidation
• Abstract supertype for estimators that determine the number of random subsets to draw. NumberSubsetsEstimator and SubsetSizeEstimator
• Abstract supertype for estimators that determine the rolling window size. WindowSizeEstimator

Covariance forecast evaluation

covariance_forecast_evaluation scores the forecast of a covariance estimator, or of a prior, against the returns realised after it. It steps through a walk-forward. With a scheme that refits, each step refits the estimator, and with an online walk-forward, each step updates it. The evaluation centres the test rows on the location that the estimator forecasts, and it keeps the diagnostics of each step. The summary, the comparison and the re-projection are then functions of one result.

Log-wealth regret

log_wealth_regret reads two prediction results scored over the same rows. It returns the difference in log terminal wealth between a comparator and a strategy, the difference row by row, and a Newey-West test that the two have the same expected log growth. The comparator is any prediction result over the rows. It can be the same estimator run causally. It can also be a hindsight comparator, fit on the rows it is scored on and predicted in sample. Through a HindsightSplit the comparator changes from row to row, which gives the dynamic regret, and the result reports the path length of the comparator beside the regret. BudgetedHindsightPath is the best sequence of comparators whose path length stays within a budget. Its fit solves one programme over the whole panel, and its prediction result has one fold per row. Pass it as the comparator to read the regret at a given budget.

• The log-wealth regret of strategy a against comparator b over one and the same sequence of rows. log_wealth_regret and LogWealthRegretResult
• Fits the path of per-row allocations with the largest log wealth whose summed step length is at most L. BudgetedHindsightPath and BudgetedHindsightPathResult

Pipeline

A Pipeline holds a whole workflow as one estimator. It is an ordered list of steps that run from left to right over a PipelineContext. The preprocessing, the priors and the optimiser then form one estimator, which you can cross-validate or tune as a unit.

• A reified end-to-end portfolio workflow: an ordered list of steps executed left-to-right over a PipelineContext. Pipeline and PipelineResult
• Explicit pipeline step wrapper — used when a step's slots or its routing intent must be stated rather than inferred. PipelineStep
• The accumulating blackboard threaded through a pipeline's steps. PipelineContext
• The mu/sigma pair held by the uncertainty slot of a PipelineContext. PipelineUncertaintySets

Plotting

The plotting functions draw a portfolio, its history, its risk and the diagnostics of the models behind it. They are in a package extension, which loads when you load StatsPlots and GraphRecipes.

• Plot the dendrogram of a hierarchical clustering, with one shaded region per cluster. plot_dendrogram
• Plot the similarity matrix of a clustering as a heatmap in the order of the clustering, with a dendrogram on two sides and a box round each cluster. plot_clusters
• Plot the cumulative returns of a portfolio above its drawdown, in two panels that share the time axis. plot_drawdowns
• Plot the maximum drawdown of the portfolio over a rolling window, in percent, against the last date of each window. plot_rolling_drawdowns
• Plot the histogram of the returns of a portfolio, with a vertical line for each of several statistics and an optional fitted Normal density. plot_histogram
• Plot a scatter of two or three measures over a collection of portfolios, coloured by a fourth. plot_measures
• Plot a risk or return measure of the portfolio returns over a rolling window, against the last date of each window. plot_rolling_measure
• Plot a collection of portfolios as a line ordered by risk, coloured by a score, to trace an efficient frontier. plot_efficient_frontier
• Plot the distribution of the weight of each asset over the folds of a path or the members of a population, as one box per asset. plot_weight_stability
• Plot the turnover of a sequence of portfolios, the $L_1$ change of the weights from one portfolio to the next. plot_turnover
• Plot the cumulative returns of a portfolio beside those of one or more benchmarks. plot_benchmark