Factor risk contribution

PortfolioOptimisers.FactorRiskContributionResult — Type
struct FactorRiskContributionResult{__T_jr, __T_rr, __T_frc_plr, __T_fb} <: RiskJuMPOptimisationResult

Result of a FactorRiskContribution optimisation.

Fields

  • r: The risk measure the optimisation ran under, or a vector of them, stored resolved. Every Deferred Quantity in it is fitted, and every unstated slot holds the prior's field. A resolved measure is fitted state, not configuration, so it belongs on the Result. Pass it back as expected_risk(res.r, res.w, res.pr; sca = res.sca). The type of r is not a type parameter of the Result, so the Results of two risk measures have one type, and a verb that reads them compiles one time.
  • rr: Regression result.
  • frc_plr: Phylogeny constraints on the factor weights, resolved on the factor returns. nothing when the estimator holds none.
  • fb: The fallback chain that answered this result: the (estimator, result) pair of every attempt optimise made before this one, in the order they ran, or nothing when the estimator it was asked of answered (see FbChain).

A property that is not a field resolves in rr first, and then in jr. So res.L reads the loadings, and res.w reads the asset weights through the virtual :w of JuMPOptimisationResult.

Constructors

FactorRiskContributionResult(;    jr::JuMPOptimisationResult, r::BaseRM_VecBaseRM, rr::AbstractLoadingsRegressionResult,    frc_plr::Option{<:PlC_VecPlC}, fb::Option{<:OptE_Opt_FbChain}) -> FactorRiskContributionResult

Keywords correspond to the struct's fields.

Related

source
PortfolioOptimisers.FactorRiskContribution — Type
struct FactorRiskContribution{__T_opt, __T_re, __T_r, __T_obj, __T_frc_ple, __T_sets, __T_wi, __T_flag, __T_fb} <: RiskJuMPOptimisationEstimator

Solves a mean-risk problem whose decision variable is the vector of factor weights, not the vector of asset weights.

The asset weights are a linear map of the factor weights through the factor loadings, so a constraint on the decision variable is a constraint on a factor. FactorRiskContribution changes the basis and sets no risk budget of its own. A target contribution of a factor is a row of the rc constraints of the risk measure, as the target of an asset is.

Under Variance the rc rows sit on the semidefinite relaxation of Formulation 16 of [190], over the factor weights. With flag = true the lift covers the off-factor weights $\boldsymbol{w}_2$ too. The variance is then the variance of the returned weights, and each row states the Euler contribution of a factor as a share of the whole variance, as factor_risk_contribution reports it. set_risk_constraints! states the formulation. A solve can report success while the factor shares of the returned portfolio miss the rows, so compare factor_risk_contribution of the result with them. The ## Risk contribution constraints subsection of Variance states the relaxation and the condition under which the rows bind.

A Variance always takes this semidefinite formulation here, with or without rows. Under MaximumRatio the ratio_alg of the variance selects the degree of its objective term, and so the ratio. The default gives the Sharpe ratio, and LinearRatio gives the excess return per unit of variance. The # Mathematical definition of MaximumRatio states the rule, and set_sdp_frc_objective_lift! states the lift.

The optimiser solves its model once. A number in settings.ub of a risk measure logs a warning, and the model ignores the bound. A Frontier or a vector in settings.ub raises an ArgumentError, see set_risk_upper_bound!. A return term with a Frontier or a vector floor raises an ArgumentError, see assert_frontier_sweep_owner. MeanRisk sweeps a frontier.

Mathematical definition

The factor model of the loadings, which re fits or the prior carries:

\[\begin{align} \mathbf{R} &= \mathbf{F} \mathbf{B}^\intercal + \mathbf{E}\,. \end{align}\]

The asset weights are a linear map of the decision variables. The first form is the model when flag = false, and the second is the model when flag = true:

