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_F

Factor 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.
  • 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 of F in order. UniverseSets also needs the asset axis, and a view slices that axis. The factor entries come back from port_opt_view with no change.
  • views_conf: The confidence of the views, in (0, 1), or nothing. A number is one confidence for all the views, and a vector holds one confidence for each view that the caller wrote. If nothing, the view uncertainty has no confidence scale, see calc_omega.
  • w: Optional equilibrium weights vector assets × 1. If nothing, equilibrium_mu uses 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. If nothing, the estimator uses 1/T, where T is 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 up chol. The default EigenFallbackSquareRoot takes the Cholesky factor where it exists, and the eigen square root of a singular positive semidefinite matrix otherwise. RidgeCholeskySquareRoot takes the Cholesky factor of the matrix with a small ridge added, and nothing takes the plain Cholesky factor, which raises a LinearAlgebra.PosDefException on a matrix that is not positive definite. matrix_square_root states each algorithm.
  • cache: Optional partial-fit state. It is nothing until partial_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. factory keeps it unchanged, because a factory call resolves the configuration, not the sample. port_opt_view copies the entries of the selected assets into a new state, so the viewed estimator holds the state of those assets alone. obs_weights_view removes 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, nothing or an AbstractReturnsSource. nothing and DataSource read the asset returns rd.X. ExcessSource reads the returns in excess of the benchmark, rd.X - rd.B, the Excess Frame, and refuses returns data with no benchmark. nothing means that the caller stated no source, so an optimiser that holds a reader of the Excess Frame warns about a prior at nothing, and not about a prior at DataSource(). A prior reads no prior, so it refuses PriorSource. A prior inside another estimator, such as the pe of a FactorPrior, keeps nothing, 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) -> FactorBlackLittermanPrior

Keywords 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 fpr is the posterior factor distribution, processed by f_mp. The estimator drops its chol, because the posterior covariance replaces the covariance that chol factorises. Its w and the diagnostics of that weighting forward with no change.
  • mu and sigma are that block projected through the loadings. So the returned prior result is internally consistent: mu == rr.M * fpr.mu + rr.b holds for all values of rf. When the rate reaches the result, it is inside fpr.mu. When rsd is true, sigma also gets a residual block.
  • w is the w of the factor prior, and it is on the correct axis. This estimator wraps only a factor prior, and posterior_X has the same rows as F. 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

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 through factory.
  • re: Recursively updated through factory.
  • ve: Recursively updated through factory.
  • cache: Carried unchanged through factory.

View parameters

port_opt_view takes the view of these @vprop fields at the selected indices:

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 ┴ nothing

The 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

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.
source
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.pe fit on F.
  • $\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_omega and bl_preroll.
  • $\mathbf{\Sigma}_\varepsilon$: $N \times N$ diagonal residual variance matrix, zero when rsd = false.
  • $\tau$: Scaling parameter, 1/T by default.
  • $r_{f}$: Risk-free rate. apply_rf adds it once, to the equilibrium factor mean. So it is inside $\hat{\boldsymbol{\mu}}_{f,BL}$ when pe.l is set, and it is absent when pe.l is nothing.

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

  1. Orient X and F with dims_oriented, to observations × assets and observations × factors.
  2. When pe.views resolves names, check the declared factor axis against the width of F with factor_universe. A precomputed BlackLittermanViews resolves no name, so step 6 checks its width instead.
  3. Reduce X to the assets that the fit can use, with coverage_reduction under pnl. The results are the mask and Xi. 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 gives active_mask, the reduction reads it in place of the active mask of pnl.
  4. Fit the wrapped prior pe.pe on F alone. The result is f_prior. Read prior_mu and prior_sigma from it. The type bound of pe is a bound for asset priors, but this step gives it the factor matrix. strict and cache_reg reach it, as in FactorPrior. So the prior stores the cache that a refit under new scenario weights reads from fpr. No other keyword reaches it, because the other keywords describe the asset axis.
  5. Regress Xi on F with factor_reconstruction, under pe.re viewed to imsk with coverage_regression. The results are the regression result rr and the reconstructed returns posterior_X.
  6. Make the views and their uncertainty with bl_preroll, over prior_sigma and the count of the factor mean from moment_observation_count. The result is blp. The axis is :tfkey, so a departed asset drops no view row, and the step keeps no ledger.
  7. Put the prior mean on the total-return scale of the views. The result is prior_total_mu. When pe.l is set, it is the equilibrium mean of equilibrium_mu plus pe.rf from apply_rf. The equilibrium mean is a risk premium, and it reads pe.w sliced to the reduced axis by investable_weights_view. When pe.l is nothing, it is prior_mu, which is on that scale already.
  8. Run the master equations with vanilla_posteriors. The result is the posterior factor pair. When no view row is left, it gives back prior_total_mu and the factor prior covariance. Step 10 lifts them as it lifts a posterior pair.
  9. Process the posterior factor covariance in place with sample_matrix_processing!, under pe.f_mp, F and the count of the factor covariance from moment_observation_count.
  10. Lift the posterior factor pair onto the reduced assets with factor_lift, with the same count. The results are mu, sigma, chol, esigma, edof and ediv. FactorPrior applies the same lift, to different factor moments. The lift adds the residual block when pe.rsd is true. It takes the square root of the posterior factor covariance for chol under pe.mtx_sqrt, and it processes sigma under pe.mp.
  11. Write esigma, edof and ediv onto rr with set_idiosyncratic_covariance. Under pe.rsd = true, the fields hold the residual variances that the lift measured and their counts. Under pe.rsd = false, esigma and ediv hold nothing, because the lift added no residual block.
  12. Forward the factor block with forward_prior. Replace mu and sigma with the posterior factor pair, and drop chol. Do not expand the block, because the reduction did not change the factor axis.
  13. Announce the departures once with announce_bl_departures. investable_universe_names gives their names.
  14. Write each block on the asset axis back onto the full universe. expand_moment writes the moment pair, expand_columns writes the reconstruction, and expand_regression writes the regression. When step 3 removed an asset, drop chol and do not expand it, because a frame with NaN entries has no factorisation.
  15. Cut the reconstruction and the oriented X to the rows that f_prior.X carries, with scenario_window. A Scenario Cap of pe.pe keeps the last rows of F alone, and the asset side keeps the same rows, as in FactorPrior. With no cap, the cut keeps every row. The fit of the moments used every observation, so the cut changes no moment.
  16. Build the prior result directly. It takes w and its diagnostics from f_prior, the reconstruction as X, and the oriented X as o_X. Under a cap, f_prior.ens gives 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: Optional AssetPanel, 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: If true, enforce strict validation of views and sets. Default is false.
  • active_mask: The active mask of X, of the shape of X, or nothing. When it is not nothing, it takes the place of the active mask of pnl.
  • cache_reg: If true, a prior stores on its result the cache that its refit under new scenario weights reads: a CrossSectionalFactorPrior the active mask and the Return Forecast history on its block, and an OpinionPoolingPrior the rows of pe1, its pooled weights and the cache of pe2 in pc. 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 is false.
  • kwargs...: More keyword arguments, for the processing of the asset covariance under pe.mp in factor_lift.

Validation

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 block fpr holds the posterior factor moments, on the total-return scale of the update. fpr.chol is nothing.

Related

source

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