Factor Black-Litterman Prior
PortfolioOptimisers.FactorBlackLittermanPrior — Type
struct FactorBlackLittermanPrior{__T_pe, __T_f_mp, __T_mp, __T_re, __T_ve, __T_rsd, __T_views, __T_sets, __T_views_conf, __T_w, __T_rf, __T_l, __T_tau, __T_mtx_sqrt, __T_cache, __T_x_src} <: AbstractLowOrderPriorEstimator_FFactor Black-Litterman prior estimator for asset returns.
FactorBlackLittermanPrior is a low order prior estimator. It fits a prior on the factor returns, and it applies the Black-Litterman update to the factor moments. A regression of the assets on the factors then lifts the posterior factor moments onto the assets.
Black and Litterman [59] state the update on the asset axis. The library applies the same update to the factor moments. It then lifts the posterior factor moments onto the assets with the factor model of Cajas [12]. Cajas [12] states the update and the lift as two separate results, and it does not state their composition.
Fields
pe: Prior estimator.
f_mp: Factor matrix processing estimator.
mp: Matrix processing estimator.
re: Regression estimator.
ve: Variance estimator.
rsd: Whether to include residual variance in the posterior covariance.
views: The views, aLinearConstraintEstimatorof view equations or a precomputedBlackLittermanViews.
sets: Universe sets. This estimator reads the time-series factor axis,sets.dict[sets.tfkey]. The views are written in the names of this axis, and the axis must name the columns ofFin order.UniverseSetsalso needs the asset axis, and a view slices that axis. The factor entries come back fromport_opt_viewwith no change.
views_conf: The confidence of the views, in(0, 1), ornothing. A number is one confidence for all the views, and a vector holds one confidence for each view that the caller wrote. Ifnothing, the view uncertainty has no confidence scale, seecalc_omega.
w: Optional equilibrium weights vectorassets × 1. Ifnothing,equilibrium_muuses equal weights.
rf: Risk-free rate. The Black-Litterman update compares the prior mean with the view returns, so it uses the total-return scale of the views. A mean from a wrapped prior estimator has that scale. An equilibrium mean is only a risk premium, and the rate converts it before the update. A member with no equilibrium branch has no mean to convert, and it adds the rate to the posterior asset expected returns. In both cases the estimator adds the rate once. It does not change the wrapped prior estimators, so a risk-free rate that one of them applied stays in its mean.
l: Risk aversion parameter.
tau: The scale of the uncertainty of the prior mean,tau > 0. Ifnothing, the estimator uses1/T, whereTis the number of observations.
mtx_sqrt: Square-root algorithm of the factor covariance, and of the idiosyncratic covariance when that block is a full matrix, whose square roots make upchol. The defaultEigenFallbackSquareRoottakes the Cholesky factor where it exists, and the eigen square root of a singular positive semidefinite matrix otherwise.RidgeCholeskySquareRoottakes the Cholesky factor of the matrix with a small ridge added, andnothingtakes the plain Cholesky factor, which raises aLinearAlgebra.PosDefExceptionon a matrix that is not positive definite.matrix_square_rootstates each algorithm.
cache: Optional partial-fit state. It isnothinguntilpartial_fit!writes one. When the caller gives no data matrix, the batch verb of the estimator reads it. Each propagation channel does one thing with it.factorykeeps it unchanged, because a factory call resolves the configuration, not the sample.port_opt_viewcopies the entries of the selected assets into a new state, so the viewed estimator holds the state of those assets alone.obs_weights_viewremoves it, because a state has no slice on the observation axis. Only a type with an observation-weights field has that channel. A type with no such field falls through to the identity method, so it keeps its state. A family whose state has no exact asset slice removes it on both axes and names the reason.
x_src: The source of the returns that the prior fits on,nothingor anAbstractReturnsSource.nothingandDataSourceread the asset returnsrd.X.ExcessSourcereads the returns in excess of the benchmark,rd.X - rd.B, the Excess Frame, and refuses returns data with no benchmark.nothingmeans that the caller stated no source, so an optimiser that holds a reader of the Excess Frame warns about a prior atnothing, and not about a prior atDataSource(). A prior reads no prior, so it refusesPriorSource. A prior inside another estimator, such as thepeof aFactorPrior, keepsnothing, and the outer estimator states the source.
Constructors
FactorBlackLittermanPrior(; pe::AbstractLowOrderPriorEstimator_A_AF = EmpiricalPrior(), f_mp::AbstractMatrixProcessingEstimator = MatrixProcessing(), mp::AbstractMatrixProcessingEstimator = MatrixProcessing(), re::AbstractTimeSeriesRegressionEstimator = StepwiseRegression(), ve::AbstractVarianceEstimator = SimpleVariance(), rsd::Bool = true, views::Lc_BLV, sets::Option{<:UniverseSets} = nothing, views_conf::Option{<:Num_VecNum} = nothing, w::Option{<:VecNum} = nothing, rf::Number = 0.0, l::Option{<:Number} = nothing, tau::Option{<:Number} = nothing, mtx_sqrt::Option{<:AbstractMatrixSquareRootAlgorithm} = EigenFallbackSquareRoot(), cache::Option{<:AbstractPartialFitState} = nothing, x_src::Option{<:AbstractReturnsSource} = nothing) -> FactorBlackLittermanPriorKeywords correspond to the struct's fields.
Composition: what this estimator forwards
This estimator lifts a prior on the factor axis onto the asset axis, and it reconstructs X as F * transpose(M) .+ transpose(b). It builds its prior result directly, and it does not forward a prior along its own axis. A posterior field still replaces the prior field of the same name, and a structural field still forwards whole. In this member of the Black-Litterman family, the views change the factor block. The views apply to the factor distribution, and the asset moments are its projection.
- The factor block
fpris the posterior factor distribution, processed byf_mp. The estimator drops itschol, because the posterior covariance replaces the covariance thatcholfactorises. Itswand the diagnostics of that weighting forward with no change. muandsigmaare that block projected through the loadings. So the returned prior result is internally consistent:mu == rr.M * fpr.mu + rr.bholds for all values ofrf. When the rate reaches the result, it is insidefpr.mu. Whenrsdistrue,sigmaalso gets a residual block.wis thewof the factor prior, and it is on the correct axis. This estimator wraps only a factor prior, andposterior_Xhas the same rows asF. No other weighting exists.
BayesianBlackLittermanPrior also satisfies the identity exactly. BlackLittermanPrior and AugmentedBlackLittermanPrior do not. See their warnings.
The views are written on the factor axis
views resolves against sets.dict[sets.tfkey], the factor axis that UniverseSets declares, because the views update the factor distribution. The asset axis is still necessary, because every UniverseSets carries one, and port_opt_view slices it. The factor entries come back with no change, so this field is @vprop and needs no exemption.
sets.dict[sets.tfkey] must name the columns of F in order. factor_universe checks it. When the axis is missing or has the wrong length, the error names the factor axis, not the asset axis.
Validation
- If
viewsis aLinearConstraintEstimator,!isnothing(sets). - If
views_confis notnothing,assert_bl_views_confchecksviews_conf. - If
tauis notnothing,tau > 0. x_srcisnothing,DataSource()orExcessSource(), seeassert_returns_source.- The
x_srcofpe,reisnothing, because the prior picks the returns that it reads, seeassert_inner_reader. - When
rsdistrue,mpstates the estimator of its repair, seeassert_matrix_processing_posdef.
The constructor does not check w. The length of w is a property of the returns matrix, and the constructor does not see that matrix. A wrong length raises a DimensionMismatch from equilibrium_mu in prior, and only when l is set. The constructor also accepts an empty w, but the sibling AugmentedBlackLittermanPrior refuses one.
Propagated parameters
factory passes its arguments on to these @fprop fields:
pe: Recursively updated throughfactory.re: Recursively updated throughfactory.ve: Recursively updated throughfactory.cache: Carried unchanged throughfactory.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
re: Recursively viewed throughport_opt_view.ve: Recursively viewed throughport_opt_view.sets: Sliced to the selected indices throughport_opt_view.w: Sliced to the selected indices throughport_opt_view.cache: Sliced to the selected assets throughport_opt_view.
Examples
julia> FactorBlackLittermanPrior(; sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"], "nf" => ["F1", "F2"])), views = LinearConstraintEstimator(; val = ["F1 == 0.03", "F2 == 0.04"]))FactorBlackLittermanPrior pe ┼ EmpiricalPrior │ ce ┼ PortfolioOptimisersCovariance │ │ ce ┼ Covariance │ │ │ me ┼ SimpleExpectedReturns │ │ │ │ w ┴ nothing │ │ │ ce ┼ GeneralCovariance │ │ │ │ ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true) │ │ │ │ w ┴ nothing │ │ │ alg ┼ FullMoment() │ │ │ w ┴ nothing │ │ mp ┼ MatrixProcessing │ │ │ pdm ┼ Posdef │ │ │ │ alg ┼ UnionAll: NearestCorrelationMatrix.Newton │ │ │ │ kwargs ┴ @NamedTuple{}: NamedTuple() │ │ │ dn ┼ nothing │ │ │ dt ┼ nothing │ │ │ alg ┼ nothing │ │ │ order ┴ NTuple{4, Symbol}: (:pdm, :dn, :dt, :alg) │ me ┼ SimpleExpectedReturns │ │ w ┴ nothing │ horizon ┼ nothing │ fill_limit ┼ nothing │ x_src ┴ nothing f_mp ┼ MatrixProcessing │ pdm ┼ Posdef │ │ alg ┼ UnionAll: NearestCorrelationMatrix.Newton │ │ kwargs ┴ @NamedTuple{}: NamedTuple() │ dn ┼ nothing │ dt ┼ nothing │ alg ┼ nothing │ order ┴ NTuple{4, Symbol}: (:pdm, :dn, :dt, :alg) mp ┼ MatrixProcessing │ pdm ┼ Posdef │ │ alg ┼ UnionAll: NearestCorrelationMatrix.Newton │ │ kwargs ┴ @NamedTuple{}: NamedTuple() │ dn ┼ nothing │ dt ┼ nothing │ alg ┼ nothing │ order ┴ NTuple{4, Symbol}: (:pdm, :dn, :dt, :alg) re ┼ StepwiseRegression │ crit ┼ PValue │ │ t ┴ Float64: 0.05 │ alg ┼ ForwardSelection() │ tgt ┼ LinearModel │ │ kwargs ┴ @NamedTuple{}: NamedTuple() │ choice ┼ BatchChoice() │ included ┼ nothing │ x_src ┴ nothing ve ┼ SimpleVariance │ me ┼ SimpleExpectedReturns │ │ w ┴ nothing │ w ┼ nothing │ corrected ┴ Bool: true rsd ┼ Bool: true views ┼ LinearConstraintEstimator │ val ┼ Vector{String}: ["F1 == 0.03", "F2 == 0.04"] │ key ┴ nothing sets ┼ UniverseSets │ xkey ┼ String: "nx" │ uxkey ┼ String: "ux" │ tfkey ┼ String: "nf" │ utfkey ┼ String: "uf" │ cfkey ┼ String: "ncf" │ ucfkey ┼ String: "ucf" │ nikey ┼ String: "ni" │ dict ┴ Dict{String, Vector{String}}: Dict("nf" => ["F1", "F2"], "nx" => ["A", "B", "C"]) views_conf ┼ nothing w ┼ nothing rf ┼ Float64: 0.0 l ┼ nothing tau ┼ nothing mtx_sqrt ┼ EigenFallbackSquareRoot() x_src ┴ nothingThe incremental fit
This prior has no exact incremental recursion, and it takes the online step by a refit from a sample buffer. Online seeds cache, and partial_fit! adds each observation to it with no change. The prior method with one argument then runs the batch verb of this estimator over the rows that the buffer kept. The result is the batch fit over those rows, and a max_history on the wrapper sets the window of the whole fit.
cache goes through the three propagation channels as every partial-fit state does. factory carries it with no change, and port_opt_view cuts it to the selected assets. obs_weights_view drops it, because a state has no cut on the observation axis. The show method does not print cache, because a buffer that changes at each step is not part of the configuration.
Related
AbstractLowOrderPriorEstimator_FEmpiricalPriorBlackLittermanViewsUniverseSetsLowOrderPriorpriorfactoryport_opt_view
References
- [59] F. Black and R. Litterman. Global asset allocation with equities, bonds, and currencies. Goldman, Sachs & Co., Fixed Income Research (1991). Appendix, items 7 and 8. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 5.1.5, Equations 5.13 to 5.15, and Section 4.1, Equations 4.4 and 4.5.
PortfolioOptimisers.prior — Function
prior(pe::FactorBlackLittermanPrior, X::MatNum, F::MatNum,
pnl::Option{<:AssetPanel} = nothing; dims::Int = 1,
strict::Bool = false,
active_mask::Option{<:AbstractMatrix{<:Bool}} = nothing,
cache_reg::Bool = false, kwargs...)Compute factor Black-Litterman prior moments for asset returns.
prior fits the wrapped prior on the factor returns, and it applies the views to the factor moments with the Black-Litterman master equations. It then lifts the posterior factor moments onto the assets.
When pe.tau is nothing, the blending parameter is 1/T, where T is the effective number of observations of the factor mean that the factor prior states in eoc. It is the number of observations of the oriented X when the factor prior states no count. The update gets a total return over the factors as its mean. The view returns in Q have this scale, and the factor block has it too. pe.rf reaches the update only when pe.l is set, because only that branch has a prior mean that is a risk premium. The closed form below gives the shift that the rate causes there. When pe.l is nothing, no step reads the field, and it does not change the result.
Mathematical definition
The Black-Litterman update applies the views to the factor moments $(\boldsymbol{\Pi}_f, \mathbf{\Sigma}_f)$ with the master equations. The loadings matrix then gives the asset posteriors:
\[\begin{align} \hat{\boldsymbol{\mu}} &= \mathbf{M} \hat{\boldsymbol{\mu}}_{f,BL} + \boldsymbol{b}\,. \end{align}\]
\[\begin{align} \hat{\mathbf{\Sigma}} &= \mathbf{M} \hat{\mathbf{\Sigma}}_{f,BL} \mathbf{M}^\intercal + \mathbf{\Sigma}_\varepsilon\,. \end{align}\]
Where:
- $N$, $K$, $K_v$, $T$: The number of assets, of factors, of views, and of observations.
- $\hat{\boldsymbol{\mu}}$: $N \times 1$ posterior asset mean vector,
pr.mu. - $\hat{\mathbf{\Sigma}}$: $N \times N$ posterior asset covariance matrix,
pr.sigma. - $\boldsymbol{\Pi}_f$, $\mathbf{\Sigma}_f$: $K \times 1$ and $K \times K$ prior factor moments, from
pe.pefit onF. - $\hat{\boldsymbol{\mu}}_{f,BL}$: $K \times 1$ Black-Litterman posterior factor mean,
pr.fpr.mu. - $\hat{\mathbf{\Sigma}}_{f,BL}$: $K \times K$ Black-Litterman posterior factor covariance,
pr.fpr.sigma. - $\mathbf{M}$: $N \times K$ factor loadings matrix,
pr.rr.M. - $\boldsymbol{b}$: $N \times 1$ regression intercept vector,
pr.rr.b. - $\mathbf{P}$: $K_v \times K$ views matrix, over the factor axis.
- $\mathbf{\Omega}$: $K_v \times K_v$ view uncertainty matrix, from
calc_omegaandbl_preroll. - $\mathbf{\Sigma}_\varepsilon$: $N \times N$ diagonal residual variance matrix, zero when
rsd = false. - $\tau$: Scaling parameter,
1/Tby default. - $r_{f}$: Risk-free rate.
apply_rfadds it once, to the equilibrium factor mean. So it is inside $\hat{\boldsymbol{\mu}}_{f,BL}$ whenpe.lis set, and it is absent whenpe.lisnothing.
The factor moments are the Black-Litterman posterior of vanilla_posteriors over the factor axis. $\mathbf{P}$ has $K$ columns, and $\mathbf{\Sigma}_f$ is the covariance of the factor prior. A direct call of vanilla_posteriors on the factor prior and on the P, Q and omega of bl_preroll gives pr.fpr.mu and pr.fpr.sigma. The two lifted forms above give pr.mu and pr.sigma for both values of rsd. The returned chol is a factor of the returned covariance, so the residual block is in both.
The rate reaches the result through the factors, and only on one branch. When pe.l is set, the equilibrium mean is a risk premium. apply_rf adds the rate to it before the update, and this gives a total factor return. The blend and the lift then carry all of that factor mean, with the rate in it. Let $\mathbf{G} = \tau\mathbf{\Sigma}_f\mathbf{P}^\intercal(\mathbf{P}\tau\mathbf{\Sigma}_f\mathbf{P}^\intercal + \mathbf{\Omega})^{-1}$ be the update gain, and let $\mathbf{1}$ be the vector of ones. Against the same estimator at $r_f = 0$, the result moves by:
\[\begin{align} \Delta\hat{\boldsymbol{\mu}} &= r_{f}\mathbf{M}\left(\mathbf{I} - \mathbf{G}\mathbf{P}\right)\mathbf{1}\,. \end{align}\]
The shift is linear in $r_f$, and it depends on the views through $\mathbf{G}$. On a 250 × 5 sample over three factors, with two factor views and l = 2.0, the shift per unit of $r_f$ is [0.489, 0.831, 0.868, 0.183, 0.973]. It agrees with the closed form to 2.2e-16, and the values at rf = 0.03 and at rf = 0.06 agree to 2.8e-16. When pe.l is nothing, the prior mean is the mean of the factor prior, which is a total return. No step then reads pe.rf, and two fits that differ only in rf are equal in each entry.
Algorithm
- Orient
XandFwithdims_oriented, toobservations × assetsandobservations × factors. - When
pe.viewsresolves names, check the declared factor axis against the width ofFwithfactor_universe. A precomputedBlackLittermanViewsresolves no name, so step 6 checks its width instead. - Reduce
Xto the assets that the fit can use, withcoverage_reductionunderpnl. The results are the mask andXi. This member wraps a factor prior, so it has no prior result on the asset axis to give an Investable Mask. The reduction reads the gaps from the returns. When the caller givesactive_mask, the reduction reads it in place of the active mask ofpnl. - Fit the wrapped prior
pe.peonFalone. The result isf_prior. Readprior_muandprior_sigmafrom it. The type bound ofpeis a bound for asset priors, but this step gives it the factor matrix.strictandcache_regreach it, as inFactorPrior. So the prior stores the cache that a refit under new scenario weights reads fromfpr. No other keyword reaches it, because the other keywords describe the asset axis. - Regress
XionFwithfactor_reconstruction, underpe.reviewed toimskwithcoverage_regression. The results are the regression resultrrand the reconstructed returnsposterior_X. - Make the views and their uncertainty with
bl_preroll, overprior_sigmaand the count of the factor mean frommoment_observation_count. The result isblp. The axis is:tfkey, so a departed asset drops no view row, and the step keeps no ledger. - Put the prior mean on the total-return scale of the views. The result is
prior_total_mu. Whenpe.lis set, it is the equilibrium mean ofequilibrium_mupluspe.rffromapply_rf. The equilibrium mean is a risk premium, and it readspe.wsliced to the reduced axis byinvestable_weights_view. Whenpe.lisnothing, it isprior_mu, which is on that scale already. - Run the master equations with
vanilla_posteriors. The result is the posterior factor pair. When no view row is left, it gives backprior_total_muand the factor prior covariance. Step 10 lifts them as it lifts a posterior pair. - Process the posterior factor covariance in place with
sample_matrix_processing!, underpe.f_mp,Fand the count of the factor covariance frommoment_observation_count. - Lift the posterior factor pair onto the reduced assets with
factor_lift, with the same count. The results aremu,sigma,chol,esigma,edofandediv.FactorPriorapplies the same lift, to different factor moments. The lift adds the residual block whenpe.rsdistrue. It takes the square root of the posterior factor covariance forcholunderpe.mtx_sqrt, and it processessigmaunderpe.mp. - Write
esigma,edofandedivontorrwithset_idiosyncratic_covariance. Underpe.rsd = true, the fields hold the residual variances that the lift measured and their counts. Underpe.rsd = false,esigmaandedivholdnothing, because the lift added no residual block. - Forward the factor block with
forward_prior. Replacemuandsigmawith the posterior factor pair, and dropchol. Do not expand the block, because the reduction did not change the factor axis. - Announce the departures once with
announce_bl_departures.investable_universe_namesgives their names. - Write each block on the asset axis back onto the full universe.
expand_momentwrites the moment pair,expand_columnswrites the reconstruction, andexpand_regressionwrites the regression. When step 3 removed an asset, dropcholand do not expand it, because a frame withNaNentries has no factorisation. - Cut the reconstruction and the oriented
Xto the rows thatf_prior.Xcarries, withscenario_window. A Scenario Cap ofpe.pekeeps the last rows ofFalone, and the asset side keeps the same rows, as inFactorPrior. With no cap, the cut keeps every row. The fit of the moments used every observation, so the cut changes no moment. - Build the prior result directly. It takes
wand its diagnostics fromf_prior, the reconstruction asX, and the orientedXaso_X. Under a cap,f_prior.ensgives the count of the observations that the moments read.
Arguments
pe: Factor Black-Litterman prior estimator.X: Asset returns matrix (observations × assets).F: Factor matrix (observations × factors).pnl: OptionalAssetPanel, the panel that the returns data held. A wrapping prior forwards it unchanged, so that it can compose an estimator that is fitted on a panel. An estimator that reads no panel ignores it. The panel reaches the reduction of step 3 alone. The estimator fits its nested prior on the factors, and no panel describes the factor axis.dims: Dimension along which the computation runs.strict: Iftrue, enforce strict validation of views and sets. Default isfalse.active_mask: The active mask ofX, of the shape ofX, ornothing. When it is notnothing, it takes the place of the active mask ofpnl.cache_reg: Iftrue, a prior stores on its result the cache that its refit under new scenario weights reads: aCrossSectionalFactorPriorthe active mask and the Return Forecast history on its block, and anOpinionPoolingPriorthe rows ofpe1, its pooled weights and the cache ofpe2inpc. The refit of an entropy pooling prior around it then runs no regression and no opinion. Every other prior forwards it to the prior that it wraps. Default isfalse.kwargs...: More keyword arguments, for the processing of the asset covariance underpe.mpinfactor_lift.
Validation
dims in (1, 2).- If
pe.viewsis aLinearConstraintEstimator,haskey(pe.sets.dict, pe.sets.tfkey)andlength(pe.sets.dict[pe.sets.tfkey]) == size(F, 2), both throughfactor_universe.
pe.w has no named check. When pe.l is set, a pe.w with a length other than size(X, 2) raises a bare DimensionMismatch from the product in equilibrium_mu. When pe.l is nothing, no step reads pe.w.
Returns
pr::LowOrderPrior: Result object with the reconstructed asset returns, the posterior asset mean vector, the posterior asset covariance matrix and its Cholesky factor. It carries the observation weighting of the factor prior, its diagnostics, and the regression result. Its factor blockfprholds the posterior factor moments, on the total-return scale of the update.fpr.cholisnothing.
Related
References
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
- [59]
- F. Black and R. Litterman. Global asset allocation with equities, bonds, and currencies (Goldman, Sachs & Co., Fixed Income Research, Oct 1991).