<a id="skfolio-prior-blacklitterman"></a>

# skfolio.prior.BlackLitterman

<a id="skfolio.prior.BlackLitterman"></a>

### *class* skfolio.prior.BlackLitterman(views, groups=None, prior_estimator=None, tau=0.05, view_confidences=None, risk_free_rate=0)

Black & Litterman estimator.

The Black & Litterman model [[1]](#rec957aca1165-1) takes a Bayesian approach by using a prior estimate
of the expected asset returns and covariance matrix, which are updated using the
analyst views to get a posterior estimate.

* **Parameters:**
  **views** *array-like of floats of shape (n_views,)*
  : The analyst views about the expected asset returns.
    The views must match the following patterns:
    > * Absolute view: “asset_i = a”
    > * Relative view: “asset_i - asset_j = b”
    <br/>
    With “asset_i” and “asset_j” the assets names and “a” and “b” the analyst views
    about the expected asset returns expressed in the same frequency as the
    returns `X`.
    <br/>
    For example:
    > * “SPX = 0.00015” –> the SPX will have a daily expected return of 0.015%
    > * “SX5E - TLT = 0.00039” –> the SX5E will outperform the TLT by a daily expected return of 0.039%
    > * “SX5E - SPX = -0.0002” –> the SX5E will underperform the SPX by a daily expected return of 0.02%
    > * “Equity = 0.00010” –> the sum of Equity assets will have a daily expected return of 0.01%
    > * “Europe - US = 0.0004” –> the sum of European assets will outperform the sum of US assets by a daily expected return of 0.04%

  **groups** *dict[str, list[str]] or array-like of strings of shape (n_groups, n_assets), optional*
  : The assets groups to be referenced in `views`.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset groups) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.
    <br/>
    For example:
    > * groups = {“SX5E”: [“Equity”, “Europe”], “SPX”: [“Equity”, “US”], “TLT”: [“Bond”, “US”]}
    > * groups = [[“Equity”, “Equity”, “Bond”], [“Europe”, “US”, “US”]]

  **prior_estimator** *BasePrior, optional*
  : The assets’ [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior). It is used to estimate
    the [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) containing estimates of
    expected asset returns, covariance matrix, returns and Cholesky decomposition.
    The default (`None`) is to use `EmpiricalPrior(mu_estimator=EquilibriumMu())`.

  **tau** *float, default=0.05*
  : Tau controls the degree of uncertainty given to the analyst views. A low value
    means high uncertainty and will put less weight on the analyst views compared to
    the prior returns. The default value is `0.05`.
    Other common values used in the literature are `1.0` or the inverse of the
    number of observations.

  **view_confidences** *array-like of floats of shape (n_views,), optional*
  : Instead of using a diagonal uncertainty matrix (Omega) proportional to the prior
    covariance matrix, you can provide the vector of view confidences (between 0
    and 1) as described in Idzorek’s method [[2]](#rec957aca1165-2).

  **risk_free_rate** *float, default=0.0*
  : The risk-free rate.
* **Attributes:**
  **return_distribution_** *ReturnDistribution*
  : Fitted [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) to be used by the optimization
    estimators, containing the asset returns distribution and posterior Black &
    Litterman moments estimation.

  **groups_** *ndarray of shape(n_groups, n_assets)*
  : Assets names and groups converted to an 2D array.

  **views_** *ndarray of shape (n_views,)*
  : The analyst views converted to a ndarray of floats.

  **picking_matrix_** *ndarray of shape (n_views, n_assets)*
  : Picking matrix computed from the views and assets names/groups.

  **prior_estimator_** *BasePrior*
  : Fitted `prior_estimator`.

  **n_features_in_** *int*
  : Number of assets seen during `fit`.

  **feature_names_in_** *ndarray of shape (`n_features_in_`,)*
  : Names of features seen during `fit`. Defined only when `X`
    has feature names that are all strings.

### Methods

| [`fit`](#skfolio.prior.BlackLitterman.fit)(X[, y])            | Fit the Black & Litterman estimator.   |
|-------------------------------------------------------------------------|----------------------------------------|
| [`get_metadata_routing`](#skfolio.prior.BlackLitterman.get_metadata_routing)() | Get metadata routing of this object.   |
| [`get_params`](#skfolio.prior.BlackLitterman.get_params)([deep])     | Get parameters for this estimator.     |
| [`set_params`](#skfolio.prior.BlackLitterman.set_params)(\*\*params) | Set the parameters of this estimator.  |

### References

* <a id='rec957aca1165-1'>**[1]**</a> “Combining investor views with market equilibrium”, The Journal of Fixed Income, Fischer Black and Robert Litterman, 1991.
* <a id='rec957aca1165-2'>**[2]**</a> “A step-by-step guide to the Black-Litterman model : Incorporating user-specified confidence”, Forecasting Expected Returns in the Financial Markets, Idzorek T, 2007.

<a id="skfolio.prior.BlackLitterman.fit"></a>

#### fit(X, y=None, \*\*fit_params)

Fit the Black & Litterman estimator.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.

  **y** *Ignored*
  : Not used, present for API consistency by convention.

  **\*\*fit_params** *dict*
  : Parameters to pass to the underlying estimators.
    Only available if `enable_metadata_routing=True`, which can be
    set by using `sklearn.set_config(enable_metadata_routing=True)`.
    See [Metadata Routing User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) for
    more details.
* **Returns:**
  **self** *BlackLitterman*
  : Fitted estimator.

<a id="skfolio.prior.BlackLitterman.get_metadata_routing"></a>

#### get_metadata_routing()

Get metadata routing of this object.

Please check [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

* **Returns:**
  **routing** *MetadataRequest*
  : A `MetadataRequest` encapsulating
    routing information.

<a id="skfolio.prior.BlackLitterman.get_params"></a>

#### get_params(deep=True)

Get parameters for this estimator.

* **Parameters:**
  **deep** *bool, default=True*
  : If True, will return the parameters for this estimator and
    contained subobjects that are estimators.
* **Returns:**
  **params** *dict*
  : Parameter names mapped to their values.

<a id="skfolio.prior.BlackLitterman.set_params"></a>

#### set_params(\*\*params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects
(such as `Pipeline`). The latter have
parameters of the form `<component>__<parameter>` so that it’s
possible to update each component of a nested object.

* **Parameters:**
  **\*\*params** *dict*
  : Estimator parameters.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.