\[\begin{align} \boldsymbol{w} &= \mathbf{B}_1 \boldsymbol{w}_1\,, \\ \boldsymbol{w} &= \mathbf{B}_1 \boldsymbol{w}_1 + \mathbf{B}_2 \boldsymbol{w}_2\,, \\ \mathbf{B}_1 &= (\mathbf{B}^\intercal)^{+}\,. \end{align}\]

The columns of $\mathbf{B}_2$ are an orthonormal basis of the null space of $\mathbf{B}^\intercal$, so $\mathbf{B}^\intercal \mathbf{B}_2 = \mathbf{0}$. When $\mathbf{B}$ has full column rank, $\mathbf{B}^\intercal \mathbf{B}_1$ is the identity, and the factor exposures of the portfolio are $\mathbf{B}^\intercal \boldsymbol{w} = \boldsymbol{w}_1$. The first form keeps $\boldsymbol{w}$ in the column space of $\mathbf{B}$. The second form adds the directions that the loadings do not span, so $\boldsymbol{w}$ can be any vector of size $N$.

The problem is the mean-risk problem of MeanRisk over the decision variables:

\[\begin{align} \underset{\boldsymbol{w}_1,\, \boldsymbol{w}_2}{\min} \; f(\boldsymbol{w}) \quad \text{s.t.} \quad \boldsymbol{w} \in \mathcal{W}\,. \end{align}\]

The risk contribution of factor $j$, which factor_risk_contribution reports, is the Euler decomposition in this basis. The last entry is the contribution of the off-factor part, and the entries sum to $\boldsymbol{w}^\intercal \nabla R(\boldsymbol{w})$, which is $R(\boldsymbol{w})$ for a risk measure that is homogeneous of degree one:

\[\begin{align} RC_j &= \left[ \mathbf{B}^\intercal \boldsymbol{w} \right]_j \left[ \mathbf{B}_1^\intercal \nabla R(\boldsymbol{w}) \right]_j\,, \quad j = 1, \ldots, N_f\,, \\ RC_{N_f + 1} &= \left( \mathbf{B}_2^\intercal \boldsymbol{w} \right)^\intercal \mathbf{B}_2^\intercal \nabla R(\boldsymbol{w})\,. \end{align}\]

Where:

  • $\mathbf{R}$: Asset returns matrix, $T \times N$.
  • $\mathbf{F}$: Factor returns matrix, $T \times N_f$.
  • $\mathbf{B}$: Loading matrix, of size $N \times N_{f}$.
  • $\mathbf{E}$: Residual matrix, $T \times N$.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{w}_1$: Factor weights of FactorRiskContribution, one entry for each of the $N_f$ factors. The asset weights are $\mathbf{B}_1 \boldsymbol{w}_1$, with $\mathbf{B}_1$ the pseudoinverse of $\mathbf{B}^\intercal$, plus an off-factor block when flag = true.
  • $\boldsymbol{w}_2$: Off-factor weights, one entry for each direction of the null space of $\mathbf{B}^\intercal$. There are $N - N_f$ of them when $\mathbf{B}$ has full column rank.
  • $\mathbf{B}_1$: The factor basis, $N \times N_f$.
  • $\mathbf{B}_2$: The off-factor basis, $N \times (N - \operatorname{rank}\mathbf{B})$.
  • $(\cdot)^{+}$: Moore-Penrose pseudoinverse.
  • $f(\boldsymbol{w})$: The objective, which obj selects, see ObjectiveFunction.
  • $\mathcal{W}$: Feasible weight set, the portfolios that the constraints of the optimiser admit.
  • $R(\boldsymbol{w})$: Portfolio risk.
  • $RC_j$: Risk contribution of factor $j$.
  • $N$: Number of assets.

Fields

  • opt: JuMP optimiser configuration.
  • re: Regression estimator.
  • r: Risk measure or vector of risk measures.
  • obj: Portfolio objective function.
  • sets: Sets used to map estimator values to assets.
  • wi: Initial portfolio weights for warm-starting the solver.
  • flag: Algorithm selection flag.
  • fb: Fallback result or estimator.

Constructors

FactorRiskContribution(;    opt::JuMPOptimiser,    re::TD{<:RegE_Reg} = StepwiseRegression(),    r::TD{<:RM_VecRM} = Variance(),    obj::TD{<:ObjectiveFunction} = MinimumRisk(),    frc_ple::TD_Option{<:Union{PlCE_PlC, AbstractVector}} = nothing,    sets::TD_Option{<:UniverseSets} = nothing,    wi::TD_Option{<:VecNum} = nothing,    flag::Bool = false,    fb::TDO_Option{<:OptE_Opt} = nothing) -> FactorRiskContribution

Keywords correspond to the struct's fields. A field typed TD, TD_Option or TDO_Option can hold a TimeDependent schedule in place of a static value. These fields define the problem: the factor model, the risk measure, the objective, the factor phylogeny constraints, the asset sets, the warm start and the fallback. A cross-validation fold loop resolves each schedule for its fold, and an optimise outside a fold uses the static default of each field. flag controls the execution and is always static. frc_ple takes a vector that mixes estimators and Results, through narrow_mixed_vector.

Validation

  • If r is a vector: !isempty(r).
  • If frc_ple or wi is a vector: !isempty.
  • fb schedules: bind !== :nearest.
  • The risk expression is not identically zero. The problem is stated in the factor basis, so a model with no risk term bounds nothing. A NoRisk measure and settings.rke = false on every measure are the two ways to get such a model.
  • If r holds a DataBenchmarkTracking: opt.pe must not state x_src = ExcessSource(), see assert_data_benchmark_prior.
  • Each estimator of frc_ple states no source, because it reads the factor returns that the head picks, see assert_inner_reader.
  • opt.ple holds no SemiDefinitePhylogeny and no SemiDefinitePhylogenyEstimator, directly, in a vector or in a schedule, see holds_precomputed. The head writes no lift of the asset weights, so the phylogeny would add no rows. A phylogeny of the factors goes in frc_ple. An IntegerPhylogeny in opt.ple applies.
  • A reader that states no source and reads the raw returns data, beside a reader that states x_src = ExcessSource(), logs one warning that names its path, see warn_raw_readers. The head then builds as configured.

Propagated parameters

factory passes its arguments on to these @fprop fields:

  • opt: Recursively updated through factory.
  • r: Recursively updated through factory.
  • fb: Recursively updated through factory.

View parameters

FactorRiskContribution has its own port_opt_view method. It does not derive the view from the tags of the fields.

  • The method reads the returns matrix X as its third argument. When opt.pe holds a prior result, the method replaces X with opt.pe.X, so the children are viewed against the observations of the prior and not against the matrix of the caller.
  • opt and r recurse through port_opt_view with that matrix. re recurses with the index alone, which slices its loadings to the selected assets and keeps every factor.
  • fb goes through view_child, which views a fallback estimator and keeps a fallback result.
  • wi is not changed, because it holds start values of the factor weights. The asset selection does not index the factor axis.
  • obj, frc_ple, sets and flag are not changed.

Observation weight parameters

obs_weights_view indexes these fields to the selected observations:

Related

References

  • [223] T. Roncalli and G. Weisang. Risk parity portfolios with risk factors. Available at SSRN 2155159 (2012). Section 3, Equation 2 and Theorem 1. The matrix $\mathbf{A}$ of that work is $\mathbf{B}$ here.
  • [224] A. Meucci. Risk contributions from generic user-defined factors. Available at SSRN 930034 (2007). Section 4, Equations 20 and 21. The completion of the basis by the null space.
  • [190] D. Cajas. A Semidefinite Programming Approach to Risk Parity Portfolio Optimization. Available at SSRN 5097869 (2025). Section 3.2, Formulation 16. The semidefinite relaxation of the rc rows under Variance.
source
PortfolioOptimisers.factory — Method
factory(a, args...; kwargs...) -> a
factory(a::AbstractArray{<:Union{Nothing, AbstractEstimator, AbstractAlgorithm,
                                 AbstractResult, StatsBase.CovarianceEstimator}},
        args...; kwargs...) -> AbstractArray

Rebuild an estimator, an algorithm or a result with runtime values. These two methods are the leaf and the array step of the traversal.

factory and port_opt_view are the two propagation mechanisms of this library. factory passes runtime values, such as prior moments, observation weights and previous portfolio weights, down a tree of composed structs. port_opt_view passes an index selection, a subset of the assets, down the same tree.

factory is a traversal, so it owns the identity on every leaf, as fmap in Functors.jl and adapt_structure in Adapt.jl do. A value that has no method of its own comes back with no change: a data field, a scalar, nothing, a set of observation weights and a covariance estimator of StatsBase. So a @propagatable struct sends each @fprop field to factory directly, whatever the field holds.

The array method is the one forwarding contract for every propagation field that holds an array of estimators, algorithms, results or covariance estimators. It applies factory to each element, and it forwards args... and kwargs... with no change. A family that accepts an array of them needs no method of its own. A family that needs more than the forward defines its own, more specific method. A concrete element type, through concrete_typed_array_if_abstract, is an example. An array of data, such as a vector of numbers, is a leaf, and it comes back with no change and with no copy.

Algorithm

The leaf method:

  1. Return a with no change, and drop args... and kwargs.... This method is the leaf of the recursion. Because of it, a call of the verb on a type with no tags returns the value and raises no error.

The array method:

  1. For each element ai of a, call factory on ai, and forward args... and kwargs... with no change.
  2. Collect the results into a new array of the shape of a, in the order of a, and return it.

A @propagatable struct always has a generated method that is more specific than the leaf method. If the struct has at least one @fprop or @wprop field, that method builds the struct again with its keyword constructor. It sends each @fprop field through factory and each @wprop field through _wprop. If the struct has no such field, that method returns x.

The leaf method does not fill a nothing field. A weights field that must take the incoming weights when it holds nothing carries @wprop, and it goes to _wprop.

Arguments

  • a: Any value, which the leaf method returns with no change. For the array method, an array of estimators, algorithms, results, covariance estimators or nothing, which it rebuilds one element at a time.
  • args...: Positional arguments. The leaf method ignores them, and the array method forwards them.
  • kwargs...: Keyword arguments. The leaf method ignores them, and the array method forwards them.

Returns

  • a: The input with no change, for the leaf method.
  • v::AbstractArray: The rebuilt elements, in an array of the shape of a, for the array method.

Examples

julia> factory(nothing, 1, 2; x = 3)julia> factory([1.0, 2.0], 1, 2; x = 3)2-element Vector{Float64}: 1.0 2.0julia> factory(MeanValue())MeanValue  w ┴ nothing

Related

source
factory(res::NonFiniteAllocationOptimisationResult, fb::Option{<:OptE_Opt_FbChain})

Rebuilds a continuous optimisation result with a new fallback record fb.

A concrete result can add its own method when a rebuild needs more than a new fb. optimise is the one caller, and it gives the FbChain of the attempts that failed.

Algorithm

  1. Read every field of res, in the order of the struct.
  2. Call the constructor of the type of res with every field except the last, and with fb as the last field.

Validation

  • fb is the last field of the type of res. Every concrete optimisation result obeys this rule, so the method checks nothing.

Related

source
factory(
    opt::Union{NonFiniteAllocationOptimisationEstimator, NonFiniteAllocationOptimisationResult},
    _
) -> RelaxedRiskBudgeting{JuMPOptimiser{__T_pe, __T_slv, __T_cbe, __T_bgt, __T_fees, __T_ret, __T_sca, __T_sc, __T_so, __T_strict, __T_cache}, _A, _B, <:RelaxedRiskBudgetingAlgorithm} where {__T_pe, __T_slv, __T_cbe, __T_bgt, __T_fees, __T_ret, __T_sca, __T_sc, __T_so, __T_strict, __T_cache, _A, _B}

Returns opt unchanged.

This is the fallback factory of an optimisation estimator or result. An estimator whose parameters change at each step of an optimisation adds its own method. A precomputed result in a field of an estimator, for example in fb, reaches this method when factory gives the estimator the weights of the previous fold. A precomputed result does not change.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    frc::FactorRiskContribution,
    i,
    X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
    args...
) -> FactorRiskContribution{__T_opt, __T_re, __T_r, __T_obj, __T_frc_ple, __T_sets, __T_wi, Bool} where {__T_opt, __T_re, __T_r, __T_obj, __T_frc_ple, __T_sets, __T_wi}

Return the view of a FactorRiskContribution at the assets i, for the returns matrix X.

The ## View parameters subsection of FactorRiskContribution states how each field is viewed.

Related

source
PortfolioOptimisers._optimise — Function
_optimise(frc::FactorRiskContribution, rd::ReturnsResult = ReturnsResult();
          str_names::Bool = false, save::Bool = true, blocks::Tuple = (),
          kwargs...) -> FactorRiskContributionResult

Build the model of a FactorRiskContribution, solve it, and return its result.

optimise reaches this method through shared_series_solve, which drops the observations of a Shared Series gap before the solve.

Algorithm

  1. Replace each schedule of frc with its static default through reset_time_dependent_estimator.
  2. Resolve frc.opt against rd with resolve_jump_optimiser, with the blocks of blocks, giving attrs.
  3. Take the view of frc and of rd at the investable assets with investable_view. Both are unchanged when every asset is investable.
  4. Bind the benchmark of each DataBenchmarkTracking measure to rd with bind_data_benchmark.
  5. Build a new model. Register the scales with set_model_scales!, the number of observations with set_model_observations!, the homogenisation variables of a ratio with set_maximum_ratio_factor_variables! and the corner of a lifted variance with set_sdp_lift_corner!.
  6. Create the factor weights and register w with set_factor_risk_contribution_constraints!, giving b1, b2 and rr. b is b1, or [b1 b2] when flag = true, the basis of the whole decision vector.
  7. Add the weight bounds, the budgets, the constraints, the return terms and the risk measures of every block with assemble_jump_model!, which reads b. The constructor refuses an asset phylogeny of the semidefinite kind, so the assembly adds the rows of an integer one alone.
  8. Resolve frc.frc_ple on the factor returns with phylogeny_constraints, giving frc_plr. Add its rows with set_sdp_frc_phylogeny_constraints! and set_frc_iplg_constraints!.
  9. Set the objective with set_portfolio_objective_function!, and solve with optimise_JuMP_model!, giving retcode and sol.
  10. Build the result. It holds attrs, retcode, sol, the model when save is true, the risk measures resolved against the prior, rr and frc_plr.

Arguments

  • frc::FactorRiskContribution: The optimiser.
  • rd: The returns result to use. The solve reads it to fit the loadings when neither re nor the prior holds them, and reads its factor returns to resolve frc_ple. A fallback or a clustering step can also read it.
  • str_names::Bool: true gives each variable and each row of the model its string name.
  • save::Bool: true keeps the model in the result.
  • blocks::Tuple = (): The blocks after the block of the optimiser of the head, the keyword blocks of resolve_jump_optimiser. The head adds the rows of every block to its model with assemble_jump_model!. The fallback chain of optimise passes the keyword to each member, so a fallback solves on the same blocks.
  • kwargs...: Passed on to resolve_jump_optimiser.

Returns

Related

source

References

[190]
D. Cajas. A Semidefinite Programming Approach to Risk Parity Portfolio Optimization. Available at SSRN 5097869 (2025).
[223]
T. Roncalli and G. Weisang. Risk Parity Portfolios with Risk Factors. Available at SSRN 2155159 (2012).
[224]
A. Meucci. Risk Contributions from Generic User-Defined Factors. Available at SSRN 930034 (2007).