# index.html.md

<a id="skfolio"></a>

# skfolio

**skfolio** is a Python library for portfolio optimization, factor model construction,
and risk management built on top of scikit-learn. It offers a unified interface and
tools compatible with scikit-learn to build, fine-tune, cross-validate, and stress-test
portfolio models.

It is distributed under the open-source 3-Clause BSD license.

**skfolio** is backed by [Skfolio Labs](https://skfoliolabs.com), which provides
enterprise support and SLAs for institutions.

<link
    rel="preload"
    as="image"
    href="_static/expo.webp"
    imagesrcset="
        \_static/expo-750.webp 750w,
        \_static/expo-1000.webp 1000w,
        \_static/expo.webp 1500w"
    imagesizes="(max-width: 960px) 100vw, 1500px"
    type="image/webp">

<a href="https://skfolio.org/auto_examples/index.html"
   title="Browse the skfolio examples gallery">
    <picture>
        <source
                srcset="
                    \_static/expo-750.webp 750w,
                    \_static/expo-1000.webp 1000w,
                    \_static/expo.webp 1500w"
                sizes="(max-width: 960px) 100vw, 1500px"
                type="image/webp">

        <source
                srcset="
                    \_static/expo-750.jpg 750w,
                    \_static/expo-1000.jpg 1000w,
                    \_static/expo.jpg 1500w"
                sizes="(max-width: 960px) 100vw, 1500px"
                type="image/jpeg">
        <img
                src="_static/expo.jpg"
                alt="Portfolio optimization examples gallery from skfolio"
                width="1500" height="750"
                style="display:block;width:100%;height:auto;"
                loading="eager"
                decoding="async">
    </picture>
</a>

<a id="important-links"></a>

## Important links

- [Examples](https://skfolio.org/auto_examples/index.html)
- [User Guide](https://skfolio.org/user_guide/index.html)
- [API Reference](https://skfolio.org/api.html)
- [GitHub Repo](https://github.com/skfolio/skfolio)
- [Enterprise Support](https://skfoliolabs.com)

<a id="featured-in"></a>

## Featured in

* [Portfolio Optimization: Theory and Application](https://portfoliooptimizationbook.com/) by Daniel P. Palomar, includes Python code examples using skfolio.

<a id="installation"></a>

## Installation

`skfolio` requires Python 3.10 or later and can be installed with:

```bash
pip install -U skfolio
```

See the [installation guide](https://skfolio.org/user_guide/install.html) for the full
dependency list, for conda-forge and for the mixed-integer solvers.

<a id="llm-friendly-documentation"></a>

## LLM-friendly documentation

The documentation follows the [llms.txt convention](https://llmstxt.org/) and
provides token-efficient Markdown alongside the HTML site:

- Start with [llms.txt](https://skfolio.org/llms.txt) to find relevant pages.
- Read only the Markdown pages needed by appending `.md` to their HTML URLs, for example
  [factor_models.html.md](https://skfolio.org/user_guide/factor_models.html.md).
- Use [llms-full.txt](https://skfolio.org/llms-full.txt) only when the complete
  documentation is required in a single file.

<a id="contribution"></a>

## Contribution

We welcome contributions of all kinds. Whether it’s reporting a bug, suggesting an
improvement, or submitting code, your input helps make `skfolio` better. See the
[contributing guide](https://github.com/skfolio/skfolio/blob/main/CONTRIBUTING.md)
to get started.

<a id="key-concepts"></a>

## Key Concepts

Since the development of modern portfolio theory by Markowitz (1952), mean-variance
optimization (MVO) has received considerable attention.

Unfortunately, it faces a number of shortcomings, including high sensitivity to the
input parameters (expected returns and covariance), weight concentration, high turnover,
and poor out-of-sample performance.

It is well-known that naive allocation (1/N, inverse-vol, etc.) tends to outperform
MVO out-of-sample (DeMiguel, 2007).

Numerous approaches have been developed to alleviate these shortcomings (shrinkage,
additional constraints, regularization, uncertainty set, higher moments, Bayesian
approaches, coherent risk measures, left-tail risk optimization, distributionally robust
optimization, factor model, risk-parity, hierarchical clustering, ensemble methods,
pre-selection, etc.).

Given the large number of methods, and the fact that they can be combined, there is a
need for a unified framework with a machine-learning approach to perform model
selection, validation, and parameter tuning while mitigating the risk of data leakage
and overfitting.

This framework is built on scikit-learn’s API.

<a id="available-models"></a>

## Available models

* Portfolio Optimization:
  : * Naive:
      : * Equal-Weighted
        * Inverse-Volatility
        * Random (Dirichlet)
    * Convex:
      : * Mean-Risk
        * Risk Budgeting
        * Maximum Diversification
        * Distributionally Robust CVaR
        * Benchmark Tracker
    * Clustering:
      : * Hierarchical Risk Parity
        * Hierarchical Equal Risk Contribution
        * Schur Complementary Allocation
        * Nested Clusters Optimization
    * Ensemble Methods:
      : * Stacking Optimization
* Prior Estimator:
  : * Empirical
    * Characteristics-Based Cross-Sectional Factor Model:
      : * 46 descriptors across 17 families (e.g. value, size, momentum, profitability)
        * Factor Exposures
        * Cross-Sectional Regression
        * Alpha Estimators
        * Forecast Evaluation
        * Ex-post and Ex-ante Attribution
    * Time-Series Factor Model
    * Black & Litterman
    * Synthetic Data (Stress Test, Factor Stress Test)
    * Entropy Pooling
    * Opinion Pooling
* Expected Returns Estimator:
  : * Empirical
    * Exponentially Weighted
    * Equilibrium
    * Shrinkage
* Covariance Estimator:
  : * Empirical
    * Gerber
    * Denoising
    * Detoning
    * Exponentially Weighted
    * Regime-Adjusted Exponentially Weighted
    * Ledoit-Wolf
    * Oracle Approximating Shrinkage
    * Shrunk Covariance
    * Graphical Lasso CV
    * Implied Covariance
* Variance Estimator:
  : * Empirical
    * Exponentially Weighted
    * Regime-Adjusted Exponentially Weighted
* Distance Estimator:
  : * Pearson Distance
    * Kendall Distance
    * Spearman Distance
    * Covariance Distance (based on any of the above covariance estimators)
    * Distance Correlation
    * Variation of Information
* Distribution Estimator:
  : * Univariate:
      : * Gaussian
        * Student’s t
        * Johnson Su
        * Normal Inverse Gaussian
    * Bivariate Copula
      : * Gaussian Copula
        * Student’s t Copula
        * Clayton Copula
        * Gumbel Copula
        * Joe Copula
        * Independent Copula
    * Multivariate
      : * Vine Copula (Regular, Centered, Clustered, Conditional Sampling)
* Uncertainty Set Estimator:
  : * On Expected Returns:
      : * Empirical
        * Circular Bootstrap
    * On Covariance:
      : * Empirical
        * Circular Bootstrap
* Pre-Selection Transformers:
  : * Non-Dominated Selection
    * Select K Extremes (Best or Worst)
    * Drop Highly Correlated Assets
    * Select Non-Expiring Assets
    * Select Complete Assets (handle late inception, delisting, etc.)
    * Drop Zero Variance
* Cross-Sectional Transformers:
  : * Standard Scaler (z-score)
    * Percentile Rank Scaler
    * Gaussian Rank Scaler (rank gaussianization)
    * Winsorizer (percentile clipping)
    * Tanh Shrinker (smooth outlier shrinkage)
* Cross-Validation and Model Selection:
  : * Compatible with all `sklearn` methods (KFold, etc.)
    * Walk Forward
    * Combinatorial Purged Cross-Validation
    * Multiple Randomized Cross-Validation
    * Covariance Forecast Evaluation
    * Online Predict and Online Score
* Hyper-Parameter Tuning:
  : * Compatible with all `sklearn` methods (GridSearchCV, RandomizedSearchCV)
    * Online Grid Search and Online Randomized Search
* Risk Measures:
  : * Variance
    * Semi-Variance
    * Mean Absolute Deviation
    * First Lower Partial Moment
    * CVaR (Conditional Value at Risk)
    * EVaR (Entropic Value at Risk)
    * Worst Realization
    * CDaR (Conditional Drawdown at Risk)
    * Maximum Drawdown
    * Average Drawdown
    * EDaR (Entropic Drawdown at Risk)
    * Ulcer Index
    * Gini Mean Difference
    * Value at Risk
    * Drawdown at Risk
    * Entropic Risk Measure
    * Fourth Central Moment
    * Fourth Lower Partial Moment
    * Skew
    * Kurtosis
* Optimization Features:
  : * Minimize Risk
    * Maximize Returns
    * Maximize Utility
    * Maximize Ratio
    * Transaction Costs
    * Management Fees
    * L1 and L2 Regularization
    * Weight Constraints
    * Group Constraints
    * Budget Constraints
    * Tracking Error Constraints
    * Turnover Constraints
    * Cardinality and Group Cardinality Constraints
    * Threshold (Long and Short) Constraints

<a id="quickstart"></a>

## Quickstart

The code snippets below are designed to introduce the functionality of `skfolio` so you
can start using it quickly. It follows the same API as scikit-learn.

<a id="imports"></a>

### Imports

```python
from sklearn import set_config
from sklearn.model_selection import (
    GridSearchCV,
    KFold,
    RandomizedSearchCV,
    train_test_split,
)
from sklearn.pipeline import Pipeline
from scipy.stats import loguniform

from skfolio import RatioMeasure, RiskMeasure
from skfolio.datasets import (
    load_factors_dataset,
    load_sp500_dataset,
    make_synthetic_characteristics,
)
from skfolio.descriptor import (
    BookToPrice,
    CashFlowToPrice,
    EWMarketBeta,
    EWMomentum,
    EWResidualVolatility,
    EWVolatility,
    LogMarketCap,
    SalesToPrice,
)
from skfolio.distribution import VineCopula
from skfolio.factor_exposure import (
    DerivedFactor,
    FixedWeightedFactor,
    GlobalFactor,
    OneHotCategoricalFactors,
)
from skfolio.model_selection import (
    CombinatorialPurgedCV,
    WalkForward,
    cross_val_predict,
)
from skfolio.moments import (
    DenoiseCovariance,
    DetoneCovariance,
    EWMu,
    GerberCovariance,
    ShrunkMu,
)
from skfolio.optimization import (
    MeanRisk,
    HierarchicalRiskParity,
    NestedClustersOptimization,
    ObjectiveFunction,
    RiskBudgeting,
)
from skfolio.pre_selection import SelectKExtremes
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import (
    BlackLitterman,
    CharacteristicsFactorModel,
    EmpiricalPrior,
    EntropyPooling,
    TimeSeriesFactorModel,
    OpinionPooling,
    SyntheticData,
)
from skfolio.uncertainty_set import BootstrapMuUncertaintySet
```

<a id="load-dataset"></a>

### Load Dataset

```python
prices = load_sp500_dataset()
```

<a id="train-test-split"></a>

### Train/Test split

```python
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="minimum-variance"></a>

### Minimum Variance

```python
model = MeanRisk()
```

<a id="fit-on-training-set"></a>

### Fit on Training Set

```python
model.fit(X_train)

print(model.weights_)
```

<a id="predict-on-test-set"></a>

### Predict on Test Set

```python
portfolio = model.predict(X_test)

print(portfolio.annualized_sharpe_ratio)
print(portfolio.summary())
```

<a id="maximum-sortino-ratio"></a>

### Maximum Sortino Ratio

```python
model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    risk_measure=RiskMeasure.SEMI_VARIANCE,
)
```

<a id="denoised-covariance-shrunk-expected-returns"></a>

### Denoised Covariance & Shrunk Expected Returns

```python
model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=EmpiricalPrior(
        mu_estimator=ShrunkMu(), covariance_estimator=DenoiseCovariance()
    ),
)
```

<a id="uncertainty-set-on-expected-returns"></a>

### Uncertainty Set on Expected Returns

```python
model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    mu_uncertainty_set_estimator=BootstrapMuUncertaintySet(),
)
```

<a id="weight-constraints-transaction-costs"></a>

### Weight Constraints & Transaction Costs

```python
model = MeanRisk(
    min_weights={"AAPL": 0.10, "JPM": 0.05},
    max_weights=0.8,
    transaction_costs={"AAPL": 0.0001, "RRC": 0.0002},
    groups=[
        ["Equity"] * 3 + ["Fund"] * 5 + ["Bond"] * 12,
        ["US"] * 2 + ["Europe"] * 8 + ["Japan"] * 10,
    ],
    linear_constraints=[
        "Equity <= 0.5 * Bond",
        "US >= 0.1",
        "Europe >= 0.5 * Fund",
        "Japan <= 1",
    ],
)
model.fit(X_train)
```

<a id="risk-parity-on-cvar"></a>

### Risk Parity on CVaR

```python
model = RiskBudgeting(risk_measure=RiskMeasure.CVAR)
```

<a id="risk-parity-gerber-covariance"></a>

### Risk Parity & Gerber Covariance

```python
model = RiskBudgeting(
    prior_estimator=EmpiricalPrior(covariance_estimator=GerberCovariance())
)
```

<a id="nested-cluster-optimization-with-cross-validation-and-parallelization"></a>

### Nested Cluster Optimization with Cross-Validation and Parallelization

```python
model = NestedClustersOptimization(
    inner_estimator=MeanRisk(risk_measure=RiskMeasure.CVAR),
    outer_estimator=RiskBudgeting(risk_measure=RiskMeasure.VARIANCE),
    cv=KFold(),
    n_jobs=-1,
)
```

<a id="randomized-search-of-the-l2-norm"></a>

### Randomized Search of the L2 Norm

```python
randomized_search = RandomizedSearchCV(
    estimator=MeanRisk(),
    cv=WalkForward(train_size=252, test_size=60),
    param_distributions={
        "l2_coef": loguniform(1e-3, 1e-1),
    },
)
randomized_search.fit(X_train)

best_model = randomized_search.best_estimator_

print(best_model.weights_)
```

<a id="grid-search-on-embedded-parameters"></a>

### Grid Search on Embedded Parameters

```python
model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    risk_measure=RiskMeasure.VARIANCE,
    prior_estimator=EmpiricalPrior(mu_estimator=EWMu(half_life=40)),
)

print(model.get_params(deep=True))

gs = GridSearchCV(
    estimator=model,
    cv=KFold(n_splits=5, shuffle=False),
    n_jobs=-1,
    param_grid={
        "risk_measure": [
            RiskMeasure.VARIANCE,
            RiskMeasure.CVAR,
            RiskMeasure.CDAR,
        ],
        "prior_estimator__mu_estimator__half_life": [10, 20, 30, 40],
    },
)
gs.fit(X)

best_model = gs.best_estimator_

print(best_model.weights_)
```

<a id="black-litterman-model"></a>

### Black & Litterman Model

```python
views = ["AAPL - BBY == 0.03 ", "CVX - KO == 0.04", "MSFT == 0.06 "]
model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=BlackLitterman(views=views),
)
```

<a id="characteristics-based-factor-model"></a>

### Characteristics-Based Factor Model

```python
month = 21
quarter = 3 * month
half_year = 6 * month
year = 12 * month

characteristics = make_synthetic_characteristics(
    n_assets=500,
    n_observations=2000,
    random_state=0,
)

# Global factor
market_factor = GlobalFactor(family="market")

# Industry factors
industry_factors = OneHotCategoricalFactors(
    category="industry",
    family="industry",
)

# Style factors
beta_factor = FixedWeightedFactor(
    descriptors=[
        ("market_beta", EWMarketBeta(half_life=year)),
    ],
    transform_by_group="industry",
)

momentum_factor = FixedWeightedFactor(
    descriptors=[
        ("momentum", EWMomentum(half_life=half_year, skip=month)),
    ],
    transform_by_group="industry",
)

size_factor = FixedWeightedFactor(
    descriptors=[("log_market_cap", LogMarketCap())],
    transform_by_group="industry",
)

non_linear_size_factor = DerivedFactor(
    source="size",
    func=lambda x: x**3,
    transform_by_group="industry",
)

value_factor = FixedWeightedFactor(
    descriptors=[
        ("book_to_price", BookToPrice()),
        ("sales_to_price", SalesToPrice()),
        ("cash_flow_to_price", CashFlowToPrice()),
    ],
    weights=[0.8, 0.1, 0.1],
    transform_by_group="industry",
)

volatility_factor = FixedWeightedFactor(
    descriptors=[
        ("vol", EWVolatility(half_life=quarter)),
        (
            "residual_vol",
            EWResidualVolatility(
                half_life=quarter,
                beta_half_life=quarter,
            ),
        ),
    ],
    transform_by_group="industry",
)

# Characteristics factor model
model = CharacteristicsFactorModel(
    factors=[
        ("market", market_factor),
        ("industry", industry_factors),
        ("beta", beta_factor),
        ("momentum", momentum_factor),
        ("size", size_factor),
        ("non_linear_size", non_linear_size_factor),
        ("value", value_factor),
        ("volatility", volatility_factor),
    ],
    neutralize_against={
        "volatility": ["beta"],
        "non_linear_size": ["size"],
    },
    constrained_families=[("industry", None)],
    exposure_lag=1,
    inv_idio_variance_weight_shrinkage=0.5,
    n_jobs=-1,
)

model.fit(characteristics=characteristics)

factor_model = model.factor_model_
print(factor_model.summary())
```

For complete workflows, see the [Factor Models user guide](https://skfolio.org/user_guide/factor_models.html) and the [Factor Models tutorials](https://skfolio.org/auto_examples/factor_models/index.html).

<a id="time-series-factor-model"></a>

### Time-Series Factor Model

```python
factor_prices = load_factors_dataset()

X, factors = prices_to_returns(prices, factor_prices)
X_train, X_test, factors_train, factors_test = train_test_split(
    X, factors, test_size=0.33, shuffle=False
)

model = MeanRisk(prior_estimator=TimeSeriesFactorModel())
model.fit(X_train, factors=factors_train)

print(model.weights_)

portfolio = model.predict(X_test)

print(portfolio.calmar_ratio)
print(portfolio.summary())
```

<a id="time-series-factor-model-covariance-detoning"></a>

### Time-Series Factor Model & Covariance Detoning

```python
model = MeanRisk(
    prior_estimator=TimeSeriesFactorModel(
        factor_prior_estimator=EmpiricalPrior(covariance_estimator=DetoneCovariance())
    )
)
```

<a id="black-litterman-time-series-factor-model"></a>

### Black & Litterman Time-Series Factor Model

```python
factor_views = ["MTUM - QUAL == 0.03 ", "VLUE == 0.06"]
model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=TimeSeriesFactorModel(
        factor_prior_estimator=BlackLitterman(views=factor_views),
    ),
)
```

<a id="pre-selection-pipeline"></a>

### Pre-Selection Pipeline

```python
set_config(transform_output="pandas")
model = Pipeline(
    [
        ("pre_selection", SelectKExtremes(k=10, highest=True)),
        ("optimization", MeanRisk()),
    ]
)
model.fit(X_train)

portfolio = model.predict(X_test)
```

<a id="k-fold-cross-validation"></a>

### K-fold Cross-Validation

```python
model = MeanRisk()
mpp = cross_val_predict(model, X_test, cv=KFold(n_splits=5))
# mpp is the predicted MultiPeriodPortfolio object composed of 5 Portfolios (1 per testing fold)

mpp.plot_cumulative_returns()
print(mpp.summary())
```

<a id="combinatorial-purged-cross-validation"></a>

### Combinatorial Purged Cross-Validation

```python
model = MeanRisk()

cv = CombinatorialPurgedCV(n_folds=10, n_test_folds=2)

print(cv.summary(X_train))

population = cross_val_predict(model, X_train, cv=cv)

population.plot_distribution(
    measure_list=[RatioMeasure.SHARPE_RATIO, RatioMeasure.SORTINO_RATIO]
)
population.plot_cumulative_returns()
print(population.summary())
```

<a id="minimum-cvar-optimization-on-synthetic-returns"></a>

### Minimum CVaR Optimization on Synthetic Returns

```python
vine = VineCopula(log_transform=True, n_jobs=-1)
prior = SyntheticData(distribution_estimator=vine, n_samples=2000)
model = MeanRisk(risk_measure=RiskMeasure.CVAR, prior_estimator=prior)
model.fit(X)
print(model.weights_)
```

<a id="stress-test"></a>

### Stress Test

```python
vine = VineCopula(log_transform=True, central_assets=["BAC"], n_jobs=-1)
vine.fit(X)
X_stressed = vine.sample(n_samples=10_000, conditioning = {"BAC": -0.2})
ptf_stressed = model.predict(X_stressed)
```

<a id="minimum-cvar-optimization-on-synthetic-factors"></a>

### Minimum CVaR Optimization on Synthetic Factors

```python
vine = VineCopula(central_assets=["QUAL"], log_transform=True, n_jobs=-1)
factor_prior = SyntheticData(
    distribution_estimator=vine,
    n_samples=10_000,
    sample_args=dict(conditioning={"QUAL": -0.2}),
)
factor_model = TimeSeriesFactorModel(factor_prior_estimator=factor_prior)
model = MeanRisk(risk_measure=RiskMeasure.CVAR, prior_estimator=factor_model)
model.fit(X, factors=factors)
print(model.weights_)
```

<a id="factor-stress-test"></a>

### Factor Stress Test

```python
factor_model.set_params(factor_prior_estimator__sample_args=dict(
    conditioning={"QUAL": -0.5}
))
factor_model.fit(X, factors=factors)
stressed_dist = factor_model.return_distribution_
stressed_ptf = model.predict(stressed_dist)
```

<a id="entropy-pooling"></a>

### Entropy Pooling

```python
entropy_pooling = EntropyPooling(
    mean_views=[
        "JPM == -0.002",
        "PG >= LLY",
        "BAC >= prior(BAC) * 1.2",
    ],
    cvar_views=[
        "GE == 0.08",
    ],
)
entropy_pooling.fit(X)
print(entropy_pooling.relative_entropy_)
print(entropy_pooling.effective_number_of_scenarios_)
print(entropy_pooling.return_distribution_.sample_weight)
```

<a id="cvar-hierarchical-risk-parity-optimization-on-entropy-pooling"></a>

### CVaR Hierarchical Risk Parity optimization on Entropy Pooling

```python
entropy_pooling = EntropyPooling(cvar_views=["GE == 0.08"])
model = HierarchicalRiskParity(
    risk_measure=RiskMeasure.CVAR,
    prior_estimator=entropy_pooling
)
model.fit(X)
print(model.weights_)
```

<a id="stress-test-with-entropy-pooling-on-factor-synthetic-data"></a>

### Stress Test with Entropy Pooling on Factor Synthetic Data

```python
# Regular Vine Copula and sampling of 100,000 synthetic factor returns
factor_synth = SyntheticData(
    n_samples=100_000,
    distribution_estimator=VineCopula(log_transform=True, n_jobs=-1, random_state=0)
)

# Entropy Pooling by imposing a CVaR-95% of 10% on the Quality factor
factor_entropy_pooling = EntropyPooling(
    prior_estimator=factor_synth,
    cvar_views=["QUAL == 0.10"],
)

factor_model = TimeSeriesFactorModel(factor_prior_estimator=factor_entropy_pooling)
factor_model.fit(X, factors=factors)

# We retrieve the stressed distribution:
stressed_dist = factor_model.return_distribution_

# We stress-test our portfolio:
stressed_ptf = model.predict(stressed_dist)
```

<a id="opinion-pooling"></a>

### Opinion Pooling

```python
# We consider two expert opinions, each generated via Entropy Pooling with
# user-defined views.
# We assign probabilities of 40% to Expert 1, 50% to Expert 2, and by default
# the remaining 10% is allocated to the prior distribution:
opinion_1 = EntropyPooling(cvar_views=["AMD == 0.10"])
opinion_2 = EntropyPooling(
    mean_views=["AMD >= BAC", "JPM <= prior(JPM) * 0.8"],
    cvar_views=["GE == 0.12"],
)

opinion_pooling = OpinionPooling(
    estimators=[("opinion_1", opinion_1), ("opinion_2", opinion_2)],
    opinion_probabilities=[0.4, 0.5],
)

opinion_pooling.fit(X)
```

<a id="docker"></a>

## Docker

You can also spin up a reproducible JupyterLab environment using Docker:

Build the image:

```default
docker build -t skfolio-jupyterlab .
```

Run the container:

```default
docker run -p 8888:8888 -v <path-to-your-folder-containing-data>:/app/data -it skfolio-jupyterlab
```

Browse:

Open `localhost:8888/lab` and start using `skfolio`

<a id="recognition"></a>

## Recognition

We would like to thank all contributors to our direct dependencies, such as
[scikit-learn](https://github.com/scikit-learn/scikit-learn) and [cvxpy](https://github.com/cvxpy/cvxpy), as well as the contributors of the following resources:

> * PyPortfolioOpt
> * Riskfolio-Lib
> * scikit-portfolio
> * statsmodels
> * rsome
> * [Microprediction](https://github.com/microprediction) (Peter Cotton)
> * [Portfolio Optimization Book](https://portfoliooptimizationbook.com/) (Daniel P. Palomar)
> * *The Elements of Quantitative Investing* (Giuseppe Paleologo)
> * [quantresearch.org](https://quantresearch.org) (Marcos López de Prado)
> * gautier.marti.ai (Gautier Marti)

<a id="citation"></a>

## Citation

If you use `skfolio` in a scientific publication, we would appreciate citations:

**The library:**

```bibtex
@software{skfolio,
  title     = {skfolio},
  author    = {Delatte, Hugo and Nicolini, Carlo and Manzi, Matteo},
  version   = {1.0.0},
  year      = {2026},
  doi       = {10.5281/zenodo.16148630},
  url       = {https://doi.org/10.5281/zenodo.16148630}
}
```

The above uses the concept DOI, which always resolves to the latest release.
If you need precise reproducibility, especially for journals or conferences that require
it, you can cite the version-specific DOI for the exact release you used. To find it,
go to our [Zenodo project page](https://doi.org/10.5281/zenodo.16148630), locate the
release you wish to reference (e.g. “v1.0.0”), and copy the DOI listed next to that
version.

**The paper:**

```bibtex
@article{nicolini2025skfolio,
  title         = {skfolio: Portfolio Optimization in Python},
  author        = {Nicolini, Carlo and Manzi, Matteo and Delatte, Hugo},
  journal       = {arXiv preprint arXiv:2507.04176},
  year          = {2025},
  eprint        = {2507.04176},
  archivePrefix = {arXiv},
  url           = {https://arxiv.org/abs/2507.04176}
}
```

# api.html.md

<a id="api"></a>

<a id="api-reference"></a>

# API Reference

This is the class and function reference of `skfolio`. Please refer to
the [full user guide](https://skfolio.org/user_guide/index.html.md#user-guide) for further details, as the class and
function raw specifications may not be enough to give full guidelines on their
uses.

<a id="measures-ref"></a>

<a id="module-skfolio.measures"></a>

<a id="skfolio-measures-measures"></a>

## [`skfolio.measures`](https://skfolio.org/api.html.md#module-skfolio.measures): Measures

Module that includes all Measures functions used across `skfolio`.

<a id="base-class"></a>

### Base Class

| [`measures.BaseMeasure`](https://skfolio.org/generated/skfolio.measures.BaseMeasure.html.md#skfolio.measures.BaseMeasure)   | Base Enum of measures.   |
|------------------------------------------------------------------------------------------------------|--------------------------|

<a id="classes"></a>

### Classes

| [`measures.PerfMeasure`](https://skfolio.org/generated/skfolio.measures.PerfMeasure.html.md#skfolio.measures.PerfMeasure)           | Enumeration of performance measures.                                |
|--------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| [`measures.RiskMeasure`](https://skfolio.org/generated/skfolio.measures.RiskMeasure.html.md#skfolio.measures.RiskMeasure)           | Enumeration of risk measures.                                       |
| [`measures.ExtraRiskMeasure`](https://skfolio.org/generated/skfolio.measures.ExtraRiskMeasure.html.md#skfolio.measures.ExtraRiskMeasure) | Enumeration of other risk measures not used in convex optimization. |
| [`measures.RatioMeasure`](https://skfolio.org/generated/skfolio.measures.RatioMeasure.html.md#skfolio.measures.RatioMeasure)         | Enumeration of ratio measures.                                      |

<a id="functions"></a>

### Functions

| [`measures.mean`](https://skfolio.org/generated/skfolio.measures.mean.html.md#skfolio.measures.mean)(returns[, sample_weight])                              | Compute the mean.                                                                       |
|---------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| [`measures.get_cumulative_returns`](https://skfolio.org/generated/skfolio.measures.get_cumulative_returns.html.md#skfolio.measures.get_cumulative_returns)(returns[, ...])    | Compute the cumulative returns from a series of returns.                                |
| [`measures.get_drawdowns`](https://skfolio.org/generated/skfolio.measures.get_drawdowns.html.md#skfolio.measures.get_drawdowns)(returns[, compounded])               | Compute the drawdowns' series from the returns.                                         |
| [`measures.variance`](https://skfolio.org/generated/skfolio.measures.variance.html.md#skfolio.measures.variance)(returns[, biased, ...])                        | Compute the variance (second moment).                                                   |
| [`measures.semi_variance`](https://skfolio.org/generated/skfolio.measures.semi_variance.html.md#skfolio.measures.semi_variance)(returns[, ...])                      | Compute the semi-variance (second lower partial moment).                                |
| [`measures.standard_deviation`](https://skfolio.org/generated/skfolio.measures.standard_deviation.html.md#skfolio.measures.standard_deviation)(returns[, ...])            | Compute the standard-deviation (square root of the second moment).                      |
| [`measures.semi_deviation`](https://skfolio.org/generated/skfolio.measures.semi_deviation.html.md#skfolio.measures.semi_deviation)(returns[, ...])                    | Compute the semi-deviation (square root of the second lower partial moment).            |
| [`measures.third_central_moment`](https://skfolio.org/generated/skfolio.measures.third_central_moment.html.md#skfolio.measures.third_central_moment)(returns[, ...])        | Compute the third central moment.                                                       |
| [`measures.fourth_central_moment`](https://skfolio.org/generated/skfolio.measures.fourth_central_moment.html.md#skfolio.measures.fourth_central_moment)(returns[, ...])      | Compute the Fourth central moment.                                                      |
| [`measures.fourth_lower_partial_moment`](https://skfolio.org/generated/skfolio.measures.fourth_lower_partial_moment.html.md#skfolio.measures.fourth_lower_partial_moment)(returns) | Compute the fourth lower partial moment.                                                |
| [`measures.skew`](https://skfolio.org/generated/skfolio.measures.skew.html.md#skfolio.measures.skew)(returns[, sample_weight])                              | Compute the Skew.                                                                       |
| [`measures.kurtosis`](https://skfolio.org/generated/skfolio.measures.kurtosis.html.md#skfolio.measures.kurtosis)(returns[, sample_weight])                      | Compute the Kurtosis.                                                                   |
| [`measures.cvar`](https://skfolio.org/generated/skfolio.measures.cvar.html.md#skfolio.measures.cvar)(returns[, beta, sample_weight])                        | Compute the historical CVaR (conditional value at risk).                                |
| [`measures.mean_absolute_deviation`](https://skfolio.org/generated/skfolio.measures.mean_absolute_deviation.html.md#skfolio.measures.mean_absolute_deviation)(returns[, ...])  | Compute the mean absolute deviation (MAD).                                              |
| [`measures.value_at_risk`](https://skfolio.org/generated/skfolio.measures.value_at_risk.html.md#skfolio.measures.value_at_risk)(returns[, beta, ...])                | Compute the historical value at risk (VaR).                                             |
| [`measures.worst_realization`](https://skfolio.org/generated/skfolio.measures.worst_realization.html.md#skfolio.measures.worst_realization)(returns)                     | Compute the worst realization (worst return).                                           |
| [`measures.first_lower_partial_moment`](https://skfolio.org/generated/skfolio.measures.first_lower_partial_moment.html.md#skfolio.measures.first_lower_partial_moment)(returns)   | Compute the first lower partial moment.                                                 |
| [`measures.entropic_risk_measure`](https://skfolio.org/generated/skfolio.measures.entropic_risk_measure.html.md#skfolio.measures.entropic_risk_measure)(returns[, ...])      | Compute the entropic risk measure.                                                      |
| [`measures.evar`](https://skfolio.org/generated/skfolio.measures.evar.html.md#skfolio.measures.evar)(returns[, beta])                                       | Compute the EVaR (entropic value at risk) and its associated risk aversion.             |
| [`measures.drawdown_at_risk`](https://skfolio.org/generated/skfolio.measures.drawdown_at_risk.html.md#skfolio.measures.drawdown_at_risk)(drawdowns[, beta])             | Compute the Drawdown at risk.                                                           |
| [`measures.cdar`](https://skfolio.org/generated/skfolio.measures.cdar.html.md#skfolio.measures.cdar)(drawdowns[, beta])                                     | Compute the historical CDaR (conditional drawdown at risk).                             |
| [`measures.max_drawdown`](https://skfolio.org/generated/skfolio.measures.max_drawdown.html.md#skfolio.measures.max_drawdown)(drawdowns)                             | Compute the maximum drawdown.                                                           |
| [`measures.average_drawdown`](https://skfolio.org/generated/skfolio.measures.average_drawdown.html.md#skfolio.measures.average_drawdown)(drawdowns)                     | Compute the average drawdown.                                                           |
| [`measures.edar`](https://skfolio.org/generated/skfolio.measures.edar.html.md#skfolio.measures.edar)(drawdowns[, beta])                                     | Compute the EDaR (entropic drawdown at risk).                                           |
| [`measures.ulcer_index`](https://skfolio.org/generated/skfolio.measures.ulcer_index.html.md#skfolio.measures.ulcer_index)(drawdowns)                               | Compute the Ulcer index.                                                                |
| [`measures.gini_mean_difference`](https://skfolio.org/generated/skfolio.measures.gini_mean_difference.html.md#skfolio.measures.gini_mean_difference)(returns)               | Compute the Gini mean difference (GMD).                                                 |
| [`measures.owa_gmd_weights`](https://skfolio.org/generated/skfolio.measures.owa_gmd_weights.html.md#skfolio.measures.owa_gmd_weights)(n_observations)                  | Compute the OWA weights used for the Gini mean difference (GMD) computation.            |
| [`measures.effective_number_assets`](https://skfolio.org/generated/skfolio.measures.effective_number_assets.html.md#skfolio.measures.effective_number_assets)(weights)         | Compute the effective number of assets, defined as the inverse of the Herfindahl index. |
| [`measures.correlation`](https://skfolio.org/generated/skfolio.measures.correlation.html.md#skfolio.measures.correlation)(X[, sample_weight])                      | Compute the correlation matrix.                                                         |

<a id="portfolio-ref"></a>

<a id="module-skfolio.portfolio"></a>

<a id="skfolio-portfolio-portfolio"></a>

## [`skfolio.portfolio`](https://skfolio.org/api.html.md#module-skfolio.portfolio): Portfolio

Portfolio module.
`Portfolio` and `MultiPeriodPortfolio` objects are returned by the `predict` method of
Optimization estimators.
They must be consistent with the convex optimization problems, meaning that `Portfolio`
is the dot product of the assets weights with the assets returns and
`MultiPeriodPortfolio` is a list of `Portfolio`.

<a id="id1"></a>

### Base Class

| [`portfolio.BasePortfolio`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio)   | Base Portfolio class for all portfolios in skfolio.   |
|------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|

<a id="id2"></a>

### Classes

| [`portfolio.Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio)                       | Portfolio class.                                           |
|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------|
| [`portfolio.FailedPortfolio`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio)           | Portfolio object returned when an optimization step fails. |
| [`portfolio.MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) | Multi-Period Portfolio class.                              |

<a id="population-ref"></a>

<a id="module-skfolio.population"></a>

<a id="skfolio-population-population"></a>

## [`skfolio.population`](https://skfolio.org/api.html.md#module-skfolio.population): Population

Population module.

<a id="id3"></a>

### Classes

| [`population.Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population)   | Population Class.   |
|--------------------------------------------------------------------------------------------------------|---------------------|

<a id="containers-ref"></a>

<a id="module-skfolio.containers"></a>

<a id="skfolio-containers-containers"></a>

## [`skfolio.containers`](https://skfolio.org/api.html.md#module-skfolio.containers): Containers

Containers module.

<a id="id4"></a>

### Classes

| [`containers.AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)         | Container for aligned cross-sectional asset data.   |
|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| [`containers.AssetPanelView`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView) | Observation-sliced view into an `AssetPanel`.       |

<a id="field-base-class"></a>

### Field Base Class

| [`containers.BaseField`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField)               | Base class for fields stored in an `AssetPanel`.               |
|------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| [`containers.Field2D`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D)                   | Numeric 2D field with axes (observations, assets).             |
| [`containers.Field3D`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D)                   | Numeric 3D field with axes (observations, assets, third_axis). |
| [`containers.FieldCategorical`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical) | Integer-coded categorical 2D field.                            |

<a id="enum"></a>

### Enum

| [`containers.InactivePolicy`](https://skfolio.org/generated/skfolio.containers.InactivePolicy.html.md#skfolio.containers.InactivePolicy)   | Validation policy for values outside an `AssetPanel` active universe.   |
|----------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|

<a id="id5"></a>

### Functions

| [`containers.concat`](https://skfolio.org/generated/skfolio.containers.concat.html.md#skfolio.containers.concat)(panels, \*[, ...])   | Concatenate panels along the observation axis.   |
|-------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|

<a id="base-ref"></a>

<a id="module-skfolio.base"></a>

<a id="skfolio-base-base-estimators"></a>

## [`skfolio.base`](https://skfolio.org/api.html.md#module-skfolio.base): Base Estimators

Base classes for all estimators and various utility functions.

<a id="id6"></a>

### Classes

| [`base.BaseAssetPanelTransformer`](https://skfolio.org/generated/skfolio.base.BaseAssetPanelTransformer.html.md#skfolio.base.BaseAssetPanelTransformer)   | Base class for estimators that transform asset panel data.   |
|--------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| [`base.BaseComposition`](https://skfolio.org/generated/skfolio.base.BaseComposition.html.md#skfolio.base.BaseComposition)                       | Handles parameter management for ensemble estimators.        |

<a id="optimization-base-ref"></a>

<a id="module-skfolio.optimization"></a>

<a id="skfolio-optimization-base-base-optimization-estimator"></a>

## `skfolio.optimization.base`: Base Optimization Estimator

Optimization module.

<a id="id7"></a>

### Classes

| [`optimization.BaseOptimization`](https://skfolio.org/generated/skfolio.optimization.BaseOptimization.html.md#skfolio.optimization.BaseOptimization)   | Base class for all portfolio optimizations in skfolio.   |
|------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|

<a id="optimization-naive-ref"></a>

<a id="module-skfolio.optimization.naive"></a>

<a id="skfolio-optimization-naive-naive-optimization-estimators"></a>

## [`skfolio.optimization.naive`](https://skfolio.org/api.html.md#module-skfolio.optimization.naive): Naive Optimization Estimators

Naive Optimization module.

<a id="id8"></a>

### Classes

| [`optimization.EqualWeighted`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted)         | Equally Weighted estimator.   |
|------------------------------------------------------------------------------------------------------------------------|-------------------------------|
| [`optimization.InverseVolatility`](https://skfolio.org/generated/skfolio.optimization.InverseVolatility.html.md#skfolio.optimization.InverseVolatility) | Inverse Volatility estimator. |
| [`optimization.Random`](https://skfolio.org/generated/skfolio.optimization.Random.html.md#skfolio.optimization.Random)                       | Random weight estimator.      |

<a id="optimization-convex-ref"></a>

<a id="module-skfolio.optimization.convex"></a>

<a id="skfolio-optimization-convex-convex-optimization-estimators"></a>

## [`skfolio.optimization.convex`](https://skfolio.org/api.html.md#module-skfolio.optimization.convex): Convex Optimization Estimators

Convex Optimization module.

<a id="id9"></a>

### Enum

| [`optimization.ObjectiveFunction`](https://skfolio.org/generated/skfolio.optimization.ObjectiveFunction.html.md#skfolio.optimization.ObjectiveFunction)   | Enumeration of objective functions.   |
|--------------------------------------------------------------------------------------------------------------------------|---------------------------------------|

<a id="id10"></a>

### Classes

| [`optimization.ConvexOptimization`](https://skfolio.org/generated/skfolio.optimization.ConvexOptimization.html.md#skfolio.optimization.ConvexOptimization)                 | Base class for all convex optimization estimators in skfolio.   |
|------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
| [`optimization.MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk)                                     | Mean-Risk Optimization estimator.                               |
| [`optimization.BenchmarkTracker`](https://skfolio.org/generated/skfolio.optimization.BenchmarkTracker.html.md#skfolio.optimization.BenchmarkTracker)                     | Benchmark Tracker Optimization estimator.                       |
| [`optimization.RiskBudgeting`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting)                           | Risk Budgeting Optimization estimator.                          |
| [`optimization.MaximumDiversification`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification)         | Maximum Diversification Optimization estimator.                 |
| [`optimization.DistributionallyRobustCVaR`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR) | Distributionally Robust CVaR.                                   |

<a id="optimization-cluster-ref"></a>

<a id="module-skfolio.optimization.cluster"></a>

<a id="skfolio-optimization-cluster-clustering-optimization-estimators"></a>

## [`skfolio.optimization.cluster`](https://skfolio.org/api.html.md#module-skfolio.optimization.cluster): Clustering Optimization Estimators

Cluster Optimization module.

<a id="id11"></a>

### Classes

| [`optimization.BaseHierarchicalOptimization`](https://skfolio.org/generated/skfolio.optimization.BaseHierarchicalOptimization.html.md#skfolio.optimization.BaseHierarchicalOptimization)           | Base Hierarchical Clustering Optimization estimator.   |
|--------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
| [`optimization.HierarchicalRiskParity`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity)                       | Hierarchical Risk Parity estimator.                    |
| [`optimization.HierarchicalEqualRiskContribution`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution) | Hierarchical Equal Risk Contribution estimator.        |
| [`optimization.SchurComplementary`](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#skfolio.optimization.SchurComplementary)                               | Schur Complementary Allocation estimator.              |
| [`optimization.NestedClustersOptimization`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization)               | Nested Clusters Optimization estimator.                |

<a id="optimization-ensemble-ref"></a>

<a id="module-skfolio.optimization.ensemble"></a>

<a id="skfolio-optimization-ensemble-ensemble-optimization-estimators"></a>

## [`skfolio.optimization.ensemble`](https://skfolio.org/api.html.md#module-skfolio.optimization.ensemble): Ensemble Optimization Estimators

Ensemble Optimization module.

<a id="id12"></a>

### Classes

| [`optimization.StackingOptimization`](https://skfolio.org/generated/skfolio.optimization.StackingOptimization.html.md#skfolio.optimization.StackingOptimization)   | Stack of optimizations with a final optimization.   |
|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|

<a id="prior-ref"></a>

<a id="module-skfolio.prior"></a>

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

## [`skfolio.prior`](https://skfolio.org/api.html.md#module-skfolio.prior): Prior Estimators

Prior module.

<a id="model-dataclass"></a>

### Model Dataclass

| [`prior.ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution)   | Return distribution estimated by a prior estimator.      |
|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
| [`prior.FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel)                 | Factor model decomposition of asset returns.             |
| [`prior.CovarianceSqrt`](https://skfolio.org/generated/skfolio.prior.CovarianceSqrt.html.md#skfolio.prior.CovarianceSqrt)           | Matrix square root decomposition of a covariance matrix. |

<a id="id13"></a>

### Base Class

| [`prior.BasePrior`](https://skfolio.org/generated/skfolio.prior.BasePrior.html.md#skfolio.prior.BasePrior)   | Base class for all prior estimators in skfolio.   |
|--------------------------------------------------------------------------------------------|---------------------------------------------------|

<a id="id14"></a>

### Classes

| [`prior.EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior)                         | Empirical Prior estimator.                          |
|----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| [`prior.BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman)                         | Black & Litterman estimator.                        |
| [`prior.TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel)           | Time-series factor model estimator.                 |
| [`prior.CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel) | Characteristics-based cross-sectional factor model. |
| [`prior.SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData)                           | Synthetic Data Estimator.                           |
| [`prior.EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling)                         | Entropy Pooling estimator.                          |
| [`prior.OpinionPooling`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling)                         | Opinion Pooling estimator.                          |

<a id="loading-matrix-classes-for-factor-models"></a>

### Loading Matrix Classes for Factor Models

| [`prior.BaseLoadingMatrix`](https://skfolio.org/generated/skfolio.prior.BaseLoadingMatrix.html.md#skfolio.prior.BaseLoadingMatrix)             | Base class for all Loading Matrix estimators.   |
|----------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| [`prior.LoadingMatrixRegression`](https://skfolio.org/generated/skfolio.prior.LoadingMatrixRegression.html.md#skfolio.prior.LoadingMatrixRegression) | Loading Matrix Regression estimator.            |

<a id="factor-model-ref"></a>

<a id="module-skfolio.descriptor"></a>

<a id="factor-model-components"></a>

## Factor Model Components

Descriptors that map `AssetPanel` columns to factor characteristics.

<a id="descriptor-base-classes"></a>

### Descriptor Base Classes

| [`descriptor.BaseDescriptor`](https://skfolio.org/generated/skfolio.descriptor.BaseDescriptor.html.md#skfolio.descriptor.BaseDescriptor)   | Base class for all descriptor transformers.   |
|----------------------------------------------------------------------------------------------------------------|-----------------------------------------------|

<a id="descriptors"></a>

### Descriptors

| [`descriptor.AccrualsCashFlow`](https://skfolio.org/generated/skfolio.descriptor.AccrualsCashFlow.html.md#skfolio.descriptor.AccrualsCashFlow)                             | Cash-flow statement accruals descriptor.                                                                                       |
|----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| [`descriptor.AnalystDispersionToPrice`](https://skfolio.org/generated/skfolio.descriptor.AnalystDispersionToPrice.html.md#skfolio.descriptor.AnalystDispersionToPrice)             | Analyst forecast dispersion to price descriptor.                                                                               |
| [`descriptor.AssetTurnover`](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#skfolio.descriptor.AssetTurnover)                                   | Asset turnover descriptor.                                                                                                     |
| [`descriptor.AssetsGrowthRate`](https://skfolio.org/generated/skfolio.descriptor.AssetsGrowthRate.html.md#skfolio.descriptor.AssetsGrowthRate)                             | Asset growth rate descriptor.                                                                                                  |
| [`descriptor.BookLeverage`](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#skfolio.descriptor.BookLeverage)                                     | Book leverage descriptor.                                                                                                      |
| [`descriptor.BookToPrice`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice)                                       | Book-to-price ratio descriptor.                                                                                                |
| [`descriptor.CapexToAssetsChangeInIntensity`](https://skfolio.org/generated/skfolio.descriptor.CapexToAssetsChangeInIntensity.html.md#skfolio.descriptor.CapexToAssetsChangeInIntensity) | Lagged change in capex-to-assets intensity.                                                                                    |
| [`descriptor.CashFlowToAssets`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToAssets.html.md#skfolio.descriptor.CashFlowToAssets)                             | Cash flow to assets descriptor.                                                                                                |
| [`descriptor.CashFlowToPrice`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#skfolio.descriptor.CashFlowToPrice)                               | Cash-flow-to-price ratio descriptor.                                                                                           |
| [`descriptor.ChangeInIntensity`](https://skfolio.org/generated/skfolio.descriptor.ChangeInIntensity.html.md#skfolio.descriptor.ChangeInIntensity)                           | Lagged change in a field-to-scale ratio.                                                                                       |
| [`descriptor.ChangeToScale`](https://skfolio.org/generated/skfolio.descriptor.ChangeToScale.html.md#skfolio.descriptor.ChangeToScale)                                   | Lagged change normalized by a positive scale.                                                                                  |
| [`descriptor.DaysToCover`](https://skfolio.org/generated/skfolio.descriptor.DaysToCover.html.md#skfolio.descriptor.DaysToCover)                                       | Exponentially weighted days-to-cover descriptor.                                                                               |
| [`descriptor.DebtToAssets`](https://skfolio.org/generated/skfolio.descriptor.DebtToAssets.html.md#skfolio.descriptor.DebtToAssets)                                     | Debt-to-assets ratio descriptor.                                                                                               |
| [`descriptor.DividendToPrice`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice)                               | Dividend-to-price ratio descriptor.                                                                                            |
| [`descriptor.EWAmihudIlliquidity`](https://skfolio.org/generated/skfolio.descriptor.EWAmihudIlliquidity.html.md#skfolio.descriptor.EWAmihudIlliquidity)                       | Exponentially weighted Amihud illiquidity descriptor.                                                                          |
| [`descriptor.EWDownsideBeta`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideBeta.html.md#skfolio.descriptor.EWDownsideBeta)                                 | Exponentially weighted downside beta descriptor.                                                                               |
| [`descriptor.EWDownsideVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideVolatility.html.md#skfolio.descriptor.EWDownsideVolatility)                     | Exponentially weighted downside return volatility descriptor.                                                                  |
| [`descriptor.EWMacroSensitivity`](https://skfolio.org/generated/skfolio.descriptor.EWMacroSensitivity.html.md#skfolio.descriptor.EWMacroSensitivity)                         | EWMA macro sensitivity after removing market exposure.                                                                         |
| [`descriptor.EWMarketBeta`](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#skfolio.descriptor.EWMarketBeta)                                     | Exponentially weighted market beta descriptor.                                                                                 |
| [`descriptor.EWMomentum`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum)                                         | Exponentially weighted momentum descriptor.                                                                                    |
| [`descriptor.EWResidualDownsideVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWResidualDownsideVolatility.html.md#skfolio.descriptor.EWResidualDownsideVolatility)     | Exponentially weighted downside CAPM residual volatility descriptor.                                                           |
| [`descriptor.EWResidualVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility)                     | Exponentially weighted CAPM residual volatility descriptor.                                                                    |
| [`descriptor.EWShareTurnover`](https://skfolio.org/generated/skfolio.descriptor.EWShareTurnover.html.md#skfolio.descriptor.EWShareTurnover)                               | Exponentially weighted share turnover descriptor.                                                                              |
| [`descriptor.EWVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWVolatility.html.md#skfolio.descriptor.EWVolatility)                                     | Exponentially weighted volatility descriptor.                                                                                  |
| [`descriptor.EarningsChangeToPrice`](https://skfolio.org/generated/skfolio.descriptor.EarningsChangeToPrice.html.md#skfolio.descriptor.EarningsChangeToPrice)                   | Lagged earnings change divided by current market capitalization.                                                               |
| [`descriptor.EarningsToPrice`](https://skfolio.org/generated/skfolio.descriptor.EarningsToPrice.html.md#skfolio.descriptor.EarningsToPrice)                               | Earnings-to-price ratio descriptor.                                                                                            |
| [`descriptor.EbitdaToEnterpriseValue`](https://skfolio.org/generated/skfolio.descriptor.EbitdaToEnterpriseValue.html.md#skfolio.descriptor.EbitdaToEnterpriseValue)               | EBITDA-to-enterprise-value ratio descriptor.                                                                                   |
| [`descriptor.ForwardDividendToPrice`](https://skfolio.org/generated/skfolio.descriptor.ForwardDividendToPrice.html.md#skfolio.descriptor.ForwardDividendToPrice)                 | Forward dividend-to-price ratio descriptor.                                                                                    |
| [`descriptor.ForwardEarningsToPrice`](https://skfolio.org/generated/skfolio.descriptor.ForwardEarningsToPrice.html.md#skfolio.descriptor.ForwardEarningsToPrice)                 | Forward earnings-to-price ratio descriptor.                                                                                    |
| [`descriptor.GrossMargin`](https://skfolio.org/generated/skfolio.descriptor.GrossMargin.html.md#skfolio.descriptor.GrossMargin)                                       | Gross margin descriptor.                                                                                                       |
| [`descriptor.GrossProfitability`](https://skfolio.org/generated/skfolio.descriptor.GrossProfitability.html.md#skfolio.descriptor.GrossProfitability)                         | Gross profitability descriptor.                                                                                                |
| [`descriptor.GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate)                                         | Period-over-period growth rate descriptor.                                                                                     |
| [`descriptor.IssuanceGrowthRate`](https://skfolio.org/generated/skfolio.descriptor.IssuanceGrowthRate.html.md#skfolio.descriptor.IssuanceGrowthRate)                         | Issuance growth rate descriptor.                                                                                               |
| [`descriptor.LogMarketCap`](https://skfolio.org/generated/skfolio.descriptor.LogMarketCap.html.md#skfolio.descriptor.LogMarketCap)                                     | Log market capitalization descriptor.                                                                                          |
| [`descriptor.MarketLeverage`](https://skfolio.org/generated/skfolio.descriptor.MarketLeverage.html.md#skfolio.descriptor.MarketLeverage)                                 | Market leverage descriptor.                                                                                                    |
| [`descriptor.MaxReturn`](https://skfolio.org/generated/skfolio.descriptor.MaxReturn.html.md#skfolio.descriptor.MaxReturn)                                           | Maximum return over a trailing window.                                                                                         |
| [`descriptor.Passthrough`](https://skfolio.org/generated/skfolio.descriptor.Passthrough.html.md#skfolio.descriptor.Passthrough)                                       | Passthrough descriptor for an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) field. |
| [`descriptor.ReturnOnAssets`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets)                                 | Return on assets (ROA) descriptor.                                                                                             |
| [`descriptor.ReturnOnEquity`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnEquity.html.md#skfolio.descriptor.ReturnOnEquity)                                 | Return on equity (ROE) descriptor.                                                                                             |
| [`descriptor.Reversal`](https://skfolio.org/generated/skfolio.descriptor.Reversal.html.md#skfolio.descriptor.Reversal)                                             | Fixed-window short-term reversal descriptor.                                                                                   |
| [`descriptor.RollingMomentum`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum)                               | Fixed-window momentum descriptor.                                                                                              |
| [`descriptor.SalesGrowthRate`](https://skfolio.org/generated/skfolio.descriptor.SalesGrowthRate.html.md#skfolio.descriptor.SalesGrowthRate)                               | Sales growth rate descriptor.                                                                                                  |
| [`descriptor.SalesToEnterpriseValue`](https://skfolio.org/generated/skfolio.descriptor.SalesToEnterpriseValue.html.md#skfolio.descriptor.SalesToEnterpriseValue)                 | Sales to enterprise value descriptor.                                                                                          |
| [`descriptor.SalesToPrice`](https://skfolio.org/generated/skfolio.descriptor.SalesToPrice.html.md#skfolio.descriptor.SalesToPrice)                                     | Sales-to-price ratio descriptor.                                                                                               |
| [`descriptor.ShareholderYield`](https://skfolio.org/generated/skfolio.descriptor.ShareholderYield.html.md#skfolio.descriptor.ShareholderYield)                             | Shareholder yield descriptor.                                                                                                  |
| [`descriptor.ShortInterest`](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#skfolio.descriptor.ShortInterest)                                   | Short interest descriptor.                                                                                                     |

<a id="module-skfolio.factor_exposure"></a>

Factor exposure transformers.

<a id="factor-exposure-estimators"></a>

### Factor Exposure Estimators

| [`factor_exposure.BaseFactorExposure`](https://skfolio.org/generated/skfolio.factor_exposure.BaseFactorExposure.html.md#skfolio.factor_exposure.BaseFactorExposure)             | Base class for factor exposure estimators.                       |
|--------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| [`factor_exposure.DerivedFactor`](https://skfolio.org/generated/skfolio.factor_exposure.DerivedFactor.html.md#skfolio.factor_exposure.DerivedFactor)                       | Factor exposure derived from another factor's computed exposure. |
| [`factor_exposure.FixedWeightedFactor`](https://skfolio.org/generated/skfolio.factor_exposure.FixedWeightedFactor.html.md#skfolio.factor_exposure.FixedWeightedFactor)           | Factor exposure as a fixed weighted combination of descriptors.  |
| [`factor_exposure.GlobalFactor`](https://skfolio.org/generated/skfolio.factor_exposure.GlobalFactor.html.md#skfolio.factor_exposure.GlobalFactor)                         | Constant factor exposure equal to one for every asset.           |
| [`factor_exposure.OneHotCategoricalFactors`](https://skfolio.org/generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md#skfolio.factor_exposure.OneHotCategoricalFactors) | One-hot factor exposures from a categorical field.               |

<a id="module-skfolio.alpha"></a>

Alpha models for factor-model score construction.

<a id="alpha-estimators"></a>

### Alpha Estimators

| [`alpha.BaseAlpha`](https://skfolio.org/generated/skfolio.alpha.BaseAlpha.html.md#skfolio.alpha.BaseAlpha)                       | Base class for all Alpha estimators in skfolio.                      |
|----------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| [`alpha.EWSharpeOptimalAlpha`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha) | Exponentially weighted least-squares Sharpe-optimal alpha estimator. |
| [`alpha.FixedWeightedAlpha`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha)     | Fixed-weighted descriptor alpha estimator.                           |
| [`alpha.PredictorAlpha`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha)             | Predictor alpha estimator using a user-provided regressor.           |

<a id="alpha-evaluation"></a>

### Alpha Evaluation

| [`alpha.AlphaForecastComparison`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastComparison.html.md#skfolio.alpha.AlphaForecastComparison)   | Side-by-side comparison of alpha forecast evaluations.   |
|------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
| [`alpha.AlphaForecastEvaluation`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation)   | Out-of-sample alpha forecast evaluation.                 |

<a id="id15"></a>

### Functions

| [`alpha.alpha_forecast_evaluation`](https://skfolio.org/generated/skfolio.alpha.alpha_forecast_evaluation.html.md#skfolio.alpha.alpha_forecast_evaluation)(estimator, X, \*)   | Evaluate alpha forecast quality.   |
|----------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|

<a id="id16"></a>

### Enum

| [`alpha.ForecastUnit`](https://skfolio.org/generated/skfolio.alpha.ForecastUnit.html.md#skfolio.alpha.ForecastUnit)                       | Unit of the intermediate alpha forecast.   |
|----------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
| [`utils.stats.CSWeighting`](https://skfolio.org/generated/skfolio.utils.stats.CSWeighting.html.md#skfolio.utils.stats.CSWeighting)             | Cross-sectional weighting.                 |
| [`utils.stats.CorrelationMethod`](https://skfolio.org/generated/skfolio.utils.stats.CorrelationMethod.html.md#skfolio.utils.stats.CorrelationMethod) | Correlation method.                        |

<a id="module-skfolio.attribution"></a>

Factor-based volatility and return attribution.

<a id="attribution"></a>

### Attribution

| [`attribution.Attribution`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution)                             | Factor attribution result.              |
|--------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| [`attribution.AssetBreakdown`](https://skfolio.org/generated/skfolio.attribution.AssetBreakdown.html.md#skfolio.attribution.AssetBreakdown)                       | Per-asset attribution breakdown.        |
| [`attribution.AssetByFactorContribution`](https://skfolio.org/generated/skfolio.attribution.AssetByFactorContribution.html.md#skfolio.attribution.AssetByFactorContribution) | Asset-by-factor contribution breakdown. |
| [`attribution.BaseBreakdown`](https://skfolio.org/generated/skfolio.attribution.BaseBreakdown.html.md#skfolio.attribution.BaseBreakdown)                         | Base class for attribution breakdowns.  |
| [`attribution.Component`](https://skfolio.org/generated/skfolio.attribution.Component.html.md#skfolio.attribution.Component)                                 | Portfolio attribution component.        |
| [`attribution.FactorBreakdown`](https://skfolio.org/generated/skfolio.attribution.FactorBreakdown.html.md#skfolio.attribution.FactorBreakdown)                     | Per-factor attribution breakdown.       |
| [`attribution.FamilyBreakdown`](https://skfolio.org/generated/skfolio.attribution.FamilyBreakdown.html.md#skfolio.attribution.FamilyBreakdown)                     | Family-level attribution breakdown.     |

<a id="attribution-functions"></a>

### Attribution Functions

| [`attribution.predicted_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.predicted_factor_attribution.html.md#skfolio.attribution.predicted_factor_attribution)(...)                   | Compute predicted (ex-ante) factor volatility and return attribution.        |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| [`attribution.realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution)(\*, ...)                 | Compute realized (ex-post) factor volatility and return attribution.         |
| [`attribution.rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution)(\*, ...) | Compute rolling realized (ex-post) factor volatility and return attribution. |

<a id="mu-ref"></a>

<a id="module-skfolio.moments.expected_returns"></a>

<a id="skfolio-moments-expected-returns-expected-returns-estimators"></a>

## [`skfolio.moments.expected_returns`](https://skfolio.org/api.html.md#module-skfolio.moments.expected_returns): Expected Returns Estimators

Expected returns module.

<a id="id17"></a>

### Base Class

| [`moments.BaseMu`](https://skfolio.org/generated/skfolio.moments.BaseMu.html.md#skfolio.moments.BaseMu)   | Base class for all expected returns estimators in skfolio.   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------|

<a id="id18"></a>

### Classes

| [`moments.EmpiricalMu`](https://skfolio.org/generated/skfolio.moments.EmpiricalMu.html.md#skfolio.moments.EmpiricalMu)         | Empirical Expected Returns (Mu) estimator.              |
|----------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| [`moments.EWMu`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu)                       | Exponentially Weighted Expected Returns (Mu) estimator. |
| [`moments.ShrunkMu`](https://skfolio.org/generated/skfolio.moments.ShrunkMu.html.md#skfolio.moments.ShrunkMu)               | Shrinkage Expected Returns (Mu) estimator.              |
| [`moments.EquilibriumMu`](https://skfolio.org/generated/skfolio.moments.EquilibriumMu.html.md#skfolio.moments.EquilibriumMu)     | Equilibrium Expected Returns (Mu) estimator.            |
| [`moments.ShrunkMuMethods`](https://skfolio.org/generated/skfolio.moments.ShrunkMuMethods.html.md#skfolio.moments.ShrunkMuMethods) | Shrinkage methods for the ShrunkMu estimator.           |

<a id="variance-ref"></a>

<a id="module-skfolio.moments.variance"></a>

<a id="skfolio-moments-variance-variance-estimators"></a>

## [`skfolio.moments.variance`](https://skfolio.org/api.html.md#module-skfolio.moments.variance): Variance Estimators

Variance module.

<a id="id19"></a>

### Base Class

| [`moments.BaseVariance`](https://skfolio.org/generated/skfolio.moments.BaseVariance.html.md#skfolio.moments.BaseVariance)   | Base class for all variance estimators in `skfolio`.   |
|------------------------------------------------------------------------------------------------------|--------------------------------------------------------|

<a id="id20"></a>

### Classes

| [`moments.EmpiricalVariance`](https://skfolio.org/generated/skfolio.moments.EmpiricalVariance.html.md#skfolio.moments.EmpiricalVariance)               | Empirical Variance estimator.                                                                                                                                                                  |
|----------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`moments.EWVariance`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance)                             | Exponentially Weighted Variance estimator.                                                                                                                                                     |
| [`moments.RegimeAdjustedEWVariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance) | Exponentially weighted variance estimator with regime adjustment via the Short-Term Volatility Update (STVU) [[R1cff04c74aab-1]](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#r1cff04c74aab-1). |

<a id="covariance-ref"></a>

<a id="module-skfolio.moments.covariance"></a>

<a id="skfolio-moments-covariance-covariance-estimators"></a>

## [`skfolio.moments.covariance`](https://skfolio.org/api.html.md#module-skfolio.moments.covariance): Covariance Estimators

Covariance module.

<a id="id22"></a>

### Base Class

| [`moments.BaseCovariance`](https://skfolio.org/generated/skfolio.moments.BaseCovariance.html.md#skfolio.moments.BaseCovariance)   | Base class for all covariance estimators in `skfolio`.   |
|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------|

<a id="id23"></a>

### Enum

| [`moments.RegimeAdjustmentMethod`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustmentMethod.html.md#skfolio.moments.RegimeAdjustmentMethod)   | Transformation used to map the STVU statistic to the volatility multiplier.   |
|--------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| [`moments.RegimeAdjustmentTarget`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustmentTarget.html.md#skfolio.moments.RegimeAdjustmentTarget)   | Target dimension used to calibrate the short-term volatility update (STVU).   |

<a id="id24"></a>

### Classes

| [`moments.EmpiricalCovariance`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance)               | Empirical Covariance estimator.                                                                                                                                                                  |
|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`moments.EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance)                             | Exponentially Weighted Covariance estimator with NaN-aware pairwise updates.                                                                                                                     |
| [`moments.GerberCovariance`](https://skfolio.org/generated/skfolio.moments.GerberCovariance.html.md#skfolio.moments.GerberCovariance)                     | Gerber Covariance estimator.                                                                                                                                                                     |
| [`moments.DenoiseCovariance`](https://skfolio.org/generated/skfolio.moments.DenoiseCovariance.html.md#skfolio.moments.DenoiseCovariance)                   | Covariance Denoising estimator.                                                                                                                                                                  |
| [`moments.DetoneCovariance`](https://skfolio.org/generated/skfolio.moments.DetoneCovariance.html.md#skfolio.moments.DetoneCovariance)                     | Covariance Detoning estimator.                                                                                                                                                                   |
| [`moments.LedoitWolf`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf)                                 | LedoitWolf Covariance Estimator.                                                                                                                                                                 |
| [`moments.OAS`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS)                                               | Oracle Approximating Shrinkage Estimator as proposed in [[Re9a22b087643-1]](https://skfolio.org/generated/skfolio.moments.OAS.html.md#re9a22b087643-1).                                                        |
| [`moments.ShrunkCovariance`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance)                     | Covariance estimator with shrinkage.                                                                                                                                                             |
| [`moments.GraphicalLassoCV`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV)                     | Sparse inverse covariance with cross-validated choice of the l1 penalty.                                                                                                                         |
| [`moments.ImpliedCovariance`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance)                   | Implied Covariance estimator.                                                                                                                                                                    |
| [`moments.RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance) | Exponentially weighted covariance estimator with regime adjustment via the Short-Term Volatility Update (STVU) [[R9fdb90a74052-1]](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#r9fdb90a74052-1). |

<a id="distance-ref"></a>

<a id="module-skfolio.distance"></a>

<a id="skfolio-distance-distance-estimators"></a>

## [`skfolio.distance`](https://skfolio.org/api.html.md#module-skfolio.distance): Distance Estimators

Distance Estimators.

<a id="id27"></a>

### Base Class

| [`distance.BaseDistance`](https://skfolio.org/generated/skfolio.distance.BaseDistance.html.md#skfolio.distance.BaseDistance)   | Base class for all distance estimators in skfolio.   |
|--------------------------------------------------------------------------------------------------------|------------------------------------------------------|

<a id="id28"></a>

### Classes

| [`distance.PearsonDistance`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance)         | Pearson Distance estimator.     |
|--------------------------------------------------------------------------------------------------------------------|---------------------------------|
| [`distance.KendallDistance`](https://skfolio.org/generated/skfolio.distance.KendallDistance.html.md#skfolio.distance.KendallDistance)         | Kendall Distance estimator.     |
| [`distance.SpearmanDistance`](https://skfolio.org/generated/skfolio.distance.SpearmanDistance.html.md#skfolio.distance.SpearmanDistance)       | Spearman Distance estimator.    |
| [`distance.CovarianceDistance`](https://skfolio.org/generated/skfolio.distance.CovarianceDistance.html.md#skfolio.distance.CovarianceDistance)   | Covariance Distance estimator.  |
| [`distance.DistanceCorrelation`](https://skfolio.org/generated/skfolio.distance.DistanceCorrelation.html.md#skfolio.distance.DistanceCorrelation) | Distance Correlation estimator. |
| [`distance.MutualInformation`](https://skfolio.org/generated/skfolio.distance.MutualInformation.html.md#skfolio.distance.MutualInformation)     | Mutual Information estimator.   |

<a id="cluster-ref"></a>

<a id="module-skfolio.cluster"></a>

<a id="skfolio-cluster-cluster-estimators"></a>

## [`skfolio.cluster`](https://skfolio.org/api.html.md#module-skfolio.cluster): Cluster Estimators

Hierarchical Clustering estimators.

<a id="id29"></a>

### Classes

| [`cluster.HierarchicalClustering`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering)   | Hierarchical Clustering.                                                     |
|--------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| [`cluster.LinkageMethod`](https://skfolio.org/generated/skfolio.cluster.LinkageMethod.html.md#skfolio.cluster.LinkageMethod)                     | Methods for calculating the distance between clusters in the linkage matrix. |

<a id="uncertainty-set-ref"></a>

<a id="module-skfolio.uncertainty_set"></a>

<a id="skfolio-uncertainty-set-uncertainty-set-estimators"></a>

## [`skfolio.uncertainty_set`](https://skfolio.org/api.html.md#module-skfolio.uncertainty_set): Uncertainty set Estimators

Uncertainty Set module.

<a id="id30"></a>

### Model Dataclass

| [`uncertainty_set.UncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.UncertaintySet.html.md#skfolio.uncertainty_set.UncertaintySet)                                   | Norm-ball uncertainty set.                                            |
|----------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| [`uncertainty_set.CompactCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.CompactCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.CompactCovarianceUncertaintySet) | Compact representation of a quadratic covariance uncertainty penalty. |

<a id="base-classes"></a>

### Base Classes

| [`uncertainty_set.BaseMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.BaseMuUncertaintySet.html.md#skfolio.uncertainty_set.BaseMuUncertaintySet)                 | Base class for all Mu Uncertainty Set estimators in `skfolio`.         |
|----------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| [`uncertainty_set.BaseCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.BaseCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.BaseCovarianceUncertaintySet) | Base class for all Covariance Uncertainty Set estimators in `skfolio`. |

<a id="id31"></a>

### Classes

| [`uncertainty_set.EmpiricalMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalMuUncertaintySet)                   | Empirical Mu Uncertainty Set.                                                     |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
| [`uncertainty_set.EmpiricalCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet)   | Empirical Covariance Uncertainty set.                                             |
| [`uncertainty_set.BootstrapMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapMuUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapMuUncertaintySet)                   | Bootstrap Mu Uncertainty set.                                                     |
| [`uncertainty_set.BootstrapCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet)   | Bootstrap Covariance Uncertainty set.                                             |
| [`uncertainty_set.OrthogonalMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet)                 | Expected return uncertainty set estimator for directions outside the factor span. |
| [`uncertainty_set.OrthogonalCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet) | Covariance uncertainty set estimator for directions outside the factor span.      |

<a id="pre-selection-ref"></a>

<a id="module-skfolio.pre_selection"></a>

<a id="skfolio-pre-selection-pre-selection-transformers"></a>

## [`skfolio.pre_selection`](https://skfolio.org/api.html.md#module-skfolio.pre_selection): Pre-selection Transformers

Pre Selection module.

<a id="id32"></a>

### Classes

| [`pre_selection.DropCorrelated`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated)         | Transformer for dropping highly correlated assets.                                                                           |
|----------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| [`pre_selection.DropZeroVariance`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance)     | Transformer for dropping assets with near-zero variance.                                                                     |
| [`pre_selection.SelectKExtremes`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes)       | Transformer for selecting the `k` best or worst assets.                                                                      |
| [`pre_selection.SelectNonDominated`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated) | Transformer for selecting non dominated assets.                                                                              |
| [`pre_selection.SelectComplete`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete)         | Transformer to select assets with complete data across the entire observation period.                                        |
| [`pre_selection.SelectNonExpiring`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring)   | Transformer to select assets that do not expire within a specified lookahead period after the end of the observation period. |

<a id="linear-model-ref"></a>

<a id="module-skfolio.linear_model"></a>

<a id="skfolio-linear-model-cross-sectional-linear-models"></a>

## [`skfolio.linear_model`](https://skfolio.org/api.html.md#module-skfolio.linear_model): Cross-sectional linear models

Linear model module.

<a id="id33"></a>

### Base Class

| [`linear_model.BaseCSLinearModel`](https://skfolio.org/generated/skfolio.linear_model.BaseCSLinearModel.html.md#skfolio.linear_model.BaseCSLinearModel)   | Base class for all cross-sectional linear model estimators.   |
|--------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|

<a id="id34"></a>

### Classes

| [`linear_model.CSLinearRegression`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression)             | Cross-sectional weighted least squares regression.            |
|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| [`linear_model.CSLinearRegressorWrapper`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper) | Cross-sectional regression based on a scikit-learn regressor. |

<a id="model-selection-ref"></a>

<a id="module-skfolio.model_selection"></a>

<a id="skfolio-model-selection-model-selection"></a>

## [`skfolio.model_selection`](https://skfolio.org/api.html.md#module-skfolio.model_selection): Model Selection

Model selection module.

<a id="id35"></a>

### Base Classes

| [`model_selection.BaseCombinatorialCV`](https://skfolio.org/generated/skfolio.model_selection.BaseCombinatorialCV.html.md#skfolio.model_selection.BaseCombinatorialCV)   | Base class for all combinatorial cross-validators.   |
|------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|

<a id="id36"></a>

### Classes

| [`model_selection.WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward)                                   | Walk Forward Cross-Validator.                                  |
|----------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| [`model_selection.CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV)               | Combinatorial Purged Cross-Validation.                         |
| [`model_selection.MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV)                 | Multiple Randomized Cross-Validation.                          |
| [`model_selection.OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch)                         | Online exhaustive hyperparameter search over a parameter grid. |
| [`model_selection.OnlineRandomizedSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch)             | Online randomized search on hyperparameters.                   |
| [`model_selection.CovarianceForecastEvaluation`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation) | Out-of-sample covariance forecast evaluation.                  |
| [`model_selection.CovarianceForecastComparison`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison) | Side-by-side comparison of covariance forecast evaluations.    |

<a id="id37"></a>

### Functions

| [`model_selection.cross_val_predict`](https://skfolio.org/generated/skfolio.model_selection.cross_val_predict.html.md#skfolio.model_selection.cross_val_predict)(estimator, X)                                | Generate cross-validated `Portfolios` estimates.                                                                            |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| [`model_selection.online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict)(estimator, X)                                      | Generate out-of-sample portfolios using online learning.                                                                    |
| [`model_selection.online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score)(estimator, X[, ...])                                   | Score an online estimator using walk-forward evaluation.                                                                    |
| [`model_selection.online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation)(...) | Evaluate out-of-sample covariance forecast quality.                                                                         |
| [`model_selection.covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.covariance_forecast_evaluation.html.md#skfolio.model_selection.covariance_forecast_evaluation)(...)               | Evaluate out-of-sample covariance forecast quality using walk-forward cross-validation.                                     |
| [`model_selection.optimal_folds_number`](https://skfolio.org/generated/skfolio.model_selection.optimal_folds_number.html.md#skfolio.model_selection.optimal_folds_number)(...[, ...])                            | Find the optimal number of folds (total folds and test folds) for a target training size and a target number of test paths. |

<a id="metrics-ref"></a>

<a id="module-skfolio.metrics"></a>

<a id="skfolio-metrics-metrics"></a>

## [`skfolio.metrics`](https://skfolio.org/api.html.md#module-skfolio.metrics): Metrics

Metrics module.

<a id="id38"></a>

### Functions

| [`metrics.make_scorer`](https://skfolio.org/generated/skfolio.metrics.make_scorer.html.md#skfolio.metrics.make_scorer)(score_func[, ...])                                     | Make a scorer from a [measure](https://skfolio.org/api.html.md#measures-ref), a portfolio score function, or a non-predictor estimator score function.   |
|---------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`metrics.diagonal_calibration_loss`](https://skfolio.org/generated/skfolio.metrics.diagonal_calibration_loss.html.md#skfolio.metrics.diagonal_calibration_loss)(estimator, ...)            | Diagonal calibration loss.                                                                                                                              |
| [`metrics.diagonal_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.diagonal_calibration_ratio.html.md#skfolio.metrics.diagonal_calibration_ratio)(...[, y])                | Diagonal calibration ratio based on marginal variances.                                                                                                 |
| [`metrics.exceedance_rate`](https://skfolio.org/generated/skfolio.metrics.exceedance_rate.html.md#skfolio.metrics.exceedance_rate)(squared_distances, ...)                        | Exceedance rate for chi-squared calibration statistics.                                                                                                 |
| [`metrics.mahalanobis_calibration_loss`](https://skfolio.org/generated/skfolio.metrics.mahalanobis_calibration_loss.html.md#skfolio.metrics.mahalanobis_calibration_loss)(...[, y])            | Mahalanobis calibration loss.                                                                                                                           |
| [`metrics.mahalanobis_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.mahalanobis_calibration_ratio.html.md#skfolio.metrics.mahalanobis_calibration_ratio)(...[, y])          | Mahalanobis calibration ratio.                                                                                                                          |
| [`metrics.portfolio_variance_calibration_loss`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_calibration_loss.html.md#skfolio.metrics.portfolio_variance_calibration_loss)(...)   | Portfolio variance calibration loss.                                                                                                                    |
| [`metrics.portfolio_variance_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_calibration_ratio.html.md#skfolio.metrics.portfolio_variance_calibration_ratio)(...) | Portfolio variance calibration ratio.                                                                                                                   |
| [`metrics.portfolio_variance_qlike_loss`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_qlike_loss.html.md#skfolio.metrics.portfolio_variance_qlike_loss)(...[, ...])        | QLIKE loss for a projected portfolio variance forecast [[R7dedfcdc36e0-1]](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_qlike_loss.html.md#r7dedfcdc36e0-1).                |
| [`metrics.qlike_loss`](https://skfolio.org/generated/skfolio.metrics.qlike_loss.html.md#skfolio.metrics.qlike_loss)(returns, forecast_variance)                              | QLIKE loss for univariate variance forecasts.                                                                                                           |

<a id="datasets-ref"></a>

<a id="skfolio-datasets-datasets"></a>

## `skfolio.datasets`: Datasets

<a id="id40"></a>

### Functions

| [`datasets.load_sp500_dataset`](https://skfolio.org/generated/skfolio.datasets.load_sp500_dataset.html.md#skfolio.datasets.load_sp500_dataset)()                              | Load the prices of 20 assets from the S&P 500 Index.                                                                            |
|-------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`datasets.load_sp500_index`](https://skfolio.org/generated/skfolio.datasets.load_sp500_index.html.md#skfolio.datasets.load_sp500_index)()                                  | Load the prices of the S&P 500 Index.                                                                                           |
| [`datasets.load_factors_dataset`](https://skfolio.org/generated/skfolio.datasets.load_factors_dataset.html.md#skfolio.datasets.load_factors_dataset)()                          | Load the prices of 5 factor ETFs.                                                                                               |
| [`datasets.load_ftse100_dataset`](https://skfolio.org/generated/skfolio.datasets.load_ftse100_dataset.html.md#skfolio.datasets.load_ftse100_dataset)([data_home, ...])          | Load the prices of 64 assets from the FTSE 100 Index composition.                                                               |
| [`datasets.load_nasdaq_dataset`](https://skfolio.org/generated/skfolio.datasets.load_nasdaq_dataset.html.md#skfolio.datasets.load_nasdaq_dataset)([data_home, ...])            | Load the prices of 1455 assets from the NASDAQ Composite Index.                                                                 |
| [`datasets.load_sp500_implied_vol_dataset`](https://skfolio.org/generated/skfolio.datasets.load_sp500_implied_vol_dataset.html.md#skfolio.datasets.load_sp500_implied_vol_dataset)([...]) | Load the 3 months ATM implied volatility of the 20 assets from the SP500 dataset.                                               |
| [`datasets.make_synthetic_characteristics`](https://skfolio.org/generated/skfolio.datasets.make_synthetic_characteristics.html.md#skfolio.datasets.make_synthetic_characteristics)([...]) | Generate a synthetic characteristics [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel). |

<a id="preprocessing-ref"></a>

<a id="module-skfolio.preprocessing"></a>

<a id="skfolio-preprocessing-preprocessing"></a>

## [`skfolio.preprocessing`](https://skfolio.org/api.html.md#module-skfolio.preprocessing): Preprocessing

Preprocessing module.

<a id="id41"></a>

### Base Class

| [`preprocessing.BaseCSTransformer`](https://skfolio.org/generated/skfolio.preprocessing.BaseCSTransformer.html.md#skfolio.preprocessing.BaseCSTransformer)   | Base class for all cross-sectional transformers in skfolio.   |
|----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|

<a id="id42"></a>

### Classes

| [`preprocessing.CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler)     | Cross-sectional rank Gaussianization.   |
|------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| [`preprocessing.CSPercentileRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler) | Cross-sectional percentile rank.        |
| [`preprocessing.CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler)             | Cross-sectional standardization.        |
| [`preprocessing.CSTanhShrinker`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker)                 | Cross-sectional tanh outlier shrinker.  |
| [`preprocessing.CSWinsorizer`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer)                     | Cross-sectional winsorization.          |

<a id="id43"></a>

### Functions

| [`preprocessing.prices_to_returns`](https://skfolio.org/generated/skfolio.preprocessing.prices_to_returns.html.md#skfolio.preprocessing.prices_to_returns)(X[, y, ...])   | Transform a DataFrame of prices to linear or logarithmic returns.   |
|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|

<a id="tools-ref"></a>

<a id="skfolio-utils-tools-tools"></a>

## `skfolio.utils.tools`: Tools

<a id="id44"></a>

### Classes

| [`tools.AutoEnum`](https://skfolio.org/generated/skfolio.utils.tools.AutoEnum.html.md#skfolio.utils.tools.AutoEnum)                           | Base Enum class used in `skfolio`.   |
|------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
| [`tools.cached_property_slots`](https://skfolio.org/generated/skfolio.utils.tools.cached_property_slots.html.md#skfolio.utils.tools.cached_property_slots) | Cached property decorator for slots. |

<a id="id45"></a>

### Functions

| [`tools.apply_window_size`](https://skfolio.org/generated/skfolio.utils.tools.apply_window_size.html.md#skfolio.utils.tools.apply_window_size)(X, window_size)             | Return the last `window_size` observations from the array X.                                                |
|--------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| [`tools.args_names`](https://skfolio.org/generated/skfolio.utils.tools.args_names.html.md#skfolio.utils.tools.args_names)(func)                                     | Returns the argument names of a function.                                                                   |
| [`tools.bisection`](https://skfolio.org/generated/skfolio.utils.tools.bisection.html.md#skfolio.utils.tools.bisection)(x)                                          | Generator to bisect a list of arrays.                                                                       |
| [`tools.cache_method`](https://skfolio.org/generated/skfolio.utils.tools.cache_method.html.md#skfolio.utils.tools.cache_method)(cache_name)                           | Decorator that caches class method results into a class dictionary.                                         |
| [`tools.check_estimator`](https://skfolio.org/generated/skfolio.utils.tools.check_estimator.html.md#skfolio.utils.tools.check_estimator)(estimator, default, ...)        | Check the estimator type and return its cloned version if provided, otherwise return the default estimator. |
| [`tools.deduplicate_names`](https://skfolio.org/generated/skfolio.utils.tools.deduplicate_names.html.md#skfolio.utils.tools.deduplicate_names)(names)                      | Rename duplicated names by appending "_{duplicate_nb}" at the end.                                          |
| [`tools.default_asset_names`](https://skfolio.org/generated/skfolio.utils.tools.default_asset_names.html.md#skfolio.utils.tools.default_asset_names)(n_assets)               | Default asset names are `["x0", "x1", ..., "x(n_assets - 1)"]`.                                             |
| [`tools.fit_and_predict`](https://skfolio.org/generated/skfolio.utils.tools.fit_and_predict.html.md#skfolio.utils.tools.fit_and_predict)(estimator, X, y, ...)           | Fit the estimator and predict values for a given dataset split.                                             |
| [`tools.fit_single_estimator`](https://skfolio.org/generated/skfolio.utils.tools.fit_single_estimator.html.md#skfolio.utils.tools.fit_single_estimator)(estimator, X, y, ...) | Fit (or partial-fit) an estimator on a subset of the data.                                                  |
| [`tools.format_measure`](https://skfolio.org/generated/skfolio.utils.tools.format_measure.html.md#skfolio.utils.tools.format_measure)(x[, percent])                     | Format a measure number into a user-friendly string.                                                        |
| [`tools.get_feature_names`](https://skfolio.org/generated/skfolio.utils.tools.get_feature_names.html.md#skfolio.utils.tools.get_feature_names)(X)                          | Get feature names from X.                                                                                   |
| [`tools.half_life_to_decay_factor`](https://skfolio.org/generated/skfolio.utils.tools.half_life_to_decay_factor.html.md#skfolio.utils.tools.half_life_to_decay_factor)(half_life)  | Convert half-life to exponential decay factor.                                                              |
| [`tools.input_to_array`](https://skfolio.org/generated/skfolio.utils.tools.input_to_array.html.md#skfolio.utils.tools.input_to_array)(items, n_assets, ...[, ...])      | Convert a collection of items (array-like or dictionary) into a numpy array and verify its shape.           |
| [`tools.optimal_rounding_decimals`](https://skfolio.org/generated/skfolio.utils.tools.optimal_rounding_decimals.html.md#skfolio.utils.tools.optimal_rounding_decimals)(x)          | Return the optimal rounding decimal number for a user-friendly formatting.                                  |
| [`tools.safe_indexing`](https://skfolio.org/generated/skfolio.utils.tools.safe_indexing.html.md#skfolio.utils.tools.safe_indexing)(X, indices[, axis])                 | Return rows, items or columns of X using indices.                                                           |
| [`tools.safe_split`](https://skfolio.org/generated/skfolio.utils.tools.safe_split.html.md#skfolio.utils.tools.safe_split)(X[, y, indices, axis])                    | Create subset of dataset.                                                                                   |
| [`tools.validate_input_list`](https://skfolio.org/generated/skfolio.utils.tools.validate_input_list.html.md#skfolio.utils.tools.validate_input_list)(items, n_assets, ...)   | Convert a list of items (asset indices or asset names) into a list of validated asset indices.              |

<a id="stats-ref"></a>

<a id="skfolio-utils-stats-stats"></a>

## `skfolio.utils.stats`: Stats

<a id="id46"></a>

### Enum

| [`stats.NBinsMethod`](https://skfolio.org/generated/skfolio.utils.stats.NBinsMethod.html.md#skfolio.utils.stats.NBinsMethod)   | Enumeration of the Number of Bins Methods.   |
|------------------------------------------------------------------------------------------------------|----------------------------------------------|

<a id="id47"></a>

### Functions

| [`stats.assert_is_distance`](https://skfolio.org/generated/skfolio.utils.stats.assert_is_distance.html.md#skfolio.utils.stats.assert_is_distance)(x)                                     | Raises an error if the matrix is not a distance matrix.                                                                                                                 |
|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`stats.assert_is_square`](https://skfolio.org/generated/skfolio.utils.stats.assert_is_square.html.md#skfolio.utils.stats.assert_is_square)(x)                                         | Raises an error if the matrix is not square.                                                                                                                            |
| [`stats.assert_is_symmetric`](https://skfolio.org/generated/skfolio.utils.stats.assert_is_symmetric.html.md#skfolio.utils.stats.assert_is_symmetric)(x, \*[, rtol, atol])                 | Raises an error if the matrix is not symmetric.                                                                                                                         |
| [`stats.combination_by_index`](https://skfolio.org/generated/skfolio.utils.stats.combination_by_index.html.md#skfolio.utils.stats.combination_by_index)(idx, n, k)                         | Retrieve the k-combination at a given lexicographic position without enumerating all combinations.                                                                      |
| [`stats.commutation_matrix`](https://skfolio.org/generated/skfolio.utils.stats.commutation_matrix.html.md#skfolio.utils.stats.commutation_matrix)(x)                                     | Compute the commutation matrix.                                                                                                                                         |
| [`stats.compute_optimal_n_clusters`](https://skfolio.org/generated/skfolio.utils.stats.compute_optimal_n_clusters.html.md#skfolio.utils.stats.compute_optimal_n_clusters)(distance, ...)         | Compute the optimal number of clusters based on Two-Order Difference to Gap Statistic [[Re0e718a4c413-1]](https://skfolio.org/generated/skfolio.utils.stats.compute_optimal_n_clusters.html.md#re0e718a4c413-1). |
| [`stats.corr_to_cov`](https://skfolio.org/generated/skfolio.utils.stats.corr_to_cov.html.md#skfolio.utils.stats.corr_to_cov)(corr, std)                                           | Convert a correlation matrix to a covariance matrix given its standard-deviation vector.                                                                                |
| [`stats.cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest)(cov[, higham, ...])                                  | Compute the nearest covariance matrix that is positive definite and with a cholesky decomposition that can be computed.                                                 |
| [`stats.cov_to_corr`](https://skfolio.org/generated/skfolio.utils.stats.cov_to_corr.html.md#skfolio.utils.stats.cov_to_corr)(cov)                                                 | Convert a covariance matrix to a correlation matrix.                                                                                                                    |
| [`stats.cs_pearson_correlation`](https://skfolio.org/generated/skfolio.utils.stats.cs_pearson_correlation.html.md#skfolio.utils.stats.cs_pearson_correlation)(a, b[, ...])                   | Weighted cross-sectional Pearson correlation.                                                                                                                           |
| [`stats.cs_rank`](https://skfolio.org/generated/skfolio.utils.stats.cs_rank.html.md#skfolio.utils.stats.cs_rank)(a[, axis])                                                   | Cross-sectional rank along an axis.                                                                                                                                     |
| [`stats.cs_spearman_correlation`](https://skfolio.org/generated/skfolio.utils.stats.cs_spearman_correlation.html.md#skfolio.utils.stats.cs_spearman_correlation)(a, b[, axis, ...])           | Cross-sectional Spearman rank correlation.                                                                                                                              |
| [`stats.inverse_multiply`](https://skfolio.org/generated/skfolio.utils.stats.inverse_multiply.html.md#skfolio.utils.stats.inverse_multiply)(a, b)                                      | Multiply the inverse of matrix a by matrix b.                                                                                                                           |
| [`stats.inverse_volatility_weights`](https://skfolio.org/generated/skfolio.utils.stats.inverse_volatility_weights.html.md#skfolio.utils.stats.inverse_volatility_weights)(covariance)            | Inverse-volatility portfolio weights from a covariance matrix.                                                                                                          |
| [`stats.safe_cholesky`](https://skfolio.org/generated/skfolio.utils.stats.safe_cholesky.html.md#skfolio.utils.stats.safe_cholesky)(covariance[, ...])                               | Compute a Cholesky factor $L$ from covariance $\Sigma$.                                                                                                                 |
| [`stats.is_cholesky_dec`](https://skfolio.org/generated/skfolio.utils.stats.is_cholesky_dec.html.md#skfolio.utils.stats.is_cholesky_dec)(x)                                           | Returns True if Cholesky decomposition can be computed.                                                                                                                 |
| [`stats.minimize_relative_weight_deviation`](https://skfolio.org/generated/skfolio.utils.stats.minimize_relative_weight_deviation.html.md#skfolio.utils.stats.minimize_relative_weight_deviation)(...)   | Apply weight constraints to an initial array of weights by minimizing the relative weight deviation of the final weights from the initial weights.                      |
| [`stats.multiply_by_inverse`](https://skfolio.org/generated/skfolio.utils.stats.multiply_by_inverse.html.md#skfolio.utils.stats.multiply_by_inverse)(a, b)                                | Multiply matrix a by the inverse of matrix b.                                                                                                                           |
| [`stats.n_bins_freedman`](https://skfolio.org/generated/skfolio.utils.stats.n_bins_freedman.html.md#skfolio.utils.stats.n_bins_freedman)(x)                                           | Compute the optimal histogram bin size using the Freedman-Diaconis rule [[R8d5b646da1d1-1]](https://skfolio.org/generated/skfolio.utils.stats.n_bins_freedman.html.md#r8d5b646da1d1-1).               |
| [`stats.n_bins_knuth`](https://skfolio.org/generated/skfolio.utils.stats.n_bins_knuth.html.md#skfolio.utils.stats.n_bins_knuth)(x)                                                 | Compute the optimal histogram bin size using Knuth's rule [[R8c3fe88ee915-1]](https://skfolio.org/generated/skfolio.utils.stats.n_bins_knuth.html.md#r8c3fe88ee915-1).                             |
| [`stats.rand_weights`](https://skfolio.org/generated/skfolio.utils.stats.rand_weights.html.md#skfolio.utils.stats.rand_weights)(n[, zeros, seed])                                  | Produces n random weights that sum to one from a uniform distribution (non-uniform distribution over a simplex).                                                        |
| [`stats.rand_weights_dirichlet`](https://skfolio.org/generated/skfolio.utils.stats.rand_weights_dirichlet.html.md#skfolio.utils.stats.rand_weights_dirichlet)(n)                             | Produces n random weights that sum to one from a Dirichlet distribution (uniform distribution over a simplex).                                                          |
| [`stats.sample_unique_subsets`](https://skfolio.org/generated/skfolio.utils.stats.sample_unique_subsets.html.md#skfolio.utils.stats.sample_unique_subsets)(n, k, n_subsets)                 | Generate unique k-element subsets from a universe of size n using combinatorial unranking.                                                                              |
| [`stats.squared_mahalanobis_dist`](https://skfolio.org/generated/skfolio.utils.stats.squared_mahalanobis_dist.html.md#skfolio.utils.stats.squared_mahalanobis_dist)(X, covariance)             | Squared Mahalanobis distance via Cholesky decomposition.                                                                                                                |
| [`stats.squared_standardized_euclidean_dist`](https://skfolio.org/generated/skfolio.utils.stats.squared_standardized_euclidean_dist.html.md#skfolio.utils.stats.squared_standardized_euclidean_dist)(...) | Squared standardized Euclidean distance.                                                                                                                                |
| [`stats.symmetric_step_up_matrix`](https://skfolio.org/generated/skfolio.utils.stats.symmetric_step_up_matrix.html.md#skfolio.utils.stats.symmetric_step_up_matrix)(n1, n2)                    | Compute the Symmetric step-up matrix M such that `M @ np.ones(n2) = np.ones(n1)`.                                                                                       |
| [`stats.symmetrize`](https://skfolio.org/generated/skfolio.utils.stats.symmetrize.html.md#skfolio.utils.stats.symmetrize)(matrix[, where])                                       | In-place symmetrization: $M \leftarrow (M + M^T) / 2$.                                                                                                                  |

<a id="validation-ref"></a>

<a id="skfolio-utils-validation-validation"></a>

## `skfolio.utils.validation`: Validation

<a id="id51"></a>

### Functions

| [`validation.validate_asset_panel`](https://skfolio.org/generated/skfolio.utils.validation.validate_asset_panel.html.md#skfolio.utils.validation.validate_asset_panel)(_estimator, ...)       | Validate an AssetPanel and set estimator metadata attributes.   |
|-------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
| [`validation.validate_cross_sectional_data`](https://skfolio.org/generated/skfolio.utils.validation.validate_cross_sectional_data.html.md#skfolio.utils.validation.validate_cross_sectional_data)(...) | Validate cross-sectional data.                                  |

<a id="distribution-ref"></a>

<a id="module-skfolio.distribution"></a>

<a id="skfolio-distribution-distribution-estimators"></a>

## [`skfolio.distribution`](https://skfolio.org/api.html.md#module-skfolio.distribution): Distribution Estimators

Distribution module.

<a id="id52"></a>

### Base Class

| [`distribution.BaseDistribution`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution)   | Base Distribution Estimator.   |
|------------------------------------------------------------------------------------------------------------------------|--------------------------------|

<a id="id53"></a>

### Enum

| [`distribution.SelectionCriterion`](https://skfolio.org/generated/skfolio.distribution.SelectionCriterion.html.md#skfolio.distribution.SelectionCriterion)   | Enum representing the selection criteria.   |
|----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------|

<a id="univariate-distribution-ref"></a>

<a id="module-skfolio.distribution.univariate"></a>

<a id="skfolio-distribution-univariate-univariate-distribution-estimators"></a>

## [`skfolio.distribution.univariate`](https://skfolio.org/api.html.md#module-skfolio.distribution.univariate): Univariate Distribution Estimators

Univariate Distribution module.

<a id="id54"></a>

### Base Class

| [`distribution.BaseUnivariateDist`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist)   | Base Univariate Distribution Estimator.   |
|----------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|

<a id="id55"></a>

### Classes

| [`distribution.Gaussian`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian)                           | Gaussian Distribution Estimation.                |
|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|
| [`distribution.StudentT`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT)                           | Student's t Distribution Estimation.             |
| [`distribution.JohnsonSU`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU)                         | Johnson SU Distribution Estimation.              |
| [`distribution.NormalInverseGaussian`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian) | Normal Inverse Gaussian Distribution Estimation. |

<a id="id56"></a>

### Functions

| [`distribution.select_univariate_dist`](https://skfolio.org/generated/skfolio.distribution.select_univariate_dist.html.md#skfolio.distribution.select_univariate_dist)(X[, ...])   | Select the optimal univariate distribution estimator based on an information criterion.   |
|----------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|

<a id="multivariate-distribution-ref"></a>

<a id="module-skfolio.distribution.multivariate"></a>

<a id="skfolio-distribution-multivariate-multivariate-distribution-estimators"></a>

## [`skfolio.distribution.multivariate`](https://skfolio.org/api.html.md#module-skfolio.distribution.multivariate): Multivariate Distribution Estimators

Multivariate Distribution module.

<a id="id57"></a>

### Base Class

| [`distribution.BaseMultivariateDist`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist)   | Base class for Multivariate Distribution Estimators.   |
|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|

<a id="id58"></a>

### Classes

| [`distribution.VineCopula`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula)   | Regular Vine Copula Estimator.   |
|------------------------------------------------------------------------------------------------------------|----------------------------------|

<a id="id59"></a>

### Enum

| [`distribution.DependenceMethod`](https://skfolio.org/generated/skfolio.distribution.DependenceMethod.html.md#skfolio.distribution.DependenceMethod)   | Enumeration of methods to measure bivariate dependence.   |
|------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|

<a id="bivariate-copula-ref"></a>

<a id="module-skfolio.distribution.copula"></a>

<a id="skfolio-distribution-copula-bivariate-copula-estimators"></a>

## [`skfolio.distribution.copula`](https://skfolio.org/api.html.md#module-skfolio.distribution.copula): Bivariate Copula Estimators

Copula module.

<a id="id60"></a>

### Base Class

| [`distribution.BaseBivariateCopula`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula)   | Base class for Bivariate Copula Estimators.   |
|------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|

<a id="id61"></a>

### Classes

| [`distribution.GaussianCopula`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula)       | Bivariate Gaussian Copula Estimation.                          |
|------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|
| [`distribution.StudentTCopula`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula)       | Bivariate Student's t Copula Estimation.                       |
| [`distribution.ClaytonCopula`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula)         | Bivariate Clayton Copula Estimation.                           |
| [`distribution.GumbelCopula`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula)           | Bivariate Gumbel Copula Estimation.                            |
| [`distribution.JoeCopula`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula)                 | Bivariate Joe Copula Estimation.                               |
| [`distribution.IndependentCopula`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula) | Bivariate Independent Copula (also called the product copula). |

<a id="id62"></a>

### Functions

| [`distribution.compute_pseudo_observations`](https://skfolio.org/generated/skfolio.distribution.compute_pseudo_observations.html.md#skfolio.distribution.compute_pseudo_observations)(X)        | Compute pseudo-observations by ranking each column of the data and scaling the ranks.      |
|------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| [`distribution.empirical_tail_concentration`](https://skfolio.org/generated/skfolio.distribution.empirical_tail_concentration.html.md#skfolio.distribution.empirical_tail_concentration)(X, ...) | Compute empirical tail concentration for the two variables in X.                           |
| [`distribution.plot_tail_concentration`](https://skfolio.org/generated/skfolio.distribution.plot_tail_concentration.html.md#skfolio.distribution.plot_tail_concentration)(...[, ...])       | Plot the empirical tail concentration curves.                                              |
| [`distribution.select_bivariate_copula`](https://skfolio.org/generated/skfolio.distribution.select_bivariate_copula.html.md#skfolio.distribution.select_bivariate_copula)(X[, ...])         | Select the best bivariate copula from a list of candidates using an information criterion. |

<a id="id63"></a>

### Enum

| [`distribution.CopulaRotation`](https://skfolio.org/generated/skfolio.distribution.CopulaRotation.html.md#skfolio.distribution.CopulaRotation)   | Enum representing the rotation (in degrees) to apply to a bivariate copula.   |
|--------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|

# auto_examples/clustering/index.html.md

<a id="sphx-glr-auto-examples-clustering"></a>

<a id="cluster-examples"></a>

<a id="hierarchical-clustering-and-nco"></a>

# Hierarchical Clustering and NCO

Examples concerning hierarchical clustering based optimizations.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the HierarchicalRiskParity optimization.">  <div class="sphx-glr-thumbnail-title">Hierarchical Risk Parity - CVaR</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the HierarchicalEqualRiskContribution optimization.">  <div class="sphx-glr-thumbnail-title">Hierarchical Equal Risk Contribution - CDaR</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="In this tutorial, we will compare the HierarchicalRiskParity (HRP) optimization with the HierarchicalEqualRiskContribution (HERC) optimization.">  <div class="sphx-glr-thumbnail-title">HRP vs HERC</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the NestedClustersOptimization optimization.">  <div class="sphx-glr-thumbnail-title">Nested Clusters Optimization</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="The previous tutorial introduced the NestedClustersOptimization.">  <div class="sphx-glr-thumbnail-title">NCO - Combinatorial Purged CV</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the SchurComplementary allocation.">  <div class="sphx-glr-thumbnail-title">Schur Complementary Allocation</div>
</div>
</div>

# auto_examples/clustering/plot_1_hrp_cvar.html.md

<a id="sphx-glr-auto-examples-clustering-plot-1-hrp-cvar-py"></a>

<a id="hierarchical-risk-parity-cvar"></a>

# Hierarchical Risk Parity - CVaR

This tutorial introduces the [`HierarchicalRiskParity`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity)
optimization.

Hierarchical Risk Parity (HRP) is a portfolio optimization method developed by Marcos
Lopez de Prado.

This algorithm uses a distance matrix to compute hierarchical clusters using the
Hierarchical Tree Clustering algorithm. It then employs seriation to rearrange the
assets in the dendrogram, minimizing the distance between leaves.

The final step is the recursive bisection where each cluster is split between two
sub-clusters by starting with the topmost cluster and traversing in a top-down
manner. For each sub-cluster, we compute the total cluster risk of an inverse-risk
allocation. A weighting factor is then computed from these two sub-cluster risks,
which is used to update the cluster weight.

#### NOTE
The original paper uses the variance as the risk measure and the single-linkage
method for the Hierarchical Tree Clustering algorithm. Here we generalize it to
multiple risk measures and linkage methods.
The default linkage method is set to the Ward
variance minimization algorithm, which is more stable and has better properties
than the single-linkage method.

In this example, we will use the CVaR risk measure.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the SPX Index composition and the Factors dataset composed of the daily
prices of 5 ETFs representing common factors:

```Python
from plotly.io import show
from sklearn.model_selection import train_test_split

from skfolio import Population, RiskMeasure
from skfolio.cluster import HierarchicalClustering, LinkageMethod
from skfolio.datasets import load_factors_dataset, load_sp500_dataset
from skfolio.distance import KendallDistance
from skfolio.optimization import EqualWeighted, HierarchicalRiskParity
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import TimeSeriesFactorModel

prices = load_sp500_dataset()
factor_prices = load_factors_dataset()

prices = prices["2014":]
factor_prices = factor_prices["2014":]

X, factors = prices_to_returns(prices, factor_prices)
X_train, X_test, factors_train, factors_test = train_test_split(
    X, factors, test_size=0.33, shuffle=False
)
```

<a id="model"></a>

## Model

We create the CVaR Hierarchical Risk Parity model and then fit it on the training set:

```Python
model1 = HierarchicalRiskParity(
    risk_measure=RiskMeasure.CVAR, portfolio_params=dict(name="HRP-CVaR-Ward-Pearson")
)
model1.fit(X_train)
model1.weights_
```

```none
array([0.05033705, 0.02773558, 0.05289115, 0.03632272, 0.059202  ,
       0.02483767, 0.03790179, 0.07464383, 0.03497807, 0.08622477,
       0.06308422, 0.04094166, 0.03144452, 0.08277551, 0.04421773,
       0.04807705, 0.02596219, 0.07596741, 0.0393462 , 0.06310889])
```

<a id="risk-contribution"></a>

## Risk Contribution

Let’s analyze the risk contribution of the model on the training set:

```Python
ptf1 = model1.predict(X_train)
ptf1.plot_contribution(measure=RiskMeasure.CVAR)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="dendrogram"></a>

## Dendrogram

To analyze the clusters structure, we plot the dendrogram.
The blue lines represent distinct clusters composed of a single asset.
The remaining colors represent clusters of more than one asset:

```Python
model1.hierarchical_clustering_estimator_.plot_dendrogram(heatmap=False)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The horizontal axis represents the assets. The links between clusters are represented
as upside-down U-shaped lines. The height of the U indicates the distance between the
clusters. For example, the link representing the cluster containing assets HD and WMT
has a distance of 0.5 (called cophenetic distance).

When `heatmap` is set to True, the heatmap of the reordered distance matrix is
displayed below the dendrogram and clusters are outlined with yellow squares:

```Python
fig = model1.hierarchical_clustering_estimator_.plot_dendrogram()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<a id="linkage-methods"></a>

## Linkage Methods

The clustering can be greatly affected by the choice of the linkage method.
The original HRP is based on the single-linkage (equivalent to the minimum spanning
tree), which suffers from the chaining effect.
In the [`HierarchicalRiskParity`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity) estimator, the default
linkage method is set to the Ward variance minimization algorithm, which is more
stable and has better properties than the single-linkage method.

However, since the HRP optimization doesn’t utilize the full cluster structure but
only their orders, the allocation remains relatively stable regardless of the chosen
linkage method.

```Python
# To show this effect, let's create a second model with the single-linkage method:
model2 = HierarchicalRiskParity(
    risk_measure=RiskMeasure.CVAR,
    hierarchical_clustering_estimator=HierarchicalClustering(
        linkage_method=LinkageMethod.SINGLE,
    ),
    portfolio_params=dict(name="HRP-CVaR-Single-Pearson"),
)
model2.fit(X_train)

model2.hierarchical_clustering_estimator_.plot_dendrogram(heatmap=True)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

We can see that the clustering has been greatly affected by the change of the linkage
method. However, you will see below that the weights remain relatively stable for the
reason explained earlier.

<a id="distance-estimator"></a>

## Distance Estimator

The choice of distance metric also has an important effect on the clustering.
The default is to use the distance from the pearson correlation matrix.
This can be changed using the [distance estimators](https://skfolio.org/user_guide/distance.html.md#distance).

For example, let’s create a third model with a distance computed from the absolute
value of the Kendal correlation matrix:

```Python
model3 = HierarchicalRiskParity(
    risk_measure=RiskMeasure.CVAR,
    distance_estimator=KendallDistance(absolute=True),
    portfolio_params=dict(name="HRP-CVaR-Ward-Kendal"),
)
model3.fit(X_train)

model3.hierarchical_clustering_estimator_.plot_dendrogram(heatmap=True)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="prior-estimator"></a>

## Prior Estimator

Finally, HRP like the other portfolio optimization, uses a
[prior estimator](https://skfolio.org/user_guide/prior.html.md#prior) that fits a [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution)
containing the distribution estimate of asset returns.
The default is the [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior) estimator.

Let’s create new model with the [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel) estimator:

```Python
model4 = HierarchicalRiskParity(
    risk_measure=RiskMeasure.CVAR,
    prior_estimator=TimeSeriesFactorModel(),
    portfolio_params=dict(name="HRP-CVaR-Factor-Model"),
)
model4.fit(X_train, factors=factors_train)

model4.hierarchical_clustering_estimator_.plot_dendrogram(heatmap=True)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

To compare the models, we use an equal weighted benchmark using
the [`EqualWeighted`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted) estimator:

```Python
bench = EqualWeighted()
bench.fit(X_train)
bench.weights_
```

```none
array([0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05,
       0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05])
```

<a id="prediction"></a>

## Prediction

We predict the models and the benchmark on the test set:

```Python
population_test = Population([])
for model in [model1, model2, model3, model4, bench]:
    population_test.append(model.predict(X_test))

population_test.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="composition"></a>

## Composition

From the below composition, we notice that all models are relatively close to each
other, as explained earlier:

```Python
population_test.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="summary"></a>

## Summary

Finally, let’s print the summary statistics:

```Python
summary = population_test.summary()
summary.loc["Annualized Sharpe Ratio"]
```

```none
HRP-CVaR-Ward-Pearson      0.86
HRP-CVaR-Single-Pearson    0.84
HRP-CVaR-Ward-Kendal       0.86
HRP-CVaR-Factor-Model      0.87
EqualWeighted              0.86
Name: Annualized Sharpe Ratio, dtype: str
```

```Python
summary
```

[plotly figure stripped from llms output]
<br />
<br />

<a id="dendrogram"></a>

## Dendrogram

To analyze the clusters structure, we plot the dendrogram.
The blue lines represent distinct clusters composed of a single asset.
The remaining colors represent clusters of more than one asset:

```Python
fig = model1.hierarchical_clustering_estimator_.plot_dendrogram(heatmap=False)
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

The horizontal axis represents the assets. The links between clusters are represented
as upside-down U-shaped lines. The height of the U indicates the distance between the
clusters. For example, the link representing the cluster containing Assets HD and WMT
has a distance of 0.5 (called cophenetic distance).

When `heatmap` is set to True, the heatmap of the reordered distance matrix is
displayed below the dendrogram and clusters are outlined with yellow squares:

```Python
model1.hierarchical_clustering_estimator_.plot_dendrogram()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="linkage-methods"></a>

## Linkage Methods

The clustering can be greatly affected by the choice of the linkage method.
In the [`HierarchicalEqualRiskContribution`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution) estimator, the
default linkage method is set to the Ward variance minimization algorithm which is
more stable and has better properties than the single-linkage method, which suffers
from the chaining effect.

And because HERC rely on the dendrogram structure as opposed
to HRP, the choice of the linkage method will have a greater impact on the allocation.

To show this effect, let’s create a second model with the single-linkage method:

```Python
model2 = HierarchicalEqualRiskContribution(
    risk_measure=RiskMeasure.CDAR,
    hierarchical_clustering_estimator=HierarchicalClustering(
        linkage_method=LinkageMethod.SINGLE,
    ),
    portfolio_params=dict(name="HERC-CDaR-Single-Pearson"),
)
model2.fit(X_train)
model2.hierarchical_clustering_estimator_.plot_dendrogram(heatmap=True)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

We can see that the clustering has been greatly affected by the change of the linkage
method. Let’s analyze the risk contribution of this model on the training set:

```Python
ptf2 = model2.predict(X_train)
ptf2.plot_contribution(measure=RiskMeasure.CDAR)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The risk of that second model is very concentrated. We can already conclude that the
single-linkage method is not appropriate for this dataset. This will be confirmed
below on the test set.

<a id="distance-estimator"></a>

## Distance Estimator

The distance metric used also has an important effect on the clustering.
The default is to use the distance of the pearson correlation matrix.
This can be changed using the [distance estimators](https://skfolio.org/user_guide/distance.html.md#distance).
For example, let’s create a third model with a distance computed from the absolute
value of the Kendal correlation matrix:

```Python
model3 = HierarchicalEqualRiskContribution(
    risk_measure=RiskMeasure.CDAR,
    distance_estimator=KendallDistance(absolute=True),
    portfolio_params=dict(name="HERC-CDaR-Ward-Kendal"),
)
model3.fit(X_train)
model3.hierarchical_clustering_estimator_.plot_dendrogram(heatmap=True)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

To compare the models, we use an equal weighted benchmark using
the [`EqualWeighted`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted) estimator:

```Python
bench = EqualWeighted()
bench.fit(X_train)
bench.weights_
```

```none
array([0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05,
       0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05])
```

<a id="prediction"></a>

## Prediction

We predict the models and the benchmark on the test set:

```Python
population_test = Population([])
for model in [model1, model2, model3, bench]:
    population_test.append(model.predict(X_test))

population_test.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="composition"></a>

## Composition

From the below composition, we notice that the model with single-linkage method is
highly concentrated:

```Python
population_test.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

**Total running time of the script:** (0 minutes 3.211 seconds)

<a id="sphx-glr-download-auto-examples-clustering-plot-2-herc-cdar-py"></a>

# auto_examples/clustering/plot_3_hrp_vs_herc.html.md

<a id="sphx-glr-auto-examples-clustering-plot-3-hrp-vs-herc-py"></a>

<a id="hrp-vs-herc"></a>

# HRP vs HERC

In this tutorial, we will compare the
[`HierarchicalRiskParity`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity) (HRP) optimization with the
[`HierarchicalEqualRiskContribution`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution) (HERC) optimization.

For that comparison, we consider a 3 months rolling (60 business days) allocation fitted
on the preceding year of data (252 business days) that minimizes the CVaR.

We will employ `GridSearchCV` to select the optimal parameters of each model on the
training set using cross-validation that achieves the highest average out-of-sample
Mean-CVaR ratio.

Then, we will evaluate the models on the test set and compare them with the
equal-weighted benchmark.

Finally, we will use the [`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) to
analyze the stability and distribution of both models.

<a id="data"></a>

## Data

We load the FTSE 100 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 64
assets from the FTSE 100 Index composition starting from 2000-01-04 up to 2023-05-31:

```Python
from plotly.io import show
from sklearn.model_selection import GridSearchCV, train_test_split

from skfolio import Population, RatioMeasure, RiskMeasure
from skfolio.cluster import HierarchicalClustering, LinkageMethod
from skfolio.datasets import load_ftse100_dataset
from skfolio.distance import KendallDistance, PearsonDistance
from skfolio.metrics import make_scorer
from skfolio.model_selection import (
    CombinatorialPurgedCV,
    WalkForward,
    cross_val_predict,
    optimal_folds_number,
)
from skfolio.optimization import (
    HierarchicalEqualRiskContribution,
    HierarchicalRiskParity,
)
from skfolio.preprocessing import prices_to_returns

prices = load_ftse100_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="model"></a>

## Model

We create two models: an HRP-CVaR and an HERC-CVaR:

```Python
model_hrp = HierarchicalRiskParity(
    risk_measure=RiskMeasure.CVAR,
    hierarchical_clustering_estimator=HierarchicalClustering(),
)

model_herc = HierarchicalEqualRiskContribution(
    risk_measure=RiskMeasure.CVAR,
    hierarchical_clustering_estimator=HierarchicalClustering(),
)
```

<a id="parameter-tuning"></a>

## Parameter Tuning

For both HRP and HERC models, we find the parameters that maximize the average
out-of-sample Mean-CVaR ratio using `GridSearchCV` with `WalkForward` cross-validation
on the training set. The `WalkForward` splits are chosen to simulate a three-month
(60 business days) rolling portfolio fitted on the previous year (252 business days):

```Python
cv = WalkForward(train_size=252, test_size=60)

grid_search_hrp = GridSearchCV(
    estimator=model_hrp,
    cv=cv,
    n_jobs=-1,
    param_grid={
        "distance_estimator": [PearsonDistance(), KendallDistance()],
        "hierarchical_clustering_estimator__linkage_method": [
            # LinkageMethod.SINGLE,
            LinkageMethod.WARD,
            LinkageMethod.COMPLETE,
        ],
    },
    scoring=make_scorer(RatioMeasure.CVAR_RATIO),
)
grid_search_hrp.fit(X_train)
model_hrp = grid_search_hrp.best_estimator_
print(model_hrp)
```

```none
HierarchicalRiskParity(distance_estimator=KendallDistance(),
                       hierarchical_clustering_estimator=HierarchicalClustering(),
                       risk_measure=CVaR)
```

```Python
grid_search_herc = grid_search_hrp.set_params(estimator=model_herc)
grid_search_herc.fit(X_train)
model_herc = grid_search_herc.best_estimator_
print(model_herc)
```

```none
HierarchicalEqualRiskContribution(distance_estimator=PearsonDistance(),
                                  hierarchical_clustering_estimator=HierarchicalClustering(linkage_method=COMPLETE),
                                  risk_measure=CVaR)
```

<a id="prediction"></a>

## Prediction

We evaluate the two models using the same `WalkForward` object on the test set:

```Python
pred_hrp = cross_val_predict(
    model_hrp,
    X_test,
    cv=cv,
    n_jobs=-1,
    portfolio_params=dict(name="HRP"),
)

pred_herc = cross_val_predict(
    model_herc,
    X_test,
    cv=cv,
    n_jobs=-1,
    portfolio_params=dict(name="HERC"),
)
```

Each predicted object is a `MultiPeriodPortfolio`.
For improved analysis, we can add them to a `Population`:

```Python
population = Population([pred_hrp, pred_herc])
```

Let’s plot the rolling portfolios compositions:

```Python
population.plot_composition(display_sub_ptf_name=False)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s plot the rolling portfolios cumulative returns on the test set:

```Python
population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="analysis"></a>

## Analysis

HERC outperform HRP both in terms of CVaR minimization and Mean-CVaR ratio
maximization:

```Python
for ptf in population:
    print("=" * 25)
    print(" " * 8 + ptf.name)
    print("=" * 25)
    print(f"CVaR : {ptf.cvar:0.2%}")
    print(f"Mean-CVaR ratio : {ptf.cvar_ratio:0.4f}")
    print("\n")
```

```none
=========================
        HRP
=========================
CVaR : 2.44%
Mean-CVaR ratio : 0.0141

=========================
        HERC
=========================
CVaR : 2.45%
Mean-CVaR ratio : 0.0159
```

<a id="combinatorial-purged-cross-validation"></a>

## Combinatorial Purged Cross-Validation

Only using one testing path (the historical path) may not be enough to compare
models. For a more robust analysis, we can use the
[`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) to create multiple testing
paths from different training folds combinations.

We choose `n_folds` and `n_test_folds` to obtain around 100 test paths and an average
training size of 252 days:

```Python
n_folds, n_test_folds = optimal_folds_number(
    n_observations=X_test.shape[0],
    target_n_test_paths=100,
    target_train_size=252,
)

cv = CombinatorialPurgedCV(n_folds=n_folds, n_test_folds=n_test_folds)
cv.summary(X_test)
```

```none
Number of Observations             1967
Total Number of Folds                16
Number of Test Folds                 14
Purge Size                            0
Embargo Size                          0
Average Training Size               245
Number of Test Paths                105
Number of Training Combinations     120
dtype: int64
```

```Python
pred_hrp = cross_val_predict(
    model_hrp,
    X_test,
    cv=cv,
    n_jobs=-1,
    portfolio_params=dict(tag="HRP"),
)
pred_herc = cross_val_predict(
    model_herc,
    X_test,
    cv=cv,
    n_jobs=-1,
    portfolio_params=dict(tag="HERC"),
)
```

The predicted object is a `Population` of `MultiPeriodPortfolio`. Each
`MultiPeriodPortfolio` represents one testing path of a rolling portfolio.
For improved analysis, we can merge the populations of each model:

```Python
population = pred_hrp + pred_herc
```

<a id="distribution"></a>

## Distribution

We plot the out-of-sample distribution of Mean-CVaR Ratio for each model:

```Python
population.plot_distribution(
    measure_list=[RatioMeasure.CVAR_RATIO], tag_list=["HRP", "HERC"], n_bins=50
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

```Python
for pred in [pred_hrp, pred_herc]:
    print("=" * 25)
    print(" " * 8 + pred[0].tag)
    print("=" * 25)
    print(
        "Average Mean-CVaR ratio :"
        f" {pred.measures_mean(measure=RatioMeasure.CVAR_RATIO):0.4f}"
    )
    print(
        "Std Mean-CVaR ratio :"
        f" {pred.measures_std(measure=RatioMeasure.CVAR_RATIO):0.4f}"
    )
    print("\n")
```

```none
=========================
        HRP
=========================
Average Mean-CVaR ratio : 0.0149
Std Mean-CVaR ratio : 0.0005

=========================
        HERC
=========================
Average Mean-CVaR ratio : 0.0157
Std Mean-CVaR ratio : 0.0029
```

We can see that, in terms of Mean-CVaR Ratio distribution, the HERC model has a higher
mean than the HRP model but also a higher standard deviation. In other words, HERC is
less stable than HRP but performs slightly better in average.

We can do the same analysis for other measures:

```Python
fig = population.plot_distribution(
    measure_list=[
        RatioMeasure.ANNUALIZED_SHARPE_RATIO,
        RatioMeasure.ANNUALIZED_SORTINO_RATIO,
    ],
    tag_list=["HRP", "HERC"],
    n_bins=50,
)
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

**Total running time of the script:** (3 minutes 4.695 seconds)

<a id="sphx-glr-download-auto-examples-clustering-plot-3-hrp-vs-herc-py"></a>

# auto_examples/clustering/plot_4_nco.html.md

<a id="sphx-glr-auto-examples-clustering-plot-4-nco-py"></a>

<a id="nested-clusters-optimization"></a>

# Nested Clusters Optimization

This tutorial introduces the [`NestedClustersOptimization`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization)
optimization.

Nested Clusters Optimization (NCO) is a portfolio optimization method developed by
Marcos Lopez de Prado.

It uses a distance matrix to compute clusters using a clustering algorithm (
Hierarchical Tree Clustering, KMeans, etc.). For each cluster, the inner-cluster
weights are computed by fitting the inner-estimator on each cluster using the whole
training data. Then the outer-cluster weights are computed by training the
outer-estimator using out-of-sample estimates of the inner-estimators with
cross-validation. Finally, the final assets weights are the dot-product of the
inner-weights and outer-weights.

#### NOTE
The original paper uses KMeans as the clustering algorithm, minimum Variance for
the inner-estimator and equal-weight for the outer-estimator. Here we generalize
it to all `sklearn` and `skfolio` clustering algorithms (Hierarchical Tree
Clustering, KMeans, etc.), all portfolio optimizations (Mean-Variance, HRP, etc.)
and risk measures (variance, CVaR, etc.).
To avoid data leakage at the outer-estimator, we use out-of-sample estimates to
fit the outer estimator.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 1990-01-02 up to 2022-12-28:

```Python
from plotly.io import show
from sklearn.cluster import KMeans
from sklearn.model_selection import train_test_split

from skfolio import Population, RiskMeasure
from skfolio.cluster import HierarchicalClustering, LinkageMethod
from skfolio.datasets import load_sp500_dataset
from skfolio.distance import KendallDistance
from skfolio.optimization import (
    EqualWeighted,
    MeanRisk,
    NestedClustersOptimization,
    ObjectiveFunction,
    RiskBudgeting,
)
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="model"></a>

## Model

We create an NCO model that maximizes the Sharpe Ratio intra-cluster and uses a CVaR
Risk Parity inter-cluster. By default, the inter-cluster optimization
uses `KFolds` out-of-sample estimates of the inner-estimator to avoid data leakage.
and the [`HierarchicalClustering`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering) estimator
to form the clusters:

```Python
inner_estimator = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    risk_measure=RiskMeasure.VARIANCE,
)
outer_estimator = RiskBudgeting(risk_measure=RiskMeasure.CVAR)

model1 = NestedClustersOptimization(
    inner_estimator=inner_estimator,
    outer_estimator=outer_estimator,
    n_jobs=-1,
    portfolio_params=dict(name="NCO-1"),
)
model1.fit(X_train)
model1.weights_
```

```none
array([4.34543978e-02, 3.10829511e-03, 2.62486890e-08, 4.55211425e-02,
       7.75888788e-02, 6.00673635e-02, 4.72963471e-02, 1.25134741e-01,
       4.62239419e-02, 3.16526258e-02, 5.09579674e-08, 2.40362071e-03,
       8.64003931e-02, 3.19344335e-02, 6.00539119e-02, 4.79349823e-02,
       9.30716937e-02, 5.98340197e-02, 4.48376606e-02, 9.34814738e-02])
```

<a id="dendrogram"></a>

## Dendrogram

To analyze the clusters structure, we can plot the dendrogram.
The blue lines represent distinct clusters composed of a single asset.
The remaining colors represent clusters of more than one asset:

```Python
model1.clustering_estimator_.plot_dendrogram(heatmap=False)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The horizontal axis represents the assets. The links between clusters are represented
as upside-down U-shaped lines. The height of the U indicates the distance between the
clusters. For example, the link representing the cluster containing Assets HD and WMT
has a distance of 0.5 (called cophenetic distance).

When `heatmap` is set to True, the heatmap of the reordered distance matrix is
displayed below the dendrogram and clusters are outlined with yellow squares:

```Python
model1.clustering_estimator_.plot_dendrogram()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="linkage-methods"></a>

## Linkage Methods

The hierarchical clustering can be greatly affected by the choice of the linkage
method. In the [`HierarchicalClustering`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering) estimator, the default
linkage method is set to the Ward variance minimization algorithm, which is more
stable and has better properties than the single-linkage method which suffers from the
chaining effect.

To show this effect, let’s create a second model with the
single-linkage method:

```Python
model2 = NestedClustersOptimization(
    inner_estimator=inner_estimator,
    outer_estimator=outer_estimator,
    clustering_estimator=HierarchicalClustering(
        linkage_method=LinkageMethod.SINGLE,
    ),
    n_jobs=-1,
    portfolio_params=dict(name="NCO-2"),
)
model2.fit(X_train)
model2.clustering_estimator_.plot_dendrogram(heatmap=True)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="distance-estimator"></a>

## Distance Estimator

The distance metric used also has an important effect on the clustering.
The default is to use the distance of the pearson correlation matrix.
This can be changed using the [distance estimators](https://skfolio.org/user_guide/distance.html.md#distance).

For example, let’s create a third model with a distance computed from the absolute
value of the Kendal correlation matrix:

```Python
model3 = NestedClustersOptimization(
    inner_estimator=inner_estimator,
    outer_estimator=outer_estimator,
    distance_estimator=KendallDistance(absolute=True),
    n_jobs=-1,
    portfolio_params=dict(name="NCO-3"),
)
model3.fit(X_train)
model3.clustering_estimator_.plot_dendrogram(heatmap=True)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="clustering-estimator"></a>

## Clustering Estimator

The above models used the default [`HierarchicalClustering`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering)
estimator. This can be replaced by any `sklearn` or `skfolio` clustering estimators.

For example, let’s create a new model with `sklearn.cluster.KMeans`:

```Python
model4 = NestedClustersOptimization(
    inner_estimator=inner_estimator,
    outer_estimator=outer_estimator,
    clustering_estimator=KMeans(n_init="auto"),
    n_jobs=-1,
    portfolio_params=dict(name="NCO-4"),
)
model4.fit(X_train)
model4.weights_
```

```none
array([9.20271408e-02, 6.38925015e-02, 2.42910005e-08, 3.98113334e-02,
       5.21527289e-02, 5.55873992e-02, 4.13638705e-02, 6.42825849e-02,
       4.27764524e-02, 6.04785422e-02, 3.30760910e-08, 5.05416009e-08,
       1.12005876e-01, 5.58256686e-02, 2.71966454e-02, 8.36394178e-02,
       3.38987010e-02, 6.03711057e-02, 3.92135820e-02, 7.54763420e-02])
```

To compare the NCO models, we use an equal weighted benchmark using
the [`EqualWeighted`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted) estimator:

```Python
bench = EqualWeighted()
bench.fit(X_train)
bench.weights_
```

```none
array([0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05,
       0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05])
```

<a id="prediction"></a>

## Prediction

We predict the models and the benchmark on the test set:

```Python
population_test = Population([])
for model in [model1, model2, model3, model4, bench]:
    population_test.append(model.predict(X_test))

population_test.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="composition"></a>

## Composition

Let’s plot each portfolio composition:

```Python
fig = population_test.plot_composition()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

**Total running time of the script:** (0 minutes 4.484 seconds)

<a id="sphx-glr-download-auto-examples-clustering-plot-4-nco-py"></a>

# auto_examples/clustering/plot_5_nco_grid_search.html.md

<a id="sphx-glr-auto-examples-clustering-plot-5-nco-grid-search-py"></a>

<a id="nco-combinatorial-purged-cv"></a>

# NCO - Combinatorial Purged CV

The previous tutorial introduced the
[`NestedClustersOptimization`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization).

In this tutorial, we will perform hyperparameter search using `GridSearch` and
distribution analysis with `CombinatorialPurgedCV`.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 2015-01-02 up to 2022-12-28:

```Python
from plotly.io import show
from sklearn.model_selection import GridSearchCV, train_test_split

from skfolio import Population, RatioMeasure, RiskMeasure
from skfolio.cluster import HierarchicalClustering, LinkageMethod
from skfolio.datasets import load_sp500_dataset
from skfolio.distance import KendallDistance, PearsonDistance
from skfolio.model_selection import (
    CombinatorialPurgedCV,
    WalkForward,
    cross_val_predict,
    optimal_folds_number,
)
from skfolio.optimization import (
    EqualWeighted,
    MeanRisk,
    NestedClustersOptimization,
    RiskBudgeting,
)
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
prices = prices["2015":]

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.5, shuffle=False)
```

<a id="model"></a>

## Model

We create two models: the NCO and the equal-weighted benchmark:

```Python
benchmark = EqualWeighted()

model_nco = NestedClustersOptimization(
    inner_estimator=MeanRisk(), clustering_estimator=HierarchicalClustering()
)
```

<a id="parameter-tuning"></a>

## Parameter Tuning

We find the model parameters that maximizes the out-of-sample Sharpe ratio using
`GridSearchCV` with `WalkForward` cross-validation on the training set.
The `WalkForward` splits are chosen to simulate a three-month (60 business days) rolling
portfolio fitted on the previous year (252 business days):

```Python
cv = WalkForward(train_size=252, test_size=60)

grid_search_hrp = GridSearchCV(
    estimator=model_nco,
    cv=cv,
    n_jobs=-1,
    param_grid={
        "inner_estimator__risk_measure": [RiskMeasure.VARIANCE, RiskMeasure.CVAR],
        "outer_estimator": [
            EqualWeighted(),
            RiskBudgeting(risk_measure=RiskMeasure.CVAR),
        ],
        "clustering_estimator__linkage_method": [
            LinkageMethod.SINGLE,
            LinkageMethod.WARD,
        ],
        "distance_estimator": [PearsonDistance(), KendallDistance()],
    },
)
grid_search_hrp.fit(X_train)
model_nco = grid_search_hrp.best_estimator_
print(model_nco)
```

```none
/home/runner/work/skfolio/skfolio/.venv/lib/python3.13/site-packages/sklearn/model_selection/_validation.py:493: FitFailedWarning:
9 fits failed out of a total of 192.
The score on these train-test partitions for these parameters will be set to nan.
If these failures are not expected, you can try to debug them by setting error_score='raise'.

Below are more details about the failures:
--------------------------------------------------------------------------------
9 fits failed with the following error:
Traceback (most recent call last):
  File "/home/runner/work/skfolio/skfolio/.venv/lib/python3.13/site-packages/sklearn/model_selection/_validation.py", line 853, in _fit_and_score
    estimator.fit(X_train, **fit_params)
    ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/skfolio/skfolio/src/skfolio/optimization/_base.py", line 152, in _wrapped_fit
    self._run_fallback_chain(
    ~~~~~~~~~~~~~~~~~~~~~~~~^
        X=X, y=y, primary_error=primary_error, **fit_params
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/runner/work/skfolio/skfolio/src/skfolio/optimization/_base.py", line 204, in _run_fallback_chain
    raise primary_error
  File "/home/runner/work/skfolio/skfolio/src/skfolio/optimization/_base.py", line 149, in _wrapped_fit
    original_fit(self, X, y, **fit_params)
    ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/skfolio/skfolio/src/skfolio/optimization/cluster/_nco.py", line 480, in fit
    fit_single_estimator(self.outer_estimator_, X_pred, y_pred, fit_params={})
    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/skfolio/skfolio/src/skfolio/utils/tools.py", line 901, in fit_single_estimator
    getattr(estimator, method)(X, y, **fit_params)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/skfolio/skfolio/src/skfolio/optimization/_base.py", line 152, in _wrapped_fit
    self._run_fallback_chain(
    ~~~~~~~~~~~~~~~~~~~~~~~~^
        X=X, y=y, primary_error=primary_error, **fit_params
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/runner/work/skfolio/skfolio/src/skfolio/optimization/_base.py", line 204, in _run_fallback_chain
    raise primary_error
  File "/home/runner/work/skfolio/skfolio/src/skfolio/optimization/_base.py", line 149, in _wrapped_fit
    original_fit(self, X, y, **fit_params)
    ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_risk_budgeting.py", line 710, in fit
    self._solve_problem(
    ~~~~~~~~~~~~~~~~~~~^
        problem=problem,
        ^^^^^^^^^^^^^^^^
    ...<7 lines>...
        },
        ^^
    )
    ^
  File "/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py", line 1225, in _solve_problem
    weights, self.problem_values_ = _solve(
                                    ~~~~~~^
        w=w,
        ^^^^
    ...<6 lines>...
        scale_objective=self._scale_objective,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py", line 2561, in _solve
    raise cp.SolverError(error) from None
cvxpy.error.SolverError: Solver 'CLARABEL' failed. Try another solver, or solve with solver_params=dict(verbose=True) for more information

  warnings.warn(some_fits_failed_message, FitFailedWarning)
NestedClustersOptimization(clustering_estimator=HierarchicalClustering(),
                           distance_estimator=PearsonDistance(),
                           inner_estimator=MeanRisk(risk_measure=CVaR),
                           outer_estimator=EqualWeighted())
```

<a id="prediction"></a>

## Prediction

We evaluate the two models using the same `WalkForward` object on the test set:

```Python
pred_bench = cross_val_predict(
    benchmark,
    X_test,
    cv=cv,
    portfolio_params=dict(name="Benchmark"),
)

pred_nco = cross_val_predict(
    model_nco,
    X_test,
    cv=cv,
    n_jobs=-1,
    portfolio_params=dict(name="NCO"),
)
```

Each predicted object is a `MultiPeriodPortfolio`.
For improved analysis, we can add them to a `Population`:

```Python
population = Population([pred_bench, pred_nco])
```

Let’s plot the rolling portfolios compositions:

```Python
population.plot_composition(display_sub_ptf_name=False)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s plot the rolling portfolios cumulative returns on the test set:

```Python
fig = population.plot_cumulative_returns()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<a id="analysis"></a>

## Analysis

The NCO outperforms the Benchmark on the test set for the below measures:
maximization:

```Python
for ptf in population:
    print("=" * 25)
    print(" " * 8 + ptf.name)
    print("=" * 25)
    print(f"Ann. Sharpe ratio : {ptf.annualized_sharpe_ratio:0.2f}")
    print(f"CVaR ratio : {ptf.cvar_ratio:0.4f}")
    print("\n")
```

```none
=========================
        Benchmark
=========================
Ann. Sharpe ratio : 0.88
CVaR ratio : 0.0235

=========================
        NCO
=========================
Ann. Sharpe ratio : 1.30
CVaR ratio : 0.0376
```

<a id="combinatorial-purged-cross-validation"></a>

## Combinatorial Purged Cross-Validation

Only using one testing path (the historical path) may not be enough for comparing both
models. For a more robust analysis, we can use
[`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) to create multiple testing
paths from different training folds combinations.

We choose `n_folds` and `n_test_folds` to obtain around 30 test paths and an average
training size of 252 days:

```Python
n_folds, n_test_folds = optimal_folds_number(
    n_observations=X_test.shape[0],
    target_n_test_paths=30,
    target_train_size=252,
)

cv = CombinatorialPurgedCV(n_folds=n_folds, n_test_folds=n_test_folds)
cv.summary(X_test)
```

```none
Number of Observations             1006
Total Number of Folds                 9
Number of Test Folds                  7
Purge Size                            0
Embargo Size                          0
Average Training Size               223
Number of Test Paths                 28
Number of Training Combinations      36
dtype: int64
```

```Python
pred_nco = cross_val_predict(
    model_nco,
    X_test,
    cv=cv,
    n_jobs=-1,
    portfolio_params=dict(tag="NCO"),
)
```

The predicted object is a `Population` of `MultiPeriodPortfolio`. Each
`MultiPeriodPortfolio` represents one testing path of a rolling portfolio.

<a id="distribution"></a>

## Distribution

We plot the out-of-sample distribution of Sharpe Ratio for the NCO model:

```Python
pred_nco.plot_distribution(measure_list=[RatioMeasure.ANNUALIZED_SHARPE_RATIO])
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s print the average and standard-deviation of out-of-sample Sharpe Ratios:

```Python
print(
    "Average of Sharpe Ratio :"
    f" {pred_nco.measures_mean(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO):0.2f}"
)
print(
    "Std of Sharpe Ratio :"
    f" {pred_nco.measures_std(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO):0.2f}"
)
```

```none
Average of Sharpe Ratio : 0.86
Std of Sharpe Ratio : 0.18
```

Let’s compare it with the benchmark:

```Python
pred_bench = benchmark.fit_predict(X_test)
print(pred_bench.annualized_sharpe_ratio)
```

```none
1.0507476631082548
```

<a id="conclusion"></a>

## Conclusion

This NCO model outperforms the Benchmark in terms of Sharpe Ratio on the historical
test set. However, the distribution analysis on the recombined (non-historical) test
sets shows that it slightly underperforms the Benchmark in average.

This was a toy example to present the API. Further analysis using different
estimators, datasets and CV parameters should be performed to determine if the
outperformance on the historical test set is due to chance or if this NCO model is
able to exploit time-dependencies information lost in `CombinatorialPurgedCV`.

**Total running time of the script:** (0 minutes 43.943 seconds)

<a id="sphx-glr-download-auto-examples-clustering-plot-5-nco-grid-search-py"></a>

# auto_examples/clustering/plot_6_schur.html.md

<a id="sphx-glr-auto-examples-clustering-plot-6-schur-py"></a>

<a id="schur-complementary-allocation"></a>

# Schur Complementary Allocation

This tutorial introduces the [`SchurComplementary`](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#skfolio.optimization.SchurComplementary)
allocation.

Schur Complementary Allocation is a portfolio allocation method developed by Peter
Cotton <sup>[1](#id4)</sup>.

It uses Schur-complement-inspired augmentation of sub-covariance matrices,
revealing a link between Hierarchical Risk Parity (HRP) and minimum-variance
portfolios (MVP).

By tuning the regularization factor `gamma`, which governs how much off-diagonal
information is incorporated into the augmented covariance blocks, the method
smoothly interpolates from the heuristic divide-and-conquer allocation of HRP
(`gamma = 0`) to the MVP solution (`gamma -> 1`).

#### NOTE
A poorly conditioned covariance matrix can prevent convergence to the MVP solution
as gamma approaches one. Setting `keep_monotonic=True` (the default) ensures that
the portfolio variance decreases monotonically with respect to gamma and remains
bounded by the variance of the HRP portfolio (`variance(Schur) <= variance(HRP)`),
even in the presence of ill-conditioned covariance matrices. Additionally, you can
apply shrinkage or other conditioning techniques via the `prior_estimator` parameter
to improve numerical stability and estimation accuracy.

<a id="data-loading"></a>

## Data Loading

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 2020-01-02 up to 2022-12-28:

```Python
import numpy as np
import scipy.stats as stats
from plotly.io import show
from sklearn.model_selection import RandomizedSearchCV, train_test_split

from skfolio import PerfMeasure, Population, RatioMeasure, RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.distance import KendallDistance, PearsonDistance
from skfolio.metrics import make_scorer
from skfolio.model_selection import MultipleRandomizedCV, WalkForward, cross_val_predict
from skfolio.moments import (
    LedoitWolf,
)
from skfolio.optimization import (
    HierarchicalRiskParity,
    MeanRisk,
    SchurComplementary,
)
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior

prices = load_sp500_dataset()
X = prices_to_returns(prices)
```

We select **10 assets** from the 20 and split the data chronologically: 70% for
training and 30% for testing.

```Python
# `shuffle=False` preserves chronological order, crucial for time-series data.
X_train, X_test = train_test_split(X.iloc[:, 10:], test_size=0.3, shuffle=False)
```

<a id="schur-complementary-model"></a>

## Schur Complementary Model

We start by fitting a simple [`SchurComplementary`](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#skfolio.optimization.SchurComplementary) model
with `gamma=0.5`:

```Python
model = SchurComplementary(gamma=0.5)
model.fit(X_train)
print(model.weights_)
```

```none
[0.03687455 0.0613539  0.0659264  0.18201864 0.03743585 0.21311991
 0.02811169 0.07392489 0.10507859 0.19615558]
```

<a id="efficient-frontier-comparison"></a>

## Efficient Frontier Comparison

Let’s take a closer look at how the Schur allocation behaves compared to other
methods.

To do that, we’re going to fit a few different portfolio models on the
**training set**:

* Minimum-Variance (MVP)
* Mean-Variance Efficient Frontier: 20 Markowitz portfolios spanning different risk levels (MVO)
* Hierarchical Risk Parity (HRP)
* 20 Schur portfolios with gamma values ranging from 0 to 1

We apply a Ledoit-Wolf shrinkage estimator to regularize the covariance matrix for
every model.

Finally, we’ll evaluate all these portfolios on the **test set** to see how well they
generalize.

```Python
prior = EmpiricalPrior(covariance_estimator=LedoitWolf())

population_train = Population([])
population_test = Population([])

# 20 Schur portfolios
for gamma in np.linspace(0.0, 1.0, 20):
    schur = SchurComplementary(
        gamma=gamma,
        prior_estimator=prior,
        portfolio_params={"name": f"Schur {gamma:0.2f}", "tag": "Schur"},
    )
    # Train
    ptf = schur.fit_predict(X_train)
    population_train.append(ptf)
    # Test
    ptf = schur.predict(X_test)
    population_test.append(ptf)

# HRP portfolio
hrp = HierarchicalRiskParity(prior_estimator=prior, portfolio_params={"tag": "HRP"})
# Train
ptf = hrp.fit_predict(X_train)
population_train.append(ptf)
hrp_std = ptf.standard_deviation
# Test
ptf = hrp.predict(X_test)
population_test.append(ptf)

# 20 MVO (including MVP) portfolios
mean_variance = MeanRisk(
    prior_estimator=prior,
    efficient_frontier_size=20,
    max_standard_deviation=hrp_std,
    portfolio_params={"tag": "MVO"},
)
# Train
mv_population_train = mean_variance.fit_predict(X_train)
mv_population_train[0].tag = "MVP"
population_train += mv_population_train
# Test
mv_population_test = mean_variance.predict(X_test)
mv_population_test[0].tag = "MVP"
population_test += mv_population_test
```

Plot Mean-Variance Frontiers on training set

```Python
fig = population_train.plot_measures(
    x=RiskMeasure.ANNUALIZED_STANDARD_DEVIATION,
    y=PerfMeasure.ANNUALIZED_MEAN,
    hover_measures=[RatioMeasure.ANNUALIZED_SHARPE_RATIO],
    title="Training Set | MVO - HRP - Schur",
)
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Plot Mean-Variance Frontiers on test set

```Python
population_test.plot_measures(
    x=RiskMeasure.ANNUALIZED_STANDARD_DEVIATION,
    y=PerfMeasure.ANNUALIZED_MEAN,
    hover_measures=[RatioMeasure.ANNUALIZED_SHARPE_RATIO],
    title="Test Set | MVO - HRP - Schur",
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Plot portfolio compositions

```Python
population_train.filter(tags=["Schur", "MVP", "MVO"]).plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="analysis"></a>

## Analysis

* When `gamma = 0`, the Schur portfolio is exactly equal to HRP.
* As `gamma` increases toward 1, it gradually approaches the MVP solution,
  **without fully reaching it**.
* On the **training set**, both Schur and HRP portfolios are Pareto dominated
  by the MVO portfolios, as expected, since those lie on the efficient frontier
  by construction.
* On the **test set**, Schur portfolios dominate the MVO portfolios.

We observe a reversal in the relative frontiers (mean-variance dominance) between the
training and test sets: MVO portfolios dominate in-sample, but their structure
fails to hold out-of-sample versus Schur portfolios, which generalize more
effectively.

Below, we’ll show how to model a more realistic train/test rebalancing strategy
and how to find the optimal `gamma` parameter.

<a id="rebalancing-strategy"></a>

## Rebalancing Strategy

We use [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) to define a quarterly rebalancing
(60 trading days), training on the prior three years (3\*252 trading days):

```Python
walk_forward = WalkForward(test_size=60, train_size=252 * 3)
```

Note that [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) also supports specific
datetime frequencies. For example, we could use
`walk_forward = WalkForward(test_size=3, train_size=36, freq="WOM-3FRI")` to
rebalance quarterly on the **third Friday** (WOM-3FRI), training on the prior 36
months.

<a id="hyperparameter-tuning"></a>

## Hyperparameter Tuning

We’ll tune the Schur model’s `gamma` and distance metric using
`RandomizedSearchCV`, optimizing for out-of-sample mean-CDaR Ratio:

```Python
model = SchurComplementary(prior_estimator=prior)

random_search = RandomizedSearchCV(
    estimator=model,
    cv=walk_forward,
    n_jobs=-1,
    param_distributions={
        "gamma": stats.uniform(0, 1),
        "distance_estimator": [PearsonDistance(), KendallDistance()],
    },
    n_iter=10,
    scoring=make_scorer(RatioMeasure.CDAR_RATIO),
    random_state=0,
)
random_search.fit(X_train)

# Retrieve the best estimator from the search.
schur = random_search.best_estimator_
schur
```

[plotly figure stripped from llms output]
<br />
<br />

Let’s display a summary of key performance metrics:

```Python
summary = population.summary()
print(summary.loc[["Annualized Sharpe Ratio", "CDaR Ratio at 95%"]])
```

```none
                          Schur     MVP
Annualized Sharpe Ratio    0.99    0.72
CDaR Ratio at 95%        0.0052  0.0032
```

A single backtest path represents one possible trajectory of cumulative
returns under the given rebalancing scheme and parameter set. While easy
to compute, it may understate the variability and uncertainty of real-world
performance compared to resampling-based methods.

<a id="multiple-randomized-cross-validation"></a>

## Multiple Randomized Cross-Validation

Using the [`MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV) methodology of
Palomar in <sup>[2](#id5)</sup>, we perform resampling-based cross-validation by drawing 200
subsamples of 10 distinct assets from the 20-asset universe and contiguous 5-year
windows (5 x 252 trading days). We then apply our walk-forward split to each
subsample. This approach captures both temporal and cross-sectional variability:

```Python
X_train, X_test = train_test_split(X, test_size=0.3, shuffle=False)

cv_mc = MultipleRandomizedCV(
    walk_forward=walk_forward,
    n_subsamples=200,
    asset_subset_size=10,
    window_size=5 * 252,
    random_state=0,
)

# Generate cross-validated predictions for both models.
pred_mvo_mc = cross_val_predict(
    mvo, X_test, cv=cv_mc, n_jobs=-1, portfolio_params={"tag": "MVP"}
)

pred_schur_mc = cross_val_predict(
    schur, X_test, cv=cv_mc, n_jobs=-1, portfolio_params={"tag": "Schur"}
)

# Combine results for easier analysis.
population_mc = pred_mvo_mc + pred_schur_mc
```

Let’s plot the distribution of out-of-sample performance metrics (e.g., Sharpe ratio,
CDaR ratio) across all resampled subsamples for both the Schur and MVP portfolios.
This helps assess how robust each model is across different asset combinations and
time periods:

```Python
population_mc.plot_distribution(
    measure_list=[RatioMeasure.ANNUALIZED_SHARPE_RATIO], tag_list=["MVP", "Schur"]
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

```Python
population_mc.plot_distribution(
    measure_list=[RatioMeasure.CDAR_RATIO], tag_list=["MVP", "Schur"]
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

```Python
for pred in [pred_mvo_mc, pred_schur_mc]:
    tag = pred[0].tag
    mean_sr = pred.measures_mean(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO)
    std_sr = pred.measures_std(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO)
    print(f"{tag}\n{'=' * len(tag)}")
    print(f"Average Sharpe Ratio: {mean_sr:0.2f}")
    print(f"Sharpe Ratio Std Dev: {std_sr:0.2f}\n")
```

```none
MVP
===
Average Sharpe Ratio: 0.71
Sharpe Ratio Std Dev: 0.34

Schur
=====
Average Sharpe Ratio: 0.87
Sharpe Ratio Std Dev: 0.38
```

In this simple example, Schur portfolios tend to outperform MVP out-of-sample,
exhibiting higher average Sharpe and CDaR ratios.

For a full tutorial on [`MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV),
see [L1 and L2 Regularization](https://skfolio.org/auto_examples/mean_risk/plot_8_regularization.html.md#sphx-glr-auto-examples-mean-risk-plot-8-regularization-py).
For additional cross-validation methods, such as
[`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) from de Prado <sup>[3](#id6)</sup>,
refer to [the model selection section](https://skfolio.org/auto_examples/model_selection/index.html.md#model-selection-examples).

<a id="conclusion"></a>

## Conclusion

This short example introduced the Schur Complementary Allocation method
and demonstrated how to use the `skfolio` API to train, evaluate, tune, and compare
Schur portfolios with other allocation strategies.

<a id="references"></a>

## References

* <a id='id4'>**[1]**</a> “Schur Complementary Allocation: A Unification of Hierarchical Risk Parity and Minimum Variance Portfolios”. Peter Cotton (2024).
* <a id='id5'>**[2]**</a> “Portfolio Optimization: Theory and Application”, Chapter 8, Daniel P. Palomar (2025)
* <a id='id6'>**[3]**</a> “Advances in Financial Machine Learning”, Marcos López de Prado (2018)

**Total running time of the script:** (1 minutes 46.933 seconds)

<a id="sphx-glr-download-auto-examples-clustering-plot-6-schur-py"></a>

# auto_examples/data_preparation/index.html.md

<a id="sphx-glr-auto-examples-data-preparation"></a>

<a id="data-preparation-examples"></a>

<a id="data-preparation"></a>

# Data Preparation

Examples about data preparation.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial explores the difference between the general procedure using different investment horizons and the simplified procedure as explained in data preparation &lt;data_preparation&gt;.">  <div class="sphx-glr-thumbnail-title">Investment Horizon</div>
</div>
</div>

# auto_examples/data_preparation/plot_1_investment_horizon.html.md

<a id="sphx-glr-auto-examples-data-preparation-plot-1-investment-horizon-py"></a>

<a id="investment-horizon"></a>

# Investment Horizon

This tutorial explores the difference between the general
procedure using different investment horizons and the simplified procedure as explained
in [data preparation](https://skfolio.org/user_guide/data_preparation.html.md#data-preparation).

<a id="prices"></a>

## Prices

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 1990-01-02 up to 2022-12-28:

```Python
from plotly.io import show

from skfolio import PerfMeasure, Population, RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior

prices = load_sp500_dataset()
prices.head()
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Let’s plot the portfolios compositions:

```Python
population.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

We can see that the simplified procedure only start to diverge from the general one
for investment horizons longer than one year.

**Total running time of the script:** (0 minutes 1.357 seconds)

<a id="sphx-glr-download-auto-examples-data-preparation-plot-1-investment-horizon-py"></a>

# auto_examples/distributionally_robust_cvar/index.html.md

<a id="sphx-glr-auto-examples-distributionally-robust-cvar"></a>

<a id="distributionally-robust-examples"></a>

<a id="distributionally-robust-cvar"></a>

# Distributionally Robust CVaR

Examples concerning the [`DistributionallyRobustCVaR`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR) optimization.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the DistributionallyRobustCVaR model.">  <div class="sphx-glr-thumbnail-title">Distributionally Robust CVaR</div>
</div>
</div>

# auto_examples/distributionally_robust_cvar/plot_1_distributionally_robust_cvar.html.md

<a id="sphx-glr-auto-examples-distributionally-robust-cvar-plot-1-distributionally-robust-cvar-py"></a>

<a id="distributionally-robust-cvar"></a>

# Distributionally Robust CVaR

This tutorial introduces the [`DistributionallyRobustCVaR`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR)
model.

The Distributionally Robust CVaR model constructs a Wasserstein ball in the space of
multivariate and non-discrete probability distributions centered at the uniform
distribution on the training samples, and finds the allocation that minimizes the CVaR of
the worst-case distribution within this Wasserstein ball.

Mohajerin Esfahani and Kuhn (2018) proved that for piecewise linear objective functions,
which is the case of CVaR (Rockafellar and Uryasev), the distributionally robust
optimization problem over a Wasserstein ball can be reformulated as finite convex
programs.

It’s advised to use a solver that handles a high number of constraints like `Mosek`.
For accessibility, this example uses the default open source solver `CLARABEL` and to
increase convergence speed, we only use 3 years of data.

The radius of the Wasserstein ball is controlled with the `wasserstein_ball_radius`
parameter. Increasing the radius will increase the uncertainty about the
distribution, bringing the weights closer to the equal weighted portfolio.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 2020-01-02 up to 2022-12-28:

```Python
from plotly.io import show
from sklearn.model_selection import train_test_split

from skfolio import Population
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import DistributionallyRobustCVaR, EqualWeighted
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
prices = prices["2020":]

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.5, shuffle=False)
```

<a id="model"></a>

## Model

We create four distributionally robust CVaR models with different radius then fit them
on the training set:

```Python
model1 = DistributionallyRobustCVaR(
    wasserstein_ball_radius=0.1,
    portfolio_params=dict(name="Distributionally Robust CVaR - 0.1"),
)
model1.fit(X_train)

model2 = DistributionallyRobustCVaR(
    wasserstein_ball_radius=0.01,
    portfolio_params=dict(name="Distributionally Robust CVaR - 0.01"),
)
model2.fit(X_train)

model3 = DistributionallyRobustCVaR(
    wasserstein_ball_radius=0.001,
    portfolio_params=dict(name="Distributionally Robust CVaR - 0.001"),
)
model3.fit(X_train)

model4 = DistributionallyRobustCVaR(
    wasserstein_ball_radius=0.0001,
    portfolio_params=dict(name="Distributionally Robust CVaR - 0.0001"),
)
model4.fit(X_train)
model4.weights_
```

```none
array([4.84531907e-11, 1.01910610e-10, 1.81629430e-11, 7.56967308e-11,
       6.67249461e-11, 5.07087663e-10, 3.97503410e-02, 2.42882219e-09,
       3.84348572e-11, 8.53379955e-02, 5.85983398e-02, 3.38460704e-01,
       9.62545194e-11, 7.42768380e-11, 6.90123331e-10, 6.06982611e-10,
       4.16112642e-02, 1.18803064e-09, 4.36241349e-01, 1.34914228e-10])
```

To compare the models, we use an equal weighted benchmark using
the [`EqualWeighted`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted) estimator:

```Python
bench = EqualWeighted()
bench.fit(X_train)
bench.weights_
```

```none
array([0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05,
       0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05])
```

<a id="prediction"></a>

## Prediction

We predict the models and the benchmark on the test set:

```Python
ptf_model1_test = model1.predict(X_test)
ptf_model2_test = model2.predict(X_test)
ptf_model3_test = model3.predict(X_test)
ptf_model4_test = model4.predict(X_test)
ptf_bench_test = bench.predict(X_test)
```

<a id="analysis"></a>

## Analysis

We load all predicted portfolios into a [`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population) and
plot their compositions:

```Python
population = Population(
    [ptf_model1_test, ptf_model2_test, ptf_model3_test, ptf_model4_test, ptf_bench_test]
)
population.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

We can see that by increasing the radius of the Wasserstein ball, the weights get
closer to the equal weighted portfolio.

Let’s plot the portfolios cumulative returns:

```Python
fig = population.plot_cumulative_returns()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

**Total running time of the script:** (0 minutes 14.822 seconds)

<a id="sphx-glr-download-auto-examples-distributionally-robust-cvar-plot-1-distributionally-robust-cvar-py"></a>

# auto_examples/ensemble/index.html.md

<a id="sphx-glr-auto-examples-ensemble"></a>

<a id="ensemble-examples"></a>

<a id="ensemble-optimizations"></a>

# Ensemble Optimizations

Examples concerning ensemble optimizations.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the StackingOptimization.">  <div class="sphx-glr-thumbnail-title">Stacking Optimization</div>
</div>
</div>

# auto_examples/ensemble/plot_1_stacking.html.md

<a id="sphx-glr-auto-examples-ensemble-plot-1-stacking-py"></a>

<a id="stacking-optimization"></a>

# Stacking Optimization

This tutorial introduces the [`StackingOptimization`](https://skfolio.org/generated/skfolio.optimization.StackingOptimization.html.md#skfolio.optimization.StackingOptimization).

Stacking Optimization is an ensemble method that consists of stacking the output of
individual portfolio optimizations with a final portfolio optimization.

The weights are the dot-product of individual optimization weights with the final
optimization weights.

Stacking uses the strength of each individual portfolio optimization by using
their output as input of a final portfolio optimization.

To avoid data leakage, out-of-sample estimates are used to fit the outer optimization.

#### NOTE
The `estimators_` are fitted on the full `X` while `final_estimator_` is trained
using cross-validated predictions of the base estimators using `cross_val_predict`.

<a id="data"></a>

## Data

We load the FTSE 100 dataset. This dataset is composed of the daily prices of 64
assets from the FTSE 100 Index composition starting from 2000-01-04 up to 2023-05-31:

```Python
from plotly.io import show
from sklearn.model_selection import GridSearchCV, train_test_split

from skfolio import Population, RatioMeasure, RiskMeasure
from skfolio.datasets import load_ftse100_dataset
from skfolio.metrics import make_scorer
from skfolio.model_selection import (
    CombinatorialPurgedCV,
    WalkForward,
    cross_val_predict,
    optimal_folds_number,
)
from skfolio.moments import EmpiricalCovariance, LedoitWolf
from skfolio.optimization import (
    EqualWeighted,
    HierarchicalEqualRiskContribution,
    InverseVolatility,
    MaximumDiversification,
    MeanRisk,
    ObjectiveFunction,
    StackingOptimization,
)
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior

prices = load_ftse100_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.50, shuffle=False)
```

<a id="stacking-model"></a>

## Stacking Model

Our stacking model will be composed of 4 models:
: * Inverse Volatility
  * Maximum Diversification
  * Maximum Mean-Risk Utility allowing short position with L1 regularization
  * Hierarchical Equal Risk Contribution

We will stack these 4 models together using the Mean-CDaR utility maximization:

```Python
estimators = [
    ("model1", InverseVolatility()),
    ("model2", MaximumDiversification(prior_estimator=EmpiricalPrior())),
    (
        "model3",
        MeanRisk(objective_function=ObjectiveFunction.MAXIMIZE_UTILITY, min_weights=-1),
    ),
    ("model4", HierarchicalEqualRiskContribution()),
]

model_stacking = StackingOptimization(
    estimators=estimators,
    final_estimator=MeanRisk(
        objective_function=ObjectiveFunction.MAXIMIZE_UTILITY,
        risk_measure=RiskMeasure.CDAR,
    ),
)
```

<a id="benchmark"></a>

## Benchmark

To compare the staking model, we use an equal-weighted benchmark:

```Python
benchmark = EqualWeighted()
```

<a id="parameter-tuning"></a>

## Parameter Tuning

To demonstrate how parameter tuning works in a staking model, we find the model
parameters that maximizes the out-of-sample Calmar Ratio using `GridSearchCV` with
`WalkForward` cross-validation on the training set.
The `WalkForward` splits are chosen to simulate a three-month (60 business days) rolling
portfolio fitted on the previous year (252 business days):

```Python
cv = WalkForward(train_size=252, test_size=60)

grid_search = GridSearchCV(
    estimator=model_stacking,
    cv=cv,
    n_jobs=-1,
    param_grid={
        "model2__prior_estimator__covariance_estimator": [
            EmpiricalCovariance(),
            LedoitWolf(),
        ],
        "model3__l1_coef": [0.001, 0.1],
        "model4__risk_measure": [
            RiskMeasure.VARIANCE,
            RiskMeasure.GINI_MEAN_DIFFERENCE,
        ],
    },
    scoring=make_scorer(RatioMeasure.CALMAR_RATIO),
)
grid_search.fit(X_train)
model_stacking = grid_search.best_estimator_
print(model_stacking)
```

```none
StackingOptimization(estimators=[('model1', InverseVolatility()),
                                 ('model2',
                                  MaximumDiversification(prior_estimator=EmpiricalPrior(covariance_estimator=EmpiricalCovariance()))),
                                 ('model3',
                                  MeanRisk(l1_coef=0.001, min_weights=-1,
                                           objective_function=MAXIMIZE_UTILITY)),
                                 ('model4',
                                  HierarchicalEqualRiskContribution())],
                     final_estimator=MeanRisk(objective_function=MAXIMIZE_UTILITY,
                                              risk_measure=CDaR))
```

<a id="prediction"></a>

## Prediction

We evaluate the Stacking model and the Benchmark using the same `WalkForward` object
on the test set:

```Python
pred_bench = cross_val_predict(
    benchmark,
    X_test,
    cv=cv,
    portfolio_params=dict(name="Benchmark"),
)

pred_stacking = cross_val_predict(
    model_stacking,
    X_test,
    cv=cv,
    n_jobs=-1,
    portfolio_params=dict(name="Stacking"),
)
```

Each predicted object is a `MultiPeriodPortfolio`.
For improved analysis, we can add them to a `Population`:

```Python
population = Population([pred_bench, pred_stacking])
```

Let’s plot the rolling portfolios cumulative returns on the test set:

```Python
population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s plot the rolling portfolios compositions:

```Python
population.plot_composition(display_sub_ptf_name=False)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="analysis"></a>

## Analysis

The Stacking model outperforms the Benchmark on the test set for the below ratios:

```Python
for ptf in population:
    print("=" * 25)
    print(" " * 8 + ptf.name)
    print("=" * 25)
    print(f"Sharpe ratio : {ptf.annualized_sharpe_ratio:0.2f}")
    print(f"CVaR ratio : {ptf.cdar_ratio:0.5f}")
    print(f"Calmar ratio : {ptf.calmar_ratio:0.5f}")
    print("\n")
```

```none
=========================
        Benchmark
=========================
Sharpe ratio : 0.79
CVaR ratio : 0.00263
Calmar ratio : 0.00122

=========================
        Stacking
=========================
Sharpe ratio : 0.82
CVaR ratio : 0.00305
Calmar ratio : 0.00125
```

Let’s display the full summary:

```Python
population.summary()
```

[plotly figure stripped from llms output]
<br />
<br />

```Python
print(
    "Average of Sharpe Ratio :"
    f" {pred_stacking.measures_mean(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO):0.2f}"
)
print(
    "Std of Sharpe Ratio :"
    f" {pred_stacking.measures_std(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO):0.2f}"
)
```

```none
Average of Sharpe Ratio : 0.84
Std of Sharpe Ratio : 0.10
```

Now, let’s analyze how the sub-models would have performed independently and compare
their distribution with the Stacking model:

```Python
population = Population([])
for model_name, model in model_stacking.estimators:
    pred = cross_val_predict(
        model,
        X_test,
        cv=cv,
        n_jobs=-1,
        portfolio_params=dict(tag=model_name),
    )
    population.extend(pred)
population.extend(pred_stacking)

fig = population.plot_distribution(
    measure_list=[RatioMeasure.ANNUALIZED_SHARPE_RATIO],
    n_bins=40,
    tag_list=["Stacking", "model1", "model2", "model3", "model4"],
)
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<a id="conclusion"></a>

## Conclusion

The Stacking model outperforms the Benchmark on the historical test set. The
distribution analysis on the recombined (non-historical) test sets shows that the
Stacking model continues to outperform the Benchmark in average.

**Total running time of the script:** (2 minutes 48.186 seconds)

<a id="sphx-glr-download-auto-examples-ensemble-plot-1-stacking-py"></a>

# auto_examples/entropy_pooling/index.html.md

<a id="sphx-glr-auto-examples-entropy-pooling"></a>

<a id="entropy-pooling-examples"></a>

<a id="entropy-opinion-pooling"></a>

# Entropy & Opinion Pooling

Examples about [`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling) and
[`OpinionPooling`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling).

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the EntropyPooling estimator.">  <div class="sphx-glr-thumbnail-title">Entropy Pooling</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the OpinionPooling estimator.">  <div class="sphx-glr-thumbnail-title">Opinion Pooling</div>
</div>
</div>

# auto_examples/entropy_pooling/plot_1_entropy_pooling.html.md

<a id="sphx-glr-auto-examples-entropy-pooling-plot-1-entropy-pooling-py"></a>

<a id="entropy-pooling"></a>

# Entropy Pooling

This tutorial introduces the [`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling) estimator.

<a id="introduction"></a>

## Introduction

Entropy Pooling, introduced by Attilio Meucci in 2008 as a generalization of the
Black-Litterman framework, is a nonparametric method for adjusting a baseline (“prior”)
probability distribution to incorporate user-defined views by finding the posterior
distribution closest to the prior while satisfying those views.

User-defined views can be **elicited** from domain experts or **derived** from
quantitative analyses.

Grounded in information theory, it updates the distribution in the least-informative
way by minimizing the Kullback-Leibler divergence (relative entropy) under the
specified view constraints.

Mathematically, the problem is formulated as:

$$
\begin{aligned}
\min_{\mathbf{q}} \quad & \sum_{i=1}^T q_i \log\left(\frac{q_i}{p_i}\right) \\
\text{subject to} \quad & \sum_{i=1}^T q_i = 1 \quad \text{(normalization constraint)} \\
                        & \mathbb{E}_q[f_j(X)] = v_j \quad(\text{or } \le v_j, \text{ or } \ge v_j), \quad j = 1,\dots,k, \text{(view constraints)} \\
                        & q_i \ge 0, \quad i = 1, \dots, T
\end{aligned}
$$

Where:

- $T$ is the number of observations (number of scenarios).
- $p_i$ is the prior probability of scenario $x_i$.
- $q_i$ is the posterior probability of scenario $x_i$.
- $X$ is the scenario matrix of shape (n_observations, n_assets).
- $f_j$ is the j <sub>th</sub> view function.
- $v_j$ is the target value imposed by the j <sub>th</sub> view.
- $k$ is the total number of views.

The `skfolio` implementation supports the following views:
: * Equalities
  * Inequalities
  * Ranking
  * Linear combinations (e.g. relative views)
  * Views on groups of assets

On the following measures:
: * Mean
  * Variance
  * Skew
  * Kurtosis
  * Correlation
  * Value-at-Risk (VaR)
  * Conditional Value-at-Risk (CVaR)

Entropy Pooling re-weights the sample probabilities of the prior distribution and is
therefore constrained by the support (completeness) of that distribution. For example,
if the historical distribution contains no returns below -10% for a given asset, we
cannot impose a CVaR view of 15%: no matter how we adjust the sample probabilities,
such tail data do not exist.

Therefore, to impose extreme views on a sparse historical distribution, one must
generate synthetic data. In that case, the EP posterior is only as reliable as the
synthetic scenarios. It is thus essential to use a generator capable of extrapolating
tail dependencies, such as [`VineCopula`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula), to model joint
extreme events accurately.

In general, for extreme stress tests, it is recommended to use conditional sampling from
[`VineCopula`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula) (see the previous tutorial
[Vine Copula & Stress Test](https://skfolio.org/auto_examples/synthetic_data/plot_2_vine_copula.html.md#sphx-glr-auto-examples-synthetic-data-plot-2-vine-copula-py)). However, when
conditional sampling does not provide sufficient granularity, one can combine Entropy
Pooling with Vine Copula, as demonstrated at the end of this tutorial.

In this tutorial, we will:
: 1. Apply Entropy Pooling to historical return data.
  2. Construct portfolios based on the adjusted distribution.
  3. Demonstrate factor-based and synthetic-data-enhanced Entropy Pooling.
  4. Perform stress tests using Entropy Pooling.

<a id="data-loading-and-preparation"></a>

## Data Loading and Preparation

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) and select seven stocks
(for demonstration purposes). We also load the factors dataset, composed of
daily prices for five ETFs representing common factors.

```Python
import numpy as np
import pandas as pd
from plotly.io import show

from skfolio import Population, RiskMeasure
from skfolio.datasets import load_factors_dataset, load_sp500_dataset
from skfolio.distribution import VineCopula
from skfolio.measures import (
    correlation,
    cvar,
    kurtosis,
    mean,
    skew,
    standard_deviation,
    value_at_risk,
)
from skfolio.optimization import HierarchicalRiskParity, RiskBudgeting
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EntropyPooling, SyntheticData, TimeSeriesFactorModel
from skfolio.utils.figure import plot_kde_distributions

# Load stock price and factor data
prices = load_sp500_dataset()
prices = prices[["AMD", "BAC", "GE", "JNJ", "JPM", "LLY", "PG"]]
factor_prices = load_factors_dataset()

# Convert to daily returns
X, factors = prices_to_returns(prices, factor_prices)

print("Shapes:")
print(f"X: {X.shape}")
print(f"factors: {factors.shape}")

print(X.tail())
print(factors.tail())
```

```none
Shapes:
X: (2263, 7)
factors: (2263, 5)
                 AMD       BAC        GE  ...       JPM       LLY        PG
Date                                      ...
2022-12-21  0.040430  0.015223  0.033001  ...  0.011248  0.023275  0.009170
2022-12-22 -0.056442 -0.008848 -0.014582  ... -0.011355 -0.007339  0.002308
2022-12-23  0.010335  0.002443  0.000235  ...  0.004749  0.007090  0.002825
2022-12-27 -0.019374  0.001875  0.012849  ...  0.003504 -0.008208  0.008713
2022-12-28 -0.011064  0.007360 -0.010502  ...  0.005463  0.000932 -0.012926

[5 rows x 7 columns]
                MTUM      QUAL      SIZE      USMV      VLUE
Date
2022-12-21  0.014312  0.017884  0.014371  0.012005  0.013246
2022-12-22 -0.010977 -0.015411 -0.012070 -0.007315 -0.011989
2022-12-23  0.010897  0.005889  0.006287  0.005281  0.005844
2022-12-27  0.001770 -0.003138 -0.001320  0.001798 -0.000111
2022-12-28 -0.011778 -0.013325 -0.013914 -0.010489 -0.015238
```

<a id="summary-statistics"></a>

### Summary Statistics

We create a helper function to compute key return statistics, optionally weighted by
sample probabilities:

```Python
def summary(X: pd.DataFrame, sample_weight: np.ndarray | None = None) -> pd.DataFrame:
    return pd.DataFrame(
        {
            "Mean": mean(X, sample_weight=sample_weight),
            "Volatility": standard_deviation(X, sample_weight=sample_weight),
            "Skew": skew(X, sample_weight=sample_weight),
            "Kurtosis": kurtosis(X, sample_weight=sample_weight),
            "VaR at 90%": value_at_risk(X, beta=0.90, sample_weight=sample_weight),
            "CVaR at 90%": cvar(X, beta=0.90, sample_weight=sample_weight),
        }
    )

print(f"Corr(BAC, JPM): {correlation(X[['BAC', 'JPM']])[0][1]:.2%}")
summary(X)
```

```none
Corr(BAC, JPM): 90.87%
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<a id="building-a-portfolio-based-on-entropy-pooling"></a>

## Building a Portfolio based on Entropy Pooling

Now that we’ve shown how the Entropy Pooling estimator works in isolation, let’s
see how to implement a risk parity portfolio with CVaR-90% as the risk measure based
on EP:

```Python
bench = RiskBudgeting(risk_measure=RiskMeasure.CVAR, cvar_beta=0.9)
model = RiskBudgeting(
    risk_measure=RiskMeasure.CVAR, cvar_beta=0.9, prior_estimator=entropy_pooling
)

bench.fit(X)
model.fit(X)

print(bench.weights_)
print(model.weights_)
```

```none
[0.07696064 0.10665992 0.11098196 0.19797973 0.11930806 0.16615742
 0.22195227]
[0.08274106 0.08631388 0.07945519 0.18251821 0.06747005 0.2268233
 0.27467831]
```

We notice that the weight on GE is lower in the portfolio based on EP versus the
benchmark, reflecting that GE’s tail risk was the most impacted by our views.

Note that instead of [`RiskBudgeting`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting), Entropy Pooling is
also compatible with the other [portfolio optimization](https://skfolio.org/user_guide/optimization.html.md#optimization) methods
such as  [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk),
[`HierarchicalRiskParity`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity) etc.

<a id="comparing-risk-contributions"></a>

### Comparing Risk Contributions

A CVaR risk-parity portfolio assigns weights so that each asset contributes the same
amount to the portfolio’s CVaR.

Therefore, as shown in the contribution graphs below:

* The benchmark has equal CVaR contributions under the **prior** distribution
* The EP portfolio has equal CVaR contributions under the **posterior** distribution

```Python
sample_weight = model.prior_estimator_.return_distribution_.sample_weight

portfolio_bench = bench.predict(X)
portfolio_bench.name = "Benchmark (Optimized on prior)"
portfolio_ep = model.predict(X)
portfolio_ep.name = "Optimized on EP posterior"
```

<a id="backtest-using-the-prior-distribution"></a>

### Backtest using the Prior Distribution

```Python
population = Population([portfolio_bench, portfolio_ep])
population.plot_contribution(measure=RiskMeasure.CVAR)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="backtest-using-the-ep-posterior-distribution"></a>

### Backtest using the EP Posterior Distribution

```Python
population.set_portfolio_params(sample_weight=sample_weight)
population.plot_contribution(measure=RiskMeasure.CVAR)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="factor-entropy-pooling"></a>

## Factor Entropy Pooling

Instead of applying Entropy Pooling directly to asset returns, we can embed it
within a Factor Model.
This allows us to impose views on factor data such as the quality factor “QUAL”:

```Python
factor_entropy_pooling = EntropyPooling(mean_views=["QUAL == 0.0005"])

factor_model = TimeSeriesFactorModel(factor_prior_estimator=factor_entropy_pooling)

model = RiskBudgeting(risk_measure=RiskMeasure.CVAR, prior_estimator=factor_model)

model.fit(X, factors=factors)
print(model.weights_)

sample_weight = model.prior_estimator_.return_distribution_.sample_weight
summary(factors, sample_weight)
```

```none
[0.08586436 0.10101076 0.11469153 0.20548908 0.11275471 0.17552998
 0.20465958]
```

[plotly figure stripped from llms output]
<br />
<br />

<a id="conclusion"></a>

## Conclusion

In this tutorial, we demonstrated how to leverage Entropy Pooling to integrate  views
into every stage of portfolio management, from ex-ante optimization to ex-post
stress testing.

<a id="references"></a>

## References

> [1] “Fully Flexible Extreme Views”,
> : Journal of Risk, Meucci, Ardia & Keel (2011)

> [2] “Fully Flexible Views: Theory and Practice”,
> : Risk, Meucci (2013).

> [3] “Effective Number of Scenarios in Fully Flexible Probabilities”,
> : GARP Risk Professional, Meucci (2012)

> [4] “I-Divergence Geometry of Probability Distributions and Minimization
> : Problems”, The Annals of Probability, Csiszar (1975)

**Total running time of the script:** (0 minutes 13.212 seconds)

<a id="sphx-glr-download-auto-examples-entropy-pooling-plot-1-entropy-pooling-py"></a>

# auto_examples/entropy_pooling/plot_2_opinion_pooling.html.md

<a id="sphx-glr-auto-examples-entropy-pooling-plot-2-opinion-pooling-py"></a>

<a id="opinion-pooling"></a>

# Opinion Pooling

This tutorial introduces the [`OpinionPooling`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling) estimator.

<a id="introduction"></a>

## Introduction

Opinion Pooling (also called Belief Aggregation or Risk Aggregation) is a process
in which different probability distributions (opinions), produced by different
experts, are combined to yield a single probability distribution (consensus).

Expert opinions (also called individual prior distributions) can be
**elicited** from domain experts or **derived** from quantitative analyses.

The `OpinionPooling` estimator takes a list of prior estimators, each of which
produces scenario probabilities (`sample_weight`), and pools them into a single
consensus probability .

You can choose between linear (arithmetic) pooling or logarithmic (geometric)
pooling, and optionally apply robust pooling using a Kullback-Leibler divergence
penalty to down-weight experts whose views deviate strongly from the group.

<a id="linear-opinion-pooling"></a>

### Linear Opinion Pooling

* Retains all nonzero support: no “zero-forcing”
* Produces an averaging that is more evenly spread across all expert opinions.

<a id="logarithmic-opinion-pooling"></a>

### Logarithmic Opinion Pooling

* Zero-Preservation: any scenario assigned zero probability by any expert
  remains zero in the aggregate.
* Information-Theoretic Optimality: yields the distribution that minimizes the
  weighted sum of KL-divergences from each expert’s distribution.
* Robust to Extremes: down-weight extreme or contrarian views more severely.

<a id="robust-pooling-with-divergence-penalty"></a>

### Robust Pooling with Divergence Penalty

By specifying a `divergence_penalty`, you can penalize each opinion’s
divergence from the group consensus, yielding a more robust aggregate distribution.

In this tutorial, we will:
: 1. Apply Opinion Pooling to historical return data.
  2. Construct portfolios based on the adjusted distribution.
  3. Demonstrate factor-based and synthetic-data-enhanced Opinion Pooling.
  4. Perform stress tests using Opinion Pooling.

<a id="data-loading-and-preparation"></a>

## Data Loading and Preparation

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) and select seven stocks
(for demonstration purposes). We also load the factors dataset, composed of
daily prices for five ETFs representing common factors.

```Python
import numpy as np
import pandas as pd
from plotly.io import show

from skfolio import Population, RiskMeasure
from skfolio.datasets import load_factors_dataset, load_sp500_dataset
from skfolio.distribution import VineCopula
from skfolio.measures import (
    cvar,
    kurtosis,
    mean,
    skew,
    standard_deviation,
    value_at_risk,
)
from skfolio.optimization import HierarchicalRiskParity, RiskBudgeting
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import (
    EntropyPooling,
    OpinionPooling,
    SyntheticData,
    TimeSeriesFactorModel,
)
from skfolio.utils.figure import plot_kde_distributions

# Load stock price and factor data
prices = load_sp500_dataset()
prices = prices[["AMD", "BAC", "GE", "JNJ", "JPM", "LLY", "PG"]]
factor_prices = load_factors_dataset()

# Convert to daily returns
X, factors = prices_to_returns(prices, factor_prices)

print("Shapes:")
print(f"X: {X.shape}")
print(f"factors: {factors.shape}")

print(X.tail())
print(factors.tail())
```

```none
Shapes:
X: (2263, 7)
factors: (2263, 5)
                 AMD       BAC        GE  ...       JPM       LLY        PG
Date                                      ...
2022-12-21  0.040430  0.015223  0.033001  ...  0.011248  0.023275  0.009170
2022-12-22 -0.056442 -0.008848 -0.014582  ... -0.011355 -0.007339  0.002308
2022-12-23  0.010335  0.002443  0.000235  ...  0.004749  0.007090  0.002825
2022-12-27 -0.019374  0.001875  0.012849  ...  0.003504 -0.008208  0.008713
2022-12-28 -0.011064  0.007360 -0.010502  ...  0.005463  0.000932 -0.012926

[5 rows x 7 columns]
                MTUM      QUAL      SIZE      USMV      VLUE
Date
2022-12-21  0.014312  0.017884  0.014371  0.012005  0.013246
2022-12-22 -0.010977 -0.015411 -0.012070 -0.007315 -0.011989
2022-12-23  0.010897  0.005889  0.006287  0.005281  0.005844
2022-12-27  0.001770 -0.003138 -0.001320  0.001798 -0.000111
2022-12-28 -0.011778 -0.013325 -0.013914 -0.010489 -0.015238
```

<a id="summary-statistics"></a>

### Summary Statistics

We create a helper function to compute key return statistics, optionally weighted by
sample probabilities:

```Python
def summary(X: pd.DataFrame, sample_weight: np.ndarray | None = None) -> pd.DataFrame:
    return pd.DataFrame(
        {
            "Mean": mean(X, sample_weight=sample_weight),
            "Volatility": standard_deviation(X, sample_weight=sample_weight),
            "Skew": skew(X, sample_weight=sample_weight),
            "Kurtosis": kurtosis(X, sample_weight=sample_weight),
            "VaR at 95%": value_at_risk(X, beta=0.95, sample_weight=sample_weight),
            "CVaR at 95%": cvar(X, beta=0.95, sample_weight=sample_weight),
        }
    )

summary(X)
```

[plotly figure stripped from llms output]
<br />
<br />

<a id="building-a-portfolio-based-on-opinion-pooling"></a>

## Building a Portfolio based on Opinion Pooling

Now that we’ve shown how the Opinion Pooling estimator works in isolation, let’s
see how to implement a risk parity portfolio with CVaR-90% as the risk measure based
on Opinion Pooling:

```Python
model = RiskBudgeting(
    risk_measure=RiskMeasure.CVAR, cvar_beta=0.9, prior_estimator=opinion_pooling
)

model.fit(X)

print(model.weights_)
```

```none
[0.08085596 0.0978985  0.0972087  0.21843437 0.10682442 0.17225667
 0.22652138]
```

<a id="factor-opinion-pooling"></a>

## Factor Opinion Pooling

Instead of applying Opinion Pooling directly to asset returns, we can embed it
within a factor model so that expert views are expressed on the factors.

```Python
factor_opinion_1 = EntropyPooling(
    mean_views=["QUAL == -0.0005"], cvar_views=["SIZE == 0.08"]
)
factor_opinion_2 = EntropyPooling(cvar_views=["SIZE == 0.09"])

factor_opinion_pooling = OpinionPooling(
    estimators=[("opinion_1", factor_opinion_1), ("opinion_2", factor_opinion_2)],
    opinion_probabilities=[0.6, 0.4],
)

factor_model = TimeSeriesFactorModel(factor_prior_estimator=factor_opinion_pooling)

model = RiskBudgeting(risk_measure=RiskMeasure.CVAR, prior_estimator=factor_model)

model.fit(X, factors=factors)
print(model.weights_)

sample_weight = model.prior_estimator_.return_distribution_.sample_weight
summary(factors, sample_weight)
```

```none
[0.09333215 0.09726882 0.10925525 0.21357395 0.10861813 0.17645262
 0.20149908]
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<a id="conclusion"></a>

## Conclusion

In this tutorial, we demonstrated how to leverage Opinion Pooling to aggregate
multiple expert views into every stage of portfolio management, from ex-ante
optimization to ex-post stress testing.

<a id="references"></a>

## References

[1] “Probabilistic opinion pooling generalized”,
: Social Choice and Welfare, Dietrich & List (2017)

[2] “Opinion Aggregation and Individual Expertise”,
: Oxford University Press, Martini & Sprenger (2017)

[3] “Rational Decisions”,
: Journal of the Royal Statistical Society, Good  (1952)

**Total running time of the script:** (0 minutes 13.236 seconds)

<a id="sphx-glr-download-auto-examples-entropy-pooling-plot-2-opinion-pooling-py"></a>

# auto_examples/factor_models/index.html.md

<a id="sphx-glr-auto-examples-factor-models"></a>

<a id="factor-models-examples"></a>

<a id="factor-models"></a>

# Factor Models

Examples about [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel): building a
characteristics factor model from an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel),
diagnosing it, and using it for portfolio construction, attribution and alpha
integration.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to build a characteristics-based cross-sectional factor model with CharacteristicsFactorModel. The methodology is covered in the Factor Models &lt;factor_models&gt; user guide.">  <div class="sphx-glr-thumbnail-title">Characteristics Factor Model</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to build a dollar-neutral long-short portfolio with factor tilts, using the characteristics-based cross-sectional factor model CharacteristicsFactorModel and the optimizer MeanRisk. The methodology is covered in the Portfolio Construction &lt;factor_model_portfolio_construction&gt; and factor_model_attribution sections of the user guide.">  <div class="sphx-glr-thumbnail-title">Factor-Constrained Portfolio and Attribution</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to research an alpha signal that forecasts the idiosyncratic returns of the characteristics-based cross-sectional factor model CharacteristicsFactorModel, and how to trade it in a factor-neutral long-short portfolio. The methodology is covered in the Alpha Estimators &lt;factor_model_alpha&gt; and Portfolio Construction &lt;factor_model_portfolio_construction&gt; sections of the user guide.">  <div class="sphx-glr-thumbnail-title">Alpha Research and Factor-Neutral Portfolio</div>
</div>
</div>

# auto_examples/factor_models/plot_alpha_factor_neutral_portfolio.html.md

<a id="sphx-glr-auto-examples-factor-models-plot-alpha-factor-neutral-portfolio-py"></a>

<a id="alpha-research-and-factor-neutral-portfolio"></a>

# Alpha Research and Factor-Neutral Portfolio

This tutorial shows how to research an alpha signal that forecasts the
idiosyncratic returns of the characteristics-based cross-sectional factor
model [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel), and how to trade it
in a factor-neutral long-short portfolio. The methodology is covered in the
[Alpha Estimators](https://skfolio.org/user_guide/factor_models.html.md#factor-model-alpha) and [Portfolio Construction](https://skfolio.org/user_guide/factor_models.html.md#factor-model-portfolio-construction) sections of the user guide.

We will:

* define an alpha signal that forecasts the factor model’s idiosyncratic returns
* evaluate its forecast quality with IC, portfolio and factor-correlation
  diagnostics
* integrate the alpha estimator into the factor model
* optimize a factor-neutral portfolio that allocates to the orthogonal alpha
* jointly tune the optimizer, factor model and alpha estimator with online
  search
* evaluate the strategy over a walk-forward test period
* run ex-ante and ex-post attribution of exposures, risk and performance,
  verifying that the return comes from the orthogonal alpha rather than factor
  premia

<a id="data"></a>

## Data

We reuse the synthetic characteristics panel from the [first tutorial](https://skfolio.org/auto_examples/factor_models/plot_characteristics_factor_model.html.md#sphx-glr-auto-examples-factor-models-plot-characteristics-factor-model-py).
It covers 500 assets over 1,500 trading days and includes late listings,
delistings, holidays and missing characteristics:

```Python
import numpy as np
from plotly.io import show

from skfolio.datasets import make_synthetic_characteristics

panel = make_synthetic_characteristics(
    n_assets=500, n_observations=1500, random_state=0
)
```

<a id="model-definition"></a>

## Model Definition

Next, we rebuild the 24-factor model with one global market factor, 10
industry factors and 13 style factors built from 29 descriptors. See the
[first tutorial](https://skfolio.org/auto_examples/factor_models/plot_characteristics_factor_model.html.md#sphx-glr-auto-examples-factor-models-plot-characteristics-factor-model-py)
for more details:

```Python
from skfolio.descriptor import (
    AnalystDispersionToPrice,
    AssetTurnover,
    AssetsGrowthRate,
    BookLeverage,
    BookToPrice,
    CapexToAssetsChangeInIntensity,
    CashFlowToAssets,
    CashFlowToPrice,
    DebtToAssets,
    DividendToPrice,
    EWAmihudIlliquidity,
    EWMarketBeta,
    EWMomentum,
    EWResidualVolatility,
    EWShareTurnover,
    EWVolatility,
    EarningsChangeToPrice,
    EarningsToPrice,
    EbitdaToEnterpriseValue,
    ForwardEarningsToPrice,
    GrossMargin,
    GrossProfitability,
    IssuanceGrowthRate,
    LogMarketCap,
    MarketLeverage,
    ReturnOnAssets,
    ReturnOnEquity,
    SalesGrowthRate,
    SalesToPrice,
    ShareholderYield,
    ShortInterest,
)
from skfolio.factor_exposure import (
    DerivedFactor,
    FixedWeightedFactor,
    GlobalFactor,
    OneHotCategoricalFactors,
)
from skfolio.moments import EWMu, RegimeAdjustedEWCovariance
from skfolio.prior import CharacteristicsFactorModel, EmpiricalPrior

month = 21
quarter = 3 * month
half_year = 6 * month
year = 12 * month

global_factor = GlobalFactor(family="market")

industry_factors = OneHotCategoricalFactors(category="industry", family="industry")

beta_factor = FixedWeightedFactor(
    descriptors=[("market_beta", EWMarketBeta(half_life=year))],
    transform_by_group="industry",
)

momentum_factor = FixedWeightedFactor(
    descriptors=[("momentum", EWMomentum(half_life=half_year, skip=month))],
    transform_by_group="industry",
)

size_factor = FixedWeightedFactor(
    descriptors=[("log_mcap", LogMarketCap())], transform_by_group="industry"
)

non_linear_size_factor = DerivedFactor(
    source="size", func=lambda x: x**3, transform_by_group="industry"
)

value_factor = FixedWeightedFactor(
    descriptors=[
        ("book_to_price", BookToPrice()),
        ("sales_to_price", SalesToPrice()),
        ("cash_flow_to_price", CashFlowToPrice()),
    ],
    weights=[0.8, 0.1, 0.1],
    transform_by_group="industry",
)

earnings_yield_factor = FixedWeightedFactor(
    descriptors=[
        ("fwd_earnings_to_price", ForwardEarningsToPrice()),
        ("earnings_to_price", EarningsToPrice()),
        ("enterprise_multiple", EbitdaToEnterpriseValue()),
    ],
    transform_by_group="industry",
)

growth_factor = FixedWeightedFactor(
    descriptors=[
        ("earnings_change_to_price", EarningsChangeToPrice(lag=year)),
        ("sales_growth", SalesGrowthRate(lag=year)),
    ],
    transform_by_group="industry",
)

profitability_factor = FixedWeightedFactor(
    descriptors=[
        ("asset_turnover", AssetTurnover()),
        ("gross_profitability", GrossProfitability()),
        ("gross_margin", GrossMargin()),
        ("return_on_assets", ReturnOnAssets()),
        ("return_on_equity", ReturnOnEquity()),
        ("cash_flow_to_assets", CashFlowToAssets()),
    ],
    transform_by_group="industry",
)

investment_factor = FixedWeightedFactor(
    descriptors=[
        ("asset_growth", AssetsGrowthRate(lag=year)),
        ("issuance_growth", IssuanceGrowthRate(lag=year)),
        ("capex_growth", CapexToAssetsChangeInIntensity(lag=year)),
    ],
    transform_by_group="industry",
)

dividend_yield_factor = FixedWeightedFactor(
    descriptors=[
        ("dividend_to_price", DividendToPrice()),
        ("shareholder_yield", ShareholderYield()),
    ],
    weights=[0.7, 0.3],
    transform_by_group="industry",
)

leverage_factor = FixedWeightedFactor(
    descriptors=[
        ("market_leverage", MarketLeverage()),
        ("debt_to_assets", DebtToAssets()),
        ("book_leverage", BookLeverage()),
    ],
    transform_by_group="industry",
)

liquidity_factor = FixedWeightedFactor(
    descriptors=[
        ("share_turnover", EWShareTurnover(half_life=quarter)),
        ("amihud_illiquidity", EWAmihudIlliquidity()),
    ],
    transform_by_group="industry",
)

volatility_factor = FixedWeightedFactor(
    descriptors=[
        ("vol", EWVolatility(half_life=quarter)),
        (
            "residual_vol",
            EWResidualVolatility(half_life=quarter, beta_half_life=quarter),
        ),
    ],
    transform_by_group="industry",
)

model = CharacteristicsFactorModel(
    factors=[
        ("market", global_factor),
        ("industry", industry_factors),
        ("beta", beta_factor),
        ("momentum", momentum_factor),
        ("size", size_factor),
        ("non_linear_size", non_linear_size_factor),
        ("value", value_factor),
        ("earnings_yield", earnings_yield_factor),
        ("growth", growth_factor),
        ("profitability", profitability_factor),
        ("investment", investment_factor),
        ("dividend_yield", dividend_yield_factor),
        ("leverage", leverage_factor),
        ("liquidity", liquidity_factor),
        ("volatility", volatility_factor),
    ],
    neutralize_against={
        "non_linear_size": ["size"],
        "volatility": ["beta"],
    },
    constrained_families=[("industry", None)],
    exposure_lag=1,
    inv_idio_variance_weight_shrinkage=0.5,
    factor_prior_estimator=EmpiricalPrior(
        covariance_estimator=RegimeAdjustedEWCovariance(
            half_life=half_year, corr_half_life=year, regime_half_life=month
        ),
        mu_estimator=EWMu(half_life=year),
    ),
    n_jobs=-1,
)
```

<a id="alpha-research"></a>

## Alpha Research

We now build the alpha signal, a cross-sectional forecast of relative
idiosyncratic performance across assets at each date. The factor model
decomposes asset returns into systematic and idiosyncratic components <sup>[1](#id5)</sup>, and
the signal targets the idiosyncratic returns. With raw returns as target,
the cross-sectional variation would also include each asset’s factor
exposures multiplied by the factor returns, so a signal correlated with the
exposures would pick up factor premia already captured by the factor model.
Targeting idiosyncratic returns removes this component and
keeps the forecast asset-specific (see [Alpha Estimators](https://skfolio.org/user_guide/factor_models.html.md#factor-model-alpha)).

We use the first three years for factor-model estimation and alpha
development and reserve the remaining three years for walk-forward
evaluation. After fitting the factor model, we use `enrich_asset_panel` to
add idiosyncratic returns, idiosyncratic variances, regression weights and
factor exposures to the training panel. We can then iterate on the alpha
estimator without refitting the factor model:

```Python
train_size = 3 * year
panel_train = panel[:train_size]

model.fit(characteristics=panel_train)
factor_model = model.factor_model_

panel_train_enriched = factor_model.enrich_asset_panel(panel_train)
```

<a id="alpha-signal"></a>

### Alpha Signal

We build the signal from two characteristics: short interest and analyst
forecast dispersion. Empirical studies have associated high short interest
<sup>[2](#id6)</sup> and high analyst forecast dispersion <sup>[3](#id7)</sup> with lower subsequent
returns. We therefore combine the two descriptors with equal negative
weights, so assets with higher values receive lower alpha forecasts.

On real data, such a relationship would have to be discovered and tested.
Here the data is synthetic, so the relationship is built into the
generator: a persistent bearish component raises short interest and analyst
forecast dispersion and lowers future idiosyncratic returns. The
[`ShortInterest`](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#skfolio.descriptor.ShortInterest) and
[`AnalystDispersionToPrice`](https://skfolio.org/generated/skfolio.descriptor.AnalystDispersionToPrice.html.md#skfolio.descriptor.AnalystDispersionToPrice) descriptors observe
this component with noise. Because the true signal is known by
construction, we can verify at the end of the tutorial that the workflow
recovers it from the observable characteristics.

We use [`FixedWeightedAlpha`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha) because the descriptor
directions and relative weights are specified in advance, which keeps the
focus on the alpha evaluation and portfolio-construction workflow. skfolio
also provides [`EWSharpeOptimalAlpha`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha) to estimate a
linear descriptor combination from historical idiosyncratic returns and
[`PredictorAlpha`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha) to use any ML predictor for
more flexible relationships:

```Python
from skfolio.alpha import FixedWeightedAlpha, alpha_forecast_evaluation
from skfolio.preprocessing import CSGaussianRankScaler
from skfolio.utils.stats import CSWeighting

holding_period = 10

alpha_estimator = FixedWeightedAlpha(
    descriptors=[
        ("short_interest", ShortInterest()),
        ("analyst_dispersion", AnalystDispersionToPrice()),
    ],
    weights=[-1.0, -1.0],
    forecast_scale=7.5e-5,
    scoring_transformer=CSGaussianRankScaler(),
    n_jobs=-1,
)
```

[`CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler) maps each descriptor and
the final composite to cross-sectional Gaussian rank scores. This places the
two descriptors on a comparable scale and limits the influence of extreme
values. [`FixedWeightedAlpha`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha) normalizes the weights by
their absolute sum, so `[-1.0, -1.0]` assigns an effective weight of
$-0.5$ to each descriptor.

`forecast_scale` converts one composite-score unit into expected
idiosyncratic return. Here, `7.5e-5` represents 0.75 basis points of expected
daily idiosyncratic return per score unit. The alpha forecast should be expressed in
expected-return units when it is combined with expected factor returns or used
in an optimization alongside return-denominated quantities such as transaction
costs, turnover constraints or return targets.

<a id="alpha-forecast-diagnostics"></a>

### Alpha Forecast Diagnostics

[`alpha_forecast_evaluation`](https://skfolio.org/generated/skfolio.alpha.alpha_forecast_evaluation.html.md#skfolio.alpha.alpha_forecast_evaluation) fits the estimator on the
enriched training panel and compares each historical forecast with the mean
idiosyncratic return over the next ten trading days. `signal_lag=1` pairs a
forecast observed at $t$ with returns beginning at $t+1$. The
default evaluation step equals the holding period, producing non-overlapping
target windows. `n_forward_periods=4` extends the decay analysis across four
consecutive ten-day windows.

We use regression weights for the Pearson IC, calibration and linear
factor-correlation diagnostics, while the Spearman IC evaluates
cross-sectional rank ordering and does not use them:

```Python
evaluation = alpha_forecast_evaluation(
    alpha_estimator,
    panel_train_enriched,
    holding_period=holding_period,
    signal_lag=1,
    n_forward_periods=4,
    cs_weighting=CSWeighting.REGRESSION,
)

evaluation.ic_summary()
```

[plotly figure stripped from llms output]
<br />
<br />

Both curves rise steadily with no prolonged flat or negative stretch,
consistent with the high hit rates of the IC summary.

Next, we check how quickly the signal decays. `plot_ic_decay` re-evaluates
each forecast over consecutive, disjoint ten-day windows:

```Python
evaluation.plot_ic_decay()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The IC is strongest in the first window and weakens over the following ones.
The latent bearish component is highly persistent, so part of its predictive
power extends beyond the ten-day holding period.

Finally, we check whether the forecast overlaps with the risk factors.
`plot_factor_correlation` shows the contemporaneous cross-sectional
correlation between the raw alpha forecast and each factor exposure:

```Python
evaluation.plot_factor_correlation()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

All correlations are small, so the forecast is close to factor neutral.
Such small overlaps are not a concern for the portfolio below because the
factor model separates the forecast into spanned alpha and orthogonal alpha
and the optimization constraints keep the portfolio’s factor exposures near
zero. Unwanted tilts can also be removed at the alpha estimator level with
`neutralize_against`.

<a id="alpha-integration"></a>

## Alpha Integration

After defining and evaluating the signal, we attach the alpha estimator to
the factor model:

```Python
model.set_params(alpha_estimator=alpha_estimator)
```

[plotly figure stripped from llms output]
<br />
<br />

Market and industry exposures are zero, while each style exposure remains
within its $\pm 0.05$ constraint.

We then inspect forecast volatility contributions:

```Python
predicted_attrib.plot_vol_contrib(top_n=15)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The idiosyncratic component dominates the risk forecast, with only small
contributions from residual style exposures.

Next, we inspect expected return contributions:

```Python
predicted_attrib.plot_return_contrib(top_n=15)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The idiosyncratic component dominates expected return. This is consistent with
the modeled expected return coming primarily from orthogonal alpha. In the previous
tutorial, the idiosyncratic
expected-return contribution was zero because the factor model had no alpha
estimator.

The same decomposition is available as a DataFrame:

```Python
predicted_attrib.summary_df()
```

[plotly figure stripped from llms output]
<br />
<br />

Next, we check the long, short, net and gross exposures through time. Net
exposure remains zero and gross exposure stays within the 300% cap:

```Python
mpp.plot_long_short_exposure()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="ex-post-attribution"></a>

## Ex-Post Attribution

Now that we have the backtest, let’s check whether realized performance was
concentrated in idiosyncratic returns, as intended by the orthogonal alpha
forecast. `realized_attribution` decomposes the walk-forward portfolio using
realized factor returns, exposures and idiosyncratic returns. For this
descriptive ex-post analysis, we refit the factor model over the completed
sample. This fit occurs after the backtest and does not enter any portfolio
decision:

```Python
model.fit(characteristics=panel)
realized_factor_model = model.factor_model_
realized_attrib = mpp.realized_attribution(factor_model=realized_factor_model)
```

For each factor, we plot the mean realized exposure and its standard
deviation over the backtest:

```Python
realized_attrib.plot_exposure(top_n=15)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Mean realized exposures remain close to zero. Their standard deviations
summarize time variation from rebalances, changing factor exposures and
within-period weight drift.

We then inspect realized return contributions:

```Python
fig = realized_attrib.plot_return_contrib(top_n=15)
# show(fig) is only used for the documentation sticker.
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

The error bars show 95% confidence intervals on annualized mean return
contributions. The idiosyncratic return contribution is positive. Residual
factor exposures make a small aggregate contribution. The realized return decomposition is
consistent with the orthogonal alpha forecast.

The summary DataFrame adds `unattributed`, the difference between
observed portfolio returns and model-attributed returns. The portfolio
returns are net of transaction costs while the factor decomposition
explains gross returns, so the cost drag falls into this component, as
would management fees, slippage and cash:

```Python
realized_attrib.summary_df()
```

[plotly figure stripped from llms output]
<br />
<br />

The market exposure is constant (every asset has unit exposure), so its
correlation row is uninformative and displays as zero. Market neutrality is
instead guaranteed by benchmark-weighted centering: every exposure has a
zero benchmark-weighted mean, so no factor carries net market exposure.
The style-industry correlations are zero, the result of
within-industry scoring
(`transform_by_group="industry"`), and so are the volatility-beta and
non-linear size-size correlations, the result of `neutralize_against`.
Industry factors are slightly negatively correlated rather than
uncorrelated. Each asset belongs to exactly one industry, so membership in
one industry rules out membership in all others. Zero correlation would
mean industry memberships are independent. The remaining style
correlations reflect the correlated traits of the synthetic universe (e.g.
value with leverage and earnings yield), with no redundant factors,
consistent with the low mean variance inflation factors (`mean_vif`)
reported in the summary table above.

#### NOTE
For two one-hot exposures $x$ and $y$ with benchmark
weights $p_x$ and $p_y$, the product $xy$ is always
zero, so the covariance
$\mathbb{E}[xy] - \mathbb{E}[x]\mathbb{E}[y] = -p_x p_y$ is
negative, giving a correlation of
$-\sqrt{p_x p_y / ((1-p_x)(1-p_y))}$, about -0.11 for ten
industries of similar weight.

<a id="regression-diagnostics"></a>

## Regression Diagnostics

Let’s inspect the fit of the cross-sectional regressions with
`cs_regression_scores`, which reports per-observation fit statistics:

```Python
factor_model.cs_regression_scores.mean()
```

```none
r2                0.608784
adjusted_r2       0.585589
aic           -4013.061835
bic           -3920.574304
dtype: float64
```

```Python
factor_model.plot_cs_regression_scores(score="adjusted_r2", window=20)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The mean $R^2$ is around 60%, as expected for this synthetic dataset,
where factor effects are deliberately easy to identify. On real daily US
equity data, the mean $R^2$ typically falls between 25% and 40% (see
[Regression Diagnostics](https://skfolio.org/user_guide/factor_models.html.md#factor-model-regression-diagnostics) in the
user guide). The synthetic universe is intentionally smaller and cleaner than
real-world datasets.

Next, `plot_cs_regression_t_stat_exceedance_rate` shows how often each factor’s
t-statistic exceeds 2 in absolute value. A factor whose true coefficient is
zero would exceed it about 5% of the time, so rates persistently above this
reference identify factors that are repeatedly significant in the
cross-section:

```Python
factor_model.plot_cs_regression_t_stat_exceedance_rate(families=["market", "style"])
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="factor-returns"></a>

## Factor Returns

Let’s plot the estimated factor returns accumulated through time:

```Python
fig = factor_model.plot_factor_cumulative_returns(families=["market", "style"])
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

The market factor tracks the cumulative benchmark return, as expected from
the benchmark-weighted centering and the industry zero-sum constraint.
Among the style factors, momentum shows the largest cumulative return and
the highest annualized Sharpe ratio in the summary table above. The
synthetic generator assigns momentum a persistent premium, and the model
recovers it from the cross-section of returns.

<a id="idiosyncratic-risk-calibration"></a>

## Idiosyncratic Risk Calibration

Now let’s test the idiosyncratic volatility forecasts. The diagnostics use
the standardized idiosyncratic returns
$z_{it} = \epsilon_{it} / \hat\sigma_{it}$. Under correct calibration,
$z$ has cross-sectional standard deviation 1.0:

```Python
factor_model.idio_calibration_summary()
```

```none
mean_cs_std                1.001165
median_cs_std              0.998134
mean_cs_excess_kurtosis    0.352186
mean_cs_skewness           0.003433
mean_tail_rate_3sigma      0.004793
Name: idio_calibration, dtype: float64
```

```Python
factor_model.plot_idio_calibration(window=20)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The series oscillates around 1.0, so the idiosyncratic risk forecasts are
correctly scaled. The `mean_tail_rate_3sigma` of about 0.5%, above the
0.27% Gaussian reference, reflects the fat tails of the idiosyncratic
returns, a feature of real equity data reproduced by the generator through
Student-t shocks.

Let’s now separate ranking power from calibration with `plot_idio_vol_ic`,
which displays the Spearman correlation between idiosyncratic volatility
forecasts and next-period absolute idiosyncratic returns. High values mean
the model tends to forecast higher volatility for assets that subsequently
experience larger idiosyncratic moves. This tests the ordering of the
forecasts, while the calibration series above tests their scale. Together,
they show that the idiosyncratic risk forecasts are both well ordered and
well scaled:

```Python
factor_model.plot_idio_vol_ic()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="information-coefficient"></a>

## Information Coefficient

Finally, we measure the return-predictive power of the exposures with
`exposure_ic_summary`, the cross-sectional rank correlation between factor
exposures at $t$ and forward asset returns:

```Python
factor_model.exposure_ic_summary(families=["market", "style"])
```

[plotly figure stripped from llms output]
<br />
<br />

Mean ICs are small, IC IRs remain low and hit rates remain around 50% across
factors, so no factor stands out as a strong, consistent predictor of
next-period returns.

The IC quantifies return-predictive power <sup>[3](#id6)</sup>. In a risk model, factors are
designed to forecast covariance, not expected returns.
A factor can therefore be an excellent risk factor with an IC near zero, and
a low IC is not a reason to discard it. The IC is mainly useful for
evaluating alpha signals and factor premia, not for deciding whether a
factor should remain in a risk model.

<a id="covariance-forecast-evaluation"></a>

## Covariance Forecast Evaluation

We now evaluate the full covariance forecast out of sample with
[`online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation) (see
[Covariance Forecast Evaluation](https://skfolio.org/user_guide/factor_models.html.md#factor-model-covariance-forecast-evaluation)). It walks forward through
the data, compares each covariance forecast with the subsequently realized
returns and computes calibration diagnostics.

`X` are the asset returns in the standard skfolio format and
`warmup_size` reserves two years plus one month for the estimator warmups
(see [Warmup Periods](https://skfolio.org/user_guide/factor_models.html.md#factor-model-warmup)):

```Python
from skfolio.model_selection import online_covariance_forecast_evaluation

X = panel.to_dataframe(fields="returns")

evaluation = online_covariance_forecast_evaluation(
    model,
    X,
    params={"characteristics": panel},
    warmup_size=2 * year + month,
    test_size=week,
)
evaluation.summary()
```

[plotly figure stripped from llms output]
<br />
<br />

The bias statistic oscillates around its 1.0 target, and the summary table
shows the Mahalanobis and diagonal calibration ratios close to 1.0 as well,
so the risk forecasts are well calibrated across the sample.

<a id="hyperparameter-tuning"></a>

## Hyperparameter Tuning

Model parameters follow the scikit-learn naming convention. Here we jointly
tune the regression weights, factor covariance dynamics and idiosyncratic
variance dynamics.

Because these parameters are continuous, we use
[`OnlineRandomizedSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch). It evaluates each
candidate in a single walk-forward pass using `partial_fit`. The search uses
the first four years, preserving the remaining observations as an untouched
holdout.

We score the risk model directly with a portfolio-variance QLIKE loss. In
`make_scorer`, `response_method=None` indicates a non-predictor estimator and
`greater_is_better=False` a loss to minimize. The complete search is shown
without execution because fitting 100 candidates is computationally
intensive (see [Hyperparameter Tuning](https://skfolio.org/user_guide/factor_models.html.md#factor-model-hyper-parameter-tuning)):

```python
from scipy.stats import loguniform, uniform

from skfolio.metrics import make_scorer, portfolio_variance_qlike_loss
from skfolio.model_selection import OnlineRandomizedSearch

qlike_scorer = make_scorer(
    portfolio_variance_qlike_loss,
    greater_is_better=False,
    response_method=None,
)

search_size = 4 * year

search = OnlineRandomizedSearch(
    estimator=model,
    param_distributions={
        "inv_idio_variance_weight_shrinkage": uniform(0.0, 1.0),
        "factor_prior_estimator__covariance_estimator__half_life": (
            loguniform(quarter, half_year)
        ),
        "factor_prior_estimator__covariance_estimator__corr_half_life": (
            loguniform(half_year, year)
        ),
        "factor_prior_estimator__covariance_estimator__regime_half_life": (
            loguniform(week, quarter)
        ),
        "idio_variance_estimator__half_life": loguniform(
            month, half_year
        ),
        "idio_variance_estimator__regime_half_life": loguniform(
            week, quarter
        ),
    },
    n_iter=100,
    scoring=qlike_scorer,
    warmup_size=2 * year + month,
    test_size=week,
    random_state=0,
    n_jobs=-1,
)
search.fit(
    X.iloc[:search_size],
    characteristics=panel[:search_size],
)

print(search.best_params_)
print(search.best_score_)
```

`best_score_` summarizes the walk-forward validation windows within the
four-year search period. `cv_results_` contains every sampled parameter set,
score, rank and fit time. For a small set of discrete candidates,
[`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch) is also available and
evaluates every parameter combination.

<a id="conclusion"></a>

## Conclusion

We built a 24-factor characteristics factor model, verified its exposures
and regressions, evaluated its risk forecasts out of sample, showed how to
tune them and updated the model online. The fitted model is a prior estimator,
so we can pass it to any skfolio optimizer through `prior_estimator`. It
supplies expected returns, covariance, scenarios and factor exposures that
can be constrained.

The next tutorial builds a factor-constrained portfolio on top of this
model and performs factor-level risk and performance attribution.

#### SEE ALSO
The [Factor Models](https://skfolio.org/user_guide/factor_models.html.md#factor-models) user guide covers the
methodology in depth, including portfolio construction, attribution
and alpha integration with this model.

<a id="references"></a>

## References

* <a id='id4'>**[1]**</a> B. Rosenberg, “Extra-Market Components of Covariance in Security Returns”, *Journal of Financial and Quantitative Analysis*, vol. 9, no. 2, pp. 263-274 (1974). [doi:10.2307/2330104](https://doi.org/10.2307/2330104).
* <a id='id5'>**[2]**</a> G. A. Paleologo, *The Elements of Quantitative Investing*, Wiley Finance (2025).
* <a id='id6'>**[3]**</a> R. C. Grinold and R. N. Kahn, *Active Portfolio Management: A Quantitative Approach for Producing Superior Returns and Controlling Risk*, McGraw-Hill (1999).

**Total running time of the script:** (1 minutes 11.975 seconds)

<a id="sphx-glr-download-auto-examples-factor-models-plot-characteristics-factor-model-py"></a>

# auto_examples/factor_models/plot_factor_constrained_portfolio.html.md

<a id="sphx-glr-auto-examples-factor-models-plot-factor-constrained-portfolio-py"></a>

<a id="factor-constrained-portfolio-and-attribution"></a>

# Factor-Constrained Portfolio and Attribution

This tutorial shows how to build a dollar-neutral long-short portfolio with
factor tilts, using the characteristics-based cross-sectional factor model
[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel) and the optimizer
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk).
The methodology is covered in the [Portfolio Construction](https://skfolio.org/user_guide/factor_models.html.md#factor-model-portfolio-construction) and [Attribution](https://skfolio.org/user_guide/factor_models.html.md#factor-model-attribution) sections of the user guide.

We will:

* optimize a portfolio with explicit factor exposure constraints
* jointly tune the optimizer and factor model with online search
* backtest it with monthly walk-forward rebalancing
* perform ex-ante and ex-post attribution of exposures, risk and performance

<a id="data"></a>

## Data

We reuse the synthetic characteristics panel from the [previous tutorial](https://skfolio.org/auto_examples/factor_models/plot_characteristics_factor_model.html.md#sphx-glr-auto-examples-factor-models-plot-characteristics-factor-model-py).
It covers 500 assets over 1,500 trading days and includes late listings,
delistings, holidays and missing characteristics:

```Python
import numpy as np
from plotly.io import show

from skfolio.datasets import make_synthetic_characteristics

panel = make_synthetic_characteristics(
    n_assets=500, n_observations=1500, random_state=0
)
```

<a id="model-definition"></a>

## Model Definition

Next, we rebuild the 24-factor model with one global market factor, 10
industry factors and 13 style factors built from 29 descriptors. See the
[previous tutorial](https://skfolio.org/auto_examples/factor_models/plot_characteristics_factor_model.html.md#sphx-glr-auto-examples-factor-models-plot-characteristics-factor-model-py)
for more details:

```Python
from skfolio.descriptor import (
    AssetTurnover,
    AssetsGrowthRate,
    BookLeverage,
    BookToPrice,
    CapexToAssetsChangeInIntensity,
    CashFlowToAssets,
    CashFlowToPrice,
    DebtToAssets,
    DividendToPrice,
    EWAmihudIlliquidity,
    EWMarketBeta,
    EWMomentum,
    EWResidualVolatility,
    EWShareTurnover,
    EWVolatility,
    EarningsChangeToPrice,
    EarningsToPrice,
    EbitdaToEnterpriseValue,
    ForwardEarningsToPrice,
    GrossMargin,
    GrossProfitability,
    IssuanceGrowthRate,
    LogMarketCap,
    MarketLeverage,
    ReturnOnAssets,
    ReturnOnEquity,
    SalesGrowthRate,
    SalesToPrice,
    ShareholderYield,
)
from skfolio.factor_exposure import (
    DerivedFactor,
    FixedWeightedFactor,
    GlobalFactor,
    OneHotCategoricalFactors,
)
from skfolio.moments import EWMu, RegimeAdjustedEWCovariance
from skfolio.prior import CharacteristicsFactorModel, EmpiricalPrior

month = 21
quarter = 3 * month
half_year = 6 * month
year = 12 * month

global_factor = GlobalFactor(family="market")

industry_factors = OneHotCategoricalFactors(category="industry", family="industry")

beta_factor = FixedWeightedFactor(
    descriptors=[("market_beta", EWMarketBeta(half_life=year))],
    transform_by_group="industry",
)

momentum_factor = FixedWeightedFactor(
    descriptors=[("momentum", EWMomentum(half_life=half_year, skip=month))],
    transform_by_group="industry",
)

size_factor = FixedWeightedFactor(
    descriptors=[("log_mcap", LogMarketCap())], transform_by_group="industry"
)

non_linear_size_factor = DerivedFactor(
    source="size", func=lambda x: x**3, transform_by_group="industry"
)

value_factor = FixedWeightedFactor(
    descriptors=[
        ("book_to_price", BookToPrice()),
        ("sales_to_price", SalesToPrice()),
        ("cash_flow_to_price", CashFlowToPrice()),
    ],
    weights=[0.8, 0.1, 0.1],
    transform_by_group="industry",
)

earnings_yield_factor = FixedWeightedFactor(
    descriptors=[
        ("fwd_earnings_to_price", ForwardEarningsToPrice()),
        ("earnings_to_price", EarningsToPrice()),
        ("enterprise_multiple", EbitdaToEnterpriseValue()),
    ],
    transform_by_group="industry",
)

growth_factor = FixedWeightedFactor(
    descriptors=[
        ("earnings_change_to_price", EarningsChangeToPrice(lag=year)),
        ("sales_growth", SalesGrowthRate(lag=year)),
    ],
    transform_by_group="industry",
)

profitability_factor = FixedWeightedFactor(
    descriptors=[
        ("asset_turnover", AssetTurnover()),
        ("gross_profitability", GrossProfitability()),
        ("gross_margin", GrossMargin()),
        ("return_on_assets", ReturnOnAssets()),
        ("return_on_equity", ReturnOnEquity()),
        ("cash_flow_to_assets", CashFlowToAssets()),
    ],
    transform_by_group="industry",
)

investment_factor = FixedWeightedFactor(
    descriptors=[
        ("asset_growth", AssetsGrowthRate(lag=year)),
        ("issuance_growth", IssuanceGrowthRate(lag=year)),
        ("capex_growth", CapexToAssetsChangeInIntensity(lag=year)),
    ],
    transform_by_group="industry",
)

dividend_yield_factor = FixedWeightedFactor(
    descriptors=[
        ("dividend_to_price", DividendToPrice()),
        ("shareholder_yield", ShareholderYield()),
    ],
    weights=[0.7, 0.3],
    transform_by_group="industry",
)

leverage_factor = FixedWeightedFactor(
    descriptors=[
        ("market_leverage", MarketLeverage()),
        ("debt_to_assets", DebtToAssets()),
        ("book_leverage", BookLeverage()),
    ],
    transform_by_group="industry",
)

liquidity_factor = FixedWeightedFactor(
    descriptors=[
        ("share_turnover", EWShareTurnover(half_life=quarter)),
        ("amihud_illiquidity", EWAmihudIlliquidity()),
    ],
    transform_by_group="industry",
)

volatility_factor = FixedWeightedFactor(
    descriptors=[
        ("vol", EWVolatility(half_life=quarter)),
        (
            "residual_vol",
            EWResidualVolatility(half_life=quarter, beta_half_life=quarter),
        ),
    ],
    transform_by_group="industry",
)

model = CharacteristicsFactorModel(
    factors=[
        ("market", global_factor),
        ("industry", industry_factors),
        ("beta", beta_factor),
        ("momentum", momentum_factor),
        ("size", size_factor),
        ("non_linear_size", non_linear_size_factor),
        ("value", value_factor),
        ("earnings_yield", earnings_yield_factor),
        ("growth", growth_factor),
        ("profitability", profitability_factor),
        ("investment", investment_factor),
        ("dividend_yield", dividend_yield_factor),
        ("leverage", leverage_factor),
        ("liquidity", liquidity_factor),
        ("volatility", volatility_factor),
    ],
    neutralize_against={
        "non_linear_size": ["size"],
        "volatility": ["beta"],
    },
    constrained_families=[("industry", None)],
    exposure_lag=1,
    inv_idio_variance_weight_shrinkage=0.5,
    factor_prior_estimator=EmpiricalPrior(
        covariance_estimator=RegimeAdjustedEWCovariance(
            half_life=half_year, corr_half_life=year, regime_half_life=month
        ),
        mu_estimator=EWMu(half_life=year),
    ),
    n_jobs=-1,
)
```

<a id="factor-constrained-optimization"></a>

## Factor-Constrained Optimization

The factor model is a prior estimator, so we can pass it to any skfolio
optimizer through `prior_estimator`. The optimizer fits it internally and
consumes its expected returns, covariance and scenarios, while scikit-learn
metadata routing forwards the `characteristics` panel to the prior.

Let’s define the portfolio. We maximize the Sharpe ratio under explicit
factor exposure constraints <sup>[1](#id5)</sup>. The synthetic generator gives momentum and
dividend yield positive premia and investment a weak premium, so we
target:

* long momentum, with exposure at least 1.0,
* long dividend yield, set exactly to 1.5,
* short investment, set exactly to -1.0.

We also set beta, size, volatility and every industry exposure to exactly
zero, and bound each remaining style within $\pm 0.05$:

```Python
from sklearn import set_config

from skfolio import RiskMeasure
from skfolio.optimization import MeanRisk, ObjectiveFunction

set_config(enable_metadata_routing=True)

X = panel.to_dataframe(fields="returns")
industry_names = panel.fields["industry"].levels

bounded_styles = [
    "non_linear_size",
    "value",
    "earnings_yield",
    "growth",
    "profitability",
    "leverage",
    "liquidity",
]

mvo = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    risk_measure=RiskMeasure.VARIANCE,
    prior_estimator=model,
    max_weights=0.05,  # limit individual positions to 5%
    min_weights=-0.05,  # allow short positions and limit to -5%
    budget=0.0,  # dollar neutral
    max_long=1.0,  # cap long exposure at 100%
    linear_constraints=[
        # Style exposures
        "momentum >= 1.0",
        "dividend_yield == 1.5",
        "investment == -1.0",
        # Styles set to zero
        "beta == 0",
        "size == 0",
        "volatility == 0",
        # Remaining styles within +/- 0.05
        *[f"{name} <= 0.05" for name in bounded_styles],
        *[f"{name} >= -0.05" for name in bounded_styles],
        # Industries set to zero
        *[f"{name} == 0" for name in industry_names],
    ],
)

mvo.fit(X, characteristics=panel)

print(f"Long positions: {(mvo.weights_ > 1e-8).sum()}")
print(f"Short positions: {(mvo.weights_ < -1e-8).sum()}")
print(f"Gross exposure: {np.abs(mvo.weights_).sum():.2f}")
```

```none
Long positions: 178
Short positions: 180
Gross exposure: 2.00
```

`budget=0.0` makes the portfolio dollar neutral and `max_long=1.0` caps the
long exposure at 100%. Dollar neutrality implies an equally sized short
exposure, so the gross exposure can reach 200%. Individual positions are
limited to $\pm 5\%$. We will add transaction costs and a fallback in
the walk-forward backtest below, where each rebalancing starts from the
previous allocation.

In `linear_constraints`, an expression on a factor name (e.g.
`"momentum >= 1.0"`) applies to the portfolio exposure to that factor.
Industry neutrality needs one constraint per industry factor. A single
`"industry == 0"` on the family name would only force industry exposures to
offset each other. For the market factor, `budget=0.0` is equivalent to a
`"market == 0"` constraint on the global factor exposure, so the explicit
constraint is unnecessary.

The factor model fitted inside the optimizer is available through
`prior_estimator_`. We keep a reference to it for attribution below:

```Python
factor_model = mvo.prior_estimator_.factor_model_
```

<a id="ex-ante-attribution"></a>

## Ex-Ante Attribution

Ex-ante attribution reports the portfolio’s factor exposures and decomposes
its forecast risk and expected return into systematic and idiosyncratic
contributions <sup>[2](#id6)</sup>. We obtain it from the predicted portfolio with
`predicted_attribution`:

```Python
portfolio = mvo.predict(X)
predicted_attrib = portfolio.predicted_attribution(factor_model=factor_model)
# Equivalent lower-level call on the factor model:
# factor_model.predicted_attribution(weights=mvo.weights_)
```

First, we verify that the optimizer delivered the targeted exposures:

```Python
predicted_attrib.plot_exposure(top_n=15)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The dividend-yield factor sits at its 1.5 target and the investment factor
at its -1.0 target. Momentum is bounded below by its 1.0 floor and can
exceed it when the Sharpe-maximizing objective concentrates in the factor
with the strongest forecast premium. The market, industry and neutralized
style exposures are zero, and the remaining styles stay within their
$\pm 0.05$ bands.

Next, we look at where the predicted risk comes from:

```Python
predicted_attrib.plot_vol_contrib(top_n=15)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Each factor’s volatility contribution is given by the product of its
exposure, standalone volatility and correlation with the portfolio
(the exposure-volatility-correlation decomposition). The idiosyncratic
contribution comes from the part of the allocation that moves into
orthogonal directions once market and industry exposures are forced to
zero.

Let’s do the same for the expected return:

```Python
predicted_attrib.plot_return_contrib(top_n=15)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The targeted factors drive the expected return. The idiosyncratic
contribution is exactly zero because no alpha estimator is attached, so
the model forecasts no return in the orthogonal space.

We can also plot each factor’s expected return contribution against its
volatility contribution:

```Python
predicted_attrib.plot_return_vs_vol_contrib(top_n=15)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The targeted factors drive both dimensions, while the idiosyncratic
component lies on the zero-return axis, carrying risk without forecast
reward.

The same information is also available as DataFrames. Let’s start with the
summary: it reports volatility and return contributions for the systematic,
idiosyncratic and total components:

```Python
predicted_attrib.summary_df()
```

[plotly figure stripped from llms output]
<br />
<br />

Next, we check the long, short, net and gross exposures through time. Net
exposure remains zero and gross exposure stays within the 200% cap:

```Python
mpp.plot_long_short_exposure()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="ex-post-attribution"></a>

## Ex-Post Attribution

Now that we have the backtest, let’s find out which factors drove the
realized performance. `realized_attribution` decomposes the walk-forward
portfolio, whose weights vary through time, using the realized factor
returns, exposures and idiosyncratic returns. It also reports standard
errors that separate genuine contributions from estimation noise:

```Python
realized_attrib = mpp.realized_attribution(factor_model=factor_model)
```

As in the ex-ante section, we start with the exposures. For each factor we
plot the mean exposure over the backtest and its standard deviation through
time:

```Python
realized_attrib.plot_exposure(top_n=15)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Dividend yield remains close to its 1.5 target, while investment stays
negative but averages less short than its -1.0 rebalancing target as
realized exposures drift between monthly rebalances. Momentum averages well
above its 1.0 floor and has the widest variation.

Next, we look at where the realized risk came from:

```Python
realized_attrib.plot_vol_contrib(top_n=15)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Realized volatility is split between intended factor tilts and orthogonal
risk. Idiosyncratic risk is the largest single contribution, while dividend
yield and momentum are the largest systematic contributors.

Next, we decompose realized return into factor and idiosyncratic contributions:

```Python
fig = realized_attrib.plot_return_contrib(top_n=15)
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

The error bars show 95% confidence intervals on annualized mean return
contributions. Momentum and dividend yield are the main positive factor
contributors. Because no alpha estimator is attached, any realized
idiosyncratic contribution is uncompensated risk.

Finally, we plot each factor’s realized return contribution against its
volatility contribution. Marker sizes are proportional to the absolute
portfolio exposure, and the idiosyncratic component displays as a
fixed-size diamond:

```Python
realized_attrib.plot_return_vs_vol_contrib(top_n=15)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The same results are available as DataFrames. Compared with the ex-ante
summary, the realized breakdown adds `unattributed`, the difference between
observed portfolio returns and model-attributed returns. The portfolio
returns are net of transaction costs while the factor decomposition
explains gross returns, so the cost drag falls into this component, as
would management fees, slippage and cash:

```Python
realized_attrib.summary_df()
```

[plotly figure stripped from llms output]
<br />
<br />

Dividend yield stays close to 1.5 throughout the backtest. Momentum varies
more because 1.0 is a minimum exposure rather than an exact target, allowing
the optimizer to increase it when this improves the forecast Sharpe ratio.
Investment remains negative, while the other exposures stay close to zero.
The shaded areas show one standard deviation of exposure within each rolling
window.

<a id="conclusion"></a>

## Conclusion

We optimized a dollar-neutral portfolio with explicit factor tilts,
verified the targeted exposures ex ante, backtested it with
monthly walk-forward rebalancing and attributed the realized risk and
performance to the factors ex post.

The next tutorial attaches an alpha estimator to the factor model and
builds a factor-neutral portfolio whose return comes from the orthogonal
alpha component.

#### SEE ALSO
The [Portfolio Construction](https://skfolio.org/user_guide/factor_models.html.md#factor-model-portfolio-construction) and [Attribution](https://skfolio.org/user_guide/factor_models.html.md#factor-model-attribution) sections of the [Factor Models](https://skfolio.org/user_guide/factor_models.html.md#factor-models) user guide cover the methodology in depth.

<a id="references"></a>

## References

* <a id='id5'>**[1]**</a> R. C. Grinold and R. N. Kahn, *Active Portfolio Management: A Quantitative Approach for Producing Superior Returns and Controlling Risk*, McGraw-Hill (1999).
* <a id='id6'>**[2]**</a> G. A. Paleologo, *The Elements of Quantitative Investing*, Wiley Finance (2025).
* <a id='id7'>**[3]**</a> D. P. Palomar, *Portfolio Optimization: Theory and Application*, Chapters 3 and 14, Cambridge University Press (2025). [doi:10.1017/9781009428095](https://doi.org/10.1017/9781009428095).
* <a id='id8'>**[4]**</a> D. Goldfarb and G. Iyengar, “Robust Portfolio Selection Problems”, *Mathematics of Operations Research*, vol. 28, no. 1, pp. 1-38 (2003). [doi:10.1287/moor.28.1.1.14260](https://doi.org/10.1287/moor.28.1.1.14260).

**Total running time of the script:** (0 minutes 37.659 seconds)

<a id="sphx-glr-download-auto-examples-factor-models-plot-factor-constrained-portfolio-py"></a>

# auto_examples/index.html.md

<a id="general-examples"></a>

<a id="examples"></a>

# Examples

We recommend starting with [Maximum Sharpe Ratio](https://skfolio.org/auto_examples/mean_risk/plot_1_maximum_sharpe_ratio.html.md#sphx-glr-auto-examples-mean-risk-plot-1-maximum-sharpe-ratio-py)
or [Minimum CVaR](https://skfolio.org/auto_examples/mean_risk/plot_2_minimum_CVaR.html.md#sphx-glr-auto-examples-mean-risk-plot-2-minimum-cvar-py) before moving to more advanced examples.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">

</div>

<a id="mean-risk"></a>

## Mean-Risk

Examples using the [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial uses the MeanRisk optimization to find the maximum Sharpe Ratio portfolio.">  <div class="sphx-glr-thumbnail-title">Maximum Sharpe Ratio</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial uses the MeanRisk optimization to find the minimum CVaR (Conditional Value at Risk) portfolio.">  <div class="sphx-glr-thumbnail-title">Minimum CVaR</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial uses the MeanRisk optimization to find an ensemble of portfolios belonging to the Mean-Variance efficient frontier (Pareto front).">  <div class="sphx-glr-thumbnail-title">Efficient Frontier</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial uses the MeanRisk optimization to find an ensemble of portfolios belonging to the Mean-Variance-CDaR efficient frontier.">  <div class="sphx-glr-thumbnail-title">Mean-Variance-CDaR Surface</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to incorporate weight constraints into the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">Weight Constraints</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to incorporate transaction costs (TC) into the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">Transaction Costs</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to incorporate management fees (MF) into the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">Management Fees</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to incorporate regularization into the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">L1 and L2 Regularization</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to incorporate expected returns uncertainty sets into the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">Uncertainty Set</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to incorporate a tracking error constraint into the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">Tracking Error</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to use the EmpiricalPrior estimator in the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">Empirical Prior</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to use the BlackLitterman estimator in the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">Black & Litterman</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="skfolio supports time-series factor models through TimeSeriesFactorModel and characteristics-based cross-sectional factor models through CharacteristicsFactorModel.">  <div class="sphx-glr-thumbnail-title">Time-Series Factor Model</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to use the TimeSeriesFactorModel estimator coupled with the BlackLitterman estimator in the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">Black & Litterman Factor Model</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to use cardinality constraints with the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">Cardinality Constraints</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to use threshold constraints with the MeanRisk optimization.">  <div class="sphx-glr-thumbnail-title">Threshold Constraints</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the optimization parameters fallback and raise_on_failure.">  <div class="sphx-glr-thumbnail-title">Failure and Fallbacks</div>
</div>
</div>

<a id="factor-models"></a>

## Factor Models

Examples about [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel): building a
characteristics factor model from an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel),
diagnosing it, and using it for portfolio construction, attribution and alpha
integration.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to build a characteristics-based cross-sectional factor model with CharacteristicsFactorModel. The methodology is covered in the Factor Models &lt;factor_models&gt; user guide.">  <div class="sphx-glr-thumbnail-title">Characteristics Factor Model</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to build a dollar-neutral long-short portfolio with factor tilts, using the characteristics-based cross-sectional factor model CharacteristicsFactorModel and the optimizer MeanRisk. The methodology is covered in the Portfolio Construction &lt;factor_model_portfolio_construction&gt; and factor_model_attribution sections of the user guide.">  <div class="sphx-glr-thumbnail-title">Factor-Constrained Portfolio and Attribution</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to research an alpha signal that forecasts the idiosyncratic returns of the characteristics-based cross-sectional factor model CharacteristicsFactorModel, and how to trade it in a factor-neutral long-short portfolio. The methodology is covered in the Alpha Estimators &lt;factor_model_alpha&gt; and Portfolio Construction &lt;factor_model_portfolio_construction&gt; sections of the user guide.">  <div class="sphx-glr-thumbnail-title">Alpha Research and Factor-Neutral Portfolio</div>
</div>
</div>

<a id="risk-budgeting"></a>

## Risk Budgeting

Examples concerning the [`RiskBudgeting`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting) optimization.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial uses the RiskBudgeting optimization to find the risk parity portfolio with variance as the risk measure.">  <div class="sphx-glr-thumbnail-title">Risk Parity - Variance</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial uses the RiskBudgeting optimization to build a risk budgeting portfolio by specifying a risk budget on each asset with CVaR as the risk measure.">  <div class="sphx-glr-thumbnail-title">Risk Budgeting - CVaR</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to incorporate covariance shrinkage in the RiskBudgeting optimization.">  <div class="sphx-glr-thumbnail-title">Risk Parity - Covariance shrinkage</div>
</div>
</div>

<a id="synthetic-data-stress-test"></a>

## Synthetic Data & Stress Test

Examples about [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData) and
[`VineCopula`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula).

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces Bivariate Copulas estimators that are the building blocks of VineCopula.">  <div class="sphx-glr-thumbnail-title">Bivariate Copulas</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial presents the VineCopula estimator. An introduction to Bivariate Copulas can be found in this previous tutorial &lt;sphx_glr_auto_examples_synthetic_data_plot_1_bivariate_copulas.py&gt;.">  <div class="sphx-glr-thumbnail-title">Vine Copula & Stress Test</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to bridge scenario generation, factor models and portfolio optimization.">  <div class="sphx-glr-thumbnail-title">Minimize CVaR on Stressed Factors</div>
</div>
</div>

<a id="entropy-opinion-pooling"></a>

## Entropy & Opinion Pooling

Examples about [`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling) and
[`OpinionPooling`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling).

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the EntropyPooling estimator.">  <div class="sphx-glr-thumbnail-title">Entropy Pooling</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the OpinionPooling estimator.">  <div class="sphx-glr-thumbnail-title">Opinion Pooling</div>
</div>
</div>

<a id="hierarchical-clustering-and-nco"></a>

## Hierarchical Clustering and NCO

Examples concerning hierarchical clustering based optimizations.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the HierarchicalRiskParity optimization.">  <div class="sphx-glr-thumbnail-title">Hierarchical Risk Parity - CVaR</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the HierarchicalEqualRiskContribution optimization.">  <div class="sphx-glr-thumbnail-title">Hierarchical Equal Risk Contribution - CDaR</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="In this tutorial, we will compare the HierarchicalRiskParity (HRP) optimization with the HierarchicalEqualRiskContribution (HERC) optimization.">  <div class="sphx-glr-thumbnail-title">HRP vs HERC</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the NestedClustersOptimization optimization.">  <div class="sphx-glr-thumbnail-title">Nested Clusters Optimization</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="The previous tutorial introduced the NestedClustersOptimization.">  <div class="sphx-glr-thumbnail-title">NCO - Combinatorial Purged CV</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the SchurComplementary allocation.">  <div class="sphx-glr-thumbnail-title">Schur Complementary Allocation</div>
</div>
</div>

<a id="maximum-diversification"></a>

## Maximum Diversification

Examples concerning the [`MaximumDiversification`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification) optimization.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial uses the MaximumDiversification optimization to find the portfolio that maximizes the diversification ratio, which is the ratio of the weighted volatilities over the total volatility.">  <div class="sphx-glr-thumbnail-title">Maximum Diversification</div>
</div>
</div>

<a id="distributionally-robust-cvar"></a>

## Distributionally Robust CVaR

Examples concerning the [`DistributionallyRobustCVaR`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR) optimization.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the DistributionallyRobustCVaR model.">  <div class="sphx-glr-thumbnail-title">Distributionally Robust CVaR</div>
</div>
</div>

<a id="ensemble-optimizations"></a>

## Ensemble Optimizations

Examples concerning ensemble optimizations.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the StackingOptimization.">  <div class="sphx-glr-thumbnail-title">Stacking Optimization</div>
</div>
</div>

<a id="model-selection"></a>

## Model Selection

Model selection is an integral part of portfolio construction and therefore appears in
most examples.

Tutorials using [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward):
: * [Custom Pre-selection Using Volumes](https://skfolio.org/auto_examples/pre_selection/plot_3_custom_pre_selection_volumes.html.md#sphx-glr-auto-examples-pre-selection-plot-3-custom-pre-selection-volumes-py)
  * [HRP vs HERC](https://skfolio.org/auto_examples/clustering/plot_3_hrp_vs_herc.html.md#sphx-glr-auto-examples-clustering-plot-3-hrp-vs-herc-py)
  * [L1 and L2 Regularization](https://skfolio.org/auto_examples/mean_risk/plot_8_regularization.html.md#sphx-glr-auto-examples-mean-risk-plot-8-regularization-py)
  * [NCO - Combinatorial Purged CV](https://skfolio.org/auto_examples/clustering/plot_5_nco_grid_search.html.md#sphx-glr-auto-examples-clustering-plot-5-nco-grid-search-py)
  * [Stacking Optimization](https://skfolio.org/auto_examples/ensemble/plot_1_stacking.html.md#sphx-glr-auto-examples-ensemble-plot-1-stacking-py)

Tutorials using [`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV):
: * [Drop Highly Correlated Assets](https://skfolio.org/auto_examples/pre_selection/plot_1_drop_correlated.html.md#sphx-glr-auto-examples-pre-selection-plot-1-drop-correlated-py)
  * [HRP vs HERC](https://skfolio.org/auto_examples/clustering/plot_3_hrp_vs_herc.html.md#sphx-glr-auto-examples-clustering-plot-3-hrp-vs-herc-py)
  * [NCO - Combinatorial Purged CV](https://skfolio.org/auto_examples/clustering/plot_5_nco_grid_search.html.md#sphx-glr-auto-examples-clustering-plot-5-nco-grid-search-py)

Below are dedicated Model Selection tutorials.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces MultipleRandomizedCV, which is based on the &quot;Multiple Randomized Backtests&quot; methodology of Palomar in [1]_. This cross-validation strategy performs a resampling-based evaluation by repeatedly sampling distinct asset subsets (without replacement) and contiguous time windows, then applying an inner walk-forward split to each subsample, capturing both temporal and cross-sectional variability in performance.">  <div class="sphx-glr-thumbnail-title">Multiple Randomized Cross-Validation</div>
</div>
</div>

<a id="online-learning"></a>

## Online Learning

Examples demonstrating online covariance evaluation, online hyperparameter
tuning, and online evaluation of portfolio optimization with incremental
estimators.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to evaluate online covariance estimators with online_covariance_forecast_evaluation.">  <div class="sphx-glr-thumbnail-title">Online Covariance Forecast Evaluation</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to tune covariance estimator hyperparameters in an online setting using OnlineGridSearch and OnlineRandomizedSearch.">  <div class="sphx-glr-thumbnail-title">Online Covariance Hyperparameter Tuning</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to tune a MeanRisk estimator with online search and evaluate it out-of-sample with an online walk-forward procedure.">  <div class="sphx-glr-thumbnail-title">Online Evaluation of Portfolio Optimization</div>
</div>
</div>

<a id="pre-selection"></a>

## Pre-selection

Examples of using [pre-selection transformers](https://skfolio.org/user_guide/pre_selection.html.md#pre-selection) with `Pipelines`.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the  pre-selection transformers &lt;pre_selection&gt; DropCorrelated to remove highly correlated assets before the optimization.">  <div class="sphx-glr-thumbnail-title">Drop Highly Correlated Assets</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the pre-selection transformers &lt;pre_selection&gt; SelectKExtremes to select the k best or the k worst assets according to a given measure before the optimization.">  <div class="sphx-glr-thumbnail-title">Select Best Performers</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial demonstrates how to implement a custom pre-selection transformer &lt;pre_selection&gt; with metadata_routing, integrate it into a Pipeline, and run walk-forward cross-validation.">  <div class="sphx-glr-thumbnail-title">Custom Pre-selection Using Volumes</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="When working with large datasets over long timeframes, we commonly encounter:">  <div class="sphx-glr-thumbnail-title">Handling Incomplete Datasets: Inception, Expiry, and Default</div>
</div>
</div>

<a id="metadata-routing"></a>

## Metadata Routing

Examples about metadata routing.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to use metadata routing &lt;metadata_routing&gt;.">  <div class="sphx-glr-thumbnail-title">Using Implied Volatility with Metadata Routing</div>
</div>
</div>

<a id="data-preparation"></a>

## Data Preparation

Examples about data preparation.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial explores the difference between the general procedure using different investment horizons and the simplified procedure as explained in data preparation &lt;data_preparation&gt;.">  <div class="sphx-glr-thumbnail-title">Investment Horizon</div>
</div>
</div>

# auto_examples/maximum_diversification/index.html.md

<a id="sphx-glr-auto-examples-maximum-diversification"></a>

<a id="maximum-diversification-examples"></a>

<a id="maximum-diversification"></a>

# Maximum Diversification

Examples concerning the [`MaximumDiversification`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification) optimization.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial uses the MaximumDiversification optimization to find the portfolio that maximizes the diversification ratio, which is the ratio of the weighted volatilities over the total volatility.">  <div class="sphx-glr-thumbnail-title">Maximum Diversification</div>
</div>
</div>

# auto_examples/maximum_diversification/plot_1_maximum_diversification.html.md

<a id="sphx-glr-auto-examples-maximum-diversification-plot-1-maximum-diversification-py"></a>

<a id="maximum-diversification"></a>

# Maximum Diversification

This tutorial uses the [`MaximumDiversification`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification)
optimization to find the portfolio that maximizes the diversification ratio, which is
the ratio of the weighted volatilities over the total volatility.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 1990-01-02 up to 2022-12-28:

```Python
from plotly.io import show
from sklearn.model_selection import train_test_split

from skfolio import Population
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import EqualWeighted, MaximumDiversification
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)

X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="model"></a>

## Model

We create the maximum diversification model and then fit it on the training set:

```Python
model = MaximumDiversification()
model.fit(X_train)
model.weights_
```

```none
array([8.33459971e-02, 6.74138299e-02, 2.93952123e-02, 8.57558650e-02,
       4.12145074e-02, 8.80360023e-09, 1.53457231e-08, 4.41151909e-02,
       1.70046770e-08, 5.11503226e-02, 6.82590399e-02, 3.02728712e-02,
       3.79430055e-03, 9.95058777e-02, 1.48755617e-02, 1.10849163e-01,
       1.08087391e-01, 9.45176307e-02, 6.51331697e-02, 2.31402810e-03])
```

To compare this model, we use an equal weighted benchmark using
the [`EqualWeighted`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted) estimator:

```Python
bench = EqualWeighted()
bench.fit(X_train)
bench.weights_
```

```none
array([0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05,
       0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05, 0.05])
```

<a id="diversification-analysis"></a>

## Diversification Analysis

Let’s analyze the diversification ratio of both models on the training set.
As expected, the maximum diversification model has the highest diversification ratio:

```Python
ptf_model_train = model.predict(X_train)
ptf_bench_train = bench.predict(X_train)
print("Diversification Ratio:")
print(f"    Maximum Diversification model: {ptf_model_train.diversification:0.2f}")
print(f"    Equal Weighted model: {ptf_bench_train.diversification:0.2f}")
```

```none
Diversification Ratio:
    Maximum Diversification model: 1.92
    Equal Weighted model: 1.82
```

<a id="prediction"></a>

## Prediction

We predict the model and the benchmark on the test set:

```Python
ptf_model_test = model.predict(X_test)
ptf_bench_test = bench.predict(X_test)
```

<a id="analysis"></a>

## Analysis

For improved analysis, it’s possible to load both predicted portfolios into a
[`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population):

```Python
population = Population([ptf_model_test, ptf_bench_test])
```

Let’s plot each portfolio composition:

```Python
fig = population.plot_composition()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Finally we can show a full summary of both strategies evaluated on the test set:

```Python
population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<br/>

Finally, we print a full summary of both strategies evaluated on the test set:

```Python
population.summary()
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Let’s print the tracking error and the CVaR:

```Python
for portfolio in [ptf_no_tracking_train, ptf_tracking_train]:
    tracking_rmse = np.sqrt(np.mean((portfolio.returns - spx_train.returns) ** 2))
    print("========================")
    print(portfolio.tag)
    print("========================")
    print(f"Tracking RMSE: {tracking_rmse:0.2%}")
    print(f"CVaR at 95%: {portfolio.cvar:0.2%}")
    print(f"CVaR ratio: {portfolio.cvar_ratio:0.2f}")
    print("\n")
```

```none
========================
No Tracking
========================
Tracking RMSE: 0.60%
CVaR at 95%: 1.58%
CVaR ratio: 0.02

========================
Tracking 0.30%
========================
Tracking RMSE: 0.30%
CVaR at 95%: 1.78%
CVaR ratio: 0.03
```

The model with tracking error achieved the required RMSE of 0.30% versus the SPX on
the training set. The tradeoff of this constraint is the higher CVaR value versus
the model without tracking error.

<a id="prediction"></a>

## Prediction

Finally, we predict both models on the test set:

```Python
ptf_no_tracking_test = model_no_tracking.predict(X_test)
ptf_tracking_test = model_tracking.predict(X_test)
spx_test = model_spx.predict(y_test)

for portfolio in [ptf_no_tracking_test, ptf_tracking_test]:
    tracking_rmse = np.sqrt(np.mean((portfolio.returns - spx_test.returns) ** 2))
    print("========================")
    print(portfolio.tag)
    print("========================")
    print(f"Tracking RMSE: {tracking_rmse:0.2%}")
    print(f"CVaR at 95%: {portfolio.cvar:0.2%}")
    print(f"CVaR ratio: {portfolio.cvar_ratio:0.2f}")
    print("\n")
```

```none
========================
No Tracking
========================
Tracking RMSE: 1.04%
CVaR at 95%: 3.08%
CVaR ratio: 0.02

========================
Tracking 0.30%
========================
Tracking RMSE: 0.58%
CVaR at 95%: 3.39%
CVaR ratio: 0.02
```

As expected, the model with tracking error also achieved a lower RMSE on the test set
compared to the model without tracking error.

**Total running time of the script:** (0 minutes 0.825 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-10-tracking-error-py"></a>

# auto_examples/mean_risk/plot_11_empirical_prior.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-11-empirical-prior-py"></a>

<a id="empirical-prior"></a>

# Empirical Prior

This tutorial shows how to use the [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior) estimator in
the [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

A [Prior Estimator](https://skfolio.org/user_guide/prior.html.md#prior) in `skfolio` fits a `ReturnDistribution`
containing your pre-optimization inputs ($\mu$, $\Sigma$, returns, sample
weight, Cholesky decomposition).

The term “prior” is used in a general optimization sense, not confined to Bayesian
priors. It denotes any **a priori** assumption or estimation method for the return
distribution before optimization, unifying **Frequentist**, **Bayesian** and
**Information-theoretic** approaches into a single cohesive framework:

1. Frequentist:
   : * [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior)
     * [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel)
     * [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData)
2. Bayesian:
   : * [`BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman)
3. Information-theoretic:
   : * [`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling)
     * [`OpinionPooling`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling)

In skfolio’s API, all such methods share the same interface and adhere to scikit-learn’s
estimator API: the `fit` method accepts `X` (the asset returns) and stores the
resulting [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) in its `return_distribution_`
attribute.

The [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) is a dataclass containing:

> * `mu`: Estimated expected returns of shape (n_assets,)
> * `covariance`: Estimated covariance matrix of shape (n_assets, n_assets)
> * `returns`: (Estimated) asset returns of shape (n_observations, n_assets)
> * `sample_weight` : Sample weight for each observation of shape (n_observations,) (optional)
> * `cholesky` : Lower-triangular Cholesky factor of the covariance (optional)

The `EmpiricalPrior` estimator estimates the `ReturnDistribution` by fitting its
`mu_estimator` and `covariance_estimator` independently.

In this tutorial we will build a Maximum Sharpe Ratio portfolio using the
`EmpiricalPrior` estimator with James-Stein shrinkage for the estimation of expected
returns and Denoising for the estimation of the covariance matrix.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the SPX Index composition starting from 1990-01-02 up to 2022-12-28:

```Python
from plotly.io import show
from sklearn.model_selection import train_test_split

from skfolio import Population, RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.moments import DenoiseCovariance, ShrunkMu
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="model"></a>

## Model

We create a Maximum Sharpe Ratio model with shrinkage for the estimation of the
expected returns and denoising for the estimation of the covariance matrix:

```Python
model = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=EmpiricalPrior(
        mu_estimator=ShrunkMu(), covariance_estimator=DenoiseCovariance()
    ),
    portfolio_params=dict(name="Max Sharpe - ShrunkMu & DenoiseCovariance"),
)
model.fit(X_train)
model.weights_
```

```none
array([5.29957573e-02, 5.62258516e-07, 2.19431587e-07, 5.78329525e-02,
       1.05704853e-01, 6.42635886e-07, 1.25145591e-02, 1.64813030e-01,
       3.95272189e-07, 8.40687639e-02, 1.20296728e-06, 1.33374541e-06,
       6.51482298e-02, 7.44911613e-02, 7.02327401e-06, 1.27177410e-01,
       3.87852705e-02, 6.81199403e-02, 4.34872838e-02, 1.04849409e-01])
```

<a id="benchmark"></a>

## Benchmark

For comparison, we also create a Maximum Sharpe Ratio model using the default
moments estimators:

```Python
bench = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    portfolio_params=dict(name="Max Sharpe"),
)
bench.fit(X_train)
bench.weights_
```

```none
array([9.43631399e-02, 1.13184579e-06, 5.04970598e-07, 1.20834667e-01,
       3.18126275e-02, 8.57806907e-07, 7.11596802e-04, 1.24104939e-01,
       9.49223801e-07, 2.77547553e-02, 1.23409042e-06, 1.37593860e-06,
       1.16299875e-01, 5.73516411e-02, 9.58498590e-06, 1.09493919e-01,
       8.64761638e-02, 1.83992252e-01, 1.32350165e-02, 3.35537683e-02])
```

<a id="prediction"></a>

## Prediction

We predict both models on the test set:

```Python
pred_model = model.predict(X_test)
pred_bench = bench.predict(X_test)

population = Population([pred_model, pred_bench])

fig = population.plot_cumulative_returns()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

**Total running time of the script:** (0 minutes 0.720 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-11-empirical-prior-py"></a>

# auto_examples/mean_risk/plot_12_black_and_litterman.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-12-black-and-litterman-py"></a>

<a id="black-litterman"></a>

# Black & Litterman

This tutorial shows how to use the [`BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman) estimator in
the [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

A [Prior Estimator](https://skfolio.org/user_guide/prior.html.md#prior) in `skfolio` fits a `ReturnDistribution`
containing your pre-optimization inputs ($\mu$, $\Sigma$, returns, sample
weight, Cholesky decomposition).

The term “prior” is used in a general optimization sense, not confined to Bayesian
priors. It denotes any **a priori** assumption or estimation method for the return
distribution before optimization, unifying **Frequentist**, **Bayesian** and
**Information-theoretic** approaches into a single cohesive framework:

1. Frequentist:
   : * [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior)
     * [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel)
     * [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData)
2. Bayesian:
   : * [`BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman)
3. Information-theoretic:
   : * [`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling)
     * [`OpinionPooling`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling)

In skfolio’s API, all such methods share the same interface and adhere to scikit-learn’s
estimator API: the `fit` method accepts `X` (the asset returns) and stores the
resulting [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) in its `return_distribution_`
attribute.

The [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) is a dataclass containing:

> * `mu`: Estimated expected returns of shape (n_assets,)
> * `covariance`: Estimated covariance matrix of shape (n_assets, n_assets)
> * `returns`: (Estimated) asset returns of shape (n_observations, n_assets)
> * `sample_weight` : Sample weight for each observation of shape (n_observations,) (optional)
> * `cholesky` : Lower-triangular Cholesky factor of the covariance (optional)

The `BlackLitterman` estimator estimates the `ReturnDistribution` using
the Black & Litterman model. It takes a Bayesian approach by starting from a prior
estimate of the assets’ expected returns and covariance matrix, then updating them with
the analyst’s views to obtain the posterior estimates.

In this tutorial we will build a Maximum Sharpe Ratio portfolio using the
`BlackLitterman` estimator.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the SPX Index composition starting from 1990-01-02 up to 2022-12-28:

```Python
from plotly.io import show
from sklearn.model_selection import train_test_split

from skfolio import Population, RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import BlackLitterman

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="analyst-views"></a>

## Analyst views

Let’s assume we are able to accurately estimate views about future realization of the
market. We estimate that Apple will have an expected return of 25% p.a. (absolute
view) and will outperform General Electric by 22% p.a. (relative view). We also
estimate that JPMorgan will outperform General Electric by 15% p.a (relative view).
By converting these annualized estimates into daily estimates to be homogeneous with
the input `X`, we get:

```Python
analyst_views = [
    "AAPL == 0.00098",
    "AAPL - GE == 0.00086",
    "JPM - GE == 0.00059",
]
```

<a id="black-litterman-model"></a>

## Black & Litterman Model

We create a Maximum Sharpe Ratio model using the Black & Litterman estimator that we
fit on the training set:

```Python
model_bl = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=BlackLitterman(views=analyst_views),
    portfolio_params=dict(name="Black & Litterman"),
)
model_bl.fit(X_train)
model_bl.weights_
```

```none
array([4.73688339e-01, 2.66641803e-02, 2.20094200e-07, 2.02229897e-02,
       7.84166754e-03, 3.01723524e-08, 5.20800179e-07, 2.47479547e-03,
       3.27262165e-01, 4.77426684e-03, 1.73055734e-02, 3.34208578e-02,
       2.10139601e-03, 1.65511656e-02, 2.20704194e-06, 8.58902956e-07,
       3.40428153e-02, 3.36417527e-02, 6.20216082e-07, 3.57834061e-06])
```

<a id="empirical-model"></a>

## Empirical Model

For comparison, we also create a Maximum Sharpe Ratio model using the default
Empirical estimator:

```Python
model_empirical = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    portfolio_params=dict(name="Empirical"),
)
model_empirical.fit(X_train)
model_empirical.weights_
```

```none
array([9.43631399e-02, 1.13184579e-06, 5.04970598e-07, 1.20834667e-01,
       3.18126275e-02, 8.57806907e-07, 7.11596802e-04, 1.24104939e-01,
       9.49223801e-07, 2.77547553e-02, 1.23409042e-06, 1.37593860e-06,
       1.16299875e-01, 5.73516411e-02, 9.58498590e-06, 1.09493919e-01,
       8.64761638e-02, 1.83992252e-01, 1.32350165e-02, 3.35537683e-02])
```

<a id="prediction"></a>

## Prediction

We predict both models on the test set:

```Python
pred_bl = model_bl.predict(X_test)
pred_empirical = model_empirical.predict(X_test)

population = Population([pred_bl, pred_empirical])

population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Because our views were accurate, the Black & Litterman model outperformed the
Empirical model on the test set. From the below composition, we can see that Apple
and JPMorgan were allocated more weights:

```Python
fig = population.plot_composition()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

**Total running time of the script:** (0 minutes 0.970 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-12-black-and-litterman-py"></a>

# auto_examples/mean_risk/plot_13_factor_model.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-13-factor-model-py"></a>
> <a id="factor-model"></a>

<a id="time-series-factor-model"></a>

<a id="factor-model"></a>

# Time-Series Factor Model

`skfolio` supports time-series factor models through
[`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel) and characteristics-based
cross-sectional factor models through
[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel).

This tutorial uses [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel) to build a maximum
Sharpe ratio portfolio with [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk). Factor returns
are supplied as time series, and each asset’s exposures are estimated by regressing
its returns on those factor returns.

[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel) builds exposures from
point-in-time asset characteristics and estimates factor returns through
cross-sectional regression at each date. See the [Factor Models user guide](https://skfolio.org/user_guide/factor_models.html.md#factor-models) for the methodology and the [Characteristics Factor Model
tutorial](https://skfolio.org/auto_examples/factor_models/plot_characteristics_factor_model.html.md#sphx-glr-auto-examples-factor-models-plot-characteristics-factor-model-py)
for a complete example.

A [Prior Estimator](https://skfolio.org/user_guide/prior.html.md#prior) in `skfolio` estimates a
[`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) containing the inputs to portfolio
optimization ($\mu$, $\Sigma$, returns, sample weights and a Cholesky
decomposition).

The term “prior” is used in a general optimization sense, not confined to Bayesian
priors. It denotes any **a priori** assumption or estimation method for the return
distribution before optimization, unifying **Frequentist**, **Bayesian** and
**Information-theoretic** approaches into a single cohesive framework:

1. Frequentist:
   : * [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior)
     * [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel)
     * [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel)
     * [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData)
2. Bayesian:
   : * [`BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman)
3. Information-theoretic:
   : * [`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling)
     * [`OpinionPooling`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling)

Prior estimators follow scikit-learn’s estimator API and store the fitted
[`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) in `return_distribution_`. Their inputs
depend on the model. `TimeSeriesFactorModel` takes asset returns in `X` and factor
returns through the `factors` keyword argument.

The [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) is a dataclass containing:

> * `mu`: Estimated expected returns of shape (n_assets,)
> * `covariance`: Estimated covariance matrix of shape (n_assets, n_assets)
> * `returns`: (Estimated) asset returns of shape (n_observations, n_assets)
> * `sample_weight` : Sample weight for each observation of shape (n_observations,) (optional)
> * `cholesky` : Lower-triangular Cholesky factor of the covariance (optional)

The `TimeSeriesFactorModel` estimator estimates the `ReturnDistribution` by fitting
a factor model on asset returns alongside a specified [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior)
for the factor returns.

The purpose of factor models is to impose a structure on financial variables and
their covariance matrix by explaining them through a small number of common factors.
This can help overcome estimation error by reducing the number of parameters,
i.e., the dimensionality of the estimation problem, making portfolio optimization
more robust against noise in the data. Factor models also provide a decomposition of
financial risk into systematic and security-specific components.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the SPX Index composition and the Factors dataset composed of the daily
prices of 5 ETFs representing common factors:

```Python
from plotly.io import show
from sklearn import set_config
from sklearn.linear_model import RidgeCV
from sklearn.model_selection import train_test_split

from skfolio import Population, RiskMeasure
from skfolio.datasets import load_factors_dataset, load_sp500_dataset
from skfolio.moments import GerberCovariance, ShrunkMu
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior, LoadingMatrixRegression, TimeSeriesFactorModel

set_config(enable_metadata_routing=True)

prices = load_sp500_dataset()
factor_prices = load_factors_dataset()

X, factors = prices_to_returns(prices, factor_prices)
X_train, X_test, factors_train, factors_test = train_test_split(
    X, factors, test_size=0.33, shuffle=False
)
```

<a id="id1"></a>

<a id="id2"></a>

## Time-Series Factor Model

We create a Maximum Sharpe Ratio model using `TimeSeriesFactorModel` and fit it
on the training set:

```Python
model_factor_1 = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=TimeSeriesFactorModel(),
    portfolio_params=dict(name="Factor Model 1"),
)
model_factor_1.fit(X_train, factors=factors_train)
model_factor_1.weights_
```

```none
array([1.03294289e-06, 1.27482685e-03, 4.19682804e-07, 3.34130826e-06,
       7.36838288e-07, 1.28824408e-06, 5.13031432e-02, 6.35619183e-02,
       6.14804834e-07, 1.79106051e-01, 5.03130911e-02, 7.13734379e-02,
       4.13002526e-02, 2.27978407e-01, 5.13348034e-02, 1.44130375e-01,
       2.99026117e-07, 6.19737850e-02, 5.63413085e-02, 8.67773198e-07])
```

We can change the [`BaseLoadingMatrix`](https://skfolio.org/generated/skfolio.prior.BaseLoadingMatrix.html.md#skfolio.prior.BaseLoadingMatrix) that estimates the loading
matrix (betas) of the factors.

The default is the `LoadingMatrixRegression`, which fit the factors using a
`LassoCV` on each asset separately.

For example, let’s change the `LassoCV` into a `RidgeCV` without intercept and use
parallelization:

```Python
model_factor_2 = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=TimeSeriesFactorModel(
        loading_matrix_estimator=LoadingMatrixRegression(
            linear_regressor=RidgeCV(fit_intercept=False), n_jobs=-1
        )
    ),
    portfolio_params=dict(name="Factor Model 2"),
)
model_factor_2.fit(X_train, factors=factors_train)
model_factor_2.weights_
```

```none
array([3.97758339e-02, 6.57843874e-03, 2.18405141e-02, 8.98258882e-03,
       3.16197378e-02, 1.42391168e-02, 8.00124906e-02, 8.32090802e-02,
       4.74782930e-02, 8.59470407e-02, 4.59776221e-02, 5.91778878e-02,
       8.42236770e-02, 1.05684777e-01, 6.43841778e-02, 7.94729901e-02,
       3.76786712e-05, 5.23695742e-02, 4.35215146e-02, 4.54669667e-02])
```

We can also change the [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior) of the factors.
It is used to estimate the [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) containing
expected factor returns and the factor covariance matrix.

For example, let’s estimate expected factor returns with James-Stein shrinkage
and the factor covariance matrix with the Gerber covariance estimator:

```Python
model_factor_3 = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=TimeSeriesFactorModel(
        factor_prior_estimator=EmpiricalPrior(
            mu_estimator=ShrunkMu(), covariance_estimator=GerberCovariance()
        )
    ),
    portfolio_params=dict(name="Factor Model 3"),
)
model_factor_3.fit(X_train, factors=factors_train)
model_factor_3.weights_
```

```none
array([4.86490691e-07, 4.38230194e-07, 4.24408222e-08, 6.69653314e-08,
       5.11878214e-08, 6.14581602e-08, 1.68436387e-02, 2.08439609e-06,
       5.27854154e-08, 6.45513596e-02, 6.24004728e-02, 9.61498232e-02,
       3.68209826e-01, 2.44692220e-01, 5.86512138e-07, 9.30385165e-06,
       2.19939735e-08, 1.47139096e-01, 3.09340379e-07, 5.81316432e-08])
```

<a id="factor-analysis"></a>

## Factor Analysis

Each fitted estimator is saved with a trailing underscore.
For example, we can access the fitted prior estimator with:

```Python
prior_estimator = model_factor_3.prior_estimator_
```

We can access the return distribution with:

```Python
return_distribution = prior_estimator.return_distribution_
```

We can access the loading matrix with:

```Python
loading_matrix = prior_estimator.loading_matrix_estimator_.loading_matrix_
```

<a id="empirical-model"></a>

## Empirical Model

For comparison, we also create a Maximum Sharpe Ratio model using the default
Empirical estimator:

```Python
model_empirical = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    portfolio_params=dict(name="Empirical"),
)
model_empirical.fit(X_train)
model_empirical.weights_
```

```none
array([1.01561518e-01, 7.81165193e-02, 6.29030035e-07, 1.89005488e-02,
       3.05610118e-07, 1.55770502e-07, 1.10594710e-01, 1.22328443e-06,
       1.56471742e-06, 3.39453275e-06, 1.62631058e-01, 1.92171374e-06,
       1.77783711e-01, 9.61805760e-02, 4.64493061e-07, 9.68566446e-03,
       7.41771351e-08, 2.44533886e-01, 1.83984286e-06, 2.34178300e-07])
```

<a id="prediction"></a>

## Prediction

We predict all models on the test set:

```Python
ptf_factor_1_test = model_factor_1.predict(X_test)
ptf_factor_2_test = model_factor_2.predict(X_test)
ptf_factor_3_test = model_factor_3.predict(X_test)
ptf_empirical_test = model_empirical.predict(X_test)

population = Population(
    [ptf_factor_1_test, ptf_factor_2_test, ptf_factor_3_test, ptf_empirical_test]
)

fig = population.plot_cumulative_returns()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Let’s plot the portfolios’ composition:

```Python
population.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

**Total running time of the script:** (0 minutes 3.859 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-13-factor-model-py"></a>

# auto_examples/mean_risk/plot_14_black_litterman_factor_model.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-14-black-litterman-factor-model-py"></a>

<a id="black-litterman-factor-model"></a>

# Black & Litterman Factor Model

This tutorial shows how to use the [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel) estimator coupled
with the [`BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman) estimator in the
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

The Black & Litterman Factor Model is a Factor Model in which we incorporate views on
factors using the Black & Litterman Model.

In the previous two tutorials, we introduced the Factor Model and the Black & Litterman
separately. In this tutorial we show how we can merge them together by building a
Maximum Sharpe Ratio portfolio using the `TimeSeriesFactorModel` estimator.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the SPX Index composition and the Factors dataset composed of the daily
prices of 5 ETFs representing common factors:

```Python
from plotly.io import show
from sklearn.model_selection import train_test_split

from skfolio import Population, RiskMeasure
from skfolio.datasets import load_factors_dataset, load_sp500_dataset
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import BlackLitterman, TimeSeriesFactorModel

prices = load_sp500_dataset()
factor_prices = load_factors_dataset()

prices = prices["2014":]
factor_prices = factor_prices["2014":]

X, factors = prices_to_returns(prices, factor_prices)
X_train, X_test, factors_train, factors_test = train_test_split(
    X, factors, test_size=0.33, shuffle=False
)
```

<a id="analyst-views"></a>

## Analyst views

Let’s assume we are able to accurately estimate views about future realization of the
factors. We estimate that the factor Size will have an expected return of 10% p.a.
(absolute view) and will outperform the factor Value by 3% p.a. (relative view). We
also estimate the factor Momentum will outperform the factor Quality by 2% p.a
(relative view). By converting these annualized estimates into daily estimates to be
homogeneous with the input `X`, we get:

```Python
factor_views = [
    "SIZE == 0.00039",
    "SIZE - VLUE == 0.00011 ",
    "MTUM - QUAL == 0.00007",
]
```

<a id="id1"></a>

## Black & Litterman Factor Model

We create a Maximum Sharpe Ratio model using the Black & Litterman Factor Model that
we fit on the training set:

```Python
model_bl_factor = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=TimeSeriesFactorModel(
        factor_prior_estimator=BlackLitterman(views=factor_views),
    ),
    portfolio_params=dict(name="Black & Litterman Factor Model"),
)
model_bl_factor.fit(X_train, factors=factors_train)
model_bl_factor.weights_
```

```none
array([5.55998971e-02, 2.42678756e-02, 3.63991372e-02, 1.97989097e-02,
       4.38883360e-08, 1.69582846e-02, 1.34103109e-01, 3.52967021e-07,
       2.78013243e-02, 9.56133325e-02, 6.72490988e-02, 9.04221682e-02,
       1.24559355e-01, 8.98176230e-02, 5.85674115e-02, 2.83525179e-02,
       6.69595123e-03, 1.02316969e-01, 2.14765919e-02, 4.61288048e-08])
```

For comparison, we also create a Maximum Sharpe Ratio model using a simple Factor
Model:

```Python
model_factor = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=TimeSeriesFactorModel(),
    portfolio_params=dict(name="Factor Model"),
)
model_factor.fit(X_train, factors=factors_train)
model_factor.weights_
```

```none
array([1.03294289e-06, 1.27482685e-03, 4.19682804e-07, 3.34130826e-06,
       7.36838288e-07, 1.28824408e-06, 5.13031432e-02, 6.35619183e-02,
       6.14804834e-07, 1.79106051e-01, 5.03130911e-02, 7.13734379e-02,
       4.13002526e-02, 2.27978407e-01, 5.13348034e-02, 1.44130375e-01,
       2.99026117e-07, 6.19737850e-02, 5.63413085e-02, 8.67773198e-07])
```

<a id="prediction"></a>

## Prediction

We predict both models on the test set:

```Python
ptf_bl_factor_test = model_bl_factor.predict(X_test)
ptf_factor_test = model_factor.predict(X_test)

population = Population([ptf_bl_factor_test, ptf_factor_test])

population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Because our factor views were accurate, the Black & Litterman Factor Model
outperformed the simple Factor Model on the test set.

Let’s plot the portfolios compositions:

```Python
fig = population.plot_composition()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<a id="going-further"></a>

## Going Further

The API design makes it possible to created nested models without limits.
In the below example, we re-apply a Black & Litterman model incorporating assets
views. But instead of using the empirical moments, we use the above Black & Litterman
factor model:

```Python
assets_views = [
    "AAPL == 0.00098",
    "AAPL - GE == 0.00086",
    "JPM - GE == 0.00059",
]

model = BlackLitterman(
    views=assets_views,
    prior_estimator=TimeSeriesFactorModel(
        factor_prior_estimator=BlackLitterman(views=factor_views),
    ),
)

model.fit(X, factors=factors)
print(model.return_distribution_.covariance.shape)
```

```none
(20, 20)
```

**Total running time of the script:** (0 minutes 5.005 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-14-black-litterman-factor-model-py"></a>

# auto_examples/mean_risk/plot_15_mip_cardinality_constraints.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-15-mip-cardinality-constraints-py"></a>

<a id="cardinality-constraints"></a>

# Cardinality Constraints

This tutorial shows how to use cardinality constraints with the
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

Cardinality constraint controls the total number of invested assets (non-zero weights)
in the portfolio. Cardinality constraints can also be specified for asset groups
(e.g., tech, healthcare).

In a previous tutorial, we showed how to reduce the number of assets using L1
regularization. However, asset managers sometimes require more granularity and
precision regarding the exact number of assets allowed, both in total and per group.

Cardinality constraints require a mixed-integer solver. For an open-source option,
we recommend using SCIP by setting `solver="SCIP"`. To install it, use:
`pip install cvxpy[SCIP]`. For commercial solvers, supported options include
MOSEK, GUROBI, or CPLEX.

Mixed-Integer Programming (MIP) involves optimization with both continuous and integer
variables and is inherently non-convex due to the discrete nature of integer variables.
Over recent decades, MIP solvers have significantly advanced, utilizing methods
like Branch and Bound and cutting planes to improve efficiency.

By leveraging specialized techniques such as homogenization and the Big M method,
combined with problem-specific calibration, Skfolio can reformulate these complex
problems into a Mixed-Integer Program that can be efficiently solved using these
solvers.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 2018-01-02 up to 2022-12-28.

```Python
from plotly.io import show
from sklearn.model_selection import train_test_split

from skfolio import PerfMeasure, RatioMeasure, RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
prices = prices["2018":]
X = prices_to_returns(prices)
```

<a id="cardinality-constraint"></a>

## Cardinality Constraint

let’s use a Minimum CVaR model and limit the total number of assets to 5:

```Python
model = MeanRisk(risk_measure=RiskMeasure.CVAR, cardinality=5, solver="SCIP")
model.fit(X)
model.weights_
```

```none
array([0.        , 0.        , 0.        , 0.        , 0.        ,
       0.        , 0.        , 0.        , 0.        , 0.18903764,
       0.        , 0.28559484, 0.        , 0.        , 0.12448701,
       0.1392389 , 0.        , 0.        , 0.26164161, 0.        ])
```

We notice that the number of non-zero weights is indeed equal to 5.
You can change the default solver parameters using `solver_params`.
For more details about solver arguments, check the CVXPY
documentation: [https://www.cvxpy.org/tutorial/solvers](https://www.cvxpy.org/tutorial/solvers)

<a id="cardinality-constraint-per-group"></a>

## Cardinality Constraint per Group

First, let’s assign two groups to each asset: sector and capitalization.

```Python
groups = {
    "AAPL": ["Technology", "Mega Cap"],
    "AMD": ["Technology", "Large Cap"],
    "BAC": ["Financials", "Mega Cap"],
    "BBY": ["Consumer", "Large Cap"],
    "CVX": ["Energy", "Mega Cap"],
    "GE": ["Industrials", "Large Cap"],
    "HD": ["Consumer", "Mega Cap"],
    "JNJ": ["Healthcare", "Mega Cap"],
    "JPM": ["Financials", "Mega Cap"],
    "KO": ["Consumer", "Mega Cap"],
    "LLY": ["Healthcare", "Mega Cap"],
    "MRK": ["Healthcare", "Mega Cap"],
    "MSFT": ["Technology", "Mega Cap"],
    "PEP": ["Consumer", "Mega Cap"],
    "PFE": ["Healthcare", "Mega Cap"],
    "PG": ["Consumer", "Mega Cap"],
    "RRC": ["Energy", "Small Cap"],
    "UNH": ["Healthcare", "Mega Cap"],
    "WMT": ["Consumer", "Mega Cap"],
    "XOM": ["Energy", "Mega Cap"],
}
```

Let’s restrict the maximum number of assets in the following groups:

> * Healthcare: 2
> * Small Cap: 1
> * Mega Cap: 4

```Python
model = MeanRisk(
    risk_measure=RiskMeasure.CVAR,
    groups=groups,
    group_cardinalities={"Healthcare": 2, "Small Cap": 1, "Mega Cap": 4},
    solver="SCIP",
)
model.fit(X)
model.weights_
```

```none
array([0.        , 0.        , 0.        , 0.        , 0.        ,
       0.        , 0.        , 0.        , 0.        , 0.22548433,
       0.        , 0.30773101, 0.        , 0.        , 0.1394078 ,
       0.        , 0.01095357, 0.        , 0.31642328, 0.        ])
```

We can see that the maximum number of assets per group has been respected:

```Python
portfolio = model.predict(X)
print({k: groups[k] for k in portfolio.composition.index})
```

```none
{'WMT': ['Consumer', 'Mega Cap'], 'MRK': ['Healthcare', 'Mega Cap'], 'KO': ['Consumer', 'Mega Cap'], 'PFE': ['Healthcare', 'Mega Cap'], 'RRC': ['Energy', 'Small Cap']}
```

<a id="efficient-frontier"></a>

## Efficient Frontier

Let’s plot the efficient frontiers of cardinality-constrained and unconstrained
mean-CVaR portfolios on the training set and analyze the results on the test set.
We will focus only on the portfolios on the frontier that have a CVaR at 95% below 5%:

```Python
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = MeanRisk(
    risk_measure=RiskMeasure.CVAR,
    efficient_frontier_size=20,
    max_cvar=0.05,
    # Name and tag are used to improve plot readability
    portfolio_params=dict(name="Unconstrained", tag="Unconstrained"),
)
model.fit(X_train)

model_constrained = MeanRisk(
    risk_measure=RiskMeasure.CVAR,
    efficient_frontier_size=20,
    max_cvar=0.05,
    cardinality=3,
    solver="SCIP",
    portfolio_params=dict(name="Constrained", tag="Constrained"),
)
model_constrained.fit(X_train)

population_train = model.predict(X_train) + model_constrained.predict(X_train)
population_test = model.predict(X_test) + model_constrained.predict(X_test)

fig = population_train.plot_measures(
    x=RiskMeasure.CVAR,
    y=PerfMeasure.ANNUALIZED_MEAN,
    color_scale=RatioMeasure.CVAR_RATIO,
    hover_measures=[RatioMeasure.ANNUALIZED_SHARPE_RATIO],
)
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Let’s plot the compositions:

```Python
population_train.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Finally, we can analyse the test population using methods such as:

> * `population_test.summary()`
> * `population_test.plot_cumulative_returns()`
> * `population_test.plot_distribution(measure_list=[RatioMeasure.CVAR_RATIO, RatioMeasure.ANNUALIZED_SHARPE_RATIO])`
> * `population_test.plot_rolling_measure(measure=RatioMeasure.CVAR_RATIO)`

**Total running time of the script:** (0 minutes 31.193 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-15-mip-cardinality-constraints-py"></a>

# auto_examples/mean_risk/plot_16_mip_threshold_constraints.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-16-mip-threshold-constraints-py"></a>

<a id="threshold-constraints"></a>

# Threshold Constraints

This tutorial shows how to use threshold constraints with the
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

Threshold constraints ensure that invested assets have sufficiently large weights.
This can help eliminate insignificant allocations.

Both long and short position thresholds can be controlled using `threshold_long` and
`threshold_short`.

Threshold constraints require a mixed-integer solver. For an open-source option,
we recommend using SCIP by setting `solver="SCIP"`. To install it, use:
`pip install cvxpy[SCIP]`. For commercial solvers, supported options include
MOSEK, GUROBI, or CPLEX.

Mixed-Integer Programming (MIP) involves optimization with both continuous and integer
variables and is inherently non-convex due to the discrete nature of integer variables.
Over recent decades, MIP solvers have significantly advanced, utilizing methods
like Branch and Bound and cutting planes to improve efficiency.

By leveraging specialized techniques such as homogenization and the Big M method,
combined with problem-specific calibration, Skfolio can reformulate these complex
problems into a Mixed-Integer Program that can be efficiently solved using these
solvers.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 2018-01-02 up to 2022-12-28.

```Python
from plotly.io import show

from skfolio import Population, RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
prices = prices["2018":]
X = prices_to_returns(prices)
```

<a id="model"></a>

## Model

let’s use a long-short Minimum CVaR model:

```Python
model = MeanRisk(
    min_weights=-1,
    risk_measure=RiskMeasure.CVAR,
)
model.fit(X)
model.weights_
```

```none
array([-0.0433679 ,  0.00122628, -0.15054114, -0.02295189, -0.06321762,
       -0.01085526,  0.0836907 ,  0.12708155,  0.0279316 ,  0.20613357,
       -0.01153713,  0.27084789,  0.00618136,  0.00118977,  0.10447746,
        0.07189762,  0.03339536,  0.04061729,  0.25238053,  0.07541995])
```

Now, let’s assume we don’t want weights that are too small.
This means that, let’s say, if an asset is invested (non-zero weight), it needs to be
between -100% to -10% **or** +15% to +100%:

```Python
model_threshold = MeanRisk(
    min_weights=-1,
    risk_measure=RiskMeasure.CVAR,
    threshold_long=0.15,
    threshold_short=-0.10,
    solver="SCIP",
)
model_threshold.fit(X)
model_threshold.weights_
```

```none
array([ 0.        ,  0.        , -0.1476994 ,  0.        , -0.1       ,
        0.        ,  0.        ,  0.15274862,  0.        ,  0.23496164,
        0.        ,  0.28011081,  0.        ,  0.        ,  0.15      ,
        0.        ,  0.        ,  0.        ,  0.25077844,  0.17909988])
```

We notice that the long and short threshold constraints have been respected.
You can change the default solver parameters using `solver_params`.
For more details about solver arguments, check the CVXPY
documentation: [https://www.cvxpy.org/tutorial/solvers](https://www.cvxpy.org/tutorial/solvers)

To visualize both portfolio compositions, let’s plot them:

```Python
ptf = model.predict(X)
ptf.name = "Min CVaR"
ptf_threshold = model_threshold.predict(X)
ptf_threshold.name = "Min CVaR with Threshold Constraints"
population = Population([ptf, ptf_threshold])
fig = population.plot_composition()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

**Total running time of the script:** (0 minutes 10.236 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-16-mip-threshold-constraints-py"></a>

# auto_examples/mean_risk/plot_17_failure_and_fallbacks.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-17-failure-and-fallbacks-py"></a>

<a id="failure-and-fallbacks"></a>

# Failure and Fallbacks

This tutorial introduces the optimization parameters `fallback` and `raise_on_failure`.

Optimization can sometimes fail during a given rebalancing. For example, a convex
mean-variance problem with strict risk or sector constraints may become infeasible on
specific dates. Such failures must be handled explicitly depending on the use case
(production vs. research).

<a id="fallback"></a>

## Fallback

The `fallback` parameter lets you define an estimator, or a list of estimators, to try
in order when the primary optimization raises an error during `fit`. Alternatively, you
can use `"previous_weights"` to reuse the last valid allocation.

Each attempt is recorded in `fallback_chain_`, and the successful estimator is available
through `fallback_`.

This mechanism is essential in automated pipelines, ensuring that optimization failures
never halt production runs while preserving full reproducibility and traceability.
Beyond safeguarding workflows, it can also be used to deliberately relax constraints in
a controlled manner when strict convergence cannot be achieved.

<a id="raise-on-failure"></a>

## Raise on Failure

In research, cross-validation and hyperparameter tuning (e.g. walk-forward, multiple
randomized cross-validation), it’s often useful to let all runs complete while keeping
a full record of failures instead of stopping on the first failed rebalancing.

- Set `raise_on_failure=True` (default) to fail fast. This is useful in production when
  the primary optimization or the fallback cascade is expected to succeed.
- Set `raise_on_failure=False` to continue uninterrupted. This is useful in research
  and cross-validation. When a failure occurs, `predict` returns a
  [`FailedPortfolio`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio) (think of it as an augmented NaN) that
  carries diagnostics such as `optimization_error` and `fallback_chain`, while remaining
  API-compatible with downstream analytics.

<a id="data-and-setup"></a>

## Data and Setup

Load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) and split into train/test.

```Python
import pandas as pd
from plotly.io import show
from sklearn.model_selection import train_test_split
from sklearn.utils.validation import validate_data

from skfolio.datasets import load_sp500_dataset
from skfolio.model_selection import WalkForward, cross_val_predict
from skfolio.optimization import BaseOptimization, EqualWeighted, MeanRisk
from skfolio.preprocessing import prices_to_returns
from skfolio.typing import Fallback, MultiInput
from skfolio.utils.stats import rand_weights

# Load S&P 500 dataset and split train/test
prices = load_sp500_dataset()
prices = prices["2010":]
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="id1"></a>

## Fallback

Let’s start with a simple example.
The primary model is a minimum-variance optimization made intentionally infeasible
(the assets’ minimum weights are set to 10%, which exceeds the feasible upper bound
of 1/n_assets = 5%). As a fallback, we provide a feasible minimum-variance model
with a 2% minimum weight constraint:

```Python
model = MeanRisk(
    min_weights=0.1,  # intentionally infeasible
    fallback=MeanRisk(min_weights=0.02),  # feasible fallback
)
model.fit(X_train)
print(model.weights_)
```

```none
[0.02000143 0.02000011 0.02000017 0.02000038 0.02000046 0.02000042
 0.02000085 0.12397314 0.02000024 0.09473377 0.02004185 0.02000133
 0.02000057 0.17901455 0.0200018  0.17643479 0.02000026 0.02000095
 0.12579215 0.02000078]
```

<a id="diagnostics"></a>

### Diagnostics

Let’s retrieve the fitted fallback that produced the final result:

```Python
print(model.fallback_)
```

```none
MeanRisk(min_weights=0.02)
```

Let’s display the sequence of attempts and their outcomes:

```Python
print(model.fallback_chain_)
```

```none
[('MeanRisk(fallback=MeanRisk(min_weights=0.02), min_weights=0.1)', "Solver 'CLARABEL' failed. Try another solver, or solve with solver_params=dict(verbose=True) for more information"), ('MeanRisk(min_weights=0.02)', 'success')]
```

The fallback audit trail is also propagated to the predicted portfolio:

```Python
portfolio = model.predict(X_test)
assert portfolio.fallback_chain == model.fallback_chain_
```

<a id="multiple-fallbacks"></a>

### Multiple fallbacks

We can also provide a list of fallbacks to be tried in order, including
“previous_weights” as a terminal safety net:

```Python
model = MeanRisk(
    min_weights=0.1,
    previous_weights={
        "AAPL": 0.4,
        "AMD": 0.2,
        "UNH": 0.4,
    },  # any missing assets default to 0
    fallback=[
        MeanRisk(min_weights=0.02),
        MeanRisk(min_weights=0.01),
        EqualWeighted(),
        "previous_weights",
    ],
)
```

<a id="chaining"></a>

### Chaining

We can also nest fallbacks.
The chain is evaluated depth-first from the primary estimator to the
first successful fallback, recording each attempt in `fallback_chain_`.
This is equivalent to providing an ordered list:

```Python
model = MeanRisk(
    min_weights=0.1,
    fallback=MeanRisk(
        min_weights=0.02,
        fallback=MeanRisk(
            min_weights=0.01,
            fallback=EqualWeighted(),
        ),
    ),
)
```

<a id="fallback-in-cross-validation"></a>

## Fallback in cross-validation

Fallback behavior is fully preserved in cross-validation.

When using `cross_val_predict`, all diagnostics (e.g., fallback chains and errors)
are propagated to the resulting portfolios in the `MultiPeriodPortfolio`:

- Each individual [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio)
  (or [`FailedPortfolio`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio)) produced during rebalancing
  carries its own `fallback_chain` and `optimization_error`.
- Global counts and statistics (e.g., the number of portfolios that required a
  fallback) are available through summary attributes such as
  `n_fallback_portfolios` and `n_failed_portfolios`.
- The `summary()` method consolidates performance and diagnostic information
  across all rebalances.

```Python
model = MeanRisk(min_weights=0.1, fallback=MeanRisk(min_weights=0.02))

# Rebalance semiannually on the third Friday (WOM-3FRI), training on the prior 12 months
walk_forward = WalkForward(test_size=6, train_size=12, freq="WOM-3FRI")

pred = cross_val_predict(model, X, cv=walk_forward)
```

Let’s retrieve the fallback chain of the first portfolio:

```Python
print(pred[0].fallback_chain)
```

```none
[('MeanRisk(fallback=MeanRisk(min_weights=0.02), min_weights=0.1)', "Solver 'CLARABEL' failed. Try another solver, or solve with solver_params=dict(verbose=True) for more information"), ('MeanRisk(min_weights=0.02)', 'success')]
```

Let’s print the number of portfolios in
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) where a fallback was used:

```Python
print(pred.n_fallback_portfolios)
```

```none
23
```

Finally, let’s display the last four rows of the `MultiPeriodPortfolio` summary,
which contain the fallback statistics:

```Python
print(pred.summary().iloc[-4:])
```

```none
Avg nb of Assets per Portfolio    20.0
Number of Portfolios                23
Number of Failed Portfolios          0
Number of Fallback Portfolios       23
dtype: str
```

<a id="failure-handling"></a>

## Failure handling

In this section, we show how to handle optimization failures using the
`raise_on_failure` parameter.
As an example, we create a custom optimization that intentionally fails during `fit`
when the first date of the input window falls on an even day of the month, or when
`always_fail=True`.

```Python
class CustomOptimization(BaseOptimization):
    """Dummy optimization that intentionally fails during `fit` when the first
    date of the input window is an even day-of-month, or when `always_fail=True`."""

    def __init__(
        self,
        always_fail: bool = False,
        portfolio_params: dict | None = None,
        fallback: Fallback = None,
        previous_weights: MultiInput | None = None,
        raise_on_failure: bool = True,
    ):
        super().__init__(
            portfolio_params=portfolio_params,
            fallback=fallback,
            raise_on_failure=raise_on_failure,
            previous_weights=previous_weights,
        )
        self.always_fail = always_fail

    def fit(self, X: pd.DataFrame, y=None):
        validate_data(self, X)
        # Fail when first observation date has an even day-of-month, or always.
        if self.always_fail:
            raise RuntimeError("Forced failure")
        first_day = X.index[0].day
        if first_day % 2 == 0:
            raise RuntimeError("Forced failure (even-start window)")
        n_assets = X.shape[1]
        self.weights_ = rand_weights(n_assets)
        return self
```

By default, as with all scikit-learn estimators, failures raise an error during `fit`:

```Python
model = CustomOptimization(always_fail=True)
try:
    model.fit(X_train)
except RuntimeError as err:
    print(err)
```

```none
Forced failure
```

By setting `raise_on_failure=False`, a warning is emitted instead of raising an error,
and `weights_` are set to `None`, with the error message stored in `error_`:

```Python
model = CustomOptimization(always_fail=True, raise_on_failure=False)
model.fit(X_train)
print(model.weights_)
print(model.error_)
```

```none
None
Forced failure
```

In this case, calling `predict` will return a `FailedPortfolio` carrying the audit
trail in `optimization_error` and `fallback_chain` (if any fallbacks occurred).

```Python
portfolio = model.predict(X_test)
print(portfolio)
print(portfolio.optimization_error)
```

```none
<FailedPortfolio CustomOptimization>
Forced failure
```

Setting `raise_on_failure=False` is useful for cross-validation and hyperparameter
tuning as it allows all runs to complete without stopping at the first rebalancing
failure. Let’s instantiate our custom optimization and run a walk-forward analysis
where failures occur deterministically on even-start windows:

```Python
model = CustomOptimization(raise_on_failure=False)
pred = cross_val_predict(model, X, cv=walk_forward)
```

`cross_val_predict` completed without interruption.
The resulting `MultiPeriodPortfolio` is composed of both `Portfolio` and
`FailedPortfolio` objects:

```Python
print(pred.portfolios)
```

```none
[<Portfolio CustomOptimization>, <FailedPortfolio CustomOptimization>, <Portfolio CustomOptimization>, <Portfolio CustomOptimization>, <FailedPortfolio CustomOptimization>, <FailedPortfolio CustomOptimization>, <FailedPortfolio CustomOptimization>, <Portfolio CustomOptimization>, <Portfolio CustomOptimization>, <FailedPortfolio CustomOptimization>, <FailedPortfolio CustomOptimization>, <Portfolio CustomOptimization>, <Portfolio CustomOptimization>, <Portfolio CustomOptimization>, <FailedPortfolio CustomOptimization>, <Portfolio CustomOptimization>, <Portfolio CustomOptimization>, <FailedPortfolio CustomOptimization>, <FailedPortfolio CustomOptimization>, <Portfolio CustomOptimization>, <Portfolio CustomOptimization>, <Portfolio CustomOptimization>, <Portfolio CustomOptimization>]
```

Let’s print the number of failed portfolios:

```Python
print(pred.n_failed_portfolios)
```

```none
9
```

Even though `MultiPeriodPortfolio` contains failed portfolios, all statistics and
plots still work properly. This is because `FailedPortfolio` is designed to behave
like non-propagating NaNs:

```Python
print(pred.summary())
```

```none
Mean                                     0.060%
Annualized Mean                          15.16%
Variance                               0.000073
Annualized Variance                       1.83%
Semi-Variance                          0.000039
Annualized Semi-Variance                  0.97%
Standard Deviation                        0.85%
Annualized Standard Deviation            13.54%
Semi-Deviation                            0.62%
Annualized Semi-Deviation                 9.87%
Mean Absolute Deviation                   0.63%
CVaR at 95%                               2.03%
EVaR at 95%                               2.60%
Worst Realization                         4.30%
CDaR at 95%                              10.44%
MAX Drawdown                             19.88%
Average Drawdown                          2.21%
EDaR at 95%                              12.96%
First Lower Partial Moment                0.31%
Ulcer Index                               0.035
Gini Mean Difference                      0.92%
Value at Risk at 95%                      1.40%
Drawdown at Risk at 95%                   7.72%
Entropic Risk Measure at 95%               3.00
Fourth Central Moment                 0.000003%
Fourth Lower Partial Moment           0.000002%
Skew                                    -22.59%
Kurtosis                                534.25%
Sharpe Ratio                              0.071
Annualized Sharpe Ratio                    1.12
Sortino Ratio                             0.097
Annualized Sortino Ratio                   1.54
Mean Absolute Deviation Ratio             0.096
First Lower Partial Moment Ratio           0.19
Value at Risk Ratio at 95%                0.043
CVaR Ratio at 95%                         0.030
Entropic Risk Measure Ratio at 95%      0.00020
EVaR Ratio at 95%                         0.023
Worst Realization Ratio                   0.014
Drawdown at Risk Ratio at 95%            0.0078
CDaR Ratio at 95%                        0.0058
Calmar Ratio                             0.0030
Average Drawdown Ratio                    0.027
EDaR Ratio at 95%                        0.0046
Ulcer Index Ratio                         0.017
Gini Mean Difference Ratio                0.065
Avg nb of Assets per Portfolio             20.0
Number of Portfolios                         23
Number of Failed Portfolios                   9
Number of Fallback Portfolios                 0
dtype: str
```

As shown below, `MultiPeriodPortfolio` plots gracefully handle `FailedPortfolio`
instances; for cumulative returns, these appear as gaps corresponding to failed
periods:

```Python
fig = pred.plot_cumulative_returns()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Finally, let’s inspect the first failed portfolio:

```Python
failed_ptf = pred.failed_portfolios[0]
print(failed_ptf.optimization_error)
```

```none
Forced failure (even-start window)
```

To replay the optimization on the failed period, we can run:

```Python
# model.fit(failed_ptf.X)
```

**Total running time of the script:** (0 minutes 1.437 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-17-failure-and-fallbacks-py"></a>

# auto_examples/mean_risk/plot_1_maximum_sharpe_ratio.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-1-maximum-sharpe-ratio-py"></a>

<a id="maximum-sharpe-ratio"></a>

# Maximum Sharpe Ratio

This tutorial uses the [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization to find the
maximum Sharpe Ratio portfolio.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 1990-01-02 up to 2022-12-28.
Prices are transformed into linear returns (see [data preparation](https://skfolio.org/user_guide/data_preparation.html.md#data-preparation)) and split into a training set and a test set without shuffling to
avoid [data leakage](https://skfolio.org/user_guide/model_selection.html.md#data-leakage).

```Python
import numpy as np
from plotly.io import show
from sklearn.model_selection import train_test_split

from skfolio import Population, RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import InverseVolatility, MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

print(X_train.head())
```

```none
                AAPL       AMD       BAC  ...       UNH       WMT       XOM
Date                                      ...
1990-01-03  0.007576 -0.030303  0.008045  ... -0.019355  0.000000 -0.010079
1990-01-04  0.003759 -0.015500 -0.021355  ... -0.009868 -0.005201 -0.009933
1990-01-05  0.003745 -0.031996 -0.021821  ... -0.043189 -0.010732 -0.005267
1990-01-08  0.003731  0.000000  0.005633  ... -0.020833  0.013630  0.015381
1990-01-09 -0.007435  0.016527  0.000000  ... -0.024823 -0.026619 -0.020114

[5 rows x 20 columns]
```

<a id="model"></a>

## Model

We create a Maximum Sharpe Ratio model and then fit it on the training set.
`portfolio_params` are parameters passed to the [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio)
returned by the `predict` method. It can be
omitted, here we use it to give a name to our maximum Sharpe Ratio portfolio:

```Python
model = MeanRisk(
    risk_measure=RiskMeasure.STANDARD_DEVIATION,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    portfolio_params=dict(name="Max Sharpe"),
)
model.fit(X_train)
model.weights_
```

```none
array([9.43837536e-02, 1.23703226e-07, 4.32481917e-08, 1.20892854e-01,
       3.18418329e-02, 7.69682661e-08, 1.78420641e-04, 1.24117994e-01,
       8.50336295e-08, 2.77970034e-02, 1.31617984e-07, 1.49536746e-07,
       1.16362392e-01, 5.73881398e-02, 9.91607320e-07, 1.09506312e-01,
       8.64772579e-02, 1.84018669e-01, 1.34639296e-02, 3.35698407e-02])
```

To compare this model, we use an inverse volatility benchmark using
the [`InverseVolatility`](https://skfolio.org/generated/skfolio.optimization.InverseVolatility.html.md#skfolio.optimization.InverseVolatility) estimator:

```Python
benchmark = InverseVolatility(portfolio_params=dict(name="Inverse Vol"))
benchmark.fit(X_train)
benchmark.weights_
```

```none
array([0.03306735, 0.02548697, 0.03551377, 0.0296872 , 0.06358463,
       0.05434705, 0.04742354, 0.07049715, 0.03882539, 0.06697905,
       0.05570808, 0.05576851, 0.04723274, 0.06351213, 0.05581397,
       0.0676481 , 0.02564642, 0.03970752, 0.05744543, 0.06610498])
```

<a id="prediction"></a>

## Prediction

We predict the model and the benchmark on the test set:

```Python
pred_model = model.predict(X_test)
pred_bench = benchmark.predict(X_test)
```

The `predict` method returns a [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) object.

[`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) is an array-container making it compatible
with `scikit-learn` tools: calling `np.asarray(pred_model)` gives the portfolio
returns (same as `pred_model.returns`):

```Python
np.asarray(pred_model)
```

```none
array([ 0.00805138,  0.01084096,  0.00199137, ...,  0.00932288,
        0.00152751, -0.01787269], shape=(2743,))
```

The [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) class contains a vast number of properties
and methods used for analysis.

For example:
<br/>
* pred_model.plot_cumulative_returns()
* pred_model.plot_composition()
* pred_model.summary()

```Python
print(pred_model.annualized_sharpe_ratio)
print(pred_bench.annualized_sharpe_ratio)
```

```none
1.0399724999465625
1.0036976120249752
```

<a id="analysis"></a>

## Analysis

For improved analysis, we load both predicted portfolios into a
[`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population):

```Python
population = Population([pred_model, pred_bench])
```

The [`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population) class also contains a
vast number of properties and methods used for analysis.
Let’s plot each portfolio composition:

```Python
population.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

#### NOTE
Every `plot` methods in `skfolio` returns a `plotly` figure.
To display a plotly figure, you may need to call `show()` and change the
default renderer: [https://plotly.com/python/renderers/](https://plotly.com/python/renderers/)

Let’s plot each portfolio cumulative returns:

```Python
fig = population.plot_cumulative_returns()
# show(fig) is only used for the documentation sticker.
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Finally, let’s display the full summary of both strategies evaluated on the test
set:

```Python
population.summary()
```

[plotly figure stripped from llms output]
<br />
<br />

#### NOTE
Every `plot` methods in `skfolio` returns a `plotly` figure.
To display a plotly figure, you may need to call `show()` and change the
default renderer: [https://plotly.com/python/renderers/](https://plotly.com/python/renderers/)

Let’s plot each portfolio cumulative returns:

```Python
fig = population.plot_cumulative_returns()
# show(fig) is only used for the documentation sticker.
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Finally, let’s display the full summary of both strategies evaluated on the test
set:

```Python
population.summary()
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Let’s plot the composition of the 30 portfolios:

```Python
population_train.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s print the Sharpe Ratio of the 30 portfolios on the test set:

```Python
population_test.measures(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO)
```

```none
array([0.91785162, 0.93000375, 0.9401232 , 0.95027284, 0.96861483,
       0.98463685, 0.9983657 , 1.00992555, 1.01943433, 1.02702131,
       1.032813  , 1.03704654, 1.03993049, 1.04204356, 1.0430764 ,
       1.04289017, 1.04158213, 1.03774863, 1.02943678, 1.02092595,
       1.01241175, 1.00356473, 0.97964062, 0.93749217, 0.87986871,
       0.78090544, 0.68550154, 0.59858003, 0.53398775, 0.55455742])
```

Finally, we can show a full summary of the 30 portfolios evaluated on the test set:

```Python
population.summary()
```

[plotly figure stripped from llms output]
<br />
<br />

**Total running time of the script:** (0 minutes 1.886 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-3-efficient-frontier-py"></a>

# auto_examples/mean_risk/plot_4_mean_variance_cdar.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-4-mean-variance-cdar-py"></a>

<a id="mean-variance-cdar-surface"></a>

# Mean-Variance-CDaR Surface

This tutorial uses the [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization to find an
ensemble of portfolios belonging to the Mean-Variance-CDaR efficient frontier.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 2015-01-05 up to 2022-12-28:

```Python
import numpy as np
from plotly.io import show
from sklearn.model_selection import train_test_split

from skfolio import PerfMeasure, RatioMeasure, RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
prices = prices["2015":]

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="model"></a>

## Model

First, we create a Maximum Sharpe Ratio model that we fit on the training set:

```Python
model = MeanRisk(
    risk_measure=RiskMeasure.STANDARD_DEVIATION,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
)
portfolio = model.fit_predict(X_train)
print(portfolio.cdar)
```

```none
0.17001212853184347
```

Let’s assume that we are not satisfied with the CDaR (Conditional Drawdown at Risk)
of 17% corresponding to the maximum Sharpe portfolio. We want to analyze alternative
portfolios that maximize the Sharpe under CDaR constraints.
To have an idea of the feasible CDaR constraints, we analyze the Minimum CDaR
portfolio:

```Python
model = MeanRisk(risk_measure=RiskMeasure.CDAR)
portfolio = model.fit_predict(X_train)
print(portfolio.cdar)
```

```none
0.09718550832245015
```

The minimum CDaR is 9.72%.
Now we find the Pareto-optimal portfolios that maximize the Sharpe under CDaR
constraint ranging from 9.72% to 17%:

```Python
model = MeanRisk(
    risk_measure=RiskMeasure.STANDARD_DEVIATION,
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    max_cdar=np.linspace(start=0.0972, stop=0.17, num=10),
)
model.fit(X_train)
print(model.weights_.shape)
```

```none
(10, 20)
```

<a id="analysis"></a>

## Analysis

We predict this model on both the training set and the test set to analyze the
deformation of the efficient frontier:

```Python
population_train = model.predict(X_train)
population_test = model.predict(X_test)

population_train.set_portfolio_params(tag="Train")
population_test.set_portfolio_params(tag="Test")

population = population_train + population_test

population.plot_measures(
    x=RiskMeasure.CDAR,
    y=RatioMeasure.ANNUALIZED_SHARPE_RATIO,
    color_scale=RatioMeasure.ANNUALIZED_SHARPE_RATIO,
    hover_measures=[RiskMeasure.MAX_DRAWDOWN, RatioMeasure.ANNUALIZED_SORTINO_RATIO],
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="pareto-optimal-surface"></a>

## Pareto Optimal Surface

Instead of analyzing the Sharpe-CDaR efficient frontier, we can analyze the
Mean-Variance-CDaR Pareto-optimal surface:

```Python
variance_upper = population_train.max_measure(PerfMeasure.MEAN).variance
x = np.linspace(start=0.00012, stop=variance_upper, num=10)
y = np.linspace(start=0.11, stop=0.17, num=10)
x, y = map(np.ravel, np.meshgrid(x, y))

model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RETURN,
    max_variance=x,
    max_cdar=y,
    raise_on_failure=False,
)
model.fit(X_train)

population_train = model.predict(X_train)

fig = population_train.plot_measures(
    x=RiskMeasure.ANNUALIZED_VARIANCE,
    y=RiskMeasure.CDAR,
    z=PerfMeasure.ANNUALIZED_MEAN,
    to_surface=True,
)
fig.update_layout(scene_camera=dict(eye=dict(x=-2, y=-0.5, z=1)))
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>
```none
/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py:1247: UserWarning: Solution may be inaccurate. Try changing the solver params or the scale. For more details, set `solver_params=dict(verbose=True)`
  weights, problem_values = _solve(
/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py:1247: UserWarning: Solution may be inaccurate. Try changing the solver params or the scale. For more details, set `solver_params=dict(verbose=True)`
  weights, problem_values = _solve(
/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py:1247: UserWarning: Solution may be inaccurate. Try changing the solver params or the scale. For more details, set `solver_params=dict(verbose=True)`
  weights, problem_values = _solve(
/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py:1247: UserWarning: Solution may be inaccurate. Try changing the solver params or the scale. For more details, set `solver_params=dict(verbose=True)`
  weights, problem_values = _solve(
/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py:1247: UserWarning: Solution may be inaccurate. Try changing the solver params or the scale. For more details, set `solver_params=dict(verbose=True)`
  weights, problem_values = _solve(
/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py:1247: UserWarning: Solution may be inaccurate. Try changing the solver params or the scale. For more details, set `solver_params=dict(verbose=True)`
  weights, problem_values = _solve(
/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py:1247: UserWarning: Solution may be inaccurate. Try changing the solver params or the scale. For more details, set `solver_params=dict(verbose=True)`
  weights, problem_values = _solve(
/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py:1247: UserWarning: Solution may be inaccurate. Try changing the solver params or the scale. For more details, set `solver_params=dict(verbose=True)`
  weights, problem_values = _solve(
```

<br/>

Let’s plot the composition of the portfolios:

```Python
population_train.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s compare the average and standard-deviation of the Sharpe Ratio and CDaR Ratio of
the portfolios on the training set versus the test set:

Train:

```Python
print(population_train.measures_mean(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO))
print(population_train.measures_std(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO))
```

```none
1.362741656336506
0.09606306762254788
```

Test:

```Python
print(population_test.measures_mean(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO))
print(population_test.measures_std(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO))
```

```none
0.9038068241543424
0.06763765525558574
```

**Total running time of the script:** (0 minutes 15.958 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-4-mean-variance-cdar-py"></a>

# auto_examples/mean_risk/plot_5_weight_constraints.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-5-weight-constraints-py"></a>

<a id="weight-constraints"></a>

# Weight Constraints

This tutorial shows how to incorporate weight constraints into the
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

We will show how to use the below parameters:
: * min_weights
  * max_weights
  * budget
  * min_budget
  * max_budget
  * max_short
  * max_long
  * linear_constraints
  * groups
  * left_inequality
  * right_inequality

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 1990-01-02 up to 2022-12-28.
We select only 3 assets to make the example more readable, which are Apple (AAPL),
General Electric (GE) and JPMorgan (JPM):

```Python
import numpy as np
from plotly.io import show

from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
prices = prices[["AAPL", "GE", "JPM"]]

X = prices_to_returns(prices)
```

<a id="model"></a>

## Model

In this tutorial, we will use a Minimum Variance model.
By default,  [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) is long only (`min_weights=0`)
and fully invested (`budget=1`). In other terms, all weights are positive and sum to
one.

```Python
model = MeanRisk()
model.fit(X)
print(sum(model.weights_))
model.weights_
```

```none
1.0

array([0.22768876, 0.56566507, 0.20664617])
```

<a id="budget"></a>

## Budget

The budget is the sum of long positions and short positions (sum of all weights).
It can be `None` or a float. `None` means that there are no budget constraints.
The default is `1.0` (fully invested).

Examples:

> * budget = 1    -> fully invested portfolio
> * budget = 0    -> market neutral portfolio
> * budget = None -> no constraints on the sum of weights

```Python
model = MeanRisk(budget=0.5)
model.fit(X)
print(sum(model.weights_))
model.weights_
```

```none
0.5

array([0.11391513, 0.28246101, 0.10362386])
```

You can also set a constraint on the minimum and maximum budget using `min_budget`
and `max_budget`, which are the lower and upper bounds of the sum of long and short
positions (sum of all weights). The default is `None`. If provided, you must set
`budget=None`.

```Python
model = MeanRisk(budget=None, min_budget=0.3, max_budget=0.5)
model.fit(X)
print(sum(model.weights_))
model.weights_
```

```none
0.300000346179165

array([0.06832987, 0.16956647, 0.06210401])
```

<a id="lower-and-upper-bounds-on-weights"></a>

## Lower and Upper Bounds on Weights

The weights lower and upper bounds are controlled by the parameters `min_weights` and
`max_weights` respectively.
You can provide `None`, a float, an array-like or a dictionary.
`None` is equivalent to `-np.Inf` (no lower bounds).
If a float is provided, it is applied to each asset.
If a dictionary is provided, its (key/value) pair must be the (asset name/asset
weight bound) and the input `X` of the `fit` method must be a DataFrame with the
assets names in columns.
The default values are `min_weights=0.0` (no short selling) and `max_weights=1.0`
(each asset is below 100%). When using a dictionary, you don’t have to provide
constraints for all assets. If not provided, the default values (0.0 for min_weights
and 1.0 for max_weights) will be assigned to the assets not specified in the
dictionary.

#### NOTE
When incorporating a pre-selection transformer into a Pipeline, using a list for
weight constraints is not feasible, as we don’t know in advance which assets will
be selected by the pre-selection process. This is where the dictionary proves
useful.

Example:
: * min_weights = 0                     -> long only portfolio (no short selling).
  * min_weights = None                  -> no lower bound (same as -np.Inf).
  * min_weights = -2                    -> each weight must be above -200%.
  * min_weights = [0, -2, 0.5]          -> “AAPL”, “GE” and “JPM” must be above 0%, -200% and 50% respectively.
  * min_weights = {“AAPL”: 0, “GE”: -2} -> “AAPL”, “GE” and “JPM”  must be above 0%, -200% and 0% (default) respectively.
  * max_weights = 0                     -> no long position (short only portfolio).
  * max_weights = None                  -> no upper bound (same as +np.Inf).
  * max_weights = 2                     -> each weight must be below 200%.
  * max_weights = [1, 2, -0.5]          -> “AAPL”, “GE” and “JPM”  must be below 100%, 200% and -50% respectively.
  * max_weights = {“AAPL”: 1, “GE”: 2}  -> “AAPL”, “GE” and “JPM”  must be below 100%, 200% and 100% (default).

Let’s create a model that allows short positions with a budget of -100%:

```Python
model = MeanRisk(budget=-1, min_weights=-1)
model.fit(X)
print(sum(model.weights_))
model.weights_
```

```none
-0.9999999999999999

array([-0.22770271, -0.56559255, -0.20670474])
```

Let’s add weight constraints on “AAPL”, “GE” and “JPM” to be above 0%, 50% and 10%
respectively:

```Python
model = MeanRisk(min_weights=[0, 0.5, 0.1])
model.fit(X)
print(sum(model.weights_))
model.weights_
```

```none
1.0

array([0.22788246, 0.56548525, 0.20663228])
```

Let’s plot the composition:

```Python
portfolio = model.predict(X)
fig = portfolio.plot_composition()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Let’s create the same model as above but using partial dictionary:

```Python
model = MeanRisk(min_weights={"GE": 0.5, "JPM": 0.1})
model.fit(X)
print(sum(model.weights_))
model.weights_
```

```none
1.0

array([0.22788246, 0.56548525, 0.20663228])
```

Let’s create a model with a leverage of 3 and every weights below 150%:

```Python
model = MeanRisk(budget=3, max_weights=1.5)
model.fit(X)
print(sum(model.weights_))
model.weights_
```

```none
3.000000000000002

array([0.74197781, 1.49999867, 0.75802352])
```

<a id="short-and-long-position-constraints"></a>

## Short and Long Position Constraints

Constraints on the upper bound for short and long positions can be set using
`max_short` and `max_long`. The short position is defined as the sum of negative
weights (in absolute term) and the long position as the sum of positive weights.

Let’s create a fully invested long-short portfolio model with a total short position
less than 50%:

```Python
model = MeanRisk(min_weights=-1, max_short=0.5)
model.fit(X)
print(sum(model.weights_))
model.weights_
```

```none
1.0

array([0.22770146, 0.56558315, 0.20671539])
```

<a id="group-and-linear-constraints"></a>

## Group and Linear Constraints

We can assign groups to each asset using the `groups` parameter and set
constraints on these groups using the `linear_constraint` parameter.
The `groups` parameter can be a 2D array-like or a dictionary. If a dictionary is
provided, its (key/value)  pair must be the (asset name/asset groups).
You can reference these groups and/or the asset names in `linear_constraint`, which
is a list of strings following the below patterns:

> * “2.5 \* ref1 + 0.10 \* ref2 + 0.0013 <= 2.5 \* ref3”
> * “ref1 >= 2.9 \* ref2”
> * “ref1 == ref2”
> * “ref1 >= ref1”

Let’s create a model with groups constraints on “industry sector” and
“capitalization”:

```Python
groups = {
    "AAPL": ["Technology", "Mega Cap"],
    "GE": ["Industrial", "Big Cap"],
    "JPM": ["Financial", "Big Cap"],
}
# You can also provide a 2D array-like:
# groups = [["Technology", "Industrial", "Financial"], ["Mega Cap", "Big Cap", "Big Cap"]]
linear_constraints = [
    "Technology + 1.5 * Industrial <= 2 * Financial",  # First group
    "Mega Cap >= 0.75 * Big Cap",  # Second group
    "Technology >= Big Cap",  # Mix of first and second groups
    "Mega Cap >= 2 * JPM",  # Mix of groups and assets
]
# Note that only the first constraint would be sufficient in that case.

model = MeanRisk(groups=groups, linear_constraints=linear_constraints)
model.fit(X)
model.weights_
```

```none
array([6.66666667e-01, 1.17341871e-11, 3.33333333e-01])
```

<a id="left-and-right-inequalities"></a>

## Left and Right Inequalities

Finally, you can also directly provide the matrix $A$ and the vector
$b$ of the linear constraint $A \cdot w \leq b$:

```Python
left_inequality = np.array(
    [[1.0, 1.5, -2.0], [-1.0, 0.75, 0.75], [-1.0, 1.0, 1.0], [-1.0, -0.0, 2.0]]
)
right_inequality = np.array([0.0, 0.0, 0.0, 0.0])

model = MeanRisk(left_inequality=left_inequality, right_inequality=right_inequality)
model.fit(X)
model.weights_
```

```none
array([6.66666667e-01, 1.17341871e-11, 3.33333333e-01])
```

**Total running time of the script:** (0 minutes 0.408 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-5-weight-constraints-py"></a>

# auto_examples/mean_risk/plot_6_transaction_costs.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-6-transaction-costs-py"></a>

<a id="transaction-costs"></a>

# Transaction Costs

This tutorial shows how to incorporate transaction costs (TC) into the
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

TC are fixed costs incurred when buying or selling an asset.

By using the `transaction_costs` parameter, you can add linear TC to the optimization
problem:

$$
total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|

$$

with $c_{i}$ the TC of asset i, $w_{i}$ its weight and $w\_prev_{i}$
its previous weight (defined in `previous_weights`).
The float $total\_cost$ is impacting the portfolio expected return in the
optimization:

$$
expected\_return = \mu^{T} \cdot w - total\_cost

$$

with $\mu$ the vector of expected asset returns and $w$ the vector of
asset weights.

the `transaction_costs` parameter can be a float, a dictionary or an array-like of
shape `(n_assets, )`. If a float is provided, it is applied to each asset.
If a dictionary is provided, its (key/value) pair must be the (asset name/asset TC) and
the input `X` of the `fit` method must be a DataFrame with the assets names in columns.
The default is 0.0 (no transaction costs).

#### WARNING
According to the above formula, the periodicity of the transaction costs
must match the periodicity of $\mu$. For example, if the input
`X` is composed of **daily** returns, the `transaction_costs` need to be
expressed as **daily** costs.

This means that fixed transaction costs must be converted to an equivalent per-period
cost. The reason is that a transaction cost is paid once per rebalancing while a
position earns its expected return on every period it is held. To convert the
one-off cost, you need the notion of expected investment duration. This is crucial
since the optimization problem itself has no notion of investment duration.

For example, let’s assume that asset A has an expected daily return of 0.01%
with a TC of 1% and asset B has an expected daily return of 0.005% with no TC.
Let’s assume both assets have the same volatility and a correlation of 1.0.
If the investment duration is only one month, we should allocate all the weights to
asset B. However, if the investment duration is one year, we should allocate all the
weights to asset A.

Example:
: * Duration = 1 months (21 business days):
    : * 1 month expected return A ~= -0.8%
      * 1 month expected return B ~= 0.1%
  * Duration = 1 year (252 business days):
    : * 1 year expected return A ~= 1.5%
      * 1 year expected return B ~= 1.3%

So in order to take that duration into account, you should divide the fix TC by the
expected investment duration. See
[Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention) for the general convention on
expressing optimization inputs in the periodicity of `X`.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 1990-01-02 up to 2022-12-28.
We select only 3 assets to make the example more readable, which are Apple (AAPL),
General Electric (GE) and JPMorgan (JPM):

```Python
import numpy as np
from plotly.io import show

from skfolio import MultiPeriodPortfolio, Population, Portfolio
from skfolio.datasets import load_sp500_dataset
from skfolio.model_selection import WalkForward, cross_val_predict
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
prices = prices[["AAPL", "GE", "JPM"]]

X = prices_to_returns(prices)
```

<a id="model"></a>

## Model

In this tutorial, we will use the Maximum Mean-Variance Utility model with a risk
aversion of 1.0:

```Python
model = MeanRisk(objective_function=ObjectiveFunction.MAXIMIZE_UTILITY)
model.fit(X)
model.weights_
```

```none
array([6.17733231e-01, 3.78774146e-09, 3.82266765e-01])
```

<a id="transaction-cost"></a>

## Transaction Cost

Let’s assume we have the below TC:
: * Apple: 1%
  * General Electric: 0.50%
  * JPMorgan: 0.20%

and an investment duration of one month (21 business days):

```Python
transaction_costs = {"AAPL": 0.01 / 21, "GE": 0.005 / 21, "JPM": 0.002 / 21}
# Same as transaction_costs = np.array([0.01, 0.005, 0.002]) / 21
```

First, we assume that there is no previous position:

```Python
model_tc = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_UTILITY,
    transaction_costs=transaction_costs,
)
model_tc.fit(X)
model_tc.weights_
```

```none
array([4.11868007e-01, 1.40979941e-07, 5.88131852e-01])
```

The higher TC of Apple induced a change of weights toward JPMorgan:

```Python
model_tc.weights_ - model.weights_
```

```none
array([-2.05865225e-01,  1.37192199e-07,  2.05865087e-01])
```

Now, let’s assume that the previous position was equal-weighted:

```Python
model_tc2 = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_UTILITY,
    transaction_costs=transaction_costs,
    previous_weights=np.ones(3) / 3,
)
model_tc2.fit(X)
model_tc2.weights_
```

```none
array([0.33333336, 0.3333332 , 0.33333345])
```

Notice that the weight of General Electric becomes non-negligible due to the cost of
rebalancing the position:

```Python
model_tc2.weights_ - model.weights_
```

```none
array([-0.28439988,  0.3333332 , -0.04893332])
```

<a id="multi-period-portfolio"></a>

## Multi-period portfolio

Let’s assume that we want to rebalance our portfolio every 60 days by re-fitting the
model on the latest 60 days. We test the impact of TC using Walk Forward Analysis:

```Python
holding_period = 60
fitting_period = 60
cv = WalkForward(train_size=fitting_period, test_size=holding_period)
```

As explained above, we transform the fix TC into a daily cost by dividing the TC by
the expected investment duration:

```Python
transaction_costs = np.array([0.01, 0.005, 0.002]) / holding_period
```

First, we train and test the model without TC:

```Python
model = MeanRisk(objective_function=ObjectiveFunction.MAXIMIZE_UTILITY)
# pred1 is a MultiPeriodPortfolio
pred1 = cross_val_predict(model, X, cv=cv, n_jobs=-1)
pred1.name = "pred1"
```

Then, we train the model without TC and test it with TC. The model trained without TC
is the same as above so we can retrieve the results and simply update the prediction
with the TC:

```Python
pred2 = MultiPeriodPortfolio(name="pred2")
previous_weights = None
for portfolio in pred1:
    new_portfolio = Portfolio(
        X=portfolio.X,
        weights=portfolio.weights,
        previous_weights=previous_weights,
        transaction_costs=transaction_costs,
    )
    previous_weights = portfolio.weights
    pred2.append(new_portfolio)
```

Finally, we train and test the model with TC.
`cross_val_predict` automatically handles the `previous_weights` dependency
between consecutive folds by propagating weights from one fold to the next.

```Python
model.set_params(transaction_costs=transaction_costs)
pred3 = cross_val_predict(model, X, cv=cv)
pred3.name = "pred3"
```

We visualize the results by plotting the cumulative returns of the successive test
periods:

```Python
population = Population([pred1, pred2, pred3])
fig = population.plot_cumulative_returns()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

If we exclude the unrealistic prediction without TC, we notice that the model
**fitted with TC** outperforms the model **fitted without TC**.

**Total running time of the script:** (0 minutes 8.035 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-6-transaction-costs-py"></a>

# auto_examples/mean_risk/plot_7_management_fees.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-7-management-fees-py"></a>

<a id="management-fees"></a>

# Management Fees

This tutorial shows how to incorporate management fees (MF) into the
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

By using the `management_fees` parameter, you can add linear MF to the optimization
problem:

$$
total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}

$$

with $f_{i}$ the management fee of asset i and $w_{i}$ its weight.
The float $total\_fee$ is impacting the portfolio expected return in the
optimization:

$$
expected\_return = \mu^{T} \cdot w - total\_fee

$$

with $\mu$ the vector of expected asset returns and $w$ the vector of
asset weights.

The `management_fees` parameter can be a float, a dictionary or an array-like of
shape `(n_assets, )`. If a float is provided, it is applied to each asset.
If a dictionary is provided, its (key/value) pair must be the (asset name/asset MF) and
the input `X` of the `fit` method must be a DataFrame with the assets names in
columns. The default is 0.0 (no management fees).

#### NOTE
Another approach is to directly impact the MF to the input `X` in order to express
the returns net of fee. However, when estimating the $\mu$ parameter using,
for example, Shrinkage estimators, this approach would mix a deterministic amount
with an uncertain one leading to unwanted bias in the management fees.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 1990-01-02 up to 2022-12-28.
We select only 3 assets to make the example more readable, which are Apple (AAPL),
General Electric (GE) and JPMorgan (JPM).

```Python
import numpy as np
from plotly.io import show

from skfolio import Population
from skfolio.datasets import load_sp500_dataset
from skfolio.model_selection import WalkForward, cross_val_predict
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
prices = prices[["AAPL", "GE", "JPM"]]

X = prices_to_returns(prices)
```

<a id="model"></a>

## Model

In this tutorial, we will use the Maximum Mean-Variance Utility model with a risk
aversion of 1.0:

```Python
model = MeanRisk(objective_function=ObjectiveFunction.MAXIMIZE_UTILITY)
model.fit(X)
model.weights_
```

```none
array([6.17733231e-01, 3.78774146e-09, 3.82266765e-01])
```

<a id="id1"></a>

## Management Fees

Management fees are usually used in assets under management but for this example we
will assume that they also apply to the stocks below:

> * Apple: 3% p.a.
> * General Electric: 6% p.a.
> * JPMorgan: 1% p.a.

The MF are expressed per annum, so we need to convert them to daily MF.
We suppose 252 trading days in a year:

```Python
management_fees = {"AAPL": 0.03 / 252, "GE": 0.06 / 252, "JPM": 0.01 / 252}
# Same as management_fees = np.array([0.03, 0.06, 0.01]) / 252

model_mf = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_UTILITY,
    management_fees=management_fees,
)
model_mf.fit(X)
model_mf.weights_
```

```none
array([5.74787861e-01, 1.43028045e-08, 4.25212125e-01])
```

The higher MF of Apple induced a change of weights toward JPMorgan:

```Python
model_mf.weights_ - model.weights_
```

```none
array([-4.29453703e-02,  1.05150631e-08,  4.29453598e-02])
```

<a id="multi-period-portfolio"></a>

## Multi-period portfolio

Let’s assume that we want to rebalance our portfolio every 60 days by re-fitting the
model on the latest 60 days. We test the impact of MF using Walk Forward Analysis:

```Python
holding_period = 60
fitting_period = 60
cv = WalkForward(train_size=fitting_period, test_size=holding_period)
```

As explained above, we transform the yearly MF into a daily MF:

```Python
management_fees = np.array([0.03, 0.06, 0.01]) / 252
```

First, we train the model without MF and test it with MF.
Note that `portfolio_params` are parameters passed to the Portfolio during `predict`
and **not** during `fit`:

```Python
model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_UTILITY,
    portfolio_params=dict(management_fees=management_fees),
)
# pred1 is a MultiPeriodPortfolio
pred1 = cross_val_predict(model, X, cv=cv, n_jobs=-1)
pred1.name = "pred1"
```

Then, we train and test the model with MF:

```Python
model.set_params(management_fees=management_fees)
pred2 = cross_val_predict(model, X, cv=cv, n_jobs=-1)
pred2.name = "pred2"
```

We visualize the results by plotting the cumulative returns of the successive test
periods:

```Python
population = Population([pred1, pred2])
fig = population.plot_cumulative_returns()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

We notice that the model **fitted with MF** outperform the model **fitted without
MF**.

**Total running time of the script:** (0 minutes 3.625 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-7-management-fees-py"></a>

# auto_examples/mean_risk/plot_8_regularization.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-8-regularization-py"></a>

<a id="l1-and-l2-regularization"></a>

# L1 and L2 Regularization

This tutorial shows how to incorporate regularization into the
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

Regularization tends to increase robustness and out-of-sample stability.

The `l1_coef` parameter is used to penalize the objective function by the L1 norm:

$$
l1\_coef \times \Vert w \Vert_{1} = l1\_coef \times \sum_{i=1}^{N} |w_{i}|

$$

and the `l2_coef` parameter is used to penalize the objective function by the L2 norm:

$$
l2\_coef \times \Vert w \Vert_{2}^{2} = l2\_coef \times \sum_{i=1}^{N} w_{i}^2

$$

#### WARNING
Increasing the L1 coefficient may reduce the number of non-zero weights
(cardinality), which can reduce diversification. However, a reduction in
diversification does not necessarily equate to a reduction in robustness.

#### NOTE
Increasing the L1 coefficient has no impact if the portfolio is long only.

In this example we will use a dataset with a large number of assets and long-short
allocation to exacerbate overfitting.

First, we will analyze the impact of regularization on the entire Mean-Variance efficient
frontier and its stability from the training set to the test set. Then, we will show how
to tune the regularization coefficients using cross-validation with `GridSearchCV`.

<a id="data"></a>

## Data

We load the FTSE 100 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 64
assets from the FTSE 100 Index composition starting from 2000-01-04 up to 2023-05-31.

```Python
import numpy as np
import plotly.graph_objects as go
from plotly.io import show
from scipy.stats import loguniform
from sklearn import clone
from sklearn.model_selection import GridSearchCV, RandomizedSearchCV, train_test_split

from skfolio import PerfMeasure, Population, RatioMeasure, RiskMeasure
from skfolio.datasets import load_ftse100_dataset
from skfolio.metrics import make_scorer
from skfolio.model_selection import WalkForward, cross_val_predict
from skfolio.optimization import EqualWeighted, MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns

prices = load_ftse100_dataset()
X = prices_to_returns(prices)

X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="efficient-frontier"></a>

## Efficient Frontier

First, we create a Mean-Variance model to estimate the efficient frontier without
regularization. We constrain the volatility to be below 30% p.a.

```Python
model = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    min_weights=-1,
    max_variance=0.3**2 / 252,
    efficient_frontier_size=30,
    portfolio_params=dict(name="Mean-Variance", tag="No Regularization"),
)
model.fit(X_train)
model.weights_.shape
```

```none
/home/runner/work/skfolio/skfolio/src/skfolio/optimization/convex/_base.py:1247: UserWarning: Solution may be inaccurate. Try changing the solver params or the scale. For more details, set `solver_params=dict(verbose=True)`
  weights, problem_values = _solve(

(30, 64)
```

Now we create the two regularized models:

```Python
model_l1 = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    min_weights=-1,
    max_variance=0.3**2 / 252,
    efficient_frontier_size=30,
    l1_coef=0.001,
    portfolio_params=dict(name="Mean-Variance", tag="L1 Regularization"),
)
model_l1.fit(X_train)

model_l2 = clone(model_l1)
model_l2.set_params(
    l1_coef=0,
    l2_coef=0.001,
    portfolio_params=dict(name="Mean-Variance", tag="L2 Regularization"),
)
model_l2.fit(X_train)
model_l2.weights_.shape
```

```none
(30, 64)
```

Let’s plot the efficient frontiers on the training set:

```Python
population_train = (
    model.predict(X_train) + model_l1.predict(X_train) + model_l2.predict(X_train)
)

population_train.plot_measures(
    x=RiskMeasure.ANNUALIZED_STANDARD_DEVIATION,
    y=PerfMeasure.ANNUALIZED_MEAN,
    color_scale=RatioMeasure.ANNUALIZED_SHARPE_RATIO,
    hover_measures=[RiskMeasure.MAX_DRAWDOWN, RatioMeasure.ANNUALIZED_SORTINO_RATIO],
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="prediction"></a>

## Prediction

The parameter `efficient_frontier_size=30` means that when we called the `fit` method,
each model ran 30 optimizations along the efficient frontier. Therefore, the `predict`
method will return a [`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population) composed of 30
[`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio):

```Python
population_test = (
    model.predict(X_test) + model_l1.predict(X_test) + model_l2.predict(X_test)
)

for tag in ["No Regularization", "L1 Regularization"]:
    print("=================")
    print(tag)
    print("=================")
    print(
        "Avg Sharpe Ratio Train:"
        f" {population_train.filter(tags=tag).measures_mean(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO):0.2f}"
    )
    print(
        "Avg Sharpe Ratio Test:"
        f" {population_test.filter(tags=tag).measures_mean(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO):0.2f}"
    )
    print(
        "Avg non-zeros assets:"
        f" {np.mean([len(ptf.nonzero_assets) for ptf in population_train.filter(tags=tag)]):0.2f}"
    )
    print("\n")

population_test.plot_measures(
    x=RiskMeasure.ANNUALIZED_STANDARD_DEVIATION,
    y=PerfMeasure.ANNUALIZED_MEAN,
    color_scale=RatioMeasure.ANNUALIZED_SHARPE_RATIO,
    hover_measures=[RiskMeasure.MAX_DRAWDOWN, RatioMeasure.ANNUALIZED_SORTINO_RATIO],
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>
```none
=================
No Regularization
=================
Avg Sharpe Ratio Train: 1.93
Avg Sharpe Ratio Test: 0.43
Avg non-zeros assets: 64.00

=================
L1 Regularization
=================
Avg Sharpe Ratio Train: 1.37
Avg Sharpe Ratio Test: 0.73
Avg non-zeros assets: 13.57
```

[plotly figure stripped from llms output]
<br />
<br />

In this example we can clearly see that L1 regularization reduced the number of assets
(from 64 down to 14) and made the model more robust: the portfolios without
regularization have a higher Sharpe on the train set and a lower Sharpe on the test
set compared to the portfolios with regularization.

<a id="hyper-parameter-tuning"></a>

## Hyper-parameter Tuning

In this section, we consider a 3 months rolling (60 business days) long-short
allocation fitted on the preceding year of data (252 business days) that maximizes the
return under a volatility constraint of 30% p.a.

We use `GridSearchCV` to select the optimal L1 and L2 regularization coefficients on
the training set using cross-validation that achieves the highest
mean test score. We use the default score, which is the Sharpe ratio.
Finally, we evaluate the model on the test set and compare it with the equal-weighted
benchmark and a reference model without regularization:

```Python
ref_model = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    objective_function=ObjectiveFunction.MAXIMIZE_RETURN,
    max_variance=0.3**2 / 252,
    min_weights=-1,
)

cv = WalkForward(train_size=252, test_size=60)

grid_search = GridSearchCV(
    estimator=ref_model,
    cv=cv,
    n_jobs=-1,
    param_grid={
        "l1_coef": [0.001, 0.01, 0.1],
        "l2_coef": [0.001, 0.01, 0.1],
    },
)
grid_search.fit(X_train)
best_model = grid_search.best_estimator_
print(best_model)
```

```none
MeanRisk(l1_coef=0.1, l2_coef=0.01, max_variance=0.00035714285714285714,
         min_weights=-1, objective_function=MAXIMIZE_RETURN)
```

The optimal parameters among the above 3x3 grid are 0.01 for the L1 coefficient
and the L2 coefficient.
These parameters are the ones that achieved the highest mean out-of-sample Sharpe
Ratio. Note that the score can be changed to another measure or function using the
`scoring` parameter.

For continuous parameters, such as L1 and L2 above, a better approach is to use
`RandomizedSearchCV` and specify a continuous distribution to take full advantage of
the randomization.

A continuous log-uniform random variable is the continuous version of a log-spaced
parameter. For example, to specify the equivalent of the L1 parameter from above,
`loguniform(1e-3, 1e-1)` can be used instead of `[0.001, 0.01, 0.1]`.

Mirroring the example above in grid search, we can specify a continuous random
variable that is log-uniformly distributed between 1e-3 and 1e-1:

```Python
randomized_search = RandomizedSearchCV(
    estimator=ref_model,
    cv=cv,
    n_jobs=-1,
    param_distributions={
        "l2_coef": loguniform(1e-3, 1e-1),
    },
    n_iter=30,
    random_state=0,
    return_train_score=True,
    scoring=make_scorer(RatioMeasure.ANNUALIZED_SHARPE_RATIO),
)
randomized_search.fit(X_train)
best_model_rd = randomized_search.best_estimator_
print(best_model_rd)
```

```none
MeanRisk(l2_coef=np.float64(0.02693883019285411),
         max_variance=0.00035714285714285714, min_weights=-1,
         objective_function=MAXIMIZE_RETURN)
```

Let’s plot both the average in-sample and out-of-sample scores (annualized Sharpe
ratio) as a function of `l2_coef`:

```Python
cv_results = randomized_search.cv_results_
x = np.asarray(cv_results["param_l2_coef"]).astype(float)
sort_idx = np.argsort(x)
y_train_mean = cv_results["mean_train_score"][sort_idx]
y_train_std = cv_results["std_train_score"][sort_idx]
y_test_mean = cv_results["mean_test_score"][sort_idx]
y_test_std = cv_results["std_test_score"][sort_idx]
x = x[sort_idx]

fig = go.Figure(
    [
        go.Scatter(
            x=x,
            y=y_train_mean,
            name="Train",
            mode="lines",
            line=dict(color="rgb(31, 119, 180)"),
        ),
        go.Scatter(
            x=x,
            y=y_train_mean + y_train_std,
            mode="lines",
            line=dict(width=0),
            showlegend=False,
        ),
        go.Scatter(
            x=x,
            y=y_train_mean - y_train_std,
            mode="lines",
            line=dict(width=0),
            showlegend=False,
            fillcolor="rgba(31, 119, 180,0.15)",
            fill="tonexty",
        ),
        go.Scatter(
            x=x,
            y=y_test_mean,
            name="Test",
            mode="lines",
            line=dict(color="rgb(255,165,0)"),
        ),
        go.Scatter(
            x=x,
            y=y_test_mean + y_test_std,
            mode="lines",
            line=dict(width=0),
            showlegend=False,
        ),
        go.Scatter(
            x=x,
            y=y_test_mean - y_test_std,
            line=dict(width=0),
            mode="lines",
            fillcolor="rgba(255,165,0, 0.15)",
            fill="tonexty",
            showlegend=False,
        ),
    ]
)
fig.add_vline(
    x=randomized_search.best_params_["l2_coef"],
    line_width=2,
    line_dash="dash",
    line_color="green",
)
fig.update_layout(
    title="Train/Test score",
    xaxis_title="L2 Coef",
    yaxis_title="Annualized Sharpe Ratio",
)
fig.update_yaxes(tickformat=".2f")
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

The dashed line identifies the L2 coefficient with the highest mean out-of-sample
Sharpe ratio. The gap between the train and test scores without regularization is a
clear indication of overfitting.

Now, we analyze all three models on the test set. By using `cross_val_predict` with
`WalkForward`, we are able to compute efficiently the `MultiPeriodPortfolio`
composed of 60 days rolling portfolios fitted on the preceding 252 days:

```Python
benchmark = EqualWeighted()
pred_bench = cross_val_predict(benchmark, X_test, cv=cv)
pred_bench.name = "Benchmark"

pred_no_reg = cross_val_predict(ref_model, X_test, cv=cv)
pred_no_reg.name = "No Regularization"

pred_reg = cross_val_predict(best_model, X_test, cv=cv, n_jobs=-1)
pred_reg.name = "Regularization"

population = Population([pred_no_reg, pred_reg, pred_bench])
population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

From the plot and the below summary, we can see that the un-regularized model is
overfitted and perform poorly on the test set. Its annualized volatility is 54%, which
is significantly above the model upper-bound of 30% and its Sharpe Ratio is 0.32 which
is the lowest of all models.

```Python
population.summary()
```

[plotly figure stripped from llms output]
<br />
<br />

**Total running time of the script:** (0 minutes 41.091 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-8-regularization-py"></a>

# auto_examples/mean_risk/plot_9_uncertainty_set.html.md

<a id="sphx-glr-auto-examples-mean-risk-plot-9-uncertainty-set-py"></a>

<a id="uncertainty-set"></a>

# Uncertainty Set

This tutorial shows how to incorporate expected returns uncertainty sets into the
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization.

By using the [Mu Uncertainty set estimator](https://skfolio.org/user_guide/uncertainty_set.html.md#uncertainty-set-estimator),
expected asset returns are modelled with an ellipsoidal uncertainty set.
This approach, known as worst-case optimization, falls under the umbrella of robust
optimization. It reduces the instability that arises from the estimation errors of the
expected returns.

The worst-case portfolio expected return is:

> $$
> w^T\hat{\mu} - \kappa_{\mu}\lVert S_{\mu}^\frac{1}{2}w\rVert_{2}

> $$

with $\kappa$ the size of the ellipsoid (confidence region) and $S$ its
shape.

In this example, we will use a Mean-CVaR model with an
[`EmpiricalMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalMuUncertaintySet) estimator.

Note that other uncertainty sets can be used, for example:
[`BootstrapMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapMuUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapMuUncertaintySet).

<a id="data"></a>

## Data

We load the FTSE 100 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 64
assets from the FTSE 100 Index composition starting from 2000-01-04 up to 2023-05-31:

```Python
import numpy as np
import plotly.graph_objects as go
from plotly.io import show
from scipy.stats import uniform
from sklearn import clone
from sklearn.model_selection import GridSearchCV, RandomizedSearchCV, train_test_split

from skfolio import PerfMeasure, Population, RatioMeasure, RiskMeasure
from skfolio.datasets import load_ftse100_dataset
from skfolio.metrics import make_scorer
from skfolio.model_selection import WalkForward, cross_val_predict
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns
from skfolio.uncertainty_set import EmpiricalMuUncertaintySet

prices = load_ftse100_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="efficient-frontier"></a>

## Efficient Frontier

First, we create a Mean-CVaR model to estimate the efficient frontier without
uncertainty set. We constrain the CVaR at 95% to be below 2% (representing the
average loss of the worst 5% daily returns over the period):

```Python
model = MeanRisk(
    risk_measure=RiskMeasure.CVAR,
    min_weights=-1,
    max_cvar=0.02,
    efficient_frontier_size=20,
    portfolio_params=dict(name="Mean-CVaR", tag="No Uncertainty Set"),
)
model.fit(X_train)
model.weights_.shape
```

```none
(20, 64)
```

Now, we create a robust (worst case) Mean-CVaR model with an uncertainty set on the
expected returns:

```Python
model_uncertainty = MeanRisk(
    risk_measure=RiskMeasure.CVAR,
    min_weights=-1,
    max_cvar=0.02,
    efficient_frontier_size=20,
    mu_uncertainty_set_estimator=EmpiricalMuUncertaintySet(confidence_level=0.60),
    portfolio_params=dict(name="Mean-CVaR", tag="Mu Uncertainty Set - 60%"),
)
model_uncertainty.fit(X_train)
model_uncertainty.weights_.shape
```

```none
(20, 64)
```

Let’s plot both efficient frontiers on the training set:

```Python
population_train = model.predict(X_train) + model_uncertainty.predict(X_train)

population_train.plot_measures(
    x=RiskMeasure.CVAR,
    y=PerfMeasure.ANNUALIZED_MEAN,
    color_scale=RatioMeasure.ANNUALIZED_SHARPE_RATIO,
    hover_measures=[RiskMeasure.MAX_DRAWDOWN, RatioMeasure.ANNUALIZED_SORTINO_RATIO],
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="hyper-parameter-tuning"></a>

## Hyper-Parameter Tuning

In this section, we consider a 3 months rolling (60 business days) long-short
allocation fitted on the preceding year of data (252 business days) that maximizes the
portfolio return under a CVaR constraint.
We will use `GridSearchCV` to select the below model parameters on the training set
using walk forward analysis with a Mean/CVaR ratio scoring.

The model parameters to tune are:

> * `max_cvar`: CVaR target (upper constraint)
> * `cvar_beta`: CVaR confidence level
> * `confidence_level`: Mu uncertainty set confidence level of the [`EmpiricalMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalMuUncertaintySet)

For embedded parameters in the `GridSearchCV`, you need to use a double underscore:
`mu_uncertainty_set_estimator__confidence_level`

```Python
model_no_uncertainty = MeanRisk(
    risk_measure=RiskMeasure.CVAR,
    objective_function=ObjectiveFunction.MAXIMIZE_RETURN,
    max_cvar=0.02,
    cvar_beta=0.9,
    min_weights=-1,
)

model_uncertainty = clone(model_no_uncertainty)
model_uncertainty.set_params(mu_uncertainty_set_estimator=EmpiricalMuUncertaintySet())

cv = WalkForward(train_size=252, test_size=60)

grid_search = GridSearchCV(
    estimator=model_uncertainty,
    cv=cv,
    n_jobs=-1,
    param_grid={
        "mu_uncertainty_set_estimator__confidence_level": [0.80, 0.90],
        "max_cvar": [0.03, 0.04, 0.05],
        "cvar_beta": [0.8, 0.9, 0.95],
    },
    scoring=make_scorer(RatioMeasure.CVAR_RATIO),
)
grid_search.fit(X_train)
best_model = grid_search.best_estimator_
print(best_model)
```

```none
MeanRisk(cvar_beta=0.9, max_cvar=0.03, min_weights=-1,
         mu_uncertainty_set_estimator=EmpiricalMuUncertaintySet(confidence_level=0.8),
         objective_function=MAXIMIZE_RETURN, risk_measure=CVaR)
```

The optimal parameters among the above 2x3x3 grid are the `max_cvar=3%`,
`cvar_beta=90%` and [`EmpiricalMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalMuUncertaintySet)
`confidence_level=80%`. These parameters are the ones that achieved the highest mean
out-of-sample Mean/CVaR ratio.

For continuous parameters, such as `confidence_level`, a better approach is to use
`RandomizedSearchCV` and specify a continuous distribution to take full advantage of
the randomization. We specify a continuous random variable that is uniformly
distributed between 0 and 1:

```Python
randomized_search = RandomizedSearchCV(
    estimator=model_uncertainty,
    cv=cv,
    n_jobs=-1,
    param_distributions={
        "mu_uncertainty_set_estimator__confidence_level": uniform(loc=0, scale=1),
    },
    n_iter=40,
    random_state=0,
    scoring=make_scorer(RatioMeasure.CVAR_RATIO),
)
randomized_search.fit(X_train)
best_model_rs = randomized_search.best_estimator_
```

The selected confidence level is 58%.

Let’s plot the average out-of-sample score (CVaR ratio) as a function of the
uncertainty set confidence level:

```Python
cv_results = randomized_search.cv_results_
x = np.asarray(
    cv_results["param_mu_uncertainty_set_estimator__confidence_level"]
).astype(float)
sort_idx = np.argsort(x)
y_test_mean = cv_results["mean_test_score"][sort_idx]
x = x[sort_idx]

fig = go.Figure(
    [
        go.Scatter(
            x=x,
            y=y_test_mean,
            name="Test",
            mode="lines",
            line=dict(color="rgb(255,165,0)"),
        ),
    ]
)
fig.add_vline(
    x=randomized_search.best_params_["mu_uncertainty_set_estimator__confidence_level"],
    line_width=2,
    line_dash="dash",
    line_color="green",
)
fig.update_layout(
    title="Test score",
    xaxis_title="Uncertainty Set Confidence Level",
    yaxis_title="CVaR Ratio",
)
fig.update_yaxes(tickformat=".3f")
fig.update_xaxes(tickformat=".0%")
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Now, we analyze all three models on the test set.
By using `cross_val_predict` with `WalkForward`, we are able to compute efficiently
the `MultiPeriodPortfolio` composed of 60 days rolling portfolios fitted on the
preceding 252 days:

```Python
pred_no_uncertainty = cross_val_predict(model_no_uncertainty, X_test, cv=cv)
pred_no_uncertainty.name = "No Uncertainty set"

pred_uncertainty = cross_val_predict(best_model, X_test, cv=cv, n_jobs=-1)
pred_uncertainty.name = "Uncertainty set - Grid Search"

pred_uncertainty_rs = cross_val_predict(best_model_rs, X_test, cv=cv, n_jobs=-1)
pred_uncertainty_rs.name = "Uncertainty set - Randomized Search"

population = Population([pred_no_uncertainty, pred_uncertainty, pred_uncertainty_rs])
population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

From the plot and the below summary, we can see that the model without uncertainty set
is overfitted and perform poorly on the test set. Its CVaR at 95% is 10% and its
Mean/CVaR ratio is 0.006 which is the lowest of all models.

```Python
population.summary()
```

[plotly figure stripped from llms output]
<br />
<br />

**Total running time of the script:** (3 minutes 16.802 seconds)

<a id="sphx-glr-download-auto-examples-mean-risk-plot-9-uncertainty-set-py"></a>

# auto_examples/metadata_routing/index.html.md

<a id="sphx-glr-auto-examples-metadata-routing"></a>

<a id="metadata-routing-examples"></a>

<a id="metadata-routing"></a>

# Metadata Routing

Examples about metadata routing.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to use metadata routing &lt;metadata_routing&gt;.">  <div class="sphx-glr-thumbnail-title">Using Implied Volatility with Metadata Routing</div>
</div>
</div>

# auto_examples/metadata_routing/plot_1_implied_volatility.html.md

<a id="sphx-glr-auto-examples-metadata-routing-plot-1-implied-volatility-py"></a>

<a id="using-implied-volatility-with-metadata-routing"></a>

# Using Implied Volatility with Metadata Routing

This tutorial shows how to use [metadata routing](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing).

We will use the [`ImpliedCovariance`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance) estimator inside
optimization models and grid search procedures to show how the implied volatility
time series can be routed.

<a id="load-datasets"></a>

## Load Datasets

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition and the implied volatility time series
of these 20 assets starting from 2010-01-04 up to 2022-12-28.

```Python
import numpy as np
import pandas as pd
import plotly.express as px
from plotly.io import show
from sklearn import set_config
from sklearn.model_selection import GridSearchCV, train_test_split

from skfolio import Population, RatioMeasure
from skfolio.datasets import load_sp500_dataset, load_sp500_implied_vol_dataset
from skfolio.metrics import make_scorer
from skfolio.model_selection import WalkForward, cross_val_predict
from skfolio.moments import (
    EmpiricalCovariance,
    GerberCovariance,
    ImpliedCovariance,
    LedoitWolf,
)
from skfolio.optimization import InverseVolatility, MeanRisk
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior

prices = load_sp500_dataset()
implied_vol = load_sp500_implied_vol_dataset()

X = prices_to_returns(prices)
X = X.loc["2010":]

implied_vol.head()
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Let’s print the average R2 per window size:

```Python
print({k: f"{np.mean(v):0.1%}" for k, v in coefs.items()})
```

```none
{10: '35.9%', 20: '36.8%', 60: '28.1%', 100: '31.4%'}
```

The highest R2 is achieved for a window size of 20 observations.

<a id="inverse-volatility"></a>

## Inverse Volatility

To use the `ImpliedCovariance` estimator inside a meta-estimator such as the
`InverseVolatility`, you must enable metadata routing with `set_config` and
specify where to route the implied vol using `set_fit_request` as shown below:

```Python
set_config(enable_metadata_routing=True)

model = InverseVolatility(
    prior_estimator=EmpiricalPrior(
        covariance_estimator=ImpliedCovariance().set_fit_request(implied_vol=True)
    )
)
```

Then you can pass the implied volatility to the `fit` method of the meta-estimator:

```Python
model.fit(X, implied_vol=implied_vol)
print(model.weights_)
```

```none
[0.03629576 0.02554287 0.04135536 0.02979163 0.04207543 0.03703667
 0.04592872 0.08520002 0.04462864 0.0739193  0.04745674 0.06701373
 0.03752756 0.07489027 0.05358558 0.07275256 0.02274707 0.05618856
 0.06368034 0.04238321]
```

<a id="cross-validation"></a>

## Cross Validation

In this section, we show how to use metadata routing with `cross_val_predict`.
First, we create a `WalkForward` cross-validator to rebalance our portfolio every 20
business days by re-fitting the model on the previous 400 business days (~ 1.5 years):

```Python
cv = WalkForward(train_size=400, test_size=20)
```

We use the model created above and pass the implied volatility in `params`:

```Python
pred_model = cross_val_predict(model, X, cv=cv, params={"implied_vol": implied_vol})
pred_model.name = "Implied Vol"
```

Let’s compare the model with a benchmark using `InverseVolatility` with the default
`EmpiricalCovariance` estimator:

```Python
benchmark = InverseVolatility()
pred_bench = cross_val_predict(benchmark, X, cv=cv)
pred_bench.name = "Benchmark"
```

For easier analysis, we add both predicted portfolios into a `Population`:

```Python
population = Population([pred_bench, pred_model])
summary = population.summary()
print(summary.loc[["Annualized Standard Deviation", "Annualized Sharpe Ratio"]])
```

```none
                              Benchmark Implied Vol
Annualized Standard Deviation    16.24%      16.09%
Annualized Sharpe Ratio            1.00        1.04
```

Let’s plot the Composition and Cumulative returns:

```Python
population.plot_composition(display_sub_ptf_name=False)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

```Python
population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="hyper-parameters-tuning"></a>

## Hyper-Parameters Tuning

In this section, we show how to use metadata routing with `GridSearchCV`.
First, we split the data into a train and a test set:

```Python
X_train, X_test, implied_vol_train, implied_vol_test = train_test_split(
    X, implied_vol, test_size=1 / 2, shuffle=False
)
```

We create a Minimum Variance that uses the `ImpliedCovariance` estimator:

```Python
model = MeanRisk(
    prior_estimator=EmpiricalPrior(
        covariance_estimator=ImpliedCovariance().set_fit_request(implied_vol=True)
    )
)
```

Then, we find the hyper-parameters of the `ImpliedCovariance` estimator that
maximizes the out-of-sample Sharpe Ratio of the Minimum Variance model:

```Python
grid_search = GridSearchCV(
    estimator=model,
    param_grid={
        "prior_estimator__covariance_estimator__window_size": np.arange(5, 50, 3),
        "prior_estimator__covariance_estimator__prior_covariance_estimator": [
            LedoitWolf(),
            GerberCovariance(),
            EmpiricalCovariance(),
        ],
    },
    return_train_score=True,
    scoring=make_scorer(RatioMeasure.ANNUALIZED_SHARPE_RATIO),
    n_jobs=-1,
    cv=cv,
)
grid_search.fit(X_train, implied_vol=implied_vol_train)
gs_model = grid_search.best_estimator_
print(gs_model)
```

```none
MeanRisk(prior_estimator=EmpiricalPrior(covariance_estimator=ImpliedCovariance(annualization_factor=252.0,
                                                                               prior_covariance_estimator=GerberCovariance(),
                                                                               window_size=np.int64(17))))
```

Let’s plot the out-of-sample Sharpe Ratio as a function of the window size and
the prior covariance estimator used to compute the correlation matrix:

```Python
cv_results = grid_search.cv_results_

df = pd.DataFrame(
    {
        "Prior Cov Estimator": [
            str(x)
            for x in cv_results[
                "param_prior_estimator__covariance_estimator__prior_covariance_estimator"
            ]
        ],
        "Window Size": cv_results[
            "param_prior_estimator__covariance_estimator__window_size"
        ],
        "Test Sharpe Ratio": cv_results["mean_test_score"],
        "error": cv_results["std_test_score"] / 10,  # one tenth of std for readability
    }
)
px.line(
    df,
    x="Window Size",
    y="Test Sharpe Ratio",
    color="Prior Cov Estimator",
    error_y="error",
    title="Out-of-Sample Sharpe Ratio",
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Finally, we compare the optimal Grid Search model with a naive Minimum Variance
benchmark on the **test set**:

```Python
pred_gs_model = cross_val_predict(
    gs_model, X_test, params={"implied_vol": implied_vol_test}, cv=cv, n_jobs=-1
)
pred_gs_model.name = "GS Model"

benchmark = MeanRisk()
pred_bench = cross_val_predict(benchmark, X_test, cv=cv)
pred_bench.name = "Benchmark"

population = Population([pred_bench, pred_gs_model])
summary = population.summary()
print(summary.loc[["Annualized Standard Deviation", "Annualized Sharpe Ratio"]])
```

```none
                              Benchmark GS Model
Annualized Standard Deviation    18.12%   18.28%
Annualized Sharpe Ratio            0.59     0.67
```

```Python
population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="conclusion"></a>

## Conclusion

This was a toy example to introduce the metadata routing API.
For more information, see [Metadata Routing User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing).

**Total running time of the script:** (1 minutes 38.627 seconds)

<a id="sphx-glr-download-auto-examples-metadata-routing-plot-1-implied-volatility-py"></a>

# auto_examples/model_selection/index.html.md

<a id="sphx-glr-auto-examples-model-selection"></a>

<a id="model-selection-examples"></a>

<a id="model-selection"></a>

# Model Selection

Model selection is an integral part of portfolio construction and therefore appears in
most examples.

Tutorials using [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward):
: * [Custom Pre-selection Using Volumes](https://skfolio.org/auto_examples/pre_selection/plot_3_custom_pre_selection_volumes.html.md#sphx-glr-auto-examples-pre-selection-plot-3-custom-pre-selection-volumes-py)
  * [HRP vs HERC](https://skfolio.org/auto_examples/clustering/plot_3_hrp_vs_herc.html.md#sphx-glr-auto-examples-clustering-plot-3-hrp-vs-herc-py)
  * [L1 and L2 Regularization](https://skfolio.org/auto_examples/mean_risk/plot_8_regularization.html.md#sphx-glr-auto-examples-mean-risk-plot-8-regularization-py)
  * [NCO - Combinatorial Purged CV](https://skfolio.org/auto_examples/clustering/plot_5_nco_grid_search.html.md#sphx-glr-auto-examples-clustering-plot-5-nco-grid-search-py)
  * [Stacking Optimization](https://skfolio.org/auto_examples/ensemble/plot_1_stacking.html.md#sphx-glr-auto-examples-ensemble-plot-1-stacking-py)

Tutorials using [`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV):
: * [Drop Highly Correlated Assets](https://skfolio.org/auto_examples/pre_selection/plot_1_drop_correlated.html.md#sphx-glr-auto-examples-pre-selection-plot-1-drop-correlated-py)
  * [HRP vs HERC](https://skfolio.org/auto_examples/clustering/plot_3_hrp_vs_herc.html.md#sphx-glr-auto-examples-clustering-plot-3-hrp-vs-herc-py)
  * [NCO - Combinatorial Purged CV](https://skfolio.org/auto_examples/clustering/plot_5_nco_grid_search.html.md#sphx-glr-auto-examples-clustering-plot-5-nco-grid-search-py)

Below are dedicated Model Selection tutorials.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces MultipleRandomizedCV, which is based on the &quot;Multiple Randomized Backtests&quot; methodology of Palomar in [1]_. This cross-validation strategy performs a resampling-based evaluation by repeatedly sampling distinct asset subsets (without replacement) and contiguous time windows, then applying an inner walk-forward split to each subsample, capturing both temporal and cross-sectional variability in performance.">  <div class="sphx-glr-thumbnail-title">Multiple Randomized Cross-Validation</div>
</div>
</div>

# auto_examples/model_selection/plot_1_multiple_randomized_cv.html.md

<a id="sphx-glr-auto-examples-model-selection-plot-1-multiple-randomized-cv-py"></a>

<a id="multiple-randomized-cross-validation"></a>

# Multiple Randomized Cross-Validation

This tutorial introduces [`MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV),
which is based on the “Multiple Randomized Backtests” methodology of Palomar in <sup>[1](#id3)</sup>.
This cross-validation strategy performs a resampling-based evaluation by repeatedly
sampling **distinct** asset subsets (without replacement) and **contiguous** time
windows, then applying an inner walk-forward split to each subsample, capturing both
temporal and cross-sectional variability in performance.

In this example, we build a portfolio model composed of a preselection of top
performers, followed by a Hierarchical Equal Risk Contribution optimization with
covariance shrinkage. We split the dataset into training and test sets, tune
hyperparameters on the training set, and then evaluate the final portfolio models on
the test set using [`MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV).

<a id="data-loading"></a>

## Data Loading

We load the FTSE 100 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets), which contains daily prices
of 64 assets from the FTSE 100 index, spanning 2000-01-04 to 2023-05-31.

```Python
import scipy.stats as stats
from plotly.io import show
from sklearn import set_config
from sklearn.model_selection import RandomizedSearchCV, train_test_split
from sklearn.pipeline import Pipeline

from skfolio import Population, RatioMeasure, RiskMeasure
from skfolio.datasets import load_ftse100_dataset
from skfolio.metrics import make_scorer
from skfolio.model_selection import MultipleRandomizedCV, WalkForward, cross_val_predict
from skfolio.moments import ShrunkCovariance
from skfolio.optimization import HierarchicalEqualRiskContribution
from skfolio.pre_selection import SelectKExtremes
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior

set_config(transform_output="pandas")

prices = load_ftse100_dataset()
returns = prices_to_returns(prices)

# Sequential train-test split: 67% training, 33% testing.
# `shuffle=False` preserves chronological order, crucial for time-series data.
X_train, X_test = train_test_split(returns, test_size=0.33, shuffle=False)
```

<a id="portfolio-construction"></a>

## Portfolio Construction

We build a pipeline that first selects the top-k assets by Sharpe ratio, then
allocates weights via Hierarchical Equal Risk Contribution using a shrunk
covariance estimator.

```Python
pre_selection = SelectKExtremes(k=10, measure=RatioMeasure.SHARPE_RATIO, highest=True)

optimization = HierarchicalEqualRiskContribution(
    prior_estimator=EmpiricalPrior(
        covariance_estimator=ShrunkCovariance(shrinkage=0.5)
    ),
    risk_measure=RiskMeasure.VARIANCE,
)

model_bench = Pipeline(
    [
        ("pre_selection", pre_selection),
        ("optimization", optimization),
    ]
)
```

<a id="rebalancing-strategy"></a>

## Rebalancing Strategy

We use [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) to define a monthly rebalancing
(20 trading days), training on the prior year (252 trading days):

```Python
walk_forward = WalkForward(test_size=20, train_size=252)
```

Note that [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) also supports specific
datetime frequencies. For examples, we could use
`walk_forward = WalkForward(test_size=1, train_size=12, freq="WOM-3FRI")` to
rebalance **monthly** on the **third Friday** (WOM-3FRI), training on the prior 12
months.

<a id="hyperparameter-tuning"></a>

## Hyperparameter Tuning

Initially, the number of selected assets and the shrinkage parameter were
chosen randomly. We use `RandomizedSearchCV` to explore these parameters and
find the combination that maximizes the mean out-of-sample CVaR ratio.

```Python
random_search = RandomizedSearchCV(
    estimator=model_bench,
    cv=walk_forward,
    n_jobs=-1,
    param_distributions={
        "pre_selection__k": stats.randint(10, 30),
        "optimization__prior_estimator__covariance_estimator__shrinkage": stats.uniform(
            0, 1
        ),
    },
    n_iter=30,
    random_state=0,
    scoring=make_scorer(RatioMeasure.CVAR_RATIO),
)
random_search.fit(X_train)

# Retrieve the best estimator from the search.
model_tuned = random_search.best_estimator_
model_tuned
```

[plotly figure stripped from llms output]
<br />
<br />

Display a summary of key performance metrics.

```Python
population.summary()
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

We now compute and display the distribution of out-of-sample annualized Sharpe ratios:

```Python
population_mc.plot_distribution(
    measure_list=[RatioMeasure.ANNUALIZED_SHARPE_RATIO],
    tag_list=["Benchmark Model", "Tuned Model"],
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

```Python
for pred in [pred_bench_mc, pred_tuned_mc]:
    tag = pred[0].tag
    mean_sr = pred.measures_mean(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO)
    std_sr = pred.measures_std(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO)
    print(f"{tag}\n{'=' * len(tag)}")
    print(f"Average Sharpe Ratio: {mean_sr:0.2f}")
    print(f"Sharpe Ratio Std Dev: {std_sr:0.2f}\n")
```

```none
Benchmark Model
===============
Average Sharpe Ratio: 0.36
Sharpe Ratio Std Dev: 0.38

Tuned Model
===========
Average Sharpe Ratio: 0.50
Sharpe Ratio Std Dev: 0.32
```

Let’s display the Box plot of the CVaR Ratio:

```Python
population_mc.boxplot_measure(
    measure=RatioMeasure.CVAR_RATIO, tag_list=["Benchmark Model", "Tuned Model"]
)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

We plot the asset composition for the first two `MultiPeriodPortfolio`:

```Python
pred_tuned_mc[:2].plot_composition(display_sub_ptf_name=False)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

We plot the weights evolution over time for the first `MultiPeriodPortfolio`:

```Python
pred_tuned_mc[0].plot_weights_per_observation()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="conclusion"></a>

## Conclusion

A single-path walk-forward analysis may understate the variability and uncertainty of
real-world performance. Multiple Randomized Cross-Validation, by contrast, applies
a resampling-based evaluation across asset subsets and time windows, yielding
performance estimates that are more robust and less prone to overfitting.

<a id="references"></a>

## References

* <a id='id3'>**[1]**</a> “Portfolio Optimization: Theory and Application”, Chapter 8 Daniel P. Palomar (2025)

**Total running time of the script:** (5 minutes 59.031 seconds)

<a id="sphx-glr-download-auto-examples-model-selection-plot-1-multiple-randomized-cv-py"></a>

# auto_examples/online_learning/index.html.md

<a id="sphx-glr-auto-examples-online-learning"></a>

<a id="online-learning-examples"></a>

<a id="online-learning"></a>

# Online Learning

Examples demonstrating online covariance evaluation, online hyperparameter
tuning, and online evaluation of portfolio optimization with incremental
estimators.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to evaluate online covariance estimators with online_covariance_forecast_evaluation.">  <div class="sphx-glr-thumbnail-title">Online Covariance Forecast Evaluation</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to tune covariance estimator hyperparameters in an online setting using OnlineGridSearch and OnlineRandomizedSearch.">  <div class="sphx-glr-thumbnail-title">Online Covariance Hyperparameter Tuning</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial shows how to tune a MeanRisk estimator with online search and evaluate it out-of-sample with an online walk-forward procedure.">  <div class="sphx-glr-thumbnail-title">Online Evaluation of Portfolio Optimization</div>
</div>
</div>

# auto_examples/online_learning/plot_1_online_covariance_forecast_evaluation.html.md

<a id="sphx-glr-auto-examples-online-learning-plot-1-online-covariance-forecast-evaluation-py"></a>

<a id="online-covariance-forecast-evaluation"></a>

# Online Covariance Forecast Evaluation

This tutorial shows how to evaluate online covariance estimators with
[`online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation).

We compare [`EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance), a plain EWMA covariance, against
[`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance), its regime-adjusted counterpart
based on the Short-Term Volatility Update (STVU) <sup>[1](#id2)</sup>.

Both support incremental updates via `partial_fit`, making them suitable for streaming
evaluation. For estimators that do not support `partial_fit`, the batch counterpart
[`covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.covariance_forecast_evaluation.html.md#skfolio.model_selection.covariance_forecast_evaluation) can be used instead.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 2010-01-04 up to 2022-12-28.

```Python
import numpy as np
from plotly.io import show

from skfolio.datasets import load_sp500_dataset
from skfolio.model_selection import (
    CovarianceForecastComparison,
    online_covariance_forecast_evaluation,
)
from skfolio.moments import (
    EWCovariance,
    RegimeAdjustedEWCovariance,
    RegimeAdjustmentMethod,
)
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X = X["2010":]
```

<a id="covariance-estimators"></a>

## Covariance Estimators

We use two covariance estimators:

* [`EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance)
* [`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance)

`EWCovariance` can react slowly to volatility shocks.

`RegimeAdjustedEWCovariance` adds a regime adjustment via the Short-Term Volatility
Update (STVU). This applies a scalar multiplier to better align predicted and
realized risk when volatility regimes change faster than a plain EWMA can track.

We set the same variance half-life of 40 trading days for both estimators and
a correlation half-life of 80 trading days for `RegimeAdjustedEWCovariance`. Lower
half-life for variance allows the model to adapt faster to volatility shifts, while
higher half-life for correlation enables more stable estimation of co-movements, which
typically require more data for reliable inference and reduces estimation noise. This
choice also aligns with empirical evidence that volatility tends to mean-revert faster
than correlation.

```Python
ew_cov = EWCovariance(half_life=40)

stvu_cov = RegimeAdjustedEWCovariance(
    half_life=40,
    corr_half_life=80,
    regime_half_life=20,
    regime_method=RegimeAdjustmentMethod.RMS,
)
```

<a id="evaluate-each-estimator"></a>

## Evaluate Each Estimator

We now evaluate each estimator with
[`online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation).
This function performs a walk-forward evaluation. At each step, it updates the
estimator with `partial_fit` and compares the one-step-ahead forecast with the next
realized return.

Here, `warmup_size=252` reserves the first year for initialization, while
`test_size=1` evaluates the forecast one day at a time.

```Python
ew_evaluation = online_covariance_forecast_evaluation(
    ew_cov,
    X,
    warmup_size=252,
    test_size=1,
)
stvu_evaluation = online_covariance_forecast_evaluation(
    stvu_cov,
    X,
    warmup_size=252,
    test_size=1,
)
```

<a id="summary-table"></a>

## Summary Table

Let’s display the summary of the regime-adjusted covariance forecast
evaluation. The four rows are:

* **Mahalanobis ratio** evaluates whether the full covariance structure
  (all eigenvalue directions) is correctly specified. The target is 1.0,
  with values above 1.0 indicating underestimated risk and values below
  1.0 indicating overestimated risk.
* **Diagonal ratio** evaluates the individual asset variances only, with
  the same 1.0 target and interpretation.
* **Portfolio standardized returns** evaluate calibration along one
  portfolio direction rather than across all directions. Their `std`
  column is the bias statistic, with values near 1.0 meaning
  well-calibrated portfolio risk.
* **Portfolio QLIKE** evaluates portfolio variance forecasts along one
  portfolio direction by comparing the forecast portfolio variance with
  the realized sum of squared portfolio returns over the evaluation
  window. Lower values indicate better variance forecasts.

```Python
stvu_evaluation.summary()
```

[plotly figure stripped from llms output]
<br />
<br />

<a id="side-by-side-comparison"></a>

## Side-by-Side Comparison

We now compare both evaluations with
[`CovarianceForecastComparison`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison):

```Python
comparison = CovarianceForecastComparison(
    [ew_evaluation, stvu_evaluation], names=["EWMA Cov", "STVU Cov"]
)
comparison.summary()
```

[plotly figure stripped from llms output]
<br />
<br />

<a id="qlike-loss"></a>

## QLIKE Loss

Let’s now plot the QLIKE loss. It compares the forecast portfolio variance
with the realized sum of squared portfolio returns over the evaluation
window, with lower values indicating better portfolio variance forecasts.
Because STVU rescales the forecast toward realized risk, we generally
expect it to achieve a lower QLIKE.

```Python
comparison.plot_qlike_loss()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="exceedance-rates"></a>

## Exceedance Rates

We can also display the exceedance summary. If the covariance forecast were perfectly
calibrated and returns were Gaussian, the squared Mahalanobis distance would follow a
chi-squared distribution. The exceedance rate measures how often this distance exceeds
the chi-squared threshold at a given significance level.

In practice, daily equity returns are fat-tailed, so in this example both estimators
exceed the nominal levels. This metric is therefore more useful for comparing
estimators than for making an absolute calibration statement.

```Python
comparison.exceedance_summary()
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

The QLIKE plot also includes the P5-P95 bands from the 30 portfolios:

```Python
multi_portfolio_comparison.plot_qlike_loss()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="conclusion"></a>

## Conclusion

This tutorial showed how to:

1. Define online covariance estimators supporting `partial_fit`.
2. Evaluate them with [`online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation).
3. Inspect calibration diagnostics and QLIKE.
4. Compare multiple estimators with [`CovarianceForecastComparison`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison).
5. Extend the analysis to multiple portfolio directions.

In the [next tutorial](https://skfolio.org/auto_examples/online_learning/plot_2_online_hyperparameter_tuning.html.md#sphx-glr-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py),
we show how to tune covariance estimator hyperparameters with online search.

* <a id='id2'>**[1]**</a> G. Paleologo, “The Elements of Quantitative Investing”, Wiley Finance (2025).

**Total running time of the script:** (0 minutes 23.516 seconds)

<a id="sphx-glr-download-auto-examples-online-learning-plot-1-online-covariance-forecast-evaluation-py"></a>

# auto_examples/online_learning/plot_2_online_hyperparameter_tuning.html.md

<a id="sphx-glr-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py"></a>

<a id="online-covariance-hyperparameter-tuning"></a>

# Online Covariance Hyperparameter Tuning

This tutorial shows how to tune covariance estimator hyperparameters in an online
setting using [`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch) and
[`OnlineRandomizedSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch).

The online approach is equivalent to combining scikit-learn’s
`GridSearchCV`
(or `RandomizedSearchCV`) with
[`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) using `expand_train=True`, but instead of
refitting every candidate from scratch at each split, it calls `partial_fit` to
incrementally update the estimator. This is significantly faster for estimators that
support this method.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 2010-01-04 up to 2022-12-28.

```Python
import pandas as pd
import plotly.express as px
import plotly.graph_objects as go
from plotly.io import show
from scipy.stats import uniform

from skfolio.datasets import load_sp500_dataset
from skfolio.metrics import (
    diagonal_calibration_loss,
    make_scorer,
    portfolio_variance_qlike_loss,
)
from skfolio.model_selection import (
    OnlineGridSearch,
    OnlineRandomizedSearch,
    online_score,
)
from skfolio.moments import RegimeAdjustedEWCovariance
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X = X["2010":]
```

<a id="build-scorers"></a>

## Build Scorers

We build scorers with [`make_scorer`](https://skfolio.org/generated/skfolio.metrics.make_scorer.html.md#skfolio.metrics.make_scorer).
We set `response_method=None` because a covariance estimator is a non-predictor
estimator (it does not implement `predict`), and `greater_is_better=False` because
both losses are minimized.

```Python
qlike_scorer = make_scorer(
    portfolio_variance_qlike_loss,
    greater_is_better=False,
    response_method=None,
)

calibration_scorer = make_scorer(
    diagonal_calibration_loss,
    greater_is_better=False,
    response_method=None,
)
```

<a id="onlinegridsearch"></a>

## OnlineGridSearch

We now tune [`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance) with
[`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch).

We search over `half_life`, `corr_half_life`, and `regime_half_life`.
`corr_half_life` controls the correlation smoothing separately from the
variance half-life, while `regime_half_life` controls how quickly the
regime adjustment adapts to market changes.

Each candidate is evaluated with a full online walk-forward pass. Here,
`warmup_size=252` uses the first year for initialization and `test_size=5`
evaluates windows of 5 consecutive daily observations (one trading week).

```Python
grid_search = OnlineGridSearch(
    estimator=RegimeAdjustedEWCovariance(),
    param_grid={
        "half_life": [20, 40, 60],
        "corr_half_life": [40, 80],
        "regime_half_life": [10, 20],
    },
    scoring=qlike_scorer,
    warmup_size=252,
    test_size=5,
    n_jobs=-1,
)
grid_search.fit(X)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<a id="conclusion"></a>

## Conclusion

This tutorial demonstrated how to tune online covariance estimator hyperparameters.

1. Build scorers with [`make_scorer`](https://skfolio.org/generated/skfolio.metrics.make_scorer.html.md#skfolio.metrics.make_scorer) and
   `response_method=None` for non-predictor estimators.
2. Use [`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch) for small,
   structured search spaces.
3. Use [`OnlineRandomizedSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch) for larger
   continuous search spaces, specifying `refit` when scoring is multi-metric.
4. Evaluate and compare estimators numerically with
   [`online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score).

In the [next tutorial](https://skfolio.org/auto_examples/online_learning/plot_3_online_portfolio_optimization_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-3-online-portfolio-optimization-evaluation-py),
we move from covariance tuning to end-to-end online portfolio optimization
evaluation with [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk).

**Total running time of the script:** (1 minutes 36.574 seconds)

<a id="sphx-glr-download-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py"></a>

# auto_examples/online_learning/plot_3_online_portfolio_optimization_evaluation.html.md

<a id="sphx-glr-auto-examples-online-learning-plot-3-online-portfolio-optimization-evaluation-py"></a>

<a id="online-evaluation-of-portfolio-optimization"></a>

# Online Evaluation of Portfolio Optimization

This tutorial shows how to tune a [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) estimator with
online search and evaluate it out-of-sample with an online walk-forward procedure.

Unlike the [previous tutorial](https://skfolio.org/auto_examples/online_learning/plot_2_online_hyperparameter_tuning.html.md#sphx-glr-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py),
which tuned the covariance estimator in isolation, here we optimize the portfolio model
end-to-end using a portfolio-level metric.

The online approach is equivalent to combining scikit-learn’s
`GridSearchCV` with
[`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) using `expand_train=True`, but instead of
refitting every candidate from scratch at each split, it calls `partial_fit` to
incrementally update each estimator. This is significantly faster for estimators that
support this method.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the S&P 500 Index composition starting from 2010-01-04 up to 2022-12-28.

```Python
import numpy as np
from plotly.io import show

from skfolio import Population
from skfolio.datasets import load_sp500_dataset
from skfolio.model_selection import OnlineGridSearch, online_predict
from skfolio.moments import EWMu, RegimeAdjustedEWCovariance
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X = X["2010":]
```

<a id="baseline-portfolio-model"></a>

## Baseline Portfolio Model

We start with a simple Minimum Variance optimization via
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk). All sub-estimators support `partial_fit`, so
the entire pipeline can be updated incrementally during walk-forward evaluation.

```Python
baseline_model = MeanRisk(
    prior_estimator=EmpiricalPrior(
        mu_estimator=EWMu(half_life=40),
        covariance_estimator=RegimeAdjustedEWCovariance(
            half_life=40,
            corr_half_life=80,
            regime_half_life=20,
        ),
    ),
)
```

<a id="online-portfolio-search"></a>

## Online Portfolio Search

We search directly over the portfolio estimator using a portfolio-level metric. For
portfolio optimization estimators, [`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch)
defaults to the Sharpe ratio when `scoring=None`.

We tune both the optimization objective and a few covariance hyperparameters.
The double-underscore syntax reaches into nested sub-estimators, just like in
scikit-learn model selection.

Here, `warmup_size=252` reserves the first year of observations for initialization and
`test_size=5` evaluates windows of 5 consecutive daily observations (one trading week).

```Python
portfolio_search = OnlineGridSearch(
    estimator=baseline_model,
    param_grid={
        "objective_function": [
            ObjectiveFunction.MINIMIZE_RISK,
            ObjectiveFunction.MAXIMIZE_RATIO,
        ],
        "prior_estimator__covariance_estimator__half_life": [20, 40, 60],
        "prior_estimator__covariance_estimator__corr_half_life": [40, 80],
    },
    warmup_size=252,
    test_size=5,
    n_jobs=-1,
    return_predictions=True,
)
portfolio_search.fit(X)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<a id="online-score"></a>

## Online Score

[`online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score) runs the same walk-forward evaluation
and returns a scalar score. This is useful when the prediction path is not needed:

```python
from skfolio.measures import RatioMeasure
from skfolio.model_selection import online_score

baseline_score = online_score(
    baseline_model,
    X,
    warmup_size=252,
    test_size=5,
    scoring=RatioMeasure.ANNUALIZED_SHARPE_RATIO,
)
tuned_score = online_score(
    portfolio_search.best_estimator_,
    X,
    warmup_size=252,
    test_size=5,
    scoring=RatioMeasure.ANNUALIZED_SHARPE_RATIO,
)
```

Both prediction paths are already available here, so the scores are read from them
below rather than running two additional walk-forward passes:

```Python
baseline_score = baseline_prediction.annualized_sharpe_ratio
tuned_score = tuned_prediction.annualized_sharpe_ratio

print(f"Baseline Sharpe: {baseline_score:.4f}")
print(f"Tuned Sharpe: {tuned_score:.4f}")
```

```none
Baseline Sharpe: 0.9365
Tuned Sharpe: 0.9662
```

<a id="conclusion"></a>

## Conclusion

This tutorial demonstrated the portfolio-level online workflow:

1. Define an incremental [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) estimator whose
   sub-estimators all support `partial_fit`.
2. Tune it with [`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch) using a
   portfolio-level metric.
3. Evaluate the tuned estimator out-of-sample with
   [`online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict) and visualize the results
   with [`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population).
4. Summarize the walk-forward performance as a scalar with
   [`online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score).

This complements the
[previous tutorial](https://skfolio.org/auto_examples/online_learning/plot_2_online_hyperparameter_tuning.html.md#sphx-glr-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py):
covariance tuning improves the statistical forecast, while direct portfolio search
optimizes the full allocation problem end-to-end.

**Total running time of the script:** (1 minutes 14.302 seconds)

<a id="sphx-glr-download-auto-examples-online-learning-plot-3-online-portfolio-optimization-evaluation-py"></a>

# auto_examples/pre_selection/index.html.md

<a id="sphx-glr-auto-examples-pre-selection"></a>

<a id="pre-selection-examples"></a>

<a id="pre-selection"></a>

# Pre-selection

Examples of using [pre-selection transformers](https://skfolio.org/user_guide/pre_selection.html.md#pre-selection) with `Pipelines`.

<div id='sg-tag-list' class='sphx-glr-tag-list'></div><div class="sphx-glr-thumbnails">
<div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the  pre-selection transformers &lt;pre_selection&gt; DropCorrelated to remove highly correlated assets before the optimization.">  <div class="sphx-glr-thumbnail-title">Drop Highly Correlated Assets</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial introduces the pre-selection transformers &lt;pre_selection&gt; SelectKExtremes to select the k best or the k worst assets according to a given measure before the optimization.">  <div class="sphx-glr-thumbnail-title">Select Best Performers</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="This tutorial demonstrates how to implement a custom pre-selection transformer &lt;pre_selection&gt; with metadata_routing, integrate it into a Pipeline, and run walk-forward cross-validation.">  <div class="sphx-glr-thumbnail-title">Custom Pre-selection Using Volumes</div>
</div><div class="sphx-glr-thumbcontainer" tooltip="When working with large datasets over long timeframes, we commonly encounter:">  <div class="sphx-glr-thumbnail-title">Handling Incomplete Datasets: Inception, Expiry, and Default</div>
</div>
</div>

# auto_examples/pre_selection/plot_1_drop_correlated.html.md

<a id="sphx-glr-auto-examples-pre-selection-plot-1-drop-correlated-py"></a>

<a id="drop-highly-correlated-assets"></a>

# Drop Highly Correlated Assets

This tutorial introduces the  [pre-selection transformers](https://skfolio.org/user_guide/pre_selection.html.md#pre-selection)
[`DropCorrelated`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated) to remove highly correlated assets before
the optimization.

Highly correlated assets tend to increase the instability of mean-variance optimization.

In this example, we will compare a mean-variance optimization with and without
pre-selection.

<a id="data"></a>

## Data

We load the FTSE 100 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 64
assets from the FTSE 100 Index composition starting from 2000-01-04 up to 2023-05-31:

```Python
from plotly.io import show
from sklearn import set_config
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline

from skfolio import Population, RatioMeasure
from skfolio.datasets import load_ftse100_dataset
from skfolio.model_selection import (
    CombinatorialPurgedCV,
    cross_val_predict,
    optimal_folds_number,
)
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.pre_selection import DropCorrelated, DropZeroVariance
from skfolio.preprocessing import prices_to_returns

prices = load_ftse100_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="model"></a>

## Model

First, we create a maximum Sharpe Ratio model without pre-selection and fit it on the
training set:

```Python
model1 = MeanRisk(objective_function=ObjectiveFunction.MAXIMIZE_RATIO)
model1.fit(X_train)
model1.weights_
```

```none
array([5.72489249e-08, 6.92799374e-02, 2.99565070e-02, 5.15427369e-07,
       5.98248544e-08, 2.11954170e-07, 1.45472665e-07, 6.30531936e-08,
       1.38474971e-01, 5.39755883e-04, 1.19668650e-06, 2.04407315e-07,
       8.79495071e-03, 9.56173669e-08, 9.05345546e-08, 3.00727420e-07,
       8.30609346e-02, 3.48492428e-07, 1.18995205e-07, 1.41496349e-07,
       3.13544690e-02, 9.49328192e-08, 3.89233565e-02, 6.73529749e-08,
       1.08791263e-01, 1.03983577e-07, 1.81104294e-01, 1.71678032e-07,
       6.17026729e-08, 1.85876178e-07, 1.06482316e-07, 5.09757681e-08,
       1.97934916e-06, 4.57814908e-08, 8.41631508e-02, 6.52279086e-08,
       6.16740873e-03, 1.07868907e-07, 1.72699954e-07, 8.59571976e-08,
       1.12484994e-01, 1.77846765e-07, 7.68211300e-08, 8.46476491e-08,
       9.91391606e-08, 1.08820474e-07, 9.52131434e-08, 4.71020370e-07,
       9.27208522e-08, 1.40414870e-07, 3.82148954e-03, 8.28101461e-02,
       3.04499311e-03, 7.93434222e-08, 1.98631698e-07, 1.72168221e-02,
       1.14241628e-07, 1.24128912e-07, 2.22757658e-07, 3.33244837e-07,
       1.59411484e-07, 4.79955614e-07, 9.26676077e-08, 5.55225624e-07])
```

<a id="pipeline"></a>

## Pipeline

Then, we create a maximum Sharpe ratio model with pre-selection using `Pipeline` and
fit it on the training set:

```Python
set_config(transform_output="pandas")

model2 = Pipeline(
    [
        ("drop_zero_variance", DropZeroVariance(threshold=1e-6)),
        ("drop_correlated", DropCorrelated(threshold=0.5)),
        ("optimization", MeanRisk(objective_function=ObjectiveFunction.MAXIMIZE_RATIO)),
    ]
)
model2.fit(X_train)
model2.named_steps["optimization"].weights_
```

```none
array([8.18629046e-02, 2.99990921e-02, 1.16397541e-06, 3.33347825e-07,
       1.82548038e-01, 2.85482485e-03, 3.56265072e-06, 1.10513944e-02,
       2.32253197e-07, 2.05141268e-07, 7.34710302e-07, 8.21495217e-02,
       9.52097597e-07, 3.41747905e-07, 3.58028595e-02, 4.20420351e-02,
       1.56245104e-07, 2.35646825e-07, 1.85053358e-01, 3.80020780e-07,
       2.42398710e-07, 1.15032452e-03, 1.09539530e-07, 9.00503120e-02,
       2.41991003e-07, 3.83742727e-07, 1.23265556e-01, 3.91693342e-07,
       1.83251807e-07, 2.09337576e-07, 2.38594386e-07, 2.26123969e-07,
       1.11576161e-06, 2.18898633e-07, 8.33465412e-03, 8.57587244e-02,
       1.29547016e-02, 1.87531533e-07, 4.25937609e-07, 2.51052265e-02,
       2.73616225e-07, 3.03373275e-07, 5.56618079e-07, 3.50951178e-07,
       1.05787166e-06, 1.45723458e-06])
```

<a id="prediction"></a>

## Prediction

We predict both models on the test set:

```Python
ptf1 = model1.predict(X_test)
ptf1.name = "model1"
ptf2 = model2.predict(X_test)
ptf2.name = "model2"

print(ptf1.n_assets)
print(ptf2.n_assets)
```

```none
64
46
```

Each predicted object is a `MultiPeriodPortfolio`.
For improved analysis, we can add them to a `Population`:

```Python
population = Population([ptf1, ptf2])
```

Let’s plot the portfolios cumulative returns on the test set:

```Python
population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="combinatorial-purged-cross-validation"></a>

## Combinatorial Purged Cross-Validation

Only using one testing path (the historical path) may not be enough for comparing both
models. For a more robust analysis, we can use the
[`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) to create multiple testing
paths from different training folds combinations.

We choose `n_folds` and `n_test_folds` to obtain around 100 test paths and an average
training size of 800 days:

```Python
n_folds, n_test_folds = optimal_folds_number(
    n_observations=X_test.shape[0],
    target_n_test_paths=100,
    target_train_size=800,
)

cv = CombinatorialPurgedCV(n_folds=n_folds, n_test_folds=n_test_folds)
cv.summary(X_test)
```

```none
Number of Observations             1967
Total Number of Folds                10
Number of Test Folds                  6
Purge Size                            0
Embargo Size                          0
Average Training Size               786
Number of Test Paths                126
Number of Training Combinations     210
dtype: int64
```

```Python
pred_1 = cross_val_predict(
    model1,
    X_test,
    cv=cv,
    n_jobs=-1,
    portfolio_params=dict(annualization_factor=252, tag="model1"),
)

pred_2 = cross_val_predict(
    model2,
    X_test,
    cv=cv,
    n_jobs=-1,
    portfolio_params=dict(annualization_factor=252, tag="model2"),
)
```

The predicted object is a `Population` of `MultiPeriodPortfolio`. Each
`MultiPeriodPortfolio` represents one testing path of a rolling portfolio.
For improved analysis, we can merge the populations of each model:

```Python
population = pred_1 + pred_2
```

<a id="distribution"></a>

## Distribution

We plot the out-of-sample distribution of Sharpe ratio for both models:

```Python
fig = population.plot_distribution(
    measure_list=[RatioMeasure.SHARPE_RATIO], tag_list=["model1", "model2"], n_bins=40
)
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Model 1:

```Python
print(
    "Average of Sharpe Ratio:"
    f" {pred_1.measures_mean(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO):0.2f}"
)
print(
    "Std of Sharpe Ratio:"
    f" {pred_1.measures_std(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO):0.2f}"
)
```

```none
Average of Sharpe Ratio: 0.46
Std of Sharpe Ratio: 0.20
```

Model 2:

```Python
print(
    "Average of Sharpe Ratio:"
    f" {pred_2.measures_mean(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO):0.2f}"
)
print(
    "Std of Sharpe Ratio:"
    f" {pred_2.measures_std(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO):0.2f}"
)
```

```none
Average of Sharpe Ratio: 0.51
Std of Sharpe Ratio: 0.21
```

**Total running time of the script:** (0 minutes 9.091 seconds)

<a id="sphx-glr-download-auto-examples-pre-selection-plot-1-drop-correlated-py"></a>

# auto_examples/pre_selection/plot_2_select_best_performers.html.md

<a id="sphx-glr-auto-examples-pre-selection-plot-2-select-best-performers-py"></a>

<a id="select-best-performers"></a>

# Select Best Performers

This tutorial introduces the [pre-selection transformers](https://skfolio.org/user_guide/pre_selection.html.md#pre-selection)
[`SelectKExtremes`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes) to select the `k` best or the `k` worst
assets according to a given measure before the optimization.

In this example, we will use a `Pipeline` to assemble the pre-selection step with a
minimum variance optimization. Then, we will use cross-validation to find the optimal
number of pre-selected assets to maximize the mean out-of-sample Sharpe Ratio.

<a id="data"></a>

## Data

We load the FTSE 100 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 64
assets from the FTSE 100 Index starting from 2000-01-04 up to 2023-05-31:

```Python
import plotly.graph_objs as go
from plotly.io import show
from sklearn import set_config
from sklearn.model_selection import GridSearchCV, train_test_split
from sklearn.pipeline import Pipeline

from skfolio import Population, RatioMeasure
from skfolio.datasets import load_ftse100_dataset
from skfolio.metrics import make_scorer
from skfolio.model_selection import (
    WalkForward,
    cross_val_predict,
)
from skfolio.optimization import MeanRisk
from skfolio.pre_selection import SelectKExtremes
from skfolio.preprocessing import prices_to_returns

prices = load_ftse100_dataset()
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)
```

<a id="model"></a>

## Model

First, we create a Minimum Variance model without pre-selection:

```Python
benchmark = MeanRisk()
```

#### NOTE
A covariance matrix that is not positive definite often occurs in high
dimensional problems. It can be due to multicollinearity, floating-point
inaccuracies, or when the number of observations is smaller than the number of
assets. By default, the parameter named `nearest` from the covariance estimator is
set to `True`: if the covariance is not positive definite (PD), it is replaced by
the nearest covariance that is PD without changing the variance.
For more details, see [`cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest).

<a id="pipeline"></a>

## Pipeline

Then, we create a Minimum Variance model with pre-selection using `Pipeline`:

```Python
set_config(transform_output="pandas")

model = Pipeline([("pre_selection", SelectKExtremes()), ("optimization", benchmark)])
```

<a id="parameter-tuning"></a>

## Parameter Tuning

To demonstrate how parameter tuning works in a Pipeline model, we find the number of
pre-selected assets `k` that maximizes the out-of-sample Sharpe Ratio using
`GridSearchCV` with `WalkForward` cross-validation on the training set. The
`WalkForward` is chosen to simulate a three months (60 business days) rolling
portfolio fitted on the previous year (252 business days):

```Python
cv = WalkForward(train_size=252, test_size=60)

scorer = make_scorer(RatioMeasure.ANNUALIZED_SHARPE_RATIO)
```

Note that we can also create a custom scorer this way:
`scorer=make_scorer(lambda pred: pred.mean - 0.5 * pred.variance)`

```Python
grid_search = GridSearchCV(
    estimator=model,
    cv=cv,
    n_jobs=-1,
    param_grid={"pre_selection__k": list(range(5, 66, 3))},
    scoring=scorer,
    return_train_score=True,
)
grid_search.fit(X_train)
model = grid_search.best_estimator_
print(model)
```

```none
Pipeline(steps=[('pre_selection', SelectKExtremes(k=53)),
                ('optimization', MeanRisk())])
```

Let’s plot the train and test scores as a function of the number of pre-selected
assets. The vertical line represents the best test score and the selected model:

```Python
cv_results = grid_search.cv_results_
fig = go.Figure(
    [
        go.Scatter(
            x=cv_results["param_pre_selection__k"],
            y=cv_results["mean_train_score"],
            name="Train",
            mode="lines",
            line=dict(color="rgb(31, 119, 180)"),
        ),
        go.Scatter(
            x=cv_results["param_pre_selection__k"],
            y=cv_results["mean_train_score"] + cv_results["std_train_score"],
            mode="lines",
            line=dict(width=0),
            showlegend=False,
        ),
        go.Scatter(
            x=cv_results["param_pre_selection__k"],
            y=cv_results["mean_train_score"] - cv_results["std_train_score"],
            mode="lines",
            line=dict(width=0),
            showlegend=False,
            fillcolor="rgba(31, 119, 180,0.15)",
            fill="tonexty",
        ),
        go.Scatter(
            x=cv_results["param_pre_selection__k"],
            y=cv_results["mean_test_score"],
            name="Test",
            mode="lines",
            line=dict(color="rgb(255,165,0)"),
        ),
        go.Scatter(
            x=cv_results["param_pre_selection__k"],
            y=cv_results["mean_test_score"] + cv_results["std_test_score"],
            mode="lines",
            line=dict(width=0),
            showlegend=False,
        ),
        go.Scatter(
            x=cv_results["param_pre_selection__k"],
            y=cv_results["mean_test_score"] - cv_results["std_test_score"],
            line=dict(width=0),
            mode="lines",
            fillcolor="rgba(255,165,0, 0.15)",
            fill="tonexty",
            showlegend=False,
        ),
    ]
)
fig.add_vline(
    x=grid_search.best_params_["pre_selection__k"],
    line_width=2,
    line_dash="dash",
    line_color="green",
)
fig.update_layout(
    title="Train/Test score",
    xaxis_title="Number of pre-selected best performers",
    yaxis_title="Annualized Sharpe Ratio",
)
fig.update_yaxes(tickformat=".2f")
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

The mean test Sharpe Ratio increases from 1.17 (for k=5) to its maximum 1.91
(for k=50) then decreases to 1.81 (for k=65).
The selected model is a pre-selection of the top 50 performers based on their Sharpe
Ratio, followed by a Minimum Variance optimization.

<a id="prediction"></a>

## Prediction

Now we evaluate the two models using the same `WalkForward` object on the test set:

```Python
pred_bench = cross_val_predict(
    benchmark,
    X_test,
    cv=cv,
    portfolio_params=dict(name="Benchmark"),
)

pred_model = cross_val_predict(
    model,
    X_test,
    cv=cv,
    n_jobs=-1,
    portfolio_params=dict(name="Pre-selection"),
)
```

Each predicted object is a `MultiPeriodPortfolio`.
For improved analysis, we can add them to a `Population`:

```Python
population = Population([pred_bench, pred_model])
```

Let’s plot the rolling portfolios cumulative returns on the test set:

```Python
population.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s plot the rolling portfolios compositions:

```Python
population.plot_composition(display_sub_ptf_name=False)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s display the full summary:

```Python
population.summary()
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Plot the full out-of-sample walk-forward path:

```Python
pred.plot_cumulative_returns()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

**Total running time of the script:** (0 minutes 2.359 seconds)

<a id="sphx-glr-download-auto-examples-pre-selection-plot-3-custom-pre-selection-volumes-py"></a>

# auto_examples/pre_selection/plot_4_incomplete_dataset.html.md

<a id="sphx-glr-auto-examples-pre-selection-plot-4-incomplete-dataset-py"></a>

<a id="handling-incomplete-datasets-inception-expiry-and-default"></a>

# Handling Incomplete Datasets: Inception, Expiry, and Default

When working with large datasets over long timeframes, we commonly encounter:

* **Inception**: Assets that began trading after the start of the dataset.
* **Expiry**: Expiring assets such as bonds, options, and futures.
* **Default**: Assets that defaulted.
* **Voluntary Delisting**

These events create challenges for portfolio optimization and backtesting.
A common workaround is to focus only on assets with complete datasets, excluding those
with later inception dates, defaults, or earlier expirations. However, this approach
either shortens the backtesting period or reduces the number of assets, potentially
introducing survivorship bias.

An additional challenge arises with assets that have known expiration dates
(e.g., options, bonds, futures). If an asset is due to expire in the next period, it
may be preferable to exit early, especially if it’s not cash-settled.

In this tutorial, we will demonstrate how to implement all these rules in a single
`Pipeline` that can be used with cross-validation techniques such as `WalkForward` and
hyperparameter tuning tools like `GridSearchCV`.

<a id="data"></a>

## Data

Let’s create price data for four hypothetical assets over 13 days:

* `inception`: Asset with a later inception date.
* `defaulted`: Asset that defaulted.
* `expired`: Asset that expired.
* `complete`: Asset with a complete price history.

We’ll convert these prices to returns and split the dataset into 3 rebalancing
periods of 4 days each.

```Python
import datetime as dt

import matplotlib.image as mpi
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from sklearn import set_config
from sklearn.impute import SimpleImputer
from sklearn.model_selection import GridSearchCV
from sklearn.pipeline import Pipeline

from skfolio import RatioMeasure
from skfolio.metrics import make_scorer
from skfolio.model_selection import WalkForward, cross_val_predict
from skfolio.optimization import EqualWeighted
from skfolio.pre_selection import SelectComplete, SelectNonExpiring
from skfolio.preprocessing import prices_to_returns

def generate_prices(n: int) -> list[float]:
    # Just for example purposes
    return list(100 * np.cumprod(1 + np.random.normal(0, 0.01, n)))

prices = pd.DataFrame(
    {
        "inception": [np.nan] * 3 + generate_prices(10),
        "defaulted": generate_prices(6) + [0.0] + [np.nan] * 6,
        "expired": generate_prices(10) + [np.nan] * 3,
        "complete": generate_prices(13),
    },
    index=pd.date_range(start="2024-01-03", end="2024-01-19", freq="B"),
)

X = prices_to_returns(prices, drop_inceptions_nan=False, fill_nan=False)

img = mpi.imread("../images/incomplete_dataset.png")
fig, ax = plt.subplots(figsize=(10, 6.327))
ax.imshow(img)
ax.axis("off")
plt.subplots_adjust(left=0, right=1, top=1, bottom=0)
```

![plot 4 incomplete dataset](/auto_examples/pre_selection/images/sphx_glr_plot_4_incomplete_dataset_001.png)

<a id="pipeline"></a>

## Pipeline

Our `Pipeline` will handle the following cases:

When we **train** our optimization model on the first period (magenta box), we want to
exclude the “inception” asset.

When **testing** on the second period (green box), we want to capture the loss on the
“defaulted” asset (the -100% on 2024-01-11) without failing on the subsequent NaNs.

Then, when we **train** on the second period, we want to include the “inception”
asset, exclude the defaulted asset, and also exclude the “expired” asset that will
expire in the next **test** period (blue box).

```Python
set_config(transform_output="pandas")

model = Pipeline(
    [
        ("select_complete_assets", SelectComplete()),
        (
            "select_non_expiring_assets",
            SelectNonExpiring(
                expiration_dates={"expired": dt.datetime(2024, 1, 16)},
                expiration_lookahead=pd.offsets.BusinessDay(4),
            ),
        ),
        ("zero_imputation", SimpleImputer(strategy="constant", fill_value=0)),
        ("optimization", EqualWeighted()),
    ]
)
```

The transformer `SelectComplete` handles the “inception” and “defaulted” assets,
while `SelectNonExpiring` excludes assets close to expiration.
`SimpleImputer` replaces NaNs with 0s on the “defaulted” asset in the test period.

<a id="walk-forward-cross-validation"></a>

## Walk-Forward Cross-Validation

Now, we pass this pipeline model into `cross_val_predict` using `WalkForward`:

```Python
pred = cross_val_predict(model, X, cv=WalkForward(train_size=4, test_size=4))
```

As expected, the pipeline correctly applies our rules to each period:

```Python
df = pred.composition
df.columns = ["Period 2 (green)", "Period 3 (blue)"]
df
```

[plotly figure stripped from llms output]
<br />
<br />

And the inverse volatility model has non-equal variance contribution. This is because
the correlation is not taken into account in an inverse volatility model:

```Python
ptf_bench_train = bench.predict(X_train)
ptf_bench_train.plot_contribution(measure=RiskMeasure.ANNUALIZED_VARIANCE)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="prediction"></a>

## Prediction

We predict the model and the benchmark on the test set:

```Python
ptf_model_test = model.predict(X_test)
ptf_bench_test = bench.predict(X_test)
```

The `predict` method returns a [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) object.

<a id="analysis"></a>

## Analysis

For improved analysis, we load both predicted portfolios into a
[`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population):

```Python
population = Population([ptf_model_test, ptf_bench_test])
```

Let’s plot each portfolio composition:

```Python
population.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s plot each portfolio cumulative returns:

```Python
fig = population.plot_cumulative_returns()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Finally, we print a full summary of both strategies evaluated on the test set:

```Python
population.summary()
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

And the inverse volatility model has different CVaR contribution for each asset:

```Python
ptf_bench_train = bench.predict(X_train)
ptf_bench_train.plot_contribution(measure=RiskMeasure.CVAR)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="prediction"></a>

## Prediction

We predict the model and the benchmark on the test set:

```Python
ptf_model_test = model.predict(X_test)
ptf_bench_test = bench.predict(X_test)
```

<a id="analysis"></a>

## Analysis

For improved analysis, it’s possible to load both predicted portfolios into a
[`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population):

```Python
population = Population([ptf_model_test, ptf_bench_test])
```

Let’s plot each portfolio composition:

```Python
population.plot_composition()
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s plot each portfolio cumulative returns:

```Python
fig = population.plot_cumulative_returns()
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Finally, we print a full summary of both strategies evaluated on the test set:

```Python
population.summary()
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Finally, we print a full summary of both strategies evaluated on the test set:

```Python
population.summary()
```

[plotly figure stripped from llms output]
<br />
<br />

Let’s analyse the Q-Q plot:

```Python
jpm_dist.qq_plot(X2)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s explore the difference versus the Gaussian distribution:

```Python
gaussian = Gaussian()
gaussian.fit(X2)
gaussian.plot_pdf(X2)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

```Python
gaussian.qq_plot(X2)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The Q-Q plot and zooming in on the tail of the Johnson Su distribution shows that its
fat tails are well captured, which is not the case for the Gaussian distribution.

<a id="uniform-marginals"></a>

## Uniform Marginals

Before working with copulas, we transform the asset returns into uniform marginals
using their univariate CDFs:

```Python
X = np.hstack([bac_dist.cdf(X1), jpm_dist.cdf(X2)])
```

<a id="id1"></a>

## Bivariate Copulas

We use the utility function `select_bivariate_copula` to select the optimal
bivariate copula based on information criterion (BIC or AIC).

```Python
candidates = [
    GaussianCopula(),
    StudentTCopula(),
    ClaytonCopula(),
    GumbelCopula(),
    JoeCopula(),
]
copula = select_bivariate_copula(X, copula_candidates=candidates)
print(copula.fitted_repr)
print(f"AIC: {copula.aic(X):,.2f}")
```

```none
StudentTCopula(rho=0.748, dof=2.65)
AIC: -7,525.40
```

Let’s plot the 2D probability density function (PDF) of the Student-t copula.
The x-axis and y-axis represent the uniform variates (u and v) obtained by applying
the marginal cumulative distribution functions (CDFs) to the returns of BAC and JPM,
respectively.

```Python
fig = copula.plot_pdf_2d()
fig.update_layout(height=700)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Each contour line connects points of equal copula density, effectively delineating
regions with the same level of joint dependence between the two assets. Areas where
the contours are closely spaced indicate a rapid change in density, reflecting regions
with higher concentrations of joint probability.

The Student-t copula captures tail dependence: extreme positive or negative returns
in one asset tend to occur simultaneously with extreme returns in the other. This is
visualized as pronounced “bulges” in the tail regions of the contour plot.

Note: The copula density is defined on the scale of the transformed uniform marginals.
To recover the joint density of the original asset returns, the copula density must
be multiplied by the marginal probability density functions, which take on lower
values in the tails.

Now, let’s plot the 3D PDF:

```Python
fig = copula.plot_pdf_3d()
fig.update_layout(scene_camera=dict(eye=dict(x=-1.2, y=1.4, z=0.8)))
fig
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="tail-dependencies"></a>

### Tail Dependencies

For a bivariate random vector $(X,Y)$ with marginal distribution functions
$F_X$ and $F_Y$, the tail dependence coefficients quantify the probability
that one variable is extreme given that the other is extreme. They are defined as
follows:

Upper Tail Dependence Coefficient:

$$
\lambda_U = \lim_{u \to 1^-} P\left( Y > F_Y^{-1}(u) \mid X > F_X^{-1}(u) \right)

$$

Lower Tail Dependence Coefficient:

$$
\lambda_L = \lim_{u \to 0^+} P\left( Y \le F_Y^{-1}(u) \mid X \le F_X^{-1}(u) \right)

$$

A positive $\lambda_U$ (or $\lambda_L$) indicates that extreme high
(or low) values of $X$ and $Y$ occur together more frequently than if
the variables were independent.

Let’s print the Student’s t Copula tail dependence.
The model indicates a tail dependence coefficient of approximately 51%, suggesting
a relatively high likelihood that extreme returns (both negative and positive) occur
simultaneously for the assets. Since the Student’s t copula is symmetric, the tail
dependence is the same for both the lower and upper tails.

```Python
print(f"Lower Tail Dependence: {copula.lower_tail_dependence:.2%}")
print(f"Upper Tail Dependence: {copula.upper_tail_dependence:.2%}")
```

```none
Lower Tail Dependence: 51.21%
Upper Tail Dependence: 51.21%
```

<a id="tail-concentration"></a>

### Tail Concentration

Tail concentration refers to how much probability mass is concentrated at the tails
of a distribution.
Let’s plot the tail concentration of the copula model versus the historical data:

```Python
copula.plot_tail_concentration(X)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

<a id="comparison-with-the-gaussian-copula"></a>

## Comparison with the Gaussian Copula

Let’s explore the difference versus the Gaussian Copula:

```Python
copula = GaussianCopula()
copula.fit(X)
print(copula.fitted_repr)
print(f"Rho: {copula.rho_:0.2f}")
print(f"AIC: {copula.aic(X):,.2f}")
print(f"Lower Tail Dependence: {copula.lower_tail_dependence:.2%}")
print(f"Upper Tail Dependence: {copula.upper_tail_dependence:.2%}")
```

```none
GaussianCopula(rho=0.748)
Rho: 0.75
AIC: -6,346.65
Lower Tail Dependence: 0.00%
Upper Tail Dependence: 0.00%
```

Let’s plot the 2D PDF:

```Python
fig = copula.plot_pdf_2d()
fig.update_layout(height=700)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s plot the tail concentration of the copula model versus the historical data:

```Python
copula.plot_tail_concentration(X)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

As expected, the tail concentration plot shows that the Gaussian Copula cannot capture
the tail dependencies of the historical data.

<a id="comparison-with-the-joe-copula"></a>

## Comparison with the Joe Copula

Let’s now compare with the Joe Copula:

```Python
copula = JoeCopula()
copula.fit(X)
print(copula.fitted_repr)
print(f"Rotation: {copula.rotation_}")
print(f"Rho: {copula.theta_:0.2f}")
print(f"AIC: {copula.aic(X):,.2f}")
print(f"Lower Tail Dependence: {copula.lower_tail_dependence:.2%}")
print(f"Upper Tail Dependence: {copula.upper_tail_dependence:.2%}")
```

```none
JoeCopula(theta=3.18, rot=180°)
Rotation: 180°
Rho: 3.18
AIC: -4,921.77
Lower Tail Dependence: 75.61%
Upper Tail Dependence: 0.00%
```

Let’s plot the 2D PDF:

```Python
fig = copula.plot_pdf_2d()
fig.update_layout(height=700)
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<br/>

Let’s plot the tail concentration of the copula model versus the historical data:

```Python
copula.plot_tail_concentration(X)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

The Joe Copula, when rotated at 180° (as in this example), exhibits strong lower
tail dependence. Although Archimedean copulas are typically not appropriate for stock
returns, they can be a good fit for other asset classes such as agricultural
commodities, derivatives, or CDSs.

<a id="conclusion"></a>

## Conclusion

Bivariate copulas are used to model complex dependencies between financial assets.
Elliptical copulas, such as the Gaussian and Student’s t, offer a straightforward
approach with symmetric dependence, while Archimedean copulas (Gumbel, Clayton, Joe)
provide specialized modeling of tail dependencies. The ability to rotate Archimedean
copulas further enhances their flexibility, allowing for a more accurate
representation of the observed tail behavior in financial data.

**Total running time of the script:** (0 minutes 5.591 seconds)

<a id="sphx-glr-download-auto-examples-synthetic-data-plot-1-bivariate-copulas-py"></a>

# auto_examples/synthetic_data/plot_2_vine_copula.html.md

<a id="sphx-glr-auto-examples-synthetic-data-plot-2-vine-copula-py"></a>

<a id="vine-copula-stress-test"></a>

# Vine Copula & Stress Test

This tutorial presents the [`VineCopula`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula) estimator.
An introduction to Bivariate Copulas can be found in
[this previous tutorial](https://skfolio.org/auto_examples/synthetic_data/plot_1_bivariate_copulas.html.md#sphx-glr-auto-examples-synthetic-data-plot-1-bivariate-copulas-py).

<a id="introduction"></a>

## Introduction

A Vine copula is a highly flexible multivariate copula model that decomposes a complex
dependency structure into a cascade of bivariate copulas (Gaussian, Student’s, Clayton,
Gumbel, Joe, etc.). This approach allows each pair of variables to be modeled with its
own copula, capturing intricate dependencies that may be asymmetric or exhibit distinct
tail behaviors.

Moreover, the marginal distributions are modeled independently using a variety of
univariate candidate distributions (Gaussian, Student’s t, Johnson Su, etc.). This
separation of marginal modeling and dependence modeling provides greater flexibility
when fitting multivariate data.

<a id="mathematical-foundations"></a>

## Mathematical Foundations

At the core of copula theory lies **Sklar’s Theorem**, which states that for any
multivariate cumulative distribution function $F(x_1, \dots, x_d)$ with marginals
$F_1(x_1), \dots, F_d(x_d)$, there exists a copula $C$ such that:

$$
F(x_1, \dots, x_d) = C\left(F_1(x_1), \dots, F_d(x_d)\right).

$$

A **Regular Vine copula** applies Sklar’s Theorem **recursively**
to factorize the joint density of $(x_1,\dots,x_d)$ into marginal densities and
bivariate copula densities arranged in a vine (tree) structure. Formally:

$$
f(x_1, \dots, x_d) = \prod_{i=1}^d f_i(x_i)
  \times \prod_{\ell=1}^{d-1} \prod_{j=1}^{d-\ell}
  c_{j,\,j+\ell \mid D_{j,\ell}}\!\Bigl(
     F(x_j \mid D_{j,\ell}),\,
     F(x_{j+\ell} \mid D_{j,\ell})
  \Bigr),

$$

where:

- $f_i(x_i)$ is the marginal density of $x_i$.
- $D_{j,\ell} = \{x_1, \dots, x_{j-1}\}$ is the conditioning set.
- $c_{j,\,j+\ell \mid D_{j,\ell}}$ is the **bivariate copula density** linking
  the conditional distributions of $x_j$ and $x_{j+\ell}$ given the
  variables in $D_{j,\ell}$.

<a id="advantages-of-vine-copulas"></a>

## Advantages of Vine Copulas

Vine copulas offer several advantages in financial modeling compared to deep learning
approaches such as out-of-the-box Generative Adversarial Networks (GANs) or Variational
Autoencoders (VAEs):

- **Interpretability:**
  Vine copulas provide a clear, parametric decomposition of the joint distribution into
  marginal and pairwise components.
- **Tail Dependence Modeling:**
  They explicitly model tail dependencies, allowing for better estimation of joint
  extreme events.
- **Flexibility and Parsimony:**
  By selecting the best-fitting parametric copula for each pair of variables, vine
  copulas can capture a wide range of dependency structures while limiting overfitting,
  even in high-dimensional settings.
- **Data Efficiency:**
  They require less data than deep learning models to accurately
  model dependencies, making them suitable for financial datasets that may be limited in
  size.
- **Conditional Sampling and Stress Testing:**
  They support advanced conditional sampling techniques that enable the generation
  of scenario-specific simulations. This is especially beneficial for generating stress
  tests that are both **extreme** and **plausible**.

<a id="types-of-vine-structures"></a>

## Types of Vine Structures

Vine copulas encompass several specific structures that organize the pair-copula
decomposition differently. The most common types are:

- **R-vine (Regular Vine):**
  The most general vine structure, which is constructed using a maximum spanning tree
  (MST) algorithm. At each tree level, the MST selects the pairwise dependencies that
  maximize a chosen dependence measure, ensuring that the strongest dependencies are
  captured.
- **C-vine (Canonical Vine):**
  A special case of the R-vine where one variable acts as a central node and is
  connected to all other variables in the first tree. Subsequent trees condition on this
  central variable. This structure is useful when one variable exerts a dominant
  influence over the others.
- **D-vine (Drawable Vine):**
  A special case where variables are arranged in a sequential chain with each variable
  conditionally dependent only on its immediate neighbors. While this chain-like
  structure is intuitive, it is often too simplistic for financial applications, where
  dependencies tend to be more complex and multidimensional.
- **Clustered Vine:**
  An extension of the vine framework that explicitly accounts for clustered dependency
  structures. In this approach, variables are grouped around central assets, capturing
  hierarchical relationships within clusters. This is especially beneficial in finance,
  where assets often exhibit strong intra-cluster dependencies, enhancing conditional
  sampling and stress testing.

<a id="skfolio-implementation"></a>

## Skfolio Implementation

The Vine Copula in skfolio is a novel, state-of-the-art implementation designed
specifically for financial data. It constructs a Regular Vine copula where asset
centrality can be controlled to capture clustered or C-like dependency structures.
This allows for a more nuanced representation of hierarchical relationships among
assets, enhancing conditional sampling and stress testing.

Key features include:

- **Inference Methods:**
  The implementation supports both inverse Kendall’s tau (itau) and Maximum Likelihood
  Estimation (MLE) approaches to estimate both optimal marginal distributions and pair
  copula parameters.
- **Dependence Structure:**
  The maximum spanning tree construction supports multiple dependence measures such as
  Kendall’s tau, mutual information, or Wasserstein distance.
- **Performance Enhancements:**
  It leverages parallelization and vine truncation to improve computational efficiency.
- **Sampling Capabilities:**
  The model supports both unconditional sampling and complex conditional sampling for
  stress testing.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) and select 6 stocks (for demonstration
purposes) starting from 1990-01-02 up to 2022-12-28:

```Python
from plotly.io import show

from skfolio import Population, RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.distribution import StudentTCopula, VineCopula, compute_pseudo_observations
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
prices = prices[["AMD", "BAC", "HD", "JPM", "LLY", "CVX"]]
X = prices_to_returns(prices)
print(X.tail())
```

```none
                 AMD       BAC        HD       JPM       LLY       CVX
Date
2022-12-21  0.040430  0.015223  0.014358  0.011248  0.023275  0.011758
2022-12-22 -0.056442 -0.008848 -0.010146 -0.011355 -0.007339 -0.014998
2022-12-23  0.010335  0.002443  0.008257  0.004749  0.007090  0.030914
2022-12-27 -0.019374  0.001875  0.002572  0.003504 -0.008208  0.012570
2022-12-28 -0.011064  0.007360 -0.011953  0.005463  0.000932 -0.014751
```

<a id="vine-copula"></a>

## Vine Copula

Let’s fit a Regular [`VineCopula`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula) in parallel using all
processors (`n_jobs=-1`) and applying a log transform for improved statistical
properties:

```Python
vine = VineCopula(n_jobs=-1, log_transform=True, random_state=0)
vine.fit(X)
vine.display_vine()
```

```none
Root Nodes
----------
Node(0): JohnsonSU(a=-0.046, b=1.2, loc=-0.0012, scale=0.033)
Node(1): StudentT(loc=0.00035, scale=0.013, df=2.5)
Node(2): JohnsonSU(a=0.0036, b=1.2, loc=0.00077, scale=0.017)
Node(3): JohnsonSU(a=-0.012, b=1.1, loc=0.00011, scale=0.015)
Node(4): StudentT(loc=0.00039, scale=0.012, df=3.7)
Node(5): StudentT(loc=0.00054, scale=0.011, df=4)

Tree(level 0)
-------------
Edge((0, 2), StudentTCopula(rho=0.316, dof=5.67))
Edge((1, 3), StudentTCopula(rho=0.748, dof=2.66))
Edge((2, 3), StudentTCopula(rho=0.443, dof=4.06))
Edge((2, 4), StudentTCopula(rho=0.332, dof=4.28))
Edge((3, 5), StudentTCopula(rho=0.377, dof=4.61))

Tree(level 1)
-------------
Edge((0, 3) | {2}, StudentTCopula(rho=0.203, dof=8.13))
Edge((1, 5) | {3}, StudentTCopula(rho=0.168, dof=17.51))
Edge((3, 4) | {2}, StudentTCopula(rho=0.215, dof=8.62))
Edge((2, 5) | {3}, StudentTCopula(rho=0.150, dof=8.21))

Tree(level 2)
-------------
Edge((0, 5) | {2, 3}, StudentTCopula(rho=0.100, dof=16.02))
Edge((1, 2) | {3, 5}, StudentTCopula(rho=0.123, dof=7.73))
Edge((4, 5) | {2, 3}, StudentTCopula(rho=0.145, dof=10.04))

Tree(level 3)
-------------
Edge((0, 1) | {2, 3, 5}, StudentTCopula(rho=0.070, dof=19.89))
Edge((0, 4) | {2, 3, 5}, StudentTCopula(rho=0.053, dof=17.92))
```

We note that the marginals are composed of Johnson Su and Student’s t distributions
while the pair copulas are only composed of Student’s t Copulas.

Let’s break it down:

* `Node(0): JohnsonSU(-0.0462, 1.24, -0.00123, 0.0332)`: This represents the marginal
  distribution of variable 0 (AMD).
* `Edge((0, 2), StudentTCopula(0.316, 5.671))`: This represents the unconditional
  bivariate copula between variables 0 (AMD) and 2 (HD) modeled by a Student’s t Copula
  with $\rho=31.6\%$ and $\nu=5.6$.
* `Edge((1, 2) | {3, 5}, StudentTCopula(0.123, 7.732))`: This represents the
  conditional bivariate copula between variables 1 (BAC) and 2 (HD) given variables
  3 (JPM) and 5 (CVX) modeled by a Student’s t Copula with $\rho=12.3\%$ and
  $\nu=7.7$.

Let’s print the total log-likelihood and AIC of the vine copula:

```Python
score = vine.score(X)
aic = vine.aic(X)
print(f"Total Log-likelihood: {score:,.02f}")
print(f"AIC: {aic:,.02f}")
```

```none
Total Log-likelihood: 132,740.11
AIC: -265,382.23
```

Note that the [`VineCopula`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula) estimator is compatible
with all scikit-learn tools for cross-validation and parameter tuning.

<a id="sampling-from-the-vine"></a>

## Sampling from the Vine

Let’s generate 10,000 synthetic returns from the vine copula model. In the next
tutorial, we will show how this can be used for minimizing portfolio CVaR when
historical tail data is limited. The use of parametric copulas enables the
extrapolation of tail dependencies, and by generating a larger sample of returns,
we can achieve enhanced accuracy in capturing tail co-dependencies during the
optimization process.

```Python
samples = vine.sample(n_samples=10000)
print(samples.shape)
```

```none
(10000, 6)
```

Let’s plot the scatter matrix of the generated returns from the Vine model and compare
them with the historical returns `X`.

```Python
fig = vine.plot_scatter_matrix(X=X)
fig.update_layout(height=600)
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<a id="tractability-interpretability"></a>

## Tractability & Interpretability

As mentioned above, one of the advantages of Vine Copula is its tractability.
First, let’s plot the marginal distribution of AMD and compare it with the
historical data:

```Python
amd_dist = vine.marginal_distributions_[0]
amd_dist.plot_pdf(X[["AMD"]])
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

```Python
amd_dist.qq_plot(X[["AMD"]])
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Now, let’s investigate the bivariate copula between variables 0 (AMD) and 2 (HD):

```Python
edge = vine.trees_[0].edges[0]
copula = edge.copula
print(edge)
print(f"Lower Tail Dependence: {copula.lower_tail_dependence:.2%}")
print(f"Upper Tail Dependence: {copula.upper_tail_dependence:.2%}")
```

```none
Edge((0, 2), StudentTCopula(rho=0.316, dof=5.67))
Lower Tail Dependence: 10.70%
Upper Tail Dependence: 10.70%
```

The model indicates a tail dependence coefficient of 10.7%, suggesting
a positive likelihood that extreme returns (both negative and positive) occur
simultaneously for the assets.

Let’s plot the tail concentration of the copula model versus the historical data:

```Python
U = compute_pseudo_observations(X[["AMD", "HD"]])
copula.plot_tail_concentration(U)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

We notice that the model properly captured the fat tail dependencies.

<a id="conditional-sampling"></a>

## Conditional Sampling

One of the main advantages of Vine Copula is its ability to produce accurate
conditional sampling in extreme scenarios by leveraging the accurate computation of
inverse CDF of the marginal distributions as well as the partial derivatives and
inverse partial derivatives of the bivariate copulas.

Let’s generate 1000 samples conditioned on AMD returns being at -20%.

When using conditional sampling, it is recommended that the assets you condition on
are set as central during the vine copula construction. This can be specified via
`central_assets`:

```Python
vine = VineCopula(n_jobs=-1, log_transform=True, central_assets=["AMD"])
vine.fit(X)
vine.display_vine()
```

```none
Root Nodes
----------
Node(0): JohnsonSU(a=-0.046, b=1.2, loc=-0.0012, scale=0.033)
Node(1): StudentT(loc=0.00035, scale=0.013, df=2.5)
Node(2): JohnsonSU(a=0.0036, b=1.2, loc=0.00077, scale=0.017)
Node(3): JohnsonSU(a=-0.012, b=1.1, loc=0.00011, scale=0.015)
Node(4): StudentT(loc=0.00039, scale=0.012, df=3.7)
Node(5): StudentT(loc=0.00054, scale=0.011, df=4)

Tree(level 0)
-------------
Edge((0, 1), StudentTCopula(rho=0.293, dof=5.56))
Edge((0, 2), StudentTCopula(rho=0.316, dof=5.67))
Edge((0, 3), StudentTCopula(rho=0.307, dof=5.28))
Edge((0, 4), StudentTCopula(rho=0.193, dof=6.09))
Edge((0, 5), StudentTCopula(rho=0.222, dof=7.01))

Tree(level 1)
-------------
Edge((1, 3) | {0}, StudentTCopula(rho=0.726, dof=2.99))
Edge((2, 3) | {0}, StudentTCopula(rho=0.394, dof=5.36))
Edge((2, 4) | {0}, StudentTCopula(rho=0.296, dof=5.61))
Edge((3, 5) | {0}, StudentTCopula(rho=0.342, dof=5.78))

Tree(level 2)
-------------
Edge((1, 5) | {0, 3}, StudentTCopula(rho=0.160, dof=21.56))
Edge((3, 4) | {0, 2}, StudentTCopula(rho=0.202, dof=10.10))
Edge((2, 5) | {0, 3}, StudentTCopula(rho=0.131, dof=9.36))

Tree(level 3)
-------------
Edge((1, 2) | {0, 3, 5}, StudentTCopula(rho=0.110, dof=8.56))
Edge((4, 5) | {0, 2, 3}, StudentTCopula(rho=0.142, dof=10.94))
```

As expected, we notice that the variable 0 (AMD) is the central node in Tree 0 and
the common conditioning variable in subsequent trees.

```Python
cond_samples = vine.sample(n_samples=1000, conditioning={"AMD": -0.2})
print(cond_samples.shape)
```

```none
(1000, 6)
```

Note that you can also provide an array of scenarios for the AMD returns
(e.g. `[-0.2,-0.21,-0.22,...]`).

Let’s now see a more complex example by generating samples conditioned on the
following:

* HD between -10% and -15%
* JPM below -5%

```Python
vine = VineCopula(
    n_jobs=-1, log_transform=True, central_assets=["HD", "JPM"], random_state=0
)
vine.fit(X)

conditioning = {"HD": (-0.15, -0.10), "JPM": (None, -0.05)}
cond_samples = vine.sample(n_samples=1000, conditioning=conditioning)
print(cond_samples.shape)
```

```none
(1000, 6)
```

Let’s plot the marginal distribution of the stressed assets and compare them with the
historical data:

```Python
vine.plot_marginal_distributions(X=X, conditioning=conditioning)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

Let’s plot the scatter matrix of the stressed assets and compare them with the
historical data:

```Python
fig = vine.plot_scatter_matrix(X, conditioning=conditioning)
fig.update_layout(height=600)
```

<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>[plotly figure stripped from llms output]
<br />
<br />

In the graph, by selecting HD and JPM, you can see that the conditioning has been
respected and has impacted the other assets following the vine structure. This allows
the creation of Stress Tests that are both **extreme** and **plausible**.

<a id="portfolio-stress-test"></a>

## Portfolio Stress Test

We create a Minimum CVaR portfolio and fit it on the historical returns.

```Python
model = MeanRisk(risk_measure=RiskMeasure.CVAR)
model.fit(X)
print(model.weights_)

ptf = model.predict(X)
```

```none
[8.65356305e-12 4.06326174e-12 2.14436665e-01 1.82085950e-11
 3.65721255e-01 4.19842080e-01]
```

We sample 50,000 new returns from the Vine Copula, conditioning on a one-day loss
of 10% for JPM and use these stressed samples to conduct a stress test on our
portfolio.

```Python
stressed_X = vine.sample(n_samples=50_000, conditioning={"JPM": -0.10})
stressed_ptf = model.predict(stressed_X)

ptf.name = "Unstressed Ptf"
stressed_ptf.name = "Stressed Ptf"
population = Population([ptf, stressed_ptf])
summary = population.summary()
summary.loc[
    ["Mean", "Standard Deviation", "CVaR at 95%", "EVaR at 95%", "Worst Realization"]
]
```

[plotly figure stripped from llms output]
<br />
<br />

<a id="advanced-stress-testing"></a>

## Advanced Stress Testing

Another approach for generating stress samples, which can be used in conjunction
with conditional sampling, involves directly stressing the vine structure. Since all
pair copulas are accessible, we can modify their parameters to simulate stressed
market conditions. This approach is particularly useful when the vine structure is
considered to be dynamic and regime-dependent (i.e. dynamic vine).
In our example, we increase the correlation parameter of the Student’s t copula by
10% and decrease its degrees of freedom by 20%, resulting in heavier tails and more
pronounced joint extreme events. In practice, these stressed parameters should be
calibrated based on specific market regimes.

```Python
for tree in vine.trees_:
    for edge in tree.edges:
        if isinstance(edge.copula, StudentTCopula):
            edge.copula.rho_ *= 1.1
            edge.copula.dof_ *= 0.8

samples = vine.sample(n_samples=1000)
```

<a id="conclusion"></a>

## Conclusion

The flexibility, interpretability, and explicit modeling of tail dependencies make
vine copulas an attractive choice for financial applications. In the next tutorial,
we will show how to use them in a portfolio pipeline for optimization and stress
testing.

<a id="references"></a>

## References

[1] Selecting and estimating regular vine copulae and application to financial returns
: Dissmann, Brechmann, Czado, and Kurowicka (2013).

[2] Growing simplified vine copula trees: improving Dißmann’s algorithm
: Krausa and Czado (2017).

[3] Pair-copula constructions of multiple dependence”
: Aas, Czado, Frigessi, Bakken (2009).

[4] Pair-Copula Constructions for Financial Applications: A Review
: Aas and Czado(2016).

[5] Conditional copula simulation for systemic risk stress testing
: Brechmann, Hendrich, Czado (2013)

**Total running time of the script:** (0 minutes 11.448 seconds)

<a id="sphx-glr-download-auto-examples-synthetic-data-plot-2-vine-copula-py"></a>

# auto_examples/synthetic_data/plot_3_min_CVaR_stressed_factors.html.md

<a id="sphx-glr-auto-examples-synthetic-data-plot-3-min-cvar-stressed-factors-py"></a>

<a id="minimize-cvar-on-stressed-factors"></a>

# Minimize CVaR on Stressed Factors

This tutorial shows how to bridge scenario generation, factor models and portfolio
optimization.

In [the previous tutorial](https://skfolio.org/auto_examples/synthetic_data/plot_2_vine_copula.html.md#sphx-glr-auto-examples-synthetic-data-plot-2-vine-copula-py),
we demonstrated how to generate conditional (stressed) synthetic returns using the
[`VineCopula`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula) estimator.

Using the [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) optimization, you could directly
minimize the CVaR of your portfolio based on synthetic returns sampled from a given
model (Vine Copula, GAN, VAE, etc.).
However, in practice, we often need to perform cross-validation, portfolio rebalancing,
and hyperparameter tuning. To facilitate this, we require a unified model that
integrates synthetic data generation and optimization. This is exactly the role of
the [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData) estimator, which bridges scenario generation,
factor models and portfolio optimization.

There are several reasons why you might choose to run optimization on (factor) synthetic
data rather than (factor) historical data:

* Historical data is often limited, especially in the tails, which can make it
  challenging to model extreme events accurately. Using parametric copulas to explicitly
  capture tail dependencies allows for better extrapolation of joint extreme events.
  By generating a larger sample of returns from Vine Copulas, you improve the accuracy
  of capturing tail co-dependencies during the optimization process.
* Build portfolios optimized for specific stressed scenarios.

<a id="data"></a>

## Data

We load the S&P 500 [dataset](https://skfolio.org/user_guide/datasets.html.md#datasets) composed of the daily prices of 20
assets from the SPX Index composition and the Factors dataset composed of the daily
prices of 5 ETFs representing common factors.

```Python
from plotly.io import show
from sklearn.model_selection import train_test_split

from skfolio import Population, RiskMeasure
from skfolio.datasets import load_factors_dataset, load_sp500_dataset
from skfolio.distribution import VineCopula
from skfolio.model_selection import WalkForward, cross_val_predict
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import SyntheticData, TimeSeriesFactorModel

prices = load_sp500_dataset()
factor_prices = load_factors_dataset()

X, factors = prices_to_returns(prices, factor_prices)
X_train, X_test, factors_train, factors_test = train_test_split(
    X, factors, test_size=0.33, shuffle=False
)
print(factors_train.tail())
```

```none
                MTUM      QUAL      SIZE      USMV      VLUE
Date
2020-01-06  0.001112  0.002372  0.001443  0.001373 -0.001556
2020-01-07 -0.002463 -0.001380 -0.000520 -0.004099  0.001447
2020-01-08  0.005328  0.004043  0.003295  0.002123  0.002248
2020-01-09  0.008698  0.008157  0.004602  0.006257  0.001787
2020-01-10  0.000000 -0.001366 -0.003462 -0.000450 -0.004245
```

```Python
print("Shapes:")
print(f"X_train: {X_train.shape}")
print(f"X_test: {X_test.shape}")
print(f"factors_train: {factors_train.shape}")
print(f"factors_test: {factors_test.shape}")
```

```none
Shapes:
X_train: (1516, 20)
X_test: (747, 20)
factors_train: (1516, 5)
factors_test: (747, 5)
```

<a id="minimize-cvar-on-synthetic-data"></a>

## Minimize CVaR on Synthetic Data

Let’s find the minimum CVaR portfolio on 10,000 synthetic returns generated from
Vine Copula fitted on the historical training set and evaluate it on the historical
test set.

```Python
vine = VineCopula(log_transform=True, n_jobs=-1, random_state=0)
prior = SyntheticData(distribution_estimator=vine, n_samples=10_000)
model = MeanRisk(risk_measure=RiskMeasure.CVAR, prior_estimator=prior)

model.fit(X_train)
print(model.weights_)
ptf = model.predict(X_test)
# You can then perform a full analysis using the portfolio methods.
```

```none
[2.99163234e-02 1.92346751e-13 1.89564634e-12 3.37339390e-12
 7.00316703e-12 1.33337111e-11 1.17286269e-01 4.80395251e-02
 1.73647665e-12 1.68249706e-01 1.28994607e-02 1.71842102e-12
 2.55424753e-02 1.12472168e-01 7.60284652e-03 1.21264748e-01
 4.71035822e-13 4.38902739e-12 1.77207763e-01 1.79518714e-01]
```

<a id="multi-period-portfolio"></a>

## Multi-period Portfolio

Now let’s run a walk-forward analysis where we optimize the minimum CVaR portfolio on
synthetic data generated from a Vine Copula fitted on one year (252 business days) of
historical data and evaluate it on the following 3 months (60 business days) of data,
repeating over the full history.

```Python
cv = WalkForward(train_size=252, test_size=60)
ptf = cross_val_predict(model, X_train, cv=cv)
ptf.summary()
```

```none
Mean                                     0.041%
Annualized Mean                          10.24%
Variance                               0.000057
Annualized Variance                       1.45%
Semi-Variance                          0.000033
Annualized Semi-Variance                  0.82%
Standard Deviation                        0.76%
Annualized Standard Deviation            12.02%
Semi-Deviation                            0.57%
Annualized Semi-Deviation                 9.05%
Mean Absolute Deviation                   0.54%
CVaR at 95%                               1.91%
EVaR at 95%                               3.02%
Worst Realization                         4.78%
CDaR at 95%                              12.16%
MAX Drawdown                             16.12%
Average Drawdown                          3.48%
EDaR at 95%                              12.99%
First Lower Partial Moment                0.27%
Ulcer Index                               0.049
Gini Mean Difference                      0.79%
Value at Risk at 95%                      1.14%
Drawdown at Risk at 95%                  10.91%
Entropic Risk Measure at 95%               3.00
Fourth Central Moment                 0.000003%
Fourth Lower Partial Moment           0.000002%
Skew                                    -74.27%
Kurtosis                                837.40%
Sharpe Ratio                              0.054
Annualized Sharpe Ratio                    0.85
Sortino Ratio                             0.071
Annualized Sortino Ratio                   1.13
Mean Absolute Deviation Ratio             0.076
First Lower Partial Moment Ratio           0.15
Value at Risk Ratio at 95%                0.036
CVaR Ratio at 95%                         0.021
Entropic Risk Measure Ratio at 95%      0.00014
EVaR Ratio at 95%                         0.013
Worst Realization Ratio                  0.0085
Drawdown at Risk Ratio at 95%            0.0037
CDaR Ratio at 95%                        0.0033
Calmar Ratio                             0.0025
Average Drawdown Ratio                    0.012
EDaR Ratio at 95%                        0.0031
Ulcer Index Ratio                        0.0083
Gini Mean Difference Ratio                0.051
Avg nb of Assets per Portfolio             20.0
Number of Portfolios                         21
Number of Failed Portfolios                   0
Number of Fallback Portfolios                 0
dtype: str
```

<a id="combining-synthetic-data-with-factor-model"></a>

## Combining Synthetic Data with Factor Model

Now, let’s add another layer of complexity by incorporating a Factor Model while
stressing the quality factor (QUAL) by -20%.
The model fits a Factor Model on historical data, then fits a Vine Copula on the
factor data, samples 10,000 stressed scenarios from the Vine, and finally projects
these scenarios back to the asset universe using the Factor Model.

```Python
vine = VineCopula(
    log_transform=True, central_assets=["QUAL"], n_jobs=-1, random_state=0
)
factor_prior = SyntheticData(
    distribution_estimator=vine,
    n_samples=10_000,
    sample_args=dict(conditioning={"QUAL": -0.2}),
)
factor_model = TimeSeriesFactorModel(factor_prior_estimator=factor_prior)

model = MeanRisk(risk_measure=RiskMeasure.CVAR, prior_estimator=factor_model)
model.fit(X_train, factors=factors_train)
print(model.weights_)

ptf = model.predict(X_test)
```

```none
[2.30693507e-12 8.77980763e-14 1.06798859e-12 4.23268991e-13
 2.42217082e-13 5.03746470e-13 3.45428401e-13 3.83045088e-13
 3.71205099e-13 2.59426568e-12 3.58116049e-13 4.09878536e-13
 1.31053125e-13 3.67972223e-13 1.02638506e-11 5.23803638e-13
 1.48858331e-02 1.66279980e-12 9.85114167e-01 2.20261169e-13]
```

Let’s show how to drill down into the model to retrieve the fitted Vine Copula and
plot the marginal distributions of the stressed factors alongside the historical data.
The stressed Momentum (MTUM), Size (SIZE), Low Volatility (USMV), and Value (VLUE)
factors deviate significantly from their unstressed distributions, reflecting the
impact of stressing the Quality (QUAL) factor.
Note that the stressed distribution of the Quality factor is a Dirac, since only -20%
was sampled.

```Python
fitted_vine = model.prior_estimator_.factor_prior_estimator_.distribution_estimator_
fig = fitted_vine.plot_marginal_distributions(factors, conditioning={"QUAL": -0.2})
show(fig)
```

[plotly figure stripped from llms output]<style>html[data-theme="dark"] div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}@media (prefers-color-scheme: dark){html:not([data-theme="light"]) div.output_subarea:has(.plotly-graph-div){background:#fff;border-radius:0.25rem;padding:0.5rem}}</style><script>if (!window.plotlySphinxGalleryResize) {window.plotlySphinxGalleryResize = true;window.addEventListener("load", function () {document.querySelectorAll(".plotly-graph-div").forEach(function (gd) { Plotly.Plots.resize(gd); });});}</script>

<a id="factor-stress-test"></a>

## Factor Stress Test

Finally, let’s stress-test the portfolio by further stressing the quality factor by
-50%.

```Python
factor_model.set_params(
    factor_prior_estimator__sample_args=dict(conditioning={"QUAL": -0.5})
)
# Refit the factor model on the full dataset to update the stressed scenarios
factor_model.fit(X, factors=factors)
stressed_dist = factor_model.return_distribution_

stressed_ptf = model.predict(stressed_dist)

ptf.name = "Unstressed Ptf"
stressed_ptf.name = "Stressed Ptf"
population = Population([ptf, stressed_ptf])
summary = population.summary()
summary.loc[
    ["Mean", "Standard Deviation", "CVaR at 95%", "EVaR at 95%", "Worst Realization"]
]
```

[plotly figure stripped from llms output]
<br />
<br />

<a id="conclusion"></a>

## Conclusion

In this tutorial, we demonstrated how to bridge scenario generation, factor models,
and portfolio optimization.

**Total running time of the script:** (0 minutes 57.192 seconds)

<a id="sphx-glr-download-auto-examples-synthetic-data-plot-3-min-cvar-stressed-factors-py"></a>

# generated/skfolio.alpha.AlphaForecastComparison.html.md

<a id="skfolio-alpha-alphaforecastcomparison"></a>

# skfolio.alpha.AlphaForecastComparison

<a id="skfolio.alpha.AlphaForecastComparison"></a>

### *class* skfolio.alpha.AlphaForecastComparison(evaluations, names=None)

Side-by-side comparison of alpha forecast evaluations.

* **Attributes:**
  **names**

### Methods

| [`ic_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastComparison.html.md#skfolio.alpha.AlphaForecastComparison.ic_summary)()                     | IC summary for all evaluations.                             |
|-----------------------------------------------------------------------------------|-------------------------------------------------------------|
| [`plot_cumulative_ic`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastComparison.html.md#skfolio.alpha.AlphaForecastComparison.plot_cumulative_ic)([title])      | Plot cumulative Spearman IC for all evaluations.            |
| [`plot_cumulative_returns`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastComparison.html.md#skfolio.alpha.AlphaForecastComparison.plot_cumulative_returns)([title]) | Plot cumulative 200% gross rank-weighted portfolio returns. |
| [`portfolio_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastComparison.html.md#skfolio.alpha.AlphaForecastComparison.portfolio_summary)()              | Simple portfolio summary for all evaluations.               |

<a id="skfolio.alpha.AlphaForecastComparison.ic_summary"></a>

#### ic_summary()

IC summary for all evaluations.

<a id="skfolio.alpha.AlphaForecastComparison.plot_cumulative_ic"></a>

#### plot_cumulative_ic(title=None)

Plot cumulative Spearman IC for all evaluations.

<a id="skfolio.alpha.AlphaForecastComparison.plot_cumulative_returns"></a>

#### plot_cumulative_returns(title=None)

Plot cumulative 200% gross rank-weighted portfolio returns.

<a id="skfolio.alpha.AlphaForecastComparison.portfolio_summary"></a>

#### portfolio_summary()

Simple portfolio summary for all evaluations.

# generated/skfolio.alpha.AlphaForecastEvaluation.html.md

<a id="skfolio-alpha-alphaforecastevaluation"></a>

# skfolio.alpha.AlphaForecastEvaluation

<a id="skfolio.alpha.AlphaForecastEvaluation"></a>

### *class* skfolio.alpha.AlphaForecastEvaluation(observations, holding_period, n_forward_periods, signal_lag, evaluation_step, annualization_factor, target, cs_weighting, spearman_ic, pearson_ic, rank_weighted_portfolio_return, zscore_weighted_portfolio_return, rank_weighted_turnover, zscore_weighted_turnover, quantile_spread, quantiles, n_valid_assets, coverage, calibration_slope, mean_forecast, std_forecast, mean_target, std_target, calibration_curve, factor_correlation, factor_correlation_method, factor_names, factor_families, holding_period_diagnostics, decay, name=None)

Out-of-sample alpha forecast evaluation.

Stores cross-sectional diagnostics produced by
[`alpha_forecast_evaluation`](https://skfolio.org/generated/skfolio.alpha.alpha_forecast_evaluation.html.md#skfolio.alpha.alpha_forecast_evaluation) and provides
summary statistics and plots.

The evaluation compares historical alpha forecasts observed at time $t$
with the forward mean of a target field over
$[t + \ell, t + \ell + h)$, where $h$ is `holding_period`
and $\ell$ is `signal_lag`. The default target is `idio_returns`,
which evaluates the alpha component not explained by the factor model.

The core diagnostics are:

* **IC**: cross-sectional correlation between alpha forecasts and future target
  returns. Spearman IC measures ordering quality. Pearson IC is the
  weighted Pearson correlation under `cs_weighting`.
* **Simple alpha portfolios**: 200% gross rank-weighted and
  z-score-weighted long-short portfolios built directly from the forecast.
  They measure the realized target return of alpha-only portfolios before
  the alpha is passed to an optimizer.
* **Quantile spreads**: top-minus-bottom target returns for forecast
  quantiles, equivalent to 200% gross long-short bucket returns. They
  measure whether realized returns are concentrated in the highest-scored
  and lowest-scored assets.
* **Calibration**: scale multiplier from a weighted regression of realized
  target on forecast with zero intercept. A value near 1 indicates that the
  forecast is already scaled to realized target units.
* **Factor correlations**: contemporaneous cross-sectional correlation
  between alpha forecasts and factor exposures. They help assess whether
  the alpha forecast is cross-sectionally neutral to existing factors.
* **Holding-period summary**: the same forecasts evaluated against
  cumulative forward target windows.
* **Decay**: the same forecasts evaluated against disjoint forward target
  windows.

* **Parameters:**
  **observations** *ndarray of shape (n_steps,)*
  : Observation labels for the evaluated forecast dates.

  **holding_period** *int*
  : Number of observations in the forward target window used for the main
    evaluation.

  **n_forward_periods** *int*
  : Number of consecutive forward periods used for holding-period and decay
    diagnostics.

  **signal_lag** *int*
  : Number of observations between the forecast date and the first target
    observation. For a forecast at date $t$, the target window is
    $[t + \ell, t + \ell + h)$, where $\ell$ is `signal_lag`
    and $h$ is `holding_period`.

  **evaluation_step** *int*
  : Spacing between evaluated forecast dates.

  **annualization_factor** *float*
  : Number of observations per year used to annualize return statistics in
    `portfolio_summary` and `quantile_summary`.

  **target** *str*
  : Name of the evaluated target field in the input `AssetPanel`.

  **cs_weighting** *CSWeighting or str*
  : Cross-sectional weighting rule used for Pearson IC and the calibration
    scale multiplier.

  **spearman_ic** *ndarray of shape (n_steps,)*
  : Spearman rank IC over time.

  **pearson_ic** *ndarray of shape (n_steps,)*
  : Pearson IC over time using `cs_weighting`. With
    `CSWeighting.IDENTITY`, this is equal-weighted Pearson IC.

  **rank_weighted_portfolio_return** *ndarray of shape (n_steps,)*
  : Forward target return of a centered-rank long-short portfolio with
    200% gross exposure.

  **zscore_weighted_portfolio_return** *ndarray of shape (n_steps,)*
  : Forward target return of a centered-forecast long-short portfolio with
    200% gross exposure.

  **rank_weighted_turnover** *ndarray of shape (n_steps,)*
  : Turnover of the rank-weighted portfolio. The first value is `NaN`.

  **zscore_weighted_turnover** *ndarray of shape (n_steps,)*
  : Turnover of the z-score-weighted portfolio. The first value is `NaN`.

  **quantile_spread** *ndarray of shape (n_steps, n_quantiles)*
  : Top-minus-bottom target return for each quantile in `quantiles`,
    equivalent to a 200% gross long-short bucket return.

  **quantiles** *tuple of float*
  : Quantiles evaluated in `quantile_spread`.

  **n_valid_assets** *ndarray of shape (n_steps,)*
  : Number of assets with finite forecast and target values.

  **coverage** *ndarray of shape (n_steps,)*
  : Fraction of eligible assets used at each evaluation date.

  **calibration_slope** *float*
  : Scale multiplier from a weighted regression of realized target on
    forecast with zero intercept.

  **mean_forecast** *float*
  : Mean evaluated alpha forecast.

  **std_forecast** *float*
  : Standard deviation of evaluated alpha forecasts.

  **mean_target** *float*
  : Mean evaluated forward target.

  **std_target** *float*
  : Standard deviation of evaluated forward targets.

  **calibration_curve** *DataFrame*
  : Forecast-bucket calibration table with average forecast and realized
    target values.

  **factor_correlation** *ndarray of shape (n_observations, n_factors), optional*
  : Contemporaneous correlation between alpha forecasts and factor exposures.
    Pearson correlations are weighted by the cross-sectional weights resolved
    from `cs_weighting`. `None` when factor correlation diagnostics were
    skipped.

  **factor_correlation_method** *CorrelationMethod, optional*
  : Factor correlation method computed from the exposure field. `None`
    when factor correlation diagnostics were skipped.

  **factor_names** *ndarray of shape (n_factors,)*
  : Factor names for `factor_correlation`.

  **factor_families** *ndarray of shape (n_factors,), optional*
  : Factor family label for each factor. `None` when the factor exposure
    field does not define groups.

  **holding_period_diagnostics** *DataFrame*
  : Summary statistics by cumulative holding period.

  **decay** *DataFrame*
  : Summary statistics by disjoint forward period.

  **name** *str, optional*
  : Display name for the evaluation.
* **Attributes:**
  **name**

### Methods

| [`calibration_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.calibration_summary)()                             | Forecast scale calibration summary.                                   |
|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| [`coverage_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.coverage_summary)()                                | Coverage summary over evaluated forecast dates.                       |
| [`decay_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.decay_summary)()                                   | Alpha decay summary by disjoint forward period.                       |
| [`factor_correlation_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.factor_correlation_summary)([factors, families])   | Alpha-factor correlation summary.                                     |
| [`holding_period_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.holding_period_summary)()                          | Alpha diagnostics by cumulative holding period.                       |
| [`ic_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.ic_summary)()                                      | Information Coefficient summary.                                      |
| [`plot_calibration`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_calibration)([title])                         | Plot realized target by forecast bucket.                              |
| [`plot_cumulative_ic`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_cumulative_ic)(\*[, include_pearson, title])  | Plot cumulative IC over time.                                         |
| [`plot_cumulative_returns`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_cumulative_returns)([title])                  | Plot cumulative returns of 200% gross simple alpha portfolios.        |
| [`plot_factor_correlation`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_factor_correlation)([factors, families, ...]) | Plot mean alpha-factor correlations.                                  |
| [`plot_ic_by_holding_period`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_ic_by_holding_period)([title])                | Plot mean IC by cumulative holding period.                            |
| [`plot_ic_decay`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_ic_decay)([title])                            | Plot mean IC by disjoint forward period.                              |
| [`plot_portfolio_by_holding_period`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_portfolio_by_holding_period)([title])         | Plot simple portfolio IR by cumulative holding period.                |
| [`plot_portfolio_decay`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_portfolio_decay)([title])                     | Plot simple portfolio IR by disjoint forward period.                  |
| [`plot_quantile_returns`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_quantile_returns)([title])                    | Plot cumulative top-minus-bottom quantile spreads.                    |
| [`plot_rolling_ic`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_rolling_ic)([window, title])                  | Plot rolling mean IC over time.                                       |
| [`portfolio_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.portfolio_summary)()                               | Annualized 200% gross simple alpha portfolio summary.                 |
| [`quantile_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.quantile_summary)()                                | Annualized top-minus-bottom quantile spread summary by tail quantile. |

<a id="skfolio.alpha.AlphaForecastEvaluation.calibration_summary"></a>

#### calibration_summary()

Forecast scale calibration summary.

<a id="skfolio.alpha.AlphaForecastEvaluation.coverage_summary"></a>

#### coverage_summary()

Coverage summary over evaluated forecast dates.

<a id="skfolio.alpha.AlphaForecastEvaluation.decay_summary"></a>

#### decay_summary()

Alpha decay summary by disjoint forward period.

<a id="skfolio.alpha.AlphaForecastEvaluation.factor_correlation_summary"></a>

#### factor_correlation_summary(factors=None, families=None)

Alpha-factor correlation summary.

Measures contemporaneous cross-sectional correlation between alpha
forecasts and factor exposures. This helps assess whether the alpha
forecast is cross-sectionally neutral to existing factors. The `ir`
column is $\bar{\rho} / \sigma_{\rho}$. The `t_stat` column is
the date-level t-statistic of the mean correlation. Pearson
correlations are weighted by the cross-sectional weights resolved from
`cs_weighting`.

* **Parameters:**
  **factors** *list of str, optional*
  : Explicit factor names to include. Takes precedence over `families`.

  **families** *str, list of str, optional*
  : Factor families to include. `None` includes all factors.
* **Returns:**
  **summary** *DataFrame*
  : Rows are factors and columns are `mean`, `std`, `ir`, `t_stat` and
    `hit_rate`.

<a id="skfolio.alpha.AlphaForecastEvaluation.holding_period_summary"></a>

#### holding_period_summary()

Alpha diagnostics by cumulative holding period.

<a id="skfolio.alpha.AlphaForecastEvaluation.ic_summary"></a>

#### ic_summary()

Information Coefficient summary.

Returns one row for Spearman IC and one row for Pearson IC. The `icir`
column is $\bar{IC} / \sigma_{IC}$. The `t_stat` column is the
date-level t-statistic of the mean IC.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_calibration"></a>

#### plot_calibration(title=None)

Plot realized target by forecast bucket.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_cumulative_ic"></a>

#### plot_cumulative_ic(\*, include_pearson=True, title=None)

Plot cumulative IC over time.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_cumulative_returns"></a>

#### plot_cumulative_returns(title=None)

Plot cumulative returns of 200% gross simple alpha portfolios.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_factor_correlation"></a>

#### plot_factor_correlation(factors=None, families=None, top_n=20, title=None)

Plot mean alpha-factor correlations.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_ic_by_holding_period"></a>

#### plot_ic_by_holding_period(title=None)

Plot mean IC by cumulative holding period.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_ic_decay"></a>

#### plot_ic_decay(title=None)

Plot mean IC by disjoint forward period.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_portfolio_by_holding_period"></a>

#### plot_portfolio_by_holding_period(title=None)

Plot simple portfolio IR by cumulative holding period.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_portfolio_decay"></a>

#### plot_portfolio_decay(title=None)

Plot simple portfolio IR by disjoint forward period.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_quantile_returns"></a>

#### plot_quantile_returns(title=None)

Plot cumulative top-minus-bottom quantile spreads.

<a id="skfolio.alpha.AlphaForecastEvaluation.plot_rolling_ic"></a>

#### plot_rolling_ic(window=50, title=None)

Plot rolling mean IC over time.

<a id="skfolio.alpha.AlphaForecastEvaluation.portfolio_summary"></a>

#### portfolio_summary()

Annualized 200% gross simple alpha portfolio summary.

<a id="skfolio.alpha.AlphaForecastEvaluation.quantile_summary"></a>

#### quantile_summary()

Annualized top-minus-bottom quantile spread summary by tail quantile.

# generated/skfolio.alpha.BaseAlpha.html.md

<a id="skfolio-alpha-basealpha"></a>

# skfolio.alpha.BaseAlpha

<a id="skfolio.alpha.BaseAlpha"></a>

### *class* skfolio.alpha.BaseAlpha

Base class for all Alpha estimators in skfolio.

### Methods

| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.alpha.BaseAlpha.html.md#skfolio.alpha.BaseAlpha.get_metadata_routing)()   | Get metadata routing of this object.   |
|---------------------------------------------------------------------------|----------------------------------------|
| [`get_params`](https://skfolio.org/generated/skfolio.alpha.BaseAlpha.html.md#skfolio.alpha.BaseAlpha.get_params)([deep])       | Get parameters for this estimator.     |
| [`set_params`](https://skfolio.org/generated/skfolio.alpha.BaseAlpha.html.md#skfolio.alpha.BaseAlpha.set_params)(\*\*params)   | Set the parameters of this estimator.  |

| **fit**   |    |
|-----------|----|

<a id="skfolio.alpha.BaseAlpha.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.alpha.BaseAlpha.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.alpha.BaseAlpha.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.

# generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md

<a id="skfolio-alpha-ewsharpeoptimalalpha"></a>

# skfolio.alpha.EWSharpeOptimalAlpha

<a id="skfolio.alpha.EWSharpeOptimalAlpha"></a>

### *class* skfolio.alpha.EWSharpeOptimalAlpha(\*, descriptors, half_life=20, ridge_scale=1e-06, horizon=1, signal_lag=1, neutralize_against=None, outlier_transformer=None, scoring_transformer=None, transform_by_group=None, forecast_unit=IDIO_RETURN, forecast_scale=1.0, normalize_weights=True, n_jobs=1)

Exponentially weighted least-squares Sharpe-optimal alpha estimator.

This estimator aggregates multiple cross-sectional signals from descriptors into a
single alpha forecast by estimating their joint contribution to forward
idiosyncratic returns. Coefficients are estimated with exponentially weighted
least squares.

The estimator supports two forecast units. With the default
`forecast_unit=ForecastUnit.IDIO_RETURN`, descriptors are fitted directly to forward
idiosyncratic returns. When descriptor scores linearly forecast idiosyncratic
returns and residual noise is proportional to idiosyncratic variance, the learned
signal blend is Sharpe-optimal in idiosyncratic return space for an unconstrained
long-short strategy.

With `forecast_unit=ForecastUnit.IDIO_SHARPE`, descriptors are fitted to forward
idiosyncratic return divided by idiosyncratic volatility, with unit regression
weights. Dividing the target by $\sigma_i$ transforms the inverse-variance
GLS objective in return units into OLS in idiosyncratic-Sharpe units.

Signals are first transformed into cross-sectional scores (e.g., z-scores, ranks),
then optionally neutralized against factors and re-transformed into cross-sectional
scores and finally combined linearly:

$$
\alpha_i = \sum_{k=1}^{K} \beta_k \, S_{k,i}
$$

where $S_{k,i}$ denotes the cross-sectional score of signal $k$ for
asset $i$ and $\beta_k$ is the estimated signal coefficient.

By default, coefficients map descriptor scores directly into expected return units.
With `forecast_unit=ForecastUnit.IDIO_SHARPE`, coefficients map descriptor scores into
idiosyncratic-Sharpe units and the final forecast is multiplied by current
idiosyncratic volatility so `alpha_` remains in expected return units.

This generalizes IC-based signal weighting by:

- accounting for cross-signal correlations (multivariate estimation)
- incorporating asset-specific risk, either through inverse idiosyncratic variance
  weights or through volatility-scaled targets
- producing an alpha forecast in expected return units, which is required whenever
  the optimizer is trading off alpha against real costs and constraints (e.g.
  transaction costs, market impact, borrow costs, turnover constraints).

For an individual signal with constant idiosyncratic variance, the estimator reduces
to a scaled IC-like weighting.

The estimator uses the following regression target:

$$
y_t =
\begin{cases}
\epsilon_t, & \text{if } \texttt{forecast\_unit=ForecastUnit.IDIO\_RETURN} \\
\epsilon_t / \sigma_t, &
\text{if } \texttt{forecast\_unit=ForecastUnit.IDIO\_SHARPE}
\end{cases}
$$

and regression weights:

$$
W_t =
\begin{cases}
\operatorname{diag}(1 / \sigma_{t,i}^2), &
\text{if } \texttt{forecast\_unit=ForecastUnit.IDIO\_RETURN} \\
I, & \text{if } \texttt{forecast\_unit=ForecastUnit.IDIO\_SHARPE}
\end{cases}
$$

where:

- $\epsilon_{t,i}$ is the forward mean idiosyncratic return over the chosen
  horizon
- $S_{t,i} \in \mathbb{R}^K$ is the vector of cross-sectional scores
- $\sigma_{t,i}^2$ is the forecast idiosyncratic variance

If `normalize_weights=True`, the positive diagonal entries of $W_t$ are
divided by their cross-sectional average before computing the normal-equation
statistics.

With `forecast_unit=ForecastUnit.IDIO_SHARPE`, the return model is instead:

$$
\epsilon_{t,i} = \sigma_{t,i} S_{t,i}^\top \beta + \eta_{t,i},
\quad \operatorname{Var}(\eta_{t,i}) \propto \sigma_{t,i}^2
$$

The corresponding inverse-variance GLS objective is:

$$
\beta_t = \arg\min_\beta \sum_i
    \frac{(\epsilon_{t,i} - \sigma_{t,i} S_{t,i}^\top \beta)^2}
    {\sigma_{t,i}^2}
$$

which is equivalent to ordinary least squares on the volatility-scaled target
$\epsilon_{t,i}/\sigma_{t,i}$:

$$
\beta_t = \arg\min_\beta \sum_i
  \left(\frac{\epsilon_{t,i}}{\sigma_{t,i}}
  - S_{t,i}^\top \beta\right)^2
$$

The final forecast is converted back to expected return units:

$$
\alpha_i = \sigma_i S_i^\top \beta
$$

This is useful when signals are assumed to forecast idiosyncratic Sharpe rather than
raw idiosyncratic return. For the same scaled signal forecast, higher-volatility
assets receive larger return alpha because the forecast is converted back from
idiosyncratic-Sharpe units to return units.

To reduce estimation noise and turnover, the estimator maintains exponentially
weighted least-squares statistics:

$$
A_t^{EW} = \lambda A_{t-1}^{EW} + (1 - \lambda) S_t^\top W_t S_t
$$

$$
b_t^{EW} = \lambda b_{t-1}^{EW} + (1 - \lambda) S_t^\top W_t y_t,
\quad \lambda = 2^{-1/\text{half-life}}
$$

Coefficients are obtained by ridge-stabilized normal equations:

$$
\beta_t = (A_t^{EW} + \rho_t I)^{-1} b_t^{EW}
$$

With `forecast_unit=ForecastUnit.IDIO_RETURN`, the final alpha forecast is:

$$
\alpha_i = S_i^\top \beta
$$

With `forecast_unit=ForecastUnit.IDIO_SHARPE`, the forecast is:

$$
\alpha_i = \sigma_i S_i^\top \beta
$$

No intercept is included to avoid absorbing cross-sectional means, making the
resulting alpha suitable for long-short strategies.

The estimator supports latest-alpha fitting with [`fit`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.fit) and [`partial_fit`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.partial_fit),
and historical alpha forecasts with [`fit_transform`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.fit_transform) and
[`partial_fit_transform`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.partial_fit_transform). Historical rows are computed as-of each observation:
for horizon $h$ and signal lag $\ell$, alpha at observation $t$
uses coefficient updates from signal observations up to $t - \ell - h + 1$.

* **Parameters:**
  **descriptors** *list of (name, estimator) tuples*
  : List of descriptors that compute signals from characteristics. Each tuple
    contains a string name and a descriptor estimator. Multiple descriptors are
    aggregated into a single alpha using multivariate regression. The descriptors
    are evaluated in parallel if `n_jobs > 1`.

  **half_life** *float, default=20*
  : Half-life of the exponential weights in number of observations.
    * Larger half-life: More stable alpha estimates, slower adaptation
    * Smaller half-life: More responsive estimates, faster adaptation

  **horizon** *int, default=1*
  : Number of forward periods to average for the target idiosyncratic return.
    Must be >= 1. The target for observation $t$ is
    `mean(idio_returns[t+signal_lag : t+signal_lag+horizon])`.
    * `horizon=1`: Predicts one-period idiosyncratic return starting after `signal_lag`
    * `horizon>1`: Predicts the mean of `horizon` idiosyncratic returns starting
      after `signal_lag`.

  **signal_lag** *int, default=1*
  : Number of periods between the signal observation and the first return in the
    target window. Must be >= 1. Under skfolio’s as-of time-indexing convention,
    `signal_lag=0` would use information observed at the end of $t$ to predict
    return at $t$, which is look-ahead. Values larger than 1 can model
    conservative data availability or execution delays.

  **neutralize_against** *list of str, optional*
  : Factor names or families to neutralize scores against. If provided, scores are
    orthogonalized with respect to the specified factor exposures before regression.

  **outlier_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for descriptor outlier handling. If None, defaults
    to `CSWinsorizer()`. Use “passthrough” to skip.

  **scoring_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for descriptor scoring applied after outlier
    handling. If None, defaults to `CSStandardScaler()`. Use “passthrough” to skip.

  **transform_by_group** *str, optional*
  : Name of a categorical characteristic in the AssetPanel to use for group-wise
    transformations. If provided, outlier and scoring transformations are applied
    within each group separately.

  **forecast_unit** *ForecastUnit, default=ForecastUnit.IDIO_RETURN*
  : Unit of the intermediate forecast learned from descriptor scores. With
    `ForecastUnit.IDIO_RETURN`, the target is the forward mean idiosyncratic return
    and WLS weights are inverse idiosyncratic variance. With
    `ForecastUnit.IDIO_SHARPE`, the target is divided by forecast idiosyncratic
    volatility and fitted with unit weights. The resulting idiosyncratic-Sharpe
    forecast is converted back to return units by multiplying by current
    idiosyncratic volatility.

  **forecast_scale** *float, default=1.0*
  : Multiplicative scale applied to the final alpha forecast after the learned
    coefficients have been converted to expected return units. This controls alpha
    strength without changing the EWLS coefficient estimates.

  **normalize_weights** *bool, default=True*
  : If `True`, regression weights are normalized within each observation to have an
    average of one across valid assets. This removes changes in aggregate weight
    caused by the scale of idiosyncratic variances, while preserving the greater
    statistical weight of observations with more valid assets. In practice, this
    prevents calm, low-volatility regimes from mechanically dominating the EWLS
    statistics just because inverse-variance weights are larger in those regimes.
    Set `normalize_weights=False` for the unnormalized GLS estimator (which is
    BLUE under the usual assumptions).

  **ridge_scale** *float, default=1e-6*
  : Relative ridge penalty applied to the exponentially weighted normal matrix.

  **n_jobs** *int, default=1*
  : Number of parallel jobs for descriptor computation. Use `-1` for all available
    cores.
* **Attributes:**
  **alpha_** *ndarray of shape (n_assets,) or None*
  : Estimated alpha (expected idiosyncratic return) for each asset. This is the
    aggregated prediction from all signals. Returns `None` during warmup phase
    (fewer than `signal_lag + horizon` observations).

  **coef_** *ndarray of shape (n_descriptors,)*
  : Estimated descriptor coefficients.

  **descriptors_** *list of BaseDescriptor*
  : Fitted descriptor estimators.

  **named_descriptors_** *dict of {str: BaseDescriptor}*
  : Dictionary mapping descriptor names to fitted estimators.

  **outlier_transformer_** *BaseCSTransformer or str*
  : The fitted outlier transformer.

  **scoring_transformer_** *BaseCSTransformer or str*
  : The fitted scoring transformer.

  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.fit)(X[, y])                   | Fit the alpha model.                                                         |
|--------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.fit_transform)(X[, y])         | Fit the alpha model and return historical alpha forecasts.                   |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.get_metadata_routing)()        | Return metadata routing for descriptor estimators.                           |
| [`get_params`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.get_params)([deep])            | Get the parameters of an estimator from the ensemble.                        |
| [`partial_fit`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.partial_fit)(X[, y])           | Incrementally fit the alpha model with new observations.                     |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.partial_fit_transform)(X[, y]) | Incrementally fit the alpha model and return new historical alpha forecasts. |
| [`set_params`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha.set_params)(\*\*params)        | Set the parameters of a factor from the ensemble.                            |

### Notes

The Information Ratio (IR) of a strategy is approximately [[1]](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#r21b9913a35b8-1):

$$
\text{IR} \approx \text{IC} \times \sqrt{\text{Breadth}}
$$

This estimator generalizes single-signal IC weighting by estimating multivariate,
risk-weighted signal payoffs. The exponential weighting and ridge stabilization
reduce turnover and estimation noise in the coefficients.

### References

* <a id='r21b9913a35b8-1'>**[1]**</a> “Active Portfolio Management: A Quantitative Approach for Producing Superior Returns and Controlling Risk”, McGraw-Hill, Grinold & Kahn (1999).

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.alpha import EWSharpeOptimalAlpha, ForecastUnit
>>> from skfolio.descriptor import EWMomentum, BookToPrice, Reversal, Passthrough
>>>
>>> X = make_synthetic_characteristics(
...     n_assets=100, n_observations=504, n_industries=5, random_state=0
... )
>>> rng = np.random.default_rng(0)
>>>
>>> # Alpha models regress forward idiosyncratic returns. In production these
>>> # come from a fitted CharacteristicsFactorModel.
>>> idio_returns = rng.standard_normal((X.n_observations, X.n_assets))
>>> idio_returns[~X.active_mask] = np.nan
>>> X["idio_returns"] = idio_returns
>>>
>>> # Required when forecast_unit=ForecastUnit.IDIO_SHARPE to scale targets and alphas.
>>> idio_variances = rng.uniform(0.01, 0.05, (X.n_observations, X.n_assets))
>>> idio_variances[~X.active_mask] = np.nan
>>> X["idio_variances"] = idio_variances
>>>
>>> # Required when neutralize_against is set. In production these are factor
>>> # exposures from the characteristics factor model.
>>> exposures = rng.standard_normal((X.n_observations, X.n_assets, 3))
>>> exposures[~X.active_mask] = np.nan
>>> X.add_3d_field(
...     "exposures",
...     exposures,
...     third_axis_name="factors",
...     third_axis_labels=["market", "beta", "size"],
... )
AssetPanel(n_observations=504, n_assets=100, n_fields=25)
>>>
>>> alpha_model = EWSharpeOptimalAlpha(
...     descriptors=[
...         ("momentum", EWMomentum()),
...         ("book_to_price", BookToPrice()),
...         ("reversal", Reversal()),
...         ("eps_ntm", Passthrough("eps_ntm")),
...     ],
...     horizon=5,      # one-week forward idiosyncratic return
...     half_life=21,    # one-month EWLS half-life
...     neutralize_against=["market", "beta", "size"],
...     forecast_unit=ForecastUnit.IDIO_SHARPE,
... )
>>>
>>> # Latest alpha forecast for the current rebalance.
>>> alpha_model.fit(X[:-5])
EWSharpeOptimalAlpha(...)
>>> # Preview five forecasts; NaN means no forecast is available.
>>> print(alpha_model.alpha_[:5])
[ 0.00649... nan        -0.0216... 0.00358... nan]
>>>
>>> # Update with the next five observations
>>> alpha_model.partial_fit(X[-5:])
EWSharpeOptimalAlpha(...)
>>> print(alpha_model.alpha_[:5])
[ 0.00837... nan        -0.0341... 0.0222...  nan]
>>>
>>> # Historical as-of alpha forecasts with fit_transform
>>> alphas = alpha_model.fit_transform(X)
>>> alphas.shape
(504, 100)
```

<a id="skfolio.alpha.EWSharpeOptimalAlpha.fit"></a>

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

Fit the alpha model.

Resets all internal state, processes the provided panel and stores the latest
alpha forecast in `alpha_`.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing “idio_returns”, “idio_variances”, descriptor
    fields and optionally “exposures” for score neutralization.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters passed to descriptors through metadata routing.
* **Returns:**
  **self** *EWSharpeOptimalAlpha*
  : Fitted estimator.

<a id="skfolio.alpha.EWSharpeOptimalAlpha.fit_transform"></a>

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

Fit the alpha model and return historical alpha forecasts.

The returned alpha at observation $t$ only uses coefficient updates whose
forward-return target is observable by $t$. Warmup rows are `NaN`.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing “idio_returns”, “idio_variances”, descriptor
    fields and optionally “exposures” for score neutralization.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters passed to descriptors through metadata routing.
* **Returns:**
  **alphas** *ndarray of shape (n_observations, n_assets)*
  : Historical alpha forecasts for the input panel.

<a id="skfolio.alpha.EWSharpeOptimalAlpha.get_metadata_routing"></a>

#### get_metadata_routing()

Return metadata routing for descriptor estimators.

<a id="skfolio.alpha.EWSharpeOptimalAlpha.get_params"></a>

#### get_params(deep=True)

Get the parameters of an estimator from the ensemble.

Returns the parameters given in the constructor as well as the
estimators contained within the `estimators` parameter.

* **Parameters:**
  **deep** *bool, default=True*
  : Setting it to True gets the various estimators and the parameters
    of the estimators as well.
* **Returns:**
  **params** *dict*
  : Parameter and estimator names mapped to their values or parameter
    names mapped to their values.

<a id="skfolio.alpha.EWSharpeOptimalAlpha.named_descriptors"></a>

#### *property* named_descriptors

Dictionary to access any fitted factors by name.

* **Returns:**
  `Bunch`

<a id="skfolio.alpha.EWSharpeOptimalAlpha.partial_fit"></a>

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

Incrementally fit the alpha model with new observations.

This method supports streaming/online updates. It maintains internal buffers to
compute forward returns across partial_fit calls.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing “idio_returns”, “idio_variances”, descriptor
    fields and optionally “exposures” for score neutralization.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters passed to descriptors through metadata routing.
* **Returns:**
  **self** *EWSharpeOptimalAlpha*
  : Fitted estimator.

<a id="skfolio.alpha.EWSharpeOptimalAlpha.partial_fit_transform"></a>

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

Incrementally fit the alpha model and return new historical alpha forecasts.

Only rows corresponding to the newly supplied observations are returned.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing “idio_returns”, “idio_variances”, descriptor
    fields and optionally “exposures” for score neutralization.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters passed to descriptors through metadata routing.
* **Returns:**
  **alphas** *ndarray of shape (n_observations, n_assets)*
  : Historical alpha forecasts for the new observations.

<a id="skfolio.alpha.EWSharpeOptimalAlpha.set_params"></a>

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

Set the parameters of a factor from the ensemble.

Valid parameter keys can be listed with `get_params()`. Note that you
can directly set the parameters of the estimators contained in
`estimators`.

* **Parameters:**
  **\*\*params** *keyword arguments*
  : Specific parameters using e.g.
    `set_params(parameter_name=new_value)`. In addition, to setting the
    parameters of the estimator, the individual estimator of the
    estimators can also be set, or can be removed by setting them to
    ‘drop’.
* **Returns:**
  **self** *object*
  : Estimator instance.

# generated/skfolio.alpha.FixedWeightedAlpha.html.md

<a id="skfolio-alpha-fixedweightedalpha"></a>

# skfolio.alpha.FixedWeightedAlpha

<a id="skfolio.alpha.FixedWeightedAlpha"></a>

### *class* skfolio.alpha.FixedWeightedAlpha(\*, descriptors, forecast_scale, weights=None, forecast_unit=IDIO_RETURN, min_coverage=0.0, neutralize_against=None, outlier_transformer=None, scoring_transformer=None, transform_by_group=None, n_jobs=1)

Fixed-weighted descriptor alpha estimator.

This estimator converts descriptors into cross-sectional scores, optionally
neutralizes the scores against factor exposures, and combines them with fixed
weights to produce an alpha forecast in expected return units.

Unlike [`EWSharpeOptimalAlpha`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha), the descriptor weights and forecast scale are
not estimated from realized returns. They are fixed hyperparameters of the
estimator.

For descriptor score $s_{k,i}$ and signed fixed weight $w_k$, the
composite score for asset $i$ is:

$$
z_i = \frac{\sum_{k \in V_i} w_k s_{k,i}}
           {\sum_{k \in V_i} |w_k|}
$$

where $V_i$ is the set of descriptors with finite scores for asset
$i$. The forecast in the selected `forecast_unit` is:

$$
\hat y_i = \text{forecast\_scale} \, z_i
$$

With `forecast_unit=ForecastUnit.IDIO_RETURN`, the alpha forecast is:

$$
\alpha_i = \hat y_i
$$

With `forecast_unit=ForecastUnit.IDIO_SHARPE`, the forecast is converted to
expected return units:

$$
\alpha_i = \sigma_i \hat y_i
$$

where $\sigma_i$ is the forecast idiosyncratic volatility.

* **Parameters:**
  **descriptors** *list of (name, estimator) tuples*
  : List of descriptors that compute signals from characteristics.

  **weights** *array-like of shape (n_descriptors,), optional*
  : Signed descriptor weights. If `None`, equal positive weights are used. Weights
    are normalized by their absolute sum. When some descriptor scores are missing,
    the composite score is renormalized over the available absolute weight.

  **forecast_scale** *float*
  : Multiplicative scale applied to the composite score in `forecast_unit`. With
    `ForecastUnit.IDIO_RETURN`, this is expected idiosyncratic return per score
    unit. With `ForecastUnit.IDIO_SHARPE`, this is idiosyncratic Sharpe per score
    unit.

  **forecast_unit** *ForecastUnit, default=ForecastUnit.IDIO_RETURN*
  : Unit of the fixed forecast before conversion to `alpha_`. The `alpha_`
    attribute is always returned in expected return units. With
    `ForecastUnit.IDIO_SHARPE`, `idio_variances` are required and the forecast is
    multiplied by current idiosyncratic volatility.

  **min_coverage** *float, default=0.0*
  : Minimum fraction of absolute descriptor weight that must be finite for the
    composite score to be computed. Values where available absolute weight is below
    this threshold are set to `NaN`. Must be in `[0, 1]`.

  **neutralize_against** *list of str, optional*
  : Factor names or families to neutralize scores against.

  **outlier_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for descriptor outlier handling. If `None`,
    defaults to `CSWinsorizer()`. Use `"passthrough"` to skip.

  **scoring_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for descriptor scoring applied after outlier
    handling. If `None`, defaults to `CSStandardScaler()`. Use `"passthrough"` to
    skip.

  **transform_by_group** *str, optional*
  : Name of a categorical characteristic in the AssetPanel to use for group-wise
    transformations.

  **n_jobs** *int, default=1*
  : Number of parallel jobs for descriptor computation.
* **Attributes:**
  [`named_descriptors`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha.named_descriptors)
  : Dictionary to access any fitted factors by name.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha.fit)(X[, y])                   | Fit descriptors and store the latest alpha forecast in `alpha_`.      |
|--------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha.fit_transform)(X[, y])         | Fit descriptors and return historical alpha forecasts.                |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha.get_metadata_routing)()        | Return metadata routing for descriptor estimators.                    |
| [`get_params`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha.get_params)([deep])            | Get the parameters of an estimator from the ensemble.                 |
| [`partial_fit`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha.partial_fit)(X[, y])           | Incrementally update descriptors and store the latest alpha forecast. |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha.partial_fit_transform)(X[, y]) | Incrementally update descriptors and return new alpha forecasts.      |
| [`set_params`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha.set_params)(\*\*params)        | Set the parameters of a factor from the ensemble.                     |

<a id="skfolio.alpha.FixedWeightedAlpha.fit"></a>

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

Fit descriptors and store the latest alpha forecast in `alpha_`.

<a id="skfolio.alpha.FixedWeightedAlpha.fit_transform"></a>

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

Fit descriptors and return historical alpha forecasts.

<a id="skfolio.alpha.FixedWeightedAlpha.get_metadata_routing"></a>

#### get_metadata_routing()

Return metadata routing for descriptor estimators.

<a id="skfolio.alpha.FixedWeightedAlpha.get_params"></a>

#### get_params(deep=True)

Get the parameters of an estimator from the ensemble.

Returns the parameters given in the constructor as well as the
estimators contained within the `estimators` parameter.

* **Parameters:**
  **deep** *bool, default=True*
  : Setting it to True gets the various estimators and the parameters
    of the estimators as well.
* **Returns:**
  **params** *dict*
  : Parameter and estimator names mapped to their values or parameter
    names mapped to their values.

<a id="skfolio.alpha.FixedWeightedAlpha.named_descriptors"></a>

#### *property* named_descriptors

Dictionary to access any fitted factors by name.

* **Returns:**
  `Bunch`

<a id="skfolio.alpha.FixedWeightedAlpha.partial_fit"></a>

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

Incrementally update descriptors and store the latest alpha forecast.

<a id="skfolio.alpha.FixedWeightedAlpha.partial_fit_transform"></a>

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

Incrementally update descriptors and return new alpha forecasts.

<a id="skfolio.alpha.FixedWeightedAlpha.set_params"></a>

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

Set the parameters of a factor from the ensemble.

Valid parameter keys can be listed with `get_params()`. Note that you
can directly set the parameters of the estimators contained in
`estimators`.

* **Parameters:**
  **\*\*params** *keyword arguments*
  : Specific parameters using e.g.
    `set_params(parameter_name=new_value)`. In addition, to setting the
    parameters of the estimator, the individual estimator of the
    estimators can also be set, or can be removed by setting them to
    ‘drop’.
* **Returns:**
  **self** *object*
  : Estimator instance.

# generated/skfolio.alpha.ForecastUnit.html.md

<a id="skfolio-alpha-forecastunit"></a>

# skfolio.alpha.ForecastUnit

<a id="skfolio.alpha.ForecastUnit"></a>

### *class* skfolio.alpha.ForecastUnit(\*values)

Unit of the intermediate alpha forecast.

<a id="skfolio.alpha.ForecastUnit.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.alpha.PredictorAlpha.html.md

<a id="skfolio-alpha-predictoralpha"></a>

# skfolio.alpha.PredictorAlpha

<a id="skfolio.alpha.PredictorAlpha"></a>

### *class* skfolio.alpha.PredictorAlpha(\*, predictor, descriptors, horizon=1, signal_lag=1, neutralize_against=None, outlier_transformer=None, scoring_transformer=None, target_outlier_transformer=None, target_scoring_transformer=None, transform_by_group=None, forecast_unit=IDIO_RETURN, calibrate_to_return_units=True, forecast_scale=1.0, half_life=20, cv=None, n_jobs=1)

Predictor alpha estimator using a user-provided regressor.

This estimator converts descriptors into cross-sectional scores, optionally
neutralizes those scores against factor exposures and fits a scikit-learn compatible
regressor where each observation-asset pair is one training sample. It supports
nonlinear signal combinations while keeping the final forecast in expected
idiosyncratic return units when calibration is enabled [[1]](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#r221c08910397-1).

The predictor supports two forecast units. With
`forecast_unit=ForecastUnit.IDIO_RETURN`, it is fitted to the forward mean
idiosyncratic return $\epsilon_{t,i}$. With
`forecast_unit=ForecastUnit.IDIO_SHARPE`, it is fitted to
$\epsilon_{t,i} / \sigma_{t,i}$ and the forecast is multiplied by current
idiosyncratic volatility so `alpha_` remains in expected return units. This is
useful when signals are assumed to forecast idiosyncratic Sharpe rather than raw
idiosyncratic return.

When `calibrate_to_return_units=True`, the raw predictor output
$\hat a_{t,i}$ is calibrated to expected-return units with scalar
exponentially weighted least squares:

$$
\beta_t = \arg\min_\beta \sum_i
\frac{(\epsilon_{t,i} - \hat a_{t,i}\beta)^2}{\sigma_{t,i}^2}
$$

The calibration coefficient is estimated with exponentially weighted least squares:

$$
A_t^{EW} = \lambda A_{t-1}^{EW}
+ (1 - \lambda)\hat a_t^\top W_t \hat a_t
$$

$$
b_t^{EW} = \lambda b_{t-1}^{EW}
+ (1 - \lambda)\hat a_t^\top W_t \epsilon_t,
\quad \lambda = 2^{-1/\text{half-life}}
$$

and the ridge-stabilized coefficient is:

$$
\beta_t = b_t^{EW} / (A_t^{EW} + \rho_t)
$$

This produces alpha in expected return units, which is required whenever the
optimizer is trading off alpha against real costs and constraints such as
transaction costs, market impact, borrow costs, or turnover constraints.

In batch mode, calibration uses predictions from held-out CV folds when enough
samples are available. This reduces the in-sample scale inflation from fitting
and calibrating on the same predictions. These predictions are used only for
scale calibration, not as a time-series performance estimate. The default splitter
treats valid observation-asset pairs as approximately exchangeable. Pass a
date-aware or purged splitter through `cv` when the calibration itself should
enforce stricter temporal separation.

The estimator supports [`fit`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha.fit) and [`partial_fit`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha.partial_fit). In online mode,
samples are trained when their forward-return targets become observable,
including rows carried in the target-maturity buffer. The predictor must
support `partial_fit` after the first fitted update.

* **Parameters:**
  **predictor** *estimator*
  : Regressor that implements `fit` and `predict`. For online mode, the predictor
    must also implement `partial_fit`. The predictor receives one sample per valid
    observation-asset pair, with shape `(n_observations * n_assets, n_descriptors)`,
    and predicts the transformed target.

  **descriptors** *list of (name, estimator) tuples*
  : List of descriptors that compute signals from characteristics. Each tuple
    contains a string name and a descriptor estimator. Multiple descriptors are
    aggregated into a single alpha using multivariate regression. The descriptors
    are evaluated in parallel if `n_jobs > 1`.

  **half_life** *float, default=20*
  : Half-life of the EWLS calibration statistics in number of observations. Only
    used when `calibrate_to_return_units=True`.
    * Larger half-life: More stable alpha estimates, slower adaptation
    * Smaller half-life: More responsive estimates, faster adaptation

  **horizon** *int, default=1*
  : Number of forward periods to average for the target idiosyncratic return.
    Must be >= 1. The target for observation $t$ is
    `mean(idio_returns[t+signal_lag : t+signal_lag+horizon])`.
    * `horizon=1`: Predicts one-period idiosyncratic return starting after `signal_lag`
    * `horizon>1`: Predicts the mean of `horizon` idiosyncratic returns starting
      after `signal_lag`.

  **signal_lag** *int, default=1*
  : Number of periods between the signal observation and the first return in the
    target window. Must be >= 1. Under skfolio’s as-of time-indexing convention,
    `signal_lag=0` would use information observed at the end of $t$ to
    predict return at $t$, which is look-ahead. Values larger than 1 can
    model conservative data availability or execution delays.

  **neutralize_against** *list of str, optional*
  : Factor names or families to neutralize scores against. If provided, scores are
    orthogonalized with respect to the specified factor exposures before prediction.

  **outlier_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for descriptor outlier handling. If `None`,
    defaults to `CSWinsorizer()`. Use `"passthrough"` to skip.

  **scoring_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for descriptor scoring applied after outlier
    handling. If None, defaults to `CSStandardScaler()`. Use “passthrough” to skip.

  **target_outlier_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for target outlier handling. If `None`, defaults
    to `CSWinsorizer()`. Use `"passthrough"` to skip.

  **target_scoring_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for target scoring. If `None`, defaults to
    `"passthrough"`. The calibration stage calibrates the predictor output back
    to expected-return units when `calibrate_to_return_units=True`.

  **transform_by_group** *str, optional*
  : Name of a categorical characteristic in the AssetPanel to use for group-wise
    transformations. If provided, cross-sectional transformations are applied
    within each group separately.

  **forecast_unit** *ForecastUnit, default=ForecastUnit.IDIO_RETURN*
  : Unit of the intermediate forecast learned by the predictor. With
    `ForecastUnit.IDIO_RETURN`, the predictor is trained on forward mean
    idiosyncratic return. With `ForecastUnit.IDIO_SHARPE`, the target is divided by
    forecast idiosyncratic volatility and the resulting idiosyncratic-Sharpe
    forecast is converted back to return units by multiplying by current
    idiosyncratic volatility.

  **calibrate_to_return_units** *bool, default=True*
  : If `True`, calibrate raw predictor output to expected return units using
    scalar EWLS. If `False`, return the predictor output after any volatility
    conversion implied by `forecast_unit`.

  **forecast_scale** *float, default=1.0*
  : Multiplicative scale applied to the final alpha forecast after optional
    return-unit calibration. This controls alpha strength without changing the
    predictor or calibration coefficient estimates.

  **cv** *cross-validator, int, optional*
  : Cross-validation strategy used to obtain predictions from held-out folds for
    return-unit calibration. When `None`, uses `KFold(5)`. CV is used only in
    batch mode when `calibrate_to_return_units=True` and there are enough
    samples.

  **n_jobs** *int, default=1*
  : Number of parallel jobs for descriptor computation and cross-validation.
* **Attributes:**
  **alpha_** *ndarray of shape (n_assets,) or None*
  : Estimated alpha for each asset, after applying `forecast_scale`. If
    `calibrate_to_return_units=True`, this is in expected return units. Otherwise,
    it is the predictor output after any volatility conversion. Returns `None`
    during warmup.

  **predictor_** *estimator*
  : Fitted predictor instance.

  **descriptors_** *list of BaseDescriptor*
  : Fitted descriptor estimators.

  **named_descriptors_** *dict of {str: BaseDescriptor}*
  : Dictionary mapping descriptor names to fitted estimators.

  **outlier_transformer_** *BaseCSTransformer or str*
  : Fitted descriptor outlier transformer.

  **scoring_transformer_** *BaseCSTransformer or str*
  : Fitted descriptor scoring transformer.

  **target_outlier_transformer_** *BaseCSTransformer or str*
  : Fitted target outlier transformer.

  **target_scoring_transformer_** *BaseCSTransformer or str*
  : Fitted target scoring transformer.

  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray*
  : Names of assets in the coverage universe.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha.fit)(X[, y])            | Fit the alpha model from scratch (batch mode).                         |
|-------------------------------------------------------------------------|------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha.get_metadata_routing)() | Return metadata routing for descriptors and the predictor.             |
| [`get_params`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha.get_params)([deep])     | Get the parameters of an estimator from the ensemble.                  |
| [`partial_fit`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha.partial_fit)(X[, y])    | Incrementally fit the alpha model with new observations (online mode). |
| [`set_params`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha.set_params)(\*\*params) | Set the parameters of a factor from the ensemble.                      |

#### SEE ALSO
[`EWSharpeOptimalAlpha`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha)
: Linear signal aggregation with Sharpe-optimal WLS weighting.

### References

* <a id='r221c08910397-1'>**[1]**</a> “Active Portfolio Management: A Quantitative Approach for Producing Superior Returns and Controlling Risk”, McGraw-Hill, Grinold & Kahn (1999).

### Examples

```pycon
>>> import numpy as np
>>> from sklearn.linear_model import SGDRegressor
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.alpha import ForecastUnit, PredictorAlpha
>>> from skfolio.descriptor import EWMomentum, BookToPrice, Reversal, Passthrough
>>>
>>> X = make_synthetic_characteristics(
...     n_assets=100, n_observations=504, n_industries=5, random_state=0
... )
>>> rng = np.random.default_rng(0)
>>>
>>> # Alpha models regress forward idiosyncratic returns. In production these
>>> # come from a fitted CharacteristicsFactorModel.
>>> idio_returns = rng.standard_normal((X.n_observations, X.n_assets))
>>> idio_returns[~X.active_mask] = np.nan
>>> X["idio_returns"] = idio_returns
>>>
>>> # Required when forecast_unit=ForecastUnit.IDIO_SHARPE to scale targets and alphas.
>>> idio_variances = rng.uniform(0.01, 0.05, (X.n_observations, X.n_assets))
>>> idio_variances[~X.active_mask] = np.nan
>>> X["idio_variances"] = idio_variances
>>>
>>> # Required when neutralize_against is set. In production these are factor
>>> # exposures from the characteristics factor model.
>>> exposures = rng.standard_normal((X.n_observations, X.n_assets, 3))
>>> exposures[~X.active_mask] = np.nan
>>> X.add_3d_field(
...     "exposures",
...     exposures,
...     third_axis_name="factors",
...     third_axis_labels=["market", "beta", "size"],
... )
AssetPanel(n_observations=504, n_assets=100, n_fields=25)
>>>
>>> alpha_model = PredictorAlpha(
...     predictor=SGDRegressor(random_state=0),
...     descriptors=[
...         ("momentum", EWMomentum()),
...         ("book_to_price", BookToPrice()),
...         ("reversal", Reversal()),
...         ("eps_ntm", Passthrough("eps_ntm")),
...     ],
...     horizon=5,
...     half_life=21,
...     neutralize_against=["market", "beta", "size"],
...     forecast_unit=ForecastUnit.IDIO_SHARPE,
... )
>>>
>>> alpha_model.fit(X[:-5])
PredictorAlpha(...)
>>> # Preview five forecasts; NaN means no forecast is available.
>>> print(alpha_model.alpha_[:5])
[-0.000494... nan          0.000636...  -0.000259... nan]
>>>
>>> # Update with the next five observations (requires partial_fit support)
>>> alpha_model.partial_fit(X[-5:])
PredictorAlpha(...)
>>> print(alpha_model.alpha_[:5])
[-0.00538... nan         0.0129...   0.00477...  nan]
```

<a id="skfolio.alpha.PredictorAlpha.fit"></a>

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

Fit the alpha model from scratch (batch mode).

This method works with any sklearn-compatible predictor. It resets all
internal state and fits on the provided data. When calibration is enabled,
predictions from held-out CV folds can be used to calibrate the return-unit
scale.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing “idio_returns”, descriptor fields and optionally
    “idio_variances” for calibration or volatility-scaled targets, and
    “exposures” for score neutralization.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters passed to descriptors and predictor.
* **Returns:**
  **self** *PredictorAlpha*
  : Fitted estimator.

<a id="skfolio.alpha.PredictorAlpha.get_metadata_routing"></a>

#### get_metadata_routing()

Return metadata routing for descriptors and the predictor.

<a id="skfolio.alpha.PredictorAlpha.get_params"></a>

#### get_params(deep=True)

Get the parameters of an estimator from the ensemble.

Returns the parameters given in the constructor as well as the
estimators contained within the `estimators` parameter.

* **Parameters:**
  **deep** *bool, default=True*
  : Setting it to True gets the various estimators and the parameters
    of the estimators as well.
* **Returns:**
  **params** *dict*
  : Parameter and estimator names mapped to their values or parameter
    names mapped to their values.

<a id="skfolio.alpha.PredictorAlpha.named_descriptors"></a>

#### *property* named_descriptors

Dictionary to access any fitted factors by name.

* **Returns:**
  `Bunch`

<a id="skfolio.alpha.PredictorAlpha.partial_fit"></a>

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

Incrementally fit the alpha model with new observations (online mode).

This method supports streaming/online updates. It maintains internal
buffers to compute forward returns across partial_fit calls. Only samples
whose targets have newly matured are used for training, avoiding
double-counting while still training buffered rows once their labels are
observable.

On the first call, the predictor is trained using `fit()`. On subsequent
calls, the predictor is updated using `partial_fit()`, which requires
the predictor to support this method.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing “idio_returns”, descriptor fields and optionally
    “idio_variances” for calibration or volatility-scaled targets, and
    “exposures” for score neutralization.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters passed to descriptors and predictor.
* **Returns:**
  **self** *PredictorAlpha*
  : Fitted estimator.
* **Raises:**
  TypeError
  : If the predictor does not support `partial_fit` (raised on second
    or subsequent calls).

<a id="skfolio.alpha.PredictorAlpha.set_params"></a>

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

Set the parameters of a factor from the ensemble.

Valid parameter keys can be listed with `get_params()`. Note that you
can directly set the parameters of the estimators contained in
`estimators`.

* **Parameters:**
  **\*\*params** *keyword arguments*
  : Specific parameters using e.g.
    `set_params(parameter_name=new_value)`. In addition, to setting the
    parameters of the estimator, the individual estimator of the
    estimators can also be set, or can be removed by setting them to
    ‘drop’.
* **Returns:**
  **self** *object*
  : Estimator instance.

# generated/skfolio.alpha.alpha_forecast_evaluation.html.md

<a id="skfolio-alpha-alpha-forecast-evaluation"></a>

# skfolio.alpha.alpha_forecast_evaluation

<a id="skfolio.alpha.alpha_forecast_evaluation"></a>

### skfolio.alpha.alpha_forecast_evaluation(estimator, X, \*, target='idio_returns', holding_period=1, signal_lag=1, evaluation_step=None, n_forward_periods=10, cs_weighting=IDENTITY, factor_exposures='exposures', factor_correlation_method=PEARSON, quantiles=(0.1,), annualization_factor=252.0, min_count=3, params=None, name=None)

Evaluate alpha forecast quality.

The function fits `estimator` with `fit_transform`, obtains historical
alpha forecasts, and compares them with a forward mean target built from an
`AssetPanel` field. The default target is `idio_returns`, which evaluates
the idiosyncratic component forecast by the alpha estimators used by
[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel).

The diagnostics evaluate alpha forecasts before the alpha is passed to an
optimizer. IC measures cross-sectional ordering and Pearson correlation.
Simple rank-weighted and z-score-weighted portfolios measure the realized
target return of 200% gross alpha-only long-short portfolios. The
calibration slope estimates the scale multiplier needed to map forecast
values to realized target units.
Holding-period diagnostics evaluate the same forecasts against cumulative
target windows. Decay diagnostics evaluate the same forecasts against
disjoint future target windows.
Diagnostics are computed on the final alpha forecast returned by the
estimator. For rank-transformed forecasts, `pearson_ic` and
`zscore_weighted_portfolio` evaluate the transformed rank scores, not raw
descriptor magnitudes. If `factor_exposures` is available and
`factor_correlation_method` is not `None`, the evaluation also measures
contemporaneous correlation between the alpha forecast and factor exposures.
Holding-period and decay diagnostics use the same evaluation dates as the
main evaluation.

For example, with `holding_period=5`, `signal_lag=1` and
`n_forward_periods=3`, `decay_summary` computes IC on disjoint windows:
$corr(\alpha_t, \bar{y}_{t+1:t+5})$,
$corr(\alpha_t, \bar{y}_{t+6:t+10})$ and
$corr(\alpha_t, \bar{y}_{t+11:t+15})$.
`holding_period_summary` computes IC on cumulative windows:
$corr(\alpha_t, \bar{y}_{t+1:t+5})$,
$corr(\alpha_t, \bar{y}_{t+1:t+10})$ and
$corr(\alpha_t, \bar{y}_{t+1:t+15})$.
With `holding_period=5` and `n_forward_periods=79`, the last cumulative
window is $corr(\alpha_t, \bar{y}_{t+1:t+395})$.

* **Parameters:**
  **estimator** *BaseEstimator or Pipeline*
  : Alpha estimator exposing `fit_transform` and returning historical alpha
    forecasts with shape `(n_observations, n_assets)`.

  **X** *AssetPanel or AssetPanelView*
  : Point-in-time asset panel containing `target` and all fields required by
    `estimator`.

  **target** *str, default=”idio_returns”*
  : Name of the 2D target field in `X`.

  **holding_period** *int, default=1*
  : Number of observations in the forward target window used for the main
    evaluation. For a forecast at date $t$, the target is the mean
    value over $[t + \ell, t + \ell + h)$, where $\ell$ is
    `signal_lag` and $h$ is `holding_period`.

  **signal_lag** *int, default=1*
  : Number of observations between the forecast date and the first target
    observation. `signal_lag=1` evaluates next-period targets and avoids
    same-period look-ahead when forecasts are observed after the current
    target is known. `signal_lag=0` evaluates same-period targets.

  **evaluation_step** *int, optional*
  : Spacing between evaluated forecast dates. The default `None` uses
    `holding_period`, which produces mostly non-overlapping target windows
    for the main evaluation. `evaluation_step=1` evaluates every valid
    forecast date, which is common for signal research and creates
    overlapping forward targets when `holding_period > 1`. Values greater
    than `holding_period` produce a sparse evaluation. When
    `evaluation_step < holding_period`, summary means remain descriptive
    diagnostics, but IC t-statistics and IR should be interpreted with the
    serial dependence from overlapping targets in mind.

  **n_forward_periods** *int, default=10*
  : Number of consecutive forward periods used for holding-period and decay
    diagnostics. `holding_period_summary` evaluates cumulative windows from
    $1 \times h$ to $n \times h$. `decay_summary` evaluates
    $n$ disjoint forward windows of length $h$, where
    $h$ is `holding_period` and $n$ is `n_forward_periods`.

  **cs_weighting** *CSWeighting or str, default=CSWeighting.IDENTITY*
  : Cross-sectional weighting for Pearson IC and the calibration scale
    multiplier. A string is interpreted as a 2D field name in `X`.
    Descriptive forecast, target and calibration-curve statistics are
    unweighted.

  **factor_exposures** *str, optional, default=”exposures”*
  : Name of a 3D field in `AssetPanel` `X` containing factor exposures
    used to compute alpha-factor correlation diagnostics. If the default
    field is not present, factor correlation diagnostics are skipped.
    Passing `None` skips them explicitly.

  **factor_correlation_method** *CorrelationMethod, optional, default=CorrelationMethod.PEARSON*
  : Factor correlation method to compute. `PEARSON` measures linear tilt
    of forecast values to factor exposures and is weighted by
    `cs_weighting`. `SPEARMAN` measures monotonic alignment of forecast
    ordering with exposure ordering and is more expensive for large
    exposure tensors. Passing `None` skips factor correlation diagnostics.

  **quantiles** *tuple of float, default=(0.1,)*
  : Forecast quantiles for top-minus-bottom spread diagnostics. Each value
    must be in `(0, 0.5]`.

  **annualization_factor** *float, default=252.0*
  : Number of observations per year used to annualize return statistics in
    `portfolio_summary` and `quantile_summary`.

  **min_count** *int, default=3*
  : Minimum number of valid assets required for each cross-sectional
    diagnostic.

  **params** *dict, optional*
  : Parameters routed to `estimator.fit_transform`.

  **name** *str, optional*
  : Display name for the evaluation. Defaults to `str(estimator)`.
* **Returns:**
  **evaluation** *AlphaForecastEvaluation*
  : Frozen dataclass with diagnostic series, summary statistics and plots.

# generated/skfolio.attribution.AssetBreakdown.html.md

<a id="skfolio-attribution-assetbreakdown"></a>

# skfolio.attribution.AssetBreakdown

<a id="skfolio.attribution.AssetBreakdown"></a>

### *class* skfolio.attribution.AssetBreakdown(names, vol_contrib, pct_total_variance, mu_contrib, weight, weight_std, systematic_vol_contrib, systematic_mu_contrib, idio_vol_contrib, idio_mu_contrib, vol, mu, corr_with_ptf)

Per-asset attribution breakdown.

Decomposes each asset’s volatility and return contribution into systematic and
idiosyncratic components.

For single-point attribution, arrays have shape `(n_assets,)`. For rolling
attribution, arrays have shape `(n_windows, n_assets)`.

* **Attributes:**
  **names** *ndarray of shape (n_assets,)*
  : Asset names. Always 1D.

  **weight** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Portfolio asset weights.

  **weight_std** *ndarray of shape (n_assets,) or (n_windows, n_assets), or None*
  : Standard deviation of asset weights over time. `None` when weights are not
    time-varying.

  **vol_contrib** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Total asset volatility contribution. Sums to `total.vol`.

  **systematic_vol_contrib** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Asset volatility contribution attributed to factor exposures. Sums to
    `systematic.vol_contrib`.

  **idio_vol_contrib** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Asset volatility contribution not attributed to factor exposures. Sums to
    `idio.vol_contrib`.

  **mu_contrib** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Total asset return contribution. Sums to `total.mu`.

  **systematic_mu_contrib** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Asset return contribution attributed to factor exposures. Sums to\`systematic.mu\`.

  **idio_mu_contrib** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Asset return contribution not attributed to factor exposures. Sums to
    `idio.mu`.

  **pct_total_variance** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Percentage of total portfolio variance.

  **vol** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Standalone asset volatility: $\sqrt{(B F B^\top + D)_{ii}}$.

  **mu** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Standalone asset return: expected return for predicted attribution and
    mean return for realized attribution.

  **corr_with_ptf** *ndarray of shape (n_assets,) or (n_windows, n_assets)*
  : Asset correlation with portfolio returns.

# generated/skfolio.attribution.AssetByFactorContribution.html.md

<a id="skfolio-attribution-assetbyfactorcontribution"></a>

# skfolio.attribution.AssetByFactorContribution

<a id="skfolio.attribution.AssetByFactorContribution"></a>

### *class* skfolio.attribution.AssetByFactorContribution(asset_names, factor_names, vol_contrib, mu_contrib)

Asset-by-factor contribution breakdown.

Breaks down factor contributions by asset. Each cell is the contribution of one
asset to one factor’s total contribution.

Summing over assets gives per-factor contributions. Summing over factors gives each
asset’s systematic contribution.

For single-point attribution, arrays have shape `(n_assets, n_factors)`. For rolling
attribution, arrays have shape `(n_windows, n_assets, n_factors)`.

* **Attributes:**
  **asset_names** *ndarray of shape (n_assets,)*
  : Asset names.

  **factor_names** *ndarray of shape (n_factors,)*
  : Factor names.

  **vol_contrib** *ndarray of shape (n_assets, n_factors) or (n_windows, n_assets, n_factors)*
  : Volatility contribution for each asset-factor pair.

  **mu_contrib** *ndarray of shape (n_assets, n_factors) or (n_windows, n_assets, n_factors)*
  : Return contribution for each asset-factor pair.

# generated/skfolio.attribution.Attribution.html.md

<a id="skfolio-attribution-attribution"></a>

# skfolio.attribution.Attribution

<a id="skfolio.attribution.Attribution"></a>

### *class* skfolio.attribution.Attribution(systematic, idio, unattributed, total, factors, families=None, assets=None, asset_by_factor_contrib=None, is_realized=False, observations=None)

Factor attribution result.

Result returned by [`predicted_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.predicted_factor_attribution.html.md#skfolio.attribution.predicted_factor_attribution),
[`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution) or [`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution).

Predicted and realized attribution expose the same decomposition: systematic,
idiosyncratic, total and per-factor attribution. Realized attribution may also
include `unattributed`, the difference between observed portfolio returns and
model-attributed returns. Rolling attribution uses the same fields with numeric
values indexed by `observations`.

* **Attributes:**
  **systematic** *Component*
  : Systematic component. Portfolio risk and return attributed to the portfolio’s
    factor exposures.

  **idio** *Component*
  : Idiosyncratic component. Portfolio risk and return not attributed to the factor
    exposures.

  **unattributed** *Component or None*
  : Difference between observed portfolio returns and model-attributed returns
    (systematic plus idiosyncratic). Captures effects outside the factor model:
    transaction costs, management fees, slippage, cash, intra-period trading
    and, for time-series factor models, the regression intercept. `None` for
    predicted attribution.

  **total** *Component*
  : Total portfolio risk and return after aggregating all attribution components.

  **factors** *FactorBreakdown*
  : Per-factor attribution with exposures, standalone statistics and contributions.

  **families** *FamilyBreakdown or None*
  : Family-aggregated attribution. `None` when factor families are not provided.

  **assets** *AssetBreakdown or None*
  : Per-asset attribution with systematic/idiosyncratic decomposition. `None` when
    asset attribution is not computed.

  **asset_by_factor_contrib** *AssetByFactorContribution or None*
  : Asset-by-factor contribution breakdown. `None` when not computed.

  **is_realized** *bool*
  : True for realized (ex-post), False for predicted (ex-ante).

  **observations** *ndarray or None*
  : Window end labels for rolling attribution. None for single-point.

### Methods

| [`asset_factor_df`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution.asset_factor_df)([metric, formatted, ...])    | Return the asset-by-factor contribution as a DataFrame.   |
|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| [`assets_df`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution.assets_df)([formatted])                       | Return per-asset attribution as a DataFrame.              |
| [`factors_df`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution.factors_df)([formatted, confidence_level])    | Return per-factor attribution as a DataFrame.             |
| [`families_df`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution.families_df)([formatted, confidence_level])   | Return family-aggregated attribution as a DataFrame.      |
| [`plot_exposure`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution.plot_exposure)([by_family, top_n, show_std])  | Plot portfolio factor exposure by factor or family.       |
| [`plot_return_contrib`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution.plot_return_contrib)([by_family, top_n, ...]) | Plot return contribution by factor or family.             |
| [`plot_return_vs_vol_contrib`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution.plot_return_vs_vol_contrib)([by_family, ...]) | Plot return contribution against volatility contribution. |
| [`plot_vol_contrib`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution.plot_vol_contrib)([by_family, top_n, ...])    | Plot volatility contribution by factor or family.         |
| [`summary_df`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution.summary_df)([formatted, confidence_level])    | Return component-level attribution as a DataFrame.        |

<a id="skfolio.attribution.Attribution.asset_factor_df"></a>

#### asset_factor_df(metric='vol_contrib', formatted=True, observation_idx=None)

Return the asset-by-factor contribution as a DataFrame.

* **Parameters:**
  **metric** *{“vol_contrib”, “mu_contrib”}, default=”vol_contrib”*
  : Contribution metric to display.

  **formatted** *bool, default=True*
  : Format values as percentages.

  **observation_idx** *int or None*
  : Observation index. Required for rolling attribution.
* **Returns:**
  DataFrame
  : Matrix with assets as rows and factors as columns.

<a id="skfolio.attribution.Attribution.assets_df"></a>

#### assets_df(formatted=True)

Return per-asset attribution as a DataFrame.

* **Parameters:**
  **formatted** *bool, default=True*
  : Format volatility, return and variance-share columns as percentage strings.
* **Returns:**
  DataFrame
  : Per-asset weights, volatility and return contributions (total/systematic/idiosyncratic).
    Indexed by `Asset` for single-point attribution. For rolling:
    MultiIndex (Observation, Asset).
* **Raises:**
  ValueError
  : If asset attribution was not computed.

<a id="skfolio.attribution.Attribution.factors_df"></a>

#### factors_df(formatted=True, confidence_level=0.95)

Return per-factor attribution as a DataFrame.

* **Parameters:**
  **formatted** *bool, default=True*
  : Format volatility, return and variance-share columns as percentage strings.

  **confidence_level** *float, default=0.95*
  : When `formatted=True` and uncertainty data are present, merges mean return
    contribution with $\mu \pm z \times SE$ into one `(N% CI)` column.
* **Returns:**
  DataFrame
  : Per-factor attribution with exposures, standalone statistics, and
    contributions. Indexed by `Factor` for single-point attribution. For
    rolling: MultiIndex (Observation, Factor).

<a id="skfolio.attribution.Attribution.families_df"></a>

#### families_df(formatted=True, confidence_level=0.95)

Return family-aggregated attribution as a DataFrame.

* **Parameters:**
  **formatted** *bool, default=True*
  : Format volatility, return and variance-share columns as percentage strings.

  **confidence_level** *float, default=0.95*
  : When `formatted=True` and uncertainty data are present, merges mean return
    contribution with $\mu \pm z \times SE$ into one `(N% CI)` column.
* **Returns:**
  DataFrame
  : Family-aggregated exposures and contributions. Indexed by `Family` for
    single-point attribution. For rolling: MultiIndex (Observation, Family).
* **Raises:**
  ValueError
  : If `factor_families` was not provided.

<a id="skfolio.attribution.Attribution.is_rolling"></a>

#### *property* is_rolling

Whether this is rolling attribution (observations is not None).

<a id="skfolio.attribution.Attribution.n_assets"></a>

#### *property* n_assets

Number of assets.

<a id="skfolio.attribution.Attribution.n_factors"></a>

#### *property* n_factors

Number of factors.

<a id="skfolio.attribution.Attribution.n_families"></a>

#### *property* n_families

Number of factor families.

<a id="skfolio.attribution.Attribution.plot_exposure"></a>

#### plot_exposure(by_family=False, top_n=25, show_std=True)

Plot portfolio factor exposure by factor or family.

Single-point attribution shows signed exposure as a bar chart. Rolling
attribution shows exposure through time. For realized attribution,
`show_std=True` displays exposure standard deviation when available:
vertical error bars for single-point charts and +/- 1 standard deviation
bands for rolling charts.

* **Parameters:**
  **by_family** *bool, default=False*
  : Aggregate factors by family.

  **top_n** *int or None, default=25*
  : Maximum number of factors or families to show, sorted by absolute exposure.
    If there are more factors/families than `top_n`, the remaining components
    are aggregated into `Other`.

  **show_std** *bool, default=True*
  : If `True`, display exposure standard deviation when available. This applies
    to realized attribution and is ignored for predicted attribution, where
    exposure standard deviation is not computed.
* **Returns:**
  go.Figure
  : Plotly exposure chart.

<a id="skfolio.attribution.Attribution.plot_return_contrib"></a>

#### plot_return_contrib(by_family=False, top_n=25, include_idio=True, confidence_level=0.95)

Plot return contribution by factor or family.

When realized attribution includes per-factor standard errors
(`mu_contrib_uncertainty`), hover text shows the mean return SE and,
if `confidence_level` is not `None`, the corresponding confidence
interval. Single-point charts display vertical error bars. Rolling
charts display confidence bands around the contribution lines.

* **Parameters:**
  **by_family** *bool, default=False*
  : Aggregate factors by family.

  **top_n** *int or None, default=25*
  : Maximum number of factors or families to show, sorted by absolute
    return contribution.
    If there are more factors/families than `top_n`, the remaining
    components are aggregated into `Other`.

  **include_idio** *bool, default=True*
  : Include idiosyncratic component.

  **confidence_level** *float or None, default=0.95*
  : Confidence level for interval display. If `None`, error bars are
    not drawn and hover text omits the confidence interval line. The
    mean return SE is still shown when uncertainty data exist.
* **Returns:**
  go.Figure
  : Plotly contribution chart.

<a id="skfolio.attribution.Attribution.plot_return_vs_vol_contrib"></a>

#### plot_return_vs_vol_contrib(by_family=False, top_n=25, include_idio=True, size_max=50)

Plot return contribution against volatility contribution.

X-axis: volatility contribution, Y-axis: return contribution.
Factor marker sizes are proportional to absolute exposure.
The idiosyncratic point uses a fixed-size diamond marker when included.
Rolling attribution returns an animated scatter plot over time.

* **Parameters:**
  **by_family** *bool, default=False*
  : Aggregate factors by family.

  **top_n** *int or None, default=25*
  : Maximum number of factors or families to show, sorted by absolute
    volatility contribution.
    If there are more factors/families than `top_n`, the remaining
    components are aggregated into `Other`.

  **include_idio** *bool, default=True*
  : Include idiosyncratic component. Displayed with a diamond marker
    at a fixed size (no exposure-based sizing).

  **size_max** *float, default=50*
  : Maximum marker size for the largest absolute exposure. The
    idiosyncratic marker uses `0.4 * size_max`.
* **Returns:**
  go.Figure
  : Plotly scatter plot. Rolling attribution uses observation labels as
    animation frames.

<a id="skfolio.attribution.Attribution.plot_vol_contrib"></a>

#### plot_vol_contrib(by_family=False, top_n=25, include_idio=True)

Plot volatility contribution by factor or family.

Single-point attribution returns one bar trace. Rolling attribution
returns one line trace per displayed component with observations on the x-axis.

* **Parameters:**
  **by_family** *bool, default=False*
  : Aggregate factors by family.

  **top_n** *int or None, default=25*
  : Maximum number of factors or families to show, sorted by absolute
    volatility contribution.
    If there are more factors/families than `top_n`, the remaining
    components are aggregated into `Other`.

  **include_idio** *bool, default=True*
  : Include idiosyncratic component.
* **Returns:**
  go.Figure
  : Plotly contribution chart.

<a id="skfolio.attribution.Attribution.summary_df"></a>

#### summary_df(formatted=True, confidence_level=0.95)

Return component-level attribution as a DataFrame.

The summary reports volatility contribution, percentage of total variance and
return contribution for the systematic, idiosyncratic, optional unattributed,
and total components.

* **Parameters:**
  **formatted** *bool, default=True*
  : Format volatility, return and variance-share columns as percentage strings.

  **confidence_level** *float, default=0.95*
  : When `formatted=True` and uncertainty data are present, the mean return
    contribution is shown in one `{label} Contribution (N% CI)` column with
    values $\mu \pm z \times SE$.
* **Returns:**
  DataFrame
  : Indexed by `Component` for single-point attribution. Rolling attribution
    returns a MultiIndex with levels `Observation` and `Component`.

# generated/skfolio.attribution.BaseBreakdown.html.md

<a id="skfolio-attribution-basebreakdown"></a>

# skfolio.attribution.BaseBreakdown

<a id="skfolio.attribution.BaseBreakdown"></a>

### *class* skfolio.attribution.BaseBreakdown(names, vol_contrib, pct_total_variance, mu_contrib)

Base class for attribution breakdowns.

Stores common per-item volatility and return contributions for factor, family and
asset attribution breakdowns.

For single-point attribution, numeric fields are 1D arrays of shape `(n_items,)`.
For rolling attribution (from [`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution)), numeric
fields are 2D arrays of shape `(n_windows, n_items)`.

* **Attributes:**
  **names** *ndarray of shape (n_items,)*
  : Item names: factors, families, or assets.

  **vol_contrib** *ndarray of shape (n_items,) or (n_windows, n_items)*
  : Volatility contribution to total portfolio volatility.

  **pct_total_variance** *ndarray of shape (n_items,) or (n_windows, n_items)*
  : Percentage of total portfolio variance.

  **mu_contrib** *ndarray of shape (n_items,) or (n_windows, n_items)*
  : Return contribution to total portfolio return.

# generated/skfolio.attribution.Component.html.md

<a id="skfolio-attribution-component"></a>

# skfolio.attribution.Component

<a id="skfolio.attribution.Component"></a>

### *class* skfolio.attribution.Component(vol_contrib, pct_total_variance, mu_contrib, vol, corr_with_ptf, mu_uncertainty=None)

Portfolio attribution component.

Represents one component of the portfolio attribution: systematic, idiosyncratic,
unattributed, or total. Each component stores volatility and return contributions,
the percentage of total portfolio variance, standalone volatility, correlation
with the portfolio and optional return uncertainty.

For single-point attribution, fields are floats. For rolling attribution (from
[`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution)), fields are 1D arrays of shape
`(n_windows,)`.

* **Attributes:**
  **vol_contrib** *float or ndarray of shape (n_windows,)*
  : Volatility contribution to total portfolio volatility.

  **pct_total_variance** *float or ndarray of shape (n_windows,)*
  : Percentage of total portfolio variance.

  **mu_contrib** *float or ndarray of shape (n_windows,)*
  : Return contribution to total portfolio return (expected return for predicted
    attribution and mean return for realized attribution).

  **vol** *float or ndarray of shape (n_windows,)*
  : Standalone component volatility.

  **corr_with_ptf** *float or ndarray of shape (n_windows,)*
  : Correlation with portfolio returns.

  **mu_uncertainty** *float or ndarray of shape (n_windows,) or None*
  : Standard error of the mean return attribution, reflecting estimation uncertainty
    in the cross-sectional factor return regression. The systematic and
    idiosyncratic values are equal because their estimation errors sum to zero
    (the total portfolio return is observed). `None` when uncertainty is not
    computed.

<a id="skfolio.attribution.Component.mu"></a>

#### *property* mu

Standalone component return (expected return for predicted attribution and
mean return for realized attribution).

Components do not store a separate standalone return statistic. Unlike `vol`,
the component-level return is already its contribution to total portfolio
return, so `mu` is equal to `mu_contrib`.

# generated/skfolio.attribution.FactorBreakdown.html.md

<a id="skfolio-attribution-factorbreakdown"></a>

# skfolio.attribution.FactorBreakdown

<a id="skfolio.attribution.FactorBreakdown"></a>

### *class* skfolio.attribution.FactorBreakdown(names, vol_contrib, pct_total_variance, mu_contrib, family, exposure, exposure_std, vol, mu, corr_with_ptf, mu_contrib_uncertainty=None)

Per-factor attribution breakdown.

Contains per-factor attribution with exposures, standalone factor statistics and
volatility/return contributions.

For single-point attribution, arrays have shape `(n_factors,)`. For rolling
attribution, arrays have shape `(n_windows, n_factors)`.

* **Attributes:**
  **names** *ndarray of shape (n_factors,)*
  : Factor names. Always 1D.

  **family** *ndarray of shape (n_factors,) or None*
  : Factor family/category labels (e.g., “Style”, “Industry”). `None` if families
    were not provided.

  **exposure** *ndarray of shape (n_factors,) or (n_windows, n_factors)*
  : Portfolio exposure to each factor. For realized attribution with time-varying
    inputs, this is the mean exposure over time.

  **exposure_std** *ndarray or None*
  : Standard deviation of portfolio factor exposures over time. `None` for predicted
    attribution.

  **vol_contrib** *ndarray of shape (n_factors,) or (n_windows, n_factors)*
  : Factor volatility contribution to total portfolio volatility.

  **pct_total_variance** *ndarray of shape (n_factors,) or (n_windows, n_factors)*
  : Percentage of total portfolio variance.

  **mu_contrib** *ndarray of shape (n_factors,) or (n_windows, n_factors)*
  : Factor return contribution to total portfolio return.

  **vol** *ndarray of shape (n_factors,) or (n_windows, n_factors)*
  : Standalone factor volatility.

  **mu** *ndarray of shape (n_factors,) or (n_windows, n_factors)*
  : Standalone factor return: expected return for predicted attribution and mean
    return for realized attribution.

  **corr_with_ptf** *ndarray of shape (n_factors,) or (n_windows, n_factors)*
  : Correlation between each factor return and portfolio returns.

  **mu_contrib_uncertainty** *ndarray of shape (n_factors,) or (n_windows, n_factors) or None*
  : Per-factor standard error of the mean return contribution, reflecting factor
    return estimation uncertainty. `None` when uncertainty is not computed.

# generated/skfolio.attribution.FamilyBreakdown.html.md

<a id="skfolio-attribution-familybreakdown"></a>

# skfolio.attribution.FamilyBreakdown

<a id="skfolio.attribution.FamilyBreakdown"></a>

### *class* skfolio.attribution.FamilyBreakdown(names, vol_contrib, pct_total_variance, mu_contrib, exposure, exposure_std, mu_contrib_uncertainty=None)

Family-level attribution breakdown.

Aggregates factor attribution by factor family.

For single-point attribution, arrays have shape `(n_families,)`. For rolling
attribution, arrays have shape `(n_windows, n_families)`.

* **Attributes:**
  **names** *ndarray of shape (n_families,)*
  : Family names. Always 1D.

  **exposure** *ndarray of shape (n_families,) or (n_windows, n_families)*
  : Sum of portfolio factor exposures within each family.

  **exposure_std** *ndarray or None*
  : Standard deviation of family exposures over time. `None` for predicted
    attribution.

  **vol_contrib** *ndarray of shape (n_families,) or (n_windows, n_families)*
  : Family volatility contribution, equal to the sum of its factor volatility
    contributions.

  **pct_total_variance** *ndarray of shape (n_families,) or (n_windows, n_families)*
  : Percentage of total portfolio variance.

  **mu_contrib** *ndarray of shape (n_families,) or (n_windows, n_families)*
  : Family return contribution, equal to the sum of its factor return contributions.

  **mu_contrib_uncertainty** *ndarray of shape (n_families,) or (n_windows, n_families) or None*
  : Standard error of the family mean return contribution, accounting for
    cross-factor estimation correlations within the family. `None` when uncertainty
    is not computed.

# generated/skfolio.attribution.predicted_factor_attribution.html.md

<a id="skfolio-attribution-predicted-factor-attribution"></a>

# skfolio.attribution.predicted_factor_attribution

<a id="skfolio.attribution.predicted_factor_attribution"></a>

### skfolio.attribution.predicted_factor_attribution(weights, loading_matrix, factor_covariance, idio_covariance, asset_names, factor_names, factor_families=None, factor_mu=None, idio_mu=None, annualization_factor=252.0, compute_asset_breakdowns=True)

Compute predicted (ex-ante) factor volatility and return attribution.

The volatility attribution follows the exposure-volatility-correlation framework
(also called $x-\sigma-\rho$). It decomposes portfolio volatility into
systematic (factor) and idiosyncratic (specific) contributions.

The return attribution decomposes portfolio expected return into spanned
(factor-explained) and orthogonal expected return contributions.

**Factor Model:**

The asset covariance matrix is modeled as:

$$
\Sigma = B F B^\top + D

$$

where $B$ is the asset-by-factor loading matrix, $F$ is the factor
covariance matrix and $D$ is the idiosyncratic covariance matrix.

The expected return vector is modeled as:

$$
\mu = B \mu_f + \mu_\perp

$$

where $\mu_f$ contains the expected factor returns (factor premia),
$B \mu_f$ is the factor-spanned expected return and
$\mu_\perp$ is the factor-orthogonal expected return, also called
orthogonal alpha.

**Portfolio Variance Decomposition:**

Let $w$ be portfolio weights and $b = B^\top w$ be the portfolio factor
: exposure vector. Then:

$$
\sigma_P^2 = w^\top \Sigma w = b^\top F b + w^\top D w.
$$

**Portfolio Expected Return Decomposition:**

$$
\mu_P = w^\top \mu = b^\top \mu_f + w^\top \mu_\perp.
$$

**Volatility Contributions:**

The contribution of factor $k$ to portfolio volatility is defined as:

$$
\operatorname{VolContrib}_k =
\frac{b_k (F b)_k}{\sigma_P}.
$$

where $\sigma_P = \sqrt{w^\top \Sigma w}$ is total portfolio volatility.

These contributions are additive: they sum to the systematic component of
volatility.

$$
\sum_k \operatorname{VolContrib}_k = \frac{b^\top F b}{\sigma_P}.
$$

The systematic vs. idiosyncratic vs. total component contributions are:

$$
\operatorname{VolContrib}_{\mathrm{sys}} = \frac{b^\top F b}{\sigma_P},
\qquad
\operatorname{VolContrib}_{\mathrm{idio}} = \frac{w^\top D w}{\sigma_P},
\qquad
\operatorname{VolContrib}_{\mathrm{total}} = \sigma_P.
$$

and sum exactly:
$\operatorname{VolContrib}_{\mathrm{sys}} + \operatorname{VolContrib}_{\mathrm{idio}} = \sigma_P$.

**Expected Return Contributions:**

The contribution of each factor to spanned expected return is:

$$
\operatorname{MuContrib}_k = b_k \mu_{f,k}.
$$

These are also additive:

$$
\sum_k \operatorname{MuContrib}_k = b^\top \mu_f.
$$

**Correlation (x-sigma-rho framework):**

Let $\sigma_k = \sqrt{F_{kk}}$ be factor $k$ standalone
volatility. The correlation of factor $k$ with the portfolio return is:

$$
\rho_{k,P} = \frac{(F b)_k}{\sigma_k \sigma_P}.
$$

The factor volatility contribution can then be written as:

$$
\operatorname{VolContrib}_k = b_k \sigma_k \rho_{k,P}.
$$

**Percentage of Total Variance:**

The variance share of each factor is:

$$
\operatorname{PctTotalVariance}_k =
\frac{\operatorname{VolContrib}_k}{\sigma_P}.
$$

**NaN handling**:

`loading_matrix`, `idio_covariance` and `idio_mu` may contain NaN for non-investable
assets (delisted, not-yet-listed, warm-up). For `idio_covariance`, inactive assets
are identified by NaN diagonal entries, following the covariance estimator
convention. When a non-zero weight falls on such an asset a warning is emitted and
the asset’s contribution is effectively zeroed out. `weights`, `factor_covariance`
and `factor_mu` must be finite.

* **Parameters:**
  **weights** *array-like of shape (n_assets,)*
  : Portfolio weights vector.

  **loading_matrix** *array-like of shape (n_assets, n_factors)*
  : Asset-by-factor loading (exposure) matrix.. NaN entries for non-investable
    assets are filled with 0 (requires corresponding weights to be zero).

  **factor_covariance** *array-like of shape (n_factors, n_factors)*
  : Covariance matrix of the factors. Must be per-period (e.g., daily covariance if
    using daily data). Use `annualization_factor` to scale to annualized values.

  **idio_covariance** *array-like of shape (n_assets,) or (n_assets, n_assets)*
  : Idiosyncratic (specific) covariance. If 1D, treated as diagonal variances.
    If 2D, used as full covariance matrix. Must be per-period, same as
    `factor_covariance`. NaN entries for non-investable assets are filled with 0.

  **asset_names** *array-like of shape (n_assets,)*
  : Names for each asset (e.g., [“AAPL”, “GOOGL”, “MSFT”]).

  **factor_names** *array-like of shape (n_factors,)*
  : Names for each factor (e.g., [“Momentum”, “Value”, “Size”]).

  **factor_families** *array-like of shape (n_factors,), optional*
  : Family/category for each factor (e.g., “Style”, “Industry”). If provided,
    enables family-level aggregation in DataFrame output.

  **factor_mu** *array-like of shape (n_factors,), optional*
  : Expected returns of each factor (factor premia), $\mu_f$. Defaults to
    zeros if not provided. Must be per-period (e.g., daily expected returns if using
    daily data). All inputs (`factor_covariance`, `idio_covariance`, `factor_mu`,
    `idio_mu`) must share the same periodicity. Use `annualization_factor` to scale
    outputs to annualized values.

  **idio_mu** *array-like of shape (n_assets,), optional*
  : Factor-orthogonal expected return for each asset, $\mu_\perp$. It is
    distinct from the time-series mean of `idio_returns`, which is not enforced to
    be factor-orthogonal. Defaults to zeros if not provided. Must be per-period,
    same as `factor_mu`. NaN entries for non-investable assets are filled with 0
    (requires corresponding weights to be zero).
    <br/>
    #### NOTE
    This vector **must already be orthogonal** to the column span of the
    loading matrix $B$ (with respect to your chosen regression metric,
    e.g., OLS or GLS). This function does **not** perform any orthogonalization.
    It assumes `idio_mu` satisfies the decomposition
    $\mu = B \mu_f + \mu_\perp$ where
    $B^\top \mu_\perp = 0$ (or the appropriate weighted inner product
    equals zero for GLS). Typically, this is the residual vector from regressing
    expected asset returns onto the factor loadings.

  **annualization_factor** *float, default=252.0*
  : Used to annualize expected returns, variances and volatilities. Use 1.0 to
    disable annualization. Common values: 252 for daily data, 12 for monthly data.

  **compute_asset_breakdowns** *bool, default=True*
  : If True, compute asset-level attribution (systematic/idiosyncratic
    decomposition). Set to False to skip asset attribution for faster computation.
* **Returns:**
  **attribution** *Attribution*
  : The [`Attribution`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution) dataclass containing component-level, factor-level and
    optionally asset-level attribution results. Use `attribution.summary_df()`,
    `attribution.factors_df()`, `attribution.assets_df()` to convert to pandas
    DataFrames.
* **Raises:**
  ValueError
  : If input dimensions are inconsistent, if `weights`,\`factor_covariance\` or
    `factor_mu` contain NaN, or if total variance is non-positive.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.attribution import predicted_factor_attribution
>>> asset_names = ["AAPL", "GOOGL", "MSFT"]
>>> factor_names = ["Momentum", "Value", "Size"]
>>> weights = np.array([0.4, 0.3, 0.3])
>>> loading_matrix = np.array(
...     [
...         [1.0, 0.5, 0.2],
...         [0.8, 1.0, 0.1],
...         [0.3, 0.2, 1.0],
...     ]
... )
>>> # Synthetic daily covariances; idiosyncratic residuals are uncorrelated.
>>> factor_covariance = np.array(
...     [
...         [0.00016, 0.00004, 0.00000],
...         [0.00004, 0.00012, 0.00000],
...         [0.00000, 0.00000, 0.00008],
...     ]
... )
>>> idio_variances = np.array([0.00004, 0.00006, 0.00008])
```

Compute annualized volatility and return contributions:

```pycon
>>> attribution = predicted_factor_attribution(
...     weights=weights,
...     loading_matrix=loading_matrix,
...     factor_covariance=factor_covariance,
...     idio_covariance=idio_variances,
...     asset_names=asset_names,
...     factor_names=factor_names,
...     factor_families=["Style", "Style", "Size"],
...     factor_mu=np.array([0.0002, 0.00012, 0.00008]),  # Daily expected returns
... )
>>> print(f"Annualized volatility: {attribution.total.vol:.2%}")
Annualized volatility: 21.77%
>>> print(f"Factor exposures: {attribution.factors.exposure}")
Factor exposures: [0.73 0.56 0.41]
```

```pycon
>>> attribution.summary_df()
              Volatility Contribution  ... Expected Return Contribution
Component                              ...
Systematic                     19.57%  ...                        6.20%
Idiosyncratic                   2.20%  ...                        0.00%
Total                          21.77%  ...                        6.20%

[3 rows x 3 columns]
```

```pycon
>>> attribution.families_df()
       Exposure  ... Expected Return Contribution
Family           ...
Style    1.2900  ...                        5.37%
Size     0.4100  ...                        0.83%

[2 rows x 4 columns]
```

# generated/skfolio.attribution.realized_factor_attribution.html.md

<a id="skfolio-attribution-realized-factor-attribution"></a>

# skfolio.attribution.realized_factor_attribution

<a id="skfolio.attribution.realized_factor_attribution"></a>

### skfolio.attribution.realized_factor_attribution(\*, asset_names, factor_names, factor_families=None, weights, factor_returns, portfolio_returns, exposures, exposure_lag=1, idio_returns, idio_variances=None, regression_weights=None, family_constraint_basis=None, annualization_factor=252.0, compute_asset_breakdowns=True, compute_uncertainty=False)

Compute realized (ex-post) factor volatility and return attribution.

This function decomposes realized portfolio volatility and return into systematic
(factors), idiosyncratic and unattributed contributions.

**Time convention (as-of indexing):**

Under this convention, all time-varying inputs at observation $t$ reflect
information available up to and including the end of period $t$.
Point-in-time fields and derived values store the latest available value for
observation $t$. Returns stored at observation $t$ cover the period
ending at $t$, namely $(t-1, t]$.

For time-varying exposures, attribution uses exposures from before the return
interval. When `exposure_lag > 0`, the function aligns $B_{t-\ell}$ with
returns at $t$; the first $\ell$ return observations are discarded.
For 2D static exposures, no trimming is needed.

$$
R_{P,t} =
\sum_{k=1}^{K} x_{k,t} f_{k,t}
+ \varepsilon_{P,t}
+ \eta_{P,t}

$$

where $x_{k,t} = B_{:,k,t-\ell}^\top w_t$, $\varepsilon_{P,t}$ is the
portfolio idiosyncratic return, $\eta_{P,t}$ is the unattributed portfolio
return, and $\ell$ is `exposure_lag`.

**Unattributed component:**

The unattributed return :math:eta_{P,t} is the difference between the observed
portfolio return and its systematic-plus-idiosyncratic reconstruction. It
captures effects outside that reconstruction, such as costs, cash, intra-period
trading and the time-series regression intercept.

**Volatility Attribution (Variance Decomposition):**

Using the covariance identity, the total portfolio variance decomposes as:

$$
\operatorname{Var}(R_P) =
\sum_{k=1}^{K} \operatorname{Cov}(x_k f_k, R_P)
+ \operatorname{Cov}(\varepsilon_P, R_P)
+ \operatorname{Cov}(\eta_P, R_P)

$$

Each factor’s variance contribution is $\operatorname{Cov}(x_k f_k, R_P)$,
which captures both the exposure magnitude and the factor’s correlation with
portfolio returns. These contributions are additive and sum exactly to total
variance.

**Volatility Contribution:**

The volatility contribution divides the variance contribution by portfolio
volatility:

$$
\operatorname{VolContrib}_k =
\frac{\operatorname{Cov}(x_k f_k, R_P)}{\sigma_P}

$$

This also satisfies the $\sigma \cdot \rho$ identity:

$$
\operatorname{VolContrib}_k =
\operatorname{std}(x_k f_k) \cdot
\operatorname{corr}(x_k f_k, R_P)

$$

**Return Attribution:**

The mean return contribution of each factor is the average of the exposure-weighted
factor returns:

$$
\operatorname{MuContrib}_k = \overline{x_k f_k}

$$

* **Parameters:**
  **asset_names** *array-like of shape (n_assets,)*
  : Names for each asset (e.g., [“AAPL”, “GOOGL”, “MSFT”]).

  **factor_names** *array-like of shape (n_factors,)*
  : Names for each factor (e.g., [“Momentum”, “Value”, “Size”]).

  **factor_families** *array-like of shape (n_factors,), optional*
  : Family/category for each factor (e.g., “Style”, “Industry”).  If provided,
    enables family-level aggregation in the output.

  **weights** *array-like of shape (n_assets,) or (n_observations, n_assets)*
  : Portfolio weights. If 1D, the same weights are used for all observations
    (static). If 2D, time-varying weights are used.

  **factor_returns** *array-like of shape (n_observations, n_factors)*
  : Factor return time series.

  **portfolio_returns** *array-like of shape (n_observations,)*
  : Portfolio return time series.

  **exposures** *array-like of shape (n_assets, n_factors) or (n_observations, n_assets, n_factors)*
  : Asset-by-factor exposure (loading) values. If 2D, this is the static loading
    matrix used for all observations. If 3D, this is a time series of loading
    matrices following the as-of time-indexing convention (the function applies
    `exposure_lag` internally and trims the returns and weights series accordingly).

  **exposure_lag** *int, default=1*
  : Lag applied to time-varying exposures under the as-of time-indexing convention.
    The default value of `1` aligns exposures at $t-1$ with returns over
    $(t-1, t]$. Only affects 3D (time-varying) exposures.

  **idio_returns** *array-like of shape (n_observations, n_assets)*
  : Idiosyncratic returns from the factor model regression. These are the residuals
    $\varepsilon_{i,t}$ from the cross-sectional regression.

  **idio_variances** *array-like of shape (n_observations, n_assets) or None, optional*
  : Per-asset idiosyncratic (specific) variances $\sigma^2_{\varepsilon,i,t}$.
    Required when `compute_uncertainty=True`. NaN values are allowed and exclude the
    corresponding asset-observation pair from the uncertainty estimate.

  **regression_weights** *array-like of shape (n_observations, n_assets) or None, optional*
  : Per-asset cross-sectional regression weights $q_{i,t}$ used when
    estimating factor returns. Required when `compute_uncertainty=True`. Must not
    contain NaN.

  **family_constraint_basis** *FamilyConstraintBasis or None, optional*
  : When provided, the uncertainty estimator is computed in the reduced (full-rank)
    basis defined by the family-constraint change of coordinates. This avoids the
    singular Gram matrix that arises from collinear constrained families and
    produces well-conditioned standard errors. Only used when
    `compute_uncertainty=True`.

  **annualization_factor** *float, default=252.0*
  : Used to annualize expected returns, variances and volatilities. Use 1.0 to
    disable annualization. Common values: 252 for daily data, 12 for monthly data.

  **compute_asset_breakdowns** *bool, default=True*
  : If True, compute asset-level attribution (systematic/idiosyncratic
    decomposition). Set to False to skip asset attribution for faster computation.

  **compute_uncertainty** *bool, default=False*
  : If `True`, compute attribution uncertainty (standard errors on
    the factor/idiosyncratic return split). Requires both `regression_weights` and
    `idio_variances`; raises `ValueError` if either is missing. If `False`
    (default), uncertainty is not computed.
* **Returns:**
  **attribution** *Attribution*
  : The [`Attribution`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution) dataclass containing component-level,  factor-level
    and optionally asset-level attribution results.

#### SEE ALSO
[`predicted_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.predicted_factor_attribution.html.md#skfolio.attribution.predicted_factor_attribution)
: Predicted (ex-ante) factor model attribution.

### Notes

When exposures are time-varying, `vol_contrib` cannot be exactly
reproduced as `exposure_mean * sigma(f) * rho(f, R_P)` because the actual
contribution is computed from the covariance of the exposure-weighted factor
return series. The displayed statistics provide intuitive factor-level
information while the contributions reflect the true realized attribution.

**NaN handling:**

`exposures` and `idio_returns` may contain NaN entries for assets that are inactive
at a given date (delistings, not-yet-listed securities, trading holidays). These NaN
values are replaced with 0 before any computation: portfolio weight for an inactive
asset is zero, so its return contribution is economically zero.

When `compute_uncertainty=True`, NaN values in `idio_variances` exclude the
corresponding asset-observation pair from the uncertainty estimate by setting its
effective regression weight to zero. This handles per-asset variance-estimator
warmup, inactive assets and sparse histories without changing the attribution
sample.

`factor_returns`, `portfolio_returns`, and `weights` must not contain NaN; a
`ValueError` is raised otherwise.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.attribution import realized_factor_attribution
>>> # Simulated daily returns: 10 assets, 3 factors.
>>> rng = np.random.default_rng(0)
>>> factor_returns = rng.standard_normal((252, 3)) * 0.01
>>> loading_matrix = rng.uniform(0.5, 1.5, size=(10, 3))
>>> weights = np.full(10, 1.0 / 10)
>>> residuals = rng.standard_normal((252, 10)) * 0.005
>>> asset_returns = factor_returns @ loading_matrix.T + residuals
>>> portfolio_returns = asset_returns @ weights
>>> asset_names = [f"Asset_{i}" for i in range(10)]
>>> factor_names = ["Momentum", "Value", "Size"]
```

Compute attribution with fixed weights (annualized by default):

```pycon
>>> attribution = realized_factor_attribution(
...     factor_returns=factor_returns,
...     portfolio_returns=portfolio_returns,
...     exposures=loading_matrix,
...     weights=weights,
...     idio_returns=residuals,
...     asset_names=asset_names,
...     factor_names=factor_names,
... )
>>> print(f"Annualized volatility: {attribution.total.vol:.2%}")
Annualized volatility: 26.16%
>>> print(f"Factor contributions: {attribution.factors.vol_contrib}")
Factor contributions: [0.07630795 0.11148071 0.07271759]
```

Simulate daily rebalancing with a different set of asset weights for each day:

```pycon
>>> daily_weights = weights + rng.uniform(-0.02, 0.02, size=(252, 10))
>>> # Normalize each day's weights to sum to one.
>>> daily_weights /= daily_weights.sum(axis=1, keepdims=True)
>>> # Apply each day's weights to that day's asset returns.
>>> portfolio_returns = (asset_returns * daily_weights).sum(axis=1)
>>> attribution = realized_factor_attribution(
...     factor_returns=factor_returns,
...     portfolio_returns=portfolio_returns,
...     exposures=loading_matrix,
...     weights=daily_weights,
...     idio_returns=residuals,
...     asset_names=asset_names,
...     factor_names=factor_names,
... )
```

Inspect the standard deviation of each factor exposure over time:

```pycon
>>> print(attribution.factors.exposure_std)
[0.0122634  0.00836653 0.01058102]
```

# generated/skfolio.attribution.rolling_realized_factor_attribution.html.md

<a id="skfolio-attribution-rolling-realized-factor-attribution"></a>

# skfolio.attribution.rolling_realized_factor_attribution

<a id="skfolio.attribution.rolling_realized_factor_attribution"></a>

### skfolio.attribution.rolling_realized_factor_attribution(\*, observations, window_size=60, step=21, asset_names, factor_names, factor_families=None, weights, factor_returns, portfolio_returns, exposures, exposure_lag=1, idio_returns, idio_variances=None, regression_weights=None, family_constraint_basis=None, annualization_factor=252.0, compute_asset_breakdowns=True, compute_asset_factor_contribs=False, compute_uncertainty=False)

Compute rolling realized (ex-post) factor volatility and return attribution.

This function computes [`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution) over rolling windows,
returning an [`Attribution`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution) object where all numeric fields are arrays
with an additional leading dimension corresponding to the number of windows.

* **Parameters:**
  **observations** *array-like of shape (n_observations,)*
  : Observation labels (e.g., dates) corresponding to each row of the input
    data. The output `Attribution.observations` will contain the labels
    for the last observation of each window.

  **window_size** *int, default=60*
  : Number of observations in each rolling window.

  **step** *int, default=21*
  : Number of observations to advance between consecutive windows. The default of
    21 produces approximately monthly output for daily data. Use `step=1` for fully
    overlapping windows (daily updates), or `step=window_size` for non-overlapping
    windows.

  **asset_names** *array-like of shape (n_assets,)*
  : Names for each asset (e.g., [“AAPL”, “GOOGL”, “MSFT”]).

  **factor_names** *array-like of shape (n_factors,)*
  : Names for each factor (e.g., [“Momentum”, “Value”, “Size”]).

  **factor_families** *array-like of shape (n_factors,), optional*
  : Family/category for each factor (e.g., “Style”, “Industry”).  If provided,
    enables family-level aggregation in the output.

  **weights** *array-like of shape (n_assets,) or (n_observations, n_assets)*
  : Portfolio weights. If 1D, the same weights are used for all observations
    (static). If 2D, time-varying weights are used.

  **factor_returns** *array-like of shape (n_observations, n_factors)*
  : Factor return time series.

  **portfolio_returns** *array-like of shape (n_observations,)*
  : Portfolio return time series.

  **exposures** *array-like of shape (n_assets, n_factors) or (n_observations, n_assets, n_factors)*
  : Asset-by-factor exposure (loading) values. If 2D, this is the static loading
    matrix used for all observations. If 3D, this is a time series of loading
    matrices following the as-of time-indexing convention (the function applies
    `exposure_lag` internally and trims the returns and weights series accordingly).

  **exposure_lag** *int, default=1*
  : Lag applied to time-varying exposures under the as-of time-indexing convention.
    The default value of `1` aligns exposures at $t-1$ with returns over
    $(t-1, t]$. Only affects 3D (time-varying) exposures.

  **idio_returns** *array-like of shape (n_observations, n_assets)*
  : Idiosyncratic returns from the factor model regression. These are the residuals
    $\varepsilon_{i,t}$ from the cross-sectional regression.

  **idio_variances** *array-like of shape (n_observations, n_assets) or None, optional*
  : Per-asset idiosyncratic (specific) variances $\sigma^2_{\varepsilon,i,t}$.
    Required when `compute_uncertainty=True`. NaN values are allowed and exclude the
    corresponding asset-observation pair from the uncertainty estimate.

  **regression_weights** *array-like of shape (n_observations, n_assets) or None, optional*
  : Per-asset cross-sectional regression weights $q_{i,t}$ used when
    estimating factor returns. Required when `compute_uncertainty=True`. Must not
    contain NaN.

  **family_constraint_basis** *FamilyConstraintBasis or None, optional*
  : When provided, the uncertainty estimator is computed in the reduced (full-rank)
    basis defined by the family-constraint change of coordinates. This avoids the
    singular Gram matrix that arises from collinear constrained families and
    produces well-conditioned standard errors. Only used when
    `compute_uncertainty=True`.

  **annualization_factor** *float, default=252.0*
  : Used to annualize expected returns, variances and volatilities. Use 1.0 to
    disable annualization. Common values: 252 for daily data, 12 for monthly data.

  **compute_asset_breakdowns** *bool, default=True*
  : If True, compute asset-level attribution for each window.
    Results in 2D arrays of shape `(n_windows, n_assets)` in AssetBreakdown.
    Set to False to skip asset attribution for faster computation.

  **compute_asset_factor_contribs** *bool, default=False*
  : If True, compute asset-by-factor contributions for each window.
    Results in 3D arrays of shape `(n_windows, n_assets, n_factors)`.
    Disabled by default for faster computation.

  **compute_uncertainty** *bool, default=False*
  : If `True`, compute per-window attribution uncertainty (standard errors on the
    factor/idiosyncratic return split). Requires both `regression_weights` and
    `idio_variances`; raises `ValueError` if either is missing. If `False`
    (default), uncertainty is not computed.
* **Returns:**
  **attribution** *Attribution*
  : The [`Attribution`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution) dataclass with rolling results. All numeric fields in
    [`Component`](https://skfolio.org/generated/skfolio.attribution.Component.html.md#skfolio.attribution.Component) are 1D arrays of shape `(n_windows,)`. All numeric fields in
    `Breakdown` are 2D arrays of shape `(n_windows, n_factors)` or
    `(n_windows, n_families)`. If `compute_asset_breakdowns=True`, asset attribution
    has shape `(n_windows, n_assets)`. The `observations` field contains the window
    end labels.

#### SEE ALSO
[`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution)
: Single-point realized factor attribution.

### Examples

```pycon
>>> import numpy as np
>>> import pandas as pd
>>> from skfolio.attribution import rolling_realized_factor_attribution
>>> # Simulated daily returns: 10 assets, 3 factors.
>>> rng = np.random.default_rng(0)
>>> factor_returns = rng.standard_normal((252, 3)) * 0.01
>>> loading_matrix = rng.uniform(0.5, 1.5, size=(10, 3))
>>> weights = np.full(10, 1.0 / 10)
>>> residuals = rng.standard_normal((252, 10)) * 0.005
>>> asset_returns = factor_returns @ loading_matrix.T + residuals
>>> portfolio_returns = asset_returns @ weights
>>> asset_names = [f"Asset_{i}" for i in range(10)]
>>> factor_names = ["Momentum", "Value", "Size"]
```

Use 60 business days per window, advancing by 21 (approximately monthly):

```pycon
>>> dates = pd.bdate_range("2023-01-01", periods=252)
>>> attribution = rolling_realized_factor_attribution(
...     factor_returns=factor_returns,
...     portfolio_returns=portfolio_returns,
...     exposures=loading_matrix,
...     weights=weights,
...     idio_returns=residuals,
...     asset_names=asset_names,
...     factor_names=factor_names,
...     observations=dates,
...     window_size=60,
...     step=21,
... )
>>> print(f"Number of windows: {len(attribution.observations)}")
Number of windows: 10
```

Annualized volatility in each window:

```pycon
>>> print(attribution.total.vol)
[0.26478682 0.28232785 0.28856211 0.27556505 0.2311759  0.23023946
 0.22712558 0.26810224 0.26441032 0.28657536]
```

Inspect the first two windows as a numeric DataFrame:

```pycon
>>> df = attribution.factors_df(formatted=False)
>>> print(df.head(6))  # Index: window end date, factor
                  Exposure Mean  ...  Correlation with Portfolio
Observation Factor                   ...
2023-03-24  Momentum       0.898797  ...                    0.687795
            Value          1.054506  ...                    0.572425
            Size           0.912125  ...                    0.564114
2023-04-24  Momentum       0.898797  ...                    0.545547
            Value          1.054506  ...                    0.689650
            Size           0.912125  ...                    0.561379

[6 rows x 8 columns]
```

# generated/skfolio.base.BaseAssetPanelTransformer.html.md

<a id="skfolio-base-baseassetpaneltransformer"></a>

# skfolio.base.BaseAssetPanelTransformer

<a id="skfolio.base.BaseAssetPanelTransformer"></a>

### *class* skfolio.base.BaseAssetPanelTransformer

Base class for estimators that transform asset panel data.

Descriptors and factor exposure estimators take an
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) and return transformed values indexed by
observation and asset. Most transformers return an array with shape
`(n_observations, n_assets)`. Transformers that produce multiple values per asset,
such as [`OneHotCategoricalFactors`](https://skfolio.org/generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md#skfolio.factor_exposure.OneHotCategoricalFactors), return an array
with shape `(n_observations, n_assets, n_categories)`.

In scikit-learn, `fit` and `partial_fit` update fitted state, stored in trailing
underscore attributes, while `transform` returns transformed input data using that
state. This separation is not suitable for every
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) transformer. For some estimators, the
transformed value is produced by the same state transition that updates the
estimator. A separate `transform` method would either need to mutate state or
depend on a preceding `partial_fit` call, so the API exposes the combined
operation directly. For example, the exponentially weighted momentum
descriptor [`EWMomentum`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum) needs to update its internal
EWMA state to compute the transformed value on each observation.

Other transformers are independent across observations. For example, the
[`DividendToPrice`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice) descriptor depends only on the current
`dividends_ttm` and `market_cap` values and can therefore be declared stateless.

Accordingly, `fit_transform` is used for full-batch computation and
`partial_fit_transform` for online computation. Subclasses must implement
`fit_transform`. Downstream meta-estimators use the presence of
`partial_fit_transform` to determine whether a transformer supports online
transformation.

Supported implementation patterns are:

- Batch-only transformers implement only `fit_transform`.
- Stateless transformers declare `stateless=True` and implement only `fit_transform`.
  The base class adds `partial_fit_transform` as a direct delegation to `fit_transform`.
- Online transformers implement both `fit_transform` and `partial_fit_transform`.

* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.base.BaseAssetPanelTransformer.html.md#skfolio.base.BaseAssetPanelTransformer.fit_transform)(X[, y])   | Fit the transformer if needed and return transformed values.   |
|--------------------------------------------------------------------------|----------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.base.BaseAssetPanelTransformer.html.md#skfolio.base.BaseAssetPanelTransformer.get_metadata_routing)()  | Get metadata routing of this object.                           |
| [`get_params`](https://skfolio.org/generated/skfolio.base.BaseAssetPanelTransformer.html.md#skfolio.base.BaseAssetPanelTransformer.get_params)([deep])      | Get parameters for this estimator.                             |
| [`set_params`](https://skfolio.org/generated/skfolio.base.BaseAssetPanelTransformer.html.md#skfolio.base.BaseAssetPanelTransformer.set_params)(\*\*params)  | Set the parameters of this estimator.                          |

#### SEE ALSO
[`BaseDescriptor`](https://skfolio.org/generated/skfolio.descriptor.BaseDescriptor.html.md#skfolio.descriptor.BaseDescriptor)
: Computes raw descriptor values.

[`BaseFactorExposure`](https://skfolio.org/generated/skfolio.factor_exposure.BaseFactorExposure.html.md#skfolio.factor_exposure.BaseFactorExposure)
: Computes factor exposures.

<a id="skfolio.base.BaseAssetPanelTransformer.fit_transform"></a>

#### *abstractmethod* fit_transform(X, y=None, \*\*fit_params)

Fit the transformer if needed and return transformed values.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel data.

  **y** *None*
  : Ignored. Present for API consistency.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Metadata routing may pass these parameters to
    sub-estimators when applicable.
* **Returns:**
  **values** *ndarray of shape (n_observations, n_assets) or (n_observations, n_assets, n_components)*
  : Transformed values.

<a id="skfolio.base.BaseAssetPanelTransformer.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.base.BaseAssetPanelTransformer.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.base.BaseAssetPanelTransformer.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.

# generated/skfolio.base.BaseComposition.html.md

<a id="skfolio-base-basecomposition"></a>

# skfolio.base.BaseComposition

<a id="skfolio.base.BaseComposition"></a>

### *class* skfolio.base.BaseComposition

Handles parameter management for ensemble estimators.

### Methods

| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.base.BaseComposition.html.md#skfolio.base.BaseComposition.get_metadata_routing)()   | Get metadata routing of this object.   |
|---------------------------------------------------------------------------|----------------------------------------|
| [`get_params`](https://skfolio.org/generated/skfolio.base.BaseComposition.html.md#skfolio.base.BaseComposition.get_params)([deep])       | Get parameters for this estimator.     |
| [`set_params`](https://skfolio.org/generated/skfolio.base.BaseComposition.html.md#skfolio.base.BaseComposition.set_params)(\*\*params)   | Set the parameters of this estimator.  |

<a id="skfolio.base.BaseComposition.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.base.BaseComposition.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.base.BaseComposition.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.

# generated/skfolio.cluster.HierarchicalClustering.html.md

<a id="skfolio-cluster-hierarchicalclustering"></a>

# skfolio.cluster.HierarchicalClustering

<a id="skfolio.cluster.HierarchicalClustering"></a>

### *class* skfolio.cluster.HierarchicalClustering(max_clusters=None, linkage_method=WARD)

Hierarchical Clustering.

* **Parameters:**
  **max_clusters** *int, optional*
  : For coherent clustering, the algorithm finds a minimum threshold `r` so that
    the cophenetic distance between any two original observations in the same flat
    cluster is no more than `r` and no more than `max_clusters` flat clusters are
    formed. The default (`None`) is to estimate the maximal number of clusters
    based on the Two-Order Difference to Gap Statistic [[1]](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#r15163dd2dd4e-1).

  **linkage_method** *LinkageMethod, default=LinkageMethod.WARD*
  : Methods for calculating the distance between clusters in the linkage matrix.
    See the `Linkage Methods` section of `scipy.cluster.hierarchy.linkage` for
    the full descriptions.
    The default is the Ward variance minimization algorithm `LinkageMethod.WARD`.
* **Attributes:**
  **n_clusters_** *int*
  : Number of formed clusters.

  **labels_** *ndarray of shape (n_assets,)*
  : Labels of each asset.

  **linkage_matrix_** *ndarray of shape (n_assets - 1, 4)*
  : Linkage matrix computed from the distance matrix of the `distance_estimator`.

  **condensed_distance_** *ndarray of shape (\\binom{n_assets}{2}, )*
  : The 1-D condensed distance matrix.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering.fit)(X[, y])                | Fit the Hierarchical Equal Risk Contribution estimator.   |
|-----------------------------------------------------------------------------|-----------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering.fit_predict)(X[, y])        | Perform clustering on `X` and returns cluster labels.     |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering.get_metadata_routing)()     | Get metadata routing of this object.                      |
| [`get_params`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering.get_params)([deep])         | Get parameters for this estimator.                        |
| [`plot_dendrogram`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering.plot_dendrogram)([heatmap]) | Plot the dendrogram.                                      |
| [`set_params`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering.set_params)(\*\*params)     | Set the parameters of this estimator.                     |

### References

* <a id='r15163dd2dd4e-1'>**[1]**</a> “Application of two-order difference to gap statistic”. Yue, Wang & Wei (2009)

<a id="skfolio.cluster.HierarchicalClustering.fit"></a>

#### fit(X, y=None)

Fit the Hierarchical Equal Risk Contribution estimator.

* **Parameters:**
  **X** *array-like of shape (n_assets, n_assets)*
  : Distance matrix of the assets.

  **y** *Ignored*
  : Not used, present for API consistency by convention.
* **Returns:**
  **self** *HierarchicalClustering*
  : Fitted estimator.

<a id="skfolio.cluster.HierarchicalClustering.fit_predict"></a>

#### fit_predict(X, y=None, \*\*kwargs)

Perform clustering on `X` and returns cluster labels.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_features)*
  : Input data.

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

  **\*\*kwargs** *dict*
  : Arguments to be passed to `fit`.
    <br/>
    #### Versionadded
    Added in version 1.4.
* **Returns:**
  **labels** *ndarray of shape (n_samples,), dtype=np.int64*
  : Cluster labels.

<a id="skfolio.cluster.HierarchicalClustering.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.cluster.HierarchicalClustering.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.cluster.HierarchicalClustering.plot_dendrogram"></a>

#### plot_dendrogram(heatmap=True)

Plot the dendrogram.

The blue lines represent distinct clusters composed of a single asset.
The remaining colors represent clusters of more than one asset.

When `heatmap` is set to True, the heatmap of the reordered distance matrix is
displayed below the dendrogram and clusters are outlined with yellow squares.

The number of clusters used in the plot is the same as the `n_clusters_`
attribute if it exists, otherwise a default number is used corresponding to the
number of cluster with a distance above 70% of the maximum cluster distance.

* **Parameters:**
  **heatmap** *bool, default=True*
  : If this is set to True, the distance heatmap is returned with the clustered
    outlined in yellow.
* **Returns:**
  **fig** *Figure*
  : The dendrogram figure.

<a id="skfolio.cluster.HierarchicalClustering.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.

# generated/skfolio.cluster.LinkageMethod.html.md

<a id="skfolio-cluster-linkagemethod"></a>

# skfolio.cluster.LinkageMethod

<a id="skfolio.cluster.LinkageMethod"></a>

### *class* skfolio.cluster.LinkageMethod(\*values)

Methods for calculating the distance between clusters in the linkage matrix.
See the `Linkage Methods` section of `scipy.cluster.hierarchy.linkage`
for full descriptions.

* **Parameters:**
  **SINGLE** *str*
  : Assigns
    $$
    d(u,v) = \min(dist(u[i],v[j]))
    <br/>
    $$
    <br/>
    for all points $i$ in cluster $u$ and
    $j$ in cluster $v$. This is also known as the
    Nearest Point Algorithm.

  **COMPLETE** *str*
  : Assigns
    $$
    d(u, v) = \max(dist(u[i],v[j]))
    <br/>
    $$
    <br/>
    for all points $i$ in cluster u and $j$ in
    cluster $v$. This is also known as the Farthest Point
    Algorithm or Voor Hees Algorithm.

  **AVERAGE** *str*
  : Assigns
    $$
    d(u,v) = \sum_{ij} \frac{d(u[i], v[j])}{(|u|*|v|)}
    <br/>
    $$
    <br/>
    for all points $i$ and $j$ where $|u|$
    and $|v|$ are the cardinalities of clusters $u$
    and $v$, respectively. This is also called the UPGMA
    algorithm.

  **WEIGHTED** *str*
  : Assigns
    $$
    d(u,v) = (dist(s,v) + dist(t,v))/2
    <br/>
    $$
    <br/>
    where cluster u was formed with cluster s and t and v
    is a remaining cluster in the forest (also called WPGMA).

  **CENTROID** *str*
  : Assigns
    $$
    dist(s,t) = ||c_s-c_t||_2
    <br/>
    $$
    <br/>
    where $c_s$ and $c_t$ are the centroids of
    clusters $s$ and $t$, respectively.
    This is also known as the UPGMC
    algorithm.

  **MEDIAN** *str*

  **assigns :math:\`d(s,t)\` like the \`centroid\` method.**

  **This is also known as the WPGMC algorithm.**

  **WARD** *str*
  : Uses the Ward variance minimization algorithm.
    The new entry $d(u,v)$ is computed as follows,
    $$
    d(u,v) = \sqrt{\frac{|v|+|s|}
                        {T}d(v,s)^2
                 + \frac{|v|+|t|}
                        {T}d(v,t)^2
                 - \frac{|v|}
                        {T}d(s,t)^2}
    $$
    <br/>
    where $u$ is the newly joined cluster consisting of
    clusters $s$ and $t$, $v$ is an unused
    cluster in the forest, $T=|v|+|s|+|t|$, and
    $|*|$ is the cardinality of its argument. This is also
    known as the incremental algorithm.

<a id="skfolio.cluster.LinkageMethod.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.containers.AssetPanel.html.md

<a id="skfolio-containers-assetpanel"></a>

# skfolio.containers.AssetPanel

<a id="skfolio.containers.AssetPanel"></a>

### *class* skfolio.containers.AssetPanel(fields, observations, asset_names, active_mask=None, estimation_mask=None, \_validate_on_init=True)

Container for aligned cross-sectional asset data.

`AssetPanel` stores asset-level fields (e.g. returns, volumes, industry
classification, factor exposure), over shared observation and asset axes.
Every field uses `observations` as the first axis and `assets` as the second
axis. These two axes always have shape (n_observations, n_assets).

Three kinds of fields are supported:

- 2D numeric fields (e.g. `returns`, `volume`, `market_cap`). These are stored as 2D
  numpy array in a `Field2D`.
- 2D categorical fields (e.g. `country`, `industry`). These are stored as 2D numpy
  array of integer codes in a `FieldCategorical`, together with the category labels
  (e.g. “bank”, “technology”)
- 3D numeric fields (e.g. `factor_exposures`). These are stored in a 3D numpy array
  in a `Field3D` with shape (n_observations, n_assets, n_third_axis), together with
  the third axis labels such as factor names (e.g. “size”, “momentum”) and optional
  group labels such as factor families (e.g. “style”, “industry”)

The container is scikit-learn compatible: `len(panel)` returns `n_observations`
and `panel[start:stop]` returns an `AssetPanelView` that can be passed to
cross-validation and hyper-parameter tuning utilities. View creation is zero-copy
when the observation selector is a slice or a contiguous index.

* **Parameters:**
  **fields** *dict[str, BaseField or ndarray]*
  : Field mapping. Raw arrays must be 2D and are converted to `Field2D`.
    Use `FieldCategorical` for integer-coded categorical fields and `Field3D` for 3D
    fields; both carry the metadata needed to interpret their codes or third axes.

  **observations** *ndarray of shape (n_observations,)*
  : Unique observation labels for the sample axis. NumPy dtypes are preserved.
    Object-dtype datetime-like labels are converted with NumPy, object-dtype string
    labels are converted to strings and mixed object labels are rejected.

  **asset_names** *ndarray of shape (n_assets,)*
  : Unique asset labels. Object-dtype labels are converted to strings.

  **active_mask** *boolean ndarray of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset belongs to the universe at each
    observation. This separates assets that are outside the universe (e.g. before
    listing, after delisting) from assets that are in the universe but have a
    missing observation (e.g. holiday, missing quote). If `None`, all pairs are
    active.

  **estimation_mask** *boolean ndarray of shape (n_observations, n_assets), optional*
  : Boolean mask indicating which active `(observation, asset)` pairs should be used
    for estimator-specific statistics by `skfolio` estimators that support it (e.g.
    [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler),
    [`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance)
    If `None`, all active pairs are eligible for estimation. Values are always
    enforced as a subset of `active_mask`.
* **Attributes:**
  [`n_observations`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.n_observations) *int*
  : Number of observations.

  [`n_assets`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.n_assets) *int*
  : Number of assets.

  [`n_fields`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.n_fields) *int*
  : Number of fields.

### Methods

| [`add_2d_field`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.add_2d_field)(name, values, \*[, inactive_policy])   | Add or replace a numeric 2D field.                                                                              |
|------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| [`add_3d_field`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.add_3d_field)(name, values, \*, ...[, ...])          | Add or replace a numeric 3D field.                                                                              |
| [`add_categorical_field`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.add_categorical_field)(name, values, \*, levels)     | Add or replace a 2D categorical field.                                                                          |
| [`align_active_mask_to`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.align_active_mask_to)(fields)                        | Align active periods to valid field values.                                                                     |
| [`bfill`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.bfill)(fields, \*[, limit, inplace])                 | Backward fill NaN values along the observation axis.                                                            |
| [`copy`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.copy)(\*[, deep])                                    | Return a copy of the panel.                                                                                     |
| [`decode_categorical_field`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.decode_categorical_field)(name, \*[, ...])           | Decode a categorical field to labels.                                                                           |
| [`describe`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.describe)(\*[, by])                                  | Return a structured missingness summary.                                                                        |
| [`drop`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.drop)(\*[, observations, assets])                    | Return a panel with selected labels removed.                                                                    |
| [`edit_masks`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.edit_masks)(\*[, \_validate])                        | Temporarily make masks editable.                                                                                |
| [`ffill`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.ffill)(fields, \*[, limit, inplace])                 | Forward fill NaN values along the observation axis.                                                             |
| [`get_field`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.get_field)(name)                                     | Return a field object.                                                                                          |
| [`info`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.info)()                                              | Multi-line report with panel dimensions, mask coverage, field missingness and categorical field level coverage. |
| [`isel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.isel)(\*[, observations, assets])                    | Select observations and assets by integer position.                                                             |
| [`keys`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.keys)()                                              | Return field names.                                                                                             |
| [`load`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.load)(path, \*[, mmap_mode, fields])                 | Load a panel saved with `save`.                                                                                 |
| [`rename`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.rename)([fields, overwrite])                         | Rename fields in place.                                                                                         |
| [`save`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.save)(path, \*[, overwrite])                         | Save the panel to a directory of `.npy` files.                                                                  |
| [`sel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.sel)(\*[, observations, assets, fields])             | Select observations, assets and fields by label.                                                                |
| [`sel_3d`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.sel_3d)(name, \*[, labels, groups])                  | Select entries from the third axis of a 3D field by label.                                                      |
| [`to_dataframe`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.to_dataframe)(\*[, fields, assets, ...])             | Convert 2D fields to a pandas DataFrame.                                                                        |

### Notes

`AssetPanel` is an optimized middle ground between raw NumPy arrays and
general-purpose labeled containers (e.g. pandas, polars, xarray). It is optimized
for portfolio, factor and alpha workflows:

- observations are the sample axis, so scikit-learn cross-validation can slice over
  time without grouping rows
- assets are fixed on axis 1, while `active_mask` represents listings, delistings
  and other universe changes
- payload arrays remain numeric, with categorical fields stored as integer codes
- categorical levels, third-axis labels and third-axis groups are stored with their
  fields
- shape, mask and universe invariants are validated by the container
- estimators can rely on validated axes, masks and float-field universe invariants
  without repeating full container validation

Compared with DataFrames, this avoids repeated `groupby`, `pivot` and
index-alignment work while keeping the arrays ready for vectorized cross-sectional
and time-series operations. Compared with xarray, it keeps a smaller API optimized
for quant workflows.

Performance benefits come from the same layout:

- observation slices return `AssetPanelView` objects, so walk-forward folds can
  reuse field arrays
- native `Field3D` fields avoid restacking large lists of 2D arrays
- integer-coded categoricals and dense boolean masks keep memory and conversion
  overhead low
- with `Parallel(..., prefer="threads")`, workers can read the same big panel in
  memory instead of receiving separate process copies. This is useful for
  NumPy-heavy computations where the numeric kernels release the GIL.
- saved panels use `.npy` files and support memory-mapped loading with
  `AssetPanel.load(..., mmap_mode=...)`.

**Indexing.**

- `panel["name"]` returns the underlying field array.
- `panel.fields["name"]` returns the field object with its metadata.
- `panel[start:stop]` returns an `AssetPanelView` with shared field
  arrays.
- `panel.isel(...)` and `panel.sel(...)` select observations and assets
  by position or label.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.containers import AssetPanel, concat
>>>
>>> n_observations = 252
>>> observations = np.arange(n_observations)
>>> assets = ["AAPL", "MSFT", "GOOG", "AMZN"]
>>> n_assets = len(assets)
>>>
>>> panel = AssetPanel(
...     fields={
...         "returns": np.random.randn(n_observations, n_assets),
...         "volume": np.random.lognormal(size=(n_observations, n_assets)),
...         "market_cap": np.random.lognormal(size=(n_observations, n_assets)),
...     },
...     observations=observations,
...     asset_names=assets,
... )
>>> panel.add_categorical_field(
...     name="industry",
...     values=np.random.randint(0, 3, size=(n_observations, n_assets)),
...     levels=["energy", "bank", "technology"],
... )
AssetPanel(n_observations=252, n_assets=4, n_fields=4)
>>> factor_labels = ["size", "momentum", "value"]
>>> panel.add_3d_field(
...     name="factor_exposure",
...     values=np.random.randn(n_observations, n_assets, len(factor_labels)),
...     third_axis_name="factor",
...     third_axis_labels=factor_labels,
...     third_axis_groups=["style", "style", "style"],
... )
AssetPanel(n_observations=252, n_assets=4, n_fields=5)
>>> panel.n_observations, panel.n_assets, panel.n_fields
(252, 4, 5)
```

Access raw NumPy arrays:

```pycon
>>> returns = panel["returns"]
>>> industry_codes = panel["industry"]
>>> factor_exposure = panel["factor_exposure"]
```

Use field objects or decoding helpers when labels or metadata are needed:

```pycon
>>> industry_labels = panel.decode_categorical_field("industry")
>>> exposure_field = panel.fields["factor_exposure"]
>>> exposure_field.third_axis_labels
array(['size', 'momentum', 'value'], dtype='<U8')
```

Slice observations:

```pycon
>>> view = panel[100:200]
>>> view.n_observations
100
```

Select observations and assets by position or label:

```pycon
>>> panel.isel(observations=slice(0, 60), assets=[0, 1])
AssetPanel(n_observations=60, n_assets=2, n_fields=5)
>>> panel.sel(observations=slice(0, 59), assets=["AAPL", "MSFT"])
AssetPanel(n_observations=60, n_assets=2, n_fields=5)
```

Select entries from a 3D field by third-axis label or group:

```pycon
>>> panel.sel_3d("factor_exposure", labels="momentum").shape
(252, 4)
>>> panel.sel_3d("factor_exposure", groups="style").shape
(252, 4, 3)
```

Convert to pandas:

```pycon
>>> df = panel.to_dataframe(fields=["returns", "industry"], output_format="wide")
```

Get summary and inspect missingness:

```pycon
>>> summary = panel.describe(by="industry")
>>> report = panel.info()
```

Clean selected fields:

```pycon
>>> panel.ffill("returns", inplace=False)
AssetPanel(n_observations=252, n_assets=4, n_fields=5)
>>> panel.bfill("returns", inplace=False)
AssetPanel(n_observations=252, n_assets=4, n_fields=5)
>>> panel.align_active_mask_to("returns")
0
```

Rename field and drop assets:

```pycon
>>> panel.rename({"market_cap": "capitalization"})
AssetPanel(n_observations=252, n_assets=4, n_fields=5)
>>> panel.drop(assets=["AMZN"])
AssetPanel(n_observations=252, n_assets=3, n_fields=5)
```

Concatenate, copy, save and load panels:

```pycon
>>> concat([panel[:126], panel[126:]])
AssetPanel(n_observations=252, n_assets=4, n_fields=5)
>>> panel.copy(deep=True)
AssetPanel(n_observations=252, n_assets=4, n_fields=5)
>>> panel.save("asset_panel")
>>> loaded = AssetPanel.load("asset_panel", mmap_mode="r")
```

<a id="skfolio.containers.AssetPanel.add_2d_field"></a>

#### add_2d_field(name, values, \*, inactive_policy=MISSING)

Add or replace a numeric 2D field.

* **Parameters:**
  **name** *str*
  : Field name.

  **values** *array-like of shape (n_observations, n_assets)*
  : Numeric 2D values.

  **inactive_policy** *InactivePolicy, default=InactivePolicy.MISSING*
  : Validation policy for values outside `active_mask`.
* **Returns:**
  **self** *BaseAssetPanel*
  : The modified container.

<a id="skfolio.containers.AssetPanel.add_3d_field"></a>

#### add_3d_field(name, values, \*, third_axis_name, third_axis_labels, third_axis_groups=None, inactive_policy=MISSING)

Add or replace a numeric 3D field.

This is a convenience wrapper around assigning a `Field3D`. The first two axes
of `values` must be observations and assets with shape (n_observations, n_assets).
The third axis stores a homogeneous block such as factors.

* **Parameters:**
  **name** *str*
  : Field name.

  **values** *array-like of shape (n_observations, n_assets, n_third_axis)*
  : Numeric 3D values.

  **third_axis_name** *str*
  : Name describing what the third axis represents (e.g. `factor`).

  **third_axis_labels** *array-like of shape (n_third_axis,)*
  : Labels for entries along the third axis such as factor names (e.g. `size`,
    `momentum`).

  **third_axis_groups** *array-like of shape (n_third_axis,), optional*
  : Optional group label for each third-axis entry such as factor families (e.g.
    `style`, `industry`).

  **inactive_policy** *InactivePolicy, default=InactivePolicy.MISSING*
  : Validation policy for values outside `active_mask`.
* **Returns:**
  **self** *BaseAssetPanel*
  : The modified container.

<a id="skfolio.containers.AssetPanel.add_categorical_field"></a>

#### add_categorical_field(name, values, \*, levels, inactive_policy=MISSING)

Add or replace a 2D categorical field.

This is a convenience wrapper around assigning a `FieldCategorical`. The field
values must be integer codes with shape (n_observations, n_assets). Code -1 is
reserved for missing values. Code 0 selects `levels[0]`, code 1 selects
`levels[1]` and so on.

* **Parameters:**
  **name** *str*
  : Field name.

  **values** *array-like of integers, shape (n_observations, n_assets)*
  : Integer category codes.

  **levels** *array-like of shape (n_levels,)*
  : Category labels selected by codes 0, 1 and so on.

  **inactive_policy** *InactivePolicy, default=InactivePolicy.MISSING*
  : Validation policy for codes outside `active_mask`.
* **Returns:**
  **self** *BaseAssetPanel*
  : The modified container.

<a id="skfolio.containers.AssetPanel.align_active_mask_to"></a>

#### align_active_mask_to(fields)

Align active periods to valid field values.

For each asset, remove leading `active_mask` entries until the selected fields
have valid values in the remaining active history. If an asset has no valid
active value for a selected field, all active entries for that asset are
removed. Only leading active entries are removed. Missing values after the first
valid active value are left unchanged.

* **Parameters:**
  **fields** *str or iterable of str*
  : Field names used to determine when each asset can become active. Floating
    values must be finite, categorical values must not be missing, and 3D
    floating values must be finite across the third axis.
* **Returns:**
  **n_removed** *int*
  : Number of `(observation, asset)` entries removed from `active_mask`.

<a id="skfolio.containers.AssetPanel.bfill"></a>

#### bfill(fields, \*, limit=None, inplace=True)

Backward fill NaN values along the observation axis.

* **Parameters:**
  **fields** *str or iterable of str*
  : Numeric `Field2D` names to fill.

  **limit** *int or None, optional*
  : Maximum number of consecutive NaN values to fill. If `None`, all consecutive
    NaN values are eligible.

  **inplace** *bool, default=True*
  : If `True`, modify this panel. If `False`, return a shallow copy with filled
    fields.
* **Returns:**
  **panel** *AssetPanel*
  : Modified panel or copied panel.

<a id="skfolio.containers.AssetPanel.copy"></a>

#### copy(\*, deep=False)

Return a copy of the panel.

* **Parameters:**
  **deep** *bool, default=False*
  : If `True`, copy field arrays and label arrays. If `False`, field arrays and
    labels are shared. Masks are always copied so the copy owns independent
    lockable mask arrays.
* **Returns:**
  **panel** *AssetPanel*
  : Copied panel.

<a id="skfolio.containers.AssetPanel.decode_categorical_field"></a>

#### decode_categorical_field(name, \*, missing_label='MISSING')

Decode a categorical field to labels.

* **Parameters:**
  **name** *str*
  : Name of a `FieldCategorical` field.

  **missing_label** *str, default=”MISSING”*
  : Label assigned to missing or out-of-bound codes.
* **Returns:**
  **decoded** *ndarray*
  : Decoded labels with shape (n_observations, n_assets).

<a id="skfolio.containers.AssetPanel.describe"></a>

#### describe(\*, by=None)

Return a structured missingness summary.

* **Parameters:**
  **by** *str or None, optional*
  : Categorical field used to group missingness statistics. If `None`,
    missingness is summarized by field.
* **Returns:**
  **summary** *pandas.DataFrame*
  : Missingness summary indexed by field, or by `(field, category)`
    when `by` is provided.

<a id="skfolio.containers.AssetPanel.drop"></a>

#### drop(\*, observations=None, assets=None)

Return a panel with selected labels removed.

* **Parameters:**
  **observations** *scalar, iterable, or None, optional*
  : Observation labels to remove.

  **assets** *scalar, iterable, or None, optional*
  : Asset labels to remove.
* **Returns:**
  **panel** *AssetPanel*
  : New panel with the selected observations or assets removed.

<a id="skfolio.containers.AssetPanel.edit_masks"></a>

#### edit_masks(\*, \_validate=True)

Temporarily make masks editable.

On exit, `estimation_mask` is re-enforced as a subset of `active_mask`,
field inactive policies are applied, and both masks are locked again.

* **Parameters:**
  **\_validate** *bool, default=True*
  : Internal flag controlling the per-observation non-empty mask check after the
    context exits.
* **Yields:**
  None
  : The panel with editable mask arrays.

<a id="skfolio.containers.AssetPanel.ffill"></a>

#### ffill(fields, \*, limit=None, inplace=True)

Forward fill NaN values along the observation axis.

* **Parameters:**
  **fields** *str or iterable of str*
  : Numeric `Field2D` names to fill.

  **limit** *int or None, optional*
  : Maximum number of consecutive NaN values to fill. If `None`, all consecutive
    NaN values are eligible.

  **inplace** *bool, default=True*
  : If `True`, modify this panel. If `False`, return a shallow copy with filled
    fields.
* **Returns:**
  **panel** *AssetPanel*
  : Modified panel or copied panel.

<a id="skfolio.containers.AssetPanel.get_field"></a>

#### get_field(name)

Return a field object.

* **Parameters:**
  **name** *str*
  : Field name.
* **Returns:**
  **field** *BaseField*
  : Field object that owns the field values and metadata.

<a id="skfolio.containers.AssetPanel.info"></a>

#### info()

Multi-line report with panel dimensions, mask coverage, field missingness
and categorical field level coverage.

* **Returns:**
  **report** *str*
  : Multi-line report.

<a id="skfolio.containers.AssetPanel.isel"></a>

#### isel(\*, observations=None, assets=None)

Select observations and assets by integer position.

* **Parameters:**
  **observations** *int, slice, array-like, or None, optional*
  : Positional selector for the observation axis. If `None`, all  observations
    are selected.

  **assets** *int, slice, array-like, or None, optional*
  : Positional selector for the asset axis. If `None`, assets are not sliced and
    an `AssetPanelView` is returned.
* **Returns:**
  **panel or view** *AssetPanel or AssetPanelView*
  : Observation-only selections return a view. Selections that slice assets
    return a new panel.

<a id="skfolio.containers.AssetPanel.keys"></a>

#### keys()

Return field names.

* **Returns:**
  **names** *KeysView of str*
  : Names of all fields in the panel.

<a id="skfolio.containers.AssetPanel.load"></a>

#### *classmethod* load(path, \*, mmap_mode=None, fields=None)

Load a panel saved with `save`.

* **Parameters:**
  **path** *str or pathlib.Path*
  : Directory containing a saved panel.

  **mmap_mode** *str or None, optional*
  : Memory-mapping mode passed to `numpy.load` for field and mask arrays.
    Use `r` for read-only memory maps.

  **fields** *list of str or None, optional*
  : Field names to load. If `None`, all fields are loaded.
* **Returns:**
  **panel** *AssetPanel*
  : Loaded panel.

<a id="skfolio.containers.AssetPanel.n_assets"></a>

#### *property* n_assets

Number of assets.

<a id="skfolio.containers.AssetPanel.n_fields"></a>

#### *property* n_fields

Number of fields.

<a id="skfolio.containers.AssetPanel.n_observations"></a>

#### *property* n_observations

Number of observations.

<a id="skfolio.containers.AssetPanel.ndim"></a>

#### *property* ndim

Number of dimensions used by scikit-learn sample indexing.

<a id="skfolio.containers.AssetPanel.rename"></a>

#### rename(fields=None, \*, overwrite=False)

Rename fields in place.

* **Parameters:**
  **fields** *mapping of str to str or None, optional*
  : Mapping from existing field names to replacement names.

  **overwrite** *bool, default=False*
  : If `True`, an existing target field can be replaced by a renamed field.
    If `False`, name conflicts raise `KeyError`.
* **Returns:**
  **self** *AssetPanel*
  : The modified panel.

<a id="skfolio.containers.AssetPanel.save"></a>

#### save(path, \*, overwrite=False)

Save the panel to a directory of `.npy` files.

The directory contains one `.npy` file per field, small metadata files for
categorical and third-axis labels and a `_metadata.json` manifest.
Object-dtype axis labels and field metadata labels are converted to strings
so the panel is loaded with `allow_pickle=False`.

* **Parameters:**
  **path** *str or pathlib.Path*
  : Destination directory.

  **overwrite** *bool, default=False*
  : If `True`, replace an existing saved panel at `path`. Existing directories
    that do not contain `_metadata.json` are never overwritten.

<a id="skfolio.containers.AssetPanel.sel"></a>

#### sel(\*, observations=None, assets=None, fields=None)

Select observations, assets and fields by label.

* **Parameters:**
  **observations** *scalar, slice, iterable, or None, optional*
  : Observation labels to select. If `None`, all observations are selected.

  **assets** *scalar, slice, iterable, or None, optional*
  : Asset labels to select. If `None`, assets are not sliced and an
    : `AssetPanelView` is returned.

  **fields** *str, iterable of str, or None, optional*
  : Field names to select. If `None`, all fields are selected.
* **Returns:**
  **panel or view** *AssetPanel or AssetPanelView*
  : Observation-only selections without field filtering return a view.
    Selections that slice assets or fields return a new panel.

<a id="skfolio.containers.AssetPanel.sel_3d"></a>

#### sel_3d(name, \*, labels=None, groups=None)

Select entries from the third axis of a 3D field by label.

Exactly one of `labels` or `groups` must be provided. Selecting a single label
returns a 2D array with shape (n_observations, n_assets). Selecting multiple
labels or any group returns a 3D array whose first two axes are unchanged.

* **Parameters:**
  **name** *str*
  : Name of a `Field3D`.

  **labels** *scalar, iterable, or None, optional*
  : Third-axis labels to select.

  **groups** *scalar, iterable, or None, optional*
  : Third-axis group labels to select. The field must define `third_axis_groups`.
* **Returns:**
  **values** *ndarray*
  : Selected values. A scalar `labels` selection returns 2D values. All other
    selections return 3D values.

<a id="skfolio.containers.AssetPanel.shape"></a>

#### *property* shape

Shape tuple used by scikit-learn sample indexing.

<a id="skfolio.containers.AssetPanel.to_dataframe"></a>

#### to_dataframe(\*, fields=None, assets=None, output_format='long', decode_categoricals=True)

Convert 2D fields to a pandas DataFrame.

`Field3D` entries are skipped with a warning when multiple fields are converted.
Selecting a single `Field3D` raises `ValueError`.

* **Parameters:**
  **fields** *str, iterable of str, or None, optional*
  : Field names to include. If a single string is passed, the result is a simple
    field DataFrame with observations as index and assets as columns. If `None`,
    all 2D fields are included.

  **assets** *str, iterable of str, or None, optional*
  : Asset labels to include. If `None`, all assets are included.

  **output_format** *{“long”, “wide”}, default=”long”*
  : Output format used when `fields` is not a single string. In long format,
    rows are indexed by `(observation, asset)` and filtered by `active_mask`.
    In wide format, columns are indexed by `(field, asset)`.

  **decode_categoricals** *bool, default=True*
  : If `True`, categorical codes are decoded to labels.
* **Returns:**
  **df** *pandas.DataFrame*
  : DataFrame representation of the selected 2D fields.

# generated/skfolio.containers.AssetPanelView.html.md

<a id="skfolio-containers-assetpanelview"></a>

# skfolio.containers.AssetPanelView

<a id="skfolio.containers.AssetPanelView"></a>

### *class* skfolio.containers.AssetPanelView(owner, observation_selector=None, \_local_fields=None)

Observation-sliced view into an `AssetPanel`.

A view stores an observation selector, a reference to its owner and optional
view-local fields. Owner field arrays are sliced lazily on access through `fields`,
`__getitem__` and `get_field`, so building a view never copies owner field data.

When the selector is a slice, all access remains zero-copy and composing nested
views produces another zero-copy slice. When the selector is an integer or boolean
array, NumPy fancy indexing is applied on access and the resulting arrays may be
copies.

New fields can also be added directly to a view. These view-local fields are useful
for derived data that only belongs to one slice (e.g. values computed for a
cross-validation fold). They are stored on the view, do not modify the owner panel,
and must have shape (n_view_observations, n_assets, …).

* **Parameters:**
  **owner** *AssetPanel*
  : Panel that owns the underlying arrays.

  **observation_selector** *slice or ndarray of integers, optional*
  : Selector applied to the owner observation axis. Slices preserve zero-copy
    semantics. Integer arrays follow NumPy fancy-indexing semantics on access.
    The default (`None`) selects all observations.

  **\_local_fields** *dict[str, BaseField], optional*
  : View-local fields. This argument is for internal use. Use `view[name] = value`
    to add local fields.
* **Attributes:**
  [`active_mask`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.active_mask)
  : Active mask selected by the view.

  [`asset_names`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.asset_names)
  : Asset labels.

  [`estimation_mask`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.estimation_mask)
  : Estimation mask selected by the view.

  [`fields`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.fields)
  : Lazy mapping of field objects with view-sized values.

  [`n_assets`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.n_assets)
  : Number of assets.

  [`n_observations`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.n_observations)
  : Number of observations in the view.

  [`ndim`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.ndim)
  : Number of dimensions used by scikit-learn sample indexing.

  **observation_selector**

  [`observations`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.observations)
  : Observation labels selected by the view.

  **owner**

  [`shape`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.shape)
  : Shape tuple used by scikit-learn sample indexing.

### Methods

| [`add_2d_field`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.add_2d_field)(name, values, \*[, inactive_policy])   | Add or replace a numeric 2D field.                              |
|------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|
| [`add_3d_field`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.add_3d_field)(name, values, \*, ...[, ...])          | Add or replace a numeric 3D field.                              |
| [`add_categorical_field`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.add_categorical_field)(name, values, \*, levels)     | Add or replace a 2D categorical field.                          |
| [`copy`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.copy)(\*[, deep, copy_owner])                        | Return a copy of the view.                                      |
| [`decode_categorical_field`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.decode_categorical_field)(name, \*[, ...])           | Decode a categorical field to labels.                           |
| [`get_field`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.get_field)(name)                                     | Return a local field or an owner field sliced to the view.      |
| [`keys`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.keys)()                                              | Return field names visible from the view.                       |
| [`sel_3d`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.sel_3d)(name, \*[, labels, groups])                  | Select entries from the third axis of a 3D field by label.      |
| [`to_dataframe`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.to_dataframe)(\*[, fields, assets, ...])             | Convert 2D fields to a pandas DataFrame.                        |
| [`to_panel`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView.to_panel)(\*[, fields, deep])                        | Return a new `AssetPanel` for the view's selected observations. |

#### SEE ALSO
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)
: Owning container.

[`AssetPanel.isel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.isel)
: Returns a view for observation-only selections.

[`AssetPanel.sel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel.sel)
: Label-based equivalent of `AssetPanel.isel`.

<a id="skfolio.containers.AssetPanelView.active_mask"></a>

#### *property* active_mask

Active mask selected by the view.

<a id="skfolio.containers.AssetPanelView.add_2d_field"></a>

#### add_2d_field(name, values, \*, inactive_policy=MISSING)

Add or replace a numeric 2D field.

* **Parameters:**
  **name** *str*
  : Field name.

  **values** *array-like of shape (n_observations, n_assets)*
  : Numeric 2D values.

  **inactive_policy** *InactivePolicy, default=InactivePolicy.MISSING*
  : Validation policy for values outside `active_mask`.
* **Returns:**
  **self** *BaseAssetPanel*
  : The modified container.

<a id="skfolio.containers.AssetPanelView.add_3d_field"></a>

#### add_3d_field(name, values, \*, third_axis_name, third_axis_labels, third_axis_groups=None, inactive_policy=MISSING)

Add or replace a numeric 3D field.

This is a convenience wrapper around assigning a `Field3D`. The first two axes
of `values` must be observations and assets with shape (n_observations, n_assets).
The third axis stores a homogeneous block such as factors.

* **Parameters:**
  **name** *str*
  : Field name.

  **values** *array-like of shape (n_observations, n_assets, n_third_axis)*
  : Numeric 3D values.

  **third_axis_name** *str*
  : Name describing what the third axis represents (e.g. `factor`).

  **third_axis_labels** *array-like of shape (n_third_axis,)*
  : Labels for entries along the third axis such as factor names (e.g. `size`,
    `momentum`).

  **third_axis_groups** *array-like of shape (n_third_axis,), optional*
  : Optional group label for each third-axis entry such as factor families (e.g.
    `style`, `industry`).

  **inactive_policy** *InactivePolicy, default=InactivePolicy.MISSING*
  : Validation policy for values outside `active_mask`.
* **Returns:**
  **self** *BaseAssetPanel*
  : The modified container.

<a id="skfolio.containers.AssetPanelView.add_categorical_field"></a>

#### add_categorical_field(name, values, \*, levels, inactive_policy=MISSING)

Add or replace a 2D categorical field.

This is a convenience wrapper around assigning a `FieldCategorical`. The field
values must be integer codes with shape (n_observations, n_assets). Code -1 is
reserved for missing values. Code 0 selects `levels[0]`, code 1 selects
`levels[1]` and so on.

* **Parameters:**
  **name** *str*
  : Field name.

  **values** *array-like of integers, shape (n_observations, n_assets)*
  : Integer category codes.

  **levels** *array-like of shape (n_levels,)*
  : Category labels selected by codes 0, 1 and so on.

  **inactive_policy** *InactivePolicy, default=InactivePolicy.MISSING*
  : Validation policy for codes outside `active_mask`.
* **Returns:**
  **self** *BaseAssetPanel*
  : The modified container.

<a id="skfolio.containers.AssetPanelView.asset_names"></a>

#### *property* asset_names

Asset labels.

<a id="skfolio.containers.AssetPanelView.copy"></a>

#### copy(\*, deep=False, copy_owner=True)

Return a copy of the view.

* **Parameters:**
  **deep** *bool, default=False*
  : If `True`, copy local field arrays and the observation selector when
    it is an ndarray.

  **copy_owner** *bool, default=True*
  : If `True`, copy the owner panel. If `False`, the copied view points
    to the same owner.
* **Returns:**
  **view** *AssetPanelView*
  : Copied view.

<a id="skfolio.containers.AssetPanelView.decode_categorical_field"></a>

#### decode_categorical_field(name, \*, missing_label='MISSING')

Decode a categorical field to labels.

* **Parameters:**
  **name** *str*
  : Name of a `FieldCategorical` field.

  **missing_label** *str, default=”MISSING”*
  : Label assigned to missing or out-of-bound codes.
* **Returns:**
  **decoded** *ndarray*
  : Decoded labels with shape (n_observations, n_assets).

<a id="skfolio.containers.AssetPanelView.estimation_mask"></a>

#### *property* estimation_mask

Estimation mask selected by the view.

<a id="skfolio.containers.AssetPanelView.fields"></a>

#### *property* fields

Lazy mapping of field objects with view-sized values.

Field objects are constructed on access and reuse the owner array sliced by
`observation_selector`. Iterating through this mapping does not materialize
sliced arrays for fields that are not accessed.

<a id="skfolio.containers.AssetPanelView.get_field"></a>

#### get_field(name)

Return a local field or an owner field sliced to the view.

* **Parameters:**
  **name** *str*
  : Field name.
* **Returns:**
  **field** *BaseField*
  : Field object with first two axes matching the view.

<a id="skfolio.containers.AssetPanelView.keys"></a>

#### keys()

Return field names visible from the view.

* **Returns:**
  **names** *list of str*
  : Union of view-local field names and owner field names. Local fields shadow
    owner fields with the same name. Owner field order is preserved and
    local-only fields are appended in insertion order.

<a id="skfolio.containers.AssetPanelView.n_assets"></a>

#### *property* n_assets

Number of assets.

<a id="skfolio.containers.AssetPanelView.n_observations"></a>

#### *property* n_observations

Number of observations in the view.

<a id="skfolio.containers.AssetPanelView.ndim"></a>

#### *property* ndim

Number of dimensions used by scikit-learn sample indexing.

<a id="skfolio.containers.AssetPanelView.observations"></a>

#### *property* observations

Observation labels selected by the view.

<a id="skfolio.containers.AssetPanelView.sel_3d"></a>

#### sel_3d(name, \*, labels=None, groups=None)

Select entries from the third axis of a 3D field by label.

Exactly one of `labels` or `groups` must be provided. Selecting a single label
returns a 2D array with shape (n_observations, n_assets). Selecting multiple
labels or any group returns a 3D array whose first two axes are unchanged.

* **Parameters:**
  **name** *str*
  : Name of a `Field3D`.

  **labels** *scalar, iterable, or None, optional*
  : Third-axis labels to select.

  **groups** *scalar, iterable, or None, optional*
  : Third-axis group labels to select. The field must define `third_axis_groups`.
* **Returns:**
  **values** *ndarray*
  : Selected values. A scalar `labels` selection returns 2D values. All other
    selections return 3D values.

<a id="skfolio.containers.AssetPanelView.shape"></a>

#### *property* shape

Shape tuple used by scikit-learn sample indexing.

<a id="skfolio.containers.AssetPanelView.to_dataframe"></a>

#### to_dataframe(\*, fields=None, assets=None, output_format='long', decode_categoricals=True)

Convert 2D fields to a pandas DataFrame.

* **Parameters:**
  **fields** *str, iterable of str, or None, optional*
  : Field names to include. If a single string is passed, the result is a simple
    field DataFrame with observations as index and assets as columns. If `None`,
    all 2D fields are included.

  **assets** *str, iterable of str, or None, optional*
  : Asset labels to include. If `None`, all assets are included.

  **output_format** *{“long”, “wide”}, default=”long”*
  : Output format used when `fields` is not a single string. In long format,
    rows are indexed by `(observation, asset)` and filtered by `active_mask`.
    In wide format, columns are indexed by `(field, asset)`.

  **decode_categoricals** *bool, default=True*
  : If `True`, categorical codes are decoded to labels.
* **Returns:**
  **df** *pandas.DataFrame*
  : DataFrame representation of the selected 2D fields.

<a id="skfolio.containers.AssetPanelView.to_panel"></a>

#### to_panel(\*, fields=None, deep=True)

Return a new `AssetPanel` for the view’s selected observations.

* **Parameters:**
  **fields** *str, iterable of str, or None, optional*
  : Field names to include. If `None`, all visible fields are included.

  **deep** *bool, default=True*
  : If `True`, copy field arrays and label arrays. If `False`, field arrays and
    labels may share memory with the view source. Masks are always copied so the
    returned panel owns independent lockable mask arrays.
* **Returns:**
  **panel** *AssetPanel*
  : Panel containing only the view’s observations and selected fields.

# generated/skfolio.containers.BaseField.html.md

<a id="skfolio-containers-basefield"></a>

# skfolio.containers.BaseField

<a id="skfolio.containers.BaseField"></a>

### *class* skfolio.containers.BaseField(values, \*, inactive_policy=MISSING)

Base class for fields stored in an `AssetPanel`.

A field stores a NumPy array for one named variable. The first two axes are always
observations and assets with shape (n_observations, n_assets).
Subclasses define any additional metadata required by the array layout.

* **Parameters:**
  **values** *ndarray of shape (n_observations, n_assets)*
  : Field values. The first two axes must be observations and assets.
* **Attributes:**
  [`dtype`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField.dtype)
  : Dtype of the underlying values.

  **inactive_policy**

  [`is_3d`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField.is_3d)
  : Whether or not the field is a 3D field.

  [`is_categorical`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField.is_categorical)
  : Whether or not the field is a categorical field.

  [`missing_mask`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField.missing_mask)
  : Return a boolean mask indicating missing entries.

  [`n_assets`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField.n_assets)
  : Number of assets.

  [`n_observations`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField.n_observations)
  : Number of observations.

  [`ndim`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField.ndim)
  : Number of dimensions of the underlying values.

  [`shape`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField.shape)
  : Shape of the underlying values.

  **values**

### Methods

| [`copy`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField.copy)(\*[, deep])    | Return a copy of the field.                              |
|----------------------------------------------------------------------|----------------------------------------------------------|
| [`with_values`](https://skfolio.org/generated/skfolio.containers.BaseField.html.md#skfolio.containers.BaseField.with_values)(values) | Return a field of the same type with replacement values. |

<a id="skfolio.containers.BaseField.copy"></a>

#### copy(\*, deep=False)

Return a copy of the field.

* **Parameters:**
  **deep** *bool, default=False*
  : If `True`, copy NumPy arrays stored by the field. If `False`, reuse the same
    array objects.
* **Returns:**
  **field** *BaseField*
  : Field instance of the same concrete class.

<a id="skfolio.containers.BaseField.dtype"></a>

#### *property* dtype

Dtype of the underlying values.

<a id="skfolio.containers.BaseField.is_3d"></a>

#### *property* is_3d

Whether or not the field is a 3D field.

<a id="skfolio.containers.BaseField.is_categorical"></a>

#### *property* is_categorical

Whether or not the field is a categorical field.

<a id="skfolio.containers.BaseField.missing_mask"></a>

#### *property* missing_mask

Return a boolean mask indicating missing entries.

* **Returns:**
  **mask** *ndarray of bool*
  : Boolean array with the same shape as `values`. Entries are `True`
    where `values` is NaN for floating-point fields and `False` elsewhere.
    Non-floating fields without a missing-value convention return an all-`False`
    mask; subclasses override this method when they define their own convention.

<a id="skfolio.containers.BaseField.n_assets"></a>

#### *property* n_assets

Number of assets.

<a id="skfolio.containers.BaseField.n_observations"></a>

#### *property* n_observations

Number of observations.

<a id="skfolio.containers.BaseField.ndim"></a>

#### *property* ndim

Number of dimensions of the underlying values.

<a id="skfolio.containers.BaseField.shape"></a>

#### *property* shape

Shape of the underlying values.

<a id="skfolio.containers.BaseField.with_values"></a>

#### with_values(values)

Return a field of the same type with replacement values.

Metadata arrays are reused. The replacement values are validated by the
concrete field class constructor.

* **Parameters:**
  **values** *array-like*
  : Replacement field values.
* **Returns:**
  **field** *BaseField*
  : Field instance of the same concrete class.

# generated/skfolio.containers.Field2D.html.md

<a id="skfolio-containers-field2d"></a>

# skfolio.containers.Field2D

<a id="skfolio.containers.Field2D"></a>

### *class* skfolio.containers.Field2D(values, \*, inactive_policy=MISSING)

Numeric 2D field with axes (observations, assets).

* **Parameters:**
  **values** *ndarray of shape (n_observations, n_assets)*
  : Numeric field values. Object dtype is rejected. Use `FieldCategorical` for
    categorical data.
* **Attributes:**
  [`dtype`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D.dtype)
  : Dtype of the underlying values.

  **inactive_policy**

  [`is_3d`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D.is_3d)
  : Whether or not the field is a 3D field.

  [`is_categorical`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D.is_categorical)
  : Whether or not the field is a categorical field.

  [`missing_mask`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D.missing_mask)
  : Return a boolean mask indicating missing entries.

  [`n_assets`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D.n_assets)
  : Number of assets.

  [`n_observations`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D.n_observations)
  : Number of observations.

  [`ndim`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D.ndim)
  : Number of dimensions of the underlying values.

  [`shape`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D.shape)
  : Shape of the underlying values.

  **values**

### Methods

| [`copy`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D.copy)(\*[, deep])    | Return a copy of the field.                              |
|----------------------------------------------------------------------|----------------------------------------------------------|
| [`with_values`](https://skfolio.org/generated/skfolio.containers.Field2D.html.md#skfolio.containers.Field2D.with_values)(values) | Return a field of the same type with replacement values. |

<a id="skfolio.containers.Field2D.copy"></a>

#### copy(\*, deep=False)

Return a copy of the field.

* **Parameters:**
  **deep** *bool, default=False*
  : If `True`, copy NumPy arrays stored by the field. If `False`, reuse the same
    array objects.
* **Returns:**
  **field** *BaseField*
  : Field instance of the same concrete class.

<a id="skfolio.containers.Field2D.dtype"></a>

#### *property* dtype

Dtype of the underlying values.

<a id="skfolio.containers.Field2D.is_3d"></a>

#### *property* is_3d

Whether or not the field is a 3D field.

<a id="skfolio.containers.Field2D.is_categorical"></a>

#### *property* is_categorical

Whether or not the field is a categorical field.

<a id="skfolio.containers.Field2D.missing_mask"></a>

#### *property* missing_mask

Return a boolean mask indicating missing entries.

* **Returns:**
  **mask** *ndarray of bool*
  : Boolean array with the same shape as `values`. Entries are `True`
    where `values` is NaN for floating-point fields and `False` elsewhere.
    Non-floating fields without a missing-value convention return an all-`False`
    mask; subclasses override this method when they define their own convention.

<a id="skfolio.containers.Field2D.n_assets"></a>

#### *property* n_assets

Number of assets.

<a id="skfolio.containers.Field2D.n_observations"></a>

#### *property* n_observations

Number of observations.

<a id="skfolio.containers.Field2D.ndim"></a>

#### *property* ndim

Number of dimensions of the underlying values.

<a id="skfolio.containers.Field2D.shape"></a>

#### *property* shape

Shape of the underlying values.

<a id="skfolio.containers.Field2D.with_values"></a>

#### with_values(values)

Return a field of the same type with replacement values.

Metadata arrays are reused. The replacement values are validated by the
concrete field class constructor.

* **Parameters:**
  **values** *array-like*
  : Replacement field values.
* **Returns:**
  **field** *BaseField*
  : Field instance of the same concrete class.

# generated/skfolio.containers.Field3D.html.md

<a id="skfolio-containers-field3d"></a>

# skfolio.containers.Field3D

<a id="skfolio.containers.Field3D"></a>

### *class* skfolio.containers.Field3D(values, third_axis_name, third_axis_labels, third_axis_groups=None, \*, inactive_policy=MISSING)

Numeric 3D field with axes (observations, assets, third_axis).

Use this field for homogeneous tensors (e.g. factor exposures). The third-axis
metadata is stored on the field. The array is stored physically in 3D so that
operations along any axis remain vectorized and avoid stacking many 2D arrays which
is expensive for large panels. When you need repeated tensor operations, prefer a
`Field3D` instead of multiple `Field2D`.

* **Parameters:**
  **values** *ndarray of shape `(n_observations, n_assets, n_third_axis)`*
  : Numeric 3D values. Object dtype is rejected.

  **third_axis_name** *str*
  : Name describing what the third axis represents (e.g. `factor`).

  **third_axis_labels** *ndarray of shape (n_third_axis,)*
  : Labels for entries along the third axis such as factor names (`size`,
    `momentum`). Labels must be unique.

  **third_axis_groups** *ndarray of shape (n_third_axis,), optional*
  : Optional group label for each third-axis entry such as factor families (e.g.
    `style`, `industry`, `country`).
* **Attributes:**
  [`dtype`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D.dtype)
  : Dtype of the underlying values.

  **inactive_policy**

  [`is_3d`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D.is_3d)
  : Whether or not the field is a 3D field.

  [`is_categorical`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D.is_categorical)
  : Whether or not the field is a categorical field.

  [`missing_mask`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D.missing_mask)
  : Return a boolean mask indicating missing entries.

  [`n_assets`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D.n_assets)
  : Number of assets.

  [`n_observations`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D.n_observations)
  : Number of observations.

  [`ndim`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D.ndim)
  : Number of dimensions of the underlying values.

  [`shape`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D.shape)
  : Shape of the underlying values.

  **third_axis_groups**

  **third_axis_labels**

  **third_axis_name**

  **values**

### Methods

| [`copy`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D.copy)(\*[, deep])    | Return a copy of the field.                              |
|----------------------------------------------------------------------|----------------------------------------------------------|
| [`with_values`](https://skfolio.org/generated/skfolio.containers.Field3D.html.md#skfolio.containers.Field3D.with_values)(values) | Return a field of the same type with replacement values. |

<a id="skfolio.containers.Field3D.copy"></a>

#### copy(\*, deep=False)

Return a copy of the field.

* **Parameters:**
  **deep** *bool, default=False*
  : If `True`, copy NumPy arrays stored by the field. If `False`, reuse the same
    array objects.
* **Returns:**
  **field** *BaseField*
  : Field instance of the same concrete class.

<a id="skfolio.containers.Field3D.dtype"></a>

#### *property* dtype

Dtype of the underlying values.

<a id="skfolio.containers.Field3D.is_3d"></a>

#### *property* is_3d

Whether or not the field is a 3D field.

<a id="skfolio.containers.Field3D.is_categorical"></a>

#### *property* is_categorical

Whether or not the field is a categorical field.

<a id="skfolio.containers.Field3D.missing_mask"></a>

#### *property* missing_mask

Return a boolean mask indicating missing entries.

* **Returns:**
  **mask** *ndarray of bool*
  : Boolean array with the same shape as `values`. Entries are `True`
    where `values` is NaN for floating-point fields and `False` elsewhere.
    Non-floating fields without a missing-value convention return an all-`False`
    mask; subclasses override this method when they define their own convention.

<a id="skfolio.containers.Field3D.n_assets"></a>

#### *property* n_assets

Number of assets.

<a id="skfolio.containers.Field3D.n_observations"></a>

#### *property* n_observations

Number of observations.

<a id="skfolio.containers.Field3D.ndim"></a>

#### *property* ndim

Number of dimensions of the underlying values.

<a id="skfolio.containers.Field3D.shape"></a>

#### *property* shape

Shape of the underlying values.

<a id="skfolio.containers.Field3D.with_values"></a>

#### with_values(values)

Return a field of the same type with replacement values.

Metadata arrays are reused. The replacement values are validated by the
concrete field class constructor.

* **Parameters:**
  **values** *array-like*
  : Replacement field values.
* **Returns:**
  **field** *BaseField*
  : Field instance of the same concrete class.

# generated/skfolio.containers.FieldCategorical.html.md

<a id="skfolio-containers-fieldcategorical"></a>

# skfolio.containers.FieldCategorical

<a id="skfolio.containers.FieldCategorical"></a>

### *class* skfolio.containers.FieldCategorical(values, levels, \*, inactive_policy=MISSING)

Integer-coded categorical 2D field.

Codes are stored as integers in a 2D array with axes (observations, assets).
Code -1 is reserved for missing values. Code 0 selects `levels[0]`, code 1 selects
`levels[1]` and so on.

* **Parameters:**
  **values** *integers ndarray of shape (n_observations, n_assets)*
  : Integer category codes. Missing values must be encoded with
    `MISSING_CATEGORY_CODE`.

  **levels** *ndarray of shape (n_levels,)*
  : Category labels selected by codes 0, 1 and so on.
    Labels must be unique.
* **Attributes:**
  [`dtype`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.dtype)
  : Dtype of the underlying values.

  **inactive_policy**

  [`is_3d`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.is_3d)
  : Whether or not the field is a 3D field.

  [`is_categorical`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.is_categorical)
  : Whether or not the field is a categorical field.

  **levels**

  [`missing_mask`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.missing_mask)
  : Return a boolean mask indicating missing categorical codes.

  [`n_assets`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.n_assets)
  : Number of assets.

  [`n_observations`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.n_observations)
  : Number of observations.

  [`ndim`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.ndim)
  : Number of dimensions of the underlying values.

  [`shape`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.shape)
  : Shape of the underlying values.

  **values**

### Methods

| [`copy`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.copy)(\*[, deep])            | Return a copy of the field.                              |
|------------------------------------------------------------------------------|----------------------------------------------------------|
| [`decode`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.decode)(\*[, missing_label]) | Decode integer codes to level labels.                    |
| [`with_values`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical.with_values)(values)         | Return a field of the same type with replacement values. |

<a id="skfolio.containers.FieldCategorical.copy"></a>

#### copy(\*, deep=False)

Return a copy of the field.

* **Parameters:**
  **deep** *bool, default=False*
  : If `True`, copy NumPy arrays stored by the field. If `False`, reuse the same
    array objects.
* **Returns:**
  **field** *BaseField*
  : Field instance of the same concrete class.

<a id="skfolio.containers.FieldCategorical.decode"></a>

#### decode(\*, missing_label='MISSING')

Decode integer codes to level labels.

* **Parameters:**
  **missing_label** *str, default=”MISSING”*
  : Label assigned to missing or out-of-bound codes.
* **Returns:**
  **decoded** *ndarray*
  : Decoded labels with the same shape as `values`.

<a id="skfolio.containers.FieldCategorical.dtype"></a>

#### *property* dtype

Dtype of the underlying values.

<a id="skfolio.containers.FieldCategorical.is_3d"></a>

#### *property* is_3d

Whether or not the field is a 3D field.

<a id="skfolio.containers.FieldCategorical.is_categorical"></a>

#### *property* is_categorical

Whether or not the field is a categorical field.

<a id="skfolio.containers.FieldCategorical.missing_mask"></a>

#### *property* missing_mask

Return a boolean mask indicating missing categorical codes.

* **Returns:**
  **mask** *ndarray of bool*
  : Boolean array with the same shape as `values`. Entries are `True`
    where `values` equals `MISSING_CATEGORY_CODE`.

<a id="skfolio.containers.FieldCategorical.n_assets"></a>

#### *property* n_assets

Number of assets.

<a id="skfolio.containers.FieldCategorical.n_observations"></a>

#### *property* n_observations

Number of observations.

<a id="skfolio.containers.FieldCategorical.ndim"></a>

#### *property* ndim

Number of dimensions of the underlying values.

<a id="skfolio.containers.FieldCategorical.shape"></a>

#### *property* shape

Shape of the underlying values.

<a id="skfolio.containers.FieldCategorical.with_values"></a>

#### with_values(values)

Return a field of the same type with replacement values.

Metadata arrays are reused. The replacement values are validated by the
concrete field class constructor.

* **Parameters:**
  **values** *array-like*
  : Replacement field values.
* **Returns:**
  **field** *BaseField*
  : Field instance of the same concrete class.

# generated/skfolio.containers.InactivePolicy.html.md

<a id="skfolio-containers-inactivepolicy"></a>

# skfolio.containers.InactivePolicy

<a id="skfolio.containers.InactivePolicy"></a>

### *class* skfolio.containers.InactivePolicy(\*values)

Validation policy for values outside an `AssetPanel` active universe.

<a id="skfolio.containers.InactivePolicy.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.containers.concat.html.md

<a id="skfolio-containers-concat"></a>

# skfolio.containers.concat

<a id="skfolio.containers.concat"></a>

### skfolio.containers.concat(panels, \*, verify_observations=False)

Concatenate panels along the observation axis.

This function performs strict vertical concatenation. All panels or panel views
must have identical assets, field names, field types, field dtypes, categorical
levels and 3D field metadata. Field arrays, observations, `active_mask` and
`estimation_mask` are concatenated on axis 0.

* **Parameters:**
  **panels** *iterable of AssetPanel or AssetPanelView*
  : Panels or panel views to concatenate. The iterable must contain at least one
    object.

  **verify_observations** *bool, default=False*
  : If `True`, raise an error when the concatenated observation labels contain
    duplicates.
* **Returns:**
  **panel** *AssetPanel*
  : Concatenated panel.

### Examples

```pycon
>>> from skfolio.containers import AssetPanel, concat
>>>
>>> panel_1 = AssetPanel(
...     fields={"returns": [[0.01, 0.02]]},
...     observations=["2024-01-01"],
...     asset_names=["A", "B"],
... )
>>> panel_2 = AssetPanel(
...     fields={"returns": [[0.03, 0.04]]},
...     observations=["2024-01-02"],
...     asset_names=["A", "B"],
... )
>>> concat([panel_1, panel_2])
AssetPanel(n_observations=2, n_assets=2, n_fields=1)
```

# generated/skfolio.datasets.load_factors_dataset.html.md

<a id="skfolio-datasets-load-factors-dataset"></a>

# skfolio.datasets.load_factors_dataset

<a id="skfolio.datasets.load_factors_dataset"></a>

### skfolio.datasets.load_factors_dataset()

Load the prices of 5 factor ETFs.

This dataset contains daily adjusted closing prices of 5 ETFs representing common
factors, covering the period from 2014-01-02 up to 2022-12-28.

The factors are:

> * “MTUM”: Momentum
> * “QUAL”: Quality
> * “SIZE”: Size
> * “VLUE”: Value
> * “USMV”: low volatility

#### CAUTION
This dataset is provided solely for testing and example purposes. It is a stale
dataset and does not reflect current or accurate market prices. It is not
intended for investment, trading, or commercial use and should not be relied
upon as authoritative market data.

| Observations   |   2264 |
|----------------|--------|
| Assets         |      5 |
* **Returns:**
  **df** *DataFrame of shape (n_observations, n_assets)*
  : Prices DataFrame

### Examples

```pycon
>>> from skfolio.datasets import load_factors_dataset
>>> prices = load_factors_dataset()
>>> prices.head()
              MTUM    QUAL    SIZE    USMV    VLUE
Date
2014-01-02  52.704  48.351  48.986  29.338  47.054
2014-01-03  52.792  48.256  48.722  29.330  46.999
2014-01-06  52.677  48.067  48.722  29.263  46.991
2014-01-07  53.112  48.455  48.731  29.430  47.253
2014-01-08  53.502  48.437  48.731  29.422  47.253
```

# generated/skfolio.datasets.load_ftse100_dataset.html.md

<a id="skfolio-datasets-load-ftse100-dataset"></a>

# skfolio.datasets.load_ftse100_dataset

<a id="skfolio.datasets.load_ftse100_dataset"></a>

### skfolio.datasets.load_ftse100_dataset(data_home=None, download_if_missing=True)

Load the prices of 64 assets from the FTSE 100 Index composition.

This dataset contains daily adjusted closing prices of 64 assets from the FTSE 100
Index, covering the period from 2000-01-04 up to 2023-05-31.
The data contains NaN.

#### CAUTION
This dataset is provided solely for testing and example purposes. It is a stale
dataset and does not reflect current or accurate market prices. It is not
intended for investment, trading, or commercial use and should not be relied
upon as authoritative market data.

| Observations   |   5960 |
|----------------|--------|
| Assets         |     64 |
* **Parameters:**
  **data_home** *str, optional*
  : Specify another download and cache folder for the datasets.
    By default, all skfolio data is stored in `~/skfolio_data` subfolders.

  **download_if_missing** *bool, default=True*
  : If False, raise an OSError if the data is not locally available
    instead of trying to download the data from the source site.
* **Returns:**
  **df** *DataFrame of shape (n_observations, n_assets)*
  : Prices DataFrame

### Examples

```pycon
>>> from skfolio.datasets import load_ftse100_dataset
>>> prices = load_ftse100_dataset()
>>> prices.head()
              AAL.L    ABF.L   AHT.L  ANTO.L  ...   VOD.L   WEIR.L    WPP.L    WTB.L
Date                                          ...
2000-01-04  535.354  205.926  97.590  40.313  ...  72.562  115.240  512.249  382.907
2000-01-05  540.039  209.185  96.729  40.313  ...  69.042  118.483  462.080  381.972
2000-01-06  553.289  229.048  95.581  40.452  ...  66.950  124.220  458.119  386.337
2000-01-07  572.829  222.220  95.581  40.452  ...  70.716  121.725  475.283  405.046
2000-01-10  578.852  224.548  92.711  40.685  ...  74.285  121.476  498.254  392.885

[5 rows x 64 columns]
```

# generated/skfolio.datasets.load_nasdaq_dataset.html.md

<a id="skfolio-datasets-load-nasdaq-dataset"></a>

# skfolio.datasets.load_nasdaq_dataset

<a id="skfolio.datasets.load_nasdaq_dataset"></a>

### skfolio.datasets.load_nasdaq_dataset(data_home=None, download_if_missing=True)

Load the prices of 1455 assets from the NASDAQ Composite Index.

This dataset contains daily adjusted closing prices of 1455 assets from the NASDAQ
Composite, covering the period from 2018-01-02 up to 2023-05-31.

#### CAUTION
This dataset is provided solely for testing and example purposes. It is a stale
dataset and does not reflect current or accurate market prices. It is not
intended for investment, trading, or commercial use and should not be relied
upon as authoritative market data.

| Observations   |   1362 |
|----------------|--------|
| Assets         |   1455 |
* **Parameters:**
  **data_home** *str, optional*
  : Specify another download and cache folder for the datasets.
    By default, all skfolio data is stored in `~/skfolio_data` subfolders.

  **download_if_missing** *bool, default=True*
  : If False, raise an OSError if the data is not locally available
    instead of trying to download the data from the source site.
* **Returns:**
  **df** *DataFrame of shape (n_observations, n_assets)*
  : Prices DataFrame

### Examples

```pycon
>>> from skfolio.datasets import load_nasdaq_dataset
>>> prices = load_nasdaq_dataset()
>>> prices.head()
               AAL   AAOI    AAON    AAPL  ...  ZVRA   ZYME    ZYNE   ZYXI
Date                                       ...
2018-01-02  51.648  37.91  35.621  41.310  ...  66.4  7.933  12.995  2.922
2018-01-03  51.014  37.89  36.247  41.303  ...  72.8  7.965  13.460  2.913
2018-01-04  51.336  38.38  36.103  41.495  ...  78.4  8.430  12.700  2.869
2018-01-05  51.316  38.89  36.681  41.967  ...  77.6  8.400  12.495  2.780
2018-01-08  50.809  38.37  36.103  41.811  ...  82.4  8.310  12.550  2.825

[5 rows x 1455 columns]
```

# generated/skfolio.datasets.load_sp500_dataset.html.md

<a id="skfolio-datasets-load-sp500-dataset"></a>

# skfolio.datasets.load_sp500_dataset

<a id="skfolio.datasets.load_sp500_dataset"></a>

### skfolio.datasets.load_sp500_dataset()

Load the prices of 20 assets from the S&P 500 Index.

This dataset contains daily adjusted closing prices for 20 selected constituents of
the S&P 500 Index, covering the period from 1990-01-02 to 2022-12-28.

#### CAUTION
This dataset is provided solely for testing and example purposes. It is a stale
dataset and does not reflect current or accurate market prices. It is not
intended for investment, trading, or commercial use and should not be relied
upon as authoritative market data.

| Observations   |   8313 |
|----------------|--------|
| Assets         |     20 |
* **Returns:**
  **df** *DataFrame of shape (n_observations, n_assets)*
  : Prices DataFrame

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> prices = load_sp500_dataset()
>>> prices.head()
             AAPL    AMD    BAC    BBY  ...    RRC    UNH    WMT    XOM
Date                                    ...
1990-01-02  0.264  4.125  4.599  0.144  ...  3.322  0.310  3.653  4.068
1990-01-03  0.266  4.000  4.636  0.161  ...  3.322  0.304  3.653  4.027
1990-01-04  0.267  3.938  4.537  0.159  ...  3.322  0.301  3.634  3.987
1990-01-05  0.268  3.812  4.438  0.159  ...  3.322  0.288  3.595  3.966
1990-01-08  0.269  3.812  4.463  0.147  ...  3.322  0.282  3.644  4.027

[5 rows x 20 columns]
```

# generated/skfolio.datasets.load_sp500_implied_vol_dataset.html.md

<a id="skfolio-datasets-load-sp500-implied-vol-dataset"></a>

# skfolio.datasets.load_sp500_implied_vol_dataset

<a id="skfolio.datasets.load_sp500_implied_vol_dataset"></a>

### skfolio.datasets.load_sp500_implied_vol_dataset(data_home=None, download_if_missing=True)

Load the 3 months ATM implied volatility of the 20 assets from the
SP500 dataset.

This dataset is composed of the 3 months ATM implied volatility of 20 assets
from the S&P 500 composition starting from 2010-01-04 up to 2022-12-28.

#### CAUTION
This dataset is provided solely for testing and example purposes. It is a stale
dataset and does not reflect current or accurate market prices. It is not
intended for investment, trading, or commercial use and should not be relied
upon as authoritative market data.

| Observations   |   3270 |
|----------------|--------|
| Assets         |     20 |
* **Parameters:**
  **data_home** *str, optional*
  : Specify another download and cache folder for the datasets.
    By default, all skfolio data is stored in `~/skfolio_data` subfolders.

  **download_if_missing** *bool, default=True*
  : If False, raise an OSError if the data is not locally available
    instead of trying to download the data from the source site.
* **Returns:**
  **df** *DataFrame of shape (n_observations, n_assets)*
  : Implied volatility DataFrame

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_implied_vol_dataset
>>> implied_vol = load_sp500_implied_vol_dataset()
>>> implied_vol.head()
                AAPL       AMD       BAC  ...       UNH       WMT       XOM
Date                                      ...
2010-01-04  0.364353  0.572056  0.382926  ...  0.362751  0.171737  0.201485
2010-01-05  0.371865  0.568791  0.374699  ...  0.368504  0.174764  0.203852
2010-01-06  0.356746  0.558054  0.349220  ...  0.368514  0.171892  0.197475
2010-01-07  0.361084  0.560475  0.354942  ...  0.355792  0.169083  0.200046
2010-01-08  0.348085  0.543932  0.360345  ...  0.351130  0.170897  0.204832

[5 rows x 20 columns]
```

# generated/skfolio.datasets.load_sp500_index.html.md

<a id="skfolio-datasets-load-sp500-index"></a>

# skfolio.datasets.load_sp500_index

<a id="skfolio.datasets.load_sp500_index"></a>

### skfolio.datasets.load_sp500_index()

Load the prices of the S&P 500 Index.

This dataset contains daily adjusted closing prices of the S&P 500 Index, covering
the period from 1990-01-02 to 2022-12-28.

#### CAUTION
This dataset is provided solely for testing and example purposes. It is a stale
dataset and does not reflect current or accurate market prices. It is not
intended for investment, trading, or commercial use and should not be relied
upon as authoritative market data.

| Observations   |   8313 |
|----------------|--------|
| Assets         |      1 |
* **Returns:**
  **df** *DataFrame of shape (n_observations, n_assets)*
  : Prices DataFrame

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_index
>>> prices = load_sp500_index()
>>> prices.head()
             SP500
Date
1990-01-02  359.69
1990-01-03  358.76
1990-01-04  355.67
1990-01-05  352.20
1990-01-08  353.79
```

# generated/skfolio.datasets.make_synthetic_characteristics.html.md

<a id="skfolio-datasets-make-synthetic-characteristics"></a>

# skfolio.datasets.make_synthetic_characteristics

<a id="skfolio.datasets.make_synthetic_characteristics"></a>

### skfolio.datasets.make_synthetic_characteristics(n_assets=500, n_observations=2520, \*, n_industries=10, start_date='2015-01-01', systematic_variance_ratio=0.5, late_listing_proba=0.15, delisting_proba=0.15, missing_ratio=0.01, random_state=None)

Generate a synthetic characteristics [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel).

The panel generated contains the minimal set of fields required by the default
`skfolio` descriptors and [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel). It is
designed so that fitting a characteristics factor model produces realistic
diagnostics: a cross-sectional regression $R^2$ away from the degenerate
values of $0$ and $1$, non-trivial information coefficients and
idiosyncratic returns with fat tails.

Returns are drawn from a factor structure

$$
r_{i,t} = \beta_i\,f^{\mathrm{mkt}}_t + f^{\mathrm{ind}(i)}_t
          + \sum_k B_{i,k}\,f^{k}_t + \varepsilon_{i,t},
$$

where the per-asset loadings $B$ are persistent traits. Characteristics are
then constructed so that the descriptor of each style is a noisy proxy of the
corresponding loading, while accounting identities (for example
$\text{market\_cap} = \text{adj\_close} \times
\text{adj\_shares\_outstanding}$) are preserved.

Fields produced:
`returns`, `adj_close`, `adj_volume`, `adj_shares_outstanding`, `market_cap`,
`ebitda_ttm`, `enterprise_value`, `net_income_ttm`, `sales_ttm`, `dividends_ttm`,
`net_buybacks_ttm`, `book_equity`, `operating_cash_flow_ttm`, `total_debt`,
`total_assets`, `industry`, `cost_of_revenue_ttm`, `capex_ttm`, `short_interest`,
`eps_ntm`, `dps_ntm`, `eps_ntm_std`.

* **Parameters:**
  **n_assets** *int, default=500*
  : Number of assets (coverage universe).

  **n_observations** *int, default=2520*
  : Number of observations.

  **n_industries** *int, default=10*
  : Number of industry groups. Must not exceed 16.

  **start_date** *str, default=”2015-01-01”*
  : First observation date. Observations follow a business-day calendar.

  **systematic_variance_ratio** *float, default=0.5*
  : Share of cross-sectional return variance explained by the factor structure.
    The realized cross-sectional regression $R^2$ of a fitted model is close
    to this value. Must lie in the open interval $(0, 1)$.

  **late_listing_proba** *float, default=0.15*
  : Probability that an asset lists after the first observation.

  **delisting_proba** *float, default=0.15*
  : Probability that an asset delists before the last observation.

  **missing_ratio** *float, default=0.01*
  : Fraction of active fundamental observations set to NaN to emulate reporting
    gaps. Price, volume, shares and market cap are left intact.

  **random_state** *int, optional*
  : Seed for the random number generator.
* **Returns:**
  **panel** *AssetPanel*
  : Synthetic asset panel with the fields listed above. `industry` is a
    [`FieldCategorical`](https://skfolio.org/generated/skfolio.containers.FieldCategorical.html.md#skfolio.containers.FieldCategorical).

### Notes

The generator is driven by a small set of time-invariant latent asset traits
(size, value, quality, risk, growth and liquidity). These traits set the factor
loadings $B$, the market beta and the idiosyncratic volatility level and
anchor the level of every fundamental and market field so that accounting
identities (such as $\text{market\_cap} = \text{adj\_close} \times
\text{adj\_shares\_outstanding}$) hold. Each characteristic is therefore a noisy
proxy of the trait that drives its matching style factor.

Factor returns combine a fat-tailed market factor, zero-mean industry factors and
mean-reverting style factors. Idiosyncratic returns mix a transitory shock with a
slow persistent component and a fast mean-reverting component. These give the
momentum and short-term reversal factors a realistic positive Sharpe without
changing the idiosyncratic variance.

To support alpha-research examples, the idiosyncratic shock also contains a small
predictable component driven by a persistent latent bearish signal
$z_{i,t}$. Short interest and analyst forecast dispersion are constructed as
noisy increasing functions of $z_{i,t}$, while the next-period return
contribution is

$$
\varepsilon^{\mathrm{signal}}_{i,t+1}
= -\sigma_i\sqrt{w_{\mathrm{signal}}}\,z_{i,t}.
$$

Consequently, high values of either descriptor predict lower future
idiosyncratic returns without same-period look-ahead.

Forward-looking and lower-coverage fields (`eps_ntm`, `dps_ntm`, `eps_ntm_std`,
`enterprise_value`, `ebitda_ttm` and `cost_of_revenue_ttm`) carry partial coverage
to mirror real data, while price, volume, shares and market cap are always
populated on active assets.

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> panel = make_synthetic_characteristics(n_assets=200, n_observations=1000)
>>> panel.n_assets, panel.n_observations
(200, 1000)
```

# generated/skfolio.descriptor.AccrualsCashFlow.html.md

<a id="skfolio-descriptor-accrualscashflow"></a>

# skfolio.descriptor.AccrualsCashFlow

<a id="skfolio.descriptor.AccrualsCashFlow"></a>

### *class* skfolio.descriptor.AccrualsCashFlow

Cash-flow statement accruals descriptor.

Computes the non-cash component of earnings, scaled by total assets:

$$
\text{accruals\_cash\_flow}(t) =
\frac{\text{net\_income\_ttm}(t) - \text{operating\_cash\_flow\_ttm}(t)}
     {\text{total\_assets}(t)}
$$

High accruals indicate that reported earnings substantially exceed cash generated
from operations. Empirically, firms with high accruals tend to have less persistent
earnings and lower future returns, a pattern known as the accrual anomaly [[1]](https://skfolio.org/generated/skfolio.descriptor.AccrualsCashFlow.html.md#ra0753b7fd962-1).

This cash-flow statement version is preferred over the balance-sheet version because
it requires fewer line items and is less sensitive to data-provider mapping
differences. The balance-sheet version (which computes accruals from changes in
working capital items) can be pre-computed and fed via [`Passthrough`](https://skfolio.org/generated/skfolio.descriptor.Passthrough.html.md#skfolio.descriptor.Passthrough) if
needed.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.AccrualsCashFlow.html.md#skfolio.descriptor.AccrualsCashFlow.fit_transform)(X[, y])         | Compute accruals scaled by total assets.       |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.AccrualsCashFlow.html.md#skfolio.descriptor.AccrualsCashFlow.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.AccrualsCashFlow.html.md#skfolio.descriptor.AccrualsCashFlow.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.AccrualsCashFlow.html.md#skfolio.descriptor.AccrualsCashFlow.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.AccrualsCashFlow.html.md#skfolio.descriptor.AccrualsCashFlow.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`ReturnOnAssets`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets)
: Net income-based profitability per unit of assets.

[`CashFlowToAssets`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToAssets.html.md#skfolio.descriptor.CashFlowToAssets)
: Cash flow-based profitability per unit of assets.

### Notes

The sign convention follows the academic literature: a positive value means earnings
exceed cash flow (high accruals, lower quality), while a negative value means cash
flow exceeds earnings (low accruals, higher quality).

### References

* <a id='ra0753b7fd962-1'>**[1]**</a> “Do stock prices fully reflect information in accruals and cash flows about future earnings?” The Accounting Review. Sloan, R. G. (1996).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import AccrualsCashFlow
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = AccrualsCashFlow()
>>> accruals_cash_flow = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.AccrualsCashFlow.fit_transform"></a>

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

Compute accruals scaled by total assets.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `net_income_ttm`, `operating_cash_flow_ttm`, and
    `total_assets`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **accruals_cash_flow** *ndarray of shape (n_observations, n_assets)*
  : Accruals (net income minus operating cash flow) divided by total assets
    for each observation and asset.

<a id="skfolio.descriptor.AccrualsCashFlow.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.descriptor.AccrualsCashFlow.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.descriptor.AccrualsCashFlow.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.AccrualsCashFlow.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.

# generated/skfolio.descriptor.AnalystDispersionToPrice.html.md

<a id="skfolio-descriptor-analystdispersiontoprice"></a>

# skfolio.descriptor.AnalystDispersionToPrice

<a id="skfolio.descriptor.AnalystDispersionToPrice"></a>

### *class* skfolio.descriptor.AnalystDispersionToPrice

Analyst forecast dispersion to price descriptor.

Computes the ratio of analyst earnings forecast dispersion to the split-adjusted
close price:

$$
\text{analyst\_dispersion\_to\_price}(t) =
\frac{\text{eps\_ntm\_std}(t)}{\text{adj\_close}(t)}
$$

Higher values indicate greater disagreement among analysts about a firm’s forward
earnings relative to its price. Forecast dispersion is a proxy for earnings
uncertainty and information asymmetry. Empirically, stocks with high analyst
disagreement tend to be overpriced and earn lower future returns [[1]](https://skfolio.org/generated/skfolio.descriptor.AnalystDispersionToPrice.html.md#r85cdca767597-1).

This descriptor uses per-share quantities (standard deviation of per-share EPS
forecasts divided by split-adjusted price) because analyst consensus data is
natively reported on a per-share basis.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.AnalystDispersionToPrice.html.md#skfolio.descriptor.AnalystDispersionToPrice.fit_transform)(X[, y])         | Compute analyst earnings dispersion relative to price.   |
|--------------------------------------------------------------------------------|----------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.AnalystDispersionToPrice.html.md#skfolio.descriptor.AnalystDispersionToPrice.get_metadata_routing)()        | Get metadata routing of this object.                     |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.AnalystDispersionToPrice.html.md#skfolio.descriptor.AnalystDispersionToPrice.get_params)([deep])            | Get parameters for this estimator.                       |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.AnalystDispersionToPrice.html.md#skfolio.descriptor.AnalystDispersionToPrice.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`.           |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.AnalystDispersionToPrice.html.md#skfolio.descriptor.AnalystDispersionToPrice.set_params)(\*\*params)        | Set the parameters of this estimator.                    |

#### SEE ALSO
[`ForwardEarningsToPrice`](https://skfolio.org/generated/skfolio.descriptor.ForwardEarningsToPrice.html.md#skfolio.descriptor.ForwardEarningsToPrice)
: Level of forward earnings to price.

### Notes

`eps_ntm_std` is the cross-analyst standard deviation of NTM EPS estimates,
typically provided by consensus data vendors. It should use the same
split-adjustment basis as `adj_close`.

### References

* <a id='r85cdca767597-1'>**[1]**</a> “Differences of opinion and the cross section of stock returns” The Journal of Finance. Diether, K. B., Malloy, C. J., & Scherbina, A. (2002).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import AnalystDispersionToPrice
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = AnalystDispersionToPrice()
>>> analyst_dispersion_to_price = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.AnalystDispersionToPrice.fit_transform"></a>

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

Compute analyst earnings dispersion relative to price.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `eps_ntm_std` and `adj_close`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **analyst_dispersion_to_price** *ndarray of shape (n_observations, n_assets)*
  : Standard deviation of forward EPS estimates divided by split-adjusted close
    for each observation and asset.

<a id="skfolio.descriptor.AnalystDispersionToPrice.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.descriptor.AnalystDispersionToPrice.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.descriptor.AnalystDispersionToPrice.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.AnalystDispersionToPrice.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.

# generated/skfolio.descriptor.AssetTurnover.html.md

<a id="skfolio-descriptor-assetturnover"></a>

# skfolio.descriptor.AssetTurnover

<a id="skfolio.descriptor.AssetTurnover"></a>

### *class* skfolio.descriptor.AssetTurnover

Asset turnover descriptor.

Computes the ratio of trailing twelve-month sales to total assets:

$$
\text{asset\_turnover}(t) = \frac{\text{sales\_ttm}(t)}{\text{total\_assets}(t)}
$$

Asset turnover measures how efficiently a firm uses its assets to generate revenue [[1]](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#r668f3a3ef6fc-1).
Higher values indicate greater capital efficiency.

Asset-light business models tend to have high turnover, while capital-intensive
industries tend to have low turnover.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#skfolio.descriptor.AssetTurnover.fit_transform)(X[, y])         | Compute asset turnover.                        |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#skfolio.descriptor.AssetTurnover.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#skfolio.descriptor.AssetTurnover.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#skfolio.descriptor.AssetTurnover.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#skfolio.descriptor.AssetTurnover.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`ReturnOnAssets`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets)
: $ROA$, which decomposes into margin and turnover.

### References

* <a id='r668f3a3ef6fc-1'>**[1]**</a> “Using asset turnover and profit margin to forecast changes in profitability” Review of Accounting Studies. Fairfield, P. M., & Yohn, T. L. (2001).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import AssetTurnover
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = AssetTurnover()
>>> asset_turnover = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.AssetTurnover.fit_transform"></a>

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

Compute asset turnover.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `sales_ttm` and `total_assets`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **asset_turnover** *ndarray of shape (n_observations, n_assets)*
  : Sales divided by total assets for each observation and asset.

<a id="skfolio.descriptor.AssetTurnover.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.descriptor.AssetTurnover.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.descriptor.AssetTurnover.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.AssetTurnover.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.

# generated/skfolio.descriptor.AssetsGrowthRate.html.md

<a id="skfolio-descriptor-assetsgrowthrate"></a>

# skfolio.descriptor.AssetsGrowthRate

<a id="skfolio.descriptor.AssetsGrowthRate"></a>

### *class* skfolio.descriptor.AssetsGrowthRate(lag=252)

Asset growth rate descriptor.

Computes period-over-period growth in total assets:

$$
\text{assets\_growth}(t)
= \frac{\text{total\_assets}(t)}
       {\text{total\_assets}(t - \text{lag})} - 1
$$

The first `lag` observations are NaN because no lagged history is available.

`total_assets` must contain non-missing finite non-negative values. NaNs are
allowed as missing observations and propagate when either the current or lagged
value is missing. Zero values are allowed and a zero lagged value makes the growth
rate undefined and produces NaN.

Asset growth is commonly used as an investment or balance-sheet expansion signal.
Firms with rapid asset growth tend to earn lower future returns [[1]](https://skfolio.org/generated/skfolio.descriptor.AssetsGrowthRate.html.md#r8145a2769a60-1).

This is a convenience subclass of [`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate) with `field="total_assets"`.

* **Parameters:**
  **lag** *int, default=252*
  : Number of observations to look back. The interpretation depends on the data
    frequency: `lag=12` means 1 year for monthly data, `lag=252` for daily data,
    `lag=4` for quarterly data.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **growth_rate_** *ndarray of shape (n_assets,)*
  : Last asset growth value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.AssetsGrowthRate.html.md#skfolio.descriptor.AssetsGrowthRate.fit_transform)(X[, y])         | Compute simple growth rates of the configured field.   |
|--------------------------------------------------------------------------------|--------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.AssetsGrowthRate.html.md#skfolio.descriptor.AssetsGrowthRate.get_metadata_routing)()        | Get metadata routing of this object.                   |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.AssetsGrowthRate.html.md#skfolio.descriptor.AssetsGrowthRate.get_params)([deep])            | Get parameters for this estimator.                     |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.AssetsGrowthRate.html.md#skfolio.descriptor.AssetsGrowthRate.partial_fit_transform)(X[, y]) | Compute simple growth rates of the configured field.   |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.AssetsGrowthRate.html.md#skfolio.descriptor.AssetsGrowthRate.set_params)(\*\*params)        | Set the parameters of this estimator.                  |

#### SEE ALSO
[`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate)
: Generic period-over-period growth rate descriptor.

### References

* <a id='r8145a2769a60-1'>**[1]**</a> “Asset growth and the cross-section of stock returns” The Journal of Finance. Cooper, M. J., Gulen, H., & Schill, M. J. (2008).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import AssetsGrowthRate
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = AssetsGrowthRate(lag=252)
>>> assets_growth_rate = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.AssetsGrowthRate.fit_transform"></a>

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

Compute simple growth rates of the configured field.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` characteristic configured at
    construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **growth_rate** *ndarray of shape (n_observations, n_assets)*
  : Period-over-period growth rate for each observation and asset.

<a id="skfolio.descriptor.AssetsGrowthRate.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.descriptor.AssetsGrowthRate.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.descriptor.AssetsGrowthRate.partial_fit_transform"></a>

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

Compute simple growth rates of the configured field.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` characteristic configured at construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **growth_rate** *ndarray of shape (n_observations, n_assets)*
  : Period-over-period growth rate for each observation and asset.

<a id="skfolio.descriptor.AssetsGrowthRate.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.

# generated/skfolio.descriptor.BaseDescriptor.html.md

<a id="skfolio-descriptor-basedescriptor"></a>

# skfolio.descriptor.BaseDescriptor

<a id="skfolio.descriptor.BaseDescriptor"></a>

### *class* skfolio.descriptor.BaseDescriptor

Base class for all descriptor transformers.

A descriptor takes an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) and returns one raw
descriptor value per observation and asset, usually with shape
`(n_observations, n_assets)`. Descriptors are the inputs used by factor exposure
estimators such as [`FixedWeightedFactor`](https://skfolio.org/generated/skfolio.factor_exposure.FixedWeightedFactor.html.md#skfolio.factor_exposure.FixedWeightedFactor).

Descriptors follow the [`BaseAssetPanelTransformer`](https://skfolio.org/generated/skfolio.base.BaseAssetPanelTransformer.html.md#skfolio.base.BaseAssetPanelTransformer)
protocol:

- Batch-only descriptors implement only `fit_transform`.
- Stateless descriptors declare `stateless=True` and implement only
  `fit_transform`. The base class adds `partial_fit_transform` by
  delegating to `fit_transform`.
- Online descriptors implement both `fit_transform` and
  `partial_fit_transform`. `fit_transform` starts from a clean state;
  `partial_fit_transform` continues from the current state.

Examples include direct field access ([`Passthrough`](https://skfolio.org/generated/skfolio.descriptor.Passthrough.html.md#skfolio.descriptor.Passthrough)), point-in-time
ratios ([`BookToPrice`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice)), and history-dependent descriptors
([`EWMomentum`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum)).

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.BaseDescriptor.html.md#skfolio.descriptor.BaseDescriptor.fit_transform)(X[, y])   | Fit the transformer if needed and return transformed values.   |
|--------------------------------------------------------------------------|----------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.BaseDescriptor.html.md#skfolio.descriptor.BaseDescriptor.get_metadata_routing)()  | Get metadata routing of this object.                           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.BaseDescriptor.html.md#skfolio.descriptor.BaseDescriptor.get_params)([deep])      | Get parameters for this estimator.                             |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.BaseDescriptor.html.md#skfolio.descriptor.BaseDescriptor.set_params)(\*\*params)  | Set the parameters of this estimator.                          |

#### SEE ALSO
[`BaseAssetPanelTransformer`](https://skfolio.org/generated/skfolio.base.BaseAssetPanelTransformer.html.md#skfolio.base.BaseAssetPanelTransformer)
: Shared transformer contract.

[`BaseFactorExposure`](https://skfolio.org/generated/skfolio.factor_exposure.BaseFactorExposure.html.md#skfolio.factor_exposure.BaseFactorExposure)
: Combines descriptors into factor exposures.

<a id="skfolio.descriptor.BaseDescriptor.fit_transform"></a>

#### *abstractmethod* fit_transform(X, y=None, \*\*fit_params)

Fit the transformer if needed and return transformed values.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel data.

  **y** *None*
  : Ignored. Present for API consistency.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Metadata routing may pass these parameters to
    sub-estimators when applicable.
* **Returns:**
  **values** *ndarray of shape (n_observations, n_assets) or (n_observations, n_assets, n_components)*
  : Transformed values.

<a id="skfolio.descriptor.BaseDescriptor.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.descriptor.BaseDescriptor.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.descriptor.BaseDescriptor.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.

# generated/skfolio.descriptor.BookLeverage.html.md

<a id="skfolio-descriptor-bookleverage"></a>

# skfolio.descriptor.BookLeverage

<a id="skfolio.descriptor.BookLeverage"></a>

### *class* skfolio.descriptor.BookLeverage

Book leverage descriptor.

Computes the proportion of total book capital financed by debt:

$$
\text{book\_leverage}(t) =
\frac{\text{total\_debt}(t)}
     {\text{total\_debt}(t) + \text{book\_equity}(t)}
$$

Book leverage measures financial risk through the lens of the capital structure: the
fraction of a firm’s total invested capital (debt plus common equity) that comes
from creditors rather than common shareholders [[1]](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#r302fa65a63b9-1).

NaNs are allowed as missing observations and propagate to the output.
Non-missing `total_debt` and `book_equity` values must be finite.

This form is preferred over the debt-to-equity ratio ($D / E$) because the two
are monotonically related ($D / E = \text{book\_leverage} / (1 - \text{book\_leverage})$)
but book leverage is bounded in $[0, 1]$ for healthy firms, producing
well-behaved cross-sectional distributions that do not require aggressive
winsorization.

`book_equity` is common shareholders’ equity (excluding preferred stock and
minority interest). When it is negative (e.g., firms with accumulated losses
exceeding paid-in capital), the denominator `total_debt + book_equity` may remain
positive, become zero or turn negative:

- **Denominator > 0 and book_equity < 0**: the ratio exceeds 1. The firm is extremely
  leveraged, with debt exceeding total book capital. The value is a valid distress
  signal and is preserved in the output.
- **Denominator <= 0**: the ratio is undefined or negative, and no longer has its
  intended interpretation as a measure of book leverage. These observations are
  masked to NaN.

This differs from [`ReturnOnEquity`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnEquity.html.md#skfolio.descriptor.ReturnOnEquity), where any negative equity makes the
concept meaningless. Here, a ratio above 1 carries real information about financial
risk.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#skfolio.descriptor.BookLeverage.fit_transform)(X[, y])         | Compute book leverage ratios.                  |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#skfolio.descriptor.BookLeverage.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#skfolio.descriptor.BookLeverage.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#skfolio.descriptor.BookLeverage.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#skfolio.descriptor.BookLeverage.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`DebtToAssets`](https://skfolio.org/generated/skfolio.descriptor.DebtToAssets.html.md#skfolio.descriptor.DebtToAssets)
: Leverage relative to total assets.

[`MarketLeverage`](https://skfolio.org/generated/skfolio.descriptor.MarketLeverage.html.md#skfolio.descriptor.MarketLeverage)
: Leverage as a fraction of total market capital.

### References

* <a id='r302fa65a63b9-1'>**[1]**</a> “Capital structure decisions: which factors are reliably important?” Financial Management. Frank, M. Z., & Goyal, V. K. (2009).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import BookLeverage
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = BookLeverage()
>>> book_leverage = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.BookLeverage.fit_transform"></a>

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

Compute book leverage ratios.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `total_debt` and `book_equity`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **book_leverage** *ndarray of shape (n_observations, n_assets)*
  : Book leverage ratio for each observation and asset.

<a id="skfolio.descriptor.BookLeverage.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.descriptor.BookLeverage.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.descriptor.BookLeverage.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.BookLeverage.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.

# generated/skfolio.descriptor.BookToPrice.html.md

<a id="skfolio-descriptor-booktoprice"></a>

# skfolio.descriptor.BookToPrice

<a id="skfolio.descriptor.BookToPrice"></a>

### *class* skfolio.descriptor.BookToPrice

Book-to-price ratio descriptor.

Computes the ratio of common shareholders’ equity (book equity) to market
capitalization:

$$
\text{book\_to\_price}(t) = \frac{\text{book\_equity}(t)}{\text{market\_cap}(t)}
$$

A high book-to-price ratio identifies stocks trading at a discount relative to their
common equity. Historically, cheap stocks (those with high book-to-price ratios) have
earned higher average returns than expensive stocks (those with low book-to-price
ratios) [[1]](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#rc230015dfaf5-1).

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice.fit_transform)(X[, y])         | Compute book to price.                         |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`SalesToPrice`](https://skfolio.org/generated/skfolio.descriptor.SalesToPrice.html.md#skfolio.descriptor.SalesToPrice)
: Sales normalized by market capitalization.

[`CashFlowToPrice`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#skfolio.descriptor.CashFlowToPrice)
: Operating cash flow normalized by market capitalization.

### Notes

Non-missing `market_cap` values must be finite and strictly positive. Negative
`book_equity` values are preserved because they carry information about the firm’s
balance sheet.

This descriptor uses aggregate quantities (common equity divided by total market
capitalization) rather than per-share quantities (book value per share divided by
price). The two are mathematically equivalent:

$$
\frac{\text{book\_equity}}{\text{price} \times \text{shares\_out}}
= \frac{\text{book\_value\_per\_share}}{\text{price}}
$$

The aggregate form is preferred because it avoids subtle split-adjustment mismatches
between numerator and denominator. Aggregate fundamentals are the primary form from
data providers; per-share quantities are derived from them.

### References

* <a id='rc230015dfaf5-1'>**[1]**</a> “The cross-section of expected stock returns” The Journal of Finance. Fama, E. F., & French, K. R. (1992).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import BookToPrice
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = BookToPrice()
>>> book_to_price = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.BookToPrice.fit_transform"></a>

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

Compute book to price.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `book_equity` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **book_to_price** *ndarray of shape (n_observations, n_assets)*
  : Book-to-price ratio for each observation and asset.

<a id="skfolio.descriptor.BookToPrice.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.descriptor.BookToPrice.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.descriptor.BookToPrice.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.BookToPrice.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.

# generated/skfolio.descriptor.CapexToAssetsChangeInIntensity.html.md

<a id="skfolio-descriptor-capextoassetschangeinintensity"></a>

# skfolio.descriptor.CapexToAssetsChangeInIntensity

<a id="skfolio.descriptor.CapexToAssetsChangeInIntensity"></a>

### *class* skfolio.descriptor.CapexToAssetsChangeInIntensity(lag=252)

Lagged change in capex-to-assets intensity.

Computes the change in the capex-to-assets ratio over a fixed lag:

$$
\text{capex\_to\_assets\_change\_in\_intensity}(t)
= \frac{\text{capex\_ttm}(t)}{\text{total\_assets}(t)}
- \frac{\text{capex\_ttm}(t - \text{lag})}
       {\text{total\_assets}(t - \text{lag})}
$$

The first `lag` observations are NaN because no lagged history is available.

NaNs are allowed as missing observations and propagate when the current, lagged or
scale value is missing. Non-missing `capex_ttm` values must be finite.
Non-missing `total_assets` values must be finite and strictly positive.

A positive value indicates that capex intensity increased relative to total assets
and a negative value indicates that it decreased.

This is a convenience subclass of [`ChangeInIntensity`](https://skfolio.org/generated/skfolio.descriptor.ChangeInIntensity.html.md#skfolio.descriptor.ChangeInIntensity) with
`field="capex_ttm"` and `scale_field="total_assets"`.

* **Parameters:**
  **lag** *int, default=252*
  : Number of observations to look back. The interpretation depends on the data
    frequency: `lag=12` means 1 year for monthly data, `lag=252` for daily data,
    `lag=4` for quarterly data.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **change_in_intensity_** *ndarray of shape (n_assets,)*
  : Last capex-to-assets intensity change for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.CapexToAssetsChangeInIntensity.html.md#skfolio.descriptor.CapexToAssetsChangeInIntensity.fit_transform)(X[, y])         | Compute changes in the intensity ratio over the configured lag.   |
|--------------------------------------------------------------------------------|-------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.CapexToAssetsChangeInIntensity.html.md#skfolio.descriptor.CapexToAssetsChangeInIntensity.get_metadata_routing)()        | Get metadata routing of this object.                              |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.CapexToAssetsChangeInIntensity.html.md#skfolio.descriptor.CapexToAssetsChangeInIntensity.get_params)([deep])            | Get parameters for this estimator.                                |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.CapexToAssetsChangeInIntensity.html.md#skfolio.descriptor.CapexToAssetsChangeInIntensity.partial_fit_transform)(X[, y]) | Compute changes in the intensity ratio over the configured lag.   |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.CapexToAssetsChangeInIntensity.html.md#skfolio.descriptor.CapexToAssetsChangeInIntensity.set_params)(\*\*params)        | Set the parameters of this estimator.                             |

#### SEE ALSO
[`ChangeInIntensity`](https://skfolio.org/generated/skfolio.descriptor.ChangeInIntensity.html.md#skfolio.descriptor.ChangeInIntensity)
: Generic field-to-scale intensity change descriptor.

[`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate)
: Period-over-period growth rate for non-negative fields.

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import CapexToAssetsChangeInIntensity
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = CapexToAssetsChangeInIntensity(lag=252)
>>> capex_intensity_change = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.CapexToAssetsChangeInIntensity.fit_transform"></a>

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

Compute changes in the intensity ratio over the configured lag.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` and `scale_field` characteristics
    configured at construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **change_in_intensity** *ndarray of shape (n_observations, n_assets)*
  : Change in `field` / `scale_field` over the lag window for each observation
    and asset.

<a id="skfolio.descriptor.CapexToAssetsChangeInIntensity.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.descriptor.CapexToAssetsChangeInIntensity.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.descriptor.CapexToAssetsChangeInIntensity.partial_fit_transform"></a>

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

Compute changes in the intensity ratio over the configured lag.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` and `scale_field` fields configured at
    construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **change_in_intensity** *ndarray of shape (n_observations, n_assets)*
  : Change in `field` / `scale_field` over the lag window for each observation
    and asset.

<a id="skfolio.descriptor.CapexToAssetsChangeInIntensity.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.

# generated/skfolio.descriptor.CashFlowToAssets.html.md

<a id="skfolio-descriptor-cashflowtoassets"></a>

# skfolio.descriptor.CashFlowToAssets

<a id="skfolio.descriptor.CashFlowToAssets"></a>

### *class* skfolio.descriptor.CashFlowToAssets

Cash flow to assets descriptor.

Computes the ratio of trailing twelve-month operating cash flow to total assets:

$$
\text{cash\_flow\_to\_assets}(t) =
\frac{\text{operating\_cash\_flow\_ttm}(t)}{\text{total\_assets}(t)}
$$

Cash flow to assets measures cash-based profitability: how much cash a firm
generates from operations per unit of assets. Unlike net income-based measures
([`ReturnOnAssets`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets)), operating cash flow is less directly affected by accrual
accounting choices [[1]](https://skfolio.org/generated/skfolio.descriptor.CashFlowToAssets.html.md#r7f640f8aad96-1)..

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToAssets.html.md#skfolio.descriptor.CashFlowToAssets.fit_transform)(X[, y])         | Compute cash flow to assets.                   |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToAssets.html.md#skfolio.descriptor.CashFlowToAssets.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToAssets.html.md#skfolio.descriptor.CashFlowToAssets.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToAssets.html.md#skfolio.descriptor.CashFlowToAssets.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToAssets.html.md#skfolio.descriptor.CashFlowToAssets.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`ReturnOnAssets`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets)
: Net income-based profitability per unit of assets.

[`CashFlowToPrice`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#skfolio.descriptor.CashFlowToPrice)
: Cash flow normalized by market cap (value signal).

### Notes

Operating cash flow can be negative, so this descriptor can take negative
values.

### References

* <a id='r7f640f8aad96-1'>**[1]**</a> “Accruals, cash flows, and operating profitability in the cross section of stock returns” Journal of Financial Economics. Ball, Gerakos, Linnainmaa & Nikolaev (2016).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import CashFlowToAssets
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = CashFlowToAssets()
>>> cash_flow_to_assets = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.CashFlowToAssets.fit_transform"></a>

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

Compute cash flow to assets.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `operating_cash_flow_ttm` and `total_assets`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **cash_flow_to_assets** *ndarray of shape (n_observations, n_assets)*
  : Operating cash flow divided by total assets for each observation and asset.

<a id="skfolio.descriptor.CashFlowToAssets.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.descriptor.CashFlowToAssets.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.descriptor.CashFlowToAssets.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.CashFlowToAssets.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.

# generated/skfolio.descriptor.CashFlowToPrice.html.md

<a id="skfolio-descriptor-cashflowtoprice"></a>

# skfolio.descriptor.CashFlowToPrice

<a id="skfolio.descriptor.CashFlowToPrice"></a>

### *class* skfolio.descriptor.CashFlowToPrice

Cash-flow-to-price ratio descriptor.

Computes the ratio of trailing twelve-month operating cash flow to market
capitalization:

$$
\text{cash\_flow\_to\_price}(t) =
\frac{\text{operating\_cash\_flow\_ttm}(t)}{\text{market\_cap}(t)}
$$

Operating cash flow measures cash generated by a firm’s core business after
working-capital adjustments. A high ratio identifies firms generating substantial
cash relative to their market capitalization, providing a value signal that is less
directly affected by accrual accounting choices than earnings-based measures [[1]](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#r4a1ae64121b5-1).

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#skfolio.descriptor.CashFlowToPrice.fit_transform)(X[, y])         | Compute cash flow to price.                    |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#skfolio.descriptor.CashFlowToPrice.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#skfolio.descriptor.CashFlowToPrice.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#skfolio.descriptor.CashFlowToPrice.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#skfolio.descriptor.CashFlowToPrice.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`CashFlowToAssets`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToAssets.html.md#skfolio.descriptor.CashFlowToAssets)
: Operating cash flow normalized by total assets.

[`BookToPrice`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice)
: Common equity normalized by market capitalization.

### Notes

Non-missing `market_cap` values must be finite and strictly positive. Operating
cash flow can be negative, so this descriptor can take negative values.

This descriptor uses aggregate quantities (total operating cash flow divided by
total market capitalization) rather than per-share quantities (cash flow per share
divided by price). The two are mathematically equivalent:

$$
\frac{\text{operating\_cash\_flow\_ttm}}{\text{market\_cap}}
= \frac{\text{cash\_flow\_per\_share}}{\text{price}}
$$

The aggregate form is preferred because it avoids subtle split-adjustment mismatches
between numerator and denominator. Aggregate fundamentals are the primary form from
data providers; per-share quantities are derived from them.

### References

* <a id='r4a1ae64121b5-1'>**[1]**</a> “Contrarian investment, extrapolation, and risk” The Journal of Finance. Lakonishok, J., Shleifer, A., & Vishny, R. W. (1994).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import CashFlowToPrice
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = CashFlowToPrice()
>>> cash_flow_to_price = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.CashFlowToPrice.fit_transform"></a>

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

Compute cash flow to price.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `operating_cash_flow_ttm` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **cash_flow_to_price** *ndarray of shape (n_observations, n_assets)*
  : Cash-flow-to-price ratio for each observation and asset.

<a id="skfolio.descriptor.CashFlowToPrice.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.descriptor.CashFlowToPrice.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.descriptor.CashFlowToPrice.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.CashFlowToPrice.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.

# generated/skfolio.descriptor.ChangeInIntensity.html.md

<a id="skfolio-descriptor-changeinintensity"></a>

# skfolio.descriptor.ChangeInIntensity

<a id="skfolio.descriptor.ChangeInIntensity"></a>

### *class* skfolio.descriptor.ChangeInIntensity(field, scale_field, lag)

Lagged change in a field-to-scale ratio.

Computes the change in the ratio $A/S$ over a fixed lag:

$$
\text{ChangeInIntensity}_\ell(t)
= \frac{A(t)}{S(t)} - \frac{A(t - \ell)}{S(t - \ell)}
$$

where $A$ is the `field` value and $S$ is the `scale_field` value.

The first `lag` observations are NaN because no lagged history is available.

This descriptor is appropriate when the economic concept of interest is the ratio
itself, such as capex/assets, R&D/sales or a margin, and whether that ratio improved
or deteriorated over the lag window. NaNs are allowed as missing observations and
propagate when the current, lagged or scale value is missing.

Non-missing numerator values must be finite. Non-missing scale values must be finite
and strictly positive. A `ValueError` is raised otherwise.

* **Parameters:**
  **field** *str*
  : Field name in the [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) used as numerator
    $A$. Non-missing values must be finite.

  **scale_field** *str*
  : Field name in the [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) used as denominator
    $S$. Non-missing values must be finite and strictly positive.

  **lag** *int*
  : Number of observations to look back. The interpretation depends on the data
    frequency: `lag=12` means 1 year for monthly data, `lag=252` for daily data,
    `lag=4` for quarterly data.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **change_in_intensity_** *ndarray of shape (n_assets,)*
  : Last change-in-intensity value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ChangeInIntensity.html.md#skfolio.descriptor.ChangeInIntensity.fit_transform)(X[, y])         | Compute changes in the intensity ratio over the configured lag.   |
|--------------------------------------------------------------------------------|-------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.ChangeInIntensity.html.md#skfolio.descriptor.ChangeInIntensity.get_metadata_routing)()        | Get metadata routing of this object.                              |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.ChangeInIntensity.html.md#skfolio.descriptor.ChangeInIntensity.get_params)([deep])            | Get parameters for this estimator.                                |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ChangeInIntensity.html.md#skfolio.descriptor.ChangeInIntensity.partial_fit_transform)(X[, y]) | Compute changes in the intensity ratio over the configured lag.   |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.ChangeInIntensity.html.md#skfolio.descriptor.ChangeInIntensity.set_params)(\*\*params)        | Set the parameters of this estimator.                             |

#### SEE ALSO
[`ChangeToScale`](https://skfolio.org/generated/skfolio.descriptor.ChangeToScale.html.md#skfolio.descriptor.ChangeToScale)
: Change in $A$ normalized by current $S$.

[`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate)
: Simple growth rate for positive-definite characteristics.

### Examples

```pycon
>>> from skfolio.descriptor import ChangeInIntensity
>>>
>>> # Capex intensity change (capex / total_assets)
>>> capex_int = ChangeInIntensity("capex_ttm", "total_assets", lag=12)
>>>
>>> # R&D intensity change (R&D / sales)
>>> rd_int = ChangeInIntensity("rd_ttm", "sales_ttm", lag=12)
```

<a id="skfolio.descriptor.ChangeInIntensity.fit_transform"></a>

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

Compute changes in the intensity ratio over the configured lag.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` and `scale_field` characteristics
    configured at construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **change_in_intensity** *ndarray of shape (n_observations, n_assets)*
  : Change in `field` / `scale_field` over the lag window for each observation
    and asset.

<a id="skfolio.descriptor.ChangeInIntensity.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.descriptor.ChangeInIntensity.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.descriptor.ChangeInIntensity.partial_fit_transform"></a>

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

Compute changes in the intensity ratio over the configured lag.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` and `scale_field` fields configured at
    construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **change_in_intensity** *ndarray of shape (n_observations, n_assets)*
  : Change in `field` / `scale_field` over the lag window for each observation
    and asset.

<a id="skfolio.descriptor.ChangeInIntensity.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.

# generated/skfolio.descriptor.ChangeToScale.html.md

<a id="skfolio-descriptor-changetoscale"></a>

# skfolio.descriptor.ChangeToScale

<a id="skfolio.descriptor.ChangeToScale"></a>

### *class* skfolio.descriptor.ChangeToScale(field, scale_field, lag)

Lagged change normalized by a positive scale.

Computes the change in `field` over a fixed lag, divided by the current value of
`scale_field`:

$$
\text{ChangeToScale}_\ell(t) = \frac{A(t) - A(t - \ell)}{S(t)}
$$

where $A$ is the `field` value and $S$ is the `scale_field` value.

The first `lag` observations are NaN because no lagged history is available.

This descriptor is appropriate when the numerator field can be negative or cross
zero, such as earnings, capex or cash flows, and the change should be scaled by the
firm’s current size or valuation. NaNs are allowed as missing observations and
propagate when the current, lagged or scale value is missing.

Non-missing numerator values must be finite. Non-missing scale values must be finite
and strictly positive. A `ValueError` is raised otherwise.

* **Parameters:**
  **field** *str*
  : Field name in the [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) to compute the
    change for. Non-missing values must be finite.

  **scale_field** *str*
  : Field name in the [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) used as the current
    positive denominator. Non-missing values must be finite and strictly positive.

  **lag** *int*
  : Number of observations to look back. The interpretation depends on the data
    frequency: `lag=12` means 1 year for monthly data, `lag=252` for daily data,
    `lag=4` for quarterly data.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **change_to_scale_** *ndarray of shape (n_assets,)*
  : Last change-to-scale value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ChangeToScale.html.md#skfolio.descriptor.ChangeToScale.fit_transform)(X[, y])         | Compute changes in level normalized by current scale.   |
|--------------------------------------------------------------------------------|---------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.ChangeToScale.html.md#skfolio.descriptor.ChangeToScale.get_metadata_routing)()        | Get metadata routing of this object.                    |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.ChangeToScale.html.md#skfolio.descriptor.ChangeToScale.get_params)([deep])            | Get parameters for this estimator.                      |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ChangeToScale.html.md#skfolio.descriptor.ChangeToScale.partial_fit_transform)(X[, y]) | Compute changes in level normalized by current scale.   |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.ChangeToScale.html.md#skfolio.descriptor.ChangeToScale.set_params)(\*\*params)        | Set the parameters of this estimator.                   |

#### SEE ALSO
[`ChangeInIntensity`](https://skfolio.org/generated/skfolio.descriptor.ChangeInIntensity.html.md#skfolio.descriptor.ChangeInIntensity)
: Change in the ratio $A/S$ (intensity change).

[`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate)
: Simple growth rate for positive-definite characteristics.

### Examples

```pycon
>>> from skfolio.descriptor import ChangeToScale
>>>
>>> # Earnings change to price (equivalent to EarningsChangeToPrice)
>>> earnings_chg = ChangeToScale("net_income_ttm", "market_cap", lag=12)
>>>
>>> # Capex change to total assets
>>> capex_chg = ChangeToScale("capex_ttm", "total_assets", lag=12)
```

<a id="skfolio.descriptor.ChangeToScale.fit_transform"></a>

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

Compute changes in level normalized by current scale.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` and `scale_field` characteristics
    configured at construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **change_to_scale** *ndarray of shape (n_observations, n_assets)*
  : Change in `field` over the lag window, divided by current `scale_field`
    for each observation and asset.

<a id="skfolio.descriptor.ChangeToScale.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.descriptor.ChangeToScale.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.descriptor.ChangeToScale.partial_fit_transform"></a>

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

Compute changes in level normalized by current scale.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` and `scale_field` fields configured at
    construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **change_to_scale** *ndarray of shape (n_observations, n_assets)*
  : Change in `field` over the lag window, divided by current `scale_field`
    for each observation and asset.

<a id="skfolio.descriptor.ChangeToScale.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.

# generated/skfolio.descriptor.DaysToCover.html.md

<a id="skfolio-descriptor-daystocover"></a>

# skfolio.descriptor.DaysToCover

<a id="skfolio.descriptor.DaysToCover"></a>

### *class* skfolio.descriptor.DaysToCover(half_life=21.0, min_periods=None)

Exponentially weighted days-to-cover descriptor.

Computes the ratio of shares sold short to exponentially weighted average daily
volume:

$$
\[
\begin{aligned}
\text{EWMA\_volume}(t)
    &= \lambda \cdot \text{EWMA\_volume}(t-1)
       + (1 - \lambda) \cdot \text{adj\_volume}(t) \\[0.75em]
\text{days\_to\_cover}(t)
    &= \frac{\text{short\_interest}(t)}{\text{EWMA\_volume}(t)}
\end{aligned}
\]
$$

where $\lambda = \exp(-\ln(2) / \text{half\_life})$ is the EWMA decay factor.

Days to cover measures how many trading days it would take short sellers to buy back
their positions at the current trading rate. High values indicate crowded short
positions relative to liquidity [[1]](https://skfolio.org/generated/skfolio.descriptor.DaysToCover.html.md#rba227fd45f66-1) [[2]](https://skfolio.org/generated/skfolio.descriptor.DaysToCover.html.md#rba227fd45f66-2).

EWMA smoothing is preferred over a fixed rolling average because daily volume can
spike around earnings, index rebalances or news events. EWMA dampens these spikes
gradually, producing more stable factor exposures.

* **Parameters:**
  **half_life** *float, default=21.0*
  : EWMA half-life in observations for volume smoothing. With daily data, common
    choices are:
    - `half_life=21`: ~1 month
    - `half_life=63`: ~3 months
    - `half_life=252`: ~1 year

  **min_periods** *int, optional*
  : Minimum number of valid positive-volume observations required for each asset.
    Until an asset reaches this count, its output is NaN. This warm-up period avoids
    exposing early EWMA values before the volume estimate has sufficiently converged
    from its zero initialization. If `None`, defaults to
    $\lceil\text{half\_life}\rceil$, with a minimum of 1.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **days_to_cover_** *ndarray of shape (n_assets,)*
  : Last days-to-cover value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.DaysToCover.html.md#skfolio.descriptor.DaysToCover.fit_transform)(X[, y])         | Compute exponentially weighted days to cover.         |
|--------------------------------------------------------------------------------|-------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.DaysToCover.html.md#skfolio.descriptor.DaysToCover.get_metadata_routing)()        | Get metadata routing of this object.                  |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.DaysToCover.html.md#skfolio.descriptor.DaysToCover.get_params)([deep])            | Get parameters for this estimator.                    |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.DaysToCover.html.md#skfolio.descriptor.DaysToCover.partial_fit_transform)(X[, y]) | Update state and return days to cover for this batch. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.DaysToCover.html.md#skfolio.descriptor.DaysToCover.set_params)(\*\*params)        | Set the parameters of this estimator.                 |

#### SEE ALSO
[`ShortInterest`](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#skfolio.descriptor.ShortInterest)
: Short interest as fraction of shares outstanding.

[`EWShareTurnover`](https://skfolio.org/generated/skfolio.descriptor.EWShareTurnover.html.md#skfolio.descriptor.EWShareTurnover)
: EWMA share turnover (volume / shares outstanding).

### Notes

`short_interest` is the number of shares held short. Non-missing values must be
finite and non-negative.

`adj_volume` is split-adjusted trading volume. Non-missing values must be finite and
non-negative.

The EWMA state is updated only for positive-volume observations. NaN or zero
`adj_volume` holds the EWMA state and does not increment the valid-observation
count. NaN `short_interest` propagates to the output but does not prevent the volume
state from updating.

The `active_mask` property of the [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)
distinguishes holidays from delistings.

### References

* <a id='rba227fd45f66-1'>**[1]**</a> “An investigation of the informational role of short interest in the Nasdaq market” The Journal of Finance. Desai, H., Ramesh, K., Thiagarajan, S. R., & Balachandran, B. V. (2002).
* <a id='rba227fd45f66-2'>**[2]**</a> “Short interest, institutional ownership, and stock returns” Journal of Financial Economics. Asquith, P., Pathak, P. A., & Ritter, J. R. (2005).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import DaysToCover
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 1-month EWMA volume smoothing (default)
>>> descriptor = DaysToCover()
>>> days_to_cover = descriptor.fit_transform(X)
>>>
>>> # 3-month EWMA volume smoothing
>>> descriptor = DaysToCover(half_life=63)
>>> days_to_cover = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.DaysToCover.fit_transform"></a>

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

Compute exponentially weighted days to cover.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `short_interest` and `adj_volume`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **days_to_cover** *ndarray of shape (n_observations, n_assets)*
  : Short interest divided by EWMA-smoothed daily volume for each observation
    and asset.

<a id="skfolio.descriptor.DaysToCover.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.descriptor.DaysToCover.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.descriptor.DaysToCover.partial_fit_transform"></a>

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

Update state and return days to cover for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `short_interest` and `adj_volume`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **days_to_cover** *ndarray of shape (n_observations, n_assets)*
  : Short interest divided by EWMA-smoothed daily volume for each observation
    and asset.

<a id="skfolio.descriptor.DaysToCover.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.

# generated/skfolio.descriptor.DebtToAssets.html.md

<a id="skfolio-descriptor-debttoassets"></a>

# skfolio.descriptor.DebtToAssets

<a id="skfolio.descriptor.DebtToAssets"></a>

### *class* skfolio.descriptor.DebtToAssets

Debt-to-assets ratio descriptor.

Computes the ratio of total debt to total assets:

$$
\text{debt\_to\_assets}(t) =
\frac{\text{total\_debt}(t)}{\text{total\_assets}(t)}
$$

Debt-to-assets is the most widely used leverage descriptor in equity risk models.
It measures the proportion of a firm’s asset base financed by debt. Higher values
indicate greater reliance on debt financing and, all else equal, a smaller equity
cushion to absorb losses, increasing the firm’s vulnerability to earnings shocks,
adverse financing conditions and credit deterioration [[1]](https://skfolio.org/generated/skfolio.descriptor.DebtToAssets.html.md#r7bd3686c5393-1).

The ratio is naturally bounded between 0 (no debt) and approximately 1 (assets fully
debt-financed), though it can exceed 1 when accumulated losses erode equity below
zero, making total liabilities exceed total assets.

NaNs are allowed as missing observations and propagate to the output. Non-missing
`total_debt` values must be finite. Non-missing `total_assets`  values must be
finite and strictly positive.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.DebtToAssets.html.md#skfolio.descriptor.DebtToAssets.fit_transform)(X[, y])         | Compute debt-to-assets ratios.                 |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.DebtToAssets.html.md#skfolio.descriptor.DebtToAssets.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.DebtToAssets.html.md#skfolio.descriptor.DebtToAssets.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.DebtToAssets.html.md#skfolio.descriptor.DebtToAssets.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.DebtToAssets.html.md#skfolio.descriptor.DebtToAssets.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`BookLeverage`](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#skfolio.descriptor.BookLeverage)
: Leverage as a fraction of total book capital.

[`MarketLeverage`](https://skfolio.org/generated/skfolio.descriptor.MarketLeverage.html.md#skfolio.descriptor.MarketLeverage)
: Leverage as a fraction of total market capital.

### References

* <a id='r7bd3686c5393-1'>**[1]**</a> “Debt/equity ratio and expected common stock returns: empirical evidence” The Journal of Finance. Bhandari, L. C. (1988).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import DebtToAssets
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = DebtToAssets()
>>> debt_to_assets = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.DebtToAssets.fit_transform"></a>

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

Compute debt-to-assets ratios.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `total_debt` and `total_assets`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **debt_to_assets** *ndarray of shape (n_observations, n_assets)*
  : Debt-to-assets ratio for each observation and asset.

<a id="skfolio.descriptor.DebtToAssets.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.descriptor.DebtToAssets.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.descriptor.DebtToAssets.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.DebtToAssets.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.

# generated/skfolio.descriptor.DividendToPrice.html.md

<a id="skfolio-descriptor-dividendtoprice"></a>

# skfolio.descriptor.DividendToPrice

<a id="skfolio.descriptor.DividendToPrice"></a>

### *class* skfolio.descriptor.DividendToPrice

Dividend-to-price ratio descriptor.

Computes the ratio of trailing twelve-month common dividends to market
: capitalization:

$$
\text{dividend\_to\_price}(t) =
\frac{\text{dividends\_ttm}(t)}{\text{market\_cap}(t)}
$$

Dividend-to-price measures the income yield that shareholders receive relative to
the current market price. High-yield stocks tend to be mature, cash-generative
businesses, while low-yield stocks are typically growth-oriented or retain earnings
for reinvestment [[1]](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#r65cfbb2a5d62-1). The dividend yield factor captures a distinct dimension of
value beyond book or earnings ratios because dividends reflect management’s
confidence in sustainable cash flows.

`dividends_ttm` should contain positive cash dividends paid on common shares only,
excluding preferred dividends. This is consistent with `market_cap`, which reflects
common equity.

This descriptor uses aggregate quantities (dividends paid divided by market
capitalization) rather than per-share quantities (dividends per share divided by
split-adjusted close price). The two are mathematically equivalent when the price
and per-share dividend use the same split-adjustment basis:

$$
\frac{\text{dividends\_ttm}}{\text{market\_cap}}
= \frac{\text{dividends\_ttm} / \text{shares\_out}}{\text{adj\_close}}
= \frac{\text{dps\_ttm}}{\text{adj\_close}}
$$

The aggregate form is preferred because it avoids subtle split-adjustment mismatches
between numerator and denominator. Aggregate fundamentals are the primary form from
data providers and per-share quantities are derived from them.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice.fit_transform)(X[, y])         | Compute trailing dividend-to-price ratios.     |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`ForwardDividendToPrice`](https://skfolio.org/generated/skfolio.descriptor.ForwardDividendToPrice.html.md#skfolio.descriptor.ForwardDividendToPrice)
: Forward (analyst-predicted) dividend yield.

[`ShareholderYield`](https://skfolio.org/generated/skfolio.descriptor.ShareholderYield.html.md#skfolio.descriptor.ShareholderYield)
: Dividend yield plus net buybacks.

### References

* <a id='r65cfbb2a5d62-1'>**[1]**</a> “Common risk factors in the returns on stocks and bonds” Journal of Financial Economics. Fama, E. F., & French, K. R. (1993).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import DividendToPrice
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = DividendToPrice()
>>> dividend_to_price = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.DividendToPrice.fit_transform"></a>

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

Compute trailing dividend-to-price ratios.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `dividends_ttm` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **dividend_to_price** *ndarray of shape (n_observations, n_assets)*
  : Dividend-to-price ratio for each observation and asset.

<a id="skfolio.descriptor.DividendToPrice.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.descriptor.DividendToPrice.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.descriptor.DividendToPrice.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.DividendToPrice.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.

# generated/skfolio.descriptor.EWAmihudIlliquidity.html.md

<a id="skfolio-descriptor-ewamihudilliquidity"></a>

# skfolio.descriptor.EWAmihudIlliquidity

<a id="skfolio.descriptor.EWAmihudIlliquidity"></a>

### *class* skfolio.descriptor.EWAmihudIlliquidity(half_life=63.0, min_periods=None)

Exponentially weighted Amihud illiquidity descriptor.

Computes an EWMA of the per-observation Amihud illiquidity ratio:

$$
\[
\begin{aligned}
\text{ILLIQ\_raw}(t)
    &= \frac{|r(t)|}
            {\text{adj\_close}(t) \times \text{adj\_volume}(t)} \\[0.75em]
\text{ILLIQ}(t)
    &= \lambda \cdot \text{ILLIQ}(t-1)
       + (1 - \lambda) \cdot \text{ILLIQ\_raw}(t)
\end{aligned}
\]
$$

where $\lambda = \exp(-\ln(2) / \text{half\_life})$ is the EWMA decay factor
and the denominator is the dollar trading volume (traded amount).

The Amihud illiquidity ratio is a proxy for price impact, defined as the absolute
return per unit of dollar volume traded. Higher values imply larger price moves for
a given dollar amount traded, reflecting lower liquidity. Higher illiquidity is
often associated with higher expected returns, commonly interpreted as an
illiquidity premium for bearing higher trading costs and exit risk [[1]](https://skfolio.org/generated/skfolio.descriptor.EWAmihudIlliquidity.html.md#r1d05a10cf7a2-1).

EWMA smoothing is preferred over a fixed rolling average because the raw ratio is
very noisy (it can spike when volume is low or returns are large). EWMA dampens
transient spikes gradually, producing more stable factor exposures.

* **Parameters:**
  **half_life** *float, default=63.0*
  : EWMA half-life in observations. Controls how fast old illiquidity values decay.
    With daily data, common choices are:
    - `half_life=21`: ~1 month
    - `half_life=63`: ~3 months (default)
    - `half_life=252`: ~1 year

  **min_periods** *int, optional*
  : Minimum number of valid illiquidity observations required for each asset. Until
    an asset reaches this count, its output is NaN. This warm-up period avoids
    exposing early EWMA values before the illiquidity estimate has sufficiently
    converged from its zero initialization. If `None`, defaults to
    $\lceil\text{half\_life}\rceil$, with a minimum of 1.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **illiquidity_** *ndarray of shape (n_assets,)*
  : Last EWMA-smoothed Amihud illiquidity value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWAmihudIlliquidity.html.md#skfolio.descriptor.EWAmihudIlliquidity.fit_transform)(X[, y])         | Compute exponentially weighted Amihud illiquidity.           |
|--------------------------------------------------------------------------------|--------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EWAmihudIlliquidity.html.md#skfolio.descriptor.EWAmihudIlliquidity.get_metadata_routing)()        | Get metadata routing of this object.                         |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EWAmihudIlliquidity.html.md#skfolio.descriptor.EWAmihudIlliquidity.get_params)([deep])            | Get parameters for this estimator.                           |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWAmihudIlliquidity.html.md#skfolio.descriptor.EWAmihudIlliquidity.partial_fit_transform)(X[, y]) | Update state and return smoothed illiquidity for this batch. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EWAmihudIlliquidity.html.md#skfolio.descriptor.EWAmihudIlliquidity.set_params)(\*\*params)        | Set the parameters of this estimator.                        |

#### SEE ALSO
[`EWShareTurnover`](https://skfolio.org/generated/skfolio.descriptor.EWShareTurnover.html.md#skfolio.descriptor.EWShareTurnover)
: EWMA share turnover (volume-based liquidity).

### Notes

Dollar trading volume (`traded_amount`) is computed internally as
`adj_close * adj_volume`. Both fields must use the same split-adjustment basis.

NaNs are allowed as missing observations. Non-missing `returns` values must be
finite. Non-missing `adj_close` values must be finite and strictly positive.
Non-missing `adj_volume` values must be finite and non-negative.

The EWMA state is updated only for valid observations. Zero `adj_volume` means the
stock did not trade, so the per-observation ratio is undefined: the EWMA state is
held and the valid-observation count is not incremented. NaN in `returns`,
`adj_close` or `adj_volume` is handled the same way.

The `active_mask` property of the [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)
distinguishes holidays from delistings.

### References

* <a id='r1d05a10cf7a2-1'>**[1]**</a> “Illiquidity and stock returns: cross-section and time-series effects” Journal of Financial Markets. Amihud, Y. (2002).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWAmihudIlliquidity
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 3-month effective window (default)
>>> descriptor = EWAmihudIlliquidity()
>>> illiq = descriptor.fit_transform(X)
>>>
>>> # 1-month effective window
>>> descriptor = EWAmihudIlliquidity(half_life=21)
>>> illiq_1m = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EWAmihudIlliquidity.fit_transform"></a>

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

Compute exponentially weighted Amihud illiquidity.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`, `adj_close`, and `adj_volume`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **illiquidity** *ndarray of shape (n_observations, n_assets)*
  : EWMA-smoothed Amihud illiquidity for each observation and asset.

<a id="skfolio.descriptor.EWAmihudIlliquidity.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.descriptor.EWAmihudIlliquidity.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.descriptor.EWAmihudIlliquidity.partial_fit_transform"></a>

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

Update state and return smoothed illiquidity for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `"returns"`, `"adj_close"`, and
    `"adj_volume"`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **illiquidity** *ndarray of shape (n_observations, n_assets)*
  : EWMA-smoothed Amihud illiquidity for each observation and asset.

<a id="skfolio.descriptor.EWAmihudIlliquidity.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.

# generated/skfolio.descriptor.EWDownsideBeta.html.md

<a id="skfolio-descriptor-ewdownsidebeta"></a>

# skfolio.descriptor.EWDownsideBeta

<a id="skfolio.descriptor.EWDownsideBeta"></a>

### *class* skfolio.descriptor.EWDownsideBeta(half_life=60.0, min_acceptable_return=0.0, min_periods=None, eps=1e-12)

Exponentially weighted downside beta descriptor.

Measures the sensitivity of each asset to market downturns using lower partial
co-moments. Unlike standard beta, which treats up-moves and down-moves
symmetrically, downside beta captures how much an asset tends to drop when the
market drops [[1]](https://skfolio.org/generated/skfolio.descriptor.EWDownsideBeta.html.md#r884431b3d256-1) [[2]](https://skfolio.org/generated/skfolio.descriptor.EWDownsideBeta.html.md#r884431b3d256-2).

The lower partial co-moment formulation is:

$$
\[
\begin{aligned}
D_i(t)
    &= \min(r_i(t) - \text{mar},\; 0) \\[0.75em]
D_m(t)
    &= \min(r_m(t) - \text{mar},\; 0) \\[0.75em]
\beta^{\text{down}}_i(t)
    &= \frac{\text{EWMA}(D_i \cdot D_m)}
            {\text{EWMA}(D_m^2)}
\end{aligned}
\]
$$

where $\text{mar}$ is the minimum acceptable return threshold and the EWMA
uses decay $\lambda = \exp(-\ln(2) / \text{half\_life})$.

The EWMA is updated at every observation. Returns above `mar` add zero downside
co-moment for that observation, while previous downside co-moments still decay.
This avoids freezing the estimator during calm periods, unlike a conditional
estimator that updates only on down-market days.

* **Parameters:**
  **half_life** *float, default=60.0*
  : EWMA half-life in observations. Controls how fast old observations decay. The
    default of 60 trading days (~3 months) balances responsiveness and stability.
    Adjust for other frequencies (e.g. `half_life=12` for weekly data).

  **min_acceptable_return** *float, default=0.0*
  : Threshold below which returns are considered “downside”. The default of `0.0`
    defines downside as negative returns (losses).

  **min_periods** *int, optional*
  : Minimum number of market observations and valid asset returns required before
    computing downside betas. Until both counts reach this value, the asset’s output
    is NaN. This warm-up period avoids exposing early EWMA values before the
    downside beta estimate has sufficiently converged from its zero initialization.
    If `None`, defaults to $\lceil\text{half\_life}\rceil$, with a minimum
    of 1.

  **eps** *float, default=1e-12*
  : Small constant for numerical stability in $1 / \text{EWMA}(D_m^2)$.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **downside_beta_** *ndarray of shape (n_assets,)*
  : Last fitted downside beta value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideBeta.html.md#skfolio.descriptor.EWDownsideBeta.fit_transform)(X[, y])         | Compute exponentially weighted downside betas.              |
|--------------------------------------------------------------------------------|-------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideBeta.html.md#skfolio.descriptor.EWDownsideBeta.get_metadata_routing)()        | Get metadata routing of this object.                        |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideBeta.html.md#skfolio.descriptor.EWDownsideBeta.get_params)([deep])            | Get parameters for this estimator.                          |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideBeta.html.md#skfolio.descriptor.EWDownsideBeta.partial_fit_transform)(X[, y]) | Update EWMA state and return downside betas for this batch. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideBeta.html.md#skfolio.descriptor.EWDownsideBeta.set_params)(\*\*params)        | Set the parameters of this estimator.                       |

### Notes

The EWMA is initialized to zero (no bias correction). Since the initialization bias
is identical across all assets at each time step, cross-sectional rankings are
unaffected.

The market downside variance is updated at every observation. Asset co-moments are
updated only for assets with valid (non-NaN) returns and each asset’s
valid-observation count controls when its output starts. This avoids emitting
initialized values for late-listed or sparsely observed assets. The `active_mask`
property of [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) distinguishes holidays from
delistings.

Market returns are computed from the estimation universe (`estimation_mask` of
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)). If no estimable asset has both finite
returns and finite `market_cap` at an observation, the market return is undefined
and a `ValueError` is raised.

### References

* <a id='r884431b3d256-1'>**[1]**</a> “Downside risk” The Review of Financial Studies. Ang, A., Chen, J., & Xing, Y. (2006).
* <a id='r884431b3d256-2'>**[2]**</a> “Systematic risk in emerging markets: the D-CAPM”. Emerging Markets Review. Estrada, J. (2002).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWDownsideBeta
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # Standard downside beta (losses only)
>>> descriptor = EWDownsideBeta()
>>> downside_beta = descriptor.fit_transform(X)
>>>
>>> # Custom threshold
>>> descriptor = EWDownsideBeta(min_acceptable_return=-0.01)
>>> downside_beta = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EWDownsideBeta.fit_transform"></a>

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

Compute exponentially weighted downside betas.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **downside_beta** *ndarray of shape (n_observations, n_assets)*
  : Downside beta for each observation and asset.

<a id="skfolio.descriptor.EWDownsideBeta.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.descriptor.EWDownsideBeta.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.descriptor.EWDownsideBeta.partial_fit_transform"></a>

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

Update EWMA state and return downside betas for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **downside_beta** *ndarray of shape (n_observations, n_assets)*
  : Downside beta for each observation and asset.

<a id="skfolio.descriptor.EWDownsideBeta.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.

# generated/skfolio.descriptor.EWDownsideVolatility.html.md

<a id="skfolio-descriptor-ewdownsidevolatility"></a>

# skfolio.descriptor.EWDownsideVolatility

<a id="skfolio.descriptor.EWDownsideVolatility"></a>

### *class* skfolio.descriptor.EWDownsideVolatility(half_life=40.0, min_acceptable_return=0.0, min_periods=None)

Exponentially weighted downside return volatility descriptor.

Computes the downside semi-deviation of asset returns using EWMA estimation [[1]](https://skfolio.org/generated/skfolio.descriptor.EWDownsideVolatility.html.md#r598f00014148-1).
Only returns below the `min_acceptable_return` threshold contribute to the variance
estimate:

$$
\[
\begin{aligned}
D_i(t)
    &= \min(r_i(t) - \text{mar},\; 0) \\[0.75em]
S_{\text{down},i}(t)
    &= \lambda \cdot S_{\text{down},i}(t-1)
       + (1 - \lambda) \cdot D_i(t)^2 \\[0.75em]
\text{output}_i(t)
    &= \sqrt{\frac{S_{\text{down},i}(t)}
                 {1 - \lambda^{n_i(t)}}}
\end{aligned}
\]
$$

where $\lambda = \exp(-\ln(2)/\text{half\_life})$ and $n_i(t)$ is the
number of valid returns for asset $i$.

* **Parameters:**
  **half_life** *float, default=40.0*
  : EWMA half-life in observations.

  **min_acceptable_return** *float, default=0.0*
  : Threshold below which returns are considered “downside”. The default of `0.0`
    defines downside as negative returns (losses).

  **min_periods** *int, optional*
  : Minimum number of valid returns required for each asset. Until an asset reaches
    this count, its output is NaN. This warm-up period avoids exposing early EWMA
    values before the downside volatility estimate has sufficiently converged from
    its zero initialization. If `None`, defaults to
    $\lceil\text{half\_life}\rceil$, with a minimum of 1.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **volatility_** *ndarray of shape (n_assets,)*
  : Last computed EWMA downside volatility. Contains NaN for inactive assets and
    assets that have not reached `min_periods` valid returns.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideVolatility.html.md#skfolio.descriptor.EWDownsideVolatility.fit_transform)(X[, y])         | Compute exponentially weighted return volatility.       |
|--------------------------------------------------------------------------------|---------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideVolatility.html.md#skfolio.descriptor.EWDownsideVolatility.get_metadata_routing)()        | Get metadata routing of this object.                    |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideVolatility.html.md#skfolio.descriptor.EWDownsideVolatility.get_params)([deep])            | Get parameters for this estimator.                      |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideVolatility.html.md#skfolio.descriptor.EWDownsideVolatility.partial_fit_transform)(X[, y]) | Update EWMA state and return volatility for this batch. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideVolatility.html.md#skfolio.descriptor.EWDownsideVolatility.set_params)(\*\*params)        | Set the parameters of this estimator.                   |

#### SEE ALSO
[`EWVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWVolatility.html.md#skfolio.descriptor.EWVolatility)
: Total (non-downside) variant.

[`EWResidualDownsideVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWResidualDownsideVolatility.html.md#skfolio.descriptor.EWResidualDownsideVolatility)
: Downside CAPM residual volatility.

### Notes

The EWMA variance accumulator is initialized to zero and bias-corrected at output
time using each asset’s valid observation count, matching
[`EWVariance`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance).

NaNs are treated as missing observations. Active assets with missing returns keep
their previous EWMA state and inactive assets output NaN and restart their warm-up
period when they become active again. Non-missing returns must be finite.

### References

* <a id='r598f00014148-1'>**[1]**</a> “The cross-section of volatility and expected returns” The Journal of Finance. Ang, A., Hodrick, R. J., Xing, Y., & Zhang, X. (2006).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWDownsideVolatility
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = EWDownsideVolatility()
>>> downside_volatility = descriptor.fit_transform(X)
>>>
>>> # Custom threshold
>>> descriptor = EWDownsideVolatility(min_acceptable_return=-0.01)
>>> downside_volatility = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EWDownsideVolatility.fit_transform"></a>

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

Compute exponentially weighted return volatility.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **volatility** *ndarray of shape (n_observations, n_assets)*
  : EWMA volatility (or downside volatility) for each observation and asset.

<a id="skfolio.descriptor.EWDownsideVolatility.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.descriptor.EWDownsideVolatility.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.descriptor.EWDownsideVolatility.partial_fit_transform"></a>

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

Update EWMA state and return volatility for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **volatility** *ndarray of shape (n_observations, n_assets)*
  : EWMA volatility (or downside volatility) for each observation and asset.

<a id="skfolio.descriptor.EWDownsideVolatility.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.

# generated/skfolio.descriptor.EWMacroSensitivity.html.md

<a id="skfolio-descriptor-ewmacrosensitivity"></a>

# skfolio.descriptor.EWMacroSensitivity

<a id="skfolio.descriptor.EWMacroSensitivity"></a>

### *class* skfolio.descriptor.EWMacroSensitivity(half_life=60.0, aggregation_period=1, min_periods=None, eps=1e-12)

EWMA macro sensitivity after removing market exposure.

The descriptor estimates the partial regression coefficient of asset returns on an
external reference series (e.g. FX, rates, inflation, commodity basket) after
removing the linear exposure to market returns in a bivariate EWMA regression:

$$
r_{i,t} = \alpha_i + \beta^M_i\, r_{\text{market},t}
         + \beta^{\text{ref}}_i\, r_{\text{ref},t}
         + \varepsilon_{i,t}
$$

where $r_{i,t}$ is the return of asset $i$ at time $t$,
$r_{\text{market},t}$ (denoted $r_{m,t}$) is the cap-weighted market
return computed on the estimation universe (`estimation_mask`) and
$r_{\text{ref},t}$ is the external reference return.

The output is $\beta^{\text{ref}}_i$, the sensitivity to the reference series
after removing market exposure.

The partial beta is computed in closed form via the Frisch-Waugh decomposition,
using only EWMA moments and no matrix inversion:

$$
\beta^{\text{ref}}_i =
\frac{C_{y_i f} - C_{y_i m}\, C_{mf} / V_m}
     {V_f - C_{mf}^2 / V_m}
$$

where $V_m, V_f$ are EWMA variances of market and reference, $C_{mf}$ is
their EWMA covariance and $C_{y_i m}, C_{y_i f}$ are the EWMA covariances of
asset $i$ with market and reference respectively.

* **Parameters:**
  **half_life** *float, default=60.0*
  : EWMA half-life in units of aggregated periods.

  **aggregation_period** *int, default=1*
  : Number of consecutive observations to aggregate before updating
    EWMA statistics.

  **min_periods** *int, optional*
  : Minimum number of market/reference observations and valid asset returns
    required before computing macro sensitivities. Until both counts reach this
    value, the asset’s output is NaN. This warm-up period avoids exposing early
    EWMA values before the sensitivity estimate has sufficiently converged from its
    zero initialization. If `None`, defaults to
    $\lceil\text{half\_life}\rceil$, with a minimum of 1.

  **eps** *float, default=1e-12*
  : Small constant for numerical stability in denominators.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **macro_sensitivity_** *ndarray of shape (n_assets,)*
  : Last fitted partial beta to the reference series for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWMacroSensitivity.html.md#skfolio.descriptor.EWMacroSensitivity.fit_transform)(X[, y, reference_returns])         | Compute exponentially weighted macro sensitivities.              |
|---------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EWMacroSensitivity.html.md#skfolio.descriptor.EWMacroSensitivity.get_metadata_routing)()                           | Return metadata routing for the external reference series.       |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EWMacroSensitivity.html.md#skfolio.descriptor.EWMacroSensitivity.get_params)([deep])                               | Get parameters for this estimator.                               |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWMacroSensitivity.html.md#skfolio.descriptor.EWMacroSensitivity.partial_fit_transform)(X[, y, reference_returns]) | Update EWMA state and return macro sensitivities for this batch. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EWMacroSensitivity.html.md#skfolio.descriptor.EWMacroSensitivity.set_params)(\*\*params)                           | Set the parameters of this estimator.                            |

#### SEE ALSO
[`EWMarketBeta`](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#skfolio.descriptor.EWMarketBeta)
: Univariate EWMA beta to the market portfolio.

### Notes

NaNs are allowed as missing observations. Non-missing `returns` and
`reference_returns` values must be finite. A missing reference return freezes the
full EWMA state for that observation or aggregated window. Asset covariances are
updated only for assets with valid returns, and each asset’s valid-observation count
controls when its output starts.

Market returns are computed from the estimation universe (`estimation_mask` of
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)). If no estimable asset has both finite
returns and finite `market_cap` at an observation, the market return is undefined
and a `ValueError` is raised.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWMacroSensitivity
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> fx_basket = np.random.default_rng(0).standard_normal(X.n_observations)
>>> rate_returns = np.random.default_rng(1).standard_normal(X.n_observations)
>>>
>>> # FX sensitivity (daily updates with default memory)
>>> descriptor = EWMacroSensitivity()
>>> macro_sensitivity = descriptor.fit_transform(X, reference_returns=fx_basket)
```

<a id="skfolio.descriptor.EWMacroSensitivity.fit_transform"></a>

#### fit_transform(X, y=None, reference_returns=None, \*\*fit_params)

Compute exponentially weighted macro sensitivities.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **reference_returns** *array-like of shape (n_observations,)*
  : External reference return series aligned with `X` (e.g., macro factor).

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **sensitivities** *ndarray of shape (n_observations, n_assets)*
  : Partial beta to the reference series for each observation and asset.

<a id="skfolio.descriptor.EWMacroSensitivity.get_metadata_routing"></a>

#### get_metadata_routing()

Return metadata routing for the external reference series.

<a id="skfolio.descriptor.EWMacroSensitivity.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.descriptor.EWMacroSensitivity.partial_fit_transform"></a>

#### partial_fit_transform(X, y=None, reference_returns=None, \*\*fit_params)

Update EWMA state and return macro sensitivities for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `"returns"` and `"market_cap"`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **reference_returns** *array-like of shape (n_observations,)*
  : External macro reference returns, e.g. FX basket returns.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **sensitivities** *ndarray of shape (n_observations, n_assets)*
  : Partial beta to the reference series for each observation and asset.

<a id="skfolio.descriptor.EWMacroSensitivity.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.

# generated/skfolio.descriptor.EWMarketBeta.html.md

<a id="skfolio-descriptor-ewmarketbeta"></a>

# skfolio.descriptor.EWMarketBeta

<a id="skfolio.descriptor.EWMarketBeta"></a>

### *class* skfolio.descriptor.EWMarketBeta(half_life=60.0, aggregation_period=1, min_periods=None, shrinkage_group=None, min_group_size=5, shrinkage_bounds=(0.0, 1.0), eps=1e-12)

Exponentially weighted market beta descriptor.

Measures each asset’s sensitivity to the market portfolio using exponentially
weighted covariance and variance estimates [[1]](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#r317192b78e0b-1):

$$
\beta_i = \frac{\text{Cov}(r_i, r_m)}{\text{Var}(r_m)}
$$

where $r_i$ is the return of asset $i$, $r_m$ is the cap-weighted
market return computed on the estimation universe and the EWMA uses decay
$\lambda = \exp(-\ln(2) / \text{half\_life})$.

* **Parameters:**
  **half_life** *float, default=60.0*
  : EWMA half-life in observations after aggregation. For example, with
    `aggregation_period=5` and `half_life=60`, the EWMA decays over 60 aggregated
    periods, equivalent to 300 raw observations.

  **aggregation_period** *int, default=1*
  : Number of consecutive observations to aggregate before updating EWMA statistics.
    Aggregation can reduce desynchronization effects. Returns are aggregated with
    the mean of finite values. If an asset has no finite returns in an aggregation
    window, its state is unchanged.

  **min_periods** *int, optional*
  : Minimum number of market observations and valid asset returns required before
    computing market betas. Until both counts reach this value, the asset’s output
    is NaN. This warm-up period avoids exposing early EWMA values before the beta
    estimate has sufficiently converged from its zero initialization. If `None`,
    defaults to $\lceil\text{half\_life}\rceil$, with a minimum of 1.

  **shrinkage_group** *str, optional*
  : Name of a categorical field containing group labels (e.g., `"industry"`) for
    Bayesian shrinkage. When provided, raw betas are shrunk toward the cap-weighted
    group mean using an empirical Bayes approach:
    $$
    \beta_i^{\text{shrunk}} = w_i \cdot \beta_i^{\text{raw}}
    + (1 - w_i) \cdot \mu_g
    $$
    <br/>
    where $w_i = \tau_g^2 / (\tau_g^2 + \sigma_i^2)$, $\mu_g$ is the
    cap-weighted group mean, $\tau_g^2$ is the prior variance (cross-sectional
    variance minus noise) and $\sigma_i^2$ is the estimation error variance.
    <br/>
    Missing category codes are excluded from shrinkage. If `None` (default), no
    shrinkage is applied.

  **min_group_size** *int, default=5*
  : Minimum number of assets in a group to compute group-specific statistics.
    Groups with fewer assets fall back to global (cross-sectional) statistics.
    Only used when `shrinkage_group` is provided.

  **shrinkage_bounds** *tuple of float, default=(0.0, 1.0)*
  : Lower and upper bounds `(w_min, w_max)` for the raw-beta weight
    $w_i$. Lower values apply more shrinkage toward the group mean, while
    higher values keep more of the raw beta. The coefficient is clipped to this
    range after estimation.
    <br/>
    For example, `(0.1, 0.9)` keeps at least 10% weight on the raw beta and at
    least 10% weight on the group mean. Only used when `shrinkage_group` is
    provided.

  **eps** *float, default=1e-12*
  : Small constant for numerical stability in
    $1 / \text{Var}(\text{market})$.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **market_beta_** *ndarray of shape (n_assets,)*
  : Last fitted market beta value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#skfolio.descriptor.EWMarketBeta.fit_transform)(X[, y])         | Compute exponentially weighted market betas.            |
|--------------------------------------------------------------------------------|---------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#skfolio.descriptor.EWMarketBeta.get_metadata_routing)()        | Get metadata routing of this object.                    |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#skfolio.descriptor.EWMarketBeta.get_params)([deep])            | Get parameters for this estimator.                      |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#skfolio.descriptor.EWMarketBeta.partial_fit_transform)(X[, y]) | Update EWMA state on X and return betas for this batch. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#skfolio.descriptor.EWMarketBeta.set_params)(\*\*params)        | Set the parameters of this estimator.                   |

### Notes

NaNs are allowed as missing observations. Non-missing `returns` values must be
finite. The market variance is updated at every observation. Asset covariances are
updated only for assets with valid returns and each asset’s valid-observation count
controls when its output starts. This avoids emitting initialized values for
late-listed or sparsely observed assets. The `active_mask` property of
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) distinguishes holidays from delistings.

Market returns are computed from the estimation universe (`estimation_mask` of
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)). If no estimable asset has both finite
returns and finite `market_cap` at an observation, the market return is undefined
and a `ValueError` is raised.

### References

* <a id='r317192b78e0b-1'>**[1]**</a> “Capital asset prices: A theory of market equilibrium under conditions of risk”. The Journal of Finance. Sharpe, W. F. (1964).

<a id="skfolio.descriptor.EWMarketBeta.fit_transform"></a>

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

Compute exponentially weighted market betas.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns` and `market_cap`, and when
    `shrinkage_group` is set, that group characteristic.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **betas** *ndarray of shape (n_observations, n_assets)*
  : Market beta for each observation and asset.

<a id="skfolio.descriptor.EWMarketBeta.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.descriptor.EWMarketBeta.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.descriptor.EWMarketBeta.partial_fit_transform"></a>

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

Update EWMA state on X and return betas for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing at least `"returns"` and `"market_cap"`.
    If shrinkage is enabled, it must also contain the field specified
    by `shrinkage_group`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **betas** *ndarray of shape (n_observations, n_assets)*
  : Market beta for each observation and asset.

<a id="skfolio.descriptor.EWMarketBeta.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.

# generated/skfolio.descriptor.EWMomentum.html.md

<a id="skfolio-descriptor-ewmomentum"></a>

# skfolio.descriptor.EWMomentum

<a id="skfolio.descriptor.EWMomentum"></a>

### *class* skfolio.descriptor.EWMomentum(half_life=87.0, skip=21, min_periods=None, exponentiate=False)

Exponentially weighted momentum descriptor.

Computes an EWMA of log returns with an optional skip period to exclude the most
recent observations:

The skip period separates medium-term momentum from short-term reversal. The classic
“12-1” momentum signal uses a skip of approximately one month [[1]](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#r9ed0ebc21f02-1).

$$
\[
\begin{aligned}
x(t)
    &= \log(1 + r(t)) \\[0.75em]
S(t)
    &= \lambda \cdot S(t-1)
       + (1 - \lambda) \cdot x(t - \text{skip}) \\[0.75em]
\text{momentum}(t)
    &=
    \begin{cases}
    \exp(S(t)) - 1 & \text{if } \texttt{exponentiate=True} \\
    S(t) & \text{otherwise}
    \end{cases}
\end{aligned}
\]
$$

where $\lambda = \exp(-\ln(2) / \text{half\_life})$ is the EWMA decay factor.
At observation $t$, the EWMA input is the log return from $t - \text{skip}$.
Therefore, $\text{half\_life}$ is measured on the delayed input series. An
EWMA with this half-life is comparable to a fixed window of about
$2 \cdot \text{half\_life} / \ln 2$ delayed observations, with the most recent
$\text{skip}$ observations excluded.

* **Parameters:**
  **half_life** *float, default=87.0*
  : Controls how fast old returns decay in the EWMA of
    $\log(1 + r(t - \text{skip}))$. The default of 87 approximately matches a
    [`RollingMomentum`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum) window of 252 observations (~1 year of daily data). To
    match a different window $W$, use
    $\text{half\_life} \approx W \cdot \ln(2) / 2 \approx 0.35 \, W$. Adjust
    for other frequencies (e.g., `half_life=6` for monthly data).

  **skip** *int, default=21*
  : Number of most recent observations to exclude before the EWMA window starts.
    Used to separate medium-term momentum from short-term reversal. The default
    assumes daily data and skips approximately one month. Set to `0` for short-term
    momentum.

  **min_periods** *int, optional*
  : Minimum number of valid delayed returns required for each asset. Until an asset
    reaches this count, its output is NaN. This warm-up period avoids exposing early
    EWMA values before the estimate has sufficiently converged from its zero
    initialization. If `None`, defaults to $\lceil\text{half\_life}\rceil$,
    with a minimum of 1.

  **exponentiate** *bool, default=False*
  : If True, output is $\exp(S(t)) - 1$ (return units). If False, output is
    $S(t)$ (EWMA of log returns; log space). Cross-sectional ranking is
    unchanged.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **momentum_** *ndarray of shape (n_assets,)*
  : Last exponentially weighted momentum value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum.fit_transform)(X[, y])         | Compute exponentially weighted momentum from returns.   |
|--------------------------------------------------------------------------------|---------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum.get_metadata_routing)()        | Get metadata routing of this object.                    |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum.get_params)([deep])            | Get parameters for this estimator.                      |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum.partial_fit_transform)(X[, y]) | Compute exponentially weighted momentum from returns.   |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum.set_params)(\*\*params)        | Set the parameters of this estimator.                   |

#### SEE ALSO
[`RollingMomentum`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum)
: Fixed-window (equal-weighted) momentum.

### Notes

The EWMA is initialized to zero (no bias correction).

NaNs are allowed as missing observations. Non-missing `returns` values must be
finite and greater than `-1`, so $\log(1 + r)$ is finite. The EWMA state is
updated only for finite delayed log returns, and each asset’s valid-observation
count controls when its output starts. The `active_mask` property of the input
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) distinguishes holidays from delistings.

### References

* <a id='r9ed0ebc21f02-1'>**[1]**</a> “Returns to buying winners and selling losers: Implications for stock market efficiency” The Journal of Finance. Jegadeesh, N., & Titman, S. (1993).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWMomentum
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 12-1 momentum with daily data (default)
>>> descriptor = EWMomentum()
>>> momentum = descriptor.fit_transform(X)
>>>
>>> # Short-term momentum (no skip)
>>> descriptor = EWMomentum(half_life=10, skip=0)
>>> short_term_momentum = descriptor.fit_transform(X)
>>>
>>> # Log-space output
>>> descriptor = EWMomentum(exponentiate=False)
>>> momentum_log = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EWMomentum.fit_transform"></a>

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

Compute exponentially weighted momentum from returns.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **momentum** *ndarray of shape (n_observations, n_assets)*
  : EWMA momentum signal for each observation and asset.

<a id="skfolio.descriptor.EWMomentum.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.descriptor.EWMomentum.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.descriptor.EWMomentum.partial_fit_transform"></a>

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

Compute exponentially weighted momentum from returns.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **momentum** *ndarray of shape (n_observations, n_assets)*
  : EWMA momentum signal for each observation and asset.

<a id="skfolio.descriptor.EWMomentum.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.

# generated/skfolio.descriptor.EWResidualDownsideVolatility.html.md

<a id="skfolio-descriptor-ewresidualdownsidevolatility"></a>

# skfolio.descriptor.EWResidualDownsideVolatility

<a id="skfolio.descriptor.EWResidualDownsideVolatility"></a>

### *class* skfolio.descriptor.EWResidualDownsideVolatility(half_life=40.0, beta_half_life=60.0, min_acceptable_return=0.0, min_periods=None, eps=1e-12)

Exponentially weighted downside CAPM residual volatility descriptor.

Computes downside volatility of CAPM residuals with an EWMA variance estimate.
Only residuals below the `min_acceptable_return` threshold contribute:

$$
\[
\begin{aligned}
\epsilon_i(t)
    &= r_i(t) - \hat\beta_i(t) \cdot r_m(t) \\[0.75em]
D_i(t)
    &= \min(\epsilon_i(t) - \text{mar},\; 0) \\[0.75em]
S_{\text{down},i}(t)
    &= \lambda_v \cdot S_{\text{down},i}(t-1)
       + (1 - \lambda_v) \cdot D_i(t)^2 \\[0.75em]
\text{output}_i(t)
    &= \sqrt{\frac{S_{\text{down},i}(t)}
                 {1 - \lambda_v^{n_i(t)}}}
\end{aligned}
\]
$$

where $\hat\beta_i(t)$ is the EWMA beta estimated with decay
$\lambda_\beta = \exp(-\ln(2)/\text{beta\_half\_life})$,
$\lambda_v = \exp(-\ln(2)/\text{half\_life})$ and $n_i(t)$ is the
number of valid returns for asset $i$. The zero-initialized residual variance
accumulator is bias-corrected at output time using each asset’s valid observation
count.

This measures stock-specific downside risk after removing market exposure.

* **Parameters:**
  **half_life** *float, default=40.0*
  : EWMA half-life in observations for the residual variance estimator.

  **beta_half_life** *float, default=60.0*
  : EWMA half-life in observations for the beta estimator.

  **min_acceptable_return** *float, default=0.0*
  : Threshold below which residuals are considered “downside”. The default of `0.0`
    defines downside as negative residuals (losses after removing market exposure).

  **min_periods** *int, optional*
  : Minimum number of valid returns required for each asset. Until an asset
    reaches this count, its output is NaN. This warm-up period avoids exposing
    early EWMA values before the downside residual volatility estimate has
    sufficiently converged from its zero initialization. If `None`, defaults to
    $\lceil\max(\text{half\_life}, \text{beta\_half\_life})\rceil$, with a
    minimum of 1.

  **eps** *float, default=1e-12*
  : Small constant for numerical stability in $1 / \text{Var}(r_m)$ when
    computing beta.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **residual_volatility_** *ndarray of shape (n_assets,)*
  : Last computed EWMA downside residual volatility. Contains NaN for inactive
    assets and assets that have not reached `min_periods` valid returns.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWResidualDownsideVolatility.html.md#skfolio.descriptor.EWResidualDownsideVolatility.fit_transform)(X[, y])         | Compute exponentially weighted CAPM residual volatility.         |
|--------------------------------------------------------------------------------|------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EWResidualDownsideVolatility.html.md#skfolio.descriptor.EWResidualDownsideVolatility.get_metadata_routing)()        | Get metadata routing of this object.                             |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EWResidualDownsideVolatility.html.md#skfolio.descriptor.EWResidualDownsideVolatility.get_params)([deep])            | Get parameters for this estimator.                               |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWResidualDownsideVolatility.html.md#skfolio.descriptor.EWResidualDownsideVolatility.partial_fit_transform)(X[, y]) | Update EWMA state and return residual volatility for this batch. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EWResidualDownsideVolatility.html.md#skfolio.descriptor.EWResidualDownsideVolatility.set_params)(\*\*params)        | Set the parameters of this estimator.                            |

#### SEE ALSO
[`EWResidualVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility)
: Total (non-downside) variant.

### Notes

NaNs are treated as missing observations. Active assets with missing returns
keep their previous asset-specific EWMA state; inactive assets output NaN and
restart their warm-up period when they become active again. Non-missing returns
must be finite.

Market returns are computed from the estimation universe (`estimation_mask` of
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)). If no estimable asset has both finite
returns and finite `market_cap` at an observation, the market return is undefined
and a `ValueError` is raised.

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWResidualDownsideVolatility
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # Downside residual volatility (losses only)
>>> descriptor = EWResidualDownsideVolatility()
>>> residual_downside_volatility = descriptor.fit_transform(X)
>>>
>>> # Custom threshold
>>> descriptor = EWResidualDownsideVolatility(min_acceptable_return=-0.01)
>>> residual_downside_volatility = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EWResidualDownsideVolatility.fit_transform"></a>

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

Compute exponentially weighted CAPM residual volatility.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **residual_volatility** *ndarray of shape (n_observations, n_assets)*
  : Residual return volatility for each observation and asset.

<a id="skfolio.descriptor.EWResidualDownsideVolatility.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.descriptor.EWResidualDownsideVolatility.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.descriptor.EWResidualDownsideVolatility.partial_fit_transform"></a>

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

Update EWMA state and return residual volatility for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **residual_volatility** *ndarray of shape (n_observations, n_assets)*
  : Residual return volatility for each observation and asset.

<a id="skfolio.descriptor.EWResidualDownsideVolatility.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.

# generated/skfolio.descriptor.EWResidualVolatility.html.md

<a id="skfolio-descriptor-ewresidualvolatility"></a>

# skfolio.descriptor.EWResidualVolatility

<a id="skfolio.descriptor.EWResidualVolatility"></a>

### *class* skfolio.descriptor.EWResidualVolatility(half_life=40.0, beta_half_life=60.0, min_periods=None, eps=1e-12)

Exponentially weighted CAPM residual volatility descriptor.

Computes volatility of CAPM residuals with an EWMA variance estimate:

$$
\[
\begin{aligned}
\epsilon_i(t)
    &= r_i(t) - \hat\beta_i(t) \cdot r_m(t) \\[0.75em]
S_{\epsilon,i}(t)
    &= \lambda_v \cdot S_{\epsilon,i}(t-1)
       + (1 - \lambda_v) \cdot \epsilon_i(t)^2 \\[0.75em]
\text{output}_i(t)
    &= \sqrt{\frac{S_{\epsilon,i}(t)}
                 {1 - \lambda_v^{n_i(t)}}}
\end{aligned}
\]
$$

where $\hat\beta_i(t)$ is the EWMA beta estimated with decay
$\lambda_\beta = \exp(-\ln(2)/\text{beta\_half\_life})$ and the residual
variance uses decay $\lambda_v = \exp(-\ln(2)/\text{half\_life})$. The
zero-initialized residual variance accumulator is bias-corrected at output
time using each asset’s valid observation count $n_i(t)$.

The market return $r_m(t)$ is computed as the cap-weighted average of returns
in the estimation universe.

Residual volatility isolates the part of return variation not explained by the
market. This can be useful when market beta is already modeled separately and the
intended signal is stock-specific risk after removing market exposure [[1]](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#r5416aa9231c8-1).

* **Parameters:**
  **half_life** *float, default=40.0*
  : EWMA half-life in observations for the residual variance estimator.

  **beta_half_life** *float, default=60.0*
  : EWMA half-life in observations for the beta estimator.

  **min_periods** *int, optional*
  : Minimum number of valid returns required for each asset. Until an asset
    reaches this count, its output is NaN. This warm-up period avoids exposing
    early EWMA values before the residual volatility estimate has sufficiently
    converged from its zero initialization. If `None`, defaults to
    $\lceil\max(\text{half\_life}, \text{beta\_half\_life})\rceil$, with a
    minimum of 1.

  **eps** *float, default=1e-12*
  : Small constant for numerical stability in $1 / \text{Var}(r_m)$ when
    computing beta.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **residual_volatility_** *ndarray of shape (n_assets,)*
  : Last computed EWMA residual volatility. Contains NaN for inactive assets and
    assets that have not reached `min_periods` valid returns.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility.fit_transform)(X[, y])         | Compute exponentially weighted CAPM residual volatility.         |
|--------------------------------------------------------------------------------|------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility.get_metadata_routing)()        | Get metadata routing of this object.                             |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility.get_params)([deep])            | Get parameters for this estimator.                               |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility.partial_fit_transform)(X[, y]) | Update EWMA state and return residual volatility for this batch. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility.set_params)(\*\*params)        | Set the parameters of this estimator.                            |

#### SEE ALSO
[`EWResidualDownsideVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWResidualDownsideVolatility.html.md#skfolio.descriptor.EWResidualDownsideVolatility)
: Downside variant using semi-deviation of residuals.

### Notes

NaNs are treated as missing observations. Active assets with missing returns
keep their previous asset-specific EWMA state; inactive assets output NaN and
restart their warm-up period when they become active again. Non-missing returns
must be finite.

Market returns are computed from the estimation universe (`estimation_mask` of
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)). If no estimable asset has both finite
returns and finite `market_cap` at an observation, the market return is undefined
and a `ValueError` is raised.

### References

* <a id='r5416aa9231c8-1'>**[1]**</a> “The cross-section of volatility and expected returns” The Journal of Finance. Ang, A., Hodrick, R. J., Xing, Y., & Zhang, X. (2006).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWResidualVolatility
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = EWResidualVolatility()
>>> residual_volatility = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EWResidualVolatility.fit_transform"></a>

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

Compute exponentially weighted CAPM residual volatility.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **residual_volatility** *ndarray of shape (n_observations, n_assets)*
  : Residual return volatility for each observation and asset.

<a id="skfolio.descriptor.EWResidualVolatility.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.descriptor.EWResidualVolatility.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.descriptor.EWResidualVolatility.partial_fit_transform"></a>

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

Update EWMA state and return residual volatility for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **residual_volatility** *ndarray of shape (n_observations, n_assets)*
  : Residual return volatility for each observation and asset.

<a id="skfolio.descriptor.EWResidualVolatility.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.

# generated/skfolio.descriptor.EWShareTurnover.html.md

<a id="skfolio-descriptor-ewshareturnover"></a>

# skfolio.descriptor.EWShareTurnover

<a id="skfolio.descriptor.EWShareTurnover"></a>

### *class* skfolio.descriptor.EWShareTurnover(half_life=21.0, min_periods=None)

Exponentially weighted share turnover descriptor.

Computes an EWMA of per-observation share turnover:

$$
\[
\begin{aligned}
\text{turnover\_raw}(t)
    &= \frac{\text{adj\_volume}(t)}
            {\text{adj\_shares\_outstanding}(t)} \\[0.75em]
\text{turnover}(t)
    &= \lambda \cdot \text{turnover}(t-1)
       + (1 - \lambda) \cdot \text{turnover\_raw}(t)
\end{aligned}
\]
$$

where $\lambda = \exp(-\ln(2) / \text{half\_life})$ is the EWMA decay factor.

Share turnover measures trading intensity as the fraction of shares outstanding that
changes hands over each observation period. Lower turnover indicates weaker trading
activity and lower liquidity, making trades more likely to incur price impact.
Low-turnover stocks are often associated with higher expected returns, commonly
interpreted as an illiquidity premium [[1]](https://skfolio.org/generated/skfolio.descriptor.EWShareTurnover.html.md#r890ece2b5cbc-1).

EWMA smoothing is preferred over a fixed rolling average because turnover can spike
around earnings, index rebalances or news events. EWMA dampens these spikes
gradually, producing more stable factor exposures.

* **Parameters:**
  **half_life** *float, default=21.0*
  : EWMA half-life in observations. Controls how fast old turnover values decay.
    With daily data, common choices are:
    - `half_life=21`: ~1 month
    - `half_life=63`: ~3 months
    - `half_life=252`: ~1 year

  **min_periods** *int, optional*
  : Minimum number of valid turnover observations required for each asset. Until an
    asset reaches this count, its output is NaN. This warm-up period avoids
    exposing early EWMA values before the turnover estimate has sufficiently
    converged from its zero initialization. If `None`, defaults to
    $\lceil\text{half\_life}\rceil$, with a minimum of 1.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **turnover_** *ndarray of shape (n_assets,)*
  : Last EWMA-smoothed share turnover value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWShareTurnover.html.md#skfolio.descriptor.EWShareTurnover.fit_transform)(X[, y])         | Compute exponentially weighted share turnover.            |
|--------------------------------------------------------------------------------|-----------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EWShareTurnover.html.md#skfolio.descriptor.EWShareTurnover.get_metadata_routing)()        | Get metadata routing of this object.                      |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EWShareTurnover.html.md#skfolio.descriptor.EWShareTurnover.get_params)([deep])            | Get parameters for this estimator.                        |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWShareTurnover.html.md#skfolio.descriptor.EWShareTurnover.partial_fit_transform)(X[, y]) | Update state and return smoothed turnover for this batch. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EWShareTurnover.html.md#skfolio.descriptor.EWShareTurnover.set_params)(\*\*params)        | Set the parameters of this estimator.                     |

#### SEE ALSO
[`EWAmihudIlliquidity`](https://skfolio.org/generated/skfolio.descriptor.EWAmihudIlliquidity.html.md#skfolio.descriptor.EWAmihudIlliquidity)
: EWMA price-impact illiquidity measure.

### Notes

`adj_shares_outstanding` is common shares outstanding. Both `adj_volume` and
`adj_shares_outstanding` must use the same split-adjustment basis.

NaNs are allowed as missing observations. Non-missing `adj_volume` values must be
finite and non-negative. Non-missing `adj_shares_outstanding` values must be finite
and strictly positive.

The EWMA state is updated only for valid observations. NaN in `adj_volume` or
`adj_shares_outstanding` holds the EWMA state and does not increment the
valid-observation count. Zero `adj_volume` is valid and produces zero turnover.

The `active_mask` property of the [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)
distinguishes holidays from delistings.

### References

* <a id='r890ece2b5cbc-1'>**[1]**</a> “Liquidity and stock returns: an alternative test” Journal of Financial Markets. Datar, V. T., Naik, N. Y., & Radcliffe, R. (1998).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWShareTurnover
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 1-month effective window (default)
>>> descriptor = EWShareTurnover()
>>> turnover = descriptor.fit_transform(X)
>>>
>>> # 3-month effective window
>>> descriptor = EWShareTurnover(half_life=63)
>>> turnover_3m = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EWShareTurnover.fit_transform"></a>

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

Compute exponentially weighted share turnover.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `adj_volume` and `adj_shares_outstanding`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **turnover** *ndarray of shape (n_observations, n_assets)*
  : EWMA-smoothed share turnover for each observation and asset.

<a id="skfolio.descriptor.EWShareTurnover.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.descriptor.EWShareTurnover.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.descriptor.EWShareTurnover.partial_fit_transform"></a>

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

Update state and return smoothed turnover for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `"adj_volume"` and
    `"adj_shares_outstanding"`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **turnover** *ndarray of shape (n_observations, n_assets)*
  : EWMA-smoothed share turnover for each observation and asset.

<a id="skfolio.descriptor.EWShareTurnover.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.

# generated/skfolio.descriptor.EWVolatility.html.md

<a id="skfolio-descriptor-ewvolatility"></a>

# skfolio.descriptor.EWVolatility

<a id="skfolio.descriptor.EWVolatility"></a>

### *class* skfolio.descriptor.EWVolatility(half_life=40.0, min_periods=None)

Exponentially weighted volatility descriptor.

Computes return volatility with an EWMA variance estimate:

$$
\[
\begin{aligned}
S_i(t)
    &= \lambda \cdot S_i(t-1) + (1 - \lambda) \cdot r_i(t)^2 \\[0.75em]
\text{output}_i(t)
    &= \sqrt{\frac{S_i(t)}{1 - \lambda^{n_i(t)}}}
\end{aligned}
\]
$$

where $\lambda = \exp(-\ln(2)/\text{half\_life})$ and $n_i(t)$ is the
number of valid returns for asset $i$.

This descriptor uses raw returns, so the estimate includes both systematic and
idiosyncratic risk. Use [`EWResidualVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility) to remove market exposure
first.

* **Parameters:**
  **half_life** *float, default=40.0*
  : EWMA half-life in observations.

  **min_periods** *int, optional*
  : Minimum number of valid returns required for each asset. Until an asset
    reaches this count, its output is NaN. This warm-up period avoids exposing
    early EWMA values before the volatility estimate has sufficiently converged
    from its zero initialization. If `None`, defaults to
    $\lceil\text{half\_life}\rceil$, with a minimum of 1.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **volatility_** *ndarray of shape (n_assets,)*
  : Last computed EWMA volatility. Contains NaN for inactive assets and assets
    that have not reached `min_periods` valid returns.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWVolatility.html.md#skfolio.descriptor.EWVolatility.fit_transform)(X[, y])         | Compute exponentially weighted return volatility.       |
|--------------------------------------------------------------------------------|---------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EWVolatility.html.md#skfolio.descriptor.EWVolatility.get_metadata_routing)()        | Get metadata routing of this object.                    |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EWVolatility.html.md#skfolio.descriptor.EWVolatility.get_params)([deep])            | Get parameters for this estimator.                      |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EWVolatility.html.md#skfolio.descriptor.EWVolatility.partial_fit_transform)(X[, y]) | Update EWMA state and return volatility for this batch. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EWVolatility.html.md#skfolio.descriptor.EWVolatility.set_params)(\*\*params)        | Set the parameters of this estimator.                   |

#### SEE ALSO
[`EWDownsideVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideVolatility.html.md#skfolio.descriptor.EWDownsideVolatility)
: Downside variant using semi-deviation of returns.

[`EWResidualVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility)
: CAPM residual volatility (market exposure removed).

### Notes

The EWMA variance accumulator is initialized to zero and bias-corrected at output
time using each asset’s valid observation count, matching
[`EWVariance`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance).

NaNs are treated as missing observations. Active assets with missing returns keep
their previous EWMA state and inactive assets output NaN and restart their warm-up
period when they become active again. Non-missing returns must be finite.

The variance is computed assuming centered returns (no demeaning), which is the
standard convention for EWMA variance estimation in cross-sectional factor models.

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWVolatility
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = EWVolatility()
>>> volatility = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EWVolatility.fit_transform"></a>

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

Compute exponentially weighted return volatility.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **volatility** *ndarray of shape (n_observations, n_assets)*
  : EWMA volatility (or downside volatility) for each observation and asset.

<a id="skfolio.descriptor.EWVolatility.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.descriptor.EWVolatility.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.descriptor.EWVolatility.partial_fit_transform"></a>

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

Update EWMA state and return volatility for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **volatility** *ndarray of shape (n_observations, n_assets)*
  : EWMA volatility (or downside volatility) for each observation and asset.

<a id="skfolio.descriptor.EWVolatility.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.

# generated/skfolio.descriptor.EarningsChangeToPrice.html.md

<a id="skfolio-descriptor-earningschangetoprice"></a>

# skfolio.descriptor.EarningsChangeToPrice

<a id="skfolio.descriptor.EarningsChangeToPrice"></a>

### *class* skfolio.descriptor.EarningsChangeToPrice(lag=252)

Lagged earnings change divided by current market capitalization.

Computes the change in trailing twelve-month net income over a fixed lag, divided by
current market capitalization:

$$
\text{earnings\_change\_to\_price}(t) =
\frac{\text{net\_income\_ttm}(t) - \text{net\_income\_ttm}(t - \text{lag})}
     {\text{market\_cap}(t)}
$$

The first `lag` observations are NaN because no lagged history is available.

NaNs are allowed as missing observations and propagate when the current, lagged or
market-cap value is missing. Non-missing `net_income_ttm` values must be finite.
Non-missing `market_cap` values must be finite and strictly positive.

This descriptor captures earnings momentum: whether a firm’s profitability is
improving or deteriorating relative to its market value [[1]](https://skfolio.org/generated/skfolio.descriptor.EarningsChangeToPrice.html.md#r342023be1f9e-1). A positive value
indicates earnings improvement and a negative value indicates deterioration.

Unlike [`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate), which computes `x(t) / x(t-lag) - 1`, this formulation
is well-defined when earnings are negative. A standard growth rate with a negative
base produces sign-inverted rankings, making it unsuitable for earnings. By
normalizing the level change with market capitalization, the sign of the output
reflects the direction of change.

This is a convenience subclass of [`ChangeToScale`](https://skfolio.org/generated/skfolio.descriptor.ChangeToScale.html.md#skfolio.descriptor.ChangeToScale) with
`field="net_income_ttm"` and `scale_field="market_cap"`.

This descriptor uses aggregate quantities (net income and market capitalization).
The per-share equivalent is:

$$
\frac{\text{eps\_ttm}(t) - \text{eps\_ttm}(t - \text{lag})}
     {\text{adj\_close}(t)}
$$

The aggregate form is preferred for consistency with the other value descriptors
and to avoid split-adjustment mismatches.

* **Parameters:**
  **lag** *int, default=252*
  : Number of observations to look back. The interpretation depends on the data
    frequency: `lag=12` means 1 year for monthly data, `lag=252` for daily data,
    `lag=4` for quarterly data.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **change_to_scale_** *ndarray of shape (n_assets,)*
  : Last earnings change to price value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EarningsChangeToPrice.html.md#skfolio.descriptor.EarningsChangeToPrice.fit_transform)(X[, y])         | Compute changes in level normalized by current scale.   |
|--------------------------------------------------------------------------------|---------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EarningsChangeToPrice.html.md#skfolio.descriptor.EarningsChangeToPrice.get_metadata_routing)()        | Get metadata routing of this object.                    |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EarningsChangeToPrice.html.md#skfolio.descriptor.EarningsChangeToPrice.get_params)([deep])            | Get parameters for this estimator.                      |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EarningsChangeToPrice.html.md#skfolio.descriptor.EarningsChangeToPrice.partial_fit_transform)(X[, y]) | Compute changes in level normalized by current scale.   |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EarningsChangeToPrice.html.md#skfolio.descriptor.EarningsChangeToPrice.set_params)(\*\*params)        | Set the parameters of this estimator.                   |

#### SEE ALSO
[`ChangeToScale`](https://skfolio.org/generated/skfolio.descriptor.ChangeToScale.html.md#skfolio.descriptor.ChangeToScale)
: Generic change-to-scale descriptor.

[`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate)
: Simple growth rate for positive-definite characteristics.

[`EarningsToPrice`](https://skfolio.org/generated/skfolio.descriptor.EarningsToPrice.html.md#skfolio.descriptor.EarningsToPrice)
: Level of trailing earnings to price (value signal).

### References

* <a id='r342023be1f9e-1'>**[1]**</a> Fama, E. F., & French, K. R. (2006). “Profitability, investment and average returns.” *Journal of Financial Economics*, 82(3), 491-518.

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EarningsChangeToPrice
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = EarningsChangeToPrice(lag=252)
>>> earnings_change_to_price = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EarningsChangeToPrice.fit_transform"></a>

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

Compute changes in level normalized by current scale.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` and `scale_field` characteristics
    configured at construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **change_to_scale** *ndarray of shape (n_observations, n_assets)*
  : Change in `field` over the lag window, divided by current `scale_field`
    for each observation and asset.

<a id="skfolio.descriptor.EarningsChangeToPrice.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.descriptor.EarningsChangeToPrice.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.descriptor.EarningsChangeToPrice.partial_fit_transform"></a>

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

Compute changes in level normalized by current scale.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` and `scale_field` fields configured at
    construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **change_to_scale** *ndarray of shape (n_observations, n_assets)*
  : Change in `field` over the lag window, divided by current `scale_field`
    for each observation and asset.

<a id="skfolio.descriptor.EarningsChangeToPrice.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.

# generated/skfolio.descriptor.EarningsToPrice.html.md

<a id="skfolio-descriptor-earningstoprice"></a>

# skfolio.descriptor.EarningsToPrice

<a id="skfolio.descriptor.EarningsToPrice"></a>

### *class* skfolio.descriptor.EarningsToPrice

Earnings-to-price ratio descriptor.

Computes the ratio of trailing twelve-month net income to market capitalization:

$$
\text{earnings\_to\_price}(t) =
\frac{\text{net\_income\_ttm}(t)}{\text{market\_cap}(t)}
$$

This is the inverse of the price-to-earnings (P/E) ratio and measures how much
profit a firm generates per unit of market value. A high ratio identifies firms with
strong current profitability relative to their price [[1]](https://skfolio.org/generated/skfolio.descriptor.EarningsToPrice.html.md#r8379f77a43fa-1). Unlike [`BookToPrice`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice),
which is based on the balance sheet, this descriptor is based on the income
statement, capturing a distinct dimension of value.

This descriptor can be negative for loss-making firms, which is economically
meaningful (unlike P/E, which becomes uninterpretable for negative earnings).

`net_income_ttm` should represent net income available to common shareholders when
the data source distinguishes common and preferred claims. This is consistent with
`market_cap`, which reflects common equity.

This descriptor uses aggregate quantities (total net income divided by total market
capitalization) rather than per-share quantities (earnings per share divided by
price). The two are mathematically equivalent when EPS and price use the same
split-adjustment basis:

$$
\frac{\text{net\_income\_ttm}}{\text{market\_cap}}
= \frac{\text{eps\_ttm}}{\text{price}}
$$

The aggregate form is preferred because it avoids subtle split-adjustment mismatches
between numerator and denominator. Aggregate fundamentals are the primary form from
data providers. Per-share quantities are derived from them.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EarningsToPrice.html.md#skfolio.descriptor.EarningsToPrice.fit_transform)(X[, y])         | Compute trailing earnings-to-price ratios.     |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EarningsToPrice.html.md#skfolio.descriptor.EarningsToPrice.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EarningsToPrice.html.md#skfolio.descriptor.EarningsToPrice.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EarningsToPrice.html.md#skfolio.descriptor.EarningsToPrice.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EarningsToPrice.html.md#skfolio.descriptor.EarningsToPrice.set_params)(\*\*params)        | Set the parameters of this estimator.          |

### References

* <a id='r8379f77a43fa-1'>**[1]**</a> “Investment performance of common stocks in relation to their price-earnings ratios: A test of the efficient market hypothesis” The Journal of Finance. Basu, S. (1977).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EarningsToPrice
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = EarningsToPrice()
>>> earnings_to_price = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EarningsToPrice.fit_transform"></a>

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

Compute trailing earnings-to-price ratios.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `net_income_ttm` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **earnings_to_price** *ndarray of shape (n_observations, n_assets)*
  : Earnings-to-price ratio for each observation and asset.

<a id="skfolio.descriptor.EarningsToPrice.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.descriptor.EarningsToPrice.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.descriptor.EarningsToPrice.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.EarningsToPrice.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.

# generated/skfolio.descriptor.EbitdaToEnterpriseValue.html.md

<a id="skfolio-descriptor-ebitdatoenterprisevalue"></a>

# skfolio.descriptor.EbitdaToEnterpriseValue

<a id="skfolio.descriptor.EbitdaToEnterpriseValue"></a>

### *class* skfolio.descriptor.EbitdaToEnterpriseValue

EBITDA-to-enterprise-value ratio descriptor.

Computes the ratio of trailing twelve-month EBITDA to enterprise value:

$$
\text{ebitda\_to\_enterprise\_value}(t) =
\frac{\text{ebitda\_ttm}(t)}{\text{enterprise\_value}(t)}
$$

Enterprise value adjusts for capital structure by adding debt and subtracting cash
and equivalents from market capitalization:

$$
EV = \text{market\_cap} + \text{total\_debt} - \text{cash\_and\_equivalents}
$$

EBITDA measures operating profitability before financing, taxes and non-cash
charges. A high ratio identifies firms generating strong operating income relative
to their total firm value, regardless of how they are financed. The corresponding
enterprise multiple has been studied as a predictor of average stock returns [[1]](https://skfolio.org/generated/skfolio.descriptor.EbitdaToEnterpriseValue.html.md#rf7da3061f712-1).

This is the inverse of the conventional EV/EBITDA multiple. It provides a valuation
measure that is comparable across firms with different leverage, unlike price-based
ratios which only reflect equity value.

If `enterprise_value` is not available directly from your data provider, it can be
computed as:

$$
\text{EV} = \text{market\_cap} + \text{total\_debt}
           - \text{cash\_and\_equivalents}
$$

Non-missing `enterprise_value` values must be finite. Observations with
`enterprise_value <= 0` are masked to NaN because the valuation yield is not
economically interpretable.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EbitdaToEnterpriseValue.html.md#skfolio.descriptor.EbitdaToEnterpriseValue.fit_transform)(X[, y])         | Compute EBITDA-to-enterprise-value ratios.     |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.EbitdaToEnterpriseValue.html.md#skfolio.descriptor.EbitdaToEnterpriseValue.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.EbitdaToEnterpriseValue.html.md#skfolio.descriptor.EbitdaToEnterpriseValue.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.EbitdaToEnterpriseValue.html.md#skfolio.descriptor.EbitdaToEnterpriseValue.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.EbitdaToEnterpriseValue.html.md#skfolio.descriptor.EbitdaToEnterpriseValue.set_params)(\*\*params)        | Set the parameters of this estimator.          |

### References

* <a id='rf7da3061f712-1'>**[1]**</a> “New evidence on the relation between the enterprise multiple and average stock returns” Journal of Financial and Quantitative Analysis. Loughran, T., & Wellman, J. W. (2011).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EbitdaToEnterpriseValue
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = EbitdaToEnterpriseValue()
>>> ebitda_to_enterprise_value = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.EbitdaToEnterpriseValue.fit_transform"></a>

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

Compute EBITDA-to-enterprise-value ratios.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `ebitda_ttm` and `enterprise_value`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **ebitda_to_enterprise_value** *ndarray of shape (n_observations, n_assets)*
  : EBITDA divided by enterprise value for each observation and asset.

<a id="skfolio.descriptor.EbitdaToEnterpriseValue.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.descriptor.EbitdaToEnterpriseValue.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.descriptor.EbitdaToEnterpriseValue.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.EbitdaToEnterpriseValue.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.

# generated/skfolio.descriptor.ForwardDividendToPrice.html.md

<a id="skfolio-descriptor-forwarddividendtoprice"></a>

# skfolio.descriptor.ForwardDividendToPrice

<a id="skfolio.descriptor.ForwardDividendToPrice"></a>

### *class* skfolio.descriptor.ForwardDividendToPrice

Forward dividend-to-price ratio descriptor.

Computes the ratio of consensus forward twelve-month dividend per share to
split-adjusted close price:

$$
\text{forward\_dividend\_to\_price}(t) =
\frac{\text{dps\_ntm}(t)}{\text{adj\_close}(t)}
$$

Forward dividend-to-price captures the expected income yield based on analyst
consensus forecasts. Because it incorporates forward-looking estimates rather than
trailing accounting data, it reacts more quickly to dividend initiations, cuts or
policy changes. A high ratio identifies firms where analysts expect generous payouts
relative to the current price.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ForwardDividendToPrice.html.md#skfolio.descriptor.ForwardDividendToPrice.fit_transform)(X[, y])         | Compute forward dividend-to-price ratios.      |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.ForwardDividendToPrice.html.md#skfolio.descriptor.ForwardDividendToPrice.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.ForwardDividendToPrice.html.md#skfolio.descriptor.ForwardDividendToPrice.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ForwardDividendToPrice.html.md#skfolio.descriptor.ForwardDividendToPrice.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.ForwardDividendToPrice.html.md#skfolio.descriptor.ForwardDividendToPrice.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`DividendToPrice`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice)
: Trailing (historical) dividend yield.

### Notes

Unlike `DividendToPrice`, which uses aggregate fundamentals divided by `market_cap`,
this descriptor uses per-share quantities (`dps_ntm / adj_close`). Consensus
estimates from data providers are typically delivered as per-share forecasts, making
per-share the primary form. `dps_ntm` should use the same split-adjustment basis
as `adj_close`.

The aggregate equivalent is:

$$
\frac{\text{dps\_ntm}}{\text{adj\_close}}
= \frac{\text{dps\_ntm} \times \text{shares\_out}}
      {\text{adj\_close} \times \text{shares\_out}}
= \frac{\text{forward\_dividends\_ntm}}{\text{market\_cap}}
$$

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import ForwardDividendToPrice
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = ForwardDividendToPrice()
>>> forward_dividend_to_price = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.ForwardDividendToPrice.fit_transform"></a>

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

Compute forward dividend-to-price ratios.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `dps_ntm` and `adj_close`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **forward_dividend_to_price** *ndarray of shape (n_observations, n_assets)*
  : Forward dividend-to-price ratio for each observation and asset.

<a id="skfolio.descriptor.ForwardDividendToPrice.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.descriptor.ForwardDividendToPrice.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.descriptor.ForwardDividendToPrice.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.ForwardDividendToPrice.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.

# generated/skfolio.descriptor.ForwardEarningsToPrice.html.md

<a id="skfolio-descriptor-forwardearningstoprice"></a>

# skfolio.descriptor.ForwardEarningsToPrice

<a id="skfolio.descriptor.ForwardEarningsToPrice"></a>

### *class* skfolio.descriptor.ForwardEarningsToPrice

Forward earnings-to-price ratio descriptor.

Computes the ratio of consensus NTM earnings per share to split-adjusted close
price:

$$
\text{forward\_earnings\_to\_price}(t) =
\frac{\text{eps\_ntm}(t)}{\text{adj\_close}(t)}
$$

Forward earnings-to-price reflects consensus expectations of future profitability
relative to the current price [[1]](https://skfolio.org/generated/skfolio.descriptor.ForwardEarningsToPrice.html.md#r3dbaa75bd164-1). Because it incorporates analyst forecasts rather
than trailing accounting data, it captures forward-looking value and is less
affected by stale or one-off items in historical earnings. A high ratio identifies
firms expected to generate strong earnings relative to their price.

Unlike the other value descriptors which use aggregate fundamentals divided by
`market_cap`, this descriptor uses per-share quantities (`eps_ntm / adj_close`).
Consensus estimates from data providers are delivered as per-share forecasts,
making per-share the primary form. `eps_ntm` should use the same split-adjustment
basis as `adj_close`.

The aggregate equivalent is:

$$
\frac{\text{eps\_ntm}}{\text{adj\_close}}
= \frac{\text{eps\_ntm} \times \text{shares\_out}}
      {\text{adj\_close} \times \text{shares\_out}}
= \frac{\text{earnings\_ntm}}{\text{market\_cap}}
$$

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ForwardEarningsToPrice.html.md#skfolio.descriptor.ForwardEarningsToPrice.fit_transform)(X[, y])         | Compute forward earnings-to-price ratios.      |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.ForwardEarningsToPrice.html.md#skfolio.descriptor.ForwardEarningsToPrice.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.ForwardEarningsToPrice.html.md#skfolio.descriptor.ForwardEarningsToPrice.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ForwardEarningsToPrice.html.md#skfolio.descriptor.ForwardEarningsToPrice.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.ForwardEarningsToPrice.html.md#skfolio.descriptor.ForwardEarningsToPrice.set_params)(\*\*params)        | Set the parameters of this estimator.          |

### References

* <a id='r3dbaa75bd164-1'>**[1]**</a> “Expectations and share prices” Management Science. Elton, E. J., Gruber, M. J., & Gultekin, M. (1981).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import ForwardEarningsToPrice
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = ForwardEarningsToPrice()
>>> forward_earnings_to_price = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.ForwardEarningsToPrice.fit_transform"></a>

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

Compute forward earnings-to-price ratios.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `eps_ntm` and `adj_close`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **forward_earnings_to_price** *ndarray of shape (n_observations, n_assets)*
  : Forward earnings-to-price ratio for each observation and asset.

<a id="skfolio.descriptor.ForwardEarningsToPrice.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.descriptor.ForwardEarningsToPrice.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.descriptor.ForwardEarningsToPrice.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.ForwardEarningsToPrice.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.

# generated/skfolio.descriptor.GrossMargin.html.md

<a id="skfolio-descriptor-grossmargin"></a>

# skfolio.descriptor.GrossMargin

<a id="skfolio.descriptor.GrossMargin"></a>

### *class* skfolio.descriptor.GrossMargin

Gross margin descriptor.

Computes the ratio of gross profit to sales:

$$
\text{gross\_margin}(t) =
\frac{\text{sales\_ttm}(t) - \text{cost\_of\_revenue\_ttm}(t)}
     {\text{sales\_ttm}(t)}
$$

Gross margin captures pricing power and unit economics: the fraction of each dollar
of revenue retained after direct production costs. A high and stable gross margin
may reflect strong competitive positioning, brand value or cost advantages.

While [`GrossProfitability`](https://skfolio.org/generated/skfolio.descriptor.GrossProfitability.html.md#skfolio.descriptor.GrossProfitability) normalizes by total assets [[1]](https://skfolio.org/generated/skfolio.descriptor.GrossMargin.html.md#r84b81a5b68e4-1), gross margin
normalizes by sales. The two descriptors capture related but distinct aspects of
firm quality.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.GrossMargin.html.md#skfolio.descriptor.GrossMargin.fit_transform)(X[, y])         | Compute gross margin.                          |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.GrossMargin.html.md#skfolio.descriptor.GrossMargin.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.GrossMargin.html.md#skfolio.descriptor.GrossMargin.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.GrossMargin.html.md#skfolio.descriptor.GrossMargin.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.GrossMargin.html.md#skfolio.descriptor.GrossMargin.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`GrossProfitability`](https://skfolio.org/generated/skfolio.descriptor.GrossProfitability.html.md#skfolio.descriptor.GrossProfitability)
: Gross profit normalized by total assets.

### Notes

`cost_of_revenue_ttm` (trailing twelve months) should be reported as a positive
number representing the cost. The descriptor computes
`sales_ttm - cost_of_revenue_ttm` to obtain gross profit. Observations with
`sales_ttm <= 0` are masked to NaN because the margin is not economically
interpretable.

### References

* <a id='r84b81a5b68e4-1'>**[1]**</a> “The other side of value: The gross profitability premium” Journal of Financial Economics. Novy-Marx, R. (2013).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import GrossMargin
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = GrossMargin()
>>> gross_margin = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.GrossMargin.fit_transform"></a>

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

Compute gross margin.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `sales_ttm` and `cost_of_revenue_ttm`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **gross_margin** *ndarray of shape (n_observations, n_assets)*
  : Gross profit divided by sales for each observation and asset.

<a id="skfolio.descriptor.GrossMargin.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.descriptor.GrossMargin.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.descriptor.GrossMargin.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.GrossMargin.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.

# generated/skfolio.descriptor.GrossProfitability.html.md

<a id="skfolio-descriptor-grossprofitability"></a>

# skfolio.descriptor.GrossProfitability

<a id="skfolio.descriptor.GrossProfitability"></a>

### *class* skfolio.descriptor.GrossProfitability

Gross profitability descriptor.

Computes the ratio of gross profit to total assets:

$$
\text{gross\_profitability}(t) =
\frac{\text{sales\_ttm}(t) - \text{cost\_of\_revenue\_ttm}(t)}
     {\text{total\_assets}(t)}
$$

Gross profitability captures a firm’s ability to generate profit from its asset base
before operating expenses, interest and taxes. It is less affected by financing,
tax and accrual accounting choices than net income-based ratios.

Profitable firms typically earn significantly higher returns than unprofitable ones [[1]](https://skfolio.org/generated/skfolio.descriptor.GrossProfitability.html.md#r7a6eadba8c21-1).

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.GrossProfitability.html.md#skfolio.descriptor.GrossProfitability.fit_transform)(X[, y])         | Compute gross profitability.                   |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.GrossProfitability.html.md#skfolio.descriptor.GrossProfitability.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.GrossProfitability.html.md#skfolio.descriptor.GrossProfitability.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.GrossProfitability.html.md#skfolio.descriptor.GrossProfitability.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.GrossProfitability.html.md#skfolio.descriptor.GrossProfitability.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`GrossMargin`](https://skfolio.org/generated/skfolio.descriptor.GrossMargin.html.md#skfolio.descriptor.GrossMargin)
: Gross profit normalized by sales.

[`ReturnOnAssets`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets)
: Net income normalized by total assets.

### Notes

`cost_of_revenue_ttm` (trailing twelve months) should be reported as a positive
number representing the cost. The descriptor computes
`sales_ttm - cost_of_revenue_ttm` to obtain gross profit.

### References

* <a id='r7a6eadba8c21-1'>**[1]**</a> “The other side of value: The gross profitability premium” Journal of Financial Economics. Novy-Marx, R. (2013).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import GrossProfitability
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = GrossProfitability()
>>> gross_profitability = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.GrossProfitability.fit_transform"></a>

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

Compute gross profitability.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `sales_ttm`, `cost_of_revenue_ttm`, and
    `total_assets`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **gross_profitability** *ndarray of shape (n_observations, n_assets)*
  : Gross profit divided by total assets for each observation and asset.

<a id="skfolio.descriptor.GrossProfitability.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.descriptor.GrossProfitability.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.descriptor.GrossProfitability.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.GrossProfitability.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.

# generated/skfolio.descriptor.GrowthRate.html.md

<a id="skfolio-descriptor-growthrate"></a>

# skfolio.descriptor.GrowthRate

<a id="skfolio.descriptor.GrowthRate"></a>

### *class* skfolio.descriptor.GrowthRate(field, lag)

Period-over-period growth rate descriptor.

Computes the growth rate of a characteristic over a fixed lag:

$$
\text{growth}(t) = \frac{x(t)}{x(t - \text{lag})} - 1
$$

The first `lag` observations are NaN because no lagged history is available.

This descriptor is intended for non-negative fields such as sales, total assets,
capital expenditure or shares outstanding. NaNs are allowed as missing observations
and propagate when either the current or lagged value is missing. It raises a
`ValueError` for negative or infinite values. Zero values are allowed and a zero
lagged value makes the growth rate undefined and produces NaN.

For fields that can be negative, such as net income or EPS, use
[`EarningsChangeToPrice`](https://skfolio.org/generated/skfolio.descriptor.EarningsChangeToPrice.html.md#skfolio.descriptor.EarningsChangeToPrice) instead. It
normalizes the level change by market capitalization and does not rely on a positive
base value.

This is the standard period-over-period growth rate used in anomaly and
investment-style factors. For trailing-twelve-month (TTM) fields with a one-year
lag, the two observations cover non-overlapping fiscal content, so intermediate
quarterly filings contribute to the comparison.

Other growth definitions exist, including regression-based multi-year trend growth
and compound annual growth rate (CAGR). For positive values, CAGR is monotonic in
simple growth and gives the same cross-sectional ranks.

Common investment-factor descriptors:

* Asset growth (`field="total_assets"`): year-over-year balance-sheet expansion.
  Firms with rapid asset growth tend to earn lower future returns [[1]](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#r18d27a2efc06-1).
* Issuance growth (`field="adj_shares_outstanding"`): year-over-year change in
  split-adjusted shares outstanding. Net share issuance is a negative predictor of
  future returns, independent of size, value and momentum [[2]](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#r18d27a2efc06-2).
* Capital expenditure growth (`field="capex_ttm"`): year-over-year change in
  trailing capital expenditure. Firms with large capex increases subsequently
  underperform, consistent with investor under-reaction to overinvestment [[3]](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#r18d27a2efc06-3).

* **Parameters:**
  **field** *str*
  : Field name in the [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) to compute growth
    for. Non-missing values must be finite and non-negative.

  **lag** *int*
  : Number of observations to look back. The interpretation depends on the data
    frequency: `lag=12` means 1 year for monthly data, `lag=252` for daily data,
    `lag=4` for quarterly data.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **growth_rate_** *ndarray of shape (n_assets,)*
  : Last growth rate value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate.fit_transform)(X[, y])         | Compute simple growth rates of the configured field.   |
|--------------------------------------------------------------------------------|--------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate.get_metadata_routing)()        | Get metadata routing of this object.                   |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate.get_params)([deep])            | Get parameters for this estimator.                     |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate.partial_fit_transform)(X[, y]) | Compute simple growth rates of the configured field.   |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate.set_params)(\*\*params)        | Set the parameters of this estimator.                  |

### References

* <a id='r18d27a2efc06-1'>**[1]**</a> “Asset growth and the cross-section of stock returns” The Journal of Finance. Cooper, M. J., Gulen, H., & Schill, M. J. (2008).
* <a id='r18d27a2efc06-2'>**[2]**</a> “Share issuance and cross-sectional returns” The Journal of Finance. Pontiff, J., & Woodgate, A. (2008).
* <a id='r18d27a2efc06-3'>**[3]**</a> “Capital investments and stock returns” Journal of Financial and Quantitative Analysis. Titman, Wei & Xie (2004).

### Examples

```pycon
>>> from skfolio.descriptor import GrowthRate
>>>
>>> # 1-year sales growth
>>> sales_growth = GrowthRate("sales_ttm", lag=252)
>>>
>>> # 1-year asset growth
>>> asset_growth = GrowthRate("total_assets", lag=252)
>>>
>>> # 1-year share issuance growth
>>> issuance_growth = GrowthRate("adj_shares_outstanding", lag=252)
```

<a id="skfolio.descriptor.GrowthRate.fit_transform"></a>

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

Compute simple growth rates of the configured field.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` characteristic configured at
    construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **growth_rate** *ndarray of shape (n_observations, n_assets)*
  : Period-over-period growth rate for each observation and asset.

<a id="skfolio.descriptor.GrowthRate.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.descriptor.GrowthRate.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.descriptor.GrowthRate.partial_fit_transform"></a>

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

Compute simple growth rates of the configured field.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` characteristic configured at construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **growth_rate** *ndarray of shape (n_observations, n_assets)*
  : Period-over-period growth rate for each observation and asset.

<a id="skfolio.descriptor.GrowthRate.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.

# generated/skfolio.descriptor.IssuanceGrowthRate.html.md

<a id="skfolio-descriptor-issuancegrowthrate"></a>

# skfolio.descriptor.IssuanceGrowthRate

<a id="skfolio.descriptor.IssuanceGrowthRate"></a>

### *class* skfolio.descriptor.IssuanceGrowthRate(lag=252)

Issuance growth rate descriptor.

Computes period-over-period growth in split-adjusted shares outstanding:

$$
\text{issuance\_growth}(t)
= \frac{\text{adj\_shares\_outstanding}(t)}
       {\text{adj\_shares\_outstanding}(t - \text{lag})} - 1
$$

The first `lag` observations are NaN because no lagged history is available.

`adj_shares_outstanding` must contain non-missing finite non-negative values. NaNs
are allowed as missing observations and propagate when either the current or lagged
value is missing. Zero values are allowed and a zero lagged value makes the growth
rate undefined and produces NaN.

Positive issuance growth indicates an increase in split-adjusted shares outstanding.
Net share issuance is a negative predictor of future returns, independent of size,
value and momentum [[1]](https://skfolio.org/generated/skfolio.descriptor.IssuanceGrowthRate.html.md#rf18918d6d53e-1).

This is a convenience subclass of [`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate) with
`field="adj_shares_outstanding"`.

* **Parameters:**
  **lag** *int, default=252*
  : Number of observations to look back. The interpretation depends on the data
    frequency: `lag=12` means 1 year for monthly data, `lag=252` for daily data,
    `lag=4` for quarterly data.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **growth_rate_** *ndarray of shape (n_assets,)*
  : Last issuance growth value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.IssuanceGrowthRate.html.md#skfolio.descriptor.IssuanceGrowthRate.fit_transform)(X[, y])         | Compute simple growth rates of the configured field.   |
|--------------------------------------------------------------------------------|--------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.IssuanceGrowthRate.html.md#skfolio.descriptor.IssuanceGrowthRate.get_metadata_routing)()        | Get metadata routing of this object.                   |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.IssuanceGrowthRate.html.md#skfolio.descriptor.IssuanceGrowthRate.get_params)([deep])            | Get parameters for this estimator.                     |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.IssuanceGrowthRate.html.md#skfolio.descriptor.IssuanceGrowthRate.partial_fit_transform)(X[, y]) | Compute simple growth rates of the configured field.   |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.IssuanceGrowthRate.html.md#skfolio.descriptor.IssuanceGrowthRate.set_params)(\*\*params)        | Set the parameters of this estimator.                  |

#### SEE ALSO
[`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate)
: Generic period-over-period growth rate descriptor.

### References

* <a id='rf18918d6d53e-1'>**[1]**</a> “Share issuance and cross-sectional returns” The Journal of Finance. Pontiff, J., & Woodgate, A. (2008).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import IssuanceGrowthRate
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = IssuanceGrowthRate(lag=252)
>>> issuance_growth_rate = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.IssuanceGrowthRate.fit_transform"></a>

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

Compute simple growth rates of the configured field.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` characteristic configured at
    construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **growth_rate** *ndarray of shape (n_observations, n_assets)*
  : Period-over-period growth rate for each observation and asset.

<a id="skfolio.descriptor.IssuanceGrowthRate.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.descriptor.IssuanceGrowthRate.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.descriptor.IssuanceGrowthRate.partial_fit_transform"></a>

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

Compute simple growth rates of the configured field.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` characteristic configured at construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **growth_rate** *ndarray of shape (n_observations, n_assets)*
  : Period-over-period growth rate for each observation and asset.

<a id="skfolio.descriptor.IssuanceGrowthRate.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.

# generated/skfolio.descriptor.LogMarketCap.html.md

<a id="skfolio-descriptor-logmarketcap"></a>

# skfolio.descriptor.LogMarketCap

<a id="skfolio.descriptor.LogMarketCap"></a>

### *class* skfolio.descriptor.LogMarketCap

Log market capitalization descriptor.

Computes the natural logarithm of market capitalization:

$$
\text{log\_market\_cap}(t) = \ln(\text{market\_cap}(t))
$$

Log market capitalization is the standard size descriptor in equity factor models [[1]](https://skfolio.org/generated/skfolio.descriptor.LogMarketCap.html.md#rb7a26d7a46b8-1).
The logarithm reduces the right skew of market capitalization and produces a more
stable cross-sectional scale.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.LogMarketCap.html.md#skfolio.descriptor.LogMarketCap.fit_transform)(X[, y])         | Compute log market capitalization.             |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.LogMarketCap.html.md#skfolio.descriptor.LogMarketCap.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.LogMarketCap.html.md#skfolio.descriptor.LogMarketCap.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.LogMarketCap.html.md#skfolio.descriptor.LogMarketCap.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.LogMarketCap.html.md#skfolio.descriptor.LogMarketCap.set_params)(\*\*params)        | Set the parameters of this estimator.          |

### Notes

`market_cap` is the market value of common equity, computed as split-adjusted price
times common shares outstanding.

Non-missing `market_cap` values must be finite and strictly positive.

### References

* <a id='rb7a26d7a46b8-1'>**[1]**</a> “Common risk factors in the returns on stocks and bonds” Journal of Financial Economics. Fama, E. F., & French, K. R. (1993).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import LogMarketCap
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = LogMarketCap()
>>> log_market_cap = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.LogMarketCap.fit_transform"></a>

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

Compute log market capitalization.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **log_market_cap** *ndarray of shape (n_observations, n_assets)*
  : Log market capitalization for each observation and asset.

<a id="skfolio.descriptor.LogMarketCap.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.descriptor.LogMarketCap.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.descriptor.LogMarketCap.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.LogMarketCap.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.

# generated/skfolio.descriptor.MarketLeverage.html.md

<a id="skfolio-descriptor-marketleverage"></a>

# skfolio.descriptor.MarketLeverage

<a id="skfolio.descriptor.MarketLeverage"></a>

### *class* skfolio.descriptor.MarketLeverage

Market leverage descriptor.

Computes the proportion of total capital (at market value) financed by debt:

$$
\text{market\_leverage}(t) =
\frac{\text{total\_debt}(t)}
     {\text{total\_debt}(t) + \text{market\_cap}(t)}
$$

Market leverage blends accounting data (total debt) with market data (market
capitalization). Unlike [`BookLeverage`](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#skfolio.descriptor.BookLeverage), the denominator updates daily with
the stock price, making it more responsive to changes in the firm’s risk profile.
When a stock drops sharply, market leverage rises immediately, capturing the
increased financial risk before any accounting restatement [[1]](https://skfolio.org/generated/skfolio.descriptor.MarketLeverage.html.md#r96fb91817dfe-1).

NaNs are allowed as missing observations and propagate to the output. Non-missing
`total_debt` values must be finite. Non-missing `market_cap` values must be finite
and strictly positive.

When `total_debt` is non-negative and given that `market_cap` is non-negative by
construction, the ratio is bounded in $[0, 1)$. This makes it the most
numerically well-behaved of the leverage descriptors, requiring no special
treatment for negative-equity firms.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.MarketLeverage.html.md#skfolio.descriptor.MarketLeverage.fit_transform)(X[, y])         | Compute market leverage ratios.                |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.MarketLeverage.html.md#skfolio.descriptor.MarketLeverage.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.MarketLeverage.html.md#skfolio.descriptor.MarketLeverage.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.MarketLeverage.html.md#skfolio.descriptor.MarketLeverage.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.MarketLeverage.html.md#skfolio.descriptor.MarketLeverage.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`DebtToAssets`](https://skfolio.org/generated/skfolio.descriptor.DebtToAssets.html.md#skfolio.descriptor.DebtToAssets)
: Leverage relative to total assets.

[`BookLeverage`](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#skfolio.descriptor.BookLeverage)
: Leverage as a fraction of total book capital.

### References

* <a id='r96fb91817dfe-1'>**[1]**</a> “Capital structure decisions: which factors are reliably important?” Financial Management. Frank, M. Z., & Goyal, V. K. (2009).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import MarketLeverage
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = MarketLeverage()
>>> market_leverage = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.MarketLeverage.fit_transform"></a>

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

Compute market leverage ratios.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `total_debt` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **market_leverage** *ndarray of shape (n_observations, n_assets)*
  : Market leverage ratio for each observation and asset.

<a id="skfolio.descriptor.MarketLeverage.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.descriptor.MarketLeverage.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.descriptor.MarketLeverage.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.MarketLeverage.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.

# generated/skfolio.descriptor.MaxReturn.html.md

<a id="skfolio-descriptor-maxreturn"></a>

# skfolio.descriptor.MaxReturn

<a id="skfolio.descriptor.MaxReturn"></a>

### *class* skfolio.descriptor.MaxReturn(window=21)

Maximum return over a trailing window.

Computes the maximum return over the last `window` observations:

$$
\text{MAX}(t) = \max_{k \in [t-w+1,\, t]} \; r_k
$$

where $w$ is the `window` size. High values identify assets with recent
extreme positive returns, capturing lottery-like payoff that may attract speculative
demand.

The output is NaN until an asset has a full trailing window of active observations.
NaN returns are allowed as missing observations and ignored when computing the
maximum. If all returns in an active trailing window are missing, the output is NaN.
Non-missing `returns` values must be finite.

Stocks with high MAX are found to earn lower subsequent returns, consistent with
investor overpricing of lottery-like payoffs [[1]](https://skfolio.org/generated/skfolio.descriptor.MaxReturn.html.md#rad7917c3d156-1).

* **Parameters:**
  **window** *int, default=21*
  : Number of trailing observations for the rolling maximum. Must be
    greater than 1. The default of 21 corresponds to approximately one
    trading month, matching the original definition in [[1]](https://skfolio.org/generated/skfolio.descriptor.MaxReturn.html.md#rad7917c3d156-1).
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **max_return_** *ndarray of shape (n_assets,)*
  : Last maximum return value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.MaxReturn.html.md#skfolio.descriptor.MaxReturn.fit_transform)(X[, y])         | Compute rolling maximum returns over the configured window.   |
|--------------------------------------------------------------------------------|---------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.MaxReturn.html.md#skfolio.descriptor.MaxReturn.get_metadata_routing)()        | Get metadata routing of this object.                          |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.MaxReturn.html.md#skfolio.descriptor.MaxReturn.get_params)([deep])            | Get parameters for this estimator.                            |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.MaxReturn.html.md#skfolio.descriptor.MaxReturn.partial_fit_transform)(X[, y]) | Update state and return rolling max return for this batch.    |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.MaxReturn.html.md#skfolio.descriptor.MaxReturn.set_params)(\*\*params)        | Set the parameters of this estimator.                         |

### References

* <a id='rad7917c3d156-1'>**[1]**</a> “Maxing out: stocks as lotteries and the cross-section of expected returns” Journal of Financial Economics. Bali, Cakici & Whitelaw (2011).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import MaxReturn
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 1-month rolling max (default)
>>> descriptor = MaxReturn()
>>> max_ret = descriptor.fit_transform(X)
>>>
>>> # 1-week rolling max
>>> descriptor = MaxReturn(window=5)
>>> max_ret_5d = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.MaxReturn.fit_transform"></a>

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

Compute rolling maximum returns over the configured window.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **max_return** *ndarray of shape (n_observations, n_assets)*
  : Rolling maximum return for each observation and asset.

<a id="skfolio.descriptor.MaxReturn.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.descriptor.MaxReturn.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.descriptor.MaxReturn.partial_fit_transform"></a>

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

Update state and return rolling max return for this batch.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `"returns"`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **max_return** *ndarray of shape (n_observations, n_assets)*
  : Rolling maximum return for each observation and asset.

<a id="skfolio.descriptor.MaxReturn.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.

# generated/skfolio.descriptor.Passthrough.html.md

<a id="skfolio-descriptor-passthrough"></a>

# skfolio.descriptor.Passthrough

<a id="skfolio.descriptor.Passthrough"></a>

### *class* skfolio.descriptor.Passthrough(field)

Passthrough descriptor for an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) field.

Returns the selected panel field without numerical transformation. This is
useful for raw vendor fields or for values computed upstream that should
enter a factor exposure model unchanged.

* **Parameters:**
  **field** *str*
  : Name of the field to read from the input
    [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel).
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.Passthrough.html.md#skfolio.descriptor.Passthrough.fit_transform)(X[, y])         | Return the configured panel field.             |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.Passthrough.html.md#skfolio.descriptor.Passthrough.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.Passthrough.html.md#skfolio.descriptor.Passthrough.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.Passthrough.html.md#skfolio.descriptor.Passthrough.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.Passthrough.html.md#skfolio.descriptor.Passthrough.set_params)(\*\*params)        | Set the parameters of this estimator.          |

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import Passthrough
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = Passthrough("eps_ntm")
>>> eps_ntm = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.Passthrough.fit_transform"></a>

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

Return the configured panel field.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` characteristic configured at
    construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **values** *ndarray of shape (n_observations, n_assets)*
  : Raw values of `field` for each observation and asset.

<a id="skfolio.descriptor.Passthrough.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.descriptor.Passthrough.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.descriptor.Passthrough.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.Passthrough.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.

# generated/skfolio.descriptor.ReturnOnAssets.html.md

<a id="skfolio-descriptor-returnonassets"></a>

# skfolio.descriptor.ReturnOnAssets

<a id="skfolio.descriptor.ReturnOnAssets"></a>

### *class* skfolio.descriptor.ReturnOnAssets

Return on assets (ROA) descriptor.

Computes the ratio of trailing twelve-month net income to total assets:

$$
\text{ROA}(t) = \frac{\text{net\_income\_ttm}(t)}{\text{total\_assets}(t)}
$$

Return on assets measures how efficiently a firm converts its asset base into
earnings. Higher values indicate greater profitability per unit of capital deployed [[1]](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#rb522965354ed-1).

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets.fit_transform)(X[, y])         | Compute return on assets.                      |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`ReturnOnEquity`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnEquity.html.md#skfolio.descriptor.ReturnOnEquity)
: Profitability per unit of equity.

[`AssetTurnover`](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#skfolio.descriptor.AssetTurnover)
: Sales generated per unit of total assets.

### Notes

Net income can be negative, so $ROA$ can be negative. Negative values
distinguish profitable from unprofitable firms.

### References

* <a id='rb522965354ed-1'>**[1]**</a> “A five-factor asset pricing model” Journal of Financial Economics. Fama, E. F., & French, K. R. (2015).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import ReturnOnAssets
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = ReturnOnAssets()
>>> return_on_assets = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.ReturnOnAssets.fit_transform"></a>

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

Compute return on assets.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `net_income_ttm` and `total_assets`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **return_on_assets** *ndarray of shape (n_observations, n_assets)*
  : Net income divided by total assets for each observation and asset.

<a id="skfolio.descriptor.ReturnOnAssets.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.descriptor.ReturnOnAssets.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.descriptor.ReturnOnAssets.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.ReturnOnAssets.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.

# generated/skfolio.descriptor.ReturnOnEquity.html.md

<a id="skfolio-descriptor-returnonequity"></a>

# skfolio.descriptor.ReturnOnEquity

<a id="skfolio.descriptor.ReturnOnEquity"></a>

### *class* skfolio.descriptor.ReturnOnEquity

Return on equity (ROE) descriptor.

Computes the ratio of trailing twelve-month net income to common shareholders’
equity:

$$
\text{ROE}(t) =  \frac{\text{net\_income\_ttm}(t)}{\text{book\_equity}(t)}
$$

Return on equity measures profitability from the common shareholders’ perspective:
how much profit a firm generates per unit of common equity capital. Stocks with
high $ROE$ tend to earn higher average returns [[1]](https://skfolio.org/generated/skfolio.descriptor.ReturnOnEquity.html.md#r29a2ea881056-1).

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnEquity.html.md#skfolio.descriptor.ReturnOnEquity.fit_transform)(X[, y])         | Compute return on equity.                      |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnEquity.html.md#skfolio.descriptor.ReturnOnEquity.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnEquity.html.md#skfolio.descriptor.ReturnOnEquity.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnEquity.html.md#skfolio.descriptor.ReturnOnEquity.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnEquity.html.md#skfolio.descriptor.ReturnOnEquity.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`ReturnOnAssets`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets)
: Profitability per unit of total assets.

### Notes

When `book_equity <= 0` (e.g., firms with accumulated deficits or heavy share
buybacks), the ratio does not represent an interpretable return on equity. These
observations are masked to NaN.

### References

* <a id='r29a2ea881056-1'>**[1]**</a> “A five-factor asset pricing model” Journal of Financial Economics. Fama, E. F., & French, K. R. (2015).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import ReturnOnEquity
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = ReturnOnEquity()
>>> return_on_equity = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.ReturnOnEquity.fit_transform"></a>

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

Compute return on equity.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `net_income_ttm` and `book_equity`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **return_on_equity** *ndarray of shape (n_observations, n_assets)*
  : Net income divided by book equity for each observation and asset.

<a id="skfolio.descriptor.ReturnOnEquity.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.descriptor.ReturnOnEquity.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.descriptor.ReturnOnEquity.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.ReturnOnEquity.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.

# generated/skfolio.descriptor.Reversal.html.md

<a id="skfolio-descriptor-reversal"></a>

# skfolio.descriptor.Reversal

<a id="skfolio.descriptor.Reversal"></a>

### *class* skfolio.descriptor.Reversal(window=21)

Fixed-window short-term reversal descriptor.

Computes the negated cumulative log return over a trailing window:

$$
\text{reversal}(t) = -\sum_{k=t-w+1}^{t} \log(1 + r_k)
$$

where $w$ is the `window` size and $r_k$ is the asset return at
observation $k$. High values indicate recent poor performance (reversal
candidates).

Short-term reversal captures mean reversion in returns driven by temporary price
pressure, liquidity provision and microstructure effects [[1]](https://skfolio.org/generated/skfolio.descriptor.Reversal.html.md#r3e64ad5733a4-1) [[2]](https://skfolio.org/generated/skfolio.descriptor.Reversal.html.md#r3e64ad5733a4-2).

The output is NaN until an asset has a full active lookback window. Active assets
with missing returns contribute zero to the log-return sum. Non-missing `returns`
values must be finite and greater than `-1`.

The descriptor is returned in log-return space. Log cumulative returns are more
symmetric than simple cumulative returns, which makes them better suited to
cross-sectional standardization. Because the logarithm is monotonic, log-space and
simple cumulative returns produce the same cross-sectional rankings when returns
are finite and greater than `-1`.

* **Parameters:**
  **window** *int, default=21*
  : Number of trailing observations for the cumulative return.
    Common choices for daily data:
    - `window=1`: 1-day reversal
    - `window=5`: 1-week reversal
    - `window=21`: 1-month reversal (default)
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **reversal_** *ndarray of shape (n_assets,)*
  : Last short-term reversal value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.Reversal.html.md#skfolio.descriptor.Reversal.fit_transform)(X[, y])         | Compute the rolling log-return descriptor from a clean state.   |
|--------------------------------------------------------------------------------|-----------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.Reversal.html.md#skfolio.descriptor.Reversal.get_metadata_routing)()        | Get metadata routing of this object.                            |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.Reversal.html.md#skfolio.descriptor.Reversal.get_params)([deep])            | Get parameters for this estimator.                              |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.Reversal.html.md#skfolio.descriptor.Reversal.partial_fit_transform)(X[, y]) | Update state and compute the rolling log-return descriptor.     |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.Reversal.html.md#skfolio.descriptor.Reversal.set_params)(\*\*params)        | Set the parameters of this estimator.                           |

#### SEE ALSO
[`EWMomentum`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum)
: Exponentially weighted momentum (medium/long-term).

[`RollingMomentum`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum)
: Fixed-window momentum with optional skip.

### Notes

Two code paths are used depending on context:

- Batch (first call with sufficient data): vectorized cumsum over
  the full panel. Time $O(T \cdot n)$, space $O(T \cdot n)$.
- Online (subsequent calls or streaming): ring buffer of size $w$ (the window)
  with a running sum. Per observation: one subtract (value leaving the window), one
  add (current value), one write. Time $O(n)$ per step, space
  $O(w \cdot n)$, zero allocation.

After a batch computation, the ring buffer state is populated for subsequent online
calls.

### References

* <a id='r3e64ad5733a4-1'>**[1]**</a> “Evidence of predictable behavior of security returns” The Journal of Finance. Jegadeesh, N. (1990).
* <a id='r3e64ad5733a4-2'>**[2]**</a> “Fads, martingales, and market efficiency” The Quarterly Journal of Economics. Lehmann, B. N. (1990).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import Reversal
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 1-month reversal (default)
>>> descriptor = Reversal()
>>> reversal = descriptor.fit_transform(X)
>>>
>>> # 1-day reversal
>>> descriptor = Reversal(window=1)
>>> reversal_1d = descriptor.fit_transform(X)
>>>
>>> # 1-week reversal
>>> descriptor = Reversal(window=5)
>>> reversal_5d = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.Reversal.fit_transform"></a>

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

Compute the rolling log-return descriptor from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **descriptor** *ndarray of shape (n_observations, n_assets)*
  : Rolling log-return descriptor for each observation and asset.

<a id="skfolio.descriptor.Reversal.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.descriptor.Reversal.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.descriptor.Reversal.partial_fit_transform"></a>

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

Update state and compute the rolling log-return descriptor.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **descriptor** *ndarray of shape (n_observations, n_assets)*
  : Rolling log-return descriptor for each observation and asset.

<a id="skfolio.descriptor.Reversal.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.

# generated/skfolio.descriptor.RollingMomentum.html.md

<a id="skfolio-descriptor-rollingmomentum"></a>

# skfolio.descriptor.RollingMomentum

<a id="skfolio.descriptor.RollingMomentum"></a>

### *class* skfolio.descriptor.RollingMomentum(window=252, skip=21, exponentiate=False)

Fixed-window momentum descriptor.

Computes the sum of log returns over a trailing window with an optional skip period
to exclude the most recent observations:

The skip period separates medium-term momentum from short-term reversal. The classic
“12-1” momentum signal uses a skip of approximately one month [[1]](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#r00dbc6ffe58d-1).

$$
\[
\begin{aligned}
x(k)
    &= \log(1 + r(k)) \\[0.75em]
S(t)
    &= \sum_{k=t-\text{skip}-\text{window}+1}^{t-\text{skip}}
       x(k) \\[0.75em]
\text{momentum}(t)
    &=
    \begin{cases}
    \exp(S(t)) - 1 & \text{if } \texttt{exponentiate=True} \\
    S(t) & \text{otherwise}
    \end{cases}
\end{aligned}
\]
$$

The window uses the $\text{window}$ observations ending at
$t - \text{skip}$. Output is NaN until the asset has a full active lookback
window.

By default, the descriptor is returned in log-return space. Log cumulative returns
are more symmetric than simple cumulative returns, which makes them better suited to
cross-sectional standardization. Because the logarithm is monotonic, log-space and
simple cumulative returns produce the same cross-sectional rankings when returns
are finite and greater than `-1`.

* **Parameters:**
  **window** *int, default=252*
  : Number of observations in the lookback window.

  **skip** *int, default=21*
  : Number of most recent observations excluded from the window. The last
    observation included is at $t - \text{skip}$. Classic 12-1 momentum uses a
    skip of about one month (21 daily obs). Set to 0 for no skip.

  **exponentiate** *bool, default=False*
  : If True, output is $\exp(S(t)) - 1$ (return units). If False, output is
    $S(t)$ (log space). Cross-sectional ranking is unchanged and only the 
    scale differs.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **momentum_** *ndarray of shape (n_assets,)*
  : Last rolling momentum value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum.fit_transform)(X[, y])         | Compute the rolling log-return descriptor from a clean state.   |
|--------------------------------------------------------------------------------|-----------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum.get_metadata_routing)()        | Get metadata routing of this object.                            |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum.get_params)([deep])            | Get parameters for this estimator.                              |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum.partial_fit_transform)(X[, y]) | Update state and compute the rolling log-return descriptor.     |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum.set_params)(\*\*params)        | Set the parameters of this estimator.                           |

#### SEE ALSO
[`EWMomentum`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum)
: Exponentially weighted momentum.

### Notes

Two code paths are used depending on context:

- Batch (first call with sufficient data): vectorized cumsum over
  the full panel. Time $O(T \cdot n)$, space $O(T \cdot n)$.
- Online (subsequent calls or streaming): ring buffer of size
  $L = \text{skip} + \text{window}$ with a running sum. Per observation: one
  subtract (value leaving the window), one add (value entering), one write.
  Time $O(n)$ per step, space $O(L \cdot n)$, zero allocation.

After a batch computation, the ring buffer state is populated for subsequent online
calls.

NaNs are allowed as missing observations. Non-missing `returns` values must be
finite and greater than `-1`, so $\log(1 + r)$ is finite. Active assets with
NaN returns (e.g. holidays) contribute 0 to the sum. Inactive asset outputs are
set to NaN.

### References

* <a id='r00dbc6ffe58d-1'>**[1]**</a> “Returns to buying winners and selling losers: Implications for stock market efficiency” The Journal of Finance. Jegadeesh, N., & Titman, S. (1993).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import RollingMomentum
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 12-1 momentum
>>> descriptor = RollingMomentum(window=252, skip=21)
>>> momentum = descriptor.fit_transform(X)
>>>
>>> # Log-space output
>>> descriptor = RollingMomentum(window=252, skip=21, exponentiate=False)
>>> momentum_log = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.RollingMomentum.fit_transform"></a>

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

Compute the rolling log-return descriptor from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **descriptor** *ndarray of shape (n_observations, n_assets)*
  : Rolling log-return descriptor for each observation and asset.

<a id="skfolio.descriptor.RollingMomentum.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.descriptor.RollingMomentum.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.descriptor.RollingMomentum.partial_fit_transform"></a>

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

Update state and compute the rolling log-return descriptor.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **descriptor** *ndarray of shape (n_observations, n_assets)*
  : Rolling log-return descriptor for each observation and asset.

<a id="skfolio.descriptor.RollingMomentum.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.

# generated/skfolio.descriptor.SalesGrowthRate.html.md

<a id="skfolio-descriptor-salesgrowthrate"></a>

# skfolio.descriptor.SalesGrowthRate

<a id="skfolio.descriptor.SalesGrowthRate"></a>

### *class* skfolio.descriptor.SalesGrowthRate(lag=252)

Sales growth rate descriptor.

Computes period-over-period growth in trailing twelve-month sales:

$$
\text{sales\_growth}(t)
= \frac{\text{sales\_ttm}(t)}{\text{sales\_ttm}(t - \text{lag})} - 1
$$

The first `lag` observations are NaN because no lagged history is available.

`sales_ttm` must contain non-missing finite non-negative values. NaNs are allowed
as missing observations and propagate when either the current or lagged value is
missing. Zero values are allowed and a zero lagged value makes the growth rate
undefined and produces NaN.

Sales growth measures top-line expansion over the lag window. For TTM sales with a
one-year lag, the two observations cover non-overlapping fiscal content.

This is a convenience subclass of [`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate) with `field="sales_ttm"`.

* **Parameters:**
  **lag** *int, default=252*
  : Number of observations to look back. The interpretation depends on the data
    frequency: `lag=12` means 1 year for monthly data, `lag=252` for daily data,
    `lag=4` for quarterly data.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **growth_rate_** *ndarray of shape (n_assets,)*
  : Last sales growth value for each asset.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.SalesGrowthRate.html.md#skfolio.descriptor.SalesGrowthRate.fit_transform)(X[, y])         | Compute simple growth rates of the configured field.   |
|--------------------------------------------------------------------------------|--------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.SalesGrowthRate.html.md#skfolio.descriptor.SalesGrowthRate.get_metadata_routing)()        | Get metadata routing of this object.                   |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.SalesGrowthRate.html.md#skfolio.descriptor.SalesGrowthRate.get_params)([deep])            | Get parameters for this estimator.                     |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.SalesGrowthRate.html.md#skfolio.descriptor.SalesGrowthRate.partial_fit_transform)(X[, y]) | Compute simple growth rates of the configured field.   |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.SalesGrowthRate.html.md#skfolio.descriptor.SalesGrowthRate.set_params)(\*\*params)        | Set the parameters of this estimator.                  |

#### SEE ALSO
[`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate)
: Generic period-over-period growth rate descriptor.

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import SalesGrowthRate
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = SalesGrowthRate(lag=252)
>>> sales_growth_rate = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.SalesGrowthRate.fit_transform"></a>

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

Compute simple growth rates of the configured field.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` characteristic configured at
    construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **growth_rate** *ndarray of shape (n_observations, n_assets)*
  : Period-over-period growth rate for each observation and asset.

<a id="skfolio.descriptor.SalesGrowthRate.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.descriptor.SalesGrowthRate.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.descriptor.SalesGrowthRate.partial_fit_transform"></a>

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

Compute simple growth rates of the configured field.

This method supports online updates by continuing from the current fitted state.
Use `fit_transform` to start from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the `field` characteristic configured at construction.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **growth_rate** *ndarray of shape (n_observations, n_assets)*
  : Period-over-period growth rate for each observation and asset.

<a id="skfolio.descriptor.SalesGrowthRate.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.

# generated/skfolio.descriptor.SalesToEnterpriseValue.html.md

<a id="skfolio-descriptor-salestoenterprisevalue"></a>

# skfolio.descriptor.SalesToEnterpriseValue

<a id="skfolio.descriptor.SalesToEnterpriseValue"></a>

### *class* skfolio.descriptor.SalesToEnterpriseValue

Sales to enterprise value descriptor.

Computes the ratio of trailing twelve-month sales to enterprise value:

$$
\text{sales\_to\_enterprise\_value}(t) =
\frac{\text{sales\_ttm}(t)}{\text{enterprise\_value}(t)}
$$

This descriptor is a valuation and efficiency measure: it measures how much revenue
a firm generates per unit of enterprise value. Unlike [`AssetTurnover`](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#skfolio.descriptor.AssetTurnover), which
normalizes by book assets, enterprise value reflects the market’s assessment of the
entire capital structure [[1]](https://skfolio.org/generated/skfolio.descriptor.SalesToEnterpriseValue.html.md#r8c06b785cdaa-1).

A high sales-to-enterprise-value ratio identifies firms that generate substantial
revenue relative to their market valuation, combining elements of both value and
operational efficiency.

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.SalesToEnterpriseValue.html.md#skfolio.descriptor.SalesToEnterpriseValue.fit_transform)(X[, y])         | Compute sales to enterprise value.             |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.SalesToEnterpriseValue.html.md#skfolio.descriptor.SalesToEnterpriseValue.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.SalesToEnterpriseValue.html.md#skfolio.descriptor.SalesToEnterpriseValue.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.SalesToEnterpriseValue.html.md#skfolio.descriptor.SalesToEnterpriseValue.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.SalesToEnterpriseValue.html.md#skfolio.descriptor.SalesToEnterpriseValue.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`AssetTurnover`](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#skfolio.descriptor.AssetTurnover)
: Sales normalized by book assets (efficiency).

[`EbitdaToEnterpriseValue`](https://skfolio.org/generated/skfolio.descriptor.EbitdaToEnterpriseValue.html.md#skfolio.descriptor.EbitdaToEnterpriseValue)
: EBITDA normalized by enterprise value.

### Notes

If `enterprise_value` is not available directly from your data provider, it can be
computed as:

$$
\text{EV} = \text{market\_cap} + \text{total\_debt}
           - \text{cash\_and\_equivalents}
$$

Non-missing `enterprise_value` values must be finite. Observations with
`enterprise_value <= 0` are masked to NaN because the valuation yield is not
economically interpretable.

### References

* <a id='r8c06b785cdaa-1'>**[1]**</a> “New evidence on the relation between the enterprise multiple and average stock returns” Journal of Financial and Quantitative Analysis. Loughran, T., & Wellman, J. W. (2011).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import SalesToEnterpriseValue
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = SalesToEnterpriseValue()
>>> sales_to_enterprise_value = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.SalesToEnterpriseValue.fit_transform"></a>

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

Compute sales to enterprise value.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `sales_ttm` and `enterprise_value`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **sales_to_enterprise_value** *ndarray of shape (n_observations, n_assets)*
  : Sales divided by enterprise value for each observation and asset.

<a id="skfolio.descriptor.SalesToEnterpriseValue.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.descriptor.SalesToEnterpriseValue.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.descriptor.SalesToEnterpriseValue.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.SalesToEnterpriseValue.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.

# generated/skfolio.descriptor.SalesToPrice.html.md

<a id="skfolio-descriptor-salestoprice"></a>

# skfolio.descriptor.SalesToPrice

<a id="skfolio.descriptor.SalesToPrice"></a>

### *class* skfolio.descriptor.SalesToPrice

Sales-to-price ratio descriptor.

Computes the ratio of trailing twelve-month sales to market capitalization:

$$
\text{sales\_to\_price}(t) = \frac{\text{sales\_ttm}(t)}{\text{market\_cap}(t)}
$$

Sales are less directly affected by accounting choices than earnings, providing a
stable value signal. Firms with high sales relative to market capitalization are
cheap on a sales basis [[1]](https://skfolio.org/generated/skfolio.descriptor.SalesToPrice.html.md#r00d224b8fe24-1). This ratio remains available for firms with negative
earnings or book equity, complementing [`BookToPrice`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice).

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.SalesToPrice.html.md#skfolio.descriptor.SalesToPrice.fit_transform)(X[, y])         | Compute sales to price.                        |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.SalesToPrice.html.md#skfolio.descriptor.SalesToPrice.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.SalesToPrice.html.md#skfolio.descriptor.SalesToPrice.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.SalesToPrice.html.md#skfolio.descriptor.SalesToPrice.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.SalesToPrice.html.md#skfolio.descriptor.SalesToPrice.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`BookToPrice`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice)
: Common equity normalized by market capitalization.

[`CashFlowToPrice`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#skfolio.descriptor.CashFlowToPrice)
: Operating cash flow normalized by market capitalization.

### Notes

Non-missing `market_cap` values must be finite and strictly positive.

This descriptor uses aggregate quantities (total sales divided by total market
capitalization) rather than per-share quantities (sales per share divided by price).
The two are mathematically equivalent:

$$
\frac{\text{sales\_ttm}}{\text{market\_cap}}
= \frac{\text{sales\_per\_share}}{\text{price}}
$$

The aggregate form is preferred because it avoids subtle split-adjustment
mismatches between numerator and denominator. Aggregate fundamentals are the primary
form from data providers; per-share quantities are derived from them.

### References

* <a id='r00d224b8fe24-1'>**[1]**</a> “Do sales-price and debt-equity explain stock returns better than book-market and firm size?” Financial Analysts Journal. Barbee, Mukherji & Raines (1996).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import SalesToPrice
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = SalesToPrice()
>>> sales_to_price = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.SalesToPrice.fit_transform"></a>

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

Compute sales to price.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `sales_ttm` and `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **sales_to_price** *ndarray of shape (n_observations, n_assets)*
  : Sales-to-price ratio for each observation and asset.

<a id="skfolio.descriptor.SalesToPrice.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.descriptor.SalesToPrice.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.descriptor.SalesToPrice.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.SalesToPrice.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.

# generated/skfolio.descriptor.ShareholderYield.html.md

<a id="skfolio-descriptor-shareholderyield"></a>

# skfolio.descriptor.ShareholderYield

<a id="skfolio.descriptor.ShareholderYield"></a>

### *class* skfolio.descriptor.ShareholderYield

Shareholder yield descriptor.

Computes net cash returned to common shareholders through dividends and share
repurchases as a fraction of market capitalization:

$$
\text{shareholder\_yield}(t) =
\frac{\text{dividends\_ttm}(t) + \text{net\_buybacks\_ttm}(t)}
     {\text{market\_cap}(t)}
$$

Dividend yield alone misses a large share of corporate payout. Since the 1990s,
share repurchases have overtaken dividends as the dominant mechanism for returning
cash to shareholders. Shareholder yield captures the total payout: a company
paying 0% dividends but buying back 5% of its equity annually has a positive payout
yield that pure dividend yield scores as zero [[1]](https://skfolio.org/generated/skfolio.descriptor.ShareholderYield.html.md#r6ab09b0564bd-1).

High shareholder yield identifies firms that return substantial capital.
Empirically, shareholder yield subsumes much of the stand-alone dividend yield
premium and provides a stronger value/payout signal [[2]](https://skfolio.org/generated/skfolio.descriptor.ShareholderYield.html.md#r6ab09b0564bd-2).

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ShareholderYield.html.md#skfolio.descriptor.ShareholderYield.fit_transform)(X[, y])         | Compute shareholder yield ratios.              |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.ShareholderYield.html.md#skfolio.descriptor.ShareholderYield.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.ShareholderYield.html.md#skfolio.descriptor.ShareholderYield.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ShareholderYield.html.md#skfolio.descriptor.ShareholderYield.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.ShareholderYield.html.md#skfolio.descriptor.ShareholderYield.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`DividendToPrice`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice)
: Dividend-only yield (trailing).

### Notes

`dividends_ttm` should contain positive cash dividends paid on common shares only,
excluding preferred dividends.

`net_buybacks_ttm` should equal net share repurchases, defined as repurchases minus
issuances, over the trailing twelve months. Positive values increase shareholder
yield and negative values represent net issuance. Some data vendors provide net
equity issuance from the cash flow statement instead, with the opposite sign
convention. In that case, `net_buybacks_ttm = -net_equity_issuance_ttm`.

This descriptor uses aggregate quantities divided by `market_cap`, consistent with
`DividendToPrice` and other value descriptors.

### References

* <a id='r6ab09b0564bd-1'>**[1]**</a> “On the importance of measuring payout yield: implications for empirical asset pricing” The Journal of Finance. Boudoukh, Michaely, Richardson & Roberts (2007).
* <a id='r6ab09b0564bd-2'>**[2]**</a> “Dividends, share repurchases, and the substitution hypothesis” The Journal of Finance. Grullon & Michaely (2002).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import ShareholderYield
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = ShareholderYield()
>>> shareholder_yield = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.ShareholderYield.fit_transform"></a>

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

Compute shareholder yield ratios.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `dividends_ttm`, `net_buybacks_ttm` and
    `market_cap`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **shareholder_yield** *ndarray of shape (n_observations, n_assets)*
  : Shareholder yield ratio for each observation and asset.

<a id="skfolio.descriptor.ShareholderYield.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.descriptor.ShareholderYield.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.descriptor.ShareholderYield.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.ShareholderYield.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.

# generated/skfolio.descriptor.ShortInterest.html.md

<a id="skfolio-descriptor-shortinterest"></a>

# skfolio.descriptor.ShortInterest

<a id="skfolio.descriptor.ShortInterest"></a>

### *class* skfolio.descriptor.ShortInterest

Short interest descriptor.

Computes the ratio of shares sold short to common shares outstanding:

$$
\text{short\_interest}(t) =
\frac{\text{short\_interest}(t)}
     {\text{adj\_shares\_outstanding}(t)}
$$

Short interest measures the fraction of common shares outstanding that have been
borrowed and sold short. High values indicate stronger bearish positioning and may
proxy for informed negative sentiment [[1]](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#r3408170d7b7b-1) [[2]](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#r3408170d7b7b-2).

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#skfolio.descriptor.ShortInterest.fit_transform)(X[, y])         | Compute short interest.                        |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#skfolio.descriptor.ShortInterest.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#skfolio.descriptor.ShortInterest.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#skfolio.descriptor.ShortInterest.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#skfolio.descriptor.ShortInterest.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`DaysToCover`](https://skfolio.org/generated/skfolio.descriptor.DaysToCover.html.md#skfolio.descriptor.DaysToCover)
: EWMA-smoothed days to cover (short interest / volume).

### Notes

`short_interest` is the number of shares held short. Non-missing values must be
finite and non-negative.

`adj_shares_outstanding` is common shares outstanding. Non-missing values must be
finite and strictly positive.

Both fields must use the same split-adjustment basis.

### References

* <a id='r3408170d7b7b-1'>**[1]**</a> “An investigation of the informational role of short interest in the Nasdaq market” The Journal of Finance. Desai, H., Ramesh, K., Thiagarajan, S. R., & Balachandran, B. V. (2002).
* <a id='r3408170d7b7b-2'>**[2]**</a> “Short interest and aggregate stock returns” Journal of Financial Economics. Rapach, D. E., Ringgenberg, M. C., & Zhou, G. (2016).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import ShortInterest
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = ShortInterest()
>>> short_interest = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.ShortInterest.fit_transform"></a>

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

Compute short interest.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `short_interest` and `adj_shares_outstanding`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **short_interest** *ndarray of shape (n_observations, n_assets)*
  : Short interest divided by adjusted shares outstanding for each
    observation and asset.

<a id="skfolio.descriptor.ShortInterest.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.descriptor.ShortInterest.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.descriptor.ShortInterest.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.ShortInterest.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.

# generated/skfolio.distance.BaseDistance.html.md

<a id="skfolio-distance-basedistance"></a>

# skfolio.distance.BaseDistance

<a id="skfolio.distance.BaseDistance"></a>

### *class* skfolio.distance.BaseDistance

Base class for all distance estimators in skfolio.

* **Attributes:**
  **codependence_** *ndarray of shape (n_assets, n_assets)*
  : Codependence matrix.

  **distance_** *ndarray of shape (n_assets, n_assets)*
  : Distance matrix.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.distance.BaseDistance.html.md#skfolio.distance.BaseDistance.fit)(X[, y])            | Fit the Distance estimator.           |
|-------------------------------------------------------------------------|---------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distance.BaseDistance.html.md#skfolio.distance.BaseDistance.get_metadata_routing)() | Get metadata routing of this object.  |
| [`get_params`](https://skfolio.org/generated/skfolio.distance.BaseDistance.html.md#skfolio.distance.BaseDistance.get_params)([deep])     | Get parameters for this estimator.    |
| [`set_params`](https://skfolio.org/generated/skfolio.distance.BaseDistance.html.md#skfolio.distance.BaseDistance.set_params)(\*\*params) | Set the parameters of this estimator. |

### Notes

All estimators should specify all the parameters that can be set
at the class level in their `__init__` as explicit keyword
arguments (no `*args` or `**kwargs`).

<a id="skfolio.distance.BaseDistance.fit"></a>

#### *abstractmethod* fit(X, y=None)

Fit the Distance 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.
* **Returns:**
  **self** *BaseDistance*
  : Fitted estimator.

<a id="skfolio.distance.BaseDistance.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.distance.BaseDistance.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.distance.BaseDistance.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.

# generated/skfolio.distance.CovarianceDistance.html.md

<a id="skfolio-distance-covariancedistance"></a>

# skfolio.distance.CovarianceDistance

<a id="skfolio.distance.CovarianceDistance"></a>

### *class* skfolio.distance.CovarianceDistance(covariance_estimator=None, absolute=False, power=1)

Covariance Distance estimator.

The codependence is computed from the correlation matrix of a chosen
[covariance estimator](https://skfolio.org/user_guide/covariance.html.md#covariance-estimator) to which is applied
a power and/or absolute transformation.
This codependence is then used to compute the distance matrix.
Some widely used distances are:

> * Standard angular distance = $\sqrt{0.5 \times (1 - corr)}$
> * Absolute angular distance = $\sqrt{1 - |corr|}$
> * Squared angular distance = $\sqrt{1 - corr^2}$
* **Parameters:**
  **covariance_estimator** *BaseCovariance, optional*
  : [Covariance estimator](https://skfolio.org/user_guide/covariance.html.md#covariance-estimator).
    The default (`None`) is to use [`GerberCovariance`](https://skfolio.org/generated/skfolio.moments.GerberCovariance.html.md#skfolio.moments.GerberCovariance).

  **absolute** *bool, default=False*
  : If this is set to True, the absolute transformation is applied to the
    correlation matrix.
    The default is `False`.

  **power** *float, default=1*
  : Exponent of the power transformation applied to the correlation matrix.
    The default value is `1`.
* **Attributes:**
  **codependence_** *ndarray of shape (n_assets, n_assets)*
  : Codependence matrix.

  **distance_** *ndarray of shape (n_assets, n_assets)*
  : Distance matrix.

  **covariance_estimator_: BaseCovariance**
  : Fitted `covariance_estimator`

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.distance.CovarianceDistance.html.md#skfolio.distance.CovarianceDistance.fit)(X[, y])            | Fit the Covariance Distance estimator.   |
|-------------------------------------------------------------------------|------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distance.CovarianceDistance.html.md#skfolio.distance.CovarianceDistance.get_metadata_routing)() | Get metadata routing of this object.     |
| [`get_params`](https://skfolio.org/generated/skfolio.distance.CovarianceDistance.html.md#skfolio.distance.CovarianceDistance.get_params)([deep])     | Get parameters for this estimator.       |
| [`set_params`](https://skfolio.org/generated/skfolio.distance.CovarianceDistance.html.md#skfolio.distance.CovarianceDistance.set_params)(\*\*params) | Set the parameters of this estimator.    |

### References

* <a id='r0f607e111fbd-1'>**[1]**</a> “Building Diversified Portfolios that Outperform Out-of-Sample”, Lòpez de Prado, Journal of Portfolio Management (2016)

<a id="skfolio.distance.CovarianceDistance.fit"></a>

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

Fit the Covariance Distance 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.
* **Returns:**
  **self** *CovarianceDistance*
  : Fitted estimator.

<a id="skfolio.distance.CovarianceDistance.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.distance.CovarianceDistance.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.distance.CovarianceDistance.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.

# generated/skfolio.distance.DistanceCorrelation.html.md

<a id="skfolio-distance-distancecorrelation"></a>

# skfolio.distance.DistanceCorrelation

<a id="skfolio.distance.DistanceCorrelation"></a>

### *class* skfolio.distance.DistanceCorrelation(threshold=0.5)

Distance Correlation estimator.

Distance Correlation was introduced by Szekely [[1]](https://skfolio.org/generated/skfolio.distance.DistanceCorrelation.html.md#rc85b9d7bb4d0-1) to capture non-linear
dependencies.

* **Parameters:**
  **threshold** *float, default=0.5*
  : Distance correlation threshold.
* **Attributes:**
  **codependence_** *ndarray of shape (n_assets, n_assets)*
  : Codependence matrix.

  **distance_** *ndarray of shape (n_assets, n_assets)*
  : Distance matrix.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.distance.DistanceCorrelation.html.md#skfolio.distance.DistanceCorrelation.fit)(X[, y])            | Fit the Distance Correlation estimator.   |
|-------------------------------------------------------------------------|-------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distance.DistanceCorrelation.html.md#skfolio.distance.DistanceCorrelation.get_metadata_routing)() | Get metadata routing of this object.      |
| [`get_params`](https://skfolio.org/generated/skfolio.distance.DistanceCorrelation.html.md#skfolio.distance.DistanceCorrelation.get_params)([deep])     | Get parameters for this estimator.        |
| [`set_params`](https://skfolio.org/generated/skfolio.distance.DistanceCorrelation.html.md#skfolio.distance.DistanceCorrelation.set_params)(\*\*params) | Set the parameters of this estimator.     |

### References

* <a id='rc85b9d7bb4d0-1'>**[1]**</a> “Measuring and testing independence by correlation of distances” Gábor J. Szekely , 2005

<a id="skfolio.distance.DistanceCorrelation.fit"></a>

#### fit(X, y=None)

Fit the Distance Correlation 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.
* **Returns:**
  **self** *DistanceCorrelation*
  : Fitted estimator.

<a id="skfolio.distance.DistanceCorrelation.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.distance.DistanceCorrelation.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.distance.DistanceCorrelation.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.

# generated/skfolio.distance.KendallDistance.html.md

<a id="skfolio-distance-kendalldistance"></a>

# skfolio.distance.KendallDistance

<a id="skfolio.distance.KendallDistance"></a>

### *class* skfolio.distance.KendallDistance(absolute=False, power=1)

Kendall Distance estimator.

The codependence is computed from the Kendall correlation to which is applied a
power and/or absolute transformation.
This codependence is then used to compute the distance matrix.
Some widely used distances are:

> * Standard angular distance = $\sqrt{0.5 \times (1 - corr)}$
> * Absolute angular distance = $\sqrt{1 - |corr|}$
> * Squared angular distance = $\sqrt{1 - corr^2}$
* **Parameters:**
  **absolute** *bool, default=False*
  : If this is set to True, the absolute transformation is applied to the
    correlation matrix.
    The default is `False`.

  **power** *float, default=1*
  : Exponent of the power transformation applied to the correlation matrix.
    The default value is `1`.
* **Attributes:**
  **codependence_** *ndarray of shape (n_assets, n_assets)*
  : Codependence matrix.

  **distance_** *ndarray of shape (n_assets, n_assets)*
  : Distance matrix.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.distance.KendallDistance.html.md#skfolio.distance.KendallDistance.fit)(X[, y])            | Fit the Kendall estimator.            |
|-------------------------------------------------------------------------|---------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distance.KendallDistance.html.md#skfolio.distance.KendallDistance.get_metadata_routing)() | Get metadata routing of this object.  |
| [`get_params`](https://skfolio.org/generated/skfolio.distance.KendallDistance.html.md#skfolio.distance.KendallDistance.get_params)([deep])     | Get parameters for this estimator.    |
| [`set_params`](https://skfolio.org/generated/skfolio.distance.KendallDistance.html.md#skfolio.distance.KendallDistance.set_params)(\*\*params) | Set the parameters of this estimator. |

### References

* <a id='re37153679f90-1'>**[1]**</a> “Building Diversified Portfolios that Outperform Out-of-Sample”, Lòpez de Prado, Journal of Portfolio Management (2016)

<a id="skfolio.distance.KendallDistance.fit"></a>

#### fit(X, y=None)

Fit the Kendall 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.
* **Returns:**
  **self** *KendallDistance*
  : Fitted estimator.

<a id="skfolio.distance.KendallDistance.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.distance.KendallDistance.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.distance.KendallDistance.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.

# generated/skfolio.distance.MutualInformation.html.md

<a id="skfolio-distance-mutualinformation"></a>

# skfolio.distance.MutualInformation

<a id="skfolio.distance.MutualInformation"></a>

### *class* skfolio.distance.MutualInformation(n_bins_method=FREEDMAN, n_bins=None, normalize=True)

Mutual Information estimator.

In information theory, the mutual information is a measure of the mutual dependence
between variables.
The related distance metric is called the variation of information.

For two random variables X and Y, the mutual information I(X,Y) is defined as:

$$
I(X,Y) = H(X) + H(Y) - H(X,Y)

$$

with H(X) and H(Y) the marginal entropies and H(X,Y) the joint entropy.

The related distance metric known as the  variation of information is defined as:

$$
d(X,Y) = H(X,Y) - I(X,Y) =  H(X) + H(Y) - 2 \times I(X,Y)

$$

and its normalization as:

$$
D(X,Y) = \frac{d(X,Y)}{H(X,Y)} = \frac{H(X) + H(Y) - 2 \times I(X,Y)}{H(X) + H(Y) - I(X,Y)}

$$

* **Parameters:**
  **n_bins_method** *NBinsMethod, default=NBinsMethod.FREEDMAN*
  : Method to compute the number of bins for the contingency matrix estimation used
    for the computation of the mutual information.
    Possible values are:
    > * FREEDMAN (`default`)
    > * KNUTH

  **n_bins** *int, optional*
  : Instead of using `n_bins_method`, you can directly specify the number of bins
    with `n_bins`.

  **normalize** *bool, default=True*
  : If this is set to True, the variation of information is normalized.
    The default is `True`.
* **Attributes:**
  **codependence_** *ndarray of shape (n_assets, n_assets)*
  : Codependence matrix.

  **distance_** *ndarray of shape (n_assets, n_assets)*
  : Distance matrix.

  **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`](https://skfolio.org/generated/skfolio.distance.MutualInformation.html.md#skfolio.distance.MutualInformation.fit)(X[, y])            | Fit the Mutual Information estimator.   |
|-------------------------------------------------------------------------|-----------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distance.MutualInformation.html.md#skfolio.distance.MutualInformation.get_metadata_routing)() | Get metadata routing of this object.    |
| [`get_params`](https://skfolio.org/generated/skfolio.distance.MutualInformation.html.md#skfolio.distance.MutualInformation.get_params)([deep])     | Get parameters for this estimator.      |
| [`set_params`](https://skfolio.org/generated/skfolio.distance.MutualInformation.html.md#skfolio.distance.MutualInformation.set_params)(\*\*params) | Set the parameters of this estimator.   |

<a id="skfolio.distance.MutualInformation.fit"></a>

#### fit(X, y=None)

Fit the Mutual Information 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.
* **Returns:**
  **self** *MutualInformation*
  : Fitted estimator.

<a id="skfolio.distance.MutualInformation.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.distance.MutualInformation.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.distance.MutualInformation.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.

# generated/skfolio.distance.PearsonDistance.html.md

<a id="skfolio-distance-pearsondistance"></a>

# skfolio.distance.PearsonDistance

<a id="skfolio.distance.PearsonDistance"></a>

### *class* skfolio.distance.PearsonDistance(absolute=False, power=1)

Pearson Distance estimator.

The codependence is computed from the Pearson correlation to which is applied a
power and/or absolute transformation.
This codependence is then used to compute the distance matrix.
Some widely used distances are:

> * Standard angular distance = $\sqrt{0.5 \times (1 - corr)}$
> * Absolute angular distance = $\sqrt{1 - |corr|}$
> * Squared angular distance = $\sqrt{1 - corr^2}$
* **Parameters:**
  **absolute** *bool, default=False*
  : If this is set to True, the absolute transformation is applied to the
    correlation matrix.

  **power** *float, default=1*
  : Exponent of the power transformation applied to the correlation matrix.
* **Attributes:**
  **codependence_** *ndarray of shape (n_assets, n_assets)*
  : Codependence matrix.

  **distance_** *ndarray of shape (n_assets, n_assets)*
  : Distance matrix.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance.fit)(X[, y])            | Fit the Pearson Distance estimator.   |
|-------------------------------------------------------------------------|---------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance.get_metadata_routing)() | Get metadata routing of this object.  |
| [`get_params`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance.get_params)([deep])     | Get parameters for this estimator.    |
| [`set_params`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance.set_params)(\*\*params) | Set the parameters of this estimator. |

### References

* <a id='r08d5dcd9018b-1'>**[1]**</a> “Building Diversified Portfolios that Outperform Out-of-Sample”, Lòpez de Prado, Journal of Portfolio Management (2016)

<a id="skfolio.distance.PearsonDistance.fit"></a>

#### fit(X, y=None)

Fit the Pearson Distance 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.
* **Returns:**
  **self** *PearsonDistance*
  : Fitted estimator.

<a id="skfolio.distance.PearsonDistance.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.distance.PearsonDistance.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.distance.PearsonDistance.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.

# generated/skfolio.distance.SpearmanDistance.html.md

<a id="skfolio-distance-spearmandistance"></a>

# skfolio.distance.SpearmanDistance

<a id="skfolio.distance.SpearmanDistance"></a>

### *class* skfolio.distance.SpearmanDistance(absolute=False, power=1)

Spearman Distance estimator.

The codependence is computed from the Spearman correlation to which is applied a
power and/or absolute transformation.
This codependence is then used to compute the distance matrix.
Some widely used distances are:

> * Standard angular distance = $\sqrt{0.5 \times (1 - corr)}$
> * Absolute angular distance = $\sqrt{1 - |corr|}$
> * Squared angular distance = $\sqrt{1 - corr^2}$
* **Parameters:**
  **absolute** *bool, default=False*
  : If this is set to True, the absolute transformation is applied to the
    correlation matrix.
    The default is `False`.

  **power** *float, default=1*
  : Exponent of the power transformation applied to the correlation matrix.
    The default value is `1`.
* **Attributes:**
  **codependence_** *ndarray of shape (n_assets, n_assets)*
  : Codependence matrix.

  **distance_** *ndarray of shape (n_assets, n_assets)*
  : Distance matrix.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.distance.SpearmanDistance.html.md#skfolio.distance.SpearmanDistance.fit)(X[, y])            | Fit the Spearman estimator.           |
|-------------------------------------------------------------------------|---------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distance.SpearmanDistance.html.md#skfolio.distance.SpearmanDistance.get_metadata_routing)() | Get metadata routing of this object.  |
| [`get_params`](https://skfolio.org/generated/skfolio.distance.SpearmanDistance.html.md#skfolio.distance.SpearmanDistance.get_params)([deep])     | Get parameters for this estimator.    |
| [`set_params`](https://skfolio.org/generated/skfolio.distance.SpearmanDistance.html.md#skfolio.distance.SpearmanDistance.set_params)(\*\*params) | Set the parameters of this estimator. |

### References

* <a id='r78e0a82fee0b-1'>**[1]**</a> “Building Diversified Portfolios that Outperform Out-of-Sample”, Lòpez de Prado, Journal of Portfolio Management (2016)

<a id="skfolio.distance.SpearmanDistance.fit"></a>

#### fit(X, y=None)

Fit the Spearman 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.
* **Returns:**
  **self** *SpearmanDistance*
  : Fitted estimator.

<a id="skfolio.distance.SpearmanDistance.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.distance.SpearmanDistance.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.distance.SpearmanDistance.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.

# generated/skfolio.distribution.BaseBivariateCopula.html.md

<a id="skfolio-distribution-basebivariatecopula"></a>

# skfolio.distribution.BaseBivariateCopula

<a id="skfolio.distribution.BaseBivariateCopula"></a>

### *class* skfolio.distribution.BaseBivariateCopula(random_state=None)

Base class for Bivariate Copula Estimators.

This abstract class defines the interface for bivariate copula models, including
methods for fitting, sampling, scoring, and computing partial derivatives.

* **Parameters:**
  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  [`fitted_repr`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.fitted_repr)
  : String representation of the fitted copula.

  [`lower_tail_dependence`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.lower_tail_dependence)
  : Theoretical lower tail dependence coefficient.

  [`n_params`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.n_params)
  : Number of model parameters.

  [`upper_tail_dependence`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.upper_tail_dependence)
  : Theoretical upper tail dependence coefficient.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.aic)(X)                                        | Compute the Akaike Information Criterion (AIC) for the model given data X.                                                                                     |
|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.bic)(X)                                        | Compute the Bayesian Information Criterion (BIC) for the model given data X.                                                                                   |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.cdf)(X)                                        | Compute the CDF of the bivariate copula.                                                                                                                       |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.fit)(X[, y])                                   | Fit the copula model.                                                                                                                                          |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.get_metadata_routing)()                        | Get metadata routing of this object.                                                                                                                           |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.get_params)([deep])                            | Get parameters for this estimator.                                                                                                                             |
| [`inverse_partial_derivative`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.inverse_partial_derivative)(X[, first_margin]) | Compute the inverse of the bivariate copula's partial derivative, commonly known as the inverse h-function [[1]](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#rb4c56b3b5247-1). |
| [`partial_derivative`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.partial_derivative)(X[, first_margin])         | Compute the h-function (partial derivative) for the bivariate copula with respect to a specified margin.                                                       |
| [`plot_pdf_2d`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.plot_pdf_2d)([title])                          | Plot a 2D contour of the estimated probability density function (PDF).                                                                                         |
| [`plot_pdf_3d`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.plot_pdf_3d)([title])                          | Plot a 3D surface of the estimated probability density function (PDF).                                                                                         |
| [`plot_tail_concentration`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.plot_tail_concentration)([X, title])           | Plot the tail concentration function.                                                                                                                          |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.sample)([n_samples])                           | Generate random samples from the bivariate copula using the inverse Rosenblatt transform.                                                                      |
| [`score`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.score)(X[, y])                                 | Compute the total log-likelihood under the model.                                                                                                              |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.score_samples)(X)                              | Compute the log-likelihood of each sample (log-pdf) under the model.                                                                                           |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.set_params)(\*\*params)                        | Set the parameters of this estimator.                                                                                                                          |
| [`tail_concentration`](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#skfolio.distribution.BaseBivariateCopula.tail_concentration)(quantiles)                 | Compute the tail concentration function for a set of quantiles.                                                                                                |

<a id="skfolio.distribution.BaseBivariateCopula.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='rfce2e11cf7cb-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.BaseBivariateCopula.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r710cbdf6a5d9-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.BaseBivariateCopula.cdf"></a>

#### *abstractmethod* cdf(X)

Compute the CDF of the bivariate copula.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **cdf** *ndarray of shape (n_observations,)*
  : CDF values for each observation in X.

<a id="skfolio.distribution.BaseBivariateCopula.fit"></a>

#### *abstractmethod* fit(X, y=None)

Fit the copula model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval [0, 1],
    having been transformed to uniform marginals.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *BaseBivariateCopula*
  : Returns the instance itself.

<a id="skfolio.distribution.BaseBivariateCopula.fitted_repr"></a>

#### *abstract property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.BaseBivariateCopula.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.distribution.BaseBivariateCopula.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.distribution.BaseBivariateCopula.inverse_partial_derivative"></a>

#### *abstractmethod* inverse_partial_derivative(X, first_margin=False)

Compute the inverse of the bivariate copula’s partial derivative, commonly
known as the inverse h-function [[1]](https://skfolio.org/generated/skfolio.distribution.BaseBivariateCopula.html.md#rb4c56b3b5247-1).

Let $C(u, v)$ be a bivariate copula. The h-function with respect to the
second margin is defined by

$$
h(u \mid v) \;=\; \frac{\partial\,C(u, v)}{\partial\,v},

$$

which is the conditional distribution of $U$ given $V = v$.
The **inverse h-function**, denoted $h^{-1}(p \mid v)$, is the unique
value $u \in [0,1]$ such that

$$
h(u \mid v) \;=\; p,
\quad \text{where } p \in [0,1].

$$

In practical terms, given $(p, v)$ in $[0, 1]^2$,
$h^{-1}(p \mid v)$ solves for the $u$ satisfying
$p = \partial C(u, v)/\partial v$.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(p, v)`, each in the interval `[0, 1]`.
    - The first column `p` corresponds to the value of the h-function.
    - The second column `v` is the conditioning variable.

  **first_margin** *bool, default=False*
  : If True, compute the inverse partial derivative with respect to the first
    margin `u`; otherwise, compute the inverse partial derivative with respect
    to the second margin `v`.
* **Returns:**
  **u** *ndarray of shape (n_observations,)*
  : A 1D-array of length `n_observations`, where each element is the computed
    $u = h^{-1}(p \mid v)$ for the corresponding pair in `X`.

### References

* <a id='rb4c56b3b5247-1'>**[1]**</a> “Multivariate Models and Dependence Concepts”, Joe, H. (1997)
* <a id='rb4c56b3b5247-2'>**[2]**</a> “An Introduction to Copulas”, Nelsen, R. B. (2006)

<a id="skfolio.distribution.BaseBivariateCopula.lower_tail_dependence"></a>

#### *abstract property* lower_tail_dependence

Theoretical lower tail dependence coefficient.

<a id="skfolio.distribution.BaseBivariateCopula.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.BaseBivariateCopula.partial_derivative"></a>

#### *abstractmethod* partial_derivative(X, first_margin=False)

Compute the h-function (partial derivative) for the bivariate copula
with respect to a specified margin.

The h-function with respect to the second margin represents the conditional
distribution function of $u$ given $v$:

$$
h(u \mid v) = \frac{\partial C(u,v)}{\partial v}

$$

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.

  **first_margin** *bool, default=False*
  : If True, compute the partial derivative with respect to the first
    margin `u`; otherwise, compute the partial derivative with respect to the
    second margin `v`.
* **Returns:**
  **p** *ndarray of shape (n_observations,)*
  : h-function values $h(u \mid v) \;=\; p$ for each observation in X.

<a id="skfolio.distribution.BaseBivariateCopula.plot_pdf_2d"></a>

#### plot_pdf_2d(title=None)

Plot a 2D contour of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
contour plot of the PDF.
Contour levels are limited to the 97th quantile to avoid extreme densities.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the 2D contour plot of the PDF.

<a id="skfolio.distribution.BaseBivariateCopula.plot_pdf_3d"></a>

#### plot_pdf_3d(title=None)

Plot a 3D surface of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
3D surface plot of the PDF using Plotly.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing a 3D surface plot of the PDF.

<a id="skfolio.distribution.BaseBivariateCopula.plot_tail_concentration"></a>

#### plot_tail_concentration(X=None, title=None)

Plot the tail concentration function.

This method computes the tail concentration function at 100 evenly spaced
quantile levels between 0.005 and 0.995.
The plot displays the concentration values on the y-axis and the quantile levels
on the x-axis.

The tail concentration is defined as:
: - Lower tail: λ_L(q) = P(U₂ ≤ q | U₁ ≤ q)
  - Upper tail: λ_U(q) = P(U₂ ≥ q | U₁ ≥ q)

where U₁ and U₂ are the pseudo-observations of the first and second variables,
respectively.

* **Parameters:**
  **X** *array-like of shape (n_samples, 2), optional*
  : If provided, it is used to plot the empirical tail concentration for
    comparison versus the model tail concentration.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the tail concentration curve.

### References

* <a id='rbbe7df47a7c7-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.BaseBivariateCopula.sample"></a>

#### sample(n_samples=1)

Generate random samples from the bivariate copula using the inverse
Rosenblatt transform.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` are uniform marginals in the
    interval `[0, 1]`.

<a id="skfolio.distribution.BaseBivariateCopula.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.BaseBivariateCopula.score_samples"></a>

#### *abstractmethod* score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : The log-likelihood of each sample under the fitted copula.

<a id="skfolio.distribution.BaseBivariateCopula.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.

<a id="skfolio.distribution.BaseBivariateCopula.tail_concentration"></a>

#### tail_concentration(quantiles)

Compute the tail concentration function for a set of quantiles.

The tail concentration function is defined as follows:
: - For quantiles q ≤ 0.5:
    : C(q) = P(U ≤ q, V ≤ q) / q
  - For quantiles q > 0.5:
    : C(q) = (1 - 2q + P(U ≤ q, V ≤ q)) / (1 - q)

where U and V are the pseudo-observations of the first and second variables,
respectively. This function returns the concentration values for each q
provided.

* **Parameters:**
  **quantiles** *ndarray of shape (n_quantiles,)*
  : A 1D array of quantile levels (values between 0 and 1) at which to compute
    the tail concentration.
* **Returns:**
  **concentration** *ndarray of shape (n_quantiles,)*
  : The computed tail concentration values corresponding to each quantile.
* **Raises:**
  ValueError
  : If any value in `quantiles` is not in the interval [0, 1].

### References

* <a id='rdc1fc86ea709-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.BaseBivariateCopula.upper_tail_dependence"></a>

#### *abstract property* upper_tail_dependence

Theoretical upper tail dependence coefficient.

# generated/skfolio.distribution.BaseDistribution.html.md

<a id="skfolio-distribution-basedistribution"></a>

# skfolio.distribution.BaseDistribution

<a id="skfolio.distribution.BaseDistribution"></a>

### *class* skfolio.distribution.BaseDistribution(random_state=None)

Base Distribution Estimator.

This abstract class serves as a foundation for distribution models in skfolio.

random_state *int, RandomState instance or None, default=None*
: Seed or random state to ensure reproducibility.

* **Attributes:**
  [`fitted_repr`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.fitted_repr)
  : String representation of the fitted model.

  [`n_params`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.n_params)
  : Number of model parameters.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.aic)(X)                 | Compute the Akaike Information Criterion (AIC) for the model given data X.   |
|-------------------------------------------------------------------------|------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.bic)(X)                 | Compute the Bayesian Information Criterion (BIC) for the model given data X. |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.fit)(X[, y])            | Fit the univariate distribution model.                                       |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.get_metadata_routing)() | Get metadata routing of this object.                                         |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.get_params)([deep])     | Get parameters for this estimator.                                           |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.sample)([n_samples])    | Generate random samples from the fitted model.                               |
| [`score`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.score)(X[, y])          | Compute the total log-likelihood under the model.                            |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.score_samples)(X)       | Compute the log-likelihood of each sample (log-pdf) under the model.         |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.BaseDistribution.html.md#skfolio.distribution.BaseDistribution.set_params)(\*\*params) | Set the parameters of this estimator.                                        |

<a id="skfolio.distribution.BaseDistribution.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r731676aa151f-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.BaseDistribution.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r5bfb00f595f0-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.BaseDistribution.fit"></a>

#### *abstractmethod* fit(X, y=None)

Fit the univariate distribution model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *BaseDistribution*
  : Returns the instance itself.

<a id="skfolio.distribution.BaseDistribution.fitted_repr"></a>

#### *abstract property* fitted_repr

String representation of the fitted model.

<a id="skfolio.distribution.BaseDistribution.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.distribution.BaseDistribution.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.distribution.BaseDistribution.n_params"></a>

#### *abstract property* n_params

Number of model parameters.

<a id="skfolio.distribution.BaseDistribution.sample"></a>

#### sample(n_samples=1)

Generate random samples from the fitted model.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 1)*
  : List of samples.

<a id="skfolio.distribution.BaseDistribution.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.BaseDistribution.score_samples"></a>

#### *abstractmethod* score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : Log-likelihood values for each observation in X.

<a id="skfolio.distribution.BaseDistribution.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.

# generated/skfolio.distribution.BaseMultivariateDist.html.md

<a id="skfolio-distribution-basemultivariatedist"></a>

# skfolio.distribution.BaseMultivariateDist

<a id="skfolio.distribution.BaseMultivariateDist"></a>

### *class* skfolio.distribution.BaseMultivariateDist(random_state=None)

Base class for Multivariate Distribution Estimators.

This abstract class defines the interface for multivariate distribution models.

* **Parameters:**
  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  [`fitted_repr`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.fitted_repr)
  : String representation of the fitted copula.

  [`n_params`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.n_params)
  : Number of model parameters.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.aic)(X)                                      | Compute the Akaike Information Criterion (AIC) for the model given data X.                                                                                          |
|----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.bic)(X)                                      | Compute the Bayesian Information Criterion (BIC) for the model given data X.                                                                                        |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.fit)(X[, y])                                 | Fit the multivariate distribution model.                                                                                                                            |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.get_metadata_routing)()                      | Get metadata routing of this object.                                                                                                                                |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.get_params)([deep])                          | Get parameters for this estimator.                                                                                                                                  |
| [`plot_scatter_matrix`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.plot_scatter_matrix)([X, conditioning, ...]) | Plot the vine copula scatter matrix by generating samples from the fitted distribution model and comparing it versus the empirical distribution of `X` if provided. |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.sample)([n_samples, conditioning])           | Generate random samples from the distribution model.                                                                                                                |
| [`score`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.score)(X[, y])                               | Compute the total log-likelihood under the model.                                                                                                                   |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.score_samples)(X)                            | Compute the log-likelihood of each sample (log-pdf) under the distribution model.                                                                                   |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.BaseMultivariateDist.html.md#skfolio.distribution.BaseMultivariateDist.set_params)(\*\*params)                      | Set the parameters of this estimator.                                                                                                                               |

<a id="skfolio.distribution.BaseMultivariateDist.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r646ba6e97556-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.BaseMultivariateDist.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r01b6a2a128e4-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.BaseMultivariateDist.fit"></a>

#### *abstractmethod* fit(X, y=None)

Fit the multivariate distribution model.

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

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *BaseMultivariateDist*
  : Returns the instance itself.

<a id="skfolio.distribution.BaseMultivariateDist.fitted_repr"></a>

#### *abstract property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.BaseMultivariateDist.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.distribution.BaseMultivariateDist.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.distribution.BaseMultivariateDist.n_params"></a>

#### *abstract property* n_params

Number of model parameters.

<a id="skfolio.distribution.BaseMultivariateDist.plot_scatter_matrix"></a>

#### plot_scatter_matrix(X=None, conditioning=None, n_samples=1000, title='Scatter Matrix')

Plot the vine copula scatter matrix by generating samples from the fitted
distribution model and comparing it versus the empirical distribution of `X` if
provided.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_assets), optional*
  : If provided, it is used to plot the empirical scatter matrix for
    comparison versus the vine copula scatter matrix.

  **conditioning** *dict[int | str, float | tuple[float, float] | array-like], optional*
  : A dictionary specifying conditioning information for one or more assets.
    The dictionary keys are asset indices or names, and the values define how
    the samples are conditioned for that asset. Three types of conditioning
    values are supported:
    1. **Fixed value (float):**
       If a float is provided, all samples are generated under the condition
       that the asset takes exactly that value.
    2. **Bounds (tuple of two floats):**
       If a tuple `(min_value, max_value)` is provided, samples are generated
       under the condition that the asset’s value falls within the specified
       bounds. Use `-np.Inf` for no lower bound or `np.Inf` for no upper bound.
    3. **Array-like (1D array):**
       If an array-like of length `n_samples` is provided, each sample is
       conditioned on the corresponding value in the array for that asset.

  **n_samples** *int, default=1000*
  : Number of samples used to control the density and readability of the plot.
    If `X` is provided and contains more than `n_samples` rows, a random
    subsample of size `n_samples` is selected. Conversely, if `X` has fewer
    rows than `n_samples`, the value is adjusted to match the number of rows in
    `X` to ensure balanced visualization.

  **title** *str, default=”Scatter Matrix”*
  : The title for the plot.
* **Returns:**
  **fig** *plotly.graph_objects.Figure*
  : A figure object containing the scatter matrix.

<a id="skfolio.distribution.BaseMultivariateDist.sample"></a>

#### *abstractmethod* sample(n_samples=1, conditioning=None)

Generate random samples from the distribution model.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.

  **conditioning** *dict[int | str, float | tuple[float, float] | array-like], optional*
  : A dictionary specifying conditioning information for one or more assets.
    The dictionary keys are asset indices or names, and the values define how
    the samples are conditioned for that asset. Three types of conditioning
    values are supported:
    1. **Fixed value (float):**
       If a float is provided, all samples are generated under the condition
       that the asset takes exactly that value.
    2. **Bounds (tuple of two floats):**
       If a tuple `(min_value, max_value)` is provided, samples are generated
       under the condition that the asset’s value falls within the specified
       bounds. Use `-np.Inf` for no lower bound or `np.Inf` for no upper bound.
    3. **Array-like (1D array):**
       If an array-like of length `n_samples` is provided, each sample is
       conditioned on the corresponding value in the array for that asset.
* **Returns:**
  **X** *array-like of shape (n_samples, n_assets)*
  : A two-dimensional array where each row is a multivariate observation sampled
    from the fitted distribution model.

<a id="skfolio.distribution.BaseMultivariateDist.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.BaseMultivariateDist.score_samples"></a>

#### *abstractmethod* score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the distribution
model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : The log-likelihood of each sample under the fitted distribution model.

<a id="skfolio.distribution.BaseMultivariateDist.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.

# generated/skfolio.distribution.BaseUnivariateDist.html.md

<a id="skfolio-distribution-baseunivariatedist"></a>

# skfolio.distribution.BaseUnivariateDist

<a id="skfolio.distribution.BaseUnivariateDist"></a>

### *class* skfolio.distribution.BaseUnivariateDist(random_state=None)

Base Univariate Distribution Estimator.

This abstract class serves as a foundation for univariate distribution models
based on scipy.

random_state *int, RandomState instance or None, default=None*
: Seed or random state to ensure reproducibility.

* **Attributes:**
  [`fitted_repr`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.fitted_repr)
  : String representation of the fitted univariate distribution.

  [`n_params`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.n_params)
  : Number of model parameters.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.aic)(X)                 | Compute the Akaike Information Criterion (AIC) for the model given data X.             |
|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.bic)(X)                 | Compute the Bayesian Information Criterion (BIC) for the model given data X.           |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.cdf)(X)                 | Compute the cumulative distribution function (CDF) for the given data.                 |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.fit)(X[, y])            | Fit the univariate distribution model.                                                 |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.get_metadata_routing)() | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.get_params)([deep])     | Get parameters for this estimator.                                                     |
| [`plot_pdf`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.plot_pdf)([X, title])   | Plot the probability density function (PDF).                                           |
| [`ppf`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.ppf)(X)                 | Compute the percent point function (inverse of the CDF) for the given                  |
| [`qq_plot`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.qq_plot)(X[, title])    | Plot the empirical quantiles of the sample X versus the quantiles of the fitted model. |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.sample)([n_samples])    | Generate random samples from the fitted distribution.                                  |
| [`score`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.score)(X[, y])          | Compute the total log-likelihood under the model.                                      |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.score_samples)(X)       | Compute the log-likelihood of each sample (log-pdf) under the model.                   |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.BaseUnivariateDist.html.md#skfolio.distribution.BaseUnivariateDist.set_params)(\*\*params) | Set the parameters of this estimator.                                                  |

<a id="skfolio.distribution.BaseUnivariateDist.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='ra226cce45484-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.BaseUnivariateDist.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r7ba9e57e1e62-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.BaseUnivariateDist.cdf"></a>

#### cdf(X)

Compute the cumulative distribution function (CDF) for the given data.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : Data points at which to evaluate the CDF.
* **Returns:**
  **cdf** *ndarray of shape (n_observations, 1)*
  : The CDF evaluated at each data point.

<a id="skfolio.distribution.BaseUnivariateDist.fit"></a>

#### *abstractmethod* fit(X, y=None)

Fit the univariate distribution model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : The input data. X must contain a single column.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *BaseUnivariateDist*
  : Returns the instance itself.

<a id="skfolio.distribution.BaseUnivariateDist.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted univariate distribution.

<a id="skfolio.distribution.BaseUnivariateDist.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.distribution.BaseUnivariateDist.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.distribution.BaseUnivariateDist.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.BaseUnivariateDist.plot_pdf"></a>

#### plot_pdf(X=None, title=None)

Plot the probability density function (PDF).

* **Parameters:**
  **X** *array-like of shape (n_samples, 1), optional*
  : If provided, it is used to plot the empirical data KDE for comparison
    versus the model PDF.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    model’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the PDF plot.

<a id="skfolio.distribution.BaseUnivariateDist.ppf"></a>

#### ppf(X)

Compute the percent point function (inverse of the CDF) for the given
: probabilities.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : Probabilities for which to compute the corresponding quantiles.
* **Returns:**
  **ppf** *ndarray of shape (n_observations, 1)*
  : The quantiles corresponding to the given probabilities.

<a id="skfolio.distribution.BaseUnivariateDist.qq_plot"></a>

#### qq_plot(X, title=None)

Plot the empirical quantiles of the sample X versus the quantiles of the
fitted model.

* **Parameters:**
  **X** *array-like of shape (n_samples, 1), optional*
  : Used to plot the empirical quantiles for comparison versus the model
    quantiles.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    model’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the PDF plot.

<a id="skfolio.distribution.BaseUnivariateDist.sample"></a>

#### sample(n_samples=1)

Generate random samples from the fitted distribution.

Currently, this is implemented only for gaussian and tophat kernels.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 1)*
  : List of samples.

<a id="skfolio.distribution.BaseUnivariateDist.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.BaseUnivariateDist.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : An array of points at which to evaluate the log-probability density.
    The data should be a single feature column.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : Log-likelihood values for each observation in X.

<a id="skfolio.distribution.BaseUnivariateDist.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.

# generated/skfolio.distribution.ClaytonCopula.html.md

<a id="skfolio-distribution-claytoncopula"></a>

# skfolio.distribution.ClaytonCopula

<a id="skfolio.distribution.ClaytonCopula"></a>

### *class* skfolio.distribution.ClaytonCopula(itau=True, kendall_tau=None, tolerance=0.0001, random_state=None)

Bivariate Clayton Copula Estimation.

The Clayton copula is an Archimedean copula characterized by strong lower tail
dependence and little to no upper tail dependence.

In its unrotated form, it is used for modeling extreme co-movements in the lower
tail (i.e. simultaneous extreme losses).

Rotations allow the copula to be adapted for different types of tail dependence:
: - A 180° rotation captures extreme co-movements in the upper tail (i.e.
    simultaneous extreme gains).
  - A 90° rotation captures scenarios where one variable exhibits extreme gains
    while the other shows extreme losses.
  - A 270° rotation captures the opposite scenario, where one variable experiences
    extreme losses while the other suffers extreme gains.

It is defined by:

$$
C_{\theta}(u, v) = \Bigl(u^{-\theta} + v^{-\theta} - 1\Bigr)^{-1/\theta}

$$

where $\theta > 0$ is the dependence parameter. As $\theta \to 0$,
the Clayton copula converges to the independence copula. Larger values of
$\theta$ result in stronger lower-tail dependence.

#### NOTE
Rotations are needed for Archimedean copulas (e.g., Joe, Gumbel, Clayton)
because their parameters only model positive dependence, and they exhibit
asymmetric tail behavior. To model negative dependence, one uses rotations
to “flip” the copula’s tail dependence.

* **Parameters:**
  **itau** *bool, default=True*
  : If True, $\theta$ is estimated using the Kendall’s tau inversion method;
    otherwise, the Maximum Likelihood Estimation (MLE) method is used. The MLE is
    slower but more accurate.

  **kendall_tau** *float, optional*
  : If `itau` is True and `kendall_tau` is provided, this value is used;
    otherwise, it is computed.

  **tolerance** *float, default=1e-4*
  : Convergence tolerance for the MLE optimization.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  **theta_** *float*
  : Fitted theta coefficient $\theta$ > 0.

  **rotation_** *CopulaRotation*
  : Fitted rotation of the copula.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.aic)(X)                                        | Compute the Akaike Information Criterion (AIC) for the model given data X.                                       |
|------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.bic)(X)                                        | Compute the Bayesian Information Criterion (BIC) for the model given data X.                                     |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.cdf)(X)                                        | Compute the CDF of the bivariate Clayton copula.                                                                 |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.fit)(X[, y])                                   | Fit the Bivariate Clayton Copula.                                                                                |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.get_metadata_routing)()                        | Get metadata routing of this object.                                                                             |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.get_params)([deep])                            | Get parameters for this estimator.                                                                               |
| [`inverse_partial_derivative`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.inverse_partial_derivative)(X[, first_margin]) | Compute the inverse of the bivariate copula's partial derivative, commonly known as the inverse h-function.      |
| [`partial_derivative`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.partial_derivative)(X[, first_margin])         | Compute the h-function (partial derivative) for the bivariate Clayton copula with respect to a specified margin. |
| [`plot_pdf_2d`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.plot_pdf_2d)([title])                          | Plot a 2D contour of the estimated probability density function (PDF).                                           |
| [`plot_pdf_3d`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.plot_pdf_3d)([title])                          | Plot a 3D surface of the estimated probability density function (PDF).                                           |
| [`plot_tail_concentration`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.plot_tail_concentration)([X, title])           | Plot the tail concentration function.                                                                            |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.sample)([n_samples])                           | Generate random samples from the bivariate copula using the inverse Rosenblatt transform.                        |
| [`score`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.score)(X[, y])                                 | Compute the total log-likelihood under the model.                                                                |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.score_samples)(X)                              | Compute the log-likelihood of each sample (log-pdf) under the model.                                             |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.set_params)(\*\*params)                        | Set the parameters of this estimator.                                                                            |
| [`tail_concentration`](https://skfolio.org/generated/skfolio.distribution.ClaytonCopula.html.md#skfolio.distribution.ClaytonCopula.tail_concentration)(quantiles)                 | Compute the tail concentration function for a set of quantiles.                                                  |

### References

* <a id='r080a40226a87-1'>**[1]**</a> “An Introduction to Copulas (2nd ed.)”, Nelsen (2006)
* <a id='r080a40226a87-2'>**[2]**</a> “Multivariate Models and Dependence Concepts”, Joe, Chapman & Hall (1997)
* <a id='r080a40226a87-3'>**[3]**</a> “Quantitative Risk Management: Concepts, Techniques and Tools”, McNeil, Frey & Embrechts (2005)
* <a id='r080a40226a87-4'>**[4]**</a> “The t Copula and Related Copulas”, Demarta & McNeil (2005)
* <a id='r080a40226a87-5'>**[5]**</a> “Copula Methods in Finance”, Cherubini, Luciano & Vecchiato (2004)

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution import ClaytonCopula, compute_pseudo_observations
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>> X = X[["AAPL", "JPM"]]
>>>
>>> # Convert returns to pseudo observation in the interval [0,1]
>>> X = compute_pseudo_observations(X)
>>>
>>> # Initialize the Copula estimator
>>> model = ClaytonCopula()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
ClaytonCopula(...)
>>>
>>> # Display the fitted parameter and tail dependence coefficients
>>> print(model.fitted_repr)
ClaytonCopula(theta=0.54, rot=0°)
>>> print(model.lower_tail_dependence)
0.276...
>>> print(model.upper_tail_dependence)
0
>>>
>>> # Compute the log-likelihood, total log-likelihood, CDF, Partial Derivative,
>>> # Inverse Partial Derivative, AIC, and BIC
>>> log_likelihood = model.score_samples(X)
>>> score = model.score(X)
>>> cdf = model.cdf(X)
>>> p = model.partial_derivative(X)
>>> u = model.inverse_partial_derivative(X)
>>> aic = model.aic(X)
>>> bic = model.bic(X)
>>>
>>> # Generate 5 new samples
>>> samples = model.sample(n_samples=5)
>>>
>>> # Plot the tail concentration function.
>>> fig = model.plot_tail_concentration()
>>>
>>> # Plot a 2D contour of the estimated PDF.
>>> fig = model.plot_pdf_2d()
>>>
>>> # Plot a 3D surface of the estimated PDF.
>>> fig = model.plot_pdf_3d()
```

<a id="skfolio.distribution.ClaytonCopula.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r9af55c15f928-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.ClaytonCopula.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r114301a61d6d-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.ClaytonCopula.cdf"></a>

#### cdf(X)

Compute the CDF of the bivariate Clayton copula.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **cdf** *ndarray of shape (n_observations,)*
  : CDF values for each observation in X.

<a id="skfolio.distribution.ClaytonCopula.fit"></a>

#### fit(X, y=None)

Fit the Bivariate Clayton Copula.

If `itau` is True, estimates $\theta$ using Kendall’s tau inversion.
Otherwise, uses MLE by maximizing the log-likelihood.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval [0, 1],
    having been transformed to uniform marginals.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *object*
  : Returns the instance itself.

<a id="skfolio.distribution.ClaytonCopula.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.ClaytonCopula.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.distribution.ClaytonCopula.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.distribution.ClaytonCopula.inverse_partial_derivative"></a>

#### inverse_partial_derivative(X, first_margin=False)

Compute the inverse of the bivariate copula’s partial derivative, commonly
known as the inverse h-function.

Let $C(u, v)$ be a bivariate copula. The h-function with respect to the
second margin is defined by

$$
h(u \mid v) \;=\; \frac{\partial\,C(u, v)}{\partial\,v},

$$

which is the conditional distribution of $U$ given $V = v$.
The **inverse h-function**, denoted $h^{-1}(p \mid v)$, is the unique
value $u \in [0,1]$ such that

$$
h(u \mid v) \;=\; p,
\quad \text{where } p \in [0,1].

$$

In practical terms, given $(p, v)$ in $[0, 1]^2$,
$h^{-1}(p \mid v)$ solves for the $u$ satisfying
$p = \partial C(u, v)/\partial v$.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(p, v)`, each in the interval `[0, 1]`.
    - The first column `p` corresponds to the value of the h-function.
    - The second column `v` is the conditioning variable.

  **first_margin** *bool, default=False*
  : If True, compute the inverse partial derivative with respect to the first
    margin `u`; otherwise, compute the inverse partial derivative with respect
    to the second margin `v`.
* **Returns:**
  **u** *ndarray of shape (n_observations,)*
  : A 1D-array of length `n_observations`, where each element is the computed
    $u = h^{-1}(p \mid v)$ for the corresponding pair in `X`.

<a id="skfolio.distribution.ClaytonCopula.lower_tail_dependence"></a>

#### *property* lower_tail_dependence

Theoretical lower tail dependence coefficient.

<a id="skfolio.distribution.ClaytonCopula.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.ClaytonCopula.partial_derivative"></a>

#### partial_derivative(X, first_margin=False)

Compute the h-function (partial derivative) for the bivariate Clayton copula
with respect to a specified margin.

The h-function with respect to the second margin represents the conditional
distribution function of $u$ given $v$:

$$
\begin{aligned}
C(u,v)&=\Bigl(u^{-\theta}+v^{-\theta}-1\Bigr)^{-1/\theta},\\[6pt]
h(u \mid v)
  &= \frac{\partial C(u,v)}{\partial v}
  = \Bigl(u^{-\theta}+v^{-\theta}-1\Bigr)^{-1/\theta-1}\,v^{-\theta-1}.
\end{aligned}

$$

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.

  **first_margin** *bool, default=False*
  : If True, compute the partial derivative with respect to the first
    margin `u`; otherwise, compute the partial derivative with respect to the
    second margin `v`.
* **Returns:**
  **p** *ndarray of shape (n_observations,)*
  : h-function values $h(u \mid v)$ for each observation in X.

<a id="skfolio.distribution.ClaytonCopula.plot_pdf_2d"></a>

#### plot_pdf_2d(title=None)

Plot a 2D contour of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
contour plot of the PDF.
Contour levels are limited to the 97th quantile to avoid extreme densities.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the 2D contour plot of the PDF.

<a id="skfolio.distribution.ClaytonCopula.plot_pdf_3d"></a>

#### plot_pdf_3d(title=None)

Plot a 3D surface of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
3D surface plot of the PDF using Plotly.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing a 3D surface plot of the PDF.

<a id="skfolio.distribution.ClaytonCopula.plot_tail_concentration"></a>

#### plot_tail_concentration(X=None, title=None)

Plot the tail concentration function.

This method computes the tail concentration function at 100 evenly spaced
quantile levels between 0.005 and 0.995.
The plot displays the concentration values on the y-axis and the quantile levels
on the x-axis.

The tail concentration is defined as:
: - Lower tail: λ_L(q) = P(U₂ ≤ q | U₁ ≤ q)
  - Upper tail: λ_U(q) = P(U₂ ≥ q | U₁ ≥ q)

where U₁ and U₂ are the pseudo-observations of the first and second variables,
respectively.

* **Parameters:**
  **X** *array-like of shape (n_samples, 2), optional*
  : If provided, it is used to plot the empirical tail concentration for
    comparison versus the model tail concentration.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the tail concentration curve.

### References

* <a id='rc2c6af168988-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.ClaytonCopula.sample"></a>

#### sample(n_samples=1)

Generate random samples from the bivariate copula using the inverse
Rosenblatt transform.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` are uniform marginals in the
    interval `[0, 1]`.

<a id="skfolio.distribution.ClaytonCopula.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.ClaytonCopula.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

For Clayton, the PDF is given by:

$$
c(u,v) = (\theta+1)\,\Bigl(u^{-\theta}+v^{-\theta}-1\Bigr)^{-\frac{1}{\theta}-2}\,(u\,v)^{-\theta-1}

$$

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : The log-likelihood of each sample under the fitted copula.

<a id="skfolio.distribution.ClaytonCopula.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.

<a id="skfolio.distribution.ClaytonCopula.tail_concentration"></a>

#### tail_concentration(quantiles)

Compute the tail concentration function for a set of quantiles.

The tail concentration function is defined as follows:
: - For quantiles q ≤ 0.5:
    : C(q) = P(U ≤ q, V ≤ q) / q
  - For quantiles q > 0.5:
    : C(q) = (1 - 2q + P(U ≤ q, V ≤ q)) / (1 - q)

where U and V are the pseudo-observations of the first and second variables,
respectively. This function returns the concentration values for each q
provided.

* **Parameters:**
  **quantiles** *ndarray of shape (n_quantiles,)*
  : A 1D array of quantile levels (values between 0 and 1) at which to compute
    the tail concentration.
* **Returns:**
  **concentration** *ndarray of shape (n_quantiles,)*
  : The computed tail concentration values corresponding to each quantile.
* **Raises:**
  ValueError
  : If any value in `quantiles` is not in the interval [0, 1].

### References

* <a id='re2eb53588924-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.ClaytonCopula.upper_tail_dependence"></a>

#### *property* upper_tail_dependence

Theoretical upper tail dependence coefficient.

# generated/skfolio.distribution.CopulaRotation.html.md

<a id="skfolio-distribution-copularotation"></a>

# skfolio.distribution.CopulaRotation

<a id="skfolio.distribution.CopulaRotation"></a>

### *class* skfolio.distribution.CopulaRotation(\*values)

Enum representing the rotation (in degrees) to apply to a bivariate copula.

It follows the standard clockwise convention:

- `CopulaRotation.R0` (0°): $(u, v) \mapsto (u, v)$
- `CopulaRotation.R90` (90°): $(u, v) \mapsto (v,\, 1 - u)$
- `CopulaRotation.R180` (180°): $(u, v) \mapsto (1 - u,\, 1 - v)$
- `CopulaRotation.R270` (270°): $(u, v) \mapsto (1 - v,\, u)$

* **Attributes:**
  **R0** *int*
  : No rotation (0°).

  **R90** *int*
  : 90° rotation.

  **R180** *int*
  : 180° rotation.

  **R270** *int*
  : 270° rotation.

# generated/skfolio.distribution.DependenceMethod.html.md

<a id="skfolio-distribution-dependencemethod"></a>

# skfolio.distribution.DependenceMethod

<a id="skfolio.distribution.DependenceMethod"></a>

### *class* skfolio.distribution.DependenceMethod(\*values)

Enumeration of methods to measure bivariate dependence.

* **Attributes:**
  **KENDALL_TAU**
  : Use Kendall’s tau correlation coefficient.

  **MUTUAL_INFORMATION**
  : Use mutual information estimated via a k-nearest neighbors method.

  **WASSERSTEIN_DISTANCE**
  : Use the Wasserstein (Earth Mover’s) distance.

<a id="skfolio.distribution.DependenceMethod.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.distribution.Gaussian.html.md

<a id="skfolio-distribution-gaussian"></a>

# skfolio.distribution.Gaussian

<a id="skfolio.distribution.Gaussian"></a>

### *class* skfolio.distribution.Gaussian(loc=None, scale=None, random_state=None)

Gaussian Distribution Estimation.

This estimator fits a univariate normal (Gaussian) distribution to the input data.

The probability density function is:

$$
f(x) = \frac{\exp(-x^2/2)}{\sqrt{2\pi}}
$$

The probability density above is defined in the “standardized” form. To shift
and/or scale the distribution use the loc and scale parameters. Specifically,
`pdf(x, loc, scale)` is equivalent to `pdf(y) / scale` with `y = (x - loc) / scale`.

For more information, you can refer to the [scipy documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.norm.html#scipy.stats.norm)

* **Parameters:**
  **loc** *float, optional*
  : If provided, the location parameter (mean) is fixed to this value.
    Otherwise, it is estimated from the data.

  **scale** *float, optional*
  : If provided, the scale parameter (standard deviation) is fixed to this value.
    Otherwise, it is estimated from the data.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  **loc_** *float*
  : The fitted location (mean) of the distribution.

  **scale_** *float*
  : The fitted scale (standard deviation) of the distribution.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.aic)(X)                 | Compute the Akaike Information Criterion (AIC) for the model given data X.             |
|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.bic)(X)                 | Compute the Bayesian Information Criterion (BIC) for the model given data X.           |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.cdf)(X)                 | Compute the cumulative distribution function (CDF) for the given data.                 |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.fit)(X[, y])            | Fit the univariate Gaussian distribution model.                                        |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.get_metadata_routing)() | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.get_params)([deep])     | Get parameters for this estimator.                                                     |
| [`plot_pdf`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.plot_pdf)([X, title])   | Plot the probability density function (PDF).                                           |
| [`ppf`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.ppf)(X)                 | Compute the percent point function (inverse of the CDF) for the given                  |
| [`qq_plot`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.qq_plot)(X[, title])    | Plot the empirical quantiles of the sample X versus the quantiles of the fitted model. |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.sample)([n_samples])    | Generate random samples from the fitted distribution.                                  |
| [`score`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.score)(X[, y])          | Compute the total log-likelihood under the model.                                      |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.score_samples)(X)       | Compute the log-likelihood of each sample (log-pdf) under the model.                   |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.Gaussian.html.md#skfolio.distribution.Gaussian.set_params)(\*\*params) | Set the parameters of this estimator.                                                  |

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_index
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution.univariate import Gaussian
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_index()
>>> X = prices_to_returns(prices)
>>>
>>> # Initialize the Gaussian estimator.
>>> model = Gaussian()
>>>
>>> # Fit the Gaussian model to the data.
>>> model.fit(X)
Gaussian(...)
>>>
>>> # Display the fitted parameters.
>>> print(model.fitted_repr)
Gaussian(loc=0.00035, scale=0.012)
>>>
>>> # Compute the log-likelihood, total log-likelihood, CDF, PPF, AIC, and BIC
>>> log_likelihood = model.score_samples(X)
>>> score = model.score(X)
>>> cdf = model.cdf(X)
>>> ppf = model.ppf([0.01, 0.05, 0.5, 0.95, 0.99])
>>> aic = model.aic(X)
>>> bic = model.bic(X)
>>>
>>> # Generate 5 new samples from the fitted Gaussian distribution.
>>> samples = model.sample(n_samples=5)
>>>
>>> # Plot the estimated probability density function (PDF).
>>> fig = model.plot_pdf()
```

<a id="skfolio.distribution.Gaussian.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r8a74d37b3e95-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.Gaussian.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r0f107fc8b41c-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.Gaussian.cdf"></a>

#### cdf(X)

Compute the cumulative distribution function (CDF) for the given data.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : Data points at which to evaluate the CDF.
* **Returns:**
  **cdf** *ndarray of shape (n_observations, 1)*
  : The CDF evaluated at each data point.

<a id="skfolio.distribution.Gaussian.fit"></a>

#### fit(X, y=None)

Fit the univariate Gaussian distribution model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : The input data. X must contain a single column.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *Gaussian*
  : Returns the instance itself.

<a id="skfolio.distribution.Gaussian.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted univariate distribution.

<a id="skfolio.distribution.Gaussian.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.distribution.Gaussian.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.distribution.Gaussian.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.Gaussian.plot_pdf"></a>

#### plot_pdf(X=None, title=None)

Plot the probability density function (PDF).

* **Parameters:**
  **X** *array-like of shape (n_samples, 1), optional*
  : If provided, it is used to plot the empirical data KDE for comparison
    versus the model PDF.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    model’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the PDF plot.

<a id="skfolio.distribution.Gaussian.ppf"></a>

#### ppf(X)

Compute the percent point function (inverse of the CDF) for the given
: probabilities.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : Probabilities for which to compute the corresponding quantiles.
* **Returns:**
  **ppf** *ndarray of shape (n_observations, 1)*
  : The quantiles corresponding to the given probabilities.

<a id="skfolio.distribution.Gaussian.qq_plot"></a>

#### qq_plot(X, title=None)

Plot the empirical quantiles of the sample X versus the quantiles of the
fitted model.

* **Parameters:**
  **X** *array-like of shape (n_samples, 1), optional*
  : Used to plot the empirical quantiles for comparison versus the model
    quantiles.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    model’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the PDF plot.

<a id="skfolio.distribution.Gaussian.sample"></a>

#### sample(n_samples=1)

Generate random samples from the fitted distribution.

Currently, this is implemented only for gaussian and tophat kernels.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 1)*
  : List of samples.

<a id="skfolio.distribution.Gaussian.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.Gaussian.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : An array of points at which to evaluate the log-probability density.
    The data should be a single feature column.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : Log-likelihood values for each observation in X.

<a id="skfolio.distribution.Gaussian.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.

# generated/skfolio.distribution.GaussianCopula.html.md

<a id="skfolio-distribution-gaussiancopula"></a>

# skfolio.distribution.GaussianCopula

<a id="skfolio.distribution.GaussianCopula"></a>

### *class* skfolio.distribution.GaussianCopula(itau=True, kendall_tau=None, tolerance=0.0001, random_state=None)

Bivariate Gaussian Copula Estimation.

The bivariate Gaussian copula is defined as:

$$
C_{\rho}(u, v) = \Phi_2\left(\Phi^{-1}(u), \Phi^{-1}(v) ; \rho\right)

$$

where:
: - $\Phi_2$ is the bivariate normal CDF with correlation $\rho$.
  - $\Phi$ is the standard normal CDF and $\Phi^{-1}$ its quantile function.
  - $\rho \in (-1, 1)$ is the correlation coefficient.

#### NOTE
Rotations are not needed for elliptical copula (e.g., Gaussian or Student-t)
because its correlation parameter $\rho \in (-1, 1)$ naturally covers
both positive and negative dependence, and they exhibit symmetric tail behavior.

* **Parameters:**
  **itau** *bool, default=True*
  : If True, $\rho$ is estimated using the Kendall’s tau inversion method;
    otherwise, we use the MLE (Maximum Likelihood Estimation) method. The MLE is
    slower but more accurate.

  **kendall_tau** *float, optional*
  : If `itau` is True and `kendall_tau` is provided, this
    value is used; otherwise, it is computed.

  **tolerance** *float, default=1e-4*
  : Convergence tolerance for the MLE optimization.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  **rho_** *float*
  : Fitted parameter ($\rho$) in [-1, 1].

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.aic)(X)                                        | Compute the Akaike Information Criterion (AIC) for the model given data X.                                                                                     |
|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.bic)(X)                                        | Compute the Bayesian Information Criterion (BIC) for the model given data X.                                                                                   |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.cdf)(X)                                        | Compute the CDF of the bivariate Gaussian copula.                                                                                                              |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.fit)(X[, y])                                   | Fit the Bivariate Gaussian Copula.                                                                                                                             |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.get_metadata_routing)()                        | Get metadata routing of this object.                                                                                                                           |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.get_params)([deep])                            | Get parameters for this estimator.                                                                                                                             |
| [`inverse_partial_derivative`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.inverse_partial_derivative)(X[, first_margin]) | Compute the inverse of the bivariate copula's partial derivative, commonly known as the inverse h-function [[1]](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#r8bb0201ee017-1). |
| [`partial_derivative`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.partial_derivative)(X[, first_margin])         | Compute the h-function (partial derivative) for the bivariate Gaussian copula.                                                                                 |
| [`plot_pdf_2d`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.plot_pdf_2d)([title])                          | Plot a 2D contour of the estimated probability density function (PDF).                                                                                         |
| [`plot_pdf_3d`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.plot_pdf_3d)([title])                          | Plot a 3D surface of the estimated probability density function (PDF).                                                                                         |
| [`plot_tail_concentration`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.plot_tail_concentration)([X, title])           | Plot the tail concentration function.                                                                                                                          |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.sample)([n_samples])                           | Generate random samples from the bivariate copula using the inverse Rosenblatt transform.                                                                      |
| [`score`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.score)(X[, y])                                 | Compute the total log-likelihood under the model.                                                                                                              |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.score_samples)(X)                              | Compute the log-likelihood of each sample (log-pdf) under the model.                                                                                           |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.set_params)(\*\*params)                        | Set the parameters of this estimator.                                                                                                                          |
| [`tail_concentration`](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#skfolio.distribution.GaussianCopula.tail_concentration)(quantiles)                 | Compute the tail concentration function for a set of quantiles.                                                                                                |

### References

* <a id='r1ac6c90fd463-1'>**[1]**</a> “An Introduction to Copulas (2nd ed.)”, Nelsen (2006)
* <a id='r1ac6c90fd463-2'>**[2]**</a> “Multivariate Models and Dependence Concepts”, Joe, Chapman & Hall (1997)
* <a id='r1ac6c90fd463-3'>**[3]**</a> “Quantitative Risk Management: Concepts, Techniques and Tools”, McNeil, Frey & Embrechts (2005)
* <a id='r1ac6c90fd463-4'>**[4]**</a> “The t Copula and Related Copulas”, Demarta & McNeil (2005)
* <a id='r1ac6c90fd463-5'>**[5]**</a> “Copula Methods in Finance”, Cherubini, Luciano & Vecchiato (2004)

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution import GaussianCopula, compute_pseudo_observations
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>> X = X[["AAPL", "JPM"]]
>>>
>>> # Convert returns to pseudo observation in the interval [0,1]
>>> X = compute_pseudo_observations(X)
>>>
>>> # Initialize the Copula estimator
>>> model = GaussianCopula()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
GaussianCopula(...)
>>>
>>> # Display the fitted parameter and tail dependence coefficients
>>> print(model.fitted_repr)
GaussianCopula(rho=0.327)
>>> print(model.lower_tail_dependence)
0
>>> print(model.upper_tail_dependence)
0
>>>
>>> # Compute the log-likelihood, total log-likelihood, CDF, Partial Derivative,
>>> # Inverse Partial Derivative, AIC, and BIC
>>> log_likelihood = model.score_samples(X)
>>> score = model.score(X)
>>> cdf = model.cdf(X)
>>> p = model.partial_derivative(X)
>>> u = model.inverse_partial_derivative(X)
>>> aic = model.aic(X)
>>> bic = model.bic(X)
>>>
>>> # Generate 5 new samples
>>> samples = model.sample(n_samples=5)
>>>
>>> # Plot the tail concentration function.
>>> fig = model.plot_tail_concentration()
>>>
>>> # Plot a 2D contour of the estimated PDF.
>>> fig = model.plot_pdf_2d()
>>>
>>> # Plot a 3D surface of the estimated PDF.
>>> fig = model.plot_pdf_3d()
```

<a id="skfolio.distribution.GaussianCopula.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r2388a775ea66-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.GaussianCopula.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='rfabb84626bba-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.GaussianCopula.cdf"></a>

#### cdf(X)

Compute the CDF of the bivariate Gaussian copula.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **cdf** *ndarray of shape (n_observations,)*
  : CDF values for each observation in X.

<a id="skfolio.distribution.GaussianCopula.fit"></a>

#### fit(X, y=None)

Fit the Bivariate Gaussian Copula.

If `itau` is True, estimates $\rho$ using Kendall’s tau inversion.
Otherwise, uses MLE by maximizing the log-likelihood.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval [0, 1],
    having been transformed to uniform marginals.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *GaussianCopula*
  : Returns the instance itself.

<a id="skfolio.distribution.GaussianCopula.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.GaussianCopula.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.distribution.GaussianCopula.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.distribution.GaussianCopula.inverse_partial_derivative"></a>

#### inverse_partial_derivative(X, first_margin=False)

Compute the inverse of the bivariate copula’s partial derivative, commonly
known as the inverse h-function [[1]](https://skfolio.org/generated/skfolio.distribution.GaussianCopula.html.md#r8bb0201ee017-1).

Let $C(u, v)$ be a bivariate copula. The h-function with respect to the
second margin is defined by

$$
h(u \mid v) \;=\; \frac{\partial\,C(u, v)}{\partial\,v},

$$

which is the conditional distribution of $U$ given $V = v$.
The **inverse h-function**, denoted $h^{-1}(p \mid v)$, is the unique
value $u \in [0,1]$ such that

$$
h(u \mid v) \;=\; p,
\quad \text{where } p \in [0,1].

$$

In practical terms, given $(p, v)$ in $[0, 1]^2$,
$h^{-1}(p \mid v)$ solves for the $u$ satisfying
$p = \partial C(u, v)/\partial v$.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(p, v)`, each in the interval `[0, 1]`.
    - The first column `p` corresponds to the value of the h-function.
    - The second column `v` is the conditioning variable.

  **first_margin** *bool, default=False*
  : If True, compute the inverse partial derivative with respect to the first
    margin `u`; otherwise, compute the inverse partial derivative with respect
    to the second margin `v`.
* **Returns:**
  **u** *ndarray of shape (n_observations,)*
  : A 1D-array of length `n_observations`, where each element is the computed
    $u = h^{-1}(p \mid v)$ for the corresponding pair in `X`.

### References

* <a id='r8bb0201ee017-1'>**[1]**</a> “Multivariate Models and Dependence Concepts”, Joe, H. (1997)
* <a id='r8bb0201ee017-2'>**[2]**</a> “An Introduction to Copulas”, Nelsen, R. B. (2006)

<a id="skfolio.distribution.GaussianCopula.lower_tail_dependence"></a>

#### *property* lower_tail_dependence

Theoretical lower tail dependence coefficient.

<a id="skfolio.distribution.GaussianCopula.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.GaussianCopula.partial_derivative"></a>

#### partial_derivative(X, first_margin=False)

Compute the h-function (partial derivative) for the bivariate Gaussian
copula.

The h-function with respect to the second margin represents the conditional
distribution function of $u$ given $v$:

$$
\begin{aligned}
h(u \mid v) &= \frac{\partial C(u,v)}{\partial v} \\
&= \Phi\Bigl(\frac{\Phi^{-1}(u)-\rho\,\Phi^{-1}(v)}{\sqrt{1-\rho^2}}\Bigr)
\end{aligned}

$$

where $\Phi$ is the standard normal CDF and $\Phi^{-1}$ is its
inverse (the quantile function).

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.

  **first_margin** *bool, default=False*
  : If True, compute the partial derivative with respect to the first
    margin `u`; otherwise, compute the partial derivative with respect to the
    second margin `v`.
* **Returns:**
  **p** *ndarray of shape (n_observations,)*
  : h-function values $h(u \mid v) \;=\; p$ for each observation in X.

<a id="skfolio.distribution.GaussianCopula.plot_pdf_2d"></a>

#### plot_pdf_2d(title=None)

Plot a 2D contour of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
contour plot of the PDF.
Contour levels are limited to the 97th quantile to avoid extreme densities.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the 2D contour plot of the PDF.

<a id="skfolio.distribution.GaussianCopula.plot_pdf_3d"></a>

#### plot_pdf_3d(title=None)

Plot a 3D surface of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
3D surface plot of the PDF using Plotly.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing a 3D surface plot of the PDF.

<a id="skfolio.distribution.GaussianCopula.plot_tail_concentration"></a>

#### plot_tail_concentration(X=None, title=None)

Plot the tail concentration function.

This method computes the tail concentration function at 100 evenly spaced
quantile levels between 0.005 and 0.995.
The plot displays the concentration values on the y-axis and the quantile levels
on the x-axis.

The tail concentration is defined as:
: - Lower tail: λ_L(q) = P(U₂ ≤ q | U₁ ≤ q)
  - Upper tail: λ_U(q) = P(U₂ ≥ q | U₁ ≥ q)

where U₁ and U₂ are the pseudo-observations of the first and second variables,
respectively.

* **Parameters:**
  **X** *array-like of shape (n_samples, 2), optional*
  : If provided, it is used to plot the empirical tail concentration for
    comparison versus the model tail concentration.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the tail concentration curve.

### References

* <a id='reacd953c84ec-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.GaussianCopula.sample"></a>

#### sample(n_samples=1)

Generate random samples from the bivariate copula using the inverse
Rosenblatt transform.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` are uniform marginals in the
    interval `[0, 1]`.

<a id="skfolio.distribution.GaussianCopula.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.GaussianCopula.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : The log-likelihood of each sample under the fitted copula.

<a id="skfolio.distribution.GaussianCopula.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.

<a id="skfolio.distribution.GaussianCopula.tail_concentration"></a>

#### tail_concentration(quantiles)

Compute the tail concentration function for a set of quantiles.

The tail concentration function is defined as follows:
: - For quantiles q ≤ 0.5:
    : C(q) = P(U ≤ q, V ≤ q) / q
  - For quantiles q > 0.5:
    : C(q) = (1 - 2q + P(U ≤ q, V ≤ q)) / (1 - q)

where U and V are the pseudo-observations of the first and second variables,
respectively. This function returns the concentration values for each q
provided.

* **Parameters:**
  **quantiles** *ndarray of shape (n_quantiles,)*
  : A 1D array of quantile levels (values between 0 and 1) at which to compute
    the tail concentration.
* **Returns:**
  **concentration** *ndarray of shape (n_quantiles,)*
  : The computed tail concentration values corresponding to each quantile.
* **Raises:**
  ValueError
  : If any value in `quantiles` is not in the interval [0, 1].

### References

* <a id='r64a287356d1b-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.GaussianCopula.upper_tail_dependence"></a>

#### *property* upper_tail_dependence

Theoretical upper tail dependence coefficient.

# generated/skfolio.distribution.GumbelCopula.html.md

<a id="skfolio-distribution-gumbelcopula"></a>

# skfolio.distribution.GumbelCopula

<a id="skfolio.distribution.GumbelCopula"></a>

### *class* skfolio.distribution.GumbelCopula(itau=True, kendall_tau=None, tolerance=0.0001, random_state=None)

Bivariate Gumbel Copula Estimation.

The Gumbel copula is an Archimedean copula characterized by strong upper tail
dependence and little to no lower tail dependence.

In its unrotated form, it is used for modeling extreme co-movements in the upper
tail (i.e. simultaneous extreme gains).

Rotations allow the copula to be adapted for different types of tail dependence:
: - A 180° rotation captures extreme co-movements in the lower tail (i.e.
    simultaneous extreme losses).
  - A 90° rotation captures scenarios where one variable exhibits extreme losses
    while the other shows extreme gains.
  - A 270° rotation captures the opposite scenario, where one variable experiences
    extreme gains while the other suffers extreme losses.

Gumbel copula generally exhibits weaker upper tail dependence than the Joe copula.

It is defined by:

$$
C_{\theta}(u, v) = \exp\Bigl(-\Bigl[(-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr]^{1/\theta}\Bigr)

$$

where $\theta \ge 1$ is the dependence parameter. When $\theta = 1$,
the Gumbel copula reduces to the independence copula. Larger values of
$\theta$ result in stronger upper-tail dependence.

#### NOTE
Rotations are needed for Archimedean copulas (e.g., Joe, Gumbel, Gumbel)
because their parameters only model positive dependence, and they exhibit
asymmetric tail behavior. To model negative dependence, one uses rotations
to “flip” the copula’s tail dependence.

* **Parameters:**
  **itau** *bool, default=True*
  : If True, $\theta$ is estimated using the Kendall’s tau inversion method;
    otherwise, the Maximum Likelihood Estimation (MLE) method is used. The MLE is
    slower but more accurate.

  **kendall_tau** *float, optional*
  : If `itau` is True and `kendall_tau` is provided, this value is used;
    otherwise, it is computed.

  **tolerance** *float, default=1e-4*
  : Convergence tolerance for the MLE optimization.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  **theta_** *float*
  : Fitted theta coefficient $\theta$ > 1.

  **rotation_** *CopulaRotation*
  : Fitted rotation of the copula.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.aic)(X)                                        | Compute the Akaike Information Criterion (AIC) for the model given data X.                                      |
|------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.bic)(X)                                        | Compute the Bayesian Information Criterion (BIC) for the model given data X.                                    |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.cdf)(X)                                        | Compute the CDF of the bivariate Gumbel copula.                                                                 |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.fit)(X[, y])                                   | Fit the Bivariate Gumbel Copula.                                                                                |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.get_metadata_routing)()                        | Get metadata routing of this object.                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.get_params)([deep])                            | Get parameters for this estimator.                                                                              |
| [`inverse_partial_derivative`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.inverse_partial_derivative)(X[, first_margin]) | Compute the inverse of the bivariate copula's partial derivative, commonly known as the inverse h-function.     |
| [`partial_derivative`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.partial_derivative)(X[, first_margin])         | Compute the h-function (partial derivative) for the bivariate Gumbel copula with respect to a specified margin. |
| [`plot_pdf_2d`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.plot_pdf_2d)([title])                          | Plot a 2D contour of the estimated probability density function (PDF).                                          |
| [`plot_pdf_3d`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.plot_pdf_3d)([title])                          | Plot a 3D surface of the estimated probability density function (PDF).                                          |
| [`plot_tail_concentration`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.plot_tail_concentration)([X, title])           | Plot the tail concentration function.                                                                           |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.sample)([n_samples])                           | Generate random samples from the bivariate copula using the inverse Rosenblatt transform.                       |
| [`score`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.score)(X[, y])                                 | Compute the total log-likelihood under the model.                                                               |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.score_samples)(X)                              | Compute the log-likelihood of each sample (log-pdf) under the model.                                            |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.set_params)(\*\*params)                        | Set the parameters of this estimator.                                                                           |
| [`tail_concentration`](https://skfolio.org/generated/skfolio.distribution.GumbelCopula.html.md#skfolio.distribution.GumbelCopula.tail_concentration)(quantiles)                 | Compute the tail concentration function for a set of quantiles.                                                 |

### References

* <a id='r9b37b4413458-1'>**[1]**</a> “An Introduction to Copulas (2nd ed.)”, Nelsen (2006)
* <a id='r9b37b4413458-2'>**[2]**</a> “Multivariate Models and Dependence Concepts”, Joe, Chapman & Hall (1997)
* <a id='r9b37b4413458-3'>**[3]**</a> “Quantitative Risk Management: Concepts, Techniques and Tools”, McNeil, Frey & Embrechts (2005)
* <a id='r9b37b4413458-4'>**[4]**</a> “The t Copula and Related Copulas”, Demarta & McNeil (2005)
* <a id='r9b37b4413458-5'>**[5]**</a> “Copula Methods in Finance”, Cherubini, Luciano & Vecchiato (2004)

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution import GumbelCopula, compute_pseudo_observations
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>> X = X[["AAPL", "JPM"]]
>>>
>>> # Convert returns to pseudo observation in the interval [0,1]
>>> X = compute_pseudo_observations(X)
>>>
>>> # Initialize the Copula estimator
>>> model = GumbelCopula()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
GumbelCopula(...)
>>>
>>> # Display the fitted parameter and tail dependence coefficients
>>> print(model.fitted_repr)
GumbelCopula(theta=1.27, rot=180°)
>>> print(model.lower_tail_dependence)
0.273...
>>> print(model.upper_tail_dependence)
0
>>>
>>> # Compute the log-likelihood, total log-likelihood, CDF, Partial Derivative,
>>> # Inverse Partial Derivative, AIC, and BIC
>>> log_likelihood = model.score_samples(X)
>>> score = model.score(X)
>>> cdf = model.cdf(X)
>>> p = model.partial_derivative(X)
>>> u = model.inverse_partial_derivative(X)
>>> aic = model.aic(X)
>>> bic = model.bic(X)
>>>
>>> # Generate 5 new samples
>>> samples = model.sample(n_samples=5)
>>>
>>> # Plot the tail concentration function.
>>> fig = model.plot_tail_concentration()
>>>
>>> # Plot a 2D contour of the estimated PDF.
>>> fig = model.plot_pdf_2d()
>>>
>>> # Plot a 3D surface of the estimated PDF.
>>> fig = model.plot_pdf_3d()
```

<a id="skfolio.distribution.GumbelCopula.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r321b5cfd4f58-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.GumbelCopula.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r57934213a7bf-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.GumbelCopula.cdf"></a>

#### cdf(X)

Compute the CDF of the bivariate Gumbel copula.

$$
C(u,v) = \exp\Bigl(-\Bigl[(-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr]^{1/\theta}\Bigr).

$$

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval [0, 1],
    having been transformed to uniform marginals.
* **Returns:**
  **cdf** *ndarray of shape (n_observations,)*
  : CDF values for each observation in X.

<a id="skfolio.distribution.GumbelCopula.fit"></a>

#### fit(X, y=None)

Fit the Bivariate Gumbel Copula.

If `itau` is True, estimates $\theta$ using Kendall’s tau inversion.
Otherwise, uses MLE by maximizing the log-likelihood.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval [0, 1],
    having been transformed to uniform marginals.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *object*
  : Returns the instance itself.

<a id="skfolio.distribution.GumbelCopula.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.GumbelCopula.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.distribution.GumbelCopula.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.distribution.GumbelCopula.inverse_partial_derivative"></a>

#### inverse_partial_derivative(X, first_margin=False)

Compute the inverse of the bivariate copula’s partial derivative, commonly
known as the inverse h-function.

Let $C(u, v)$ be a bivariate copula. The h-function with respect to the
second margin is defined by

$$
h(u \mid v) \;=\; \frac{\partial\,C(u, v)}{\partial\,v},

$$

which is the conditional distribution of $U$ given $V = v$.
The **inverse h-function**, denoted $h^{-1}(p \mid v)$, is the unique
value $u \in [0,1]$ such that

$$
h(u \mid v) \;=\; p,
\quad \text{where } p \in [0,1].

$$

In practical terms, given $(p, v)$ in $[0, 1]^2$,
$h^{-1}(p \mid v)$ solves for the $u$ satisfying
$p = \partial C(u, v)/\partial v$.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(p, v)`, each in the interval [0, 1].
    - The first column `p` corresponds to the value of the h-function.
    - The second column `v` is the conditioning variable.

  **first_margin** *bool, default=False*
  : If True, compute the inverse partial derivative with respect to the first
    margin `u`; otherwise, compute the inverse partial derivative with respect
    to the second margin `v`.
* **Returns:**
  **u** *ndarray of shape (n_observations,)*
  : A 1D-array where each element is the computed $u = h^{-1}(p \mid v)$
    for the corresponding pair in `X`.

<a id="skfolio.distribution.GumbelCopula.lower_tail_dependence"></a>

#### *property* lower_tail_dependence

Theoretical lower tail dependence coefficient.

<a id="skfolio.distribution.GumbelCopula.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.GumbelCopula.partial_derivative"></a>

#### partial_derivative(X, first_margin=False)

Compute the h-function (partial derivative) for the bivariate Gumbel copula
with respect to a specified margin.

The h-function with respect to the second margin represents the conditional
distribution function of $u$ given $v$:

$$
\begin{aligned}
h(u \mid v)
  &= \frac{\partial C(u,v)}{\partial v}\\[6pt]
  &= C(u,v)\,\Bigl[(-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr]^{\frac{1}{\theta}-1}
      \,(-\ln v)^{\theta-1}\,\frac{1}{v}.
\end{aligned}

$$

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval [0, 1],
    having been transformed to uniform marginals.

  **first_margin** *bool, default=False*
  : If True, compute the partial derivative with respect to the first
    margin `u`; otherwise, compute the partial derivative with respect to the
    second margin `v`.
* **Returns:**
  **p** *ndarray of shape (n_observations,)*
  : h-function values $h(u \mid v)$ for each observation in X.

<a id="skfolio.distribution.GumbelCopula.plot_pdf_2d"></a>

#### plot_pdf_2d(title=None)

Plot a 2D contour of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
contour plot of the PDF.
Contour levels are limited to the 97th quantile to avoid extreme densities.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the 2D contour plot of the PDF.

<a id="skfolio.distribution.GumbelCopula.plot_pdf_3d"></a>

#### plot_pdf_3d(title=None)

Plot a 3D surface of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
3D surface plot of the PDF using Plotly.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing a 3D surface plot of the PDF.

<a id="skfolio.distribution.GumbelCopula.plot_tail_concentration"></a>

#### plot_tail_concentration(X=None, title=None)

Plot the tail concentration function.

This method computes the tail concentration function at 100 evenly spaced
quantile levels between 0.005 and 0.995.
The plot displays the concentration values on the y-axis and the quantile levels
on the x-axis.

The tail concentration is defined as:
: - Lower tail: λ_L(q) = P(U₂ ≤ q | U₁ ≤ q)
  - Upper tail: λ_U(q) = P(U₂ ≥ q | U₁ ≥ q)

where U₁ and U₂ are the pseudo-observations of the first and second variables,
respectively.

* **Parameters:**
  **X** *array-like of shape (n_samples, 2), optional*
  : If provided, it is used to plot the empirical tail concentration for
    comparison versus the model tail concentration.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the tail concentration curve.

### References

* <a id='r2922bef24754-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.GumbelCopula.sample"></a>

#### sample(n_samples=1)

Generate random samples from the bivariate copula using the inverse
Rosenblatt transform.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` are uniform marginals in the
    interval `[0, 1]`.

<a id="skfolio.distribution.GumbelCopula.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.GumbelCopula.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

For Gumbel, the PDF is given by:

$$
c(u,v) = \exp\Bigl(-\Bigl((-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr)^{1/\theta}\Bigr)
         \cdot \left[\Bigl((-\ln u)^{\theta}+(-\ln v)^{\theta}\Bigr)^{1/\theta-1}
              \left\{ \frac{(-\ln u)^{\theta}}{u}+\frac{(-\ln v)^{\theta}}{v}\right\}\right].

$$

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval [0, 1],
    having been transformed to uniform marginals.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : The log-likelihood of each sample under the fitted copula.

<a id="skfolio.distribution.GumbelCopula.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.

<a id="skfolio.distribution.GumbelCopula.tail_concentration"></a>

#### tail_concentration(quantiles)

Compute the tail concentration function for a set of quantiles.

The tail concentration function is defined as follows:
: - For quantiles q ≤ 0.5:
    : C(q) = P(U ≤ q, V ≤ q) / q
  - For quantiles q > 0.5:
    : C(q) = (1 - 2q + P(U ≤ q, V ≤ q)) / (1 - q)

where U and V are the pseudo-observations of the first and second variables,
respectively. This function returns the concentration values for each q
provided.

* **Parameters:**
  **quantiles** *ndarray of shape (n_quantiles,)*
  : A 1D array of quantile levels (values between 0 and 1) at which to compute
    the tail concentration.
* **Returns:**
  **concentration** *ndarray of shape (n_quantiles,)*
  : The computed tail concentration values corresponding to each quantile.
* **Raises:**
  ValueError
  : If any value in `quantiles` is not in the interval [0, 1].

### References

* <a id='r2ce4a0e7b676-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.GumbelCopula.upper_tail_dependence"></a>

#### *property* upper_tail_dependence

Theoretical upper tail dependence coefficient.

# generated/skfolio.distribution.IndependentCopula.html.md

<a id="skfolio-distribution-independentcopula"></a>

# skfolio.distribution.IndependentCopula

<a id="skfolio.distribution.IndependentCopula"></a>

### *class* skfolio.distribution.IndependentCopula(random_state=None)

Bivariate Independent Copula (also called the product copula).

It is defined by:

$$
C(u, v) = u \cdot v

$$

* **Parameters:**
  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  [`fitted_repr`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.fitted_repr)
  : String representation of the fitted copula.

  [`lower_tail_dependence`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.lower_tail_dependence)
  : Theoretical lower tail dependence coefficient.

  [`n_params`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.n_params)
  : Number of model parameters.

  [`upper_tail_dependence`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.upper_tail_dependence)
  : Theoretical upper tail dependence coefficient.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.aic)(X)                                        | Compute the Akaike Information Criterion (AIC) for the model given data X.                                  |
|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.bic)(X)                                        | Compute the Bayesian Information Criterion (BIC) for the model given data X.                                |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.cdf)(X)                                        | Compute the CDF of the bivariate Independent copula.                                                        |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.fit)(X[, y])                                   | Fit the Bivariate Independent Copula.                                                                       |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.get_metadata_routing)()                        | Get metadata routing of this object.                                                                        |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.get_params)([deep])                            | Get parameters for this estimator.                                                                          |
| [`inverse_partial_derivative`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.inverse_partial_derivative)(X[, first_margin]) | Compute the inverse of the bivariate copula's partial derivative, commonly known as the inverse h-function. |
| [`partial_derivative`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.partial_derivative)(X[, first_margin])         | Compute the h-function (partial derivative) for the bivariate Independent copula.                           |
| [`plot_pdf_2d`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.plot_pdf_2d)([title])                          | Plot a 2D contour of the estimated probability density function (PDF).                                      |
| [`plot_pdf_3d`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.plot_pdf_3d)([title])                          | Plot a 3D surface of the estimated probability density function (PDF).                                      |
| [`plot_tail_concentration`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.plot_tail_concentration)([X, title])           | Plot the tail concentration function.                                                                       |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.sample)([n_samples])                           | Generate random samples from the bivariate copula using the inverse Rosenblatt transform.                   |
| [`score`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.score)(X[, y])                                 | Compute the total log-likelihood under the model.                                                           |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.score_samples)(X)                              | Compute the log-likelihood of each sample (log-pdf) under the model.                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.set_params)(\*\*params)                        | Set the parameters of this estimator.                                                                       |
| [`tail_concentration`](https://skfolio.org/generated/skfolio.distribution.IndependentCopula.html.md#skfolio.distribution.IndependentCopula.tail_concentration)(quantiles)                 | Compute the tail concentration function for a set of quantiles.                                             |

### References

* <a id='rbefe6bda9883-1'>**[1]**</a> “An Introduction to Copulas (2nd ed.)”, Nelsen (2006)
* <a id='rbefe6bda9883-2'>**[2]**</a> “Multivariate Models and Dependence Concepts”, Joe, Chapman & Hall (1997)
* <a id='rbefe6bda9883-3'>**[3]**</a> “Quantitative Risk Management: Concepts, Techniques and Tools”, McNeil, Frey & Embrechts (2005)
* <a id='rbefe6bda9883-4'>**[4]**</a> “The t Copula and Related Copulas”, Demarta & McNeil (2005)
* <a id='rbefe6bda9883-5'>**[5]**</a> “Copula Methods in Finance”, Cherubini, Luciano & Vecchiato (2004)

<a id="skfolio.distribution.IndependentCopula.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r646dbfb39f08-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.IndependentCopula.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r920075fadd84-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.IndependentCopula.cdf"></a>

#### cdf(X)

Compute the CDF of the bivariate Independent copula.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **cdf** *ndarray of shape (n_observations,)*
  : CDF values for each observation in X.

<a id="skfolio.distribution.IndependentCopula.fit"></a>

#### fit(X, y=None)

Fit the Bivariate Independent Copula.

Provided for compatibility with the API.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval [0, 1],
    having been transformed to uniform marginals.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *IndependentCopula*
  : Returns the instance itself.

<a id="skfolio.distribution.IndependentCopula.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.IndependentCopula.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.distribution.IndependentCopula.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.distribution.IndependentCopula.inverse_partial_derivative"></a>

#### inverse_partial_derivative(X, first_margin=False)

Compute the inverse of the bivariate copula’s partial derivative, commonly
known as the inverse h-function.

For the independent copula, the h-function with respect to the second margin is

$$
h(u\mid v)= u,

$$

and the derivative with respect to the first margin is

$$
g(u,v)= v.

$$

Their inverses are trivial:

> - Given (p,v) for h(u|v)= p, we have u = p.
> - Given (p,u) for g(u,v)= p, we have v = p.
* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(p, v)`, each in the interval `[0, 1]`.
    - The first column `p` corresponds to the value of the h-function.
    - The second column `v` is the conditioning variable.

  **first_margin** *bool, default=False*
  : If True, compute the inverse partial derivative with respect to the first
    margin `u`; otherwise, compute the inverse partial derivative with respect
    to the second margin `v`.
* **Returns:**
  **u** *ndarray of shape (n_observations,)*
  : A 1D-array of length `n_observations`, where each element is the computed
    $u = h^{-1}(p \mid v)$ for the corresponding pair in `X`.

<a id="skfolio.distribution.IndependentCopula.lower_tail_dependence"></a>

#### *property* lower_tail_dependence

Theoretical lower tail dependence coefficient.

<a id="skfolio.distribution.IndependentCopula.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.IndependentCopula.partial_derivative"></a>

#### partial_derivative(X, first_margin=False)

Compute the h-function (partial derivative) for the bivariate Independent
copula.

The h-function with respect to the second margin represents the conditional
distribution function of $u$ given $v$:

$$
\frac{\partial C(u,v)}{\partial v}=u,

$$

* **Parameters:**
  **X** *array-like of shape (n_samples, 2)*
  : Array of pairs $(u,v)$, where each value is in the interval [0,1].
* **Returns:**
  FloatArray
  : Array of h-function values for each observation in X.

<a id="skfolio.distribution.IndependentCopula.plot_pdf_2d"></a>

#### plot_pdf_2d(title=None)

Plot a 2D contour of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
contour plot of the PDF.
Contour levels are limited to the 97th quantile to avoid extreme densities.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the 2D contour plot of the PDF.

<a id="skfolio.distribution.IndependentCopula.plot_pdf_3d"></a>

#### plot_pdf_3d(title=None)

Plot a 3D surface of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
3D surface plot of the PDF using Plotly.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing a 3D surface plot of the PDF.

<a id="skfolio.distribution.IndependentCopula.plot_tail_concentration"></a>

#### plot_tail_concentration(X=None, title=None)

Plot the tail concentration function.

This method computes the tail concentration function at 100 evenly spaced
quantile levels between 0.005 and 0.995.
The plot displays the concentration values on the y-axis and the quantile levels
on the x-axis.

The tail concentration is defined as:
: - Lower tail: λ_L(q) = P(U₂ ≤ q | U₁ ≤ q)
  - Upper tail: λ_U(q) = P(U₂ ≥ q | U₁ ≥ q)

where U₁ and U₂ are the pseudo-observations of the first and second variables,
respectively.

* **Parameters:**
  **X** *array-like of shape (n_samples, 2), optional*
  : If provided, it is used to plot the empirical tail concentration for
    comparison versus the model tail concentration.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the tail concentration curve.

### References

* <a id='ree82233b7896-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.IndependentCopula.sample"></a>

#### sample(n_samples=1)

Generate random samples from the bivariate copula using the inverse
Rosenblatt transform.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` are uniform marginals in the
    interval `[0, 1]`.

<a id="skfolio.distribution.IndependentCopula.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.IndependentCopula.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_samples, 2)*
  : The input data where each row represents a bivariate observation.
    The data should be transformed to uniform marginals in [0, 1].
* **Returns:**
  **density** *ndarray of shape (n_samples,)*
  : The log-likelihood of each sample under the fitted copula.

<a id="skfolio.distribution.IndependentCopula.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.

<a id="skfolio.distribution.IndependentCopula.tail_concentration"></a>

#### tail_concentration(quantiles)

Compute the tail concentration function for a set of quantiles.

The tail concentration function is defined as follows:
: - For quantiles q ≤ 0.5:
    : C(q) = P(U ≤ q, V ≤ q) / q
  - For quantiles q > 0.5:
    : C(q) = (1 - 2q + P(U ≤ q, V ≤ q)) / (1 - q)

where U and V are the pseudo-observations of the first and second variables,
respectively. This function returns the concentration values for each q
provided.

* **Parameters:**
  **quantiles** *ndarray of shape (n_quantiles,)*
  : A 1D array of quantile levels (values between 0 and 1) at which to compute
    the tail concentration.
* **Returns:**
  **concentration** *ndarray of shape (n_quantiles,)*
  : The computed tail concentration values corresponding to each quantile.
* **Raises:**
  ValueError
  : If any value in `quantiles` is not in the interval [0, 1].

### References

* <a id='r21a1660a69a1-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.IndependentCopula.upper_tail_dependence"></a>

#### *property* upper_tail_dependence

Theoretical upper tail dependence coefficient.

# generated/skfolio.distribution.JoeCopula.html.md

<a id="skfolio-distribution-joecopula"></a>

# skfolio.distribution.JoeCopula

<a id="skfolio.distribution.JoeCopula"></a>

### *class* skfolio.distribution.JoeCopula(itau=True, kendall_tau=None, tolerance=0.0001, random_state=None)

Bivariate Joe Copula Estimation.

The Joe copula is an Archimedean copula characterized by strong upper tail
dependence and little to no lower tail dependence.

In its unrotated form, it is used for modeling extreme co-movements in the upper
tail (i.e. simultaneous extreme gains).

Rotations allow the copula to be adapted for different types of tail dependence:
: - A 180° rotation captures extreme co-movements in the lower tail (i.e.
    simultaneous extreme losses).
  - A 90° rotation captures scenarios where one variable exhibits extreme losses
    while the other shows extreme gains.
  - A 270° rotation captures the opposite scenario, where one variable experiences
    extreme gains while the other suffers extreme losses.

Joe copula generally exhibits stronger upper tail dependence than the Gumbel copula.

It is defined by:

$$
C_{\theta}(u, v) = 1-\Bigl[(1 - u)^{\theta} + (1 - v)^{\theta} -
    (1 - u)^{\theta} (1 - v)^{\theta}\Bigr]^{\frac{1}{\theta}}

$$

where $\theta \ge 1$ is the dependence parameter. When $\theta = 1$,
the Joe copula reduces to the independence copula. Larger values of $\theta$
result in stronger upper-tail dependence.

#### NOTE
Rotation are needed for archimedean copulas (e.g., Joe, Gumbel, Clayton)
because their parameters only model positive dependence, and they exhibit
asymmetric tail behavior. To model negative dependence, one uses rotations
to “flip” the copula’s tail dependence.

* **Parameters:**
  **itau** *bool, default=True*
  : If True, $\theta$ is estimated using the Kendall’s tau inversion method;
    otherwise, the Maximum Likelihood Estimation (MLE) method is used. The MLE is
    slower but more accurate.

  **kendall_tau** *float, optional*
  : If `itau` is True and `kendall_tau` is provided, this value is used;
    otherwise, it is computed.

  **tolerance** *float, default=1e-4*
  : Convergence tolerance for the MLE optimization.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  **theta_** *float*
  : Fitted theta coefficient $\theta$ > 1.

  **rotation_** *CopulaRotation*
  : Fitted rotation of the copula.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.aic)(X)                                        | Compute the Akaike Information Criterion (AIC) for the model given data X.                                                                                     |
|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.bic)(X)                                        | Compute the Bayesian Information Criterion (BIC) for the model given data X.                                                                                   |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.cdf)(X)                                        | Compute the CDF of the bivariate Joe copula.                                                                                                                   |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.fit)(X[, y])                                   | Fit the Bivariate Joe Copula.                                                                                                                                  |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.get_metadata_routing)()                        | Get metadata routing of this object.                                                                                                                           |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.get_params)([deep])                            | Get parameters for this estimator.                                                                                                                             |
| [`inverse_partial_derivative`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.inverse_partial_derivative)(X[, first_margin]) | Compute the inverse of the bivariate copula's partial derivative, commonly known as the inverse h-function [[1]](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#rf0ec9f4ea0c3-1). |
| [`partial_derivative`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.partial_derivative)(X[, first_margin])         | Compute the h-function (partial derivative) for the bivariate Joe copula with respect to a specified margin.                                                   |
| [`plot_pdf_2d`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.plot_pdf_2d)([title])                          | Plot a 2D contour of the estimated probability density function (PDF).                                                                                         |
| [`plot_pdf_3d`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.plot_pdf_3d)([title])                          | Plot a 3D surface of the estimated probability density function (PDF).                                                                                         |
| [`plot_tail_concentration`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.plot_tail_concentration)([X, title])           | Plot the tail concentration function.                                                                                                                          |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.sample)([n_samples])                           | Generate random samples from the bivariate copula using the inverse Rosenblatt transform.                                                                      |
| [`score`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.score)(X[, y])                                 | Compute the total log-likelihood under the model.                                                                                                              |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.score_samples)(X)                              | Compute the log-likelihood of each sample (log-pdf) under the model.                                                                                           |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.set_params)(\*\*params)                        | Set the parameters of this estimator.                                                                                                                          |
| [`tail_concentration`](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#skfolio.distribution.JoeCopula.tail_concentration)(quantiles)                 | Compute the tail concentration function for a set of quantiles.                                                                                                |

### References

* <a id='r86860317e993-1'>**[1]**</a> “An Introduction to Copulas (2nd ed.)”, Nelsen (2006)
* <a id='r86860317e993-2'>**[2]**</a> “Multivariate Models and Dependence Concepts”, Joe, Chapman & Hall (1997)
* <a id='r86860317e993-3'>**[3]**</a> “Quantitative Risk Management: Concepts, Techniques and Tools”, McNeil, Frey & Embrechts (2005)
* <a id='r86860317e993-4'>**[4]**</a> “The t Copula and Related Copulas”, Demarta & McNeil (2005)
* <a id='r86860317e993-5'>**[5]**</a> “Copula Methods in Finance”, Cherubini, Luciano & Vecchiato (2004)

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution import JoeCopula, compute_pseudo_observations
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>> X = X[["AAPL", "JPM"]]
>>>
>>> # Convert returns to pseudo observation in the interval [0,1]
>>> X = compute_pseudo_observations(X)
>>>
>>> # Initialize the Copula estimator
>>> model = JoeCopula()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
JoeCopula(...)
>>>
>>> # Display the fitted parameter and tail dependence coefficients
>>> print(model.fitted_repr)
JoeCopula(theta=1.48, rot=180°)
>>> print(model.lower_tail_dependence)
0.402...
>>> print(model.upper_tail_dependence)
0
>>>
>>> # Compute the log-likelihood, total log-likelihood, CDF, Partial Derivative,
>>> # Inverse Partial Derivative, AIC, and BIC
>>> log_likelihood = model.score_samples(X)
>>> score = model.score(X)
>>> cdf = model.cdf(X)
>>> p = model.partial_derivative(X)
>>> u = model.inverse_partial_derivative(X)
>>> aic = model.aic(X)
>>> bic = model.bic(X)
>>>
>>> # Generate 5 new samples
>>> samples = model.sample(n_samples=5)
>>>
>>> # Plot the tail concentration function.
>>> fig = model.plot_tail_concentration()
>>>
>>> # Plot a 2D contour of the estimated PDF.
>>> fig = model.plot_pdf_2d()
>>>
>>> # Plot a 3D surface of the estimated PDF.
>>> fig = model.plot_pdf_3d()
```

<a id="skfolio.distribution.JoeCopula.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='ra3d6a7c9ca96-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.JoeCopula.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r7ba13b427350-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.JoeCopula.cdf"></a>

#### cdf(X)

Compute the CDF of the bivariate Joe copula.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **cdf** *ndarray of shape (n_observations,)*
  : CDF values for each observation in X.

<a id="skfolio.distribution.JoeCopula.fit"></a>

#### fit(X, y=None)

Fit the Bivariate Joe Copula.

If `itau` is True, estimates $\theta$ using Kendall’s tau inversion.
Otherwise, uses MLE by maximizing the log-likelihood.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval [0, 1],
    having been transformed to uniform marginals.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *object*
  : Returns the instance itself.

<a id="skfolio.distribution.JoeCopula.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.JoeCopula.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.distribution.JoeCopula.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.distribution.JoeCopula.inverse_partial_derivative"></a>

#### inverse_partial_derivative(X, first_margin=False)

Compute the inverse of the bivariate copula’s partial derivative, commonly
known as the inverse h-function [[1]](https://skfolio.org/generated/skfolio.distribution.JoeCopula.html.md#rf0ec9f4ea0c3-1).

Let $C(u, v)$ be a bivariate copula. The h-function with respect to the
second margin is defined by

$$
h(u \mid v) \;=\; \frac{\partial\,C(u, v)}{\partial\,v},

$$

which is the conditional distribution of $U$ given $V = v$.
The **inverse h-function**, denoted $h^{-1}(p \mid v)$, is the unique
value $u \in [0,1]$ such that

$$
h(u \mid v) \;=\; p,
\quad \text{where } p \in [0,1].

$$

In practical terms, given $(p, v)$ in $[0, 1]^2$,
$h^{-1}(p \mid v)$ solves for the $u$ satisfying
$p = \partial C(u, v)/\partial v$.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(p, v)`, each in the interval `[0, 1]`.
    - The first column `p` corresponds to the value of the h-function.
    - The second column `v` is the conditioning variable.

  **first_margin** *bool, default=False*
  : If True, compute the inverse partial derivative with respect to the first
    margin `u`; otherwise, compute the inverse partial derivative with respect
    to the second margin `v`.
* **Returns:**
  **u** *ndarray of shape (n_observations,)*
  : A 1D-array of length `n_observations`, where each element is the computed
    $u = h^{-1}(p \mid v)$ for the corresponding pair in `X`.

### References

* <a id='rf0ec9f4ea0c3-1'>**[1]**</a> “Multivariate Models and Dependence Concepts”, Joe, H. (1997)
* <a id='rf0ec9f4ea0c3-2'>**[2]**</a> “An Introduction to Copulas”, Nelsen, R. B. (2006)
* <a id='rf0ec9f4ea0c3-3'>**[3]**</a> . “Nested Archimedean Copulas Meet “, Hofert & Mächler (2011)

<a id="skfolio.distribution.JoeCopula.lower_tail_dependence"></a>

#### *property* lower_tail_dependence

Theoretical lower tail dependence coefficient.

<a id="skfolio.distribution.JoeCopula.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.JoeCopula.partial_derivative"></a>

#### partial_derivative(X, first_margin=False)

Compute the h-function (partial derivative) for the bivariate Joe copula
with respect to a specified margin.

The h-function with respect to the second margin represents the conditional
distribution function of $u$ given $v$:

$$
\begin{aligned}
h(u \mid v)
  &= \frac{\partial C(u,v)}{\partial v} \\[6pt]
  &= (1-v)^{\theta-1}\,\Bigl[1 \;-\;(1-u)^{\theta}\Bigr]\,
     \Bigl[(1-u)^{\theta} \;+\;(1-v)^{\theta}
           \;-\;(1-u)^{\theta}(1-v)^{\theta}\Bigr]^{\frac{1}{\theta}-1} \\[6pt]
  &= \left( 1 \;+\;\frac{(1-u)^{\theta}}{(1-v)^{\theta}}
           \;-\;(1-u)^{\theta} \right)^{-1 + \frac{1}{\theta}}
     \;\cdot\;\bigl[\,1 \;-\;(1-u)^{\theta}\bigr].
\end{aligned}

$$

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.

  **first_margin** *bool, default=False*
  : If True, compute the partial derivative with respect to the first
    margin `u`; otherwise, compute the partial derivative with respect to the
    second margin `v`.
* **Returns:**
  **p** *ndarray of shape (n_observations,)*
  : h-function values $h(u \mid v) \;=\; p$ for each observation in X.

<a id="skfolio.distribution.JoeCopula.plot_pdf_2d"></a>

#### plot_pdf_2d(title=None)

Plot a 2D contour of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
contour plot of the PDF.
Contour levels are limited to the 97th quantile to avoid extreme densities.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the 2D contour plot of the PDF.

<a id="skfolio.distribution.JoeCopula.plot_pdf_3d"></a>

#### plot_pdf_3d(title=None)

Plot a 3D surface of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
3D surface plot of the PDF using Plotly.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing a 3D surface plot of the PDF.

<a id="skfolio.distribution.JoeCopula.plot_tail_concentration"></a>

#### plot_tail_concentration(X=None, title=None)

Plot the tail concentration function.

This method computes the tail concentration function at 100 evenly spaced
quantile levels between 0.005 and 0.995.
The plot displays the concentration values on the y-axis and the quantile levels
on the x-axis.

The tail concentration is defined as:
: - Lower tail: λ_L(q) = P(U₂ ≤ q | U₁ ≤ q)
  - Upper tail: λ_U(q) = P(U₂ ≥ q | U₁ ≥ q)

where U₁ and U₂ are the pseudo-observations of the first and second variables,
respectively.

* **Parameters:**
  **X** *array-like of shape (n_samples, 2), optional*
  : If provided, it is used to plot the empirical tail concentration for
    comparison versus the model tail concentration.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the tail concentration curve.

### References

* <a id='r36592470e977-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.JoeCopula.sample"></a>

#### sample(n_samples=1)

Generate random samples from the bivariate copula using the inverse
Rosenblatt transform.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` are uniform marginals in the
    interval `[0, 1]`.

<a id="skfolio.distribution.JoeCopula.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.JoeCopula.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : The log-likelihood of each sample under the fitted copula.

<a id="skfolio.distribution.JoeCopula.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.

<a id="skfolio.distribution.JoeCopula.tail_concentration"></a>

#### tail_concentration(quantiles)

Compute the tail concentration function for a set of quantiles.

The tail concentration function is defined as follows:
: - For quantiles q ≤ 0.5:
    : C(q) = P(U ≤ q, V ≤ q) / q
  - For quantiles q > 0.5:
    : C(q) = (1 - 2q + P(U ≤ q, V ≤ q)) / (1 - q)

where U and V are the pseudo-observations of the first and second variables,
respectively. This function returns the concentration values for each q
provided.

* **Parameters:**
  **quantiles** *ndarray of shape (n_quantiles,)*
  : A 1D array of quantile levels (values between 0 and 1) at which to compute
    the tail concentration.
* **Returns:**
  **concentration** *ndarray of shape (n_quantiles,)*
  : The computed tail concentration values corresponding to each quantile.
* **Raises:**
  ValueError
  : If any value in `quantiles` is not in the interval [0, 1].

### References

* <a id='rd013f05b5432-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.JoeCopula.upper_tail_dependence"></a>

#### *property* upper_tail_dependence

Theoretical upper tail dependence coefficient.

# generated/skfolio.distribution.JohnsonSU.html.md

<a id="skfolio-distribution-johnsonsu"></a>

# skfolio.distribution.JohnsonSU

<a id="skfolio.distribution.JohnsonSU"></a>

### *class* skfolio.distribution.JohnsonSU(loc=None, scale=None, random_state=None)

Johnson SU Distribution Estimation.

This estimator fits a univariate Johnson SU distribution to the input data.
The Johnson SU distribution is flexible and can capture both skewness and fat tails,
making it appropriate for financial time series modeling.

The probability density function is:

$$
f(x, a, b) = \frac{b}{\sqrt{x^2 + 1}}
             \phi(a + b \log(x + \sqrt{x^2 + 1}))
$$

where $x$, $a$, and $b$ are real scalars; $b > 0$.
$\phi$ is the pdf of the normal distribution.

The probability density above is defined in the “standardized” form. To shift
and/or scale the distribution use the loc and scale parameters. Specifically,
`pdf(x, a, b, loc, scale)` is equivalent to `pdf(y, a, b) / scale` with
`y = (x - loc) / scale`.

For more information, you can refer to the [scipy documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.johnsonsu.html#scipy.stats.johnsonsu)

* **Parameters:**
  **loc** *float, optional*
  : If provided, the location parameter is fixed to this value during fitting.
    Otherwise, it is estimated from the data.

  **scale** *float, optional*
  : If provided, the scale parameter is fixed to this value during fitting.
    Otherwise, it is estimated from the data.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  **a_** *float*
  : The fitted first shape parameter of the Johnson SU distribution.

  **b_** *float*
  : The fitted second shape parameter of the Johnson SU distribution.

  **loc_** *float*
  : The fitted location parameter.

  **scale_** *float*
  : The fitted scale parameter.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.aic)(X)                 | Compute the Akaike Information Criterion (AIC) for the model given data X.             |
|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.bic)(X)                 | Compute the Bayesian Information Criterion (BIC) for the model given data X.           |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.cdf)(X)                 | Compute the cumulative distribution function (CDF) for the given data.                 |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.fit)(X[, y])            | Fit the univariate Johnson SU distribution model.                                      |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.get_metadata_routing)() | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.get_params)([deep])     | Get parameters for this estimator.                                                     |
| [`plot_pdf`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.plot_pdf)([X, title])   | Plot the probability density function (PDF).                                           |
| [`ppf`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.ppf)(X)                 | Compute the percent point function (inverse of the CDF) for the given                  |
| [`qq_plot`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.qq_plot)(X[, title])    | Plot the empirical quantiles of the sample X versus the quantiles of the fitted model. |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.sample)([n_samples])    | Generate random samples from the fitted distribution.                                  |
| [`score`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.score)(X[, y])          | Compute the total log-likelihood under the model.                                      |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.score_samples)(X)       | Compute the log-likelihood of each sample (log-pdf) under the model.                   |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.JohnsonSU.html.md#skfolio.distribution.JohnsonSU.set_params)(\*\*params) | Set the parameters of this estimator.                                                  |

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_index
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution.univariate import JohnsonSU
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_index()
>>> X = prices_to_returns(prices)
>>>
>>> # Initialize the estimator.
>>> model = JohnsonSU()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
JohnsonSU(...)
>>>
>>> # Display the fitted parameters.
>>> print(model.fitted_repr)
JohnsonSU(a=0.074, b=1.1, loc=0.0012, scale=0.0077)
>>>
>>> # Compute the log-likelihood, total log-likelihood, CDF, PPF, AIC, and BIC
>>> log_likelihood = model.score_samples(X)
>>> score = model.score(X)
>>> cdf = model.cdf(X)
>>> ppf = model.ppf([0.01, 0.05, 0.5, 0.95, 0.99])
>>> aic = model.aic(X)
>>> bic = model.bic(X)
>>>
>>> # Generate 5 new samples from the fitted distribution.
>>> samples = model.sample(n_samples=5)
>>>
>>> # Plot the estimated probability density function (PDF).
>>> fig = model.plot_pdf()
```

<a id="skfolio.distribution.JohnsonSU.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r5a04a0347f78-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.JohnsonSU.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='rcd0e825af9bd-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.JohnsonSU.cdf"></a>

#### cdf(X)

Compute the cumulative distribution function (CDF) for the given data.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : Data points at which to evaluate the CDF.
* **Returns:**
  **cdf** *ndarray of shape (n_observations, 1)*
  : The CDF evaluated at each data point.

<a id="skfolio.distribution.JohnsonSU.fit"></a>

#### fit(X, y=None)

Fit the univariate Johnson SU distribution model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : The input data. X must contain a single column.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *JohnsonSU*
  : Returns the instance itself.

<a id="skfolio.distribution.JohnsonSU.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted univariate distribution.

<a id="skfolio.distribution.JohnsonSU.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.distribution.JohnsonSU.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.distribution.JohnsonSU.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.JohnsonSU.plot_pdf"></a>

#### plot_pdf(X=None, title=None)

Plot the probability density function (PDF).

* **Parameters:**
  **X** *array-like of shape (n_samples, 1), optional*
  : If provided, it is used to plot the empirical data KDE for comparison
    versus the model PDF.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    model’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the PDF plot.

<a id="skfolio.distribution.JohnsonSU.ppf"></a>

#### ppf(X)

Compute the percent point function (inverse of the CDF) for the given
: probabilities.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : Probabilities for which to compute the corresponding quantiles.
* **Returns:**
  **ppf** *ndarray of shape (n_observations, 1)*
  : The quantiles corresponding to the given probabilities.

<a id="skfolio.distribution.JohnsonSU.qq_plot"></a>

#### qq_plot(X, title=None)

Plot the empirical quantiles of the sample X versus the quantiles of the
fitted model.

* **Parameters:**
  **X** *array-like of shape (n_samples, 1), optional*
  : Used to plot the empirical quantiles for comparison versus the model
    quantiles.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    model’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the PDF plot.

<a id="skfolio.distribution.JohnsonSU.sample"></a>

#### sample(n_samples=1)

Generate random samples from the fitted distribution.

Currently, this is implemented only for gaussian and tophat kernels.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 1)*
  : List of samples.

<a id="skfolio.distribution.JohnsonSU.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.JohnsonSU.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : An array of points at which to evaluate the log-probability density.
    The data should be a single feature column.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : Log-likelihood values for each observation in X.

<a id="skfolio.distribution.JohnsonSU.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.

# generated/skfolio.distribution.NormalInverseGaussian.html.md

<a id="skfolio-distribution-normalinversegaussian"></a>

# skfolio.distribution.NormalInverseGaussian

<a id="skfolio.distribution.NormalInverseGaussian"></a>

### *class* skfolio.distribution.NormalInverseGaussian(loc=None, scale=None, random_state=None)

Normal Inverse Gaussian Distribution Estimation.

This estimator fits a univariate Normal Inverse Gaussian (NIG) distribution
to the input data.

The probability density function is:

$$
f(x, a, b) = \frac{a \, K_1(a \sqrt{1 + x^2})}{\pi \sqrt{1 + x^2}} \,
             \exp(\sqrt{a^2 - b^2} + b x)
$$

where $x$ is a real number, the parameter $a$ is the tail
heaviness and $b$ is the asymmetry parameter satisfying $a > 0$
and $|b| <= a$. $K_1$ is the modified Bessel function of second kind
(`scipy.special.k1`).

The probability density above is defined in the “standardized” form. To shift
and/or scale the distribution use the loc and scale parameters. Specifically,
`pdf(x, a, b, loc, scale)` is equivalent to `pdf(y, a, b) / scale` with
`y = (x - loc) / scale`.

For more information, you can refer to the [scipy documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.norminvgauss.html#scipy.stats.norminvgauss)

* **Parameters:**
  **loc** *float, optional*
  : If provided, the location parameter is fixed to this value during fitting.
    Otherwise, it is estimated from the data.

  **scale** *float, optional*
  : If provided, the scale parameter is fixed to this value during fitting.
    Otherwise, it is estimated from the data.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  **a_** *float*
  : The fitted shape parameter a of the NIG distribution.

  **b_** *float*
  : The fitted shape parameter b of the NIG distribution.

  **loc_** *float*
  : The fitted location parameter.

  **scale_** *float*
  : The fitted scale parameter.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.aic)(X)                 | Compute the Akaike Information Criterion (AIC) for the model given data X.             |
|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.bic)(X)                 | Compute the Bayesian Information Criterion (BIC) for the model given data X.           |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.cdf)(X)                 | Compute the cumulative distribution function (CDF) for the given data.                 |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.fit)(X[, y])            | Fit the univariate Normal Inverse Gaussian distribution model.                         |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.get_metadata_routing)() | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.get_params)([deep])     | Get parameters for this estimator.                                                     |
| [`plot_pdf`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.plot_pdf)([X, title])   | Plot the probability density function (PDF).                                           |
| [`ppf`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.ppf)(X)                 | Compute the percent point function (inverse of the CDF) for the given                  |
| [`qq_plot`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.qq_plot)(X[, title])    | Plot the empirical quantiles of the sample X versus the quantiles of the fitted model. |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.sample)([n_samples])    | Generate random samples from the fitted distribution.                                  |
| [`score`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.score)(X[, y])          | Compute the total log-likelihood under the model.                                      |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.score_samples)(X)       | Compute the log-likelihood of each sample (log-pdf) under the model.                   |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.NormalInverseGaussian.html.md#skfolio.distribution.NormalInverseGaussian.set_params)(\*\*params) | Set the parameters of this estimator.                                                  |

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_index
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution.univariate import NormalInverseGaussian
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_index()
>>> X = prices_to_returns(prices)
>>>
>>> # Initialize the estimator.
>>> model = NormalInverseGaussian()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
NormalInverseGaussian(...)
>>>
>>> # Display the fitted parameters.
>>> print(model.fitted_repr)
NormalInverseGaussian(a=0.42, b=-0.032, loc=0.00091, scale=0.0074)
>>>
>>> # Compute the log-likelihood, total log-likelihood, CDF, PPF, AIC, and BIC
>>> log_likelihood = model.score_samples(X)
>>> score = model.score(X)
>>> cdf = model.cdf(X)
>>> ppf = model.ppf([0.01, 0.05, 0.5, 0.95, 0.99])
>>> aic = model.aic(X)
>>> bic = model.bic(X)
>>>
>>> # Generate 5 new samples from the fitted distribution.
>>> samples = model.sample(n_samples=5)
>>>
>>> # Plot the estimated probability density function (PDF).
>>> fig = model.plot_pdf()
```

<a id="skfolio.distribution.NormalInverseGaussian.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='rb2fed704a2a6-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.NormalInverseGaussian.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='ra14e22b9546c-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.NormalInverseGaussian.cdf"></a>

#### cdf(X)

Compute the cumulative distribution function (CDF) for the given data.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : Data points at which to evaluate the CDF.
* **Returns:**
  **cdf** *ndarray of shape (n_observations, 1)*
  : The CDF evaluated at each data point.

<a id="skfolio.distribution.NormalInverseGaussian.fit"></a>

#### fit(X, y=None)

Fit the univariate Normal Inverse Gaussian distribution model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : The input data. X must contain a single column.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *NormalInverseGaussian*
  : Returns the instance itself.

<a id="skfolio.distribution.NormalInverseGaussian.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted univariate distribution.

<a id="skfolio.distribution.NormalInverseGaussian.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.distribution.NormalInverseGaussian.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.distribution.NormalInverseGaussian.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.NormalInverseGaussian.plot_pdf"></a>

#### plot_pdf(X=None, title=None)

Plot the probability density function (PDF).

* **Parameters:**
  **X** *array-like of shape (n_samples, 1), optional*
  : If provided, it is used to plot the empirical data KDE for comparison
    versus the model PDF.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    model’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the PDF plot.

<a id="skfolio.distribution.NormalInverseGaussian.ppf"></a>

#### ppf(X)

Compute the percent point function (inverse of the CDF) for the given
: probabilities.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : Probabilities for which to compute the corresponding quantiles.
* **Returns:**
  **ppf** *ndarray of shape (n_observations, 1)*
  : The quantiles corresponding to the given probabilities.

<a id="skfolio.distribution.NormalInverseGaussian.qq_plot"></a>

#### qq_plot(X, title=None)

Plot the empirical quantiles of the sample X versus the quantiles of the
fitted model.

* **Parameters:**
  **X** *array-like of shape (n_samples, 1), optional*
  : Used to plot the empirical quantiles for comparison versus the model
    quantiles.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    model’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the PDF plot.

<a id="skfolio.distribution.NormalInverseGaussian.sample"></a>

#### sample(n_samples=1)

Generate random samples from the fitted distribution.

Currently, this is implemented only for gaussian and tophat kernels.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 1)*
  : List of samples.

<a id="skfolio.distribution.NormalInverseGaussian.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.NormalInverseGaussian.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : An array of points at which to evaluate the log-probability density.
    The data should be a single feature column.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : Log-likelihood values for each observation in X.

<a id="skfolio.distribution.NormalInverseGaussian.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.

# generated/skfolio.distribution.SelectionCriterion.html.md

<a id="skfolio-distribution-selectioncriterion"></a>

# skfolio.distribution.SelectionCriterion

<a id="skfolio.distribution.SelectionCriterion"></a>

### *class* skfolio.distribution.SelectionCriterion(\*values)

Enum representing the selection criteria.

* **Attributes:**
  **AIC** *str*
  : Akaike Information Criterion (AIC)

  **BIC** *str*
  : Bayesian Information Criterion (BIC)

<a id="skfolio.distribution.SelectionCriterion.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.distribution.StudentT.html.md

<a id="skfolio-distribution-studentt"></a>

# skfolio.distribution.StudentT

<a id="skfolio.distribution.StudentT"></a>

### *class* skfolio.distribution.StudentT(loc=None, scale=None, random_state=None)

Student’s t Distribution Estimation.

This estimator fits a univariate Student’s t distribution to the input data.

The probability density function is:

$$
f(x, \nu) = \frac{\Gamma((\nu+1)/2)}
                {\sqrt{\pi \nu} \Gamma(\nu/2)}
            (1+x^2/\nu)^{-(\nu+1)/2}
$$

where $x$ is a real number and the degrees of freedom parameter $\nu$
(denoted `dof` in the implementation) satisfies $\nu > 0$. $\Gamma$ is
the gamma function (`scipy.special.gamma`).

The probability density above is defined in the “standardized” form. To shift
and/or scale the distribution use the loc and scale parameters. Specifically,
`pdf(x, df, loc, scale)` is equivalent to `pdf(y, df) / scale` with
`y = (x - loc) / scale`.

For more information, you can refer to the [scipy documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.t.html#scipy.stats.t)

* **Parameters:**
  **loc** *float or None, default=None*
  : If provided, the location parameter is fixed to this value during fitting.
    Otherwise, it is estimated from the data.

  **scale** *float or None, default=None*
  : If provided, the scale parameter is fixed to this value during fitting.
    Otherwise, it is estimated from the data.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  **dof_** *float*
  : The fitted degrees of freedom for the Student’s t distribution.

  **loc_** *float*
  : The fitted location parameter.

  **scale_** *float*
  : The fitted scale parameter.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.aic)(X)                 | Compute the Akaike Information Criterion (AIC) for the model given data X.             |
|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.bic)(X)                 | Compute the Bayesian Information Criterion (BIC) for the model given data X.           |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.cdf)(X)                 | Compute the cumulative distribution function (CDF) for the given data.                 |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.fit)(X[, y])            | Fit the univariate Student's t distribution model.                                     |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.get_metadata_routing)() | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.get_params)([deep])     | Get parameters for this estimator.                                                     |
| [`plot_pdf`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.plot_pdf)([X, title])   | Plot the probability density function (PDF).                                           |
| [`ppf`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.ppf)(X)                 | Compute the percent point function (inverse of the CDF) for the given                  |
| [`qq_plot`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.qq_plot)(X[, title])    | Plot the empirical quantiles of the sample X versus the quantiles of the fitted model. |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.sample)([n_samples])    | Generate random samples from the fitted distribution.                                  |
| [`score`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.score)(X[, y])          | Compute the total log-likelihood under the model.                                      |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.score_samples)(X)       | Compute the log-likelihood of each sample (log-pdf) under the model.                   |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.StudentT.html.md#skfolio.distribution.StudentT.set_params)(\*\*params) | Set the parameters of this estimator.                                                  |

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_index
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution.univariate import StudentT
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_index()
>>> X = prices_to_returns(prices)
>>>
>>> # Initialize the estimator.
>>> model = StudentT()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
StudentT(...)
>>>
>>> # Display the fitted parameters.
>>> print(model.fitted_repr)
StudentT(loc=0.00062, scale=0.0068, df=2.7)
>>>
>>> # Compute the log-likelihood, total log-likelihood, CDF, PPF, AIC, and BIC
>>> log_likelihood = model.score_samples(X)
>>> score = model.score(X)
>>> cdf = model.cdf(X)
>>> ppf = model.ppf([0.01, 0.05, 0.5, 0.95, 0.99])
>>> aic = model.aic(X)
>>> bic = model.bic(X)
>>>
>>> # Generate 5 new samples from the fitted distribution.
>>> samples = model.sample(n_samples=5)
>>>
>>> # Plot the estimated probability density function (PDF).
>>> fig = model.plot_pdf()
```

<a id="skfolio.distribution.StudentT.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r219c46e80256-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.StudentT.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r6f1d052b627f-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.StudentT.cdf"></a>

#### cdf(X)

Compute the cumulative distribution function (CDF) for the given data.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : Data points at which to evaluate the CDF.
* **Returns:**
  **cdf** *ndarray of shape (n_observations, 1)*
  : The CDF evaluated at each data point.

<a id="skfolio.distribution.StudentT.fit"></a>

#### fit(X, y=None)

Fit the univariate Student’s t distribution model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : The input data. X must contain a single column.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *StudentT*
  : Returns the instance itself.

<a id="skfolio.distribution.StudentT.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted univariate distribution.

<a id="skfolio.distribution.StudentT.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.distribution.StudentT.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.distribution.StudentT.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.StudentT.plot_pdf"></a>

#### plot_pdf(X=None, title=None)

Plot the probability density function (PDF).

* **Parameters:**
  **X** *array-like of shape (n_samples, 1), optional*
  : If provided, it is used to plot the empirical data KDE for comparison
    versus the model PDF.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    model’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the PDF plot.

<a id="skfolio.distribution.StudentT.ppf"></a>

#### ppf(X)

Compute the percent point function (inverse of the CDF) for the given
: probabilities.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : Probabilities for which to compute the corresponding quantiles.
* **Returns:**
  **ppf** *ndarray of shape (n_observations, 1)*
  : The quantiles corresponding to the given probabilities.

<a id="skfolio.distribution.StudentT.qq_plot"></a>

#### qq_plot(X, title=None)

Plot the empirical quantiles of the sample X versus the quantiles of the
fitted model.

* **Parameters:**
  **X** *array-like of shape (n_samples, 1), optional*
  : Used to plot the empirical quantiles for comparison versus the model
    quantiles.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    model’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the PDF plot.

<a id="skfolio.distribution.StudentT.sample"></a>

#### sample(n_samples=1)

Generate random samples from the fitted distribution.

Currently, this is implemented only for gaussian and tophat kernels.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 1)*
  : List of samples.

<a id="skfolio.distribution.StudentT.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.StudentT.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : An array of points at which to evaluate the log-probability density.
    The data should be a single feature column.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : Log-likelihood values for each observation in X.

<a id="skfolio.distribution.StudentT.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.

# generated/skfolio.distribution.StudentTCopula.html.md

<a id="skfolio-distribution-studenttcopula"></a>

# skfolio.distribution.StudentTCopula

<a id="skfolio.distribution.StudentTCopula"></a>

### *class* skfolio.distribution.StudentTCopula(itau=True, kendall_tau=None, tolerance=0.0001, random_state=None)

Bivariate Student’s t Copula Estimation.

The bivariate Student’s t copula density is defined as:

$$
C_{\nu, \rho}(u, v) = T_{\nu, \rho} \Bigl(t_{\nu}^{-1}(u),\;t_{\nu}^{-1}(v)\Bigr)

$$

where:
: - $\nu > 0$ is the degrees of freedom.
  - $\rho \in (-1, 1)$ is the correlation coefficient.
  - $T_{\nu, \rho}(x, y)$ is the CDF of the bivariate t-distribution.
  - $t_{\nu}^{-1}(p)$ is the quantile function (inverse CDF) of the
    univariate t-distribution.

Student’s t copula with degrees of freedom (dof) less than 2.0 is extremely
heavy-tailed, to the extent that even the mean (and many moments) do not exist,
rendering it impractical. Conversely, for dof above 50 the t copula behaves
similarly to a Gaussian copula. Thus, for improved stability and robustness,
the dof is limited to the interval [2, 50].

#### NOTE
Rotations are not needed for elliptical copula (e.g., Gaussian or Student-t)
because its correlation parameter $\rho \in (-1, 1)$ naturally covers
both positive and negative dependence, and they exhibit symmetric tail behavior.

* **Parameters:**
  **itau** *bool, default=True*
  : itau : bool, default=True
    If True, $\rho$ is estimated using the Kendall’s tau inversion method;
    otherwise, we use the MLE (Maximum Likelihood Estimation) method. The MLE is
    slower but more accurate.

  **kendall_tau** *float, optional*
  : If `itau` is True and `kendall_tau` is provided, this
    value is used; otherwise, it is computed.

  **tolerance** *float, default=1e-4*
  : Convergence tolerance for the MLE optimization.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  **rho_** *float*
  : Fitted correlation coefficient ($\rho$) in [-1, 1].

  **dof_** *float*
  : Fitted degrees of freedom ($\nu$) > 2.

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.aic)(X)                                        | Compute the Akaike Information Criterion (AIC) for the model given data X.                                                                                     |
|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.bic)(X)                                        | Compute the Bayesian Information Criterion (BIC) for the model given data X.                                                                                   |
| [`cdf`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.cdf)(X)                                        | Compute the CDF of the bivariate Student-t copula.                                                                                                             |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.fit)(X[, y])                                   | Fit the Bivariate Student's t Copula.                                                                                                                          |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.get_metadata_routing)()                        | Get metadata routing of this object.                                                                                                                           |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.get_params)([deep])                            | Get parameters for this estimator.                                                                                                                             |
| [`inverse_partial_derivative`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.inverse_partial_derivative)(X[, first_margin]) | Compute the inverse of the bivariate copula's partial derivative, commonly known as the inverse h-function [[1]](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#r545b7220ce64-1). |
| [`partial_derivative`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.partial_derivative)(X[, first_margin])         | Compute the h-function (partial derivative) for the bivariate Student's t copula.                                                                              |
| [`plot_pdf_2d`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.plot_pdf_2d)([title])                          | Plot a 2D contour of the estimated probability density function (PDF).                                                                                         |
| [`plot_pdf_3d`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.plot_pdf_3d)([title])                          | Plot a 3D surface of the estimated probability density function (PDF).                                                                                         |
| [`plot_tail_concentration`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.plot_tail_concentration)([X, title])           | Plot the tail concentration function.                                                                                                                          |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.sample)([n_samples])                           | Generate random samples from the bivariate copula using the inverse Rosenblatt transform.                                                                      |
| [`score`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.score)(X[, y])                                 | Compute the total log-likelihood under the model.                                                                                                              |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.score_samples)(X)                              | Compute the log-likelihood of each sample (log-pdf) under the model.                                                                                           |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.set_params)(\*\*params)                        | Set the parameters of this estimator.                                                                                                                          |
| [`tail_concentration`](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#skfolio.distribution.StudentTCopula.tail_concentration)(quantiles)                 | Compute the tail concentration function for a set of quantiles.                                                                                                |

### References

* <a id='r77ea93c803cf-1'>**[1]**</a> “An Introduction to Copulas (2nd ed.)”, Nelsen (2006)
* <a id='r77ea93c803cf-2'>**[2]**</a> “Multivariate Models and Dependence Concepts”, Joe, Chapman & Hall (1997)
* <a id='r77ea93c803cf-3'>**[3]**</a> “Quantitative Risk Management: Concepts, Techniques and Tools”, McNeil, Frey & Embrechts (2005)
* <a id='r77ea93c803cf-4'>**[4]**</a> “The t Copula and Related Copulas”, Demarta & McNeil (2005)
* <a id='r77ea93c803cf-5'>**[5]**</a> “Copula Methods in Finance”, Cherubini, Luciano & Vecchiato (2004)

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution import StudentTCopula, compute_pseudo_observations
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(504)
>>> X = X[["AAPL", "JPM"]]
>>>
>>> # Convert returns to pseudo observation in the interval [0,1]
>>> X = compute_pseudo_observations(X)
>>>
>>> # Initialize the Copula estimator
>>> model = StudentTCopula()
>>>
>>> # Fit the model to the data.
>>> model.fit(X)
StudentTCopula(...)
>>>
>>> # Display the fitted parameter and tail dependence coefficients
>>> print(model.fitted_repr)
StudentTCopula(rho=0.385, dof=4.90)
>>> print(model.lower_tail_dependence)
0.157...
>>> print(model.upper_tail_dependence)
0.157...
>>>
>>> # Compute the log-likelihood, total log-likelihood, CDF, Partial Derivative,
>>> # Inverse Partial Derivative, AIC, and BIC
>>> log_likelihood = model.score_samples(X)
>>> score = model.score(X)
>>> cdf = model.cdf(X)
>>> p = model.partial_derivative(X)
>>> u = model.inverse_partial_derivative(X)
>>> aic = model.aic(X)
>>> bic = model.bic(X)
>>>
>>> # Generate 5 new samples
>>> samples = model.sample(n_samples=5)
>>>
>>> # Plot the tail concentration function.
>>> fig = model.plot_tail_concentration()
>>>
>>> # Plot a 2D contour of the estimated PDF.
>>> fig = model.plot_pdf_2d()
>>>
>>> # Plot a 3D surface of the estimated PDF.
>>> fig = model.plot_pdf_3d()
```

<a id="skfolio.distribution.StudentTCopula.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r85028b203ba8-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.StudentTCopula.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r95845f2ac3ff-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.StudentTCopula.cdf"></a>

#### cdf(X)

Compute the CDF of the bivariate Student-t copula.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **cdf** *ndarray of shape (n_observations,)*
  : CDF values for each observation in X.

<a id="skfolio.distribution.StudentTCopula.fit"></a>

#### fit(X, y=None)

Fit the Bivariate Student’s t Copula.

If `itau` is True, it uses a Kendall-based two-step method:
: - Estimates the correlation parameter ($\rho$) from Kendall’s
    tau inversion.
  - Optimizes the degrees of freedom ($\nu$) by maximizing the
    log-likelihood.

Otherwise, it uses the full MLE method: optimizes both $\rho$ and
$\nu$ by maximizing the log-likelihood.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval [0, 1],
    having been transformed to uniform marginals.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **self** *StudentTCopula*
  : Returns the instance itself.

<a id="skfolio.distribution.StudentTCopula.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted copula.

<a id="skfolio.distribution.StudentTCopula.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.distribution.StudentTCopula.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.distribution.StudentTCopula.inverse_partial_derivative"></a>

#### inverse_partial_derivative(X, first_margin=False)

Compute the inverse of the bivariate copula’s partial derivative, commonly
known as the inverse h-function [[1]](https://skfolio.org/generated/skfolio.distribution.StudentTCopula.html.md#r545b7220ce64-1).

Let $C(u, v)$ be a bivariate copula. The h-function with respect to the
second margin is defined by

$$
h(u \mid v) \;=\; \frac{\partial\,C(u, v)}{\partial\,v},

$$

which is the conditional distribution of $U$ given $V = v$.
The **inverse h-function**, denoted $h^{-1}(p \mid v)$, is the unique
value $u \in [0,1]$ such that

$$
h(u \mid v) \;=\; p,
\quad \text{where } p \in [0,1].

$$

In practical terms, given $(p, v)$ in $[0, 1]^2$,
$h^{-1}(p \mid v)$ solves for the $u$ satisfying
$p = \partial C(u, v)/\partial v$.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(p, v)`, each in the interval `[0, 1]`.
    - The first column `p` corresponds to the value of the h-function.
    - The second column `v` is the conditioning variable.

  **first_margin** *bool, default=False*
  : If True, compute the inverse partial derivative with respect to the first
    margin `u`; otherwise, compute the inverse partial derivative with respect
    to the second margin `v`.
* **Returns:**
  **u** *ndarray of shape (n_observations,)*
  : A 1D-array of length `n_observations`, where each element is the computed
    $u = h^{-1}(p \mid v)$ for the corresponding pair in `X`.

### References

* <a id='r545b7220ce64-1'>**[1]**</a> “Multivariate Models and Dependence Concepts”, Joe, H. (1997)
* <a id='r545b7220ce64-2'>**[2]**</a> “An Introduction to Copulas”, Nelsen, R. B. (2006)

<a id="skfolio.distribution.StudentTCopula.lower_tail_dependence"></a>

#### *property* lower_tail_dependence

Theoretical lower tail dependence coefficient.

<a id="skfolio.distribution.StudentTCopula.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.StudentTCopula.partial_derivative"></a>

#### partial_derivative(X, first_margin=False)

Compute the h-function (partial derivative) for the bivariate Student’s t
copula.

The h-function with respect to the second margin represents the conditional
distribution function of $u$ given $v$:

$$
\begin{aligned}
 h(u \mid v) &= \frac{\partial C(u,v)}{\partial v} \\
             &= t_{\nu+1}\!\left(\frac{t_\nu^{-1}(u) - \rho\,t_\nu^{-1}(v)}
                {\sqrt{\frac{(1-\rho^2)\left(\nu + \left(t_\nu^{-1}(v)\right)^2\right)}{\nu+1}}}\right).
\end{aligned}

$$

where:
: - $\nu > 0$ is the degrees of freedom.
  - $\rho \in (-1, 1)$ is the correlation coefficient.
  - $t_{\nu}^{-1}(p)$ is the quantile function (inverse CDF) of the
    univariate (t)-distribution.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.

  **first_margin** *bool, default=False*
  : If True, compute the partial derivative with respect to the first
    margin `u`; otherwise, compute the partial derivative with respect to the
    second margin `v`.
* **Returns:**
  **p** *ndarray of shape (n_observations,)*
  : h-function values $h(u \mid v) \;=\; p$ for each observation in X.

<a id="skfolio.distribution.StudentTCopula.plot_pdf_2d"></a>

#### plot_pdf_2d(title=None)

Plot a 2D contour of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
contour plot of the PDF.
Contour levels are limited to the 97th quantile to avoid extreme densities.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the 2D contour plot of the PDF.

<a id="skfolio.distribution.StudentTCopula.plot_pdf_3d"></a>

#### plot_pdf_3d(title=None)

Plot a 3D surface of the estimated probability density function (PDF).

This method generates a grid over [0, 1]^2, computes the PDF, and displays a
3D surface plot of the PDF using Plotly.

* **Parameters:**
  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing a 3D surface plot of the PDF.

<a id="skfolio.distribution.StudentTCopula.plot_tail_concentration"></a>

#### plot_tail_concentration(X=None, title=None)

Plot the tail concentration function.

This method computes the tail concentration function at 100 evenly spaced
quantile levels between 0.005 and 0.995.
The plot displays the concentration values on the y-axis and the quantile levels
on the x-axis.

The tail concentration is defined as:
: - Lower tail: λ_L(q) = P(U₂ ≤ q | U₁ ≤ q)
  - Upper tail: λ_U(q) = P(U₂ ≥ q | U₁ ≥ q)

where U₁ and U₂ are the pseudo-observations of the first and second variables,
respectively.

* **Parameters:**
  **X** *array-like of shape (n_samples, 2), optional*
  : If provided, it is used to plot the empirical tail concentration for
    comparison versus the model tail concentration.

  **title** *str, optional*
  : The title for the plot. If not provided, a default title based on the fitted
    copula’s representation is used.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the tail concentration curve.

### References

* <a id='r3a8c6760c227-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.StudentTCopula.sample"></a>

#### sample(n_samples=1)

Generate random samples from the bivariate copula using the inverse
Rosenblatt transform.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.
* **Returns:**
  **X** *array-like of shape (n_samples, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` are uniform marginals in the
    interval `[0, 1]`.

<a id="skfolio.distribution.StudentTCopula.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.StudentTCopula.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs `(u, v)` where each row represents a
    bivariate observation. Both `u` and `v` must be in the interval `[0, 1]`,
    having been transformed to uniform marginals.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : The log-likelihood of each sample under the fitted copula.

<a id="skfolio.distribution.StudentTCopula.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.

<a id="skfolio.distribution.StudentTCopula.tail_concentration"></a>

#### tail_concentration(quantiles)

Compute the tail concentration function for a set of quantiles.

The tail concentration function is defined as follows:
: - For quantiles q ≤ 0.5:
    : C(q) = P(U ≤ q, V ≤ q) / q
  - For quantiles q > 0.5:
    : C(q) = (1 - 2q + P(U ≤ q, V ≤ q)) / (1 - q)

where U and V are the pseudo-observations of the first and second variables,
respectively. This function returns the concentration values for each q
provided.

* **Parameters:**
  **quantiles** *ndarray of shape (n_quantiles,)*
  : A 1D array of quantile levels (values between 0 and 1) at which to compute
    the tail concentration.
* **Returns:**
  **concentration** *ndarray of shape (n_quantiles,)*
  : The computed tail concentration values corresponding to each quantile.
* **Raises:**
  ValueError
  : If any value in `quantiles` is not in the interval [0, 1].

### References

* <a id='r8effa94fcca2-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

<a id="skfolio.distribution.StudentTCopula.upper_tail_dependence"></a>

#### *property* upper_tail_dependence

Theoretical upper tail dependence coefficient.

# generated/skfolio.distribution.VineCopula.html.md

<a id="skfolio-distribution-vinecopula"></a>

# skfolio.distribution.VineCopula

<a id="skfolio.distribution.VineCopula"></a>

### *class* skfolio.distribution.VineCopula(fit_marginals=True, marginal_candidates=None, copula_candidates=None, max_depth=4, log_transform=False, central_assets=None, dependence_method=KENDALL_TAU, selection_criterion=AIC, independence_level=0.05, n_jobs=None, random_state=None)

Regular Vine Copula Estimator.

This model first fits the best univariate distribution for each asset, transforming
the data to uniform marginals via the fitted CDFs. Then, it constructs a regular
vine copula by sequentially selecting the best bivariate copula from a list of
candidates for each edge in the vine using a maximum spanning tree algorithm based
on a given dependence measure [[1]](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#r05b9bab6cf6a-1).

Regular vines captures complex, fat-tailed dependencies and tail co-movements
between asset returns.

It also supports conditional sampling, enabling stress testing and scenario analysis
by generating samples under specified conditions.

Moreover, by marking some assets as central, this novel implementation is able to
capture clustered or C-like dependency structures, allowing for more nuanced
representation of hierarchical relationships among assets and improving conditional
sampling and stress testing.

* **Parameters:**
  **fit_marginals** *bool, default=True*
  : Whether to fit marginal distributions to each asset before constructing the
    vine. If True, the data will be transformed to uniform marginals using the
    fitted CDFs.

  **marginal_candidates** *list[BaseUnivariateDist], optional*
  : Candidate univariate distribution estimators to fit the marginals.
    If None, defaults to `[Gaussian(), StudentT(), JohnsonSU()]`.

  **copula_candidates** *list[BaseBivariateCopula], optional*
  : Candidate bivariate copula estimators. If None, defaults to
    `[GaussianCopula(), StudentTCopula(), ClaytonCopula(), GumbelCopula(), JoeCopula()]`.

  **max_depth** *int or None, default=4*
  : Maximum vine depth (truncated level). Must be greater than 1.
    `None` means that no truncation is applied. The default is 4.

  **log_transform** *bool | dict[str, bool] | array-like of shape (n_assets, ), default=False*
  : If True, the simple returns provided as input will be transformed to log returns
    before fitting the vine copula. That is, each return R is transformed via
    r = log(1+R). After sampling, the generated log returns are converted back to
    simple returns using R = exp(r) - 1.
    <br/>
    If a boolean is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/boolean) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.

  **central_assets** *array-like of asset names or asset positions, optional*
  : Assets that should be centrally placed during vine construction.
    If None, no asset is forced to the center.
    If an array-like of **integer** is provided, its values must be asset positions.
    If an array-like of **string** is provided, its values must be asset names and
    the input `X` of the `fit` method must be a DataFrame with the assets names in
    columns. Assets marked as central are forced to occupy central positions in the
    vine, leading to C-like or clustered structure. This is needed for conditional
    sampling, where the conditioning assets should be central nodes.
    <br/>
    For example:
    - If only asset 1 is marked as central, it will be connected to all other
      : assets in the first tree (yielding a C-like structure for the initial
        tree), with subsequent trees following the standard R-vine pattern.
    - If asset 1 and asset 2 are marked as central, they will be connected
      : together and the remaining assets will connect to either asset 1 or asset
        2 (forming a clustered structure in the initial trees). In the next tree,
        the edge between asset 1 and asset 2 becomes the central node, with
        subsequent trees following the standard R-vine structure.
    - This logic extends naturally to more than two central assets.

  **dependence_method** *DependenceMethod, default=DependenceMethod.KENDALL_TAU*
  : The dependence measure used to compute edge weights for the MST.
    Possible values are:
    - KENDALL_TAU
    - MUTUAL_INFORMATION
    - WASSERSTEIN_DISTANCE

  **selection_criterion** *SelectionCriterion, default=SelectionCriterion.AIC*
  : The criterion used for univariate and copula selection. Possible values are:
    - SelectionCriterion.AIC : Akaike Information Criterion
    - SelectionCriterion.BIC : Bayesian Information Criterion

  **independence_level** *float, default=0.05*
  : Significance level used for the Kendall tau independence test during copula
    fitting. If the p-value exceeds this threshold, the null hypothesis of
    independence is accepted, and the pair copula is modeled using the
    `IndependentCopula()` class.

  **n_jobs** *int, optional*
  : The number of jobs to run in parallel for `fit` of all `estimators`.
    The value `-1` means using all processors.
    The default (`None`) means 1 unless in a `joblib.parallel_backend` context.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.
* **Attributes:**
  **trees_** *list[Tree]*
  : List of constructed vine trees.

  **marginal_distributions_** *list[BaseUnivariateDist]*
  : List of fitted marginal distributions (if fit_marginals is True).

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

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

### Methods

| [`aic`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.aic)(X)                                      | Compute the Akaike Information Criterion (AIC) for the model given data X.                                                                                          |
|----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`bic`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.bic)(X)                                      | Compute the Bayesian Information Criterion (BIC) for the model given data X.                                                                                        |
| [`clear_cache`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.clear_cache)([clear_count])                  | Clear cached intermediate results in the vine trees.                                                                                                                |
| [`display_vine`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.display_vine)()                              | Display the vine trees and fitted copulas.                                                                                                                          |
| [`fit`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.fit)(X[, y])                                 | Fit the Vine Copula model to the data.                                                                                                                              |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.get_metadata_routing)()                      | Get metadata routing of this object.                                                                                                                                |
| [`get_params`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.get_params)([deep])                          | Get parameters for this estimator.                                                                                                                                  |
| [`plot_marginal_distributions`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.plot_marginal_distributions)([X, ...])       | Plot overlaid marginal distributions.                                                                                                                               |
| [`plot_scatter_matrix`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.plot_scatter_matrix)([X, conditioning, ...]) | Plot the vine copula scatter matrix by generating samples from the fitted distribution model and comparing it versus the empirical distribution of `X` if provided. |
| [`sample`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.sample)([n_samples, conditioning])           | Generate random samples from the vine copula.                                                                                                                       |
| [`score`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.score)(X[, y])                               | Compute the total log-likelihood under the model.                                                                                                                   |
| [`score_samples`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.score_samples)(X)                            | Compute the log-likelihood of each sample (log-pdf) under the model.                                                                                                |
| [`set_params`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula.set_params)(\*\*params)                      | Set the parameters of this estimator.                                                                                                                               |

### References

* <a id='r05b9bab6cf6a-1'>**[1]**</a> “Selecting and estimating regular vine copulae and application to financial returns” Dißmann, Brechmann, Czado, and Kurowicka (2013).
* <a id='r05b9bab6cf6a-2'>**[2]**</a> “Growing simplified vine copula trees: improving Dißmann’s algorithm” Krausa and Czado (2017).
* <a id='r05b9bab6cf6a-3'>**[3]**</a> “Pair-copula constructions of multiple dependence” Aas, Czado, Frigessi, Bakken (2009).
* <a id='r05b9bab6cf6a-4'>**[4]**</a> “Pair-Copula Constructions for Financial Applications: A Review” Aas and Czado (2016).
* <a id='r05b9bab6cf6a-5'>**[5]**</a> “Conditional copula simulation for systemic risk stress testing” Brechmann, Hendrich, Czado (2013)

### Examples

```pycon
>>> from skfolio.datasets import load_factors_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution import VineCopula
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_factors_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # Instantiate the VineCopula model
>>> vine = VineCopula()
>>> # Fit the model
>>> vine.fit(X)
VineCopula(...)
>>> # Display the vine trees and fitted copulas
>>> vine.display_vine()
Root Nodes
...
>>> # Log-likelihood, AIC and BIC
>>> log_likelihood = vine.score(X)
>>> aic = vine.aic(X)
>>> bic = vine.bic(X)
>>>
>>> # Generate 10 samples from the fitted vine copula
>>> samples = vine.sample(n_samples=10)
>>>
>>> # Set QUAL, SIZE and MTUM as central
>>> vine = VineCopula(central_assets=["QUAL", "SIZE", "MTUM"])
>>> vine.fit(X)
VineCopula(...)
>>> # Sample by conditioning on QUAL and SIZE returns
>>> samples = vine.sample(
...    n_samples=4,
...    conditioning={
...        "QUAL": [-0.1, -0.2, -0.3, -0.4],
...        "SIZE": -0.2,
...        "MTUM": (None, -0.3) # MTUM sampled between -Inf and -30%
...    },
... )
>>> # Plots Scatter matrix of sampled returns vs historical X
>>> fig = vine.plot_scatter_matrix(X=X)
>>>
>>> # Plots univariate distributions of sampled returns vs historical X
>>> fig = vine.plot_marginal_distributions(X=X)
```

<a id="skfolio.distribution.VineCopula.aic"></a>

#### aic(X)

Compute the Akaike Information Criterion (AIC) for the model given data X.

The AIC is defined as:

$$
\mathrm{AIC} = -2 \, \log L \;+\; 2 k,

$$

where

- $\log L$ is the total log-likelihood
- $k$ is the number of parameters in the model

A lower AIC value indicates a better trade-off between model fit and complexity.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the AIC.
* **Returns:**
  **aic** *float*
  : The AIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='rc53278a5dfc7-1'>**[1]**</a> “A new look at the statistical model identification”, Akaike (1974).

<a id="skfolio.distribution.VineCopula.bic"></a>

#### bic(X)

Compute the Bayesian Information Criterion (BIC) for the model given data X.

The BIC is defined as:

$$
\mathrm{BIC} = -2 \, \log L \;+\; k \,\ln(n),

$$

where

- $\log L$ is the (maximized) total log-likelihood
- $k$ is the number of parameters in the model
- $n$ is the number of observations

A lower BIC value suggests a better fit while imposing a stronger penalty
for model complexity than the AIC.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : The input data on which to compute the BIC.
* **Returns:**
  **bic** *float*
  : The BIC of the fitted model on the given data.

### Notes

In practice, both AIC and BIC measure the trade-off between model fit and
complexity, but BIC tends to prefer simpler models for large $n$
because of the $\ln(n)$ term.

### References

* <a id='r03ba3df2b986-1'>**[1]**</a> “Estimating the dimension of a model”, Schwarz, G. (1978).

<a id="skfolio.distribution.VineCopula.clear_cache"></a>

#### clear_cache(clear_count=True)

Clear cached intermediate results in the vine trees.

<a id="skfolio.distribution.VineCopula.display_vine"></a>

#### display_vine()

Display the vine trees and fitted copulas.
Prints the structure of each tree and the details of each edge.

<a id="skfolio.distribution.VineCopula.fit"></a>

#### fit(X, y=None)

Fit the Vine Copula model to the data.

* **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.
* **Returns:**
  **self** *VineCopula*
  : The fitted VineCopula instance.
* **Raises:**
  ValueError
  : If the number of assets is less than or equal to 2, or if max_depth <= 1.

<a id="skfolio.distribution.VineCopula.fitted_repr"></a>

#### *property* fitted_repr

String representation of the fitted Vine Copula.

<a id="skfolio.distribution.VineCopula.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.distribution.VineCopula.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.distribution.VineCopula.n_params"></a>

#### *property* n_params

Number of model parameters.

<a id="skfolio.distribution.VineCopula.plot_marginal_distributions"></a>

#### plot_marginal_distributions(X=None, conditioning=None, subset=None, n_samples=500, percentile_cutoff=None, title='Vine Copula Marginal Distributions')

Plot overlaid marginal distributions.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_assets), optional*
  : Historical data where each column corresponds to an asset.

  **conditioning** *dict[int | str, float | tuple[float, float] | array-like], optional*
  : A dictionary specifying conditioning information for one or more assets.
    The dictionary keys are asset indices or names, and the values define how
    the samples are conditioned for that asset. Three types of conditioning
    values are supported:
    1. **Fixed value (float):**
       If a float is provided, all samples are generated under the condition
       that the asset takes exactly that value.
    2. **Bounds (tuple of two floats):**
       If a tuple `(min_value, max_value)` is provided, samples are generated
       under the condition that the asset’s value falls within the specified
       bounds. Use `-np.Inf` for no lower bound or `np.Inf` for no upper bound.
    3. **Array-like (1D array):**
       If an array-like of length `n_samples` is provided, each sample is
       conditioned on the corresponding value in the array for that asset.
    <br/>
    When using conditional sampling, it is recommended that the
    assets you condition on are set as central during the vine copula
    construction. This can be specified via the `central_assets` parameter in
    the vine copula instantiation.

  **subset** *list[int | str], optional*
  : Indices or names of assets to include in the plot. If None, all assets are
    used.

  **n_samples** *int, default=500*
  : Number of samples used to control the density and readability of the plot.
    If `X` is provided and contains more than `n_samples` rows, a random
    subsample of size `n_samples` is selected. Conversely, if `X` has fewer
    rows than `n_samples`, the value is adjusted to match the number of rows in
    `X` to ensure balanced visualization.

  **percentile_cutoff** *float, default=None*
  : Percentile cutoff for tail truncation (percentile), in percent.
    If a float p is provided, the distribution support is truncated at
    the p-th and (100 - p)-th percentiles.
    If None, no truncation is applied (uses full min/max of returns).

  **title** *str, default=”Vine Copula Marginal Distributions”*
  : The title for the plot.
* **Returns:**
  **fig** *plotly.graph_objects.Figure*
  : A figure with overlaid univariate distributions for each asset.

<a id="skfolio.distribution.VineCopula.plot_scatter_matrix"></a>

#### plot_scatter_matrix(X=None, conditioning=None, n_samples=1000, title='Scatter Matrix')

Plot the vine copula scatter matrix by generating samples from the fitted
distribution model and comparing it versus the empirical distribution of `X` if
provided.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_assets), optional*
  : If provided, it is used to plot the empirical scatter matrix for
    comparison versus the vine copula scatter matrix.

  **conditioning** *dict[int | str, float | tuple[float, float] | array-like], optional*
  : A dictionary specifying conditioning information for one or more assets.
    The dictionary keys are asset indices or names, and the values define how
    the samples are conditioned for that asset. Three types of conditioning
    values are supported:
    1. **Fixed value (float):**
       If a float is provided, all samples are generated under the condition
       that the asset takes exactly that value.
    2. **Bounds (tuple of two floats):**
       If a tuple `(min_value, max_value)` is provided, samples are generated
       under the condition that the asset’s value falls within the specified
       bounds. Use `-np.Inf` for no lower bound or `np.Inf` for no upper bound.
    3. **Array-like (1D array):**
       If an array-like of length `n_samples` is provided, each sample is
       conditioned on the corresponding value in the array for that asset.

  **n_samples** *int, default=1000*
  : Number of samples used to control the density and readability of the plot.
    If `X` is provided and contains more than `n_samples` rows, a random
    subsample of size `n_samples` is selected. Conversely, if `X` has fewer
    rows than `n_samples`, the value is adjusted to match the number of rows in
    `X` to ensure balanced visualization.

  **title** *str, default=”Scatter Matrix”*
  : The title for the plot.
* **Returns:**
  **fig** *plotly.graph_objects.Figure*
  : A figure object containing the scatter matrix.

<a id="skfolio.distribution.VineCopula.sample"></a>

#### sample(n_samples=1, conditioning=None)

Generate random samples from the vine copula.

This method generates `n_samples` from the fitted vine copula model. The
resulting samples represent multivariate observations drawn according to the
dependence structure captured by the vine copula.

* **Parameters:**
  **n_samples** *int, default=1*
  : Number of samples to generate.

  **conditioning** *dict[int | str, float | tuple[float, float] | array-like], optional*
  : A dictionary specifying conditioning information for one or more assets.
    The dictionary keys are asset indices or names, and the values define how
    the samples are conditioned for that asset. Three types of conditioning
    values are supported:
    1. **Fixed value (float):**
       If a float is provided, all samples are generated under the condition
       that the asset takes exactly that value.
    2. **Bounds (tuple of two floats):**
       If a tuple `(min_value, max_value)` is provided, samples are generated
       under the condition that the asset’s value falls within the specified
       bounds. Use `-np.Inf` for no lower bound or `np.Inf` for no upper bound.
    3. **Array-like (1D array):**
       If an array-like of length `n_samples` is provided, each sample is
       conditioned on the corresponding value in the array for that asset.
    <br/>
    **Important:** When using conditional sampling, it is recommended that the
    assets you condition on are set as central during the vine copula
    construction. This can be specified via the `central_assets` parameter in
    the vine copula instantiation.
* **Returns:**
  **X** *array-like of shape (n_samples, n_assets)*
  : A two-dimensional array where each row is a multivariate observation sampled
    from the vine copula.

<a id="skfolio.distribution.VineCopula.score"></a>

#### score(X, y=None)

Compute the total log-likelihood under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_features)*
  : An array of data points for which the total log-likelihood is computed.

  **y** *None*
  : Ignored. Provided for compatibility with scikit-learn’s API.
* **Returns:**
  **logprob** *float*
  : The total log-likelihood (sum of log-pdf values).

<a id="skfolio.distribution.VineCopula.score_samples"></a>

#### score_samples(X)

Compute the log-likelihood of each sample (log-pdf) under the model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  **density** *ndarray of shape (n_observations,)*
  : The log-likelihood of each sample under the fitted vine copula.

<a id="skfolio.distribution.VineCopula.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.

# generated/skfolio.distribution.compute_pseudo_observations.html.md

<a id="skfolio-distribution-compute-pseudo-observations"></a>

# skfolio.distribution.compute_pseudo_observations

<a id="skfolio.distribution.compute_pseudo_observations"></a>

### skfolio.distribution.compute_pseudo_observations(X)

Compute pseudo-observations by ranking each column of the data and scaling the
ranks.

The goal of computing pseudo-observations is to transform your raw data into a
form that has uniform marginal distributions on the open interval (0, 1). This is
particularly useful in copula modeling and other statistical methods where the
dependence structure is of primary interest, independent of the marginal
distributions.

This function transforms each column of the input data into pseudo-observations
on the (0, 1) interval. For each column, the ranks (starting at 1) are divided by
(n_samples + 1) to avoid 0 and 1 values, which are problematic for many copula
methods.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input data.
* **Returns:**
  pseudo_observations: ndarray of shape (n_observations, n_assets)
  : An array of pseudo-observations corresponding to the ranks scaled to (0, 1).

# generated/skfolio.distribution.empirical_tail_concentration.html.md

<a id="skfolio-distribution-empirical-tail-concentration"></a>

# skfolio.distribution.empirical_tail_concentration

<a id="skfolio.distribution.empirical_tail_concentration"></a>

### skfolio.distribution.empirical_tail_concentration(X, quantiles)

Compute empirical tail concentration for the two variables in X.
This function computes the concentration at each quantile provided.

The tail concentration are estimated as:
: - Lower tail: λ_L(q) = P(U₂ ≤ q | U₁ ≤ q)
  - Upper tail: λ_U(q) = P(U₂ ≥ q | U₁ ≥ q)

where U₁ and U₂ are the pseudo-observations.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : A 2D array with exactly 2 columns representing the pseudo-observations.

  **quantiles** *array-like of shape (n_quantiles,)*
  : A 1D array of quantile levels (values between 0 and 1) at which to compute the
    concentration.
* **Returns:**
  **concentration** *ndarray of shape (n_quantiles,)*
  : An array of empirical tail concentration values for the given quantiles.
* **Raises:**
  ValueError
  : If X is not a 2D array with exactly 2 columns or if quantiles are not in [0, 1].

### References

* <a id='rc9ce9bd57366-1'>**[1]**</a> “Quantitative Risk Management: Concepts, Techniques, and Tools”, McNeil, Frey, Embrechts (2005)

# generated/skfolio.distribution.plot_tail_concentration.html.md

<a id="skfolio-distribution-plot-tail-concentration"></a>

# skfolio.distribution.plot_tail_concentration

<a id="skfolio.distribution.plot_tail_concentration"></a>

### skfolio.distribution.plot_tail_concentration(tail_concentration_dict, quantiles, title='Empirical Tail Dependencies', smoothing=0.5)

Plot the empirical tail concentration curves.

This function takes a dictionary where keys are dataset names and values are the
corresponding tail concentration arrays computed at the given quantiles. It then
creates a Plotly figure with the tail concentration curves. The x-axis (quantiles)
and y-axis (tail concentration) are both formatted as percentages.

* **Parameters:**
  **tail_concentration_dict** *dict[str, ArrayLike]*
  : A dictionary mapping dataset names to their tail concentration values.

  **quantiles** *array-like of shape (n_quantiles,)*
  : The quantile levels at which the tail concentration has been computed.

  **title** *str, default=”Empirical Tail Dependencies”*
  : The title for the plot.

  **smoothing** *float or None, default=0.5*
  : Smoothing parameter for the spline line shape. If provided, the curves will be
    smoothed using a spline interpolation.
* **Returns:**
  **fig** *go.Figure*
  : A Plotly figure object containing the tail concentration curves.
* **Raises:**
  ValueError
  : If the smoothing parameter is not in the allowed range.

# generated/skfolio.distribution.select_bivariate_copula.html.md

<a id="skfolio-distribution-select-bivariate-copula"></a>

# skfolio.distribution.select_bivariate_copula

<a id="skfolio.distribution.select_bivariate_copula"></a>

### skfolio.distribution.select_bivariate_copula(X, copula_candidates=None, selection_criterion=AIC, independence_level=0.05)

Select the best bivariate copula from a list of candidates using an information
criterion.

This function first tests the dependence between the two variables in X using
Kendall’s tau independence test. If the p-value is greater than or equal to
`independence_level`, the null hypothesis of independence is not rejected, and the
`IndependentCopula` is returned. Otherwise, each candidate copula in
`copula_candidates` is fitted to the data X. For each candidate, either the
Akaike Information Criterion (AIC) or the Bayesian Information Criterion (BIC) is
computed, and the copula with the lowest criterion value is selected.

* **Parameters:**
  **X** *array-like of shape (n_observations, 2)*
  : An array of bivariate inputs (u, v) with uniform marginals (values in [0, 1]).

  **copula_candidates** *list[BaseBivariateCopula]*
  : A list of candidate copula models. Each candidate must inherit from
    `BaseBivariateCopula`. If None, defaults to
    `[GaussianCopula(), StudentTCopula(), ClaytonCopula(), GumbelCopula(), JoeCopula()]`.

  **selection_criterion** *SelectionCriterion, default=SelectionCriterion.AIC*
  : The criterion used for model selection. Possible values are:
    : - SelectionCriterion.AIC : Akaike Information Criterion
      - SelectionCriterion.BIC : Bayesian Information Criterion

  **independence_level** *float, default=0.05*
  : The significance level for the Kendall tau independence test. If the p-value is
    greater than or equal to this level, the independence hypothesis is not
    rejected, and the `IndependentCopula` is returned.
* **Returns:**
  **selected_copula** *BaseBivariateCopula*
  : The fitted copula model among the candidates that minimizes the selected
    information criterion (AIC or BIC).
* **Raises:**
  ValueError
  : If X is not a 2D array with exactly two columns, or if any candidate in
    `copula_candidates` does not inherit from `BaseBivariateCopula`.

# generated/skfolio.distribution.select_univariate_dist.html.md

<a id="skfolio-distribution-select-univariate-dist"></a>

# skfolio.distribution.select_univariate_dist

<a id="skfolio.distribution.select_univariate_dist"></a>

### skfolio.distribution.select_univariate_dist(X, distribution_candidates=None, selection_criterion=AIC)

Select the optimal univariate distribution estimator based on an information
criterion.

For each candidate distribution, the function fits the distribution to X and then
computes either the Akaike Information Criterion (AIC) or the Bayesian Information
Criterion (BIC). The candidate with the lowest criterion value is returned.

* **Parameters:**
  **X** *array-like of shape (n_observations, 1)*
  : The input data used to fit each candidate distribution.

  **distribution_candidates** *list of BaseUnivariateDist*
  : A list of candidate distribution estimators. Each candidate must be an instance
    of a class that inherits from `BaseUnivariateDist`.
    If None, defaults to `[Gaussian(), StudentT(), JohnsonSU()]`.

  **selection_criterion** *SelectionCriterion, default=SelectionCriterion.AIC*
  : The criterion used for model selection. Possible values are:
    : - SelectionCriterion.AIC : Akaike Information Criterion
      - SelectionCriterion.BIC : Bayesian Information Criterion
* **Returns:**
  BaseUnivariateDist
  : The fitted candidate estimator that minimizes the selected information
    criterion.
* **Raises:**
  ValueError
  : If X does not have exactly one column or if any candidate in the list does not
    inherit from BaseUnivariateDist.

# generated/skfolio.factor_exposure.BaseFactorExposure.html.md

<a id="skfolio-factor-exposure-basefactorexposure"></a>

# skfolio.factor_exposure.BaseFactorExposure

<a id="skfolio.factor_exposure.BaseFactorExposure"></a>

### *class* skfolio.factor_exposure.BaseFactorExposure(\*, family)

Base class for factor exposure estimators.

A factor exposure estimator takes an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) and
returns asset exposures to one or more factors. Single-factor estimators return
values with shape `(n_observations, n_assets)`. Multi-factor estimators return
values with shape `(n_observations, n_assets, n_factors)`.

Factor exposures follow the [`BaseAssetPanelTransformer`](https://skfolio.org/generated/skfolio.base.BaseAssetPanelTransformer.html.md#skfolio.base.BaseAssetPanelTransformer)
protocol:

- Batch-only estimators implement only `fit_transform`.
- Stateless estimators declare `stateless=True` and implement only `fit_transform`.
  The base class adds `partial_fit_transform` by delegating to `fit_transform`.
- Online estimators implement both `fit_transform` and `partial_fit_transform`.
  `fit_transform` starts from a clean state and `partial_fit_transform` continues
  from the current state.

* **Parameters:**
  **family** *str*
  : The factor family this exposure belongs to (e.g., “market”, “style”, “industry”,
    “country”). Factor families group related factors for basket-neutral
    constraints, neutralization, attribution and reporting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.factor_exposure.BaseFactorExposure.html.md#skfolio.factor_exposure.BaseFactorExposure.fit_transform)(X[, y])   | Fit the transformer if needed and return transformed values.   |
|--------------------------------------------------------------------------|----------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.factor_exposure.BaseFactorExposure.html.md#skfolio.factor_exposure.BaseFactorExposure.get_metadata_routing)()  | Get metadata routing of this object.                           |
| [`get_params`](https://skfolio.org/generated/skfolio.factor_exposure.BaseFactorExposure.html.md#skfolio.factor_exposure.BaseFactorExposure.get_params)([deep])      | Get parameters for this estimator.                             |
| [`set_params`](https://skfolio.org/generated/skfolio.factor_exposure.BaseFactorExposure.html.md#skfolio.factor_exposure.BaseFactorExposure.set_params)(\*\*params)  | Set the parameters of this estimator.                          |

#### SEE ALSO
[`BaseAssetPanelTransformer`](https://skfolio.org/generated/skfolio.base.BaseAssetPanelTransformer.html.md#skfolio.base.BaseAssetPanelTransformer)
: Shared transformer contract.

[`BaseDescriptor`](https://skfolio.org/generated/skfolio.descriptor.BaseDescriptor.html.md#skfolio.descriptor.BaseDescriptor)
: Computes raw descriptor values.

<a id="skfolio.factor_exposure.BaseFactorExposure.fit_transform"></a>

#### *abstractmethod* fit_transform(X, y=None, \*\*fit_params)

Fit the transformer if needed and return transformed values.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel data.

  **y** *None*
  : Ignored. Present for API consistency.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Metadata routing may pass these parameters to
    sub-estimators when applicable.
* **Returns:**
  **values** *ndarray of shape (n_observations, n_assets) or (n_observations, n_assets, n_components)*
  : Transformed values.

<a id="skfolio.factor_exposure.BaseFactorExposure.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.factor_exposure.BaseFactorExposure.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.factor_exposure.BaseFactorExposure.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.

# generated/skfolio.factor_exposure.DerivedFactor.html.md

<a id="skfolio-factor-exposure-derivedfactor"></a>

# skfolio.factor_exposure.DerivedFactor

<a id="skfolio.factor_exposure.DerivedFactor"></a>

### *class* skfolio.factor_exposure.DerivedFactor(\*, source, func, family='style', outlier_transformer='passthrough', scoring_transformer=None, transform_by_group=None)

Factor exposure derived from another factor’s computed exposure.

The derived exposure is computed by applying `func` to the source factor’s
exposure, then optionally applying outlier and scoring transformations.

* **Parameters:**
  **source** *str*
  : Name of the source factor whose exposure will be transformed. The source factor
    must be defined in the factors list of `CharacteristicsFactorModel`. Dependency
    ordering is handled automatically via topological sorting.

  **func** *Callable[[np.ndarray], np.ndarray]*
  : Function to apply to the source exposure. Receives a 2D array of shape
    (n_observations, n_assets) and should return an array of the same shape.
    The source exposure is passed directly. If `func` uses in-place operations,
    it should copy the input first unless mutating the source exposure is intended.

  **family** *str, default=”style”*
  : The factor family this exposure belongs to (e.g., “market”, “style”, “industry”,
    “country”). Factor families group related factors for basket-neutral constraints,
    neutralization, attribution and reporting. The default is `"style"`.

  **outlier_transformer** *BaseCSTransformer or “passthrough” or None, default=”passthrough”*
  : Cross-sectional transformer for outlier handling applied after `func`. If None,
    defaults to `CSWinsorizer()`. Use “passthrough” to skip.

  **scoring_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for scoring applied after outlier handling.
    If None, defaults to `CSStandardScaler()`. Use “passthrough” to skip.

  **transform_by_group** *str, optional*
  : Name of a categorical characteristic in the AssetPanel to use for group-wise
    transformations. If provided, outlier and scoring transformations are applied
    within each group separately.
* **Attributes:**
  **outlier_transformer_** *BaseCSTransformer or str*
  : The fitted outlier transformer.

  **scoring_transformer_** *BaseCSTransformer or str*
  : The fitted scoring transformer.

  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.factor_exposure.DerivedFactor.html.md#skfolio.factor_exposure.DerivedFactor.fit_transform)(X[, y, source_exposure])   | Fit and transform the source exposure.         |
|-------------------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.factor_exposure.DerivedFactor.html.md#skfolio.factor_exposure.DerivedFactor.get_metadata_routing)()                   | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.factor_exposure.DerivedFactor.html.md#skfolio.factor_exposure.DerivedFactor.get_params)([deep])                       | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.factor_exposure.DerivedFactor.html.md#skfolio.factor_exposure.DerivedFactor.partial_fit_transform)(X[, y])            | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.factor_exposure.DerivedFactor.html.md#skfolio.factor_exposure.DerivedFactor.set_params)(\*\*params)                   | Set the parameters of this estimator.          |

### Examples

```pycon
>>> from skfolio.factor_exposure import DerivedFactor, FixedWeightedFactor
>>> from skfolio.descriptor import LogMarketCap
>>> from skfolio.prior import CharacteristicsFactorModel
>>>
>>> # Non linear size factor
>>> factors = [
...     ("size", FixedWeightedFactor(descriptors=[("log_mcap", LogMarketCap())])),
...     ("non_linear_size", DerivedFactor(source="size", func=lambda x: x**3)),
... ]
>>>
>>> # Orthogonalize non_linear_size vs size
>>> model = CharacteristicsFactorModel(
...     factors=factors,
...     neutralize_against={"non_linear_size": ["size"]},
... )
```

<a id="skfolio.factor_exposure.DerivedFactor.fit_transform"></a>

#### fit_transform(X, y=None, source_exposure=None, \*\*fit_params)

Fit and transform the source exposure.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing benchmark weights and optional grouping.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **source_exposure** *ndarray of shape (n_observations, n_assets)*
  : The computed exposure from the source factor. This is passed automatically
    by `CharacteristicsFactorModel`.

  **\*\*fit_params** *dict*
  : Additional fit parameters (unused).
* **Returns:**
  **exposure** *ndarray of shape (n_observations, n_assets)*
  : The derived factor exposure.

<a id="skfolio.factor_exposure.DerivedFactor.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.factor_exposure.DerivedFactor.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.factor_exposure.DerivedFactor.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.factor_exposure.DerivedFactor.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.

# generated/skfolio.factor_exposure.FixedWeightedFactor.html.md

<a id="skfolio-factor-exposure-fixedweightedfactor"></a>

# skfolio.factor_exposure.FixedWeightedFactor

<a id="skfolio.factor_exposure.FixedWeightedFactor"></a>

### *class* skfolio.factor_exposure.FixedWeightedFactor(\*, descriptors, family='style', weights=None, min_coverage=0.0, outlier_transformer=None, scoring_transformer=None, transform_by_group=None, n_jobs=1)

Factor exposure as a fixed weighted combination of descriptors.

Computes descriptor values, applies cross-sectional outlier and scoring transforms
to each descriptor, then combines the resulting scores into a single factor exposure
matrix with shape `(n_observations, n_assets)`.

For descriptor $i$, let $s_{i,t,j}$ be its score for observation
$t$ and asset $j$ after the cross-sectional transforms, $w_i$ its
fixed non-negative weight and $V_{t,j}$ the set of descriptors with a finite
score. The weighted composite is:

$$
c_{t,j} = \frac{\sum_{i \in V_{t,j}} w_i \, s_{i,t,j}}
               {\sum_{i \in V_{t,j}} w_i}
$$

Weights are renormalized over available scores for each asset-observation pair.
This allows assets with structurally unavailable descriptor values (e.g., Gross
Margin for financial firms, which do not report cost of goods sold) to receive a
composite score from the remaining descriptors. When all descriptor scores are
non-finite for a pair, the composite is NaN.

The `min_coverage` parameter controls the minimum fraction of total descriptor
weight that must be valid for the composite to be computed. If the valid weight
fraction falls below this threshold, the composite is set to NaN instead. This
guards against low-quality exposures based on too few descriptors.

The default `min_coverage=0.0` uses any available descriptor (no threshold), which
maximizes coverage.  A value of `0.5` requires at least half the descriptor weight
to be valid.

When multiple descriptors are combined and `scoring_transformer` is not
`"passthrough"`, the composite is scored again cross-sectionally so assets with
different descriptor coverage are on the same scale. The final exposure is this
re-scored composite, or the weighted composite when scoring is skipped.

`weights` are fixed inputs and are not learned by this estimator. They can be set
from economic priors or selected by hyperparameter tuning.

* **Parameters:**
  **descriptors** *list of tuple (str, BaseDescriptor)*
  : List of `(name, descriptor)` pairs. Each descriptor computes values from the
    [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel).

  **family** *str, default=”style”*
  : The factor family this exposure belongs to (e.g., “market”, “style”, “industry”,
    “country”). Factor families group related factors for basket-neutral constraints,
    neutralization, attribution and reporting. The default is `"style"`.

  **weights** *array-like of shape (n_descriptors,), optional*
  : Non-negative descriptor combination weights. Must sum to 1. If `None` (default),
    equal weights are used.

  **min_coverage** *float, default=0.0*
  : Minimum fraction of total descriptor weight that must be finite for the
    composite to be computed. Values where the valid weight fraction is below this
    threshold are set to NaN. Must be in `[0, 1]`.
    - `0.0` (default): use any available descriptor. Maximizes cross-sectional coverage.
    - `0.5`: require at least half the descriptor weight to be valid.
    <br/>
    The threshold is weight-based, not count-based. If descriptor weights are
    `[0.8, 0.2]` and only the first descriptor is valid, the valid weight fraction
    is 0.8, so a `min_coverage=0.5` threshold is satisfied even though only 1 out of
    2 descriptors is present.

  **outlier_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for outlier handling. If None, defaults to
    `CSWinsorizer()`. Use “passthrough” to skip.

  **scoring_transformer** *BaseCSTransformer or “passthrough”, optional*
  : Cross-sectional transformer for scoring applied after outlier handling.
    If None, defaults to `CSStandardScaler()`. Use “passthrough” to skip.

  **transform_by_group** *str, optional*
  : Name of a categorical characteristic in the AssetPanel to use for group-wise
    transformations. If provided, outlier and scoring transformations are applied
    within each group separately.

  **n_jobs** *int, default=1*
  : Number of parallel jobs for descriptor computation.
* **Attributes:**
  **descriptors_** *list of BaseDescriptor*
  : Fitted descriptor estimators.

  **named_descriptors_** *dict of {str: BaseDescriptor}*
  : Dictionary mapping descriptor names to fitted estimators.

  **outlier_transformer_** *BaseCSTransformer or str*
  : The fitted outlier transformer.

  **scoring_transformer_** *BaseCSTransformer or str*
  : The fitted scoring transformer.

  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.factor_exposure.FixedWeightedFactor.html.md#skfolio.factor_exposure.FixedWeightedFactor.fit_transform)(X[, y])         | Compute factor exposure from a clean descriptor state.   |
|--------------------------------------------------------------------------------|----------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.factor_exposure.FixedWeightedFactor.html.md#skfolio.factor_exposure.FixedWeightedFactor.get_metadata_routing)()        | Return metadata routing for descriptor estimators.       |
| [`get_params`](https://skfolio.org/generated/skfolio.factor_exposure.FixedWeightedFactor.html.md#skfolio.factor_exposure.FixedWeightedFactor.get_params)([deep])            | Get the parameters of an estimator from the ensemble.    |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.factor_exposure.FixedWeightedFactor.html.md#skfolio.factor_exposure.FixedWeightedFactor.partial_fit_transform)(X[, y]) | Update descriptor state and compute factor exposure.     |
| [`set_params`](https://skfolio.org/generated/skfolio.factor_exposure.FixedWeightedFactor.html.md#skfolio.factor_exposure.FixedWeightedFactor.set_params)(\*\*params)        | Set the parameters of a factor from the ensemble.        |

<a id="skfolio.factor_exposure.FixedWeightedFactor.fit_transform"></a>

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

Compute factor exposure from a clean descriptor state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing “benchmark_weights”, descriptor fields and optional
    grouping fields.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters passed to descriptors through metadata routing.
* **Returns:**
  **exposure** *ndarray of shape (n_observations, n_assets)*
  : Fixed-weighted factor exposure.

<a id="skfolio.factor_exposure.FixedWeightedFactor.get_metadata_routing"></a>

#### get_metadata_routing()

Return metadata routing for descriptor estimators.

<a id="skfolio.factor_exposure.FixedWeightedFactor.get_params"></a>

#### get_params(deep=True)

Get the parameters of an estimator from the ensemble.

Returns the parameters given in the constructor as well as the
estimators contained within the `estimators` parameter.

* **Parameters:**
  **deep** *bool, default=True*
  : Setting it to True gets the various estimators and the parameters
    of the estimators as well.
* **Returns:**
  **params** *dict*
  : Parameter and estimator names mapped to their values or parameter
    names mapped to their values.

<a id="skfolio.factor_exposure.FixedWeightedFactor.named_descriptors"></a>

#### *property* named_descriptors

Dictionary to access any fitted factors by name.

* **Returns:**
  `Bunch`

<a id="skfolio.factor_exposure.FixedWeightedFactor.partial_fit_transform"></a>

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

Update descriptor state and compute factor exposure.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing benchmark weights, descriptor fields and optional
    grouping fields.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters passed to descriptors through metadata routing.
* **Returns:**
  **exposure** *ndarray of shape (n_observations, n_assets)*
  : Fixed-weighted factor exposure for the new observations.

<a id="skfolio.factor_exposure.FixedWeightedFactor.set_params"></a>

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

Set the parameters of a factor from the ensemble.

Valid parameter keys can be listed with `get_params()`. Note that you
can directly set the parameters of the estimators contained in
`estimators`.

* **Parameters:**
  **\*\*params** *keyword arguments*
  : Specific parameters using e.g.
    `set_params(parameter_name=new_value)`. In addition, to setting the
    parameters of the estimator, the individual estimator of the
    estimators can also be set, or can be removed by setting them to
    ‘drop’.
* **Returns:**
  **self** *object*
  : Estimator instance.

# generated/skfolio.factor_exposure.GlobalFactor.html.md

<a id="skfolio-factor-exposure-globalfactor"></a>

# skfolio.factor_exposure.GlobalFactor

<a id="skfolio.factor_exposure.GlobalFactor"></a>

### *class* skfolio.factor_exposure.GlobalFactor(\*, family='market')

Constant factor exposure equal to one for every asset.

`GlobalFactor` represents a cross-sectional regression intercept or broad market
factor in a characteristics factor model. It does not depend on any characteristic
field. It uses the panel dimensions to return an exposure matrix of ones with shape
`(n_observations, n_assets)`.

For each observation $t$ and asset $i$, the exposure is:

$$
x_{t,i} = 1
$$

This factor is typically used when the cross-sectional regression should estimate
a common return component in addition to characteristic-based style industry or
country factors.

* **Parameters:**
  **family** *str, default=”market”*
  : The factor family this exposure belongs to. Factor families group related
    factors for basket-neutral constraints, neutralization, attribution and
    reporting. The default is `"market"`.
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.factor_exposure.GlobalFactor.html.md#skfolio.factor_exposure.GlobalFactor.fit_transform)(X[, y])         | Return a constant exposure matrix.             |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.factor_exposure.GlobalFactor.html.md#skfolio.factor_exposure.GlobalFactor.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.factor_exposure.GlobalFactor.html.md#skfolio.factor_exposure.GlobalFactor.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.factor_exposure.GlobalFactor.html.md#skfolio.factor_exposure.GlobalFactor.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.factor_exposure.GlobalFactor.html.md#skfolio.factor_exposure.GlobalFactor.set_params)(\*\*params)        | Set the parameters of this estimator.          |

### Examples

```pycon
>>> from skfolio.factor_exposure import GlobalFactor
>>> from skfolio.prior import CharacteristicsFactorModel
>>>
>>> model = CharacteristicsFactorModel(
...     factors=[("market", GlobalFactor())]
... )
```

<a id="skfolio.factor_exposure.GlobalFactor.fit_transform"></a>

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

Return a constant exposure matrix.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel used to determine the number of observations and assets.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. They are ignored.
* **Returns:**
  **exposure** *ndarray of shape (n_observations, n_assets)*
  : Constant factor exposure equal to one for every asset in every observation.

<a id="skfolio.factor_exposure.GlobalFactor.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.factor_exposure.GlobalFactor.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.factor_exposure.GlobalFactor.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.factor_exposure.GlobalFactor.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.

# generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md

<a id="skfolio-factor-exposure-onehotcategoricalfactors"></a>

# skfolio.factor_exposure.OneHotCategoricalFactors

<a id="skfolio.factor_exposure.OneHotCategoricalFactors"></a>

### *class* skfolio.factor_exposure.OneHotCategoricalFactors(category, \*, family)

One-hot factor exposures from a categorical field.

Expands a categorical field into one factor per category level. The result is an
exposure tensor with shape `(n_observations, n_assets, n_factors)`, where
`n_factors` is the number of category levels.

For each observation $t$, asset $i$ and category factor $k$, the
exposure is:

$$
x_{t,i,k} =
\begin{cases}
1 & \text{if asset } i \text{ belongs to category } k \\
0 & \text{otherwise}
\end{cases}
$$

Missing category codes produce NaN exposures for all category factors of that
asset-observation pair.

* **Parameters:**
  **category** *str*
  : Name of the categorical field in the AssetPanel to one-hot encode. The field
    must be a `FieldCategorical`.

  **family** *str*
  : The factor family this exposure belongs to (e.g., “industry”, “country”).
    Factor families group related factors for basket-neutral constraints,
    neutralization, attribution and reporting.
* **Attributes:**
  **factor_names_** *ndarray of shape (n_factors,)*
  : The category labels corresponding to each one-hot column.

  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

### Methods

| [`fit_transform`](https://skfolio.org/generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md#skfolio.factor_exposure.OneHotCategoricalFactors.fit_transform)(X[, y])         | One-hot encode the categorical field.          |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md#skfolio.factor_exposure.OneHotCategoricalFactors.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md#skfolio.factor_exposure.OneHotCategoricalFactors.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](https://skfolio.org/generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md#skfolio.factor_exposure.OneHotCategoricalFactors.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](https://skfolio.org/generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md#skfolio.factor_exposure.OneHotCategoricalFactors.set_params)(\*\*params)        | Set the parameters of this estimator.          |

<a id="skfolio.factor_exposure.OneHotCategoricalFactors.fit_transform"></a>

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

One-hot encode the categorical field.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing the categorical field as integer codes.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. They are ignored.
* **Returns:**
  **exposures** *ndarray of shape (n_observations, n_assets, n_factors)*
  : One-hot encoded exposures. Column order matches `X.fields[category].levels`.
    Entries with missing codes (MISSING_CATEGORY_CODE == -1) are filled with
    NaN.
* **Raises:**
  IndexError
  : If any valid code is >= n_levels (indicates data corruption).

<a id="skfolio.factor_exposure.OneHotCategoricalFactors.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.factor_exposure.OneHotCategoricalFactors.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.factor_exposure.OneHotCategoricalFactors.partial_fit_transform"></a>

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

Stateless class delegation to `fit_transform`.

<a id="skfolio.factor_exposure.OneHotCategoricalFactors.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.

# generated/skfolio.linear_model.BaseCSLinearModel.html.md

<a id="skfolio-linear-model-basecslinearmodel"></a>

# skfolio.linear_model.BaseCSLinearModel

<a id="skfolio.linear_model.BaseCSLinearModel"></a>

### *class* skfolio.linear_model.BaseCSLinearModel(fit_intercept=False)

Base class for all cross-sectional linear model estimators.

This abstract base class defines the common interface for cross-sectional linear
model estimators that fit one linear model per observation across a set of assets.
Subclasses are responsible for implementing `fit` and for setting the fitted
attributes used by `predict` and `score`.

* **Parameters:**
  **fit_intercept** *bool, default=False*
  : Whether to calculate the intercept for each observation. If set to False, no
    intercept will be used in calculations.
* **Attributes:**
  **coef_** *ndarray of shape (n_observations, n_features)*
  : Estimated coefficients for each observation.

  **intercept_** *ndarray of shape (n_observations,)*
  : intercept for each observation. Set to zeros if `fit_intercept=False`.

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

  **n_valid_assets_** *ndarray of shape (n_observations,)*
  : Number of assets that participated in estimation (those with positive
    weight) for each observation.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.linear_model.BaseCSLinearModel.html.md#skfolio.linear_model.BaseCSLinearModel.fit)(X, y[, cs_weights])             | Fit one cross-sectional linear model per observation.                              |
|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.linear_model.BaseCSLinearModel.html.md#skfolio.linear_model.BaseCSLinearModel.get_metadata_routing)()              | Get metadata routing of this object.                                               |
| [`get_params`](https://skfolio.org/generated/skfolio.linear_model.BaseCSLinearModel.html.md#skfolio.linear_model.BaseCSLinearModel.get_params)([deep])                  | Get parameters for this estimator.                                                 |
| [`predict`](https://skfolio.org/generated/skfolio.linear_model.BaseCSLinearModel.html.md#skfolio.linear_model.BaseCSLinearModel.predict)(X)                          | Predict using the cross-sectional linear model.                                    |
| [`score`](https://skfolio.org/generated/skfolio.linear_model.BaseCSLinearModel.html.md#skfolio.linear_model.BaseCSLinearModel.score)(X, y[, cs_weights])           | Return the mean coefficient of determination across observations.                  |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.linear_model.BaseCSLinearModel.html.md#skfolio.linear_model.BaseCSLinearModel.set_fit_request)(\*[, cs_weights])   | Configure whether metadata should be requested to be passed to the `fit` method.   |
| [`set_params`](https://skfolio.org/generated/skfolio.linear_model.BaseCSLinearModel.html.md#skfolio.linear_model.BaseCSLinearModel.set_params)(\*\*params)              | Set the parameters of this estimator.                                              |
| [`set_score_request`](https://skfolio.org/generated/skfolio.linear_model.BaseCSLinearModel.html.md#skfolio.linear_model.BaseCSLinearModel.set_score_request)(\*[, cs_weights]) | Configure whether metadata should be requested to be passed to the `score` method. |

<a id="skfolio.linear_model.BaseCSLinearModel.fit"></a>

#### *abstractmethod* fit(X, y, cs_weights=None)

Fit one cross-sectional linear model per observation.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets, n_features)*
  : Feature tensor. The first axis indexes observations, the second
    axis indexes assets, and the third axis indexes features.

  **y** *array-like of shape (n_observations, n_assets)*
  : Target values aligned with `X`.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Cross-sectional weights for each `(observation, asset)` pair.
* **Returns:**
  **self** *BaseCSLinearModel*
  : Fitted estimator.

<a id="skfolio.linear_model.BaseCSLinearModel.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.linear_model.BaseCSLinearModel.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.linear_model.BaseCSLinearModel.predict"></a>

#### predict(X)

Predict using the cross-sectional linear model.

For each observation $t$ and asset $i$, the prediction is
the systematic part; realized outcomes satisfy
$y_{ti} = \hat{y}_{ti} + \epsilon_{ti}$ with residual
$\epsilon_{ti}$. The prediction is

$$
\hat{y}_{ti} = X_{ti}^{T} \beta_t + \beta_{t,0}
$$

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets, n_features)*
  : Feature tensor used for prediction.
    The observation and feature axes must match those seen during
    `fit`. The asset axis may differ.
* **Returns:**
  **y_pred** *ndarray of shape (n_observations, n_assets)*
  : Predicted values.

<a id="skfolio.linear_model.BaseCSLinearModel.score"></a>

#### score(X, y, cs_weights=None)

Return the mean coefficient of determination across observations.

The coefficient of determination $R^2$ is computed independently
for each observation and then averaged. For observation $t$:

$$
R^2_t = 1 - \frac{\sum_i w_{ti}(y_{ti} - \hat{y}_{ti})^2}
                 {\sum_i w_{ti}(y_{ti} - \bar{y}_t)^2}
$$

where $\bar{y}_t$ is the weighted mean of $y$ for
observation $t$.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets, n_features)*
  : Feature tensor on which to evaluate the model.

  **y** *array-like of shape (n_observations, n_assets)*
  : Target values aligned with `X`.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Asset weights for computing weighted $R^2$ scores.
    If None, all assets are given equal weight. Pairs with zero weight
    are excluded from the score. Pairs with positive weight must have
    finite `X` and finite `y`.
* **Returns:**
  **score** *float*
  : Mean $R^2$ across all observations with finite values.
    Returns NaN if no observations have valid $R^2$ values.

<a id="skfolio.linear_model.BaseCSLinearModel.set_fit_request"></a>

#### set_fit_request(\*, cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.linear_model.BaseCSLinearModel.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.

<a id="skfolio.linear_model.BaseCSLinearModel.set_score_request"></a>

#### set_score_request(\*, cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.linear_model.CSLinearRegression.html.md

<a id="skfolio-linear-model-cslinearregression"></a>

# skfolio.linear_model.CSLinearRegression

<a id="skfolio.linear_model.CSLinearRegression"></a>

### *class* skfolio.linear_model.CSLinearRegression(fit_intercept=False)

Cross-sectional weighted least squares regression.

This estimator fits one weighted least squares regression per
observation across the asset cross-section. The implementation is fully
vectorized and is designed for panel data whose asset universe may vary
over time.

The model solves the weighted least squares problem independently for each
observation:

$$
\beta_t = \arg\min_{\beta} \sum_{i=1}^{n_{\text{assets}}}
          w_{ti} (y_{ti} - X_{ti}^T \beta)^2
$$

where $t$ denotes the observation, $i$ denotes the asset,
$w_{ti}$ are the cross-section weights, and $X_{ti}$ is the
feature vector for asset $i$ at observation $t$.

The cross-sectional weights must be finite and non-negative. A pair with
zero weight is excluded from estimation for that observation. This is the
intended way to represent inactive pairs such as assets outside the
estimation universe, listed or delisted assets, or pairs with missing (NaNs)
data.

For each `(observation, asset)` pair:

- If `cs_weights > 0`, all features in `X` and `y` must be finite.
- If `cs_weights == 0`, the pair is excluded from estimation and `X` and
  `y` may be finite or missing (NaNs).

* **Parameters:**
  **fit_intercept** *bool, default=False*
  : Whether to calculate the intercept for each observation.
    If set to False, no intercept will be used in calculations.
* **Attributes:**
  **coef_** *ndarray of shape (n_observations, n_features)*
  : Estimated coefficients for each observation.

  **intercept_** *ndarray of shape (n_observations,)*
  : Intercept for each observation. Set to zeros if `fit_intercept=False`.

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

  **n_valid_assets_** *ndarray of shape (n_observations,)*
  : Number of assets that participated in estimation (those with positive weight)
    for each observation.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression.fit)(X, y[, cs_weights])             | Fit the cross-sectional regression model.                                          |
|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression.get_metadata_routing)()              | Get metadata routing of this object.                                               |
| [`get_params`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression.get_params)([deep])                  | Get parameters for this estimator.                                                 |
| [`predict`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression.predict)(X)                          | Predict using the cross-sectional linear model.                                    |
| [`score`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression.score)(X, y[, cs_weights])           | Return the mean coefficient of determination across observations.                  |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression.set_fit_request)(\*[, cs_weights])   | Configure whether metadata should be requested to be passed to the `fit` method.   |
| [`set_params`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression.set_params)(\*\*params)              | Set the parameters of this estimator.                                              |
| [`set_score_request`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression.set_score_request)(\*[, cs_weights]) | Configure whether metadata should be requested to be passed to the `score` method. |

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.linear_model import CSLinearRegression
>>>
>>> rng = np.random.RandomState(42)
>>> X = rng.randn(3, 5, 2)
>>> y = rng.randn(3, 5)
>>>
>>> model = CSLinearRegression()
>>> model.fit(X, y)
CSLinearRegression()
>>>
>>> model.intercept_.shape
(3,)
>>> model.coef_.shape
(3, 2)
>>> model.predict(X).shape
(3, 5)
>>> model.score(X, y)
0.6353...
```

<a id="skfolio.linear_model.CSLinearRegression.fit"></a>

#### fit(X, y, cs_weights=None)

Fit the cross-sectional regression model.

Estimates regression coefficients independently for each observation by
solving weighted least squares problems across assets.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets, n_features)*
  : Training data.  3D array where the first axis indexes
    observations, the second axis indexes assets, and the third
    axis indexes features.

  **y** *array-like of shape (n_observations, n_assets)*
  : Target values.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Cross-sectional weights for each `(observation, asset)` pair.
    - Must be finite and non-negative.
    - Pairs with zero weight are excluded from estimation.
    - If None, all pairs receive unit weight.
* **Returns:**
  **self** *CSLinearRegression*
  : Fitted estimator.

### Notes

Each `(observation, asset)` pair with positive `cs_weights` must have
finite `X` and finite `y`. Pairs with zero weight are excluded from
estimation and may contain missing values.

<a id="skfolio.linear_model.CSLinearRegression.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.linear_model.CSLinearRegression.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.linear_model.CSLinearRegression.predict"></a>

#### predict(X)

Predict using the cross-sectional linear model.

For each observation $t$ and asset $i$, the prediction is
the systematic part; realized outcomes satisfy
$y_{ti} = \hat{y}_{ti} + \epsilon_{ti}$ with residual
$\epsilon_{ti}$. The prediction is

$$
\hat{y}_{ti} = X_{ti}^{T} \beta_t + \beta_{t,0}
$$

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets, n_features)*
  : Feature tensor used for prediction.
    The observation and feature axes must match those seen during
    `fit`. The asset axis may differ.
* **Returns:**
  **y_pred** *ndarray of shape (n_observations, n_assets)*
  : Predicted values.

<a id="skfolio.linear_model.CSLinearRegression.score"></a>

#### score(X, y, cs_weights=None)

Return the mean coefficient of determination across observations.

The coefficient of determination $R^2$ is computed independently
for each observation and then averaged. For observation $t$:

$$
R^2_t = 1 - \frac{\sum_i w_{ti}(y_{ti} - \hat{y}_{ti})^2}
                 {\sum_i w_{ti}(y_{ti} - \bar{y}_t)^2}
$$

where $\bar{y}_t$ is the weighted mean of $y$ for
observation $t$.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets, n_features)*
  : Feature tensor on which to evaluate the model.

  **y** *array-like of shape (n_observations, n_assets)*
  : Target values aligned with `X`.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Asset weights for computing weighted $R^2$ scores.
    If None, all assets are given equal weight. Pairs with zero weight
    are excluded from the score. Pairs with positive weight must have
    finite `X` and finite `y`.
* **Returns:**
  **score** *float*
  : Mean $R^2$ across all observations with finite values.
    Returns NaN if no observations have valid $R^2$ values.

<a id="skfolio.linear_model.CSLinearRegression.set_fit_request"></a>

#### set_fit_request(\*, cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.linear_model.CSLinearRegression.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.

<a id="skfolio.linear_model.CSLinearRegression.set_score_request"></a>

#### set_score_request(\*, cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md

<a id="skfolio-linear-model-cslinearregressorwrapper"></a>

# skfolio.linear_model.CSLinearRegressorWrapper

<a id="skfolio.linear_model.CSLinearRegressorWrapper"></a>

### *class* skfolio.linear_model.CSLinearRegressorWrapper(regressor, n_jobs=1)

Cross-sectional regression based on a scikit-learn regressor.

This estimator wraps a scikit-learn regressor and fits one independent regression
across assets for each observation. These independent observation-level regressions
can be fitted in parallel by setting `n_jobs`. The wrapped regressor must define
`fit_intercept`, implement `fit`, accept a `sample_weight` argument, and expose
fitted `coef_` and `intercept_` attributes.

Missing-value handling is driven by `cs_weights` on each `(observation, asset)`
pair:

- If `cs_weights > 0`, all features in `X` and `y` must be finite.
- If `cs_weights == 0`, the pair is excluded from estimation and `X` and `y` may be
  finite or missing.
- Each observation must retain at least one valid asset after applying `cs_weights`.

* **Parameters:**
  **regressor** *BaseEstimator*
  : Scikit-learn regressor used at each observation.

  **n_jobs** *int, default=1*
  : Number of parallel jobs used to fit the observation-level regressions.
* **Attributes:**
  **coef_** *ndarray of shape (n_observations, n_features)*
  : Estimated coefficients for each observation.

  **intercept_** *ndarray of shape (n_observations,)*
  : Intercept for each observation. Set to zeros if `fit_intercept=False`.

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

  **n_valid_assets_** *ndarray of shape (n_observations,)*
  : Number of assets that participated in estimation (those with positive weight)
    for each observation.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper.fit)(X, y[, cs_weights])             | Fit one wrapped regressor per observation.                                         |
|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper.get_metadata_routing)()              | Get metadata routing of this object.                                               |
| [`get_params`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper.get_params)([deep])                  | Get parameters for this estimator.                                                 |
| [`predict`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper.predict)(X)                          | Predict using the cross-sectional linear model.                                    |
| [`score`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper.score)(X, y[, cs_weights])           | Return the mean coefficient of determination across observations.                  |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper.set_fit_request)(\*[, cs_weights])   | Configure whether metadata should be requested to be passed to the `fit` method.   |
| [`set_params`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper.set_params)(\*\*params)              | Set the parameters of this estimator.                                              |
| [`set_score_request`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper.set_score_request)(\*[, cs_weights]) | Configure whether metadata should be requested to be passed to the `score` method. |

#### SEE ALSO
[`CSLinearRegression`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression)

### Examples

```pycon
>>> import numpy as np
>>> from sklearn.linear_model import HuberRegressor
>>> from skfolio.linear_model import CSLinearRegressorWrapper
>>>
>>> rng = np.random.default_rng(42)
>>> X = rng.normal(size=(3, 5, 2))
>>> y = rng.normal(size=(3, 5))
>>> cs_weights = 1.0 + rng.random(size=(3, 5))
>>>
>>> model = CSLinearRegressorWrapper(
...     regressor=HuberRegressor(fit_intercept=True, max_iter=200)
... )
>>> model.fit(X, y, cs_weights=cs_weights)
CSLinearRegressorWrapper(...)
>>>
>>> model.intercept_.shape
(3,)
>>> model.coef_.shape
(3, 2)
>>> model.predict(X).shape
(3, 5)
>>> model.score(X, y)
0.4901...
```

<a id="skfolio.linear_model.CSLinearRegressorWrapper.fit"></a>

#### fit(X, y, cs_weights=None)

Fit one wrapped regressor per observation.

Each observation must contain at least one asset with positive weight
and finite `X` and `y` values.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets, n_features)*
  : Input feature tensor.

  **y** *array-like of shape (n_observations, n_assets)*
  : Target values.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Cross-sectional weights passed to the wrapped regressor as `sample_weight`.
    If None, all assets receive unit weight.
* **Returns:**
  **self** *CSLinearRegressorWrapper*
  : Fitted estimator.

<a id="skfolio.linear_model.CSLinearRegressorWrapper.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.linear_model.CSLinearRegressorWrapper.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.linear_model.CSLinearRegressorWrapper.predict"></a>

#### predict(X)

Predict using the cross-sectional linear model.

For each observation $t$ and asset $i$, the prediction is
the systematic part; realized outcomes satisfy
$y_{ti} = \hat{y}_{ti} + \epsilon_{ti}$ with residual
$\epsilon_{ti}$. The prediction is

$$
\hat{y}_{ti} = X_{ti}^{T} \beta_t + \beta_{t,0}
$$

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets, n_features)*
  : Feature tensor used for prediction.
    The observation and feature axes must match those seen during
    `fit`. The asset axis may differ.
* **Returns:**
  **y_pred** *ndarray of shape (n_observations, n_assets)*
  : Predicted values.

<a id="skfolio.linear_model.CSLinearRegressorWrapper.score"></a>

#### score(X, y, cs_weights=None)

Return the mean coefficient of determination across observations.

The coefficient of determination $R^2$ is computed independently
for each observation and then averaged. For observation $t$:

$$
R^2_t = 1 - \frac{\sum_i w_{ti}(y_{ti} - \hat{y}_{ti})^2}
                 {\sum_i w_{ti}(y_{ti} - \bar{y}_t)^2}
$$

where $\bar{y}_t$ is the weighted mean of $y$ for
observation $t$.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets, n_features)*
  : Feature tensor on which to evaluate the model.

  **y** *array-like of shape (n_observations, n_assets)*
  : Target values aligned with `X`.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Asset weights for computing weighted $R^2$ scores.
    If None, all assets are given equal weight. Pairs with zero weight
    are excluded from the score. Pairs with positive weight must have
    finite `X` and finite `y`.
* **Returns:**
  **score** *float*
  : Mean $R^2$ across all observations with finite values.
    Returns NaN if no observations have valid $R^2$ values.

<a id="skfolio.linear_model.CSLinearRegressorWrapper.set_fit_request"></a>

#### set_fit_request(\*, cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.linear_model.CSLinearRegressorWrapper.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.

<a id="skfolio.linear_model.CSLinearRegressorWrapper.set_score_request"></a>

#### set_score_request(\*, cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.measures.BaseMeasure.html.md

<a id="skfolio-measures-basemeasure"></a>

# skfolio.measures.BaseMeasure

<a id="skfolio.measures.BaseMeasure"></a>

### *class* skfolio.measures.BaseMeasure(new_class_name, /, names, \*, module=None, qualname=None, type=None, start=1, boundary=None)

Base Enum of measures.

<a id="skfolio.measures.BaseMeasure.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.measures.ExtraRiskMeasure.html.md

<a id="skfolio-measures-extrariskmeasure"></a>

# skfolio.measures.ExtraRiskMeasure

<a id="skfolio.measures.ExtraRiskMeasure"></a>

### *class* skfolio.measures.ExtraRiskMeasure(\*values)

Enumeration of other risk measures not used in convex optimization.

* **Attributes:**
  **VALUE_AT_RISK** *str*
  : Value at Risk (VaR).

  **DRAWDOWN_AT_RISK** *str*
  : Drawdown at Risk.

  **ENTROPIC_RISK_MEASURE** *str*
  : Entropic Risk Measure.

  **FOURTH_CENTRAL_MOMENT** *str*
  : Fourth Central Moment.

  **FOURTH_LOWER_PARTIAL_MOMENT** *str*
  : Fourth Lower Central Moment.

  **SKEW** *str*
  : Skew.

  **KURTOSIS** *str*
  : Kurtosis.

<a id="skfolio.measures.ExtraRiskMeasure.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.measures.PerfMeasure.html.md

<a id="skfolio-measures-perfmeasure"></a>

# skfolio.measures.PerfMeasure

<a id="skfolio.measures.PerfMeasure"></a>

### *class* skfolio.measures.PerfMeasure(\*values)

Enumeration of performance measures.

* **Attributes:**
  **MEAN** *str*
  : Mean

  **ANNUALIZED_MEAN** *str*
  : Annualized Mean

<a id="skfolio.measures.PerfMeasure.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.measures.RatioMeasure.html.md

<a id="skfolio-measures-ratiomeasure"></a>

# skfolio.measures.RatioMeasure

<a id="skfolio.measures.RatioMeasure"></a>

### *class* skfolio.measures.RatioMeasure(\*values)

Enumeration of ratio measures.

* **Attributes:**
  **SHARPE_RATIO** *str*
  : Ratio of the excess Mean divided by the Standard-deviation.

  **ANNUALIZED_SHARPE_RATIO** *str*
  : Annualized Sharpe ratio.

  **SORTINO_RATIO** *str*
  : Ratio of the excess Mean divided by the Semi standard-deviation.

  **ANNUALIZED_SORTINO_RATIO** *str*
  : Annualized Sortino ratio.

  **MEAN_ABSOLUTE_DEVIATION_RATIO** *str*
  : Ratio of the excess Mean divided by the Mean Absolute Deviation.

  **FIRST_LOWER_PARTIAL_MOMENT_RATIO** *str*
  : Ratio of the excess Mean divided by the First Lower Partial Moment.

  **VALUE_AT_RISK_RATIO** *str*
  : Ratio of the excess Mean divided by the Value at Risk.

  **CVAR_RATIO** *str*
  : Ratio of the excess Mean divided by the Conditional Value at Risk.

  **ENTROPIC_RISK_MEASURE_RATIO** *str*
  : Ratio of the excess Mean divided by the Entropic Risk Measure.

  **EVAR_RATIO** *str*
  : Ratio of the excess Mean divided by the Entropic Value at Risk.

  **WORST_REALIZATION_RATIO** *str*
  : Ratio of the excess Mean divided by the Worst Realization.

  **DRAWDOWN_AT_RISK_RATIO** *str*
  : Ratio of the excess Mean divided by the Drawdown at Risk.

  **CDAR_RATIO** *str*
  : Ratio of the excess Mean divided by the Conditional Drawdown at Risk.

  **CALMAR_RATIO** *str*
  : Ratio of the excess Mean divided by the Maximum Drawdown.

  **AVERAGE_DRAWDOWN_RATIO** *str*
  : Ratio of the excess Mean divided by the Average Drawdown.

  **EDAR_RATIO** *str*
  : Ratio of the excess Mean divided by the Entropic Drawdown at Risk.

  **ULCER_INDEX_RATIO** *str*
  : Ratio of the excess Mean divided by the Ulcer Index.

  **GINI_MEAN_DIFFERENCE_RATIO** *str*
  : Ratio of the excess Mean divided by the Gini Mean Difference.

<a id="skfolio.measures.RatioMeasure.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.measures.RiskMeasure.html.md

<a id="skfolio-measures-riskmeasure"></a>

# skfolio.measures.RiskMeasure

<a id="skfolio.measures.RiskMeasure"></a>

### *class* skfolio.measures.RiskMeasure(\*values)

Enumeration of risk measures.

* **Attributes:**
  **VARIANCE** *str*
  : Variance.

  **ANNUALIZED_VARIANCE** *str*
  : Annualized Variance.

  **SEMI_VARIANCE** *str*
  : Semi-variance (Second Lower Partial Moment or Downside Variance).

  **ANNUALIZED_SEMI_VARIANCE** *str*
  : Annualized Semi-variance.

  **STANDARD_DEVIATION** *str*
  : Standard-deviation

  **ANNUALIZED_STANDARD_DEVIATION** *str*
  : Annualized Standard-deviation.

  **SEMI_DEVIATION** *str*
  : Semi-deviation.

  **ANNUALIZED_SEMI_DEVIATION** *str*
  : Annualized Semi-deviation.

  **MEAN_ABSOLUTE_DEVIATION** *str*
  : Mean Absolute Deviation.

  **CVAR** *str*
  : Conditional Value at Risk or Expected Shortfall.

  **EVAR** *str*
  : Entropic Value at Risk.

  **WORST_REALIZATION** *str*
  : Worst Realization (Worst Return).

  **CDAR** *str*
  : Conditional Drawdown at Risk.

  **MAX_DRAWDOWN** *str*
  : Maximum Drawdown.

  **AVERAGE_DRAWDOWN** *str*
  : Average Drawdown.

  **EDAR** *str*
  : Entropic Drawdown at Risk.

  **FIRST_LOWER_PARTIAL_MOMENT** *str*
  : First Lower Partial Moment.

  **ULCER_INDEX** *str*
  : Ulcer Index.

  **GINI_MEAN_DIFFERENCE** *str*
  : Gini Mean Difference.

<a id="skfolio.measures.RiskMeasure.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.measures.average_drawdown.html.md

<a id="skfolio-measures-average-drawdown"></a>

# skfolio.measures.average_drawdown

<a id="skfolio.measures.average_drawdown"></a>

### skfolio.measures.average_drawdown(drawdowns)

Compute the average drawdown.

* **Parameters:**
  **drawdowns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Vector of drawdowns.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Average drawdown.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

# generated/skfolio.measures.cdar.html.md

<a id="skfolio-measures-cdar"></a>

# skfolio.measures.cdar

<a id="skfolio.measures.cdar"></a>

### skfolio.measures.cdar(drawdowns, beta=0.95)

Compute the historical CDaR (conditional drawdown at risk).

* **Parameters:**
  **drawdowns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Vector of drawdowns.

  **beta** *float, default = 0.95*
  : The CDaR confidence level (expected drawdown on the worst
    (1-beta)% observations).
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : CDaR.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

# generated/skfolio.measures.correlation.html.md

<a id="skfolio-measures-correlation"></a>

# skfolio.measures.correlation

<a id="skfolio.measures.correlation"></a>

### skfolio.measures.correlation(X, sample_weight=None)

Compute the correlation matrix.

* **Parameters:**
  **X** *ndarray of shape (n_observations, n_assets)*
  : Array of values.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **corr** *ndarray of shape (n_assets,)*
  : The correlation matrix.

# generated/skfolio.measures.cvar.html.md

<a id="skfolio-measures-cvar"></a>

# skfolio.measures.cvar

<a id="skfolio.measures.cvar"></a>

### skfolio.measures.cvar(returns, beta=0.95, sample_weight=None)

Compute the historical CVaR (conditional value at risk).

The CVaR (or Tail VaR) represents the mean shortfall at a specified confidence
level (beta).

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **beta** *float, default=0.95*
  : The CVaR confidence level (expected VaR on the worst (1-beta)% observations).

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : CVaR.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.drawdown_at_risk.html.md

<a id="skfolio-measures-drawdown-at-risk"></a>

# skfolio.measures.drawdown_at_risk

<a id="skfolio.measures.drawdown_at_risk"></a>

### skfolio.measures.drawdown_at_risk(drawdowns, beta=0.95)

Compute the Drawdown at risk.

The Drawdown at risk is the maximum drawdown at a given confidence level (beta).

* **Parameters:**
  **drawdowns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Vector of drawdowns.

  **beta** *float, default = 0.95*
  : The DaR confidence level (drawdown on the worst (1-beta)% observations).
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Drawdown at risk.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

# generated/skfolio.measures.edar.html.md

<a id="skfolio-measures-edar"></a>

# skfolio.measures.edar

<a id="skfolio.measures.edar"></a>

### skfolio.measures.edar(drawdowns, beta=0.95)

Compute the EDaR (entropic drawdown at risk).

The EDaR is a coherent risk measure which is an upper bound for the DaR and the
CDaR, obtained from the Chernoff inequality. The EDaR can be represented by using
the concept of relative entropy.

* **Parameters:**
  **drawdowns** *ndarray of shape (n_observations,)*
  : Vector of drawdowns.

  **beta** *float, default=0.95*
  : The EDaR confidence level.
* **Returns:**
  **value** *float*
  : EDaR.

# generated/skfolio.measures.effective_number_assets.html.md

<a id="skfolio-measures-effective-number-assets"></a>

# skfolio.measures.effective_number_assets

<a id="skfolio.measures.effective_number_assets"></a>

### skfolio.measures.effective_number_assets(weights)

Compute the effective number of assets, defined as the inverse of the
Herfindahl index.

$$
N_{eff} = \frac{1}{\Vert w \Vert_{2}^{2}}

$$

It quantifies portfolio concentration, with a higher value indicating a more
diversified portfolio.

* **Parameters:**
  **weights** *ndarray of shape (n_assets,)*
  : Weights of the assets.
* **Returns:**
  **value** *float*
  : Effective number of assets.

### References

* <a id='r3692bcdb1be2-1'>**[1]**</a> “Banking and Financial Institutions Law in a Nutshell”. Lovett, William Anthony (1988)

# generated/skfolio.measures.entropic_risk_measure.html.md

<a id="skfolio-measures-entropic-risk-measure"></a>

# skfolio.measures.entropic_risk_measure

<a id="skfolio.measures.entropic_risk_measure"></a>

### skfolio.measures.entropic_risk_measure(returns, theta=1, beta=0.95, sample_weight=None)

Compute the entropic risk measure.

The entropic risk measure is a risk measure which depends on the risk aversion
defined by the investor (theta) through the exponential utility function at a given
confidence level (beta).

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **theta** *float, default=1.0*
  : Risk aversion.

  **beta** *float, default=0.95*
  : Confidence level.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Entropic risk measure.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.evar.html.md

<a id="skfolio-measures-evar"></a>

# skfolio.measures.evar

<a id="skfolio.measures.evar"></a>

### skfolio.measures.evar(returns, beta=0.95)

Compute the EVaR (entropic value at risk) and its associated risk aversion.

The EVaR is a coherent risk measure which is an upper bound for the VaR and the
CVaR, obtained from the Chernoff inequality. The EVaR can be represented by using
the concept of relative entropy.

* **Parameters:**
  **returns** *ndarray of shape (n_observations,)*
  : Vector of returns.

  **beta** *float, default=0.95*
  : The EVaR confidence level.
* **Returns:**
  **value** *float*
  : EVaR.

# generated/skfolio.measures.first_lower_partial_moment.html.md

<a id="skfolio-measures-first-lower-partial-moment"></a>

# skfolio.measures.first_lower_partial_moment

<a id="skfolio.measures.first_lower_partial_moment"></a>

### skfolio.measures.first_lower_partial_moment(returns, min_acceptable_return=None, sample_weight=None)

Compute the first lower partial moment.

The first lower partial moment is the mean of the returns below a minimum
acceptable return.

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **min_acceptable_return** *float or ndarray of shape (n_assets,) optional*
  : Minimum acceptable return. It is the return target to distinguish “downside” and
    “upside” returns. The default (`None`) is to use the returns’ mean.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : First lower partial moment.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.fourth_central_moment.html.md

<a id="skfolio-measures-fourth-central-moment"></a>

# skfolio.measures.fourth_central_moment

<a id="skfolio.measures.fourth_central_moment"></a>

### skfolio.measures.fourth_central_moment(returns, sample_weight=None)

Compute the Fourth central moment.

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Fourth central moment.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.fourth_lower_partial_moment.html.md

<a id="skfolio-measures-fourth-lower-partial-moment"></a>

# skfolio.measures.fourth_lower_partial_moment

<a id="skfolio.measures.fourth_lower_partial_moment"></a>

### skfolio.measures.fourth_lower_partial_moment(returns, min_acceptable_return=None)

Compute the fourth lower partial moment.

The Fourth Lower Partial Moment is a measure of the heaviness of the downside tail
of the returns below a minimum acceptable return.
Higher Fourth Lower Partial Moment corresponds to greater extremity of downside
deviations (downside fat tail).

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **min_acceptable_return** *float, optional*
  : Minimum acceptable return. It is the return target to distinguish “downside” and
    “upside” returns.
    The default (`None`) is to use the returns mean.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Fourth lower partial moment.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.get_cumulative_returns.html.md

<a id="skfolio-measures-get-cumulative-returns"></a>

# skfolio.measures.get_cumulative_returns

<a id="skfolio.measures.get_cumulative_returns"></a>

### skfolio.measures.get_cumulative_returns(returns, compounded=False, base=1.0)

Compute the cumulative returns from a series of returns.

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **compounded** *bool, default=False*
  : If True, compute compounded (geometric) cumulative returns as a wealth index
    starting at `base`. If False, compute non-compounded (arithmetic) cumulative
    returns starting at 0. Default is False.

  **base** *float, default=1.0*
  : Starting value for compounded cumulative returns, expressed as a wealth index.
    For example, use 1.0 for a “wealth index” representing $1 invested, or 100.0
    for index-style rebasing.
* **Returns:**
  values: ndarray of shape (n_observations,) or (n_observations, n_assets)
  : Cumulative returns.

### Notes

NaN handling:
Missing values (NaNs) remain at their original locations in the output and are
treated as neutral elements during accumulation, so they do not propagate to
subsequent values.

# generated/skfolio.measures.get_drawdowns.html.md

<a id="skfolio-measures-get-drawdowns"></a>

# skfolio.measures.get_drawdowns

<a id="skfolio.measures.get_drawdowns"></a>

### skfolio.measures.get_drawdowns(returns, compounded=False)

Compute the drawdowns’ series from the returns.

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **compounded** *bool, default=False*
  : If this is set to True, the cumulative returns are compounded otherwise they
    are uncompounded.
* **Returns:**
  values: ndarray of shape (n_observations,) or (n_observations, n_assets)
  : Drawdowns.

### Notes

NaN handling:
Missing values (NaNs) remain at their original locations in the output and are
treated as neutral elements during accumulation, so they do not propagate to
subsequent values.

# generated/skfolio.measures.gini_mean_difference.html.md

<a id="skfolio-measures-gini-mean-difference"></a>

# skfolio.measures.gini_mean_difference

<a id="skfolio.measures.gini_mean_difference"></a>

### skfolio.measures.gini_mean_difference(returns)

Compute the Gini mean difference (GMD).

The GMD is the expected absolute difference between two realisations.
The GMD is a superior measure of variability  for non-normal distribution than the
variance.
It can be used to form necessary conditions for second-degree stochastic dominance,
while the variance cannot.

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Gini mean difference.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

# generated/skfolio.measures.kurtosis.html.md

<a id="skfolio-measures-kurtosis"></a>

# skfolio.measures.kurtosis

<a id="skfolio.measures.kurtosis"></a>

### skfolio.measures.kurtosis(returns, sample_weight=None)

Compute the Kurtosis.

The Kurtosis is a measure of the heaviness of the tail of the distribution.
Higher Kurtosis corresponds to greater extremity of deviations (fat tails).

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Kurtosis.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.max_drawdown.html.md

<a id="skfolio-measures-max-drawdown"></a>

# skfolio.measures.max_drawdown

<a id="skfolio.measures.max_drawdown"></a>

### skfolio.measures.max_drawdown(drawdowns)

Compute the maximum drawdown.

* **Parameters:**
  **drawdowns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Vector of drawdowns.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Maximum drawdown.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

# generated/skfolio.measures.mean.html.md

<a id="skfolio-measures-mean"></a>

# skfolio.measures.mean

<a id="skfolio.measures.mean"></a>

### skfolio.measures.mean(returns, sample_weight=None)

Compute the mean.

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : The computed mean.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.mean_absolute_deviation.html.md

<a id="skfolio-measures-mean-absolute-deviation"></a>

# skfolio.measures.mean_absolute_deviation

<a id="skfolio.measures.mean_absolute_deviation"></a>

### skfolio.measures.mean_absolute_deviation(returns, min_acceptable_return=None, sample_weight=None)

Compute the mean absolute deviation (MAD).

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **min_acceptable_return** *float or ndarray of shape (n_assets,) optional*
  : Minimum acceptable return. It is the return target to distinguish “downside” and
    “upside” returns. The default (`None`) is to use the returns’ mean.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Mean absolute deviation.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.owa_gmd_weights.html.md

<a id="skfolio-measures-owa-gmd-weights"></a>

# skfolio.measures.owa_gmd_weights

<a id="skfolio.measures.owa_gmd_weights"></a>

### skfolio.measures.owa_gmd_weights(n_observations)

Compute the OWA weights used for the Gini mean difference (GMD) computation.

* **Parameters:**
  **n_observations** *int*
  : Number of observations.
* **Returns:**
  **value** *float*
  : OWA GMD weights.

# generated/skfolio.measures.semi_deviation.html.md

<a id="skfolio-measures-semi-deviation"></a>

# skfolio.measures.semi_deviation

<a id="skfolio.measures.semi_deviation"></a>

### skfolio.measures.semi_deviation(returns, min_acceptable_return=None, sample_weight=None, biased=False)

Compute the semi-deviation (square root of the second lower partial moment).

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **min_acceptable_return** *float or ndarray of shape (n_assets,) optional*
  : Minimum acceptable return. It is the return target to distinguish “downside” and
    “upside” returns. The default (`None`) is to use the returns’ mean.

  **biased** *bool, default=False*
  : If False (default), computes the sample semi-deviation (unbiased); otherwise,
    computes the population semi-seviation (biased).

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Semi-deviation.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.semi_variance.html.md

<a id="skfolio-measures-semi-variance"></a>

# skfolio.measures.semi_variance

<a id="skfolio.measures.semi_variance"></a>

### skfolio.measures.semi_variance(returns, min_acceptable_return=None, sample_weight=None, biased=False)

Compute the semi-variance (second lower partial moment).

The semi-variance is the variance of the returns below a minimum acceptable return.

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **min_acceptable_return** *float or ndarray of shape (n_assets,) optional*
  : Minimum acceptable return. It is the return target to distinguish “downside” and
    “upside” returns. The default (`None`) is to use the returns’ mean.

  **biased** *bool, default=False*
  : If False (default), computes the sample semi-variance (unbiased); otherwise,
    computes the population semi-variance (biased).

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Semi-variance.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.skew.html.md

<a id="skfolio-measures-skew"></a>

# skfolio.measures.skew

<a id="skfolio.measures.skew"></a>

### skfolio.measures.skew(returns, sample_weight=None)

Compute the Skew.

The Skew is a measure of the lopsidedness of the distribution.
A symmetric distribution have a Skew of zero.
Higher Skew corresponds to longer right tail.

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Skew.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.standard_deviation.html.md

<a id="skfolio-measures-standard-deviation"></a>

# skfolio.measures.standard_deviation

<a id="skfolio.measures.standard_deviation"></a>

### skfolio.measures.standard_deviation(returns, sample_weight=None, biased=False)

Compute the standard-deviation (square root of the second moment).

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **biased** *bool, default=False*
  : If False (default), computes the sample standard-deviation (unbiased);
    otherwise, computes the population standard-deviation (biased).

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Standard-deviation.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.third_central_moment.html.md

<a id="skfolio-measures-third-central-moment"></a>

# skfolio.measures.third_central_moment

<a id="skfolio.measures.third_central_moment"></a>

### skfolio.measures.third_central_moment(returns, sample_weight=None)

Compute the third central moment.

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Third central moment.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.ulcer_index.html.md

<a id="skfolio-measures-ulcer-index"></a>

# skfolio.measures.ulcer_index

<a id="skfolio.measures.ulcer_index"></a>

### skfolio.measures.ulcer_index(drawdowns)

Compute the Ulcer index.

* **Parameters:**
  **drawdowns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Vector of drawdowns.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Ulcer Index.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

# generated/skfolio.measures.value_at_risk.html.md

<a id="skfolio-measures-value-at-risk"></a>

# skfolio.measures.value_at_risk

<a id="skfolio.measures.value_at_risk"></a>

### skfolio.measures.value_at_risk(returns, beta=0.95, sample_weight=None)

Compute the historical value at risk (VaR).
The VaR is the maximum loss at a given confidence level (beta).

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **beta** *float, default=0.95*
  : The VaR confidence level (return on the worst (1-beta)% observation).

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Value at Risk.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.variance.html.md

<a id="skfolio-measures-variance"></a>

# skfolio.measures.variance

<a id="skfolio.measures.variance"></a>

### skfolio.measures.variance(returns, biased=False, sample_weight=None)

Compute the variance (second moment).

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.

  **biased** *bool, default=False*
  : If False (default), computes the sample variance (unbiased); otherwise,
    computes the population variance (biased).

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Variance.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.measures.worst_realization.html.md

<a id="skfolio-measures-worst-realization"></a>

# skfolio.measures.worst_realization

<a id="skfolio.measures.worst_realization"></a>

### skfolio.measures.worst_realization(returns)

Compute the worst realization (worst return).

* **Parameters:**
  **returns** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Array of return values.
* **Returns:**
  **value** *float or ndarray of shape (n_assets,)*
  : Worst realization.
    If `returns` is a 1D-array, the result is a float.
    If `returns` is a 2D-array, the result is a ndarray of shape (n_assets,).

### Notes

NaN handling:
- Unweighted: NaNs are ignored; all-NaN inputs yield NaN.
- Weighted: NaNs propagate.

# generated/skfolio.metrics.diagonal_calibration_loss.html.md

<a id="skfolio-metrics-diagonal-calibration-loss"></a>

# skfolio.metrics.diagonal_calibration_loss

<a id="skfolio.metrics.diagonal_calibration_loss"></a>

### skfolio.metrics.diagonal_calibration_loss(estimator, X_test, y=None)

Diagonal calibration loss.

Computes the absolute deviation of [`diagonal_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.diagonal_calibration_ratio.html.md#skfolio.metrics.diagonal_calibration_ratio) from its
calibration target of `1.0`.

Let $r_t$ be the one-period realized return vector at time $t$,
and let $R^{(h)} = \sum_{t=1}^{h} r_t$ be the aggregated return over
an evaluation window of $h$ observations.

$$
\ell = \left\lvert
    \frac{1}{n}\sum_{i=1}^{n}
    \frac{(R_i^{(h)})^2}{h\,\sigma_i^2} - 1
\right\rvert
$$

where $n$ is the number of assets.

* **Parameters:**
  **estimator** *BaseEstimator*
  : Fitted estimator, must expose `covariance_` or `return_distribution_.covariance`.

  **X_test** *array-like of shape (n_observations, n_assets)*
  : Realized returns for the test window.

  **y** *Ignored*
  : Present for scikit-learn API compatibility.
* **Returns:**
  float
  : Calibration loss. Lower values are better and the optimum is `0.0`.

#### SEE ALSO
[`diagonal_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.diagonal_calibration_ratio.html.md#skfolio.metrics.diagonal_calibration_ratio)
: The underlying calibration ratio.

[`mahalanobis_calibration_loss`](https://skfolio.org/generated/skfolio.metrics.mahalanobis_calibration_loss.html.md#skfolio.metrics.mahalanobis_calibration_loss)
: Loss using the full covariance structure.

# generated/skfolio.metrics.diagonal_calibration_ratio.html.md

<a id="skfolio-metrics-diagonal-calibration-ratio"></a>

# skfolio.metrics.diagonal_calibration_ratio

<a id="skfolio.metrics.diagonal_calibration_ratio"></a>

### skfolio.metrics.diagonal_calibration_ratio(estimator, X_test, y=None)

Diagonal calibration ratio based on marginal variances.

Let $r_t$ be the one-period realized return vector at time $t$,
and let $R^{(h)} = \sum_{t=1}^{h} r_t$ be the aggregated return over
an evaluation window of $h$ observations. This metric uses only the
diagonal of the covariance matrix, ignoring correlations, and compares
each component $R_i^{(h)}$ against the horizon-scaled variance
$h\,\sigma_i^2$:

$$
s = \frac{1}{n}\sum_{i=1}^{n}
    \frac{(R_i^{(h)})^2}{h\,\sigma_i^2}
$$

where $n$ is the number of assets and $\sigma_i^2$ is the
forecast variance for asset $i$.

If the marginal variance forecasts are correct and the aggregated returns are
centered, then $\mathbb{E}[s] = 1$ for any horizon $h$.
Because correlations are ignored, this metric diagnoses the calibration
of marginal scales rather than the full covariance structure.

When `X_test` contains NaNs (e.g. holidays, pre-listing, or post-delisting
periods), each asset uses its own effective horizon $h_i$, equal to
the number of finite observations for that asset, so the ratio retains the
same target under missing data. In skfolio, NaN diagonal entries in the
forecast covariance mark inactive assets, which are excluded from the
evaluation.

* **Parameters:**
  **estimator** *BaseEstimator*
  : Fitted estimator, must expose `covariance_` or `return_distribution_.covariance`.

  **X_test** *array-like of shape (n_observations, n_assets)*
  : Realized returns for the test window.

  **y** *Ignored*
  : Present for scikit-learn API compatibility.
* **Returns:**
  float
  : Calibration ratio. Values near `1.0` indicate well-calibrated
    marginal variance forecasts.

#### SEE ALSO
[`diagonal_calibration_loss`](https://skfolio.org/generated/skfolio.metrics.diagonal_calibration_loss.html.md#skfolio.metrics.diagonal_calibration_loss)
: Absolute deviation from the calibration target of `1.0`.

[`mahalanobis_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.mahalanobis_calibration_ratio.html.md#skfolio.metrics.mahalanobis_calibration_ratio)
: Calibration ratio using the full covariance structure.

# generated/skfolio.metrics.exceedance_rate.html.md

<a id="skfolio-metrics-exceedance-rate"></a>

# skfolio.metrics.exceedance_rate

<a id="skfolio.metrics.exceedance_rate"></a>

### skfolio.metrics.exceedance_rate(squared_distances, n_features, confidence_level)

Exceedance rate for chi-squared calibration statistics.

Computes the fraction of squared distances exceeding the upper `confidence_level`
chi-squared quantile.

The reference threshold assumes Gaussian standardized returns. In practice,
the rate is sensitive not only to covariance misspecification but also to
heavy tails, regime shifts, and non-Gaussian standardized returns. It is
best used as a comparative metric across estimators rather than as
an absolute calibration test.

* **Parameters:**
  **squared_distances** *array-like of shape (n_observations,)*
  : Squared Mahalanobis distances or similar chi-squared statistics.

  **n_features** *int*
  : Degrees of freedom (number of features/assets).

  **confidence_level** *float*
  : Coverage confidence level used to define the upper chi-squared
    threshold. For example, `0.95` corresponds to an expected
    exceedance rate of `0.05` under calibration.
* **Returns:**
  float
  : Observed exceedance rate. It should be close to
    $1 - \text{confidence\_level}$ when the reference
    chi-squared approximation is appropriate.

#### SEE ALSO
[`mahalanobis_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.mahalanobis_calibration_ratio.html.md#skfolio.metrics.mahalanobis_calibration_ratio)
: Calibration ratio based on squared Mahalanobis distances.

### Notes

Under correct calibration and Gaussian standardized returns,
$d^2 \sim \chi^2(n_{\text{features}})$, so
$P(d^2 > \chi^2_{\text{confidence\_level}}) =
1 - \text{confidence\_level}$.

# generated/skfolio.metrics.mahalanobis_calibration_loss.html.md

<a id="skfolio-metrics-mahalanobis-calibration-loss"></a>

# skfolio.metrics.mahalanobis_calibration_loss

<a id="skfolio.metrics.mahalanobis_calibration_loss"></a>

### skfolio.metrics.mahalanobis_calibration_loss(estimator, X_test, y=None)

Mahalanobis calibration loss.

Computes the absolute deviation of [`mahalanobis_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.mahalanobis_calibration_ratio.html.md#skfolio.metrics.mahalanobis_calibration_ratio) from its
calibration target of `1.0`.

Let $r_t$ be the one-period realized return vector at time $t$,
and let $R^{(h)} = \sum_{t=1}^{h} r_t$ be the aggregated return over
an evaluation window of $h$ observations.

$$
\ell = \left\lvert
    \frac{{R^{(h)}}^\top (h\,\Sigma)^{-1} R^{(h)}}{n} - 1
\right\rvert
$$

where $n$ is the number of assets.

As with [`mahalanobis_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.mahalanobis_calibration_ratio.html.md#skfolio.metrics.mahalanobis_calibration_ratio), heavy tails and regime
changes can weaken the Gaussian reference. This loss is therefore often
most useful for relative comparison across covariance estimators.

* **Parameters:**
  **estimator** *BaseEstimator*
  : Fitted estimator, must expose `covariance_` or `return_distribution_.covariance`.

  **X_test** *array-like of shape (n_observations, n_assets)*
  : Realized returns for the test window.

  **y** *Ignored*
  : Present for scikit-learn API compatibility.
* **Returns:**
  float
  : Calibration loss. Lower values are better and the optimum is `0.0`.

#### SEE ALSO
[`mahalanobis_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.mahalanobis_calibration_ratio.html.md#skfolio.metrics.mahalanobis_calibration_ratio)
: The underlying calibration ratio.

[`diagonal_calibration_loss`](https://skfolio.org/generated/skfolio.metrics.diagonal_calibration_loss.html.md#skfolio.metrics.diagonal_calibration_loss)
: Loss using only marginal variances.

# generated/skfolio.metrics.mahalanobis_calibration_ratio.html.md

<a id="skfolio-metrics-mahalanobis-calibration-ratio"></a>

# skfolio.metrics.mahalanobis_calibration_ratio

<a id="skfolio.metrics.mahalanobis_calibration_ratio"></a>

### skfolio.metrics.mahalanobis_calibration_ratio(estimator, X_test, y=None)

Mahalanobis calibration ratio.

Let $r_t$ be the one-period realized return vector at time $t$,
and let $R^{(h)} = \sum_{t=1}^{h} r_t$ be the aggregated return over
an evaluation window of $h$ observations. This metric compares
$R^{(h)}$ against the horizon-scaled covariance $h\,\Sigma$:

$$
s = \frac{{R^{(h)}}^\top (h\,\Sigma)^{-1} R^{(h)}}{n}
$$

where $n$ is the number of assets.

If the forecast covariance is correct and the aggregated return is centered,
then $\mathbb{E}[s] = 1$ for any horizon $h$. Under
multivariate normality, $n s \sim \chi^2(n)$.

For financial return series, heavy tails and regime changes can cause
departures from the Gaussian reference. In practice, this ratio is often
most useful as a relative diagnostic across estimators.

When `X_test` contains NaNs (e.g. holidays, pre-listing, or post-delisting
periods), only finite observations are used in the aggregated return and
the covariance is scaled by the pairwise observation count matrix
$H$ (Hadamard product $H \odot \Sigma$) so that the same
target applies with missing data. In skfolio, NaN diagonal entries in the
forecast covariance mark inactive assets, which are excluded from the
evaluation.

* **Parameters:**
  **estimator** *BaseEstimator*
  : Fitted estimator, must expose `covariance_` or `return_distribution_.covariance`.

  **X_test** *array-like of shape (n_observations, n_assets)*
  : Realized returns for the test window.

  **y** *Ignored*
  : Present for scikit-learn API compatibility.
* **Returns:**
  float
  : Calibration ratio. Values near `1.0` indicate that the forecast
    covariance matches the scale of the realized aggregated return.

#### SEE ALSO
[`mahalanobis_calibration_loss`](https://skfolio.org/generated/skfolio.metrics.mahalanobis_calibration_loss.html.md#skfolio.metrics.mahalanobis_calibration_loss)
: Absolute deviation from the calibration target of `1.0`.

[`diagonal_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.diagonal_calibration_ratio.html.md#skfolio.metrics.diagonal_calibration_ratio)
: Calibration ratio using only marginal variances.

# generated/skfolio.metrics.make_scorer.html.md

<a id="skfolio-metrics-make-scorer"></a>

# skfolio.metrics.make_scorer

<a id="skfolio.metrics.make_scorer"></a>

### skfolio.metrics.make_scorer(score_func, greater_is_better=None, response_method='predict', \*\*kwargs)

Make a scorer from a [measure](https://skfolio.org/api.html.md#measures-ref), a portfolio score
function, or a non-predictor estimator score function.

This function wraps scoring functions for use in model selection:

* `response_method="predict"` (default): for portfolio optimization
  estimators (e.g.
  [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk)). Compatible with
  `GridSearchCV` and
  `cross_val_score`.
* `response_method=None`: for non-predictor estimators
  (covariance, expected returns, prior) that implement `fit` but not
  `predict`. Compatible with both sklearn cross-validation utilities
  and skfolio online utilities
  ([`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch),
  [`online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score)).

#### NOTE
For online evaluation of portfolio optimization estimators, pass a
[measure](https://skfolio.org/api.html.md#measures-ref) directly to the `scoring` parameter instead of using
`make_scorer`. Online evaluation scores the full
aggregated [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) rather than averaging
per-fold scores.

* **Parameters:**
  **score_func** *Measure | callable*
  : If `score_func` is a [measure](https://skfolio.org/api.html.md#measures-ref), we return the
    measure of the predicted [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) times
    `1` or `-1` depending on `greater_is_better`.
    `response_method` must be `"predict"` in this case.
    <br/>
    If `response_method="predict"`, `score_func` must be a score
    function (or loss function) with signature
    `score_func(pred, **kwargs)` where `pred` is the predicted
    [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio).
    <br/>
    If `response_method=None`, `score_func` must be a score function
    (or loss function) with signature
    `score_func(estimator, X_test, **kwargs)` where `estimator` is
    the fitted non-predictor estimator and `X_test` the realized
    returns.

  **greater_is_better** *bool, optional*
  : Whether `score_func` is a score function (high is good) or a loss
    function (low is good).  In the latter case the scorer sign-flips
    the outcome so that higher values always indicate a better model.
    The default (`None`) is:
    * If `score_func` is a [measure](https://skfolio.org/api.html.md#measures-ref):
      > * `True` for [`PerfMeasure`](https://skfolio.org/generated/skfolio.measures.PerfMeasure.html.md#skfolio.measures.PerfMeasure) and
      >   [`RatioMeasure`](https://skfolio.org/generated/skfolio.measures.RatioMeasure.html.md#skfolio.measures.RatioMeasure).
      > * `False` for [`RiskMeasure`](https://skfolio.org/generated/skfolio.measures.RiskMeasure.html.md#skfolio.measures.RiskMeasure) and
      >   [`ExtraRiskMeasure`](https://skfolio.org/generated/skfolio.measures.ExtraRiskMeasure.html.md#skfolio.measures.ExtraRiskMeasure).
    * Otherwise, `True`.

  **response_method** *str or None, default=”predict”*
  : Determines how the scorer obtains predictions. Only `"predict"` and
    `None` are supported:
    * `"predict"`: call `estimator.predict(X)` and pass the resulting
      [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) to `score_func`. Use for
      portfolio optimization estimators (e.g.
      [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk)).
    * `None`: pass `(estimator, X_test)` directly to `score_func`
      without calling any response method. Use for non-predictor
      estimators (covariance, expected returns, prior).

  **\*\*kwargs** *additional arguments*
  : Additional parameters to be passed to `score_func`.
* **Returns:**
  **scorer** *callable*
  : Callable object with signature `scorer(estimator, X, y=None)`
    that returns a scalar score (higher is better).

### Examples

Portfolio scorer from a measure:

```pycon
>>> from skfolio.measures import RatioMeasure
>>> scorer = make_scorer(RatioMeasure.SHARPE_RATIO)
```

Portfolio scorer from a custom function:

```pycon
>>> def custom(pred):
...     return pred.mean - 2 * pred.variance
>>> scorer = make_scorer(custom)
```

Non-predictor estimator scorer for covariance evaluation:

```pycon
>>> from skfolio.metrics import portfolio_variance_qlike_loss
>>> import numpy as np
>>> scorer = make_scorer(
...     portfolio_variance_qlike_loss,
...     greater_is_better=False,
...     response_method=None,
...     portfolio_weights=np.ones(20) / 20,
... )
```

# generated/skfolio.metrics.portfolio_variance_calibration_loss.html.md

<a id="skfolio-metrics-portfolio-variance-calibration-loss"></a>

# skfolio.metrics.portfolio_variance_calibration_loss

<a id="skfolio.metrics.portfolio_variance_calibration_loss"></a>

### skfolio.metrics.portfolio_variance_calibration_loss(estimator, X_test, y=None, portfolio_weights=None)

Portfolio variance calibration loss.

Computes the absolute deviation of [`portfolio_variance_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_calibration_ratio.html.md#skfolio.metrics.portfolio_variance_calibration_ratio) from
its calibration target of `1.0`.

Let $r_t$ be the one-period realized return vector at time $t$
and $w^\top r_t$ the corresponding one-period portfolio return for
weights $w$.

$$
\ell = \left\lvert
    \frac{\sum_{t=1}^{h} (w^\top r_t)^2}
         {h\, w^\top \Sigma\, w} - 1
\right\rvert
$$

When multiple portfolios are provided, the loss is the absolute deviation
of the mean ratio from `1.0`.

* **Parameters:**
  **estimator** *BaseEstimator*
  : Fitted estimator, must expose `covariance_` or `return_distribution_.covariance`.

  **X_test** *array-like of shape (n_observations, n_assets)*
  : Realized returns for the test window.

  **y** *Ignored*
  : Present for scikit-learn API compatibility.

  **portfolio_weights** *array-like of shape (n_assets,) or (n_portfolios, n_assets), optional*
  : Portfolio weights. If `None` (default), inverse-volatility weights are used,
    which neutralizes volatility dispersion so that high-volatility assets do not
    dominate the diagnostic. If a 2D array is provided, each row defines a test
    portfolio. For equal-weight calibration, pass
    `portfolio_weights=np.ones(n_assets) / n_assets`.
* **Returns:**
  float
  : Calibration loss. Lower values are better and the optimum is `0.0`.

#### SEE ALSO
[`portfolio_variance_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_calibration_ratio.html.md#skfolio.metrics.portfolio_variance_calibration_ratio)
: The underlying calibration ratio.

[`portfolio_variance_qlike_loss`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_qlike_loss.html.md#skfolio.metrics.portfolio_variance_qlike_loss)
: QLIKE loss for the projected portfolio variance.

# generated/skfolio.metrics.portfolio_variance_calibration_ratio.html.md

<a id="skfolio-metrics-portfolio-variance-calibration-ratio"></a>

# skfolio.metrics.portfolio_variance_calibration_ratio

<a id="skfolio.metrics.portfolio_variance_calibration_ratio"></a>

### skfolio.metrics.portfolio_variance_calibration_ratio(estimator, X_test, y=None, portfolio_weights=None)

Portfolio variance calibration ratio.

Let $r_t$ be the one-period realized return vector at time $t$
and $w^\top r_t$ the corresponding one-period portfolio return for
weights $w$. This metric compares the sum of squared portfolio
returns over an evaluation window of $h$ observations to the
horizon-scaled forecast portfolio variance:

$$
s = \frac{\sum_{t=1}^{h} (w^\top r_t)^2}
         {h\, w^\top \Sigma\, w}
$$

If the projected portfolio variance is correctly specified and portfolio
returns are centered, then $\mathbb{E}[s] = 1$.

When `X_test` contains NaNs (e.g. holidays, pre-listing, or post-delisting
periods), NaN returns for active assets contribute zero to the realized
portfolio return. The forecast covariance is scaled by the pairwise
observation count matrix $H$ (Hadamard product
$H \odot \Sigma$) so that the realized portfolio variance and
forecast variance follow the same missing-data convention. In skfolio,
NaN diagonal entries in the forecast covariance mark inactive assets,
which are excluded before the score is computed.

When multiple portfolios are provided (2D weights), the ratio is computed
independently for each and the mean is returned. This produces a more
robust diagnostic by averaging across multiple portfolio directions.

* **Parameters:**
  **estimator** *BaseEstimator*
  : Fitted estimator, must expose `covariance_` or `return_distribution_.covariance`.

  **X_test** *array-like of shape (n_observations, n_assets)*
  : Realized returns for the test window.

  **y** *Ignored*
  : Present for scikit-learn API compatibility.

  **portfolio_weights** *array-like of shape (n_assets,) or (n_portfolios, n_assets), optional*
  : Portfolio weights. If `None` (default), inverse-volatility weights are used,
    which neutralizes volatility dispersion so that high-volatility assets do not
    dominate the diagnostic. If a 2D array is provided, each row defines a test
    portfolio and the mean ratio across portfolios is returned. For equal-weight
    calibration, pass `portfolio_weights=np.ones(n_assets) / n_assets`.
* **Returns:**
  float
  : Calibration ratio. Values near `1.0` indicate that the projected
    portfolio variance is well calibrated on average.

#### SEE ALSO
[`portfolio_variance_calibration_loss`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_calibration_loss.html.md#skfolio.metrics.portfolio_variance_calibration_loss)
: Absolute deviation from the calibration target of `1.0`.

[`portfolio_variance_qlike_loss`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_qlike_loss.html.md#skfolio.metrics.portfolio_variance_qlike_loss)
: QLIKE loss for the projected portfolio variance.

# generated/skfolio.metrics.portfolio_variance_qlike_loss.html.md

<a id="skfolio-metrics-portfolio-variance-qlike-loss"></a>

# skfolio.metrics.portfolio_variance_qlike_loss

<a id="skfolio.metrics.portfolio_variance_qlike_loss"></a>

### skfolio.metrics.portfolio_variance_qlike_loss(estimator, X_test, y=None, portfolio_weights=None)

QLIKE loss for a projected portfolio variance forecast [[1]](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_qlike_loss.html.md#r7dedfcdc36e0-1).

Let $r_t$ be the one-period realized return vector at time $t$
and $w^\top r_t$ the corresponding one-period portfolio return for
weights $w$. The loss compares the forecast portfolio variance
with the realized sum of squared portfolio returns over the evaluation
window of $h$ observations:

$$
\ell = \log\left(h\, w^\top \Sigma\, w\right)
     + \frac{\sum_{t=1}^{h} (w^\top r_t)^2}{h\, w^\top \Sigma\, w}
$$

Lower values are better. In expectation, the loss is minimized by the
true conditional portfolio variance forecast.

When `X_test` contains NaNs (e.g. holidays, pre-listing, or post-delisting
periods), NaN returns for active assets contribute zero to the realized
portfolio return. The forecast covariance is scaled by the pairwise
observation count matrix $H$ (Hadamard product
$H \odot \Sigma$) so that the realized portfolio variance and
forecast variance follow the same missing-data convention. In skfolio,
NaN diagonal entries in the forecast covariance mark inactive assets,
which are excluded before the score is computed.

When multiple portfolios are provided (2D weights), the QLIKE is computed
independently for each and the mean is returned. This lets one summary
score evaluate several portfolio directions at once.

* **Parameters:**
  **estimator** *BaseEstimator*
  : Fitted estimator, must expose `covariance_` or `return_distribution_.covariance`.

  **X_test** *array-like of shape (n_observations, n_assets)*
  : Realized returns for the test window.

  **y** *Ignored*
  : Present for scikit-learn API compatibility.

  **portfolio_weights** *array-like of shape (n_assets,) or (n_portfolios, n_assets), optional*
  : Portfolio weights. If `None` (default), inverse-volatility weights are used,
    which neutralizes volatility dispersion so that high-volatility assets do not
    dominate the diagnostic. If a 2D array is provided, each row defines a test
    portfolio and the mean QLIKE across portfolios is returned.
* **Returns:**
  float
  : Mean portfolio QLIKE loss. Lower values are better; in expectation, the loss
    is minimized by the true conditional portfolio variance forecast.

#### SEE ALSO
[`portfolio_variance_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_calibration_ratio.html.md#skfolio.metrics.portfolio_variance_calibration_ratio)
: Calibration ratio for the projected portfolio variance.

[`portfolio_variance_calibration_loss`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_calibration_loss.html.md#skfolio.metrics.portfolio_variance_calibration_loss)
: Calibration loss for the projected portfolio variance.

[`qlike_loss`](https://skfolio.org/generated/skfolio.metrics.qlike_loss.html.md#skfolio.metrics.qlike_loss)
: Univariate QLIKE loss.

### References

* <a id='r7dedfcdc36e0-1'>**[1]**</a> “Volatility forecast comparison using imperfect volatility proxies” Journal of Econometrics. Patton, A. J. (2011).

# generated/skfolio.metrics.qlike_loss.html.md

<a id="skfolio-metrics-qlike-loss"></a>

# skfolio.metrics.qlike_loss

<a id="skfolio.metrics.qlike_loss"></a>

### skfolio.metrics.qlike_loss(returns, forecast_variance)

QLIKE loss for univariate variance forecasts.

$$
\text{QLIKE} = \frac{1}{n} \sum_{t=1}^{n}
\left( \log(\sigma_t^2) + \frac{r_t^2}{\sigma_t^2} \right)
$$

Lower values are better. For numerical stability, forecast variances are
clipped below by a small positive constant before evaluating the score.

In financial time series, QLIKE is often used as a comparative score when
returns are heavy-tailed and realized variance is only an imperfect proxy
for latent volatility.

* **Parameters:**
  **returns** *array-like of shape (n_observations,)*
  : Realized returns.

  **forecast_variance** *array-like of shape (n_observations,)*
  : Forecast variances for the same timestamps, expressed in squared
    return units.
* **Returns:**
  float
  : Mean QLIKE loss. Lower values are better; in expectation, the loss is minimized
    by the true conditional variance forecast.

#### SEE ALSO
[`portfolio_variance_qlike_loss`](https://skfolio.org/generated/skfolio.metrics.portfolio_variance_qlike_loss.html.md#skfolio.metrics.portfolio_variance_qlike_loss)
: Multivariate QLIKE loss projected onto portfolio weights.

# generated/skfolio.model_selection.BaseCombinatorialCV.html.md

<a id="skfolio-model-selection-basecombinatorialcv"></a>

# skfolio.model_selection.BaseCombinatorialCV

<a id="skfolio.model_selection.BaseCombinatorialCV"></a>

### *class* skfolio.model_selection.BaseCombinatorialCV

Base class for all combinatorial cross-validators.

Implementations must define `split` or `get_path_ids`.

### Methods

| [`get_path_ids`](https://skfolio.org/generated/skfolio.model_selection.BaseCombinatorialCV.html.md#skfolio.model_selection.BaseCombinatorialCV.get_path_ids)()   | Return the path id of each test sets in each split.   |
|-------------------------------------------------------------------|-------------------------------------------------------|

| **split**   |    |
|-------------|----|

<a id="skfolio.model_selection.BaseCombinatorialCV.get_path_ids"></a>

#### *abstractmethod* get_path_ids()

Return the path id of each test sets in each split.

# generated/skfolio.model_selection.CombinatorialPurgedCV.html.md

<a id="skfolio-model-selection-combinatorialpurgedcv"></a>

# skfolio.model_selection.CombinatorialPurgedCV

<a id="skfolio.model_selection.CombinatorialPurgedCV"></a>

### *class* skfolio.model_selection.CombinatorialPurgedCV(n_folds=10, n_test_folds=8, purged_size=0, embargo_size=0)

Combinatorial Purged Cross-Validation.

Provides train/test indices to split time series data samples based on
Combinatorial Purged Cross-Validation [[1]](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#re93330c75414-1).

Compared to `KFold`, which splits the data into `k` folds with `1` fold for the test
set and `k - 1` folds for the training set, `CombinatorialPurgedCV` uses `k - p`
folds for the training set with `p > 1` being the number of test folds.

`KFold` can recombine one single testing path while `CombinatorialPurgedCV` can
recombine multiple testing paths from the combinations of the train/test sets.

To avoid data leakage, purging and embargoing can be performed.

Purging consists of removing from the training set all observations whose labels
overlapped in time with those labels included in the testing set.

Embargoing consists of removing from the training set all observations that
immediately follow an observation in the testing set, since financial features
often incorporate series that exhibit serial correlation (like ARMA processes).

* **Parameters:**
  **n_folds** *int, default=10*
  : Number of folds. Must be at least 3.

  **n_test_folds** *int, default=8*
  : Number of test folds. Must be at least 2.
    For only one test fold, use `sklearn.model_validation.KFold`.

  **purged_size** *int, default=0*
  : Number of observations to exclude from the start of each train set that are
    after a test set **and** the number of observations to exclude from the end of
    each training set that are before a test set.

  **embargo_size** *int, default=0*
  : Number of observations to exclude from the start of each training set that are
    after a test set.
* **Attributes:**
  **index_train_test_** *ndarray of shape (n_observations, n_splits)*

### Methods

| [`get_n_splits`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV.get_n_splits)([X, y, groups])   | Return the number of splitting iterations in the cross-validator.                                                                              |
|---------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| [`get_path_ids`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV.get_path_ids)()                 | Return the path id of each test sets in each split.                                                                                            |
| [`plot_train_test_folds`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV.plot_train_test_folds)()        | Plot the train/test fold locations.                                                                                                            |
| [`plot_train_test_index`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV.plot_train_test_index)(X)       | Plot the training and test indices for each combinations by assigning `0` to training, `1` to test and `-1` to both purge and embargo indices. |
| [`split`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV.split)(X[, y, groups])          | Generate indices to split data into training and test set.                                                                                     |

| **summary**   |    |
|---------------|----|

### References

* <a id='re93330c75414-1'>**[1]**</a> “Advances in Financial Machine Learning”, Marcos López de Prado (2018)

### Examples

Tutorials using `CombinatorialPurgedCV`:
: * [Drop Highly Correlated Assets](https://skfolio.org/auto_examples/pre_selection/plot_1_drop_correlated.html.md#sphx-glr-auto-examples-pre-selection-plot-1-drop-correlated-py)
  * [HRP vs HERC](https://skfolio.org/auto_examples/clustering/plot_3_hrp_vs_herc.html.md#sphx-glr-auto-examples-clustering-plot-3-hrp-vs-herc-py)
  * [NCO - Combinatorial Purged CV](https://skfolio.org/auto_examples/clustering/plot_5_nco_grid_search.html.md#sphx-glr-auto-examples-clustering-plot-5-nco-grid-search-py)

```pycon
>>> import numpy as np
>>> from skfolio.model_selection import CombinatorialPurgedCV
>>> X = np.random.randn(12, 2)
>>> cv = CombinatorialPurgedCV(n_folds=3, n_test_folds=2)
>>> for i, (train_index, tests) in enumerate(cv.split(X)):
...     print(f"Split {i}:")
...     print(f"  Train: index={train_index}")
...     for j, test_index in enumerate(tests):
...         print(f"  Test {j}:  index={test_index}")
Split 0:
  Train: index=[ 8  9 10 11]
  Test 0:  index=[0 1 2 3]
  Test 1:  index=[4 5 6 7]
Split 1:
  Train: index=[4 5 6 7]
  Test 0:  index=[0 1 2 3]
  Test 1:  index=[ 8  9 10 11]
Split 2:
  Train: index=[0 1 2 3]
  Test 0:  index=[4 5 6 7]
  Test 1:  index=[ 8  9 10 11]
>>> cv = CombinatorialPurgedCV(n_folds=3, n_test_folds=2, purged_size=1)
>>> for i, (train_index, tests) in enumerate(cv.split(X)):
...     print(f"Split {i}:")
...     print(f"  Train: index={train_index}")
...     for j, test_index in enumerate(tests):
...         print(f"  Test {j}:  index={test_index}")
Split 0:
  Train: index=[ 9 10 11]
  Test 0:  index=[0 1 2 3]
  Test 1:  index=[4 5 6 7]
Split 1:
  Train: index=[5 6]
  Test 0:  index=[0 1 2 3]
  Test 1:  index=[ 8  9 10 11]
Split 2:
  Train: index=[0 1 2]
  Test 0:  index=[4 5 6 7]
  Test 1:  index=[ 8  9 10 11]
>>> cv = CombinatorialPurgedCV(n_folds=3, n_test_folds=2, embargo_size=1)
>>> for i, (train_index, tests) in enumerate(cv.split(X)):
...     print(f"Split {i}:")
...     print(f"  Train: index={train_index}")
...     for j, test_index in enumerate(tests):
...         print(f"  Test {j}:  index={test_index}")
Split 0:
  Train: index=[ 9 10 11]
  Test 0:  index=[0 1 2 3]
  Test 1:  index=[4 5 6 7]
Split 1:
  Train: index=[5 6 7]
  Test 0:  index=[0 1 2 3]
  Test 1:  index=[ 8  9 10 11]
Split 2:
  Train: index=[0 1 2 3]
  Test 0:  index=[4 5 6 7]
  Test 1:  index=[ 8  9 10 11]
```

<a id="skfolio.model_selection.CombinatorialPurgedCV.binary_train_test_sets"></a>

#### *property* binary_train_test_sets

Identify training and test folds for each combinations by assigning `0` to
training folds and `1` to test folds.

<a id="skfolio.model_selection.CombinatorialPurgedCV.get_n_splits"></a>

#### get_n_splits(X=None, y=None, groups=None)

Return the number of splitting iterations in the cross-validator.

* **Parameters:**
  **X** *object*
  : Always ignored, exists for compatibility.

  **y** *object*
  : Always ignored, exists for compatibility.

  **groups** *object*
  : Always ignored, exists for compatibility.
* **Returns:**
  **n_splits** *int*
  : Number of splitting iterations in the cross-validator.

<a id="skfolio.model_selection.CombinatorialPurgedCV.get_path_ids"></a>

#### get_path_ids()

Return the path id of each test sets in each split.

<a id="skfolio.model_selection.CombinatorialPurgedCV.n_splits"></a>

#### *property* n_splits

Number of splits.

<a id="skfolio.model_selection.CombinatorialPurgedCV.n_test_paths"></a>

#### *property* n_test_paths

Number of test paths that can be reconstructed from the train/test
combinations.

<a id="skfolio.model_selection.CombinatorialPurgedCV.plot_train_test_folds"></a>

#### plot_train_test_folds()

Plot the train/test fold locations.

<a id="skfolio.model_selection.CombinatorialPurgedCV.plot_train_test_index"></a>

#### plot_train_test_index(X)

Plot the training and test indices for each combinations by assigning `0` to
training, `1` to test and `-1` to both purge and embargo indices.

<a id="skfolio.model_selection.CombinatorialPurgedCV.recombined_paths"></a>

#### *property* recombined_paths

Recombine each test path by returning the test set location in each split.

<a id="skfolio.model_selection.CombinatorialPurgedCV.split"></a>

#### split(X, y=None, groups=None)

Generate indices to split data into training and test set.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_features)*
  : Training data, where `n_samples` is the number of samples and `n_features`
    is the number of features.

  **y** *array-like of shape (n_samples,), optional*
  : The (multi-)target variable

  **groups** *array-like of shape (n_samples,), optional*
  : Group labels for the samples used while splitting the dataset into
    train/test set.
* **Yields:**
  **train** *ndarray*
  : The training set indices for that split.

  **test** *ndarray*
  : The testing set indices for that split.

<a id="skfolio.model_selection.CombinatorialPurgedCV.test_set_index"></a>

#### *property* test_set_index

Location of each test set.

# generated/skfolio.model_selection.CovarianceForecastComparison.html.md

<a id="skfolio-model-selection-covarianceforecastcomparison"></a>

# skfolio.model_selection.CovarianceForecastComparison

<a id="skfolio.model_selection.CovarianceForecastComparison"></a>

### *class* skfolio.model_selection.CovarianceForecastComparison(evaluations, names=None)

Side-by-side comparison of covariance forecast evaluations.

Aggregates multiple [`CovarianceForecastEvaluation`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation) instances and provides
combined summary tables and overlay plots for comparing estimator performance.

* **Parameters:**
  **evaluations** *list of CovarianceForecastEvaluation*
  : Evaluation results to compare.

  **names** *list of str, optional*
  : Override display names. When provided, must have the same length as
    `evaluations`. When `None`, defaults to each evaluation’s
    `name` (falling back to
    `"Estimator 0"`, `"Estimator 1"`, etc. when the name is unset).
* **Attributes:**
  **names**

### Methods

| [`bias_statistic_summary`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison.bias_statistic_summary)()                         | Cross-portfolio bias statistic distribution for all estimators.   |
|---------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| [`exceedance_summary`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison.exceedance_summary)([confidence_levels])          | Exceedance rate summary for all estimators.                       |
| [`plot_calibration`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison.plot_calibration)([diagnostics, window, title])   | Rolling calibration diagnostics comparison.                       |
| [`plot_exceedance`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison.plot_exceedance)([confidence_level, window, ...]) | Rolling exceedance rate comparison at a fixed confidence level.   |
| [`plot_qlike_loss`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison.plot_qlike_loss)([window, title])                 | Rolling portfolio QLIKE loss comparison.                          |
| [`summary`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison.summary)()                                        | Consolidated summary statistics for all estimators.               |

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.model_selection import (
...     CovarianceForecastComparison,
...     online_covariance_forecast_evaluation,
... )
>>> from skfolio.moments import EWCovariance
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(504)
>>> evaluation_30 = online_covariance_forecast_evaluation(
...     EWCovariance(half_life=30), X, warmup_size=252,
... )
>>> evaluation_60 = online_covariance_forecast_evaluation(
...     EWCovariance(half_life=60), X, warmup_size=252,
... )
>>> comparison = CovarianceForecastComparison(
...     [evaluation_30, evaluation_60],
...     names=["EWCov(30)", "EWCov(60)"],
... )
>>> comparison.summary()
estimator                      EWCov(30)  ...        EWCov(60)
                                    mean  ...           target
Mahalanobis ratio               1.405...  ...              1.0
Diagonal ratio                  1.090...  ...              1.0
Portfolio standardized returns  0.010...  ...    mean=0, std=1
Portfolio QLIKE                -7.923...  ...  lower is better

[4 rows x 14 columns]
>>> comparison.plot_calibration()
Figure(...)
```

<a id="skfolio.model_selection.CovarianceForecastComparison.bias_statistic_summary"></a>

#### bias_statistic_summary()

Cross-portfolio bias statistic distribution for all estimators.

Returns a DataFrame indexed by estimator name with percentile
columns and portfolio count.

* **Returns:**
  **summary** *DataFrame*

<a id="skfolio.model_selection.CovarianceForecastComparison.exceedance_summary"></a>

#### exceedance_summary(confidence_levels=(0.95, 0.99))

Exceedance rate summary for all estimators.

Returns a DataFrame with confidence levels as rows and a column-level
MultiIndex `(estimator, stat)` where stat is `observed_rate` or
`deviation`.

* **Parameters:**
  **confidence_levels** *tuple of float, default=(0.95, 0.99)*
  : Confidence levels used to define the upper chi-squared thresholds.
* **Returns:**
  **summary** *DataFrame*

<a id="skfolio.model_selection.CovarianceForecastComparison.plot_calibration"></a>

#### plot_calibration(diagnostics=('mahalanobis', 'diagonal', 'bias'), window=50, title=None)

Rolling calibration diagnostics comparison.

Overlays calibration diagnostics from all estimators on one figure.
Each `(estimator, diagnostic)` pair gets a distinct auto-assigned
color.

* **Parameters:**
  **diagnostics** *tuple of str, default=(“mahalanobis”, “diagonal”, “bias”)*
  : Which diagnostics to include. Valid values are `"mahalanobis"`,
    `"diagonal"`, and `"bias"`.

  **window** *int, default=50*
  : Rolling window length.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.model_selection.CovarianceForecastComparison.plot_exceedance"></a>

#### plot_exceedance(confidence_level=0.95, window=50, title=None)

Rolling exceedance rate comparison at a fixed confidence level.

Overlays exceedance rates from all estimators at a single
confidence level on one figure.

* **Parameters:**
  **confidence_level** *float, default=0.95*
  : Confidence level used to define the upper chi-squared threshold.

  **window** *int, default=50*
  : Rolling window length.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.model_selection.CovarianceForecastComparison.plot_qlike_loss"></a>

#### plot_qlike_loss(window=50, title=None)

Rolling portfolio QLIKE loss comparison.

Overlays QLIKE loss from all estimators on one figure. For
evaluations with multiple portfolios, the median across portfolios
is shown with a P5-P95 band.

* **Parameters:**
  **window** *int, default=50*
  : Rolling window length.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.model_selection.CovarianceForecastComparison.summary"></a>

#### summary()

Consolidated summary statistics for all estimators.

Returns a DataFrame with metrics as rows and a column-level
MultiIndex `(estimator, stat)` where stat is one of `mean`,
`median`, `std`, `p5`, `p95`, `mad_from_target`, `target`.

* **Returns:**
  **summary** *DataFrame*

# generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md

<a id="skfolio-model-selection-covarianceforecastevaluation"></a>

# skfolio.model_selection.CovarianceForecastEvaluation

<a id="skfolio.model_selection.CovarianceForecastEvaluation"></a>

### *class* skfolio.model_selection.CovarianceForecastEvaluation(observations, horizon, squared_mahalanobis_distance, mahalanobis_calibration_ratio, diagonal_calibration_ratio, portfolio_standardized_return, portfolio_variance_qlike_loss, n_valid_assets, n_portfolios, name=None)

Out-of-sample covariance forecast evaluation.

Stores per-step calibration diagnostics produced by
[`covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.covariance_forecast_evaluation.html.md#skfolio.model_selection.covariance_forecast_evaluation) or
[`online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation)
and provides summary statistics and plots.

The four core diagnostics are:

* **Mahalanobis calibration ratio**: tests whether the full covariance
  structure (all eigenvalue directions) is correctly specified. At each
  step, let $r_t$ be the one-period realized return vector and let
  $R^{(h)}$ be the aggregated return over the evaluation window of
  $h$ observations. The squared Mahalanobis distance
  $d^2 = {R^{(h)}}^\top(h\,\Sigma)^{-1}R^{(h)}$ yields the
  calibration ratio $d^2 / n$, where $n$ is the number of
  active assets. The target is 1.0. A value above 1.0 indicates
  underestimated risk; below 1.0 indicates overestimated risk.
* **Diagonal calibration ratio**: tests whether the individual asset
  variances are correctly specified, ignoring correlations. Computed as
  $\frac{1}{n}\sum_i (R_i^{(h)})^2 / (h_i\,\sigma_i^2)$ where
  $h_i$ is the number of finite returns for asset $i$ in the
  evaluation window. The target is 1.0. A value above 1.0 indicates
  underestimated volatilities; below 1.0 indicates overestimated
  volatilities.
* **Portfolio standardized returns**: tests whether the covariance is
  well calibrated along one or more portfolio directions rather than
  across all directions. For a portfolio with weights $w$, the
  realized portfolio return is standardized by the matching forecast
  portfolio volatility: $b = r_p / \hat\sigma_p$ with
  $r_p = w^\top R^{(h)}$ and
  $\hat\sigma_p^{2} = w^\top(h\,\Sigma)w$.
  Under correct calibration $b_t$ has mean 0 and standard
  deviation 1. The bias statistic $B = \mathrm{std}(b_t)$
  summarizes forecast quality: $B \approx 1$ is well calibrated,
  $B > 1$ indicates underestimated risk, $B < 1$ indicates
  overestimated risk.
* **Portfolio QLIKE**: evaluates portfolio variance forecasts along one
  or more portfolio directions by comparing the forecast portfolio
  variance with the realized sum of squared portfolio returns over the
  evaluation window. Lower values indicate better portfolio variance
  forecasts.

When `X_test` contains NaNs (e.g. holidays, pre-listing, or
post-delisting periods), only finite observations contribute to the
aggregated return. For portfolio diagnostics, NaN returns for active
assets contribute zero to the realized portfolio return and the forecast
covariance is scaled by the pairwise observation count matrix $H$
(Hadamard product $H \odot \Sigma$) so that the realized portfolio
variance and forecast variance follow the same missing-data convention.
In skfolio, NaN diagonal entries in the forecast covariance mark inactive
assets, which are excluded from the evaluation.

When multiple test portfolios are provided, portfolio-level diagnostics
are computed for each portfolio independently. The
cross-portfolio distribution of bias statistics reveals anisotropic
calibration errors that a single portfolio might miss.

* **Parameters:**
  **observations** *ndarray of shape (n_steps,)*
  : Time index labels for each evaluation step.

  **horizon** *int*
  : Number of observations per evaluation window. Every window has exactly
    this many observations.

  **squared_mahalanobis_distance** *ndarray of shape (n_steps,)*
  : Squared Mahalanobis distance
    $d_t^2 = {R_t^{(h)}}^\top(h\,\Sigma_t)^{-1}R_t^{(h)}$.
    Under correct Gaussian calibration each value follows a
    $\chi^2(n)$ distribution, where $n$ is the number of
    active assets.

  **mahalanobis_calibration_ratio** *ndarray of shape (n_steps,)*
  : $d_t^2 / n$, where $n$ is the number of active assets.
    Target is 1.0. Tests whether the full covariance structure (all
    eigenvalue directions) is correctly specified.

  **diagonal_calibration_ratio** *ndarray of shape (n_steps,)*
  : $\frac{1}{n}\sum_i (R_{i,t}^{(h)})^2 / (h_{i,t}\,\sigma_{i,t}^2)$.
    Target is 1.0. Tests individual asset variances only.

  **portfolio_standardized_return** *ndarray of shape (n_steps, n_portfolios)*
  : $b_t = r_{p,t} / \hat\sigma_{p,t}$.
    Target mean is 0.0 and target std is 1.0 (the bias statistic).

  **portfolio_variance_qlike_loss** *ndarray of shape (n_steps, n_portfolios)*
  : $\log(\hat\sigma_{p,t}^{2}) +
    \sum_{j=1}^{h} r_{p,t,j}^{2} / \hat\sigma_{p,t}^{2}$.
    Compares the forecast portfolio variance with the realized sum of
    squared portfolio returns over the evaluation window. Lower values
    are better.

  **n_valid_assets** *ndarray of shape (n_steps,)*
  : Number of active assets used at each evaluation step.

  **n_portfolios** *int*
  : Number of test portfolios.

  **name** *str, optional*
  : Display name for the evaluation.
* **Attributes:**
  [`bias_statistic`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.bias_statistic)
  : Per-portfolio bias statistic.

  **name**

### Methods

| [`bias_statistic_summary`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.bias_statistic_summary)()                          | Cross-portfolio distribution of bias statistics.   |
|----------------------------------------------------------------------------------------------------|----------------------------------------------------|
| [`exceedance_summary`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.exceedance_summary)([confidence_levels])           | Exceedance rate summary.                           |
| [`plot_calibration`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.plot_calibration)([diagnostics, window, title])    | Rolling calibration diagnostics over time.         |
| [`plot_exceedance`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.plot_exceedance)([confidence_levels, window, ...]) | Rolling exceedance rates over time.                |
| [`plot_qlike_loss`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.plot_qlike_loss)([window, title])                  | Rolling portfolio QLIKE loss over time.            |
| [`summary`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.summary)()                                         | Consolidated summary statistics.                   |

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.model_selection import online_covariance_forecast_evaluation
>>> from skfolio.moments import EWCovariance
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(504)
>>> evaluation = online_covariance_forecast_evaluation(
...     EWCovariance(half_life=30),
...     X,
...     warmup_size=252,
... )
>>> evaluation.summary()
                                    mean  ...           target
Mahalanobis ratio               1.405...  ...              1.0
Diagonal ratio                  1.090...  ...              1.0
Portfolio standardized returns  0.010...  ...    mean=0, std=1
Portfolio QLIKE                -7.923...  ...  lower is better

[4 rows x 7 columns]
>>> evaluation.plot_calibration()
Figure(...)
```

<a id="skfolio.model_selection.CovarianceForecastEvaluation.bias_statistic"></a>

#### *property* bias_statistic

Per-portfolio bias statistic.

Computed as the sample standard deviation of the portfolio
standardized returns $B_k = \mathrm{std}(b_{k,t})$ for each
test portfolio $k$.

A value near 1.0 indicates well-calibrated risk forecasts.
Values above 1.0 indicate underestimated risk; values below 1.0
indicate overestimated risk.

* **Returns:**
  **bias** *ndarray of shape (n_portfolios,)*

<a id="skfolio.model_selection.CovarianceForecastEvaluation.bias_statistic_summary"></a>

#### bias_statistic_summary()

Cross-portfolio distribution of bias statistics.

Computes percentiles of bias statistics across test portfolios. This
is useful for evaluating covariance forecast quality using a set
of representative portfolios.

Under Gaussian returns with perfect forecasts, $B^2(T-1)$
follows a $\chi^2(T-1)$ distribution where $T$ is the
number of evaluation steps. Reference bands can be derived from
the appropriate chi-squared quantiles:
$B_{p} = \sqrt{\chi^2_{p}(T-1) / (T-1)}$. In financial return
series, heavy tails widen these bands because the sampling variance of
$B$ increases.

* **Returns:**
  **summary** *Series*

<a id="skfolio.model_selection.CovarianceForecastEvaluation.exceedance_summary"></a>

#### exceedance_summary(confidence_levels=(0.95, 0.99))

Exceedance rate summary.

Compares squared Mahalanobis distances to $\chi^2$ thresholds.
The rate is sensitive not only to covariance misspecification but also
to heavy tails, regime shifts, and non-Gaussian standardized returns.
It is best used as a comparative metric across estimators rather than
as an absolute calibration test.

* **Parameters:**
  **confidence_levels** *tuple of float, default=(0.95, 0.99)*
  : Confidence levels used to define the upper chi-squared thresholds.
* **Returns:**
  **summary** *DataFrame*
  : Indexed by `confidence_level` with columns `observed_rate` and
    `deviation`, where `deviation` is measured relative to the target
    exceedance rate $1 - \text{confidence\_level}$.

<a id="skfolio.model_selection.CovarianceForecastEvaluation.plot_calibration"></a>

#### plot_calibration(diagnostics=('mahalanobis', 'diagonal', 'bias'), window=50, title=None)

Rolling calibration diagnostics over time.

Plots rolling calibration diagnostics with a reference line at 1.0.
By default all three diagnostics are shown: rolling mean of the
Mahalanobis ratio, rolling mean of the diagonal ratio, and rolling
standard deviation of the portfolio standardized return (bias
statistic).

For multiple portfolios, the bias statistic shows the median across
portfolios with a P5-P95 shaded band.

* **Parameters:**
  **diagnostics** *tuple of str, default=(“mahalanobis”, “diagonal”, “bias”)*
  : Which diagnostics to include. Valid values are `"mahalanobis"`,
    `"diagonal"`, and `"bias"`.

  **window** *int, default=50*
  : Rolling window length.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.model_selection.CovarianceForecastEvaluation.plot_exceedance"></a>

#### plot_exceedance(confidence_levels=(0.95, 0.99), window=50, title=None)

Rolling exceedance rates over time.

Compares squared Mahalanobis distances to $\chi^2$ thresholds.
The rate is sensitive not only to covariance misspecification but also
to heavy tails, regime shifts, and non-Gaussian standardized returns.
It is best used as a comparative metric across estimators rather than
as an absolute calibration test.

* **Parameters:**
  **confidence_levels** *tuple of float, default=(0.95, 0.99)*
  : Confidence levels used to define the upper chi-squared thresholds.

  **window** *int, default=50*
  : Rolling window length.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.model_selection.CovarianceForecastEvaluation.plot_qlike_loss"></a>

#### plot_qlike_loss(window=50, title=None)

Rolling portfolio QLIKE loss over time.

The QLIKE loss compares the forecast portfolio variance with the
realized sum of squared portfolio returns over the evaluation
window. Lower values are better.

For multiple portfolios, a shaded band shows the P5-P95 range across portfolios,
with a line for the median.

* **Parameters:**
  **window** *int, default=50*
  : Rolling window length.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.model_selection.CovarianceForecastEvaluation.summary"></a>

#### summary()

Consolidated summary statistics.

Returns a DataFrame with one row per metric and columns `mean`, `median`, `std`,
`p5`, `p95`, `mad_from_target`, and `target`.

* For calibration ratios, the target is `1.0`, so `mad_from_target` is the mean
  absolute deviation from `1.0`.
* For portfolio standardized returns, the target mean is `0.0`, so
  `mad_from_target` is the mean absolute value. The `std` column corresponds to
  the bias statistic $B = \mathrm{std}(b_t)$, whose target is `1.0`.
  Values near `1.0` indicate well-calibrated risk forecasts, values above `1.0`
  indicate underestimated risk, and values below `1.0` indicate overestimated
  risk.When only one portfolio is evaluated, the `std` column is exactly that
  portfolio’s bias statistic. When multiple portfolios are evaluated,
  portfolio-level diagnostics are first computed separately for each portfolio
  and then aggregated by their median. In particular, the `std` column becomes
  the median of the per-portfolio bias statistics. See also
  [`bias_statistic`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.bias_statistic) and [`bias_statistic_summary`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.bias_statistic_summary).
* For QLIKE loss, there is no fixed numeric target. Accordingly,
  `mad_from_target` is NaN and `target` is `"lower is better"`.

* **Returns:**
  **summary** *DataFrame*

# generated/skfolio.model_selection.MultipleRandomizedCV.html.md

<a id="skfolio-model-selection-multiplerandomizedcv"></a>

# skfolio.model_selection.MultipleRandomizedCV

<a id="skfolio.model_selection.MultipleRandomizedCV"></a>

### *class* skfolio.model_selection.MultipleRandomizedCV(walk_forward, n_subsamples, asset_subset_size, window_size=None, random_state=None)

Multiple Randomized Cross-Validation.

Based on the “Multiple Randomized Backtests” methodology of Palomar [[1]](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#re1c77981427b-1),
this cross-validation strategy performs a resampling-based evaluation by repeatedly
sampling **distinct** asset subsets (without replacement) and **contiguous** time
windows, then applying an inner walk-forward split to each subsample, capturing both
temporal and cross-sectional variability in performance.

On each of the `n_subsamples` iterations, the following actions are performed:

1. Randomly pick a contiguous time window of length `window_size` (or the full history if None).
2. Randomly pick an asset subset of size `asset_subset_size` (without replacement).
3. Run a walk-forward split (via the supplied `walk_forward` object) on that sub-dataset.
4. Yield `(train_indices, test_indices, asset_indices)` for each inner split.

Each asset subset is sampled without replacement (assets within each subset are
distinct) and no subset is repeated across the `n_subsamples` draws. We employ the
combinatorial unranking algorithm to compute any k-combination in
`O(n_subsamples * asset_subset_size)` time and space, without generating or storing
all $M=\binom{n\_assets}{asset\_subset\_size}$ subsets. When $M$ is
small, this guarantees exhaustive coverage of every possible asset-universe.
Because ranks are drawn without replacement from a finite population of size
$M$, the variance of the sample mean is reduced by the finite-population
correction factor $\tfrac{M - n\_subsamples}{M - 1}$.

* **Parameters:**
  **walk_forward** *WalkForward*
  : A [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) CV object to be applied to
    each subsample.

  **n_subsamples** *int*
  : Number of independent subsamples (sub-datasets) to draw. Each subsample is a
    (time window x asset subset) on which you run the inner walk-forward.

  **asset_subset_size** *int*
  : How many assets to include in each subsample.
    Must be less or equal to the total number of assets.

  **window_size** *int or None, default=None*
  : Length of the contiguous time slice (number of observations) for each
    subsample. If None, uses the full time series observations in every draw.

  **random_state** *int, RandomState instance or None, default=None*
  : Seed or random state to ensure reproducibility.

### Methods

| [`get_n_splits`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV.get_n_splits)([X, y, groups])   | Return the number of splitting iterations in the cross-validator.   |
|---------------------------------------------------------------------------------|---------------------------------------------------------------------|
| [`get_path_ids`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV.get_path_ids)()                 | Return the path id of each test sets in each split.                 |
| [`split`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV.split)(X[, y])                  | Generate indices to split data into training and test set.          |

### References

* <a id='re1c77981427b-1'>**[1]**</a> “Portfolio Optimization: Theory and Application”, Chapter 8, Daniel P. Palomar (2025)

### Examples

Tutorials using `MultipleRandomizedCV`:
: * [Multiple Randomized Cross-Validation](https://skfolio.org/auto_examples/model_selection/plot_1_multiple_randomized_cv.html.md#sphx-glr-auto-examples-model-selection-plot-1-multiple-randomized-cv-py)

```pycon
>>> import numpy as np
>>> from skfolio.datasets import load_sp500_dataset, load_factors_dataset
>>> from skfolio.model_selection import WalkForward, MultipleRandomizedCV
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> X = np.random.randn(4, 5) # 4 observations and 5 assets.
>>> # Draw 2 subsamples (sub-datasets) with 3 assets chosen randomly among the 5.
>>> # For each subsample, run a Walk Forward.
>>> # Use the full time series (no time resampling).
>>> cv = MultipleRandomizedCV(
...     walk_forward=WalkForward(test_size=1, train_size=2),
...     n_subsamples=2,
...     asset_subset_size=3,
...     window_size=None,
...     random_state=0,
... )
>>> for i, (train_index, test_index, assets) in enumerate(cv.split(X)):
...     print(f"Fold {i}:")
...     print(f"  Train:  index={train_index}")
...     print(f"  Test:   index={test_index}")
...     print(f"  Assets: columns={assets}")
Fold 0:
  Train:  index=[0 1]
  Test:   index=[2]
  Assets: columns=[1 2 3]
Fold 1:
  Train:  index=[1 2]
  Test:   index=[3]
  Assets: columns=[1 2 3]
Fold 2:
  Train:  index=[0 1]
  Test:   index=[2]
  Assets: columns=[2 3 4]
Fold 3:
  Train:  index=[1 2]
  Test:   index=[3]
  Assets: columns=[2 3 4]
>>> print(f"Path ids: {cv.get_path_ids()}")
Path ids: [0 0 1 1]
>>>
>>> # Random contiguous time slice of 4 observations among 10 observations.
>>> X = np.random.randn(10, 5) # 10 observations and 5 assets.
>>> cv = MultipleRandomizedCV(
...     walk_forward=WalkForward(test_size=1, train_size=2),
...     n_subsamples=2,
...     asset_subset_size=3,
...     window_size=4,
...     random_state=0,
... )
>>> for i, (train_index, test_index, assets) in enumerate(cv.split(X)):
...     print(f"Fold {i}:")
...     print(f"  Train:  index={train_index}")
...     print(f"  Test:   index={test_index}")
...     print(f"  Assets: columns={assets}")
Fold 0:
  Train:  index=[4 5]
  Test:   index=[6]
  Assets: columns=[1 2 3]
Fold 1:
  Train:  index=[5 6]
  Test:   index=[7]
  Assets: columns=[1 2 3]
Fold 2:
  Train:  index=[5 6]
  Test:   index=[7]
  Assets: columns=[2 3 4]
Fold 3:
  Train:  index=[6 7]
  Test:   index=[8]
  Assets: columns=[2 3 4]
>>>
>>> # Walk Forward with time-based (calendar) rebalancing.
>>> # Rebalance every 3 months on the third Friday, and train on the last 12 months.
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>> X = X["2021":"2022"]
>>> cv = MultipleRandomizedCV(
...     walk_forward=WalkForward(test_size=3, train_size=12, freq="WOM-3FRI"),
...     n_subsamples=2,
...     asset_subset_size=3,
...     window_size=None,
...     random_state=0,
... )
>>> for i, (train_index, test_index, assets) in enumerate(cv.split(X)):
...     print(f"Fold {i}:")
...     print(f"  Train:  size={len(train_index)}")
...     print(f"  Test:   size={len(test_index)}")
...     print(f"  Assets: columns={assets}")
Fold 0:
  Train:  size=256
  Test:   size=59
  Assets: columns=[6 8 9]
Fold 1:
  Train:  size=253
  Test:   size=61
  Assets: columns=[6 8 9]
Fold 2:
  Train:  size=251
  Test:   size=69
  Assets: columns=[6 8 9]
Fold 3:
  Train:  size=256
  Test:   size=59
  Assets: columns=[ 7  8 16]
Fold 4:
  Train:  size=253
  Test:   size=61
  Assets: columns=[ 7  8 16]
Fold 5:
  Train:  size=251
  Test:   size=69
  Assets: columns=[ 7  8 16]
>>> print(f"Path ids: {cv.get_path_ids()}")
Path ids: [0 0 0 1 1 1]
```

<a id="skfolio.model_selection.MultipleRandomizedCV.get_n_splits"></a>

#### get_n_splits(X=None, y=None, groups=None)

Return the number of splitting iterations in the cross-validator.

When combining a frequency-based walk-forward with `window_size`, the exact
count depends on the random time slices drawn during `split`, so `split` must
be called first. In all other cases the count is computed directly from the
parameters and `X`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. Required when the count can be pre-computed
    (i.e. `window_size` is `None` or the inner walk-forward has no frequency).
    Ignored after [`split`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV.split) has been called.

  **y** *array-like of shape (n_observations, n_targets)*
  : Always ignored, exists for compatibility.

  **groups** *array-like of shape (n_observations,)*
  : Always ignored, exists for compatibility.
* **Returns:**
  **n_splits** *int*
  : Number of splitting iterations in the cross-validator.

<a id="skfolio.model_selection.MultipleRandomizedCV.get_path_ids"></a>

#### get_path_ids()

Return the path id of each test sets in each split.

<a id="skfolio.model_selection.MultipleRandomizedCV.split"></a>

#### split(X, y=None)

Generate indices to split data into training and test set.

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

  **y** *array-like of shape (n_observations, n_targets)*
  : Always ignored, exists for compatibility.
* **Yields:**
  **train** *ndarray*
  : The training set indices for that split.

  **test** *ndarray*
  : The testing set indices for that split.

  **assets** *ndarray*
  : The assets indices for that split.

# generated/skfolio.model_selection.OnlineGridSearch.html.md

<a id="skfolio-model-selection-onlinegridsearch"></a>

# skfolio.model_selection.OnlineGridSearch

<a id="skfolio.model_selection.OnlineGridSearch"></a>

### *class* skfolio.model_selection.OnlineGridSearch(estimator, param_grid, \*, scoring=None, warmup_size=252, test_size=1, freq=None, freq_offset=None, previous=False, purged_size=0, reduce_test=False, refit=True, error_score=nan, return_predictions=False, portfolio_params=None, entry_rebalancing_params=None, n_jobs=None, verbose=0)

Online exhaustive hyperparameter search over a parameter grid.

Each parameter combination is evaluated by running a full online
walk-forward pass. The best estimator is selected based on the
aggregate out-of-sample score.

* **Parameters:**
  **estimator** *BaseEstimator*
  : Estimator that supports `partial_fit`.

  **param_grid** *dict or list[dict]*
  : Dictionary with parameters names (`str`) as keys and lists of parameter
    settings to try as values, or a list of such dictionaries, in which case the
    grids spanned by each dictionary in the list are explored. This enables
    searching over any sequence of parameter settings.

  **scoring** *callable, dict, BaseMeasure, or None*
  : Scoring specification. Semantics depend on the estimator type:
    * **Component estimators** (e.g. covariance, expected returns):
      `None` uses `estimator.score`; otherwise pass a callable
      `scorer(estimator, X_test)` or a dict of such callables.
    * **Portfolio optimization estimators**:
      a [`BaseMeasure`](https://skfolio.org/generated/skfolio.measures.BaseMeasure.html.md#skfolio.measures.BaseMeasure) or a dict of measures.
      `None` defaults to
      `SHARPE_RATIO`.
    <br/>
    For portfolio optimization estimators, online evaluation scores the
    aggregated out-of-sample
    [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio), rather than scoring
    each test window independently and averaging as in
    `GridSearchCV`. Pass the measure enum
    directly; `make_scorer` is not supported.

  **warmup_size** *int, default=252*
  : Number of initial observations (or periods when `freq` is set) used
    for the first `partial_fit` call.

  **test_size** *int, default=1*
  : Number of observations (or periods when `freq` is set) per test
    window.

  **freq** *str | pandas.offsets.BaseOffset, optional*
  : Rebalancing frequency. When provided, `warmup_size` and `test_size`
    are interpreted as period counts rather than observation counts, and
    `X` must be a DataFrame with a `DatetimeIndex`. See
    [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) for details and
    examples.

  **freq_offset** *pandas.offsets.BaseOffset | datetime.timedelta, optional*
  : Offset applied to the `freq` boundaries. Only used when `freq` is
    provided.

  **previous** *bool, default=False*
  : Only used when `freq` is provided. If `True`, period boundaries
    that fall between observations snap to the previous observation;
    otherwise they snap to the next.

  **purged_size** *int, default=0*
  : Number of observations (or periods) to skip between the last data the
    model sees and the start of the test window.

  **reduce_test** *bool, default=False*
  : If `True`, the last test window is included even when it contains
    fewer observations than `test_size`.

  **refit** *bool, str, or callable, default=True*
  : Controls how the best candidate is selected and whether the
    selected fitted candidate is exposed as `best_estimator_`.
    <br/>
    This parameter is named for API alignment with scikit-learn.
    Unlike scikit-learn search estimators, enabling `refit` does
    not trigger an additional fit after model selection because
    each candidate is already evaluated through a full online
    walk-forward pass and updated through the full sample.
    * Single-metric scoring: `True` or `False` are both supported.
      If `False`, `best_estimator_` is not stored, but
      `best_index_`, `best_params_`, and `best_score_` remain
      available.
    * Multi-metric scoring: set to a scorer name to select the best
      candidate for that metric, or to `False` to disable
      best-candidate selection and storage of `best_estimator_`.
    * A callable receives `cv_results_` and must return the best
      candidate index.

  **error_score** *“raise” or float, default=np.nan*
  : Value to assign to the score if an error occurs during fitting.
    If set to `"raise"`, the error is raised.

  **return_predictions** *bool, default=False*
  : If `True`, store
    [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) objects per
    candidate in `cv_results_["predictions"]`. Only applies to
    portfolio optimization estimators.

  **portfolio_params** *dict, optional*
  : Portfolio parameters for the evaluation of each candidate parameter set.
    <br/>
    Parameters shared by [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) and
    [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) (`compounded`,
    `risk_free_rate`, `annualization_factor`, `fitness_measures` and the risk
    measure parameters) are applied to the `MultiPeriodPortfolio` scored for each
    parameter set and to each `Portfolio` it contains. A value passed here takes
    precedence over the optimizer’s `portfolio_params`. When omitted here, it is
    inherited from the optimizer’s `portfolio_params`. When omitted from both,
    `risk_free_rate` falls back to the optimizer’s `risk_free_rate` parameter when
    it has one. These parameters only affect how the portfolios are measured, not
    the optimization, so they can change the scores and the ranking of the
    parameter sets.
    <br/>
    `weight_drift` applies to each `Portfolio` of the path. With
    `weight_drift=True`, the weights held within each test window drift with the
    asset returns, and the path runs sequentially: the `ending_weights` of each
    portfolio are passed as `previous_weights` to the next update. A value passed
    here overrides the optimizer’s `portfolio_params`. When refitting is enabled,
    `weight_drift` is retained in `best_estimator_`. The other parameters are not.
    <br/>
    Optimizer parameters such as `transaction_costs`, `management_fees` and
    `previous_weights` are not accepted here. Set them on the optimizer.
    <br/>
    `name`, `tag`, `sample_weight` and `check_observations_order` apply to the
    scored `MultiPeriodPortfolio` only.

  **entry_rebalancing_params** *dict, optional*
  : Portfolio optimizer parameters applied only while constructing the first
    portfolio in the online path for each candidate parameter set. This is useful
    when the strategy starts with no existing position, while later portfolios
    represent regular rebalancing from the previously predicted weights. For
    example, the entry rebalancing can use lower `transaction_costs` or require a
    valid initial solution with `fallback=None`. Only supported for portfolio
    optimization estimators.

  **n_jobs** *int, optional*
  : Number of parallel jobs. `None` means 1.

  **verbose** *int, default=0*
  : Verbosity level for `joblib.Parallel`.
* **Attributes:**
  **cv_results_** *dict[str, ndarray]*
  : A dict with keys:
    * `params`: list of candidate parameter dicts.
    * `mean_score`: array of aggregate scores (or
      `mean_score_<name>` for multi-metric).
    * `rank`: array of ranks where 1 is best (or `rank_<name>`
      for multi-metric).
    * `fit_time`: array of wall-clock times.
    * `predictions`: object array of `MultiPeriodPortfolio` or `None`
      aligned with candidates (only when `return_predictions=True` and
      the estimator is portfolio-based).

  **best_estimator_** *BaseEstimator*
  : Estimator fitted on the full data with the best parameters.
    Only available when `refit` is not `False`.

  **best_score_** *float*
  : Aggregate score of the selected best candidate. Available when
    `best_index_` is defined and `refit` is not callable.

  **best_params_** *dict*
  : Parameter setting that gave the selected best score. Available when
    `best_index_` is defined.

  **best_index_** *int*
  : Index into `cv_results_` of the best candidate. Available for
    single-metric scoring and for multi-metric scoring when `refit` is
    not `False`.

  **multimetric_** *bool*
  : Whether or not the scorers compute several metrics.

  **is_portfolio_estimator_** *bool*
  : Whether or not the estimator is a portfolio optimization estimator.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch.fit)(X[, y])            | Run the online search over all candidate parameter combinations.   |
|-------------------------------------------------------------------------|--------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch.get_metadata_routing)() | Get metadata routing of this object.                               |
| [`get_params`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch.get_params)([deep])     | Get parameters for this estimator.                                 |
| [`predict`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch.predict)(X)             | Predict using the best estimator found during search.              |
| [`score`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch.score)(X[, y])          | Score using the best estimator found during search.                |
| [`set_params`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch.set_params)(\*\*params) | Set the parameters of this estimator.                              |

#### SEE ALSO
[Online Covariance Hyperparameter Tuning](https://skfolio.org/auto_examples/online_learning/plot_2_online_hyperparameter_tuning.html.md#sphx-glr-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py)
: Exhaustive online tuning of covariance estimator hyperparameters.

[Online Evaluation of Portfolio Optimization](https://skfolio.org/auto_examples/online_learning/plot_3_online_portfolio_optimization_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-3-online-portfolio-optimization-evaluation-py)
: Exhaustive online tuning of a `MeanRisk` estimator.

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.model_selection import OnlineGridSearch
>>> from skfolio.moments import EWCovariance, EWMu
>>> from skfolio.optimization import MeanRisk
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.prior import EmpiricalPrior
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(504)
>>>
>>> model = MeanRisk(
...     prior_estimator=EmpiricalPrior(
...         mu_estimator=EWMu(),
...         covariance_estimator=EWCovariance(),
...     ),
... )
>>> search = OnlineGridSearch(
...     model,
...     param_grid={
...         "prior_estimator__mu_estimator__half_life": [20, 40, 60],
...         "prior_estimator__covariance_estimator__half_life": [20, 40, 60],
...     },
...     warmup_size=252,
...     test_size=5,
...     n_jobs=-1,
... )
>>> search.fit(X)
OnlineGridSearch(...)
>>> search.best_params_
{'prior_estimator__covariance_estimator__half_life': 60,
 'prior_estimator__mu_estimator__half_life': 20}
>>> search.best_estimator_
MeanRisk(...)
```

<a id="skfolio.model_selection.OnlineGridSearch.fit"></a>

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

Run the online search over all candidate parameter combinations.

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

  **y** *array-like, optional*
  : Optional Target.

  **\*\*fit_params**
  : Additional parameters routed via metadata routing.
* **Returns:**
  self

<a id="skfolio.model_selection.OnlineGridSearch.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.model_selection.OnlineGridSearch.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.model_selection.OnlineGridSearch.predict"></a>

#### predict(X)

Predict using the best estimator found during search.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns.
* **Returns:**
  **prediction** *Portfolio | Population*

<a id="skfolio.model_selection.OnlineGridSearch.score"></a>

#### score(X, y=None)

Score using the best estimator found during search.

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

  **y** *Ignored*
  : Present for scikit-learn API compatibility.
* **Returns:**
  **score** *float*

<a id="skfolio.model_selection.OnlineGridSearch.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.

# generated/skfolio.model_selection.OnlineRandomizedSearch.html.md

<a id="skfolio-model-selection-onlinerandomizedsearch"></a>

# skfolio.model_selection.OnlineRandomizedSearch

<a id="skfolio.model_selection.OnlineRandomizedSearch"></a>

### *class* skfolio.model_selection.OnlineRandomizedSearch(estimator, param_distributions, \*, n_iter=10, scoring=None, warmup_size=252, test_size=1, freq=None, freq_offset=None, previous=False, purged_size=0, reduce_test=False, refit=True, random_state=None, error_score=nan, return_predictions=False, portfolio_params=None, entry_rebalancing_params=None, n_jobs=None, verbose=0)

Online randomized search on hyperparameters.

Each sampled parameter combination is evaluated by running a full online
walk-forward pass. Unlike [`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch), not all parameters are tried
out, but a fixed number of parameter settings are sampled from the specified
distributions. The number of parameter settings that are tried is given by `n_iter`.

If all parameters are presented as a list, sampling without replacement is
performed. If at least one parameter is given as a distribution, sampling with
replacement is used. It is highly recommended to use continuous distributions for
continuous parameters.

* **Parameters:**
  **estimator** *BaseEstimator*
  : Estimator that supports `partial_fit`.

  **param_distributions** *dict or list of dicts*
  : Dictionary with parameters names (`str`) as keys and distributions
    or lists of parameters to try. Distributions must provide a `rvs`
    method for sampling (such as those from scipy.stats.distributions).
    If a list is given, it is sampled uniformly.
    If a list of dicts is given, first a dict is sampled uniformly, and
    then a parameter is sampled using that dict as above.

  **n_iter** *int, default=10*
  : Number of parameter settings that are sampled. n_iter trades
    off runtime vs quality of the solution.

  **scoring** *callable, dict, BaseMeasure, or None*
  : Scoring specification. Semantics depend on the estimator type:
    * **Component estimators** (e.g. covariance, expected returns):
      `None` uses `estimator.score`; otherwise pass a callable
      `scorer(estimator, X_test)` or a dict of such callables.
    * **Portfolio optimization estimators**:
      a [`BaseMeasure`](https://skfolio.org/generated/skfolio.measures.BaseMeasure.html.md#skfolio.measures.BaseMeasure) or a dict of measures.
      `None` defaults to
      `SHARPE_RATIO`.
    <br/>
    For portfolio optimization estimators, online evaluation scores the
    aggregated out-of-sample
    [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio), rather than scoring
    each test window independently and averaging as in
    `GridSearchCV`. Pass the measure enum
    directly; `make_scorer` is not supported.

  **warmup_size** *int, default=252*
  : Number of initial observations (or periods when `freq` is set) used
    for the first `partial_fit` call.

  **test_size** *int, default=1*
  : Number of observations (or periods when `freq` is set) per test
    window.

  **freq** *str | pandas.offsets.BaseOffset, optional*
  : Rebalancing frequency. When provided, `warmup_size` and `test_size`
    are interpreted as period counts rather than observation counts, and
    `X` must be a DataFrame with a `DatetimeIndex`. See
    [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) for details and
    examples.

  **freq_offset** *pandas.offsets.BaseOffset | datetime.timedelta, optional*
  : Offset applied to the `freq` boundaries. Only used when `freq` is
    provided.

  **previous** *bool, default=False*
  : Only used when `freq` is provided. If `True`, period boundaries
    that fall between observations snap to the previous observation;
    otherwise they snap to the next.

  **purged_size** *int, default=0*
  : Number of observations (or periods) to skip between the last data the
    model sees and the start of the test window.

  **reduce_test** *bool, default=False*
  : If `True`, the last test window is included even when it contains
    fewer observations than `test_size`.

  **refit** *bool, str, or callable, default=True*
  : Controls how the best candidate is selected and whether the
    selected fitted candidate is exposed as `best_estimator_`.
    <br/>
    This parameter is named for API alignment with scikit-learn.
    Unlike scikit-learn search estimators, enabling `refit` does
    not trigger an additional fit after model selection because
    each candidate is already evaluated through a full online
    walk-forward pass and updated through the full sample.
    * Single-metric scoring: `True` or `False` are both supported.
      If `False`, `best_estimator_` is not stored, but
      `best_index_`, `best_params_`, and `best_score_` remain
      available.
    * Multi-metric scoring: set to a scorer name to select the best
      candidate for that metric, or to `False` to disable
      best-candidate selection and storage of `best_estimator_`.
    * A callable receives `cv_results_` and must return the best
      candidate index.

  **random_state** *int, RandomState instance, optional*
  : Pseudo random number generator state used for random uniform sampling
    from lists of possible values instead of scipy.stats distributions.
    Pass an int for reproducible output across multiple function calls.

  **error_score** *“raise” or float, default=np.nan*
  : Value to assign to the score if an error occurs during fitting.
    If set to `"raise"`, the error is raised.

  **return_predictions** *bool, default=False*
  : If `True`, store
    [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) objects per
    candidate in `cv_results_["predictions"]`. Only applies to
    portfolio optimization estimators.

  **portfolio_params** *dict, optional*
  : Portfolio parameters for the evaluation of each candidate parameter set.
    <br/>
    Parameters shared by [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) and
    [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) (`compounded`,
    `risk_free_rate`, `annualization_factor`, `fitness_measures` and the risk
    measure parameters) are applied to the `MultiPeriodPortfolio` scored for each
    parameter set and to each `Portfolio` it contains. A value passed here takes
    precedence over the optimizer’s `portfolio_params`. When omitted here, it is
    inherited from the optimizer’s `portfolio_params`. When omitted from both,
    `risk_free_rate` falls back to the optimizer’s `risk_free_rate` parameter when
    it has one. These parameters only affect how the portfolios are measured, not
    the optimization, so they can change the scores and the ranking of the
    parameter sets.
    <br/>
    `weight_drift` applies to each `Portfolio` of the path. With
    `weight_drift=True`, the weights held within each test window drift with the
    asset returns, and the path runs sequentially: the `ending_weights` of each
    portfolio are passed as `previous_weights` to the next update. A value passed
    here overrides the optimizer’s `portfolio_params`. When refitting is enabled,
    `weight_drift` is retained in `best_estimator_`. The other parameters are not.
    <br/>
    Optimizer parameters such as `transaction_costs`, `management_fees` and
    `previous_weights` are not accepted here. Set them on the optimizer.
    <br/>
    `name`, `tag`, `sample_weight` and `check_observations_order` apply to the
    scored `MultiPeriodPortfolio` only.

  **entry_rebalancing_params** *dict, optional*
  : Portfolio optimizer parameters applied only while constructing the first
    portfolio in the online path for each candidate parameter set. This is useful
    when the strategy starts with no existing position, while later portfolios
    represent regular rebalancing from the previously predicted weights. For
    example, the entry rebalancing can use lower `transaction_costs` or require a
    valid initial solution with `fallback=None`. Only supported for portfolio
    optimization estimators.

  **n_jobs** *int, optional*
  : Number of parallel jobs. `None` means 1.

  **verbose** *int, default=0*
  : Verbosity level for `joblib.Parallel`.
* **Attributes:**
  **cv_results_** *dict[str, ndarray]*
  : A dict with keys:
    * `params`: list of candidate parameter dicts.
    * `mean_score`: array of aggregate scores (or
      `mean_score_<name>` for multi-metric).
    * `rank`: array of ranks where 1 is best (or `rank_<name>`
      for multi-metric).
    * `fit_time`: array of wall-clock times.
    * `predictions`: object array of `MultiPeriodPortfolio` or `None`
      aligned with candidates (only when `return_predictions=True` and
      the estimator is portfolio-based).

  **best_estimator_** *BaseEstimator*
  : Estimator fitted on the full data with the best parameters.
    Only available when `refit` is not `False`.

  **best_score_** *float*
  : Aggregate score of the selected best candidate. Available when
    `best_index_` is defined and `refit` is not callable.

  **best_params_** *dict*
  : Parameter setting that gave the selected best score. Available when
    `best_index_` is defined.

  **best_index_** *int*
  : Index into `cv_results_` of the best candidate. Available for
    single-metric scoring and for multi-metric scoring when `refit` is
    not `False`.

  **multimetric_** *bool*
  : Whether or not the scorers compute several metrics.

  **is_portfolio_estimator_** *bool*
  : Whether or not the estimator is a portfolio optimization estimator.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch.fit)(X[, y])            | Run the online search over all candidate parameter combinations.   |
|-------------------------------------------------------------------------|--------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch.get_metadata_routing)() | Get metadata routing of this object.                               |
| [`get_params`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch.get_params)([deep])     | Get parameters for this estimator.                                 |
| [`predict`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch.predict)(X)             | Predict using the best estimator found during search.              |
| [`score`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch.score)(X[, y])          | Score using the best estimator found during search.                |
| [`set_params`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch.set_params)(\*\*params) | Set the parameters of this estimator.                              |

#### SEE ALSO
[Online Covariance Hyperparameter Tuning](https://skfolio.org/auto_examples/online_learning/plot_2_online_hyperparameter_tuning.html.md#sphx-glr-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py)
: Randomized online tuning of covariance estimator hyperparameters.

### Examples

```pycon
>>> from scipy.stats import uniform
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.model_selection import OnlineRandomizedSearch
>>> from skfolio.moments import EWCovariance, EWMu
>>> from skfolio.optimization import MeanRisk
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.prior import EmpiricalPrior
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(504)
>>>
>>> model = MeanRisk(
...     prior_estimator=EmpiricalPrior(
...         mu_estimator=EWMu(),
...         covariance_estimator=EWCovariance(),
...     ),
... )
>>> search = OnlineRandomizedSearch(
...     model,
...     param_distributions={
...         "prior_estimator__mu_estimator__half_life": uniform(10, 90),
...         "prior_estimator__covariance_estimator__half_life": uniform(10, 90),
...     },
...     n_iter=20,
...     warmup_size=252,
...     test_size=5,
...     n_jobs=-1,
...     random_state=42,
... )
>>> search.fit(X)
OnlineRandomizedSearch(...)
>>> search.best_params_
{'prior_estimator__covariance_estimator__half_life': 63.31...,
 'prior_estimator__mu_estimator__half_life': 14.18...}
>>> search.best_estimator_
MeanRisk(...)
```

<a id="skfolio.model_selection.OnlineRandomizedSearch.fit"></a>

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

Run the online search over all candidate parameter combinations.

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

  **y** *array-like, optional*
  : Optional Target.

  **\*\*fit_params**
  : Additional parameters routed via metadata routing.
* **Returns:**
  self

<a id="skfolio.model_selection.OnlineRandomizedSearch.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.model_selection.OnlineRandomizedSearch.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.model_selection.OnlineRandomizedSearch.predict"></a>

#### predict(X)

Predict using the best estimator found during search.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns.
* **Returns:**
  **prediction** *Portfolio | Population*

<a id="skfolio.model_selection.OnlineRandomizedSearch.score"></a>

#### score(X, y=None)

Score using the best estimator found during search.

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

  **y** *Ignored*
  : Present for scikit-learn API compatibility.
* **Returns:**
  **score** *float*

<a id="skfolio.model_selection.OnlineRandomizedSearch.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.

# generated/skfolio.model_selection.WalkForward.html.md

<a id="skfolio-model-selection-walkforward"></a>

# skfolio.model_selection.WalkForward

<a id="skfolio.model_selection.WalkForward"></a>

### *class* skfolio.model_selection.WalkForward(test_size, train_size, freq=None, freq_offset=None, previous=False, expand_train=False, reduce_test=False, purged_size=0)

Walk Forward Cross-Validator.

Provides train/test indices to split time series data samples using a walk-forward
logic.

In each split, test indices must be higher than the previous ones; therefore,
shuffling in cross-validator is inappropriate.

Compared to `sklearn.model_selection.TimeSeriesSplit`, you control the train/test
folds by specifying the number of training and test samples instead of the number
of splits, making it more suitable for portfolio cross-validation.

If your data is a DataFrame indexed with a DatetimeIndex, you can split the data
using specific datetime frequencies and offsets.

* **Parameters:**
  **test_size** *int*
  : Length of each test set.
    If `freq` is `None` (default), it represents the number of observations.
    Otherwise, it represents the number of periods defined by `freq`.

  **train_size** *int | pandas.offsets.DateOffset | datetime.timedelta*
  : Length of each training set.
    If `freq` is `None` (default), it represents the number of observations.
    Otherwise, for integers, it represents the number of periods defined by `freq`;
    for pandas DateOffset or datetime timedelta it represents the date offset
    applied to the start of each period.

  **freq** *str | pandas.offsets.DateOffset, optional*
  : If provided, it must be a frequency string or a pandas DateOffset, and the
    returns `X` must be a DataFrame with an index of type `DatetimeIndex`.
    For a list of pandas frequencies and offsets, see [here](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#timeseries-offset-aliases).
    The default (`None`) means `test_size` and `train_size` represent the number of
    observations.
    <br/>
    Below are some common examples:
    > * Rebalancing    : Monthly on the first day
    > * Test Duration  : 1 month
    > * Train Duration : 6 months
    <br/>
    > ```pycon
    > >>> cv = WalkForward(test_size=1, train_size=6, freq="MS")
    > ```
    <br/>
    > * Rebalancing    : Quarterly on the first day
    > * Test Duration  : 1 quarter
    > * Train Duration : 2 months
    <br/>
    > ```pycon
    > >>> cv = WalkForward(test_size=1, train_size=pd.DateOffset(months=2), freq="QS")
    > ```
    <br/>
    > * Rebalancing    : Monthly on the third Friday
    > * Test Duration  : 1 month
    > * Train Duration : 6 weeks
    <br/>
    > ```pycon
    > >>> cv = WalkForward(test_size=1, train_size=pd.offsets.Week(6), freq= "WOM-3FRI")
    > ```
    <br/>
    > * Rebalancing    : Semi-annually on the last day
    > * Test Duration  : 6 months
    > * Train Duration : 1 year
    <br/>
    > ```pycon
    > >>> cv = WalkForward(test_size=1, train_size=2, freq=pd.offsets.SemiMonthEnd())
    > ```
    <br/>
    > * Rebalancing    : Every 2 months on the second day
    > * Test Duration  : 2 months
    > * Train Duration : 6 months
    <br/>
    > ```pycon
    > >>> cv = WalkForward(test_size=2, train_size=6, freq="MS", freq_offset=dt.timedelta(days=2))
    > ```

  **freq_offset** *pandas DateOffset | datetime timedelta, optional*
  : Only used if `freq` is provided. Offsets the `freq` by a pandas DateOffset or a
    datetime timedelta offset.

  **previous** *bool, default=False*
  : Only used if `freq` is provided. If set to `True`, and if the period start
    or period end is not in the `DatetimeIndex`, the previous observation is used;
    otherwise, the next observation is used (default).

  **expand_train** *bool, default=False*
  : If set to `True`, each subsequent training set after the first one will
    use all past observations.
    The default is `False`.

  **reduce_test** *bool, default=False*
  : If set to `True`, the last train/test split will be returned even if the
    test set is partial (i.e., it contains fewer observations than `test_size`),
    otherwise, it will be ignored.
    The default is `False`.

  **purged_size** *int, default=0*
  : The number of observations to exclude from the end of each training set before
    the test set.
    The default value is `0`.
    <br/>
    #### WARNING
    **Execution timing and look-ahead control**
    <br/>
    With `purged_size=0`:
    : - Training ends at the current period and testing begins immediately.
      - Assumes you can observe, compute, and execute within the same period.
      - If observation/computation-to-execution latency is non-negligible
        (submission cutoffs, illiquidity, end-of-period finalization, or
        markets with no intraday quotation), results may be too optimistic.
    <br/>
    With `purged_size=1`:
    : - One observation is dropped between training and test.
      - Decisions made on the current period start affecting performance from
        the next period.
    <br/>
    Rules of thumb:
    : - Use `purged_size=0` only when you truly can execute at the same period
        with minimal latency.
      - Use `purged_size >= 1` when execution is delayed (daily-priced assets,
        illiquid markets, end-of-day data that settles after the close).

### Methods

| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward.get_metadata_routing)()       | Get metadata routing of this object.                              |
|-------------------------------------------------------------------------------|-------------------------------------------------------------------|
| [`get_n_splits`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward.get_n_splits)([X, y, groups]) | Return the number of splitting iterations in the cross-validator. |
| [`split`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward.split)(X[, y, groups])        | Generate indices to split data into training and test set.        |

### Examples

Tutorials using `WalkForward`:
: * [Custom Pre-selection Using Volumes](https://skfolio.org/auto_examples/pre_selection/plot_3_custom_pre_selection_volumes.html.md#sphx-glr-auto-examples-pre-selection-plot-3-custom-pre-selection-volumes-py)
  * [HRP vs HERC](https://skfolio.org/auto_examples/clustering/plot_3_hrp_vs_herc.html.md#sphx-glr-auto-examples-clustering-plot-3-hrp-vs-herc-py)
  * [L1 and L2 Regularization](https://skfolio.org/auto_examples/mean_risk/plot_8_regularization.html.md#sphx-glr-auto-examples-mean-risk-plot-8-regularization-py)
  * [NCO - Combinatorial Purged CV](https://skfolio.org/auto_examples/clustering/plot_5_nco_grid_search.html.md#sphx-glr-auto-examples-clustering-plot-5-nco-grid-search-py)
  * [Stacking Optimization](https://skfolio.org/auto_examples/ensemble/plot_1_stacking.html.md#sphx-glr-auto-examples-ensemble-plot-1-stacking-py)

```pycon
>>> import numpy as np
>>> from skfolio.datasets import load_sp500_dataset, load_factors_dataset
>>> from skfolio.model_selection import WalkForward
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> X = np.random.randn(6, 2) # 6 observations
>>> cv = WalkForward(test_size=1, train_size=2)
>>> for i, (train_index, test_index) in enumerate(cv.split(X)):
...     print(f"Fold {i}:")
...     print(f"  Train: index={train_index}")
...     print(f"  Test:  index={test_index}")
Fold 0:
  Train: index=[0 1]
  Test:  index=[2]
Fold 1:
  Train: index=[1 2]
  Test:  index=[3]
Fold 2:
  Train: index=[2 3]
  Test:  index=[4]
Fold 3:
  Train: index=[3 4]
  Test:  index=[5]
>>> cv = WalkForward(test_size=1, train_size=2, purged_size=1)
>>> for i, (train_index, test_index) in enumerate(cv.split(X)):
...     print(f"Fold {i}:")
...     print(f"  Train: index={train_index}")
...     print(f"  Test:  index={test_index}")
Fold 0:
  Train: index=[0 1]
  Test:  index=[3]
Fold 1:
  Train: index=[1 2]
  Test:  index=[4]
Fold 2:
  Train: index=[2 3]
  Test:  index=[5]
>>> cv = WalkForward(test_size=2, train_size=3)
>>> for i, (train_index, test_index) in enumerate(cv.split(X)):
...     print(f"Fold {i}:")
...     print(f"  Train: index={train_index}")
...     print(f"  Test:  index={test_index}")
Fold 0:
  Train: index=[0 1 2]
  Test:  index=[3 4]
>>> cv = WalkForward(test_size=2, train_size=3, reduce_test=True)
>>> for i, (train_index, test_index) in enumerate(cv.split(X)):
...     print(f"Fold {i}:")
...     print(f"  Train: index={train_index}")
...     print(f"  Test:  index={test_index}")
Fold 0:
  Train: index=[0 1 2]
  Test:  index=[3 4]
Fold 1:
  Train: index=[2 3 4]
  Test:  index=[5]
>>> cv = WalkForward(test_size=2, train_size=3, expand_train=True, reduce_test=True)
>>> for i, (train_index, test_index) in enumerate(cv.split(X)):
...     print(f"Fold {i}:")
...     print(f"  Train: index={train_index}")
...     print(f"  Test:  index={test_index}")
Fold 0:
  Train: index=[0 1 2]
  Test:  index=[3 4]
Fold 1:
  Train: index=[0 1 2 3 4]
  Test:  index=[5]
>>>
>>> # Time-based (calendar) rebalancing
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>> X = X["2021":"2022"]
>>> # Rebalance every 3 months on the third Friday, and train on the last 12 months.
>>> cv = WalkForward(test_size=3, train_size=12, freq="WOM-3FRI")
>>>
>>> for i, (train_index, test_index) in enumerate(cv.split(X)):
...     print(f"Fold {i}:")
...     print(f"  Train: size={len(train_index)}")
...     print(f"  Test:  size={len(test_index)}")
Fold 0:
  Train: size=256
  Test:  size=59
Fold 1:
  Train: size=253
  Test:  size=61
Fold 2:
  Train: size=251
  Test:  size=69
```

<a id="skfolio.model_selection.WalkForward.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.model_selection.WalkForward.get_n_splits"></a>

#### get_n_splits(X=None, y=None, groups=None)

Return the number of splitting iterations in the cross-validator.

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

  **y** *array-like of shape (n_observations, n_targets)*
  : Always ignored, exists for compatibility.

  **groups** *array-like of shape (n_observations,)*
  : Always ignored, exists for compatibility.
* **Returns:**
  **n_folds** *int*
  : Returns the number of splitting iterations in the cross-validator.
* **Raises:**
  ValueError
  : If `X` is `None`, if a window size has an invalid type, if a training or
    test window size is not positive, or if `purged_size` is not a
    non-negative integer.

<a id="skfolio.model_selection.WalkForward.split"></a>

#### split(X, y=None, groups=None)

Generate indices to split data into training and test set.

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

  **y** *array-like of shape (n_observations, n_targets)*
  : Always ignored, exists for compatibility.

  **groups** *array-like of shape (n_observations,)*
  : Always ignored, exists for compatibility.
* **Yields:**
  **train** *ndarray*
  : The training set indices for that split.

  **test** *ndarray*
  : The testing set indices for that split.
* **Raises:**
  ValueError
  : If a window size has an invalid type, if a training or test window size
    is not positive, or if `purged_size` is not a non-negative integer.

# generated/skfolio.model_selection.covariance_forecast_evaluation.html.md

<a id="skfolio-model-selection-covariance-forecast-evaluation"></a>

# skfolio.model_selection.covariance_forecast_evaluation

<a id="skfolio.model_selection.covariance_forecast_evaluation"></a>

### skfolio.model_selection.covariance_forecast_evaluation(estimator, X, y=None, train_size=252, test_size=1, expand_train=False, portfolio_weights=None, purged_size=0, params=None)

Evaluate out-of-sample covariance forecast quality using walk-forward
cross-validation.

At each fold the estimator is fitted from scratch on the training window
and the fitted covariance is evaluated against the next `test_size`
observations. This is the batch counterpart of
[`online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation),
which instead updates the estimator incrementally via `partial_fit`.

The walk-forward scheme is controlled by `train_size` and
`expand_train`, mirroring the semantics of
[`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward):

* `expand_train=False` (default): rolling window of fixed `train_size`.
* `expand_train=True`: expanding window starting from the first `train_size`
  observations.

Every evaluation window contains exactly `test_size` observations, ensuring that
diagnostics (in particular QLIKE) are directly comparable across folds.

Four core diagnostics are computed:

* **Mahalanobis calibration ratio**: tests whether the full covariance
  structure (all eigenvalue directions) is correctly specified. The
  target is 1.0. A value above 1.0 indicates underestimated risk;
  below 1.0 indicates overestimated risk.
* **Diagonal calibration ratio**: tests whether the individual asset
  variances are correctly specified, ignoring correlations. The target
  is 1.0. A value above 1.0 indicates underestimated volatilities;
  below 1.0 indicates overestimated volatilities.
* **Portfolio standardized returns / bias statistic**: tests whether
  the covariance is well calibrated along one or more portfolio
  directions.
* **Portfolio QLIKE**: evaluates portfolio variance forecasts along
  one or more portfolio directions by comparing the forecast portfolio
  variance with the realized sum of squared portfolio returns over the
  evaluation window. Lower values indicate better portfolio variance
  forecasts.

When the test returns contain NaNs (e.g. holidays, pre-listing, or post-delisting
periods), only finite observations contribute to the aggregated return. For
portfolio diagnostics, NaN returns for active assets contribute zero to the realized
portfolio return and the forecast covariance is scaled by the pairwise observation
count matrix $H$ (Hadamard product $H \odot \Sigma$) so that the
realized portfolio variance and forecast variance follow the same missing-data
convention. In skfolio, NaN diagonal entries in the forecast covariance mark
inactive assets, which are excluded from the evaluation.

* **Parameters:**
  **estimator** *BaseEstimator or Pipeline*
  : Fitted estimator or Pipeline. Must expose `covariance_` or
    `return_distribution_.covariance` after fitting.

  **X** *array-like of shape (n_observations, n_assets)*
  : Asset returns.

  **y** *Ignored*
  : Present for scikit-learn API compatibility.

  **train_size** *int, default=252*
  : Number of observations in each training window (rolling or initial expanding
    window size).

  **test_size** *int, default=1*
  : Number of observations per evaluation window. All windows have exactly this many
    observations.

  **expand_train** *bool, default=False*
  : If `True`, each subsequent training window includes all past observations
    (expanding window). If `False`, a rolling window of fixed `train_size` is used.

  **portfolio_weights** *array-like of shape (n_assets,) or (n_portfolios, n_assets), optional*
  : Portfolio weights for portfolio-level diagnostics (bias statistic and QLIKE).
    <br/>
    If `None` (default), inverse-volatility weights are used, recomputed dynamically
    at each step from the forecast covariance. This neutralizes volatility
    dispersion so that high-volatility assets do not dominate the diagnostic.
    <br/>
    If a 1D array is provided, a single static portfolio is used.
    <br/>
    If a 2D array of shape `(n_portfolios, n_assets)` is provided, each row defines
    a test portfolio and diagnostics are computed independently for each.
    <br/>
    For equal-weight calibration, pass `portfolio_weights=np.ones(n_assets) / n_assets`.

  **purged_size** *int, default=0*
  : Number of observations to skip between training and test data.

  **params** *dict, optional*
  : Parameters routed to the estimator’s `fit` via metadata routing.
* **Returns:**
  **evaluation** *CovarianceForecastEvaluation*
  : Frozen dataclass with per-step calibration arrays, summary statistics, and
    plotting methods.
* **Raises:**
  ValueError
  : If the data is too short for at least one evaluation fold.

#### SEE ALSO
[`online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation)
: Online counterpart that updates the estimator incrementally via `partial_fit`.

[`CovarianceForecastEvaluation`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation)
: Result dataclass with summary statistics and plotting methods.

[`CovarianceForecastComparison`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison)
: Compare multiple evaluation results side by side with combined summary tables and overlay plots.

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.model_selection import covariance_forecast_evaluation
>>> from skfolio.moments import LedoitWolf
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(504)
>>> evaluation = covariance_forecast_evaluation(
...     LedoitWolf(),
...     X,
...     train_size=252,
...     test_size=5,
... )
>>> evaluation.summary()
                                    mean  ...           target
Mahalanobis ratio                1.169...  ...              1.0
Diagonal ratio                  1.313...  ...              1.0
Portfolio standardized returns  0.028...  ...    mean=0, std=1
Portfolio QLIKE                -6.082...  ...  lower is better

[4 rows x 7 columns]
>>> evaluation.bias_statistic
array([1.380...])
>>> evaluation.plot_calibration()
Figure(...)
```

# generated/skfolio.model_selection.cross_val_predict.html.md

<a id="skfolio-model-selection-cross-val-predict"></a>

# skfolio.model_selection.cross_val_predict

<a id="skfolio.model_selection.cross_val_predict"></a>

### skfolio.model_selection.cross_val_predict(estimator, X, y=None, cv=None, n_jobs=None, method='predict', verbose=0, params=None, pre_dispatch='2\*n_jobs', column_indices=None, portfolio_params=None, entry_rebalancing_params=None)

Generate cross-validated `Portfolios` estimates.

The data is split according to the `cv` parameter.
The optimization estimator is fitted on the training set and portfolios are
predicted on the corresponding test set.

For single-path cross-validation such as `KFold` or
[`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward), the output is a
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) where each
[`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) corresponds to a train/test split (`k`
portfolios for `KFold`).

For multi-path cross-validation such as
[`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) or
[`MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV), the output is a
[`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population) of multiple
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) objects (each test produces a
collection of paths rather than a single path).

If the final estimator in the pipeline (or the estimator itself) declares
`needs_previous_weights=True`, this function automatically propagates
`previous_weights` from one fold to the next for sequential CV strategies
(e.g., `WalkForward` or `MultipleRandomizedCV`).

* **Parameters:**
  **estimator** *BaseEstimator | Pipeline*
  : Portfolio optimization estimator or pipeline whose last step is an optimization
    estimator.

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

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Target data (optional).
    For example, the price returns of the factors.

  **cv** *int | cross-validation generator, optional*
  : Determines the cross-validation splitting strategy.
    Possible inputs for cv are:
    * None, to use the default 5-fold cross validation,
    * int, to specify the number of folds in a `(Stratified)KFold`,
    * `CV splitter`,
    * An iterable that generates (train, test) splits as arrays of indices.

  **n_jobs** *int, optional*
  : The number of jobs to run in parallel for `fit` of all `estimators`.
    `None` means 1 unless in a `joblib.parallel_backend` context. -1 means
    using all processors.

  **method** *str*
  : Invokes the passed method name of the passed estimator.

  **verbose** *int, default=0*
  : The verbosity level.

  **params** *dict, optional*
  : Parameters to pass to the underlying estimator’s `fit` and the CV splitter.

  **pre_dispatch** *int or str, default=’2\*n_jobs’*
  : Controls the number of jobs that get dispatched during parallel
    execution. Reducing this number can be useful to avoid an
    explosion of memory consumption when more jobs get dispatched
    than CPUs can process. This parameter can be:
    > * None, in which case all the jobs are immediately
    >   created and spawned. Use this for lightweight and
    >   fast-running jobs, to avoid delays due to on-demand
    >   spawning of the jobs
    > * An int, giving the exact number of total jobs that are
    >   spawned
    > * A str, giving an expression as a function of n_jobs,
    >   as in ‘2\*n_jobs’

  **column_indices** *ndarray, optional*
  : Indices of the `X` columns to cross-validate on.

  **portfolio_params** *dict, optional*
  : Portfolio parameters for the evaluation.
    <br/>
    Parameters shared by `Portfolio` and `MultiPeriodPortfolio` (`compounded`,
    `risk_free_rate`, `annualization_factor`, `fitness_measures` and the risk
    measure parameters) are applied to the returned `MultiPeriodPortfolio` and to
    each `Portfolio` it contains. A value passed here takes precedence over the
    optimizer’s `portfolio_params`. When omitted here, it is inherited from the
    optimizer’s `portfolio_params`. When omitted from both, `risk_free_rate` falls
    back to the optimizer’s `risk_free_rate` parameter when it has one. These
    parameters only affect how the portfolios are measured, not the optimization.
    <br/>
    `weight_drift` applies to each `Portfolio` of the path. With
    `weight_drift=True`, the weights held within each test window drift with the
    asset returns, and the path runs sequentially: the `ending_weights` of each
    portfolio are passed as `previous_weights` to the next fit. A value passed here
    overrides the optimizer’s `portfolio_params`.
    <br/>
    Optimizer parameters such as `transaction_costs`, `management_fees` and
    `previous_weights` are not accepted here. Set them on the optimizer.
    <br/>
    `name`, `tag`, `sample_weight` and `check_observations_order` apply to the
    returned `MultiPeriodPortfolio` only.

  **entry_rebalancing_params** *dict, optional*
  : Portfolio optimizer parameters applied only while constructing the first
    portfolio of each sequential path. This is useful when the strategy starts with
    no existing position, while later portfolios represent regular rebalancing from
    the previously predicted weights. For example, the entry rebalancing can relax
    `max_turnover` or use lower `transaction_costs` to avoid a slow ramp from cash
    caused by recurring rebalancing constraints. The first portfolio is included in
    the result. The regular optimizer parameters are used for all subsequent
    optimizations. When provided, `cross_val_predict` evaluates a sequential
    strategy path and propagates `previous_weights` between portfolios. This is only
    supported for sequential CV strategies such as
    [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward),
    `TimeSeriesSplit` and
    [`MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV).
* **Returns:**
  **predictions** *MultiPeriodPortfolio | Population*
  : This is the result of calling `predict`

### Notes

With a sequential CV, each portfolio’s `ending_weights` are passed as
`previous_weights` to the next fit when the estimator needs them. Otherwise,
fits remain independent and previous weights are assigned to the predicted
portfolios afterward for turnover and cost calculations. Ending weights equal
the target `weights` when `weight_drift=False` and the weights after the last
observation when `weight_drift=True`. Failed and empty portfolios are skipped
when propagating holdings. With a non-sequential CV, drift is applied inside
each test fold and nothing is propagated.

# generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md

<a id="skfolio-model-selection-online-covariance-forecast-evaluation"></a>

# skfolio.model_selection.online_covariance_forecast_evaluation

<a id="skfolio.model_selection.online_covariance_forecast_evaluation"></a>

### skfolio.model_selection.online_covariance_forecast_evaluation(estimator, X, y=None, warmup_size=252, test_size=1, portfolio_weights=None, purged_size=0, params=None)

Evaluate out-of-sample covariance forecast quality.

Walks forward through the data using incremental learning and computes per-step
calibration diagnostics comparing the covariance forecast to realized returns.

At each step the estimator is updated via `partial_fit` and the fitted covariance is
evaluated against the next `test_size` observations. This is the online counterpart
of [`covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.covariance_forecast_evaluation.html.md#skfolio.model_selection.covariance_forecast_evaluation), which instead
refits the estimator from scratch on each training window.

Every evaluation window contains exactly `test_size` observations, ensuring that
diagnostics (in particular QLIKE) are directly comparable across steps.

Four core diagnostics are computed:

* **Mahalanobis calibration ratio**: tests whether the full covariance
  structure (all eigenvalue directions) is correctly specified. The
  target is 1.0. A value above 1.0 indicates underestimated risk;
  below 1.0 indicates overestimated risk.
* **Diagonal calibration ratio**: tests whether the individual asset
  variances are correctly specified, ignoring correlations. The target
  is 1.0. A value above 1.0 indicates underestimated volatilities;
  below 1.0 indicates overestimated volatilities.
* **Portfolio standardized returns / bias statistic**: tests whether
  the covariance is well calibrated along one or more portfolio
  directions.
* **Portfolio QLIKE**: evaluates portfolio variance forecasts along
  one or more portfolio directions by comparing the forecast portfolio
  variance with the realized sum of squared portfolio returns over the
  evaluation window. Lower values indicate better portfolio variance
  forecasts.

When the test returns contain NaNs (e.g. holidays, pre-listing, or post-delisting
periods), only finite observations contribute to the aggregated return. For
portfolio diagnostics, NaN returns for active assets contribute zero to the realized
portfolio return and the forecast covariance is scaled by the pairwise observation
count matrix $H$ (Hadamard product $H \odot \Sigma$) so that the
realized portfolio variance and forecast variance follow the same missing-data
convention. In skfolio, NaN diagonal entries in the forecast covariance mark
inactive assets, which are excluded from the evaluation.

* **Parameters:**
  **estimator** *BaseEstimator or Pipeline*
  : Fitted estimator or Pipeline. Must expose `covariance_` or
    `return_distribution_.covariance` after fitting.

  **X** *array-like of shape (n_observations, n_assets)*
  : Asset returns.

  **y** *Ignored*
  : Present for scikit-learn API compatibility.

  **warmup_size** *int, default=252*
  : Number of initial observations used for the first `partial_fit` call.

  **test_size** *int, default=1*
  : Number of observations per evaluation window. All windows have exactly this many
    observations.

  **portfolio_weights** *array-like of shape (n_assets,) or (n_portfolios, n_assets), optional*
  : Portfolio weights for portfolio-level diagnostics (bias statistic and QLIKE).
    <br/>
    If `None` (default), inverse-volatility weights are used, recomputed dynamically
    at each step from the forecast covariance. This neutralizes volatility
    dispersion so that high-volatility assets do not dominate the diagnostic.
    <br/>
    If a 1D array is provided, a single static portfolio is used.
    <br/>
    If a 2D array of shape `(n_portfolios, n_assets)` is provided, each row defines
    a test portfolio and diagnostics are computed independently for each.
    <br/>
    For equal-weight calibration, pass `portfolio_weights=np.ones(n_assets) / n_assets`.

  **purged_size** *int, default=0*
  : Number of observations to skip between training and test data.

  **params** *dict, optional*
  : Parameters routed to the estimator’s `partial_fit` via metadata routing.
* **Returns:**
  **evaluation** *CovarianceForecastEvaluation*
  : Frozen dataclass with per-step calibration arrays, summary statistics, and
    plotting methods.
* **Raises:**
  TypeError
  : If the estimator does not support `partial_fit`.

  ValueError
  : If the data is too short for at least one evaluation step.

#### SEE ALSO
[`covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.covariance_forecast_evaluation.html.md#skfolio.model_selection.covariance_forecast_evaluation)
: Batch counterpart that refits the estimator from scratch on each training window.

[`CovarianceForecastEvaluation`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation)
: Result dataclass with summary statistics and plotting methods.

[Online Covariance Forecast Evaluation](https://skfolio.org/auto_examples/online_learning/plot_1_online_covariance_forecast_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-1-online-covariance-forecast-evaluation-py)
: End-to-end covariance forecast evaluation tutorial.

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.model_selection import (
...     online_covariance_forecast_evaluation,
... )
>>> from skfolio.moments import EWCovariance
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(504)
>>> evaluation = online_covariance_forecast_evaluation(
...     EWCovariance(half_life=60),
...     X,
...     warmup_size=252,
...     test_size=5,
... )
>>> evaluation.summary()
                                    mean  ...           target
Mahalanobis ratio               1.353...  ...              1.0
Diagonal ratio                  1.199...  ...              1.0
Portfolio standardized returns  0.027...  ...    mean=0, std=1
Portfolio QLIKE                -6.260...  ...  lower is better

[4 rows x 7 columns]
>>> evaluation.bias_statistic
array([1.224...])
>>> evaluation.plot_calibration()
Figure(...)
```

# generated/skfolio.model_selection.online_predict.html.md

<a id="skfolio-model-selection-online-predict"></a>

# skfolio.model_selection.online_predict

<a id="skfolio.model_selection.online_predict"></a>

### skfolio.model_selection.online_predict(estimator, X, y=None, warmup_size=252, test_size=1, freq=None, freq_offset=None, previous=False, purged_size=0, reduce_test=False, params=None, portfolio_params=None, entry_rebalancing_params=None)

Generate out-of-sample portfolios using online learning.

Walks forward through the data, updating the estimator incrementally via
`partial_fit` and predicting on each subsequent test window. Unlike
[`cross_val_predict`](https://skfolio.org/generated/skfolio.model_selection.cross_val_predict.html.md#skfolio.model_selection.cross_val_predict), which clones the estimator for
each fold, this function maintains a single stateful estimator that accumulates
knowledge over time.

The algorithm:

1. Clone the estimator to ensure a clean, unfitted starting state.
2. Initialize the estimator on the first `warmup_size` observations via `partial_fit`.
3. At each step, predict on the test window, then update the model with the newly
   observed data via `partial_fit`.

If the estimator declares `needs_previous_weights=True`, portfolio weights are
automatically propagated from one step to the next.

* **Parameters:**
  **estimator** *BaseOptimization*
  : Portfolio optimization estimator. It must implement `partial_fit`.
    Pipelines are not supported.

  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. Must be a DataFrame with a `DatetimeIndex` when
    `freq` is provided.

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Target data to pass to `partial_fit`.

  **warmup_size** *int, default=252*
  : Number of initial observations (or periods when `freq` is set) used for the
    first `partial_fit` call. No predictions are made during warmup.

  **test_size** *int, default=1*
  : Length of each test set.
    If `freq` is `None` (default), it represents the number of observations.
    Otherwise, it represents the number of periods defined by `freq`. Controls the
    rebalancing frequency.

  **freq** *str | pandas.offsets.BaseOffset, optional*
  : If provided, it must be a frequency string or a pandas DateOffset, and `X` must
    be a DataFrame with an index of type `DatetimeIndex`. In that case,
    `warmup_size` and `test_size` represent the number of periods defined by `freq`
    instead of the number of observations.

  **freq_offset** *pandas.offsets.BaseOffset | datetime.timedelta, optional*
  : Only used if `freq` is provided. Offsets `freq` by a pandas DateOffset or a
    datetime timedelta offset.

  **previous** *bool, default=False*
  : Only used if `freq` is provided. If set to `True`, and if the period start or
    period end is not in the `DatetimeIndex`, the previous observation is used;
    otherwise, the next observation is used.

  **purged_size** *int, default=0*
  : The number of observations to exclude from the end of each training window
    before the test window. Use `purged_size >= 1` when execution is delayed
    relative to observation.

  **reduce_test** *bool, default=False*
  : If set to `True`, the last test window is returned even if it is partial,
    otherwise it is ignored.

  **params** *dict, optional*
  : Parameters to pass to the underlying estimator’s `partial_fit` through metadata
    routing.

  **portfolio_params** *dict, optional*
  : Portfolio parameters for the evaluation.
    <br/>
    Parameters shared by [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) and
    [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) (`compounded`,
    `risk_free_rate`, `annualization_factor`, `fitness_measures` and the risk
    measure parameters) are applied to the returned `MultiPeriodPortfolio` and to
    each `Portfolio` it contains. A value passed here takes precedence over the
    optimizer’s `portfolio_params`. When omitted here, it is inherited from the
    optimizer’s `portfolio_params`. When omitted from both, `risk_free_rate` falls
    back to the optimizer’s `risk_free_rate` parameter when it has one. These
    parameters only affect how the portfolios are measured, not the optimization.
    <br/>
    `weight_drift` applies to each `Portfolio` of the path. With
    `weight_drift=True`, the weights held within each test window drift with the
    asset returns, and the path runs sequentially: the `ending_weights` of each
    portfolio are passed as `previous_weights` to the next update. A value passed
    here overrides the optimizer’s `portfolio_params`.
    Failed and empty portfolios do not update the previous holdings.
    <br/>
    Optimizer parameters such as `transaction_costs`, `management_fees` and
    `previous_weights` are not accepted here. Set them on the optimizer.
    <br/>
    `name`, `tag`, `sample_weight` and `check_observations_order` apply to the
    returned `MultiPeriodPortfolio` only.

  **entry_rebalancing_params** *dict, optional*
  : Portfolio optimizer parameters applied only while constructing the first
    portfolio. This is useful when the strategy starts with no existing position,
    while later portfolios represent regular rebalancing from the previously
    predicted weights. For example, the entry rebalancing can relax `max_turnover`
    or use lower `transaction_costs` to avoid a slow ramp from cash caused by
    recurring rebalancing constraints. The first portfolio is included in the
    result. The regular optimizer parameters are restored before the next online
    update.
* **Returns:**
  **prediction** *MultiPeriodPortfolio*
  : A [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) containing one
    [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) per test window, ordered chronologically.
* **Raises:**
  TypeError
  : If the estimator is not a portfolio optimization estimator, does not
    implement `partial_fit`, or is a pipeline.

  ValueError
  : If `warmup_size < 1`, `test_size < 1`, or the data is too short for at least one
    test window.

#### SEE ALSO
[Online Evaluation of Portfolio Optimization](https://skfolio.org/auto_examples/online_learning/plot_3_online_portfolio_optimization_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-3-online-portfolio-optimization-evaluation-py)
: Online evaluation of portfolio optimization using `online_predict`.

### Notes

When the estimator needs previous weights, each portfolio’s `ending_weights` are
passed as `previous_weights` to the next update. Otherwise, previous weights are
assigned to the predicted portfolios afterward for turnover and cost calculations.
Ending weights equal the target `weights` when `weight_drift=False` and the
weights after the last observation when `weight_drift=True`. Failed and empty
portfolios are skipped when propagating holdings, preserving the last valid weights.

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.model_selection import online_predict
>>> from skfolio.moments import EWCovariance, EWMu
>>> from skfolio.optimization import MeanRisk
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.prior import EmpiricalPrior
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(504)
>>>
>>> model = MeanRisk(
...     prior_estimator=EmpiricalPrior(
...         mu_estimator=EWMu(half_life=40),
...         covariance_estimator=EWCovariance(half_life=40),
...     ),
... )
>>> pred = online_predict(model, X, warmup_size=252, test_size=5)
```

# generated/skfolio.model_selection.online_score.html.md

<a id="skfolio-model-selection-online-score"></a>

# skfolio.model_selection.online_score

<a id="skfolio.model_selection.online_score"></a>

### skfolio.model_selection.online_score(estimator, X, y=None, warmup_size=252, test_size=1, freq=None, freq_offset=None, previous=False, purged_size=0, reduce_test=False, scoring=None, params=None, per_step=False, portfolio_params=None, entry_rebalancing_params=None)

Score an online estimator using walk-forward evaluation.

Walks forward through the data, updating the estimator incrementally via
`partial_fit` and scoring on each subsequent test window. This is the scoring
counterpart of [`online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict).

The function handles both *non-predictor estimators* (e.g. covariance, expected
returns, prior) and *portfolio optimization* estimators:

* **non-predictor estimators** are scored on each test window independently.
  By default the average of per-step scores is returned.
* **Portfolio optimization estimators** are evaluated by collecting out-of-sample
  predictions into a [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) and computing
  the requested measure on the full multi-period portfolio.

* **Parameters:**
  **estimator** *BaseEstimator*
  : Estimator instance to use to fit the data. It must implement `partial_fit`.
    Pipelines are not supported.

  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. Must be a DataFrame with a `DatetimeIndex` when
    `freq` is provided.

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Target data to pass to `partial_fit`.

  **warmup_size** *int, default=252*
  : Number of initial observations (or periods when `freq` is set) used for the
    first `partial_fit` call. No scores are produced during warmup.

  **test_size** *int, default=1*
  : Length of each test set.
    If `freq` is `None` (default), it represents the number of observations.
    Otherwise, it represents the number of periods defined by `freq`.

  **freq** *str | pandas.offsets.BaseOffset, optional*
  : If provided, it must be a frequency string or a pandas DateOffset, and `X` must
    be a DataFrame with an index of type `DatetimeIndex`. In that case,
    `warmup_size` and `test_size` represent the number of periods defined by `freq`
    instead of the number of observations.

  **freq_offset** *pandas.offsets.BaseOffset | datetime.timedelta, optional*
  : Only used if `freq` is provided. Offsets `freq` by a pandas DateOffset or a
    datetime timedelta offset.

  **previous** *bool, default=False*
  : Only used if `freq` is provided. If set to `True`, and if the period start or
    period end is not in the `DatetimeIndex`, the previous observation is used;
    otherwise, the next observation is used.

  **purged_size** *int, default=0*
  : The number of observations to exclude from the end of each training
    window before the test window.

  **reduce_test** *bool, default=False*
  : If set to `True`, the last test window is returned even if it is partial,
    otherwise it is ignored.

  **scoring** *callable, dict, BaseMeasure, or None*
  : Scoring specification. Semantics depend on the estimator type:
    * **Non-predictor estimators** (e.g. covariance, expected returns, prior):
      `None` uses `estimator.score`; otherwise pass a callable
      scorer(estimator, X_test)\` or a dict of such callables.
    * **Portfolio optimization estimators**:
      a [`BaseMeasure`](https://skfolio.org/generated/skfolio.measures.BaseMeasure.html.md#skfolio.measures.BaseMeasure) or a dict of measures. `None`
      defaults to `SHARPE_RATIO`.
    <br/>
    #### NOTE
    For portfolio optimization estimators, online evaluation scores the
    aggregated out-of-sample [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio),
    rather than scoring each test window independently and averaging as in
    `GridSearchCV`. Pass the measure enum
    directly; `make_scorer` is not supported.

  **params** *dict, optional*
  : Parameters to pass to the underlying estimator’s `partial_fit`
    through metadata routing.

  **per_step** *bool, default=False*
  : If `True`, return per-step score arrays instead of aggregated
    scalars. Only supported for non-predictor estimators; raises
    `ValueError` for portfolio optimization estimators.

  **portfolio_params** *dict, optional*
  : Portfolio parameters for the evaluation of a portfolio optimizer.
    <br/>
    Parameters shared by [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) and
    [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) (`compounded`,
    `risk_free_rate`, `annualization_factor`, `fitness_measures` and the risk
    measure parameters) are applied to the scored `MultiPeriodPortfolio` and to
    each `Portfolio` it contains. A value passed here takes precedence over the
    optimizer’s `portfolio_params`. When omitted here, it is inherited from the
    optimizer’s `portfolio_params`. When omitted from both, `risk_free_rate` falls
    back to the optimizer’s `risk_free_rate` parameter when it has one. These
    parameters only affect how the portfolios are measured, not the optimization,
    so they can change the score.
    <br/>
    `weight_drift` applies to each `Portfolio` of the path. With
    `weight_drift=True`, the weights held within each test window drift with the
    asset returns, and the path runs sequentially: the `ending_weights` of each
    portfolio are passed as `previous_weights` to the next update. A value passed
    here overrides the optimizer’s `portfolio_params`.
    Failed and empty portfolios do not update the previous holdings.
    <br/>
    Optimizer parameters such as `transaction_costs`, `management_fees` and
    `previous_weights` are not accepted here. Set them on the optimizer.
    <br/>
    `name`, `tag`, `sample_weight` and `check_observations_order` apply to the
    scored `MultiPeriodPortfolio` only.

  **entry_rebalancing_params** *dict, optional*
  : Portfolio optimizer parameters applied only while constructing its first
    portfolio. This is useful when the strategy starts with no existing position,
    while later portfolios represent regular rebalancing from the previously
    predicted weights. For example, the entry rebalancing can relax `max_turnover`
    or use lower `transaction_costs` to avoid a slow ramp from cash caused by
    recurring rebalancing constraints. The regular optimizer parameters are
    restored before the next online update.
* **Returns:**
  **score** *float | dict[str, float] | ndarray | dict[str, ndarray]*
  : By default, an aggregate `float` (or `dict` for multi-metric).
    When `per_step=True`, a `FloatArray` of per-step scores (or
    `dict` thereof).
* **Raises:**
  TypeError
  : If the estimator does not implement `partial_fit` or is a pipeline.

  ValueError
  : If `per_step=True` is used with a portfolio optimization estimator,
    or if `warmup_size < 1`, `test_size < 1`, or the data is too
    short for at least one test window.

#### SEE ALSO
[Online Covariance Hyperparameter Tuning](https://skfolio.org/auto_examples/online_learning/plot_2_online_hyperparameter_tuning.html.md#sphx-glr-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py)
: Programmatic comparison of covariance estimators with `online_score`.

[Online Evaluation of Portfolio Optimization](https://skfolio.org/auto_examples/online_learning/plot_3_online_portfolio_optimization_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-3-online-portfolio-optimization-evaluation-py)
: Portfolio-level evaluation with `online_score`.

### Examples

non-predictor estimator (default `estimator.score`):

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.model_selection import online_score
>>> from skfolio.moments import EWCovariance
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(504)
>>> score = online_score(EWCovariance(), X, warmup_size=252)
```

Portfolio optimization estimator:

```pycon
>>> from skfolio.measures import RatioMeasure
>>> from skfolio.moments import EWMu
>>> from skfolio.optimization import MeanRisk
>>> from skfolio.prior import EmpiricalPrior
>>>
>>> model = MeanRisk(
...     prior_estimator=EmpiricalPrior(
...         mu_estimator=EWMu(half_life=40),
...         covariance_estimator=EWCovariance(half_life=40),
...     ),
... )
>>> score = online_score(
...     model,
...     X,
...     warmup_size=252,
...     test_size=5,
...     scoring=RatioMeasure.SHARPE_RATIO,
... )
```

# generated/skfolio.model_selection.optimal_folds_number.html.md

<a id="skfolio-model-selection-optimal-folds-number"></a>

# skfolio.model_selection.optimal_folds_number

<a id="skfolio.model_selection.optimal_folds_number"></a>

### skfolio.model_selection.optimal_folds_number(n_observations, target_train_size, target_n_test_paths, weight_train_size=1, weight_n_test_paths=1)

Find the optimal number of folds (total folds and test folds) for a target
training size and a target number of test paths.

We find `x = n_folds` and `y = n_test_folds` that minimizes the below
cost function of the relative distance from the two targets:

$$
cost(x,y) = w_{f} \times \lvert\frac{f(x,y)-f_{target}}{f_{target}}\rvert + w_{g} \times \lvert\frac{g(x,y)-g_{target}}{g_{target}}\rvert

$$

with $w_{f}$ and $w_{g}$ the weights assigned to the distance
from each target and $f(x,y)$ and $g(x,y)$ the average training size
and the number of test paths as a function of the number of total folds and test
folds.

This is a combinatorial problem with $\frac{T\times(T-3)}{2}$ combinations,
with $T$ the number of observations.

We reduce the search space by using the combinatorial symmetry
${n \choose k}={n \choose n-k}$ and skipping cost computation above 1e5.

* **Parameters:**
  **n_observations** *int*
  : Number of observations.

  **target_train_size** *int*
  : The target number of observation in the training set.

  **target_n_test_paths** *int*
  : The target number of test paths (that can be reconstructed from the train/test
    combinations).

  **weight_train_size** *float, default=1*
  : The weight assigned to the distance from the target train size.
    The default value is 1.

  **weight_n_test_paths** *float, default=1*
  : The weight assigned to the distance from the target number of test paths.
    The default value is 1.
* **Returns:**
  **n_folds** *int*
  : Optimal number of total folds.

  **n_test_folds** *int*
  : Optimal number of test folds.

# generated/skfolio.moments.BaseCovariance.html.md

<a id="skfolio-moments-basecovariance"></a>

# skfolio.moments.BaseCovariance

<a id="skfolio.moments.BaseCovariance"></a>

### *class* skfolio.moments.BaseCovariance(assume_centered=False, nearest=True, higham=False, higham_max_iteration=100)

Base class for all covariance estimators in `skfolio`.

* **Parameters:**
  **assume_centered** *bool, default=False*
  : If False (default), the data are mean-centered before computing the covariance.
    This is the standard behavior when working with raw returns where the mean is
    not guaranteed to be zero. If True, the estimator assumes the input data are
    already centered. Use this when you know the returns have zero mean, such as
    pre-demeaned data or regression residuals.

  **nearest** *bool, default=True*
  : If this is set to True, the covariance is replaced by the nearest covariance
    matrix that is positive definite and with a Cholesky decomposition that can be
    computed. The variance is left unchanged.
    A covariance matrix that is not positive definite often occurs in high
    dimensional problems. It can be due to multicollinearity, floating-point
    inaccuracies, or when the number of observations is smaller than the number of
    assets. For more details, see [`cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest).
    The default is `True`.

  **higham** *bool, default=False*
  : If this is set to True, the Higham (2002) algorithm is used to find the
    nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
    above zeros (1e-13). The default is `False` and uses the clipping method as the
    Higham algorithm can be slow for large datasets.

  **higham_max_iteration** *int, default=100*
  : Maximum number of iterations of the Higham (2002) algorithm.
    The default value is `100`.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance matrix.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location, i.e. the estimated mean.
    Use for compatibility with scikit-learn Covariance estimators and for
    mahalanobis and score methods.

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

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

### Methods

| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.BaseCovariance.html.md#skfolio.moments.BaseCovariance.get_metadata_routing)()          | Get metadata routing of this object.                                               |
|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| [`get_params`](https://skfolio.org/generated/skfolio.moments.BaseCovariance.html.md#skfolio.moments.BaseCovariance.get_params)([deep])              | Get parameters for this estimator.                                                 |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.BaseCovariance.html.md#skfolio.moments.BaseCovariance.mahalanobis)(X_test)             | Compute the squared Mahalanobis distance of observations.                          |
| [`score`](https://skfolio.org/generated/skfolio.moments.BaseCovariance.html.md#skfolio.moments.BaseCovariance.score)(X_test[, y])              | Compute the mean log-likelihood of observations under the estimated model.         |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.BaseCovariance.html.md#skfolio.moments.BaseCovariance.set_params)(\*\*params)          | Set the parameters of this estimator.                                              |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.BaseCovariance.html.md#skfolio.moments.BaseCovariance.set_score_request)(\*[, X_test]) | Configure whether metadata should be requested to be passed to the `score` method. |

| **fit**   |    |
|-----------|----|

### Notes

All estimators should specify all the parameters that can be set
at the class level in their `__init__` as explicit keyword
arguments (no `*args` or `**kwargs`).

<a id="skfolio.moments.BaseCovariance.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.moments.BaseCovariance.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.moments.BaseCovariance.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.BaseCovariance.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.BaseCovariance.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.

<a id="skfolio.moments.BaseCovariance.set_score_request"></a>

#### set_score_request(\*, X_test='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **X_test** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `X_test` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.BaseMu.html.md

<a id="skfolio-moments-basemu"></a>

# skfolio.moments.BaseMu

<a id="skfolio.moments.BaseMu"></a>

### *class* skfolio.moments.BaseMu

Base class for all expected returns estimators in skfolio.

### Methods

| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.BaseMu.html.md#skfolio.moments.BaseMu.get_metadata_routing)()   | Get metadata routing of this object.   |
|---------------------------------------------------------------------------|----------------------------------------|
| [`get_params`](https://skfolio.org/generated/skfolio.moments.BaseMu.html.md#skfolio.moments.BaseMu.get_params)([deep])       | Get parameters for this estimator.     |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.BaseMu.html.md#skfolio.moments.BaseMu.set_params)(\*\*params)   | Set the parameters of this estimator.  |

| **fit**   |    |
|-----------|----|

### Notes

All estimators should specify all the parameters that can be set
at the class level in their `__init__` as explicit keyword
arguments (no `*args` or `**kwargs`).

<a id="skfolio.moments.BaseMu.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.moments.BaseMu.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.moments.BaseMu.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.

# generated/skfolio.moments.BaseVariance.html.md

<a id="skfolio-moments-basevariance"></a>

# skfolio.moments.BaseVariance

<a id="skfolio.moments.BaseVariance"></a>

### *class* skfolio.moments.BaseVariance(assume_centered=False)

Base class for all variance estimators in `skfolio`.

Variance estimators estimate the diagonal elements of a covariance matrix,
assuming **zero correlation** between assets. This is appropriate when:

* Estimating **idiosyncratic (specific) risk** in factor models, where residual
  returns are uncorrelated by construction
* Working with **orthogonalized** or **uncorrelated** return series
* The full covariance structure is not needed or is constructed separately

* **Parameters:**
  **assume_centered** *bool, default=False*
  : If False (default), the data are mean-centered before computing the variance.
    This is the standard behavior when working with raw returns where the mean is
    not guaranteed to be zero.
    If True, the estimator assumes the input data are already centered. Use this
    when you know the returns have zero mean, such as pre-demeaned data or
    regression residuals.
* **Attributes:**
  **variance_** *ndarray of shape (n_assets,)*
  : Estimated variance vector $(\\sigma^2_1, ..., \\sigma^2_n)$.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location, i.e. the estimated mean.
    When `assume_centered=True`, this is zero.
    When `assume_centered=False`, this is the sample mean.

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

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

### Methods

| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.BaseVariance.html.md#skfolio.moments.BaseVariance.get_metadata_routing)()   | Get metadata routing of this object.   |
|---------------------------------------------------------------------------|----------------------------------------|
| [`get_params`](https://skfolio.org/generated/skfolio.moments.BaseVariance.html.md#skfolio.moments.BaseVariance.get_params)([deep])       | Get parameters for this estimator.     |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.BaseVariance.html.md#skfolio.moments.BaseVariance.set_params)(\*\*params)   | Set the parameters of this estimator.  |

| **fit**   |    |
|-----------|----|

### Notes

All estimators should specify all the parameters that can be set
at the class level in their `__init__` as explicit keyword
arguments (no `*args` or `**kwargs`).

<a id="skfolio.moments.BaseVariance.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.moments.BaseVariance.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.moments.BaseVariance.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.

# generated/skfolio.moments.DenoiseCovariance.html.md

<a id="skfolio-moments-denoisecovariance"></a>

# skfolio.moments.DenoiseCovariance

<a id="skfolio.moments.DenoiseCovariance"></a>

### *class* skfolio.moments.DenoiseCovariance(covariance_estimator=None, nearest=True, higham=False, higham_max_iteration=100)

Covariance Denoising estimator.

The goal of Covariance Denoising is to reduce the noise and enhance the signal of
the empirical covariance matrix [[1]](https://skfolio.org/generated/skfolio.moments.DenoiseCovariance.html.md#r24485fcb4f82-1).
It reduces the ill-conditioning of the traditional covariance estimate by
differentiating the eigenvalues associated with noise from the eigenvalues
associated with signal.
Denoising replaces the eigenvalues of the eigenvectors classified as random by
Marčenko-Pastur with a constant eigenvalue.

* **Parameters:**
  **covariance_estimator** *BaseCovariance, optional*
  : [Covariance estimator](https://skfolio.org/user_guide/covariance.html.md#covariance-estimator) to estimate the covariance
    matrix that will be denoised.
    The default (`None`) is to use [`EmpiricalCovariance`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance).

  **nearest** *bool, default=True*
  : If this is set to True, the covariance is replaced by the nearest covariance
    matrix that is positive definite and with a Cholesky decomposition that can be
    computed. The variance is left unchanged.
    A covariance matrix that is not positive definite often occurs in high
    dimensional problems. It can be due to multicollinearity, floating-point
    inaccuracies, or when the number of observations is smaller than the number of
    assets. For more details, see [`cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest).
    The default is `True`.

  **higham** *bool, default=False*
  : If this is set to True, the Higham & Nick (2002) algorithm is used to find the
    nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
    above zeros (1e-13). The default is `False` and use the clipping method as the
    Higham & Nick algorithm can be slow for large datasets.

  **higham_max_iteration** *int, default=100*
  : Maximum number of iteration of the Higham & Nick (2002) algorithm.
    The default value is `100`.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance.

  **covariance_estimator_** *BaseCovariance*
  : Fitted `covariance_estimator`.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.moments.DenoiseCovariance.html.md#skfolio.moments.DenoiseCovariance.fit)(X[, y])                     | Fit the Covariance Denoising estimator.                                            |
|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.DenoiseCovariance.html.md#skfolio.moments.DenoiseCovariance.get_metadata_routing)()          | Get metadata routing of this object.                                               |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.DenoiseCovariance.html.md#skfolio.moments.DenoiseCovariance.get_params)([deep])              | Get parameters for this estimator.                                                 |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.DenoiseCovariance.html.md#skfolio.moments.DenoiseCovariance.mahalanobis)(X_test)             | Compute the squared Mahalanobis distance of observations.                          |
| [`score`](https://skfolio.org/generated/skfolio.moments.DenoiseCovariance.html.md#skfolio.moments.DenoiseCovariance.score)(X_test[, y])              | Compute the mean log-likelihood of observations under the estimated model.         |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.DenoiseCovariance.html.md#skfolio.moments.DenoiseCovariance.set_params)(\*\*params)          | Set the parameters of this estimator.                                              |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.DenoiseCovariance.html.md#skfolio.moments.DenoiseCovariance.set_score_request)(\*[, X_test]) | Configure whether metadata should be requested to be passed to the `score` method. |

### References

* <a id='r24485fcb4f82-1'>**[1]**</a> “Machine Learning for Asset Managers”. Elements in Quantitative Finance. Lòpez de Prado (2020).

<a id="skfolio.moments.DenoiseCovariance.fit"></a>

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

Fit the Covariance Denoising 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** *DenoiseCovariance*
  : Fitted estimator.

<a id="skfolio.moments.DenoiseCovariance.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.moments.DenoiseCovariance.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.moments.DenoiseCovariance.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.DenoiseCovariance.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.DenoiseCovariance.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.

<a id="skfolio.moments.DenoiseCovariance.set_score_request"></a>

#### set_score_request(\*, X_test='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **X_test** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `X_test` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.DetoneCovariance.html.md

<a id="skfolio-moments-detonecovariance"></a>

# skfolio.moments.DetoneCovariance

<a id="skfolio.moments.DetoneCovariance"></a>

### *class* skfolio.moments.DetoneCovariance(covariance_estimator=None, n_markets=1, nearest=True, higham=False, higham_max_iteration=100)

Covariance Detoning estimator.

Financial covariance matrices usually incorporate a market component corresponding
to the first eigenvectors [[1]](https://skfolio.org/generated/skfolio.moments.DetoneCovariance.html.md#r84b9a959864f-1).
For some applications like clustering, removing the market component (loud tone)
allow a greater portion of the covariance to be explained by components that affect
specific subsets of the securities.

* **Parameters:**
  **covariance_estimator** *BaseCovariance, optional*
  : [Covariance estimator](https://skfolio.org/user_guide/covariance.html.md#covariance-estimator) to estimate the covariance
    matrix prior detoning.
    The default (`None`) is to use [`EmpiricalCovariance`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance).

  **n_markets** *int, default=1*
  : Number of eigenvectors related to the market.
    The default value is `1`.

  **nearest** *bool, default=True*
  : If this is set to True, the covariance is replaced by the nearest covariance
    matrix that is positive definite and with a Cholesky decomposition that can be
    computed. The variance is left unchanged.
    A covariance matrix that is not positive definite often occurs in high
    dimensional problems. It can be due to multicollinearity, floating-point
    inaccuracies, or when the number of observations is smaller than the number of
    assets. For more details, see [`cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest).
    The default is `True`.

  **higham** *bool, default=False*
  : If this is set to True, the Higham (2002) algorithm is used to find the
    nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
    above zeros (1e-13). The default is `False` and uses the clipping method as the
    Higham algorithm can be slow for large datasets.

  **higham_max_iteration** *int, default=100*
  : Maximum number of iterations of the Higham (2002) algorithm.
    The default value is `100`.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance.

  **covariance_estimator_** *BaseCovariance*
  : Fitted `covariance_estimator`.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.moments.DetoneCovariance.html.md#skfolio.moments.DetoneCovariance.fit)(X[, y])                     | Fit the Covariance Detoning estimator.                                             |
|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.DetoneCovariance.html.md#skfolio.moments.DetoneCovariance.get_metadata_routing)()          | Get metadata routing of this object.                                               |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.DetoneCovariance.html.md#skfolio.moments.DetoneCovariance.get_params)([deep])              | Get parameters for this estimator.                                                 |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.DetoneCovariance.html.md#skfolio.moments.DetoneCovariance.mahalanobis)(X_test)             | Compute the squared Mahalanobis distance of observations.                          |
| [`score`](https://skfolio.org/generated/skfolio.moments.DetoneCovariance.html.md#skfolio.moments.DetoneCovariance.score)(X_test[, y])              | Compute the mean log-likelihood of observations under the estimated model.         |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.DetoneCovariance.html.md#skfolio.moments.DetoneCovariance.set_params)(\*\*params)          | Set the parameters of this estimator.                                              |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.DetoneCovariance.html.md#skfolio.moments.DetoneCovariance.set_score_request)(\*[, X_test]) | Configure whether metadata should be requested to be passed to the `score` method. |

### References

* <a id='r84b9a959864f-1'>**[1]**</a> “Machine Learning for Asset Managers”. Elements in Quantitative Finance. Lòpez de Prado (2020).

<a id="skfolio.moments.DetoneCovariance.fit"></a>

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

Fit the Covariance Detoning 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** *DetoneCovariance*
  : Fitted estimator.

<a id="skfolio.moments.DetoneCovariance.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.moments.DetoneCovariance.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.moments.DetoneCovariance.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.DetoneCovariance.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.DetoneCovariance.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.

<a id="skfolio.moments.DetoneCovariance.set_score_request"></a>

#### set_score_request(\*, X_test='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **X_test** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `X_test` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.EWCovariance.html.md

<a id="skfolio-moments-ewcovariance"></a>

# skfolio.moments.EWCovariance

<a id="skfolio.moments.EWCovariance"></a>

### *class* skfolio.moments.EWCovariance(half_life=40, assume_centered=True, min_observations=None, window_size=None, nearest=True, higham=False, higham_max_iteration=100)

Exponentially Weighted Covariance estimator with NaN-aware pairwise updates.

This estimator uses the recursive EWMA formula:

$$
\Sigma_t = \lambda \Sigma_{t-1} + (1-\lambda) r_t r_t^\top
$$

where $\lambda$ is the decay factor, which determines how much weight is
given to past observations. It is computed from the half-life parameter:

$$
\lambda = 2^{-1/\text{half-life}}
$$

The half-life is the number of observations for the weight to decay to 50%.

This estimator supports both batch fitting via [`fit`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.fit) and incremental updates
via [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.partial_fit), making it suitable for online learning.

**NaN handling:**

The estimator handles missing data (NaN returns) caused by late listings,
delistings, and holidays using EWMA updates together with `active_mask`. An asset
with `active_mask=True` is treated as active at time $t$. If its return is
finite, the EWMA is updated normally. If its return is NaN, the observation is
treated as a holiday and covariance entries involving this asset are kept unchanged.
An asset with `active_mask=False` is treated as inactive, for example during
pre-listing or post-delisting periods, and covariance entries involving this asset
are set to NaN.

* **Active with valid return**: Normal EWMA update.
* **Active with NaN return (holiday)**: Freeze; covariance entries involving this
  asset are kept unchanged.
* **Inactive** (`active_mask=False`): Covariance entries involving this asset are
  set to NaN.

When `active_mask` is not provided, trailing NaN returns are ambiguous: they could
correspond either to holidays, in which case covariance is frozen, or to inactive
periods, in which case covariance is set to NaN.

**Late-listing bias correction:**

When an asset becomes active (late listing), the EWMA recursion for its covariance
entries is initialized at zero rather than at the outer product of the first return.
This initialization guarantees that the internal covariance state remains positive
semi-definite at every step, but it introduces a transient downward scale bias:
after $n_i$ observations, the raw EWMA for asset $i$ is damped by a
factor $(1 - \lambda^{n_i})$. At output time, a per-asset correction removes
this bias:

$$
\hat{\Sigma}_{ij} = \frac{S_{ij}}{\sqrt{(1 - \lambda^{n_i})(1 - \lambda^{n_j})}}
$$

where $S$ is the raw internal EWMA. This is a congruence transform
$D S D$ with $D = \text{diag}(1 / \sqrt{1 - \lambda^{n_i}})$,
which preserves positive semi-definiteness while restoring the correct variance
scale. Correlations are unaffected by the correction. For assets with a long
history, the correction is negligible ($\lambda^{n_i} \to 0$).

The `min_observations` parameter controls a warm-up period: an asset’s covariance
entries remain NaN in the output until it has accumulated enough valid observations
for a reliable estimate.

* **Parameters:**
  **half_life** *float, default=40*
  : Half-life of the exponential weights in number of observations.
    <br/>
    The half-life controls how quickly older observations lose their influence:
    * **Larger half-life**: More stable estimates, slower to adapt (robust to noise)
    * **Smaller half-life**: More responsive estimates, faster to adapt (sensitive to noise)
    <br/>
    The decay factor $\lambda$ is computed as:
    $\lambda = 2^{-1/\text{half-life}}$
    <br/>
    For example:
    : * half-life = 40: $\lambda \approx 0.983$
      * half-life = 23: $\lambda \approx 0.970$
      * half-life = 11: $\lambda \approx 0.939$
      * half-life = 6: $\lambda \approx 0.891$
    <br/>
    #### NOTE
    For portfolio optimization, larger half-lives (>= 20) are generally
    preferred to avoid excessive turnover from estimation noise.

  **assume_centered** *bool, default=True*
  : If True (default), the EWMA update uses raw returns without demeaning. This
    is the standard convention for EWMA covariance estimation in finance.
    If False, returns are demeaned using an EWMA mean estimate before computing
    the covariance update, and `location_` tracks the EWMA mean.

  **min_observations** *int, optional*
  : Minimum number of valid observations per asset before its covariance entries
    are considered reliable and exposed in the output `covariance_`. Until this
    threshold is reached, the asset’s covariance entries remain NaN.
    <br/>
    The default (`None`) uses `int(half_life)` as the threshold, ensuring
    the late-listing initialization bias has decayed to at most 50%. Set to
    1 to disable warm-up entirely.

  **window_size** *int, optional*
  : Window size to truncate data to the last `window_size` observations before
    fitting. Only applies to the initial [`fit`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.fit) call (or equivalently, the
    first [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.partial_fit) call); subsequent [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.partial_fit) calls use
    all provided data.
    <br/>
    This is a computational optimization for very long time series. Due to
    exponential decay, observations far in the past contribute negligibly to
    the current estimate. For example, with half-life = 23 ($\lambda = 0.97$),
    observations beyond ~150 periods contribute less than 1% to the estimate.
    Truncating to a reasonable window (e.g., 252 trading days) speeds up
    computation without materially affecting results.
    <br/>
    The default (`None`) uses all available data.

  **nearest** *bool, default=True*
  : If this is set to True, the covariance is replaced by the nearest covariance
    matrix that is positive definite and with a Cholesky decomposition that can be
    computed. The variance is left unchanged.
    A covariance matrix that is not positive definite often occurs in high
    dimensional problems. It can be due to multicollinearity, floating-point
    inaccuracies, or when the number of observations is smaller than the number of
    assets. For more details, see [`cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest).
    The default is `True`.

  **higham** *bool, default=False*
  : If this is set to True, the Higham (2002) algorithm is used to find the
    nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
    above zeros (1e-13). The default is `False` and uses the clipping method as
    the Higham algorithm can be slow for large datasets.

  **higham_max_iteration** *int, default=100*
  : Maximum number of iterations of the Higham (2002) algorithm.
    The default value is `100`.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance. Contains NaN for assets that are inactive
    or have not yet accumulated `min_observations` valid observations.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location (mean). If `assume_centered=True`, this is zeros.
    Otherwise, it tracks the EWMA mean of returns. Contains NaN for inactive
    assets.

  **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`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.fit)(X[, y, active_mask])                   | Fit the Exponentially Weighted Covariance estimator.                                     |
|---------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.get_metadata_routing)()                     | Get metadata routing of this object.                                                     |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.get_params)([deep])                         | Get parameters for this estimator.                                                       |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.mahalanobis)(X_test)                        | Compute the squared Mahalanobis distance of observations.                                |
| [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.partial_fit)(X[, y, active_mask])           | Incrementally fit the Exponentially Weighted Covariance estimator.                       |
| [`score`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.score)(X_test[, y])                         | Compute the mean log-likelihood of observations under the estimated model.               |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.set_fit_request)(\*[, active_mask])         | Configure whether metadata should be requested to be passed to the `fit` method.         |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.set_params)(\*\*params)                     | Set the parameters of this estimator.                                                    |
| [`set_partial_fit_request`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.set_partial_fit_request)(\*[, active_mask]) | Configure whether metadata should be requested to be passed to the `partial_fit` method. |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance.set_score_request)(\*[, X_test])            | Configure whether metadata should be requested to be passed to the `score` method.       |

#### SEE ALSO
[Online Covariance Forecast Evaluation](https://skfolio.org/auto_examples/online_learning/plot_1_online_covariance_forecast_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-1-online-covariance-forecast-evaluation-py)
: Online covariance forecast evaluation with `EWCovariance` and `RegimeAdjustedEWCovariance`.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.moments import EWCovariance
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # Batch fitting
>>> model = EWCovariance(half_life=40)
>>> model.fit(X)
EWCovariance()
>>> print(model.covariance_.shape)
(20, 20)
>>>
>>> # Streaming updates with partial_fit
>>> model2 = EWCovariance(half_life=20)
>>> model2.partial_fit(X[:100])  # Initial fit
EWCovariance(half_life=20)
>>> model2.partial_fit(X[100:200])  # Update with new data
EWCovariance(half_life=20)
>>> model2.partial_fit(X[200:])  # Continue updating
EWCovariance(half_life=20)
>>>
>>> # NaN-aware fitting with active_mask
>>> # Asset 2 is listed starting from observation 50
>>> active_mask = np.ones(X.shape, dtype=bool)
>>> active_mask[:50, 2] = False
>>> X_nan = X.copy()
>>> X_nan.iloc[:50, 2] = np.nan
>>> model3 = EWCovariance(half_life=40)
>>> model3.fit(X_nan, active_mask=active_mask)
EWCovariance()
```

<a id="skfolio.moments.EWCovariance.fit"></a>

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

Fit the Exponentially Weighted Covariance estimator.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. May contain NaN for missing data (holidays,
    late listings, delistings).

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

  **active_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset is structurally active at each
    observation. Use this to distinguish between holidays (`active_mask=True`
    and NaN return: covariance is frozen) and inactive periods such as
    pre-listing or post-delisting (`active_mask=False`: covariance is set to
    NaN). If `None` (default), all assets are assumed active.
* **Returns:**
  **self** *EWCovariance*
  : Fitted estimator.

<a id="skfolio.moments.EWCovariance.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.moments.EWCovariance.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.moments.EWCovariance.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.EWCovariance.partial_fit"></a>

#### partial_fit(X, y=None, \*, active_mask=None)

Incrementally fit the Exponentially Weighted Covariance estimator.

This method allows for streaming/online updates to the covariance estimate.
Each call updates the internal state with new observations.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. May contain NaN for missing data (holidays,
    late listings, delistings).

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

  **active_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset is structurally active at each
    observation. Use this to distinguish between holidays (`active_mask=True`
    and NaN return: covariance is frozen) and inactive periods such as
    pre-listing or post-delisting (`active_mask=False`: covariance is set to
    NaN). If `None` (default), all assets are assumed active.
* **Returns:**
  **self** *EWCovariance*
  : Fitted estimator.

<a id="skfolio.moments.EWCovariance.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.EWCovariance.set_fit_request"></a>

#### set_fit_request(\*, active_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **active_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `active_mask` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.moments.EWCovariance.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.

<a id="skfolio.moments.EWCovariance.set_partial_fit_request"></a>

#### set_partial_fit_request(\*, active_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `partial_fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `partial_fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `partial_fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **active_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `active_mask` parameter in `partial_fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.moments.EWCovariance.set_score_request"></a>

#### set_score_request(\*, X_test='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **X_test** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `X_test` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.EWMu.html.md

<a id="skfolio-moments-ewmu"></a>

# skfolio.moments.EWMu

<a id="skfolio.moments.EWMu"></a>

### *class* skfolio.moments.EWMu(half_life=40, min_observations=None, window_size=None)

Exponentially Weighted Expected Returns (Mu) estimator.

This estimator uses the recursive EWMA formula:

$$
\mu_t = \lambda \mu_{t-1} + (1-\lambda) r_t
$$

where $\lambda$ is the decay factor, which determines how much weight is
given to past observations. It is computed from the half-life parameter:

$$
\lambda = 2^{-1/\text{half-life}}
$$

The half-life is the number of observations for the weight to decay to 50%.

This estimator supports both batch fitting via [`fit`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.fit) and incremental
updates via [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.partial_fit), making it suitable for online learning
scenarios.

**NaN handling:**

The estimator handles missing data (NaN returns) caused by late listings,
delistings, and holidays using EWMA updates together with `active_mask`.
An asset with `active_mask=True` is treated as active at time $t$.
If its return is finite, the EWMA is updated normally. If its return is
NaN, the observation is treated as a holiday and the previous estimate is
kept. An asset with `active_mask=False` is treated as inactive, for
example during pre-listing or post-delisting periods, and its estimate is
set to NaN.

* **Active with valid return**: Normal EWMA update.
* **Active with NaN return (holiday)**: Freeze; the previous estimate is
  kept.
* **Inactive** (`active_mask=False`): The estimate is set to NaN.

When `active_mask` is not provided, trailing NaN returns are ambiguous:
they could correspond either to holidays, in which case the mean is
frozen, or to inactive periods, in which case the mean is set to NaN.

**Late-listing bias correction:**

When an asset becomes active (late listing), the EWMA recursion is
initialized at zero rather than at the first return. This zero-initialization
introduces a transient downward bias: after $n_i$ valid observations,
the raw EWMA weights sum to $(1 - \lambda^{n_i})$ instead of 1. At
output time, a per-asset correction removes this bias:

$$
\hat{\mu}_i = \frac{S_i}{1 - \lambda^{n_i}}
$$

where $S_i$ is the raw internal EWMA accumulator. For assets with a long
history, the correction is negligible ($\lambda^{n_i} \to 0$).

The `min_observations` parameter controls a warm-up period: an asset’s
mean estimate remains NaN in the output until it has accumulated enough
valid observations for a reliable estimate.

* **Parameters:**
  **half_life** *float, default=40*
  : Half-life of the exponential weights in number of observations.
    <br/>
    The half-life controls how quickly older observations lose their influence:
    * **Larger half-life**: More stable estimates, slower to adapt (robust to noise)
    * **Smaller half-life**: More responsive estimates, faster to adapt (sensitive to noise)
    <br/>
    The decay factor $\lambda$ is computed as:
    $\lambda = 2^{-1/\text{half-life}}$
    <br/>
    For example:
    : * half-life = 40: $\lambda \approx 0.983$
      * half-life = 23: $\lambda \approx 0.970$
      * half-life = 11: $\lambda \approx 0.939$
      * half-life = 6: $\lambda \approx 0.891$
    <br/>
    #### NOTE
    For portfolio optimization, larger half-lives (>= 20) are generally
    preferred to avoid excessive turnover from estimation noise.

  **min_observations** *int, optional*
  : Minimum number of valid observations per asset before its mean estimate
    is considered reliable and exposed in the output `mu_`. Until this
    threshold is reached, the asset’s mean estimate remains NaN.
    <br/>
    The default (`None`) uses `int(half_life)` as the threshold, ensuring
    the late-listing initialization bias has decayed to at most 50%. Set to
    1 to disable warm-up entirely.

  **window_size** *int, optional*
  : Window size to truncate data to the last `window_size` observations before
    fitting. Only applies to the initial [`fit`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.fit) call (or equivalently, the
    first [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.partial_fit) call); subsequent [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.partial_fit) calls use
    all provided data.
    <br/>
    This is a computational optimization for very long time series. Due to
    exponential decay, observations far in the past contribute negligibly to
    the current estimate. For example, with half-life = 23 ($\lambda = 0.97$),
    observations beyond ~150 periods contribute less than 1% to the estimate.
    Truncating to a reasonable window (e.g., 252 trading days) speeds up
    computation without materially affecting results.
    <br/>
    The default (`None`) uses all available data.
* **Attributes:**
  **mu_** *ndarray of shape (n_assets,)*
  : Estimated expected returns of the assets. Contains NaN for assets that are
    inactive or have not yet accumulated `min_observations` valid
    observations.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.fit)(X[, y, active_mask])                   | Fit the EWMu estimator model.                                                            |
|---------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.get_metadata_routing)()                     | Get metadata routing of this object.                                                     |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.get_params)([deep])                         | Get parameters for this estimator.                                                       |
| [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.partial_fit)(X[, y, active_mask])           | Incrementally fit the EWMu estimator.                                                    |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.set_fit_request)(\*[, active_mask])         | Configure whether metadata should be requested to be passed to the `fit` method.         |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.set_params)(\*\*params)                     | Set the parameters of this estimator.                                                    |
| [`set_partial_fit_request`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu.set_partial_fit_request)(\*[, active_mask]) | Configure whether metadata should be requested to be passed to the `partial_fit` method. |

#### SEE ALSO
[Online Evaluation of Portfolio Optimization](https://skfolio.org/auto_examples/online_learning/plot_3_online_portfolio_optimization_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-3-online-portfolio-optimization-evaluation-py)
: Online evaluation of portfolio optimization using `MeanRisk` with `EWMu` and exponentially weighted covariance estimators.

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.moments import EWMu
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # Batch fitting
>>> model = EWMu(half_life=40)
>>> model.fit(X)
EWMu()
>>> print(model.mu_.shape)
(20,)
>>>
>>> # Streaming updates with partial_fit
>>> model2 = EWMu(half_life=20)
>>> model2.partial_fit(X[:100])  # Initial fit
EWMu(half_life=20)
>>> model2.partial_fit(X[100:200])  # Update with new data
EWMu(half_life=20)
>>> model2.partial_fit(X[200:])  # Continue updating
EWMu(half_life=20)
>>>
>>> # NaN-aware fitting with active_mask
>>> import numpy as np
>>> # Asset 2 is listed starting from observation 50
>>> active_mask = np.ones(X.shape, dtype=bool)
>>> active_mask[:50, 2] = False
>>> X_nan = X.copy()
>>> X_nan.iloc[:50, 2] = np.nan
>>> model3 = EWMu(half_life=40)
>>> model3.fit(X_nan, active_mask=active_mask)
EWMu()
```

<a id="skfolio.moments.EWMu.fit"></a>

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

Fit the EWMu estimator model.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. May contain NaN for missing data
    (holidays, late listings, delistings).

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

  **active_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset is structurally active at
    each observation. Use this to distinguish between holidays
    (`active_mask=True` and NaN return: mean is frozen) and inactive
    periods such as pre-listing or post-delisting
    (`active_mask=False`: mean is set to NaN). If `None`
    (default), all assets are assumed active.
* **Returns:**
  **self** *EWMu*
  : Fitted estimator.

<a id="skfolio.moments.EWMu.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.moments.EWMu.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.moments.EWMu.partial_fit"></a>

#### partial_fit(X, y=None, \*, active_mask=None)

Incrementally fit the EWMu estimator.

This method allows for streaming/online updates to the expected returns
estimate. Each call updates the internal state with new observations.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. May contain NaN for missing data
    (holidays, late listings, delistings).

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

  **active_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset is structurally active at
    each observation. Use this to distinguish between holidays
    (`active_mask=True` and NaN return: mean is frozen) and inactive
    periods such as pre-listing or post-delisting
    (`active_mask=False`: mean is set to NaN). If `None`
    (default), all assets are assumed active.
* **Returns:**
  **self** *EWMu*
  : Fitted estimator.

<a id="skfolio.moments.EWMu.set_fit_request"></a>

#### set_fit_request(\*, active_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **active_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `active_mask` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.moments.EWMu.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.

<a id="skfolio.moments.EWMu.set_partial_fit_request"></a>

#### set_partial_fit_request(\*, active_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `partial_fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `partial_fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `partial_fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **active_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `active_mask` parameter in `partial_fit`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.EWVariance.html.md

<a id="skfolio-moments-ewvariance"></a>

# skfolio.moments.EWVariance

<a id="skfolio.moments.EWVariance"></a>

### *class* skfolio.moments.EWVariance(half_life=40, assume_centered=True, min_observations=None, window_size=None)

Exponentially Weighted Variance estimator.

This is the variance-only counterpart of
`EWCovariance`, computing only the diagonal
elements (variances) and assuming zero correlation. This is appropriate when:

* Estimating **idiosyncratic (specific) risk** in factor models, where residual
  returns are uncorrelated by construction
* Working with **orthogonalized** or **uncorrelated** return series
* The full covariance structure is not needed or is constructed separately

This estimator uses the recursive EWMA formula:

$$
\sigma^2_{i,t} = \lambda \sigma^2_{i,t-1} + (1-\lambda) r_{i,t}^2
$$

where $\lambda$ is the decay factor, which determines how much weight is
given to past observations. It is computed from the half-life parameter:

$$
\lambda = 2^{-1/\text{half-life}}
$$

The half-life is the number of observations for the weight to decay to 50%.

This estimator supports both batch fitting via [`fit`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.fit) and incremental
updates via [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.partial_fit), making it suitable for online learning
scenarios.

**NaN handling:**

The estimator handles missing data (NaN returns) caused by late listings,
delistings, and holidays using EWMA updates together with `active_mask`.
An asset with `active_mask=True` is treated as active at time $t$.
If its return is finite, the EWMA is updated normally. If its return is
NaN, the observation is treated as a holiday and the previous variance is
kept. An asset with `active_mask=False` is treated as inactive, for
example during pre-listing or post-delisting periods, and its variance is
set to NaN.

* **Active with valid return**: Normal EWMA update.
* **Active with NaN return (holiday)**: Freeze; the previous variance is
  kept.
* **Inactive** (`active_mask=False`): Variance is set to NaN.

When `active_mask` is not provided, trailing NaN returns are ambiguous:
they could correspond either to holidays, in which case the variance is
frozen, or to inactive periods, in which case the variance is set to NaN.

**Late-listing bias correction:**

When an asset becomes active (late listing), the EWMA recursion is
initialized at zero rather than at the first squared return. This
zero-initialization introduces a transient downward scale bias: after
$n_i$ valid observations, the raw EWMA weights sum to
$(1 - \lambda^{n_i})$ instead of 1. At output time, a per-asset
correction removes this bias:

$$
\hat{\sigma}^2_i = \frac{S_i}{1 - \lambda^{n_i}}
$$

where $S_i$ is the raw internal EWMA accumulator. For assets with a
long history, the correction is negligible ($\lambda^{n_i} \to 0$).

The `min_observations` parameter controls a warm-up period: an asset’s
variance estimate remains NaN in the output until it has accumulated enough
valid observations for a reliable estimate.

* **Parameters:**
  **half_life** *float, default=40*
  : Half-life of the exponential weights in number of observations.
    <br/>
    The half-life controls how quickly older observations lose their influence:
    * **Larger half-life**: More stable estimates, slower to adapt (robust to noise)
    * **Smaller half-life**: More responsive estimates, faster to adapt (sensitive to noise)
    <br/>
    The decay factor $\lambda$ is computed as:
    $\lambda = 2^{-1/\text{half-life}}$
    <br/>
    For example:
    : * half-life = 40: $\lambda \approx 0.983$
      * half-life = 23: $\lambda \approx 0.970$
      * half-life = 11: $\lambda \approx 0.939$
      * half-life = 6: $\lambda \approx 0.891$
    <br/>
    #### NOTE
    For portfolio optimization, larger half-lives (>= 20) are generally
    preferred to avoid excessive turnover from estimation noise.

  **assume_centered** *bool, default=True*
  : If True (default), the EWMA update uses raw returns without demeaning. This
    is the standard convention for EWMA variance estimation in finance.
    If False, returns are demeaned using an EWMA mean estimate before computing
    the variance update, and `location_` tracks the EWMA mean.

  **min_observations** *int, optional*
  : Minimum number of valid observations per asset before its variance estimate
    is considered reliable and exposed in the output `variance_`. Until this
    threshold is reached, the asset’s variance estimate remains NaN.
    <br/>
    The default (`None`) uses `int(half_life)` as the threshold, ensuring
    the late-listing initialization bias has decayed to at most 50%. Set to
    1 to disable warm-up entirely.

  **window_size** *int, optional*
  : Window size to truncate data to the last `window_size` observations before
    fitting. Only applies to the initial [`fit`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.fit) call (or equivalently, the
    first [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.partial_fit) call); subsequent [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.partial_fit) calls use
    all provided data.
    <br/>
    This is a computational optimization for very long time series. Due to
    exponential decay, observations far in the past contribute negligibly to
    the current estimate. For example, with half-life = 23 ($\lambda = 0.97$),
    observations beyond ~150 periods contribute less than 1% to the estimate.
    Truncating to a reasonable window (e.g., 252 trading days) speeds up
    computation without materially affecting results.
    <br/>
    The default (`None`) uses all available data.
* **Attributes:**
  **variance_** *ndarray of shape (n_assets,)*
  : Estimated variance vector. Contains NaN for assets that are inactive
    or that have not yet accumulated `min_observations` valid observations.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location (mean). If `assume_centered=True`, this is zeros.
    Otherwise, it tracks the EWMA mean of returns. Contains NaN for inactive
    assets when `assume_centered=False`.

  **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`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.fit)(X[, y, active_mask])                   | Fit the Exponentially Weighted Variance estimator.                                       |
|---------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.get_metadata_routing)()                     | Get metadata routing of this object.                                                     |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.get_params)([deep])                         | Get parameters for this estimator.                                                       |
| [`partial_fit`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.partial_fit)(X[, y, active_mask])           | Incrementally fit the Exponentially Weighted Variance estimator.                         |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.set_fit_request)(\*[, active_mask])         | Configure whether metadata should be requested to be passed to the `fit` method.         |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.set_params)(\*\*params)                     | Set the parameters of this estimator.                                                    |
| [`set_partial_fit_request`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance.set_partial_fit_request)(\*[, active_mask]) | Configure whether metadata should be requested to be passed to the `partial_fit` method. |

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.moments import EWVariance
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # Batch fitting
>>> model = EWVariance(half_life=40)
>>> model.fit(X)
EWVariance()
>>> print(model.variance_.shape)
(20,)
>>>
>>> # Streaming updates with partial_fit
>>> model2 = EWVariance(half_life=20)
>>> model2.partial_fit(X[:100])  # Initial fit
EWVariance(half_life=20)
>>> model2.partial_fit(X[100:200])  # Update with new data
EWVariance(half_life=20)
>>> model2.partial_fit(X[200:])  # Continue updating
EWVariance(half_life=20)
>>>
>>> # NaN-aware fitting with active_mask
>>> # Asset 2 is listed starting from observation 50
>>> active_mask = np.ones(X.shape, dtype=bool)
>>> active_mask[:50, 2] = False
>>> X_nan = X.copy()
>>> X_nan.iloc[:50, 2] = np.nan
>>> model3 = EWVariance(half_life=40)
>>> model3.fit(X_nan, active_mask=active_mask)
EWVariance()
```

<a id="skfolio.moments.EWVariance.fit"></a>

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

Fit the Exponentially Weighted Variance estimator.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. NaN values are allowed and handled
    robustly.

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

  **active_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset is structurally active at
    each observation. Use this to distinguish between holidays
    (`active_mask=True` and NaN return: variance is frozen) and
    inactive periods such as pre-listing or post-delisting
    (`active_mask=False`: variance is set to NaN). If `None`
    (default), all assets are assumed active.
* **Returns:**
  **self** *EWVariance*
  : Fitted estimator.

<a id="skfolio.moments.EWVariance.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.moments.EWVariance.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.moments.EWVariance.partial_fit"></a>

#### partial_fit(X, y=None, \*, active_mask=None)

Incrementally fit the Exponentially Weighted Variance estimator.

This method allows for streaming/online updates to the variance estimate.
Each call updates the internal state with new observations.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. NaN values are allowed and handled
    robustly.

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

  **active_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset is structurally active at
    each observation. See `fit` for details.
* **Returns:**
  **self** *EWVariance*
  : Fitted estimator.

<a id="skfolio.moments.EWVariance.set_fit_request"></a>

#### set_fit_request(\*, active_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **active_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `active_mask` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.moments.EWVariance.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.

<a id="skfolio.moments.EWVariance.set_partial_fit_request"></a>

#### set_partial_fit_request(\*, active_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `partial_fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `partial_fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `partial_fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **active_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `active_mask` parameter in `partial_fit`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.EmpiricalCovariance.html.md

<a id="skfolio-moments-empiricalcovariance"></a>

# skfolio.moments.EmpiricalCovariance

<a id="skfolio.moments.EmpiricalCovariance"></a>

### *class* skfolio.moments.EmpiricalCovariance(window_size=None, ddof=1, assume_centered=False, nearest=True, higham=False, higham_max_iteration=100)

Empirical Covariance estimator.

* **Parameters:**
  **window_size** *int, optional*
  : Window size. The model is fitted on the last `window_size` observations.
    The default (`None`) is to use all the data.

  **ddof** *int, default=1*
  : Normalization is by `(n_observations - ddof)`.
    Note that `ddof=1` will return the unbiased estimate, and `ddof=0`
    will return the simple average. The default value is `1`.

  **assume_centered** *bool, default=False*
  : If False (default), the data are mean-centered before computing the covariance.
    This is the standard behavior when working with raw returns where the mean is
    not guaranteed to be zero.
    If True, the estimator assumes the input data are already centered. Use this
    when you know the returns have zero mean, such as pre-demeaned data or
    regression residuals.

  **nearest** *bool, default=True*
  : If this is set to True, the covariance is replaced by the nearest covariance
    matrix that is positive definite and with a Cholesky decomposition that can be
    computed. The variance is left unchanged.
    A covariance matrix that is not positive definite often occurs in high
    dimensional problems. It can be due to multicollinearity, floating-point
    inaccuracies, or when the number of observations is smaller than the number of
    assets. For more details, see [`cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest).
    The default is `True`.

  **higham** *bool, default=False*
  : If this is set to True, the Higham (2002) algorithm is used to find the
    nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
    above zeros (1e-13). The default is `False` and uses the clipping method as the
    Higham algorithm can be slow for large datasets.

  **higham_max_iteration** *int, default=100*
  : Maximum number of iterations of the Higham (2002) algorithm.
    The default value is `100`.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance matrix.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location, i.e. the estimated mean.
    Use for compatibility with scikit-learn Covariance estimators and for
    mahalanobis and score methods.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance.fit)(X[, y])                     | Fit the empirical covariance estimator.                                            |
|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance.get_metadata_routing)()          | Get metadata routing of this object.                                               |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance.get_params)([deep])              | Get parameters for this estimator.                                                 |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance.mahalanobis)(X_test)             | Compute the squared Mahalanobis distance of observations.                          |
| [`score`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance.score)(X_test[, y])              | Compute the mean log-likelihood of observations under the estimated model.         |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance.set_params)(\*\*params)          | Set the parameters of this estimator.                                              |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance.set_score_request)(\*[, X_test]) | Configure whether metadata should be requested to be passed to the `score` method. |

<a id="skfolio.moments.EmpiricalCovariance.fit"></a>

#### fit(X, y=None)

Fit the empirical covariance 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.
* **Returns:**
  **self** *EmpiricalCovariance*
  : Fitted estimator.

<a id="skfolio.moments.EmpiricalCovariance.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.moments.EmpiricalCovariance.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.moments.EmpiricalCovariance.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.EmpiricalCovariance.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.EmpiricalCovariance.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.

<a id="skfolio.moments.EmpiricalCovariance.set_score_request"></a>

#### set_score_request(\*, X_test='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **X_test** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `X_test` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.EmpiricalMu.html.md

<a id="skfolio-moments-empiricalmu"></a>

# skfolio.moments.EmpiricalMu

<a id="skfolio.moments.EmpiricalMu"></a>

### *class* skfolio.moments.EmpiricalMu(window_size=None)

Empirical Expected Returns (Mu) estimator.

Estimates the expected returns with the historical mean.

* **Parameters:**
  **window_size** *int, optional*
  : Window size. The model is fitted on the last `window_size` observations.
    The default (`None`) is to use all the data.
* **Attributes:**
  **mu_** *ndarray of shape (n_assets,)*
  : Estimated expected returns of the assets.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.moments.EmpiricalMu.html.md#skfolio.moments.EmpiricalMu.fit)(X[, y])            | Fit the Mu Empirical estimator model.   |
|-------------------------------------------------------------------------|-----------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.EmpiricalMu.html.md#skfolio.moments.EmpiricalMu.get_metadata_routing)() | Get metadata routing of this object.    |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.EmpiricalMu.html.md#skfolio.moments.EmpiricalMu.get_params)([deep])     | Get parameters for this estimator.      |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.EmpiricalMu.html.md#skfolio.moments.EmpiricalMu.set_params)(\*\*params) | Set the parameters of this estimator.   |

<a id="skfolio.moments.EmpiricalMu.fit"></a>

#### fit(X, y=None)

Fit the Mu Empirical estimator model.

* **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.
* **Returns:**
  **self** *EmpiricalMu*
  : Fitted estimator.

<a id="skfolio.moments.EmpiricalMu.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.moments.EmpiricalMu.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.moments.EmpiricalMu.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.

# generated/skfolio.moments.EmpiricalVariance.html.md

<a id="skfolio-moments-empiricalvariance"></a>

# skfolio.moments.EmpiricalVariance

<a id="skfolio.moments.EmpiricalVariance"></a>

### *class* skfolio.moments.EmpiricalVariance(window_size=None, ddof=1, assume_centered=False)

Empirical Variance estimator.

This is the variance-only counterpart of
`EmpiricalCovariance`, computing only
the diagonal elements (variances) and assuming zero correlation. This is
appropriate when:

* Estimating **idiosyncratic (specific) risk** in factor models, where residual
  returns are uncorrelated by construction
* Working with **orthogonalized** or **uncorrelated** return series
* The full covariance structure is not needed or is constructed separately

* **Parameters:**
  **window_size** *int, optional*
  : Window size. The model is fitted on the last `window_size` observations.
    The default (`None`) is to use all the data.

  **ddof** *int, default=1*
  : Normalization is by `(n_observations - ddof)`.
    Note that `ddof=1` will return the unbiased estimate, and `ddof=0`
    will return the simple average. The default value is `1`.

  **assume_centered** *bool, default=False*
  : If False (default), the data are mean-centered before computing the variance.
    This is the standard behavior when working with raw returns where the mean is
    not guaranteed to be zero.
    If True, the estimator assumes the input data are already centered. Use this
    when you know the returns have zero mean, such as pre-demeaned data or
    regression residuals.
* **Attributes:**
  **variance_** *ndarray of shape (n_assets,)*
  : Estimated variance vector.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.moments.EmpiricalVariance.html.md#skfolio.moments.EmpiricalVariance.fit)(X[, y])            | Fit the empirical variance estimator.   |
|-------------------------------------------------------------------------|-----------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.EmpiricalVariance.html.md#skfolio.moments.EmpiricalVariance.get_metadata_routing)() | Get metadata routing of this object.    |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.EmpiricalVariance.html.md#skfolio.moments.EmpiricalVariance.get_params)([deep])     | Get parameters for this estimator.      |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.EmpiricalVariance.html.md#skfolio.moments.EmpiricalVariance.set_params)(\*\*params) | Set the parameters of this estimator.   |

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.moments import EmpiricalVariance
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>> model = EmpiricalVariance()
>>> model.fit(X)
EmpiricalVariance()
>>> print(model.variance_[:5])
[0.000747... 0.00151... 0.000681... 0.00101... 0.000275...]
```

<a id="skfolio.moments.EmpiricalVariance.fit"></a>

#### fit(X, y=None)

Fit the empirical variance 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.
* **Returns:**
  **self** *EmpiricalVariance*
  : Fitted estimator.

<a id="skfolio.moments.EmpiricalVariance.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.moments.EmpiricalVariance.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.moments.EmpiricalVariance.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.

# generated/skfolio.moments.EquilibriumMu.html.md

<a id="skfolio-moments-equilibriummu"></a>

# skfolio.moments.EquilibriumMu

<a id="skfolio.moments.EquilibriumMu"></a>

### *class* skfolio.moments.EquilibriumMu(risk_aversion=1, weights=None, covariance_estimator=None)

Equilibrium Expected Returns (Mu) estimator.

The Equilibrium is defined as:

> $$
> risk\_aversion \times \Sigma \cdot w^T

> $$

For Market Cap Equilibrium, the weights are the assets Market Caps.
For Equal-weighted Equilibrium, the weights are equal-weighted (1/N).

* **Parameters:**
  **risk_aversion** *float, default=1.0*
  : Risk aversion factor.
    The default value is `1.0`.

  **weights** *array-like of shape (n_assets,), optional*
  : Asset weights used to compute the Expected Return Equilibrium.
    The default is to use the equal-weighted equilibrium (1/N).
    For a Market Cap weighted equilibrium, you must provide the asset Market Caps.

  **covariance_estimator** *BaseCovariance, optional*
  : [Covariance estimator](https://skfolio.org/user_guide/covariance.html.md#covariance-estimator) used to estimate the
    covariance in the equilibrium formula.
    The default (`None`) is to use [`EmpiricalCovariance`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance).
* **Attributes:**
  **mu_** *ndarray of shape (n_assets,)*
  : Estimated expected returns of the assets.

  **covariance_estimator_** *BaseCovariance*
  : Fitted `covariance_estimator`.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.moments.EquilibriumMu.html.md#skfolio.moments.EquilibriumMu.fit)(X[, y])            | Fit the EquilibriumMu estimator model.   |
|-------------------------------------------------------------------------|------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.EquilibriumMu.html.md#skfolio.moments.EquilibriumMu.get_metadata_routing)() | Get metadata routing of this object.     |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.EquilibriumMu.html.md#skfolio.moments.EquilibriumMu.get_params)([deep])     | Get parameters for this estimator.       |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.EquilibriumMu.html.md#skfolio.moments.EquilibriumMu.set_params)(\*\*params) | Set the parameters of this estimator.    |

<a id="skfolio.moments.EquilibriumMu.fit"></a>

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

Fit the EquilibriumMu estimator model.

* **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** *EquilibriumMu*
  : Fitted estimator.

<a id="skfolio.moments.EquilibriumMu.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.moments.EquilibriumMu.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.moments.EquilibriumMu.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.

# generated/skfolio.moments.GerberCovariance.html.md

<a id="skfolio-moments-gerbercovariance"></a>

# skfolio.moments.GerberCovariance

<a id="skfolio.moments.GerberCovariance"></a>

### *class* skfolio.moments.GerberCovariance(window_size=None, threshold=0.5, psd_variant=True, nearest=True, higham=False, higham_max_iteration=100)

Gerber Covariance estimator.

Robust co-movement measure which ignores fluctuations below a certain threshold
while simultaneously limiting the effects of extreme movements.
The Gerber statistic extends Kendall’s Tau by counting the proportion of
simultaneous co-movements in series when their amplitudes exceed data-dependent
thresholds.

Three variant has been published:

> * Gerber et al. (2015): tend to produce matrices that are non-PSD.
> * Gerber et al. (2019): alteration of the denominator of the above statistic.
> * Gerber et al. (2022): final alteration to ensure PSD matrix.

The last two variants are implemented.

* **Parameters:**
  **window_size** *int, optional*
  : Window size. The model is fitted on the last `window_size` observations.
    The default (`None`) is to use all the data.

  **threshold** *float, default=0.5*
  : Gerber threshold. The default value is `0.5`.

  **psd_variant** *bool, default=True*
  : If this is set to True, the Gerber et al. (2022) variant is used to ensure a
    positive semi-definite matrix.
    Otherwise, the Gerber et al. (2019) variant is used.
    The default is `True`.

  **nearest** *bool, default=True*
  : If this is set to True, the covariance is replaced by the nearest covariance
    matrix that is positive definite and with a Cholesky decomposition that can be
    computed. The variance is left unchanged.
    A covariance matrix that is not positive definite often occurs in high
    dimensional problems. It can be due to multicollinearity, floating-point
    inaccuracies, or when the number of observations is smaller than the number of
    assets. For more details, see [`cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest).
    The default is `True`.

  **higham** *bool, default=False*
  : If this is set to True, the Higham (2002) algorithm is used to find the
    nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
    above zeros (1e-13). The default is `False` and uses the clipping method as the
    Higham algorithm can be slow for large datasets.

  **higham_max_iteration** *int, default=100*
  : Maximum number of iterations of the Higham (2002) algorithm.
    The default value is `100`.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.moments.GerberCovariance.html.md#skfolio.moments.GerberCovariance.fit)(X[, y])                     | Fit the Gerber covariance estimator.                                               |
|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.GerberCovariance.html.md#skfolio.moments.GerberCovariance.get_metadata_routing)()          | Get metadata routing of this object.                                               |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.GerberCovariance.html.md#skfolio.moments.GerberCovariance.get_params)([deep])              | Get parameters for this estimator.                                                 |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.GerberCovariance.html.md#skfolio.moments.GerberCovariance.mahalanobis)(X_test)             | Compute the squared Mahalanobis distance of observations.                          |
| [`score`](https://skfolio.org/generated/skfolio.moments.GerberCovariance.html.md#skfolio.moments.GerberCovariance.score)(X_test[, y])              | Compute the mean log-likelihood of observations under the estimated model.         |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.GerberCovariance.html.md#skfolio.moments.GerberCovariance.set_params)(\*\*params)          | Set the parameters of this estimator.                                              |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.GerberCovariance.html.md#skfolio.moments.GerberCovariance.set_score_request)(\*[, X_test]) | Configure whether metadata should be requested to be passed to the `score` method. |

### References

* <a id='r520bcc228f55-1'>**[1]**</a> “The gerber statistic: A robust co-movement measure for portfolio optimization”. The Journal of Portfolio Management. Gerber, S., B. Javid, H. Markowitz, P. Sargen, and D. Starer (2022).
* <a id='r520bcc228f55-2'>**[2]**</a> “The gerber statistic: A robust measure of correlation”. Gerber, S., B. Javid, H. Markowitz, P. Sargen, and D. Starer (2019).
* <a id='r520bcc228f55-3'>**[3]**</a> “Enhancing multi-asset portfolio construction under modern portfolio theory with a robust co-movement measure”. Social Science Research network Working Paper Series. Gerber, S., H. Markowitz, and P. Pujara (2015).
* <a id='r520bcc228f55-4'>**[4]**</a> “Deconstructing the Gerber Statistic”. Flint & Polakow, 2023.

<a id="skfolio.moments.GerberCovariance.fit"></a>

#### fit(X, y=None)

Fit the Gerber covariance 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.
* **Returns:**
  **self** *GerberCovariance*
  : Fitted estimator.

<a id="skfolio.moments.GerberCovariance.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.moments.GerberCovariance.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.moments.GerberCovariance.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.GerberCovariance.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.GerberCovariance.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.

<a id="skfolio.moments.GerberCovariance.set_score_request"></a>

#### set_score_request(\*, X_test='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **X_test** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `X_test` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.GraphicalLassoCV.html.md

<a id="skfolio-moments-graphicallassocv"></a>

# skfolio.moments.GraphicalLassoCV

<a id="skfolio.moments.GraphicalLassoCV"></a>

### *class* skfolio.moments.GraphicalLassoCV(alphas=4, n_refinements=4, cv=None, tol=0.0001, enet_tol=0.0001, max_iter=100, mode='cd', n_jobs=None, verbose=False, assume_centered=False, nearest=True, higham=False, higham_max_iteration=100)

Sparse inverse covariance with cross-validated choice of the l1 penalty.

Read more in [scikit-learn](https://scikit-learn.org/stable/auto_examples/covariance/plot_sparse_cov.html).

* **Parameters:**
  **alphas** *int or array-like of shape (n_alphas,), dtype=float, default=4*
  : If an integer is given, it fixes the number of points on the
    grids of alpha to be used. If a list is given, it gives the
    grid to be used. See the notes in the class docstring for
    more details. Range is [1, inf) for an integer.
    Range is (0, inf] for an array-like of floats.

  **n_refinements** *int, default=4*
  : The number of times the grid is refined. Not used if explicit
    values of alphas are passed. Range is [1, inf).

  **cv** *int, cross-validation generator or iterable, default=None*
  : Determines the cross-validation splitting strategy.
    Possible inputs for cv are:
    - None, to use the default 5-fold cross-validation,
    - integer, to specify the number of folds.
    - `CV splitter`,
    - An iterable yielding (train, test) splits as arrays of indices.
    <br/>
    For integer/None inputs `KFold` is used.

  **tol** *float, default=1e-4*
  : The tolerance to declare convergence: if the dual gap goes below
    this value, iterations are stopped. Range is (0, inf].

  **enet_tol** *float, default=1e-4*
  : The tolerance for the elastic net solver used to calculate the descent
    direction. This parameter controls the accuracy of the search direction
    for a given column update, not of the overall parameter estimate. Only
    used for mode=’cd’. Range is (0, inf].

  **max_iter** *int, default=100*
  : Maximum number of iterations.

  **mode** *{‘cd’, ‘lars’}, default=’cd’*
  : The Lasso solver to use: coordinate descent or LARS. Use LARS for
    very sparse underlying graphs, where number of features is greater
    than number of samples. Elsewhere prefer cd which is more numerically
    stable.

  **n_jobs** *int, default=None*
  : Number of jobs to run in parallel.
    `None` means 1 unless in a `joblib.parallel_backend` context.
    `-1` means using all processors.

  **verbose** *bool, default=False*
  : If verbose is True, the objective function and duality gap are
    printed at each iteration.

  **assume_centered** *bool, default=False*
  : If True, data are not centered before computation.
    Useful when working with data whose mean is almost, but not exactly
    zero.
    If False, data are centered before computation.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location, i.e. the estimated mean.

  **precision_** *ndarray of shape (n_assets, n_assets)*
  : Estimated pseudo inverse matrix.
    (stored only if store_precision is True)

  **alpha_** *float*
  : Penalization parameter selected.

  **cv_results_** *dict of ndarrays*
  : A dict with keys:
    <br/>
    alphas *ndarray of shape (n_alphas,)*
    : All penalization parameters explored.
    <br/>
    split(k)_test_score *ndarray of shape (n_alphas,)*
    : Log-likelihood score on left-out data across (k)th fold.
      <br/>
      #### Versionadded
      Added in version 1.0.
    <br/>
    mean_test_score *ndarray of shape (n_alphas,)*
    : Mean of scores over the folds.
      <br/>
      #### Versionadded
      Added in version 1.0.
    <br/>
    std_test_score *ndarray of shape (n_alphas,)*
    : Standard deviation of scores over the folds.
      <br/>
      #### Versionadded
      Added in version 1.0.

  **n_iter_** *int*
  : Number of iterations run for the optimal alpha.

  **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

| [`error_norm`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV.error_norm)(comp_cov[, norm, scaling, squared])   | Compute the Mean Squared Error between two covariance estimators.          |
|---------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| [`fit`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV.fit)(X[, y])                                      | Fit the GraphicalLasso covariance model to X.                              |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV.get_metadata_routing)()                           | Get metadata routing of this object.                                       |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV.get_params)([deep])                               | Get parameters for this estimator.                                         |
| [`get_precision`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV.get_precision)()                                  | Getter for the precision matrix.                                           |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV.mahalanobis)(X_test)                              | Compute the squared Mahalanobis distance of observations.                  |
| [`score`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV.score)(X_test[, y])                               | Compute the mean log-likelihood of observations under the estimated model. |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV.set_params)(\*\*params)                           | Set the parameters of this estimator.                                      |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV.set_score_request)()                              | No-op.                                                                     |

### Notes

The search for the optimal penalization parameter (`alpha`) is done on an
iteratively refined grid: first the cross-validated scores on a grid are
computed, then a new refined grid is centered around the maximum, and so
on.

One of the challenges which is faced here is that the solvers can
fail to converge to a well-conditioned estimate. The corresponding
values of `alpha` then come out as missing values, but the optimum may
be close to these missing values.

In `fit`, once the best parameter `alpha` is found through
cross-validation, the model is fit again using the entire training set.

<a id="skfolio.moments.GraphicalLassoCV.error_norm"></a>

#### error_norm(comp_cov, norm='frobenius', scaling=True, squared=True)

Compute the Mean Squared Error between two covariance estimators.

* **Parameters:**
  **comp_cov** *array-like of shape (n_features, n_features)*
  : The covariance to compare with.

  **norm** *{“frobenius”, “spectral”}, default=”frobenius”*
  : The type of norm used to compute the error. Available error types:
    - ‘frobenius’ (default): sqrt(tr(A^t.A))
    - ‘spectral’: sqrt(max(eigenvalues(A^t.A))
    where A is the error `(comp_cov - self.covariance_)`.

  **scaling** *bool, default=True*
  : If True (default), the squared error norm is divided by n_features.
    If False, the squared error norm is not rescaled.

  **squared** *bool, default=True*
  : Whether to compute the squared error norm or the error norm.
    If True (default), the squared error norm is returned.
    If False, the error norm is returned.
* **Returns:**
  **result** *float*
  : The Mean Squared Error (in the sense of the Frobenius norm) between
    `self` and `comp_cov` covariance estimators.

<a id="skfolio.moments.GraphicalLassoCV.fit"></a>

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

Fit the GraphicalLasso covariance model to X.

* **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.
* **Returns:**
  **self** *GraphicalLassoCV*
  : Fitted estimator.

<a id="skfolio.moments.GraphicalLassoCV.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.

#### Versionadded
Added in version 1.5.

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

<a id="skfolio.moments.GraphicalLassoCV.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.moments.GraphicalLassoCV.get_precision"></a>

#### get_precision()

Getter for the precision matrix.

* **Returns:**
  **precision_** *array-like of shape (n_features, n_features)*
  : The precision matrix associated to the current covariance object.

<a id="skfolio.moments.GraphicalLassoCV.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.GraphicalLassoCV.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.GraphicalLassoCV.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.

<a id="skfolio.moments.GraphicalLassoCV.set_score_request"></a>

#### set_score_request()

No-op.

Calling this method has no effect.

* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.ImpliedCovariance.html.md

<a id="skfolio-moments-impliedcovariance"></a>

# skfolio.moments.ImpliedCovariance

<a id="skfolio.moments.ImpliedCovariance"></a>

### *class* skfolio.moments.ImpliedCovariance(prior_covariance_estimator=None, annualization_factor=None, window_size=20, linear_regressor=None, volatility_risk_premium_adj=None, nearest=True, higham=False, higham_max_iteration=100, annualized_factor=None)

Implied Covariance estimator.

For each asset, the implied volatility time series is used to estimate the realised
volatility using the non-overlapping log-transformed OLS model [[6]](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#rc0964e4bf4fd-6):

$$
\ln(RV_{t}) = \alpha + \beta_{1} \ln(IV_{t-1}) + \beta_{2} \ln(RV_{t-1}) + \epsilon

$$

with $\alpha$, $\beta_{1}$ and $\beta_{2}$ the intercept and
coefficients to estimate, $RV$ the realised volatility, and $IV$ the
implied volatility. The training set uses non-overlapping data of sample size
`window_size` to avoid possible regression errors caused by auto-correlation.
The logarithmic transformation of volatilities is used for its better finite sample
properties and distribution, which is closer to normality, less skewed and
leptokurtic [[6]](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#rc0964e4bf4fd-6).

Alternatively, if `volatility_risk_premium_adj` is provided, the realised
volatility is estimated using:

$$
RV_{t} = \frac{IV_{t-1}}{VRPA}

$$

with $VRPA$ the volatility risk premium adjustment.

The final step is the reconstruction of the covariance matrix from the correlation
and estimated realised volatilities $D$:

$$
\Sigma = D \ Corr \ D

$$

With $Corr$, the correlation matrix computed from the prior covariance
estimator. The default is the `EmpiricalCovariance`. It can be changed to any
covariance estimator using `prior_covariance_estimator`.

* **Parameters:**
  **prior_covariance_estimator** *BaseCovariance, optional*
  : [Covariance estimator](https://skfolio.org/user_guide/covariance.html.md#covariance-estimator) to estimate the covariance
    matrix used for the correlation estimates prior the volatilities update.
    The default (`None`) is to use [`EmpiricalCovariance`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance).

  **annualization_factor** *float, default=252*
  : Annualization factor (AF) used to convert the implied volatilities into the same
    frequency as the returns using $\frac{IV}{\sqrt{AF}}$.
    The default is 252 which corresponds to **daily** returns and implied volatility
    expressed in **p.a.**

  **window_size** *int, default=20*
  : Window size used to construct the non-overlapping training set of realised
    volatilities and implied volatilities used in the regression.
    The default is 20 observations.

  **linear_regressor** *BaseEstimator, optional*
  : Estimator of the linear regression used to estimate the realised volatilities
    from the implied volatilities. The default is to use the scikit-learn OLS
    estimator `LinearRegression`.

  **volatility_risk_premium_adj** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : If provided, instead of using the regression model, the realised volatilities
    are estimated using:
    $$
    RV_{t} = \frac{IV_{t-1}}{VRPA}
    <br/>
    $$
    <br/>
    with $VRPA$ the volatility risk premium adjustment.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset $VRPA$) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.

  **nearest** *bool, default=True*
  : If this is set to True, the covariance is replaced by the nearest covariance
    matrix that is positive definite and with a Cholesky decomposition that can be
    computed. The variance is left unchanged.
    A covariance matrix that is not positive definite often occurs in high
    dimensional problems. It can be due to multicollinearity, floating-point
    inaccuracies, or when the number of observations is smaller than the number of
    assets. For more details, see [`cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest).
    The default is `True`.

  **higham** *bool, default=False*
  : If this is set to True, the Higham (2002) algorithm is used to find the
    nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
    above zeros (1e-13). The default is `False` and uses the clipping method as the
    Higham algorithm can be slow for large datasets.

  **higham_max_iteration** *int, default=100*
  : Maximum number of iterations of the Higham (2002) algorithm.
    The default value is `100`.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance matrix.

  **prior_covariance_estimator_** *BaseEstimator*
  : Fitted prior covariance estimator.

  **pred_realised_vols_** *ndarray of shape (n_assets,)*
  : The predicted realised volatilities

  **linear_regressors_** *list[BaseEstimator]*
  : The fitted linear regressions.

  **coefs_** *ndarray of shape (n_assets, 2)*
  : The coefficients of the log transformed regression model for each asset.

  **intercepts_** *ndarray of shape (n_assets,)*
  : The intercepts of the log transformed regression model for each asset.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance.fit)(X[, y, implied_vol])           | Fit the implied covariance estimator.                                              |
|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance.get_metadata_routing)()             | Get metadata routing of this object.                                               |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance.get_params)([deep])                 | Get parameters for this estimator.                                                 |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance.mahalanobis)(X_test)                | Compute the squared Mahalanobis distance of observations.                          |
| [`score`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance.score)(X_test[, y])                 | Compute the mean log-likelihood of observations under the estimated model.         |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance.set_fit_request)(\*[, implied_vol]) | Configure whether metadata should be requested to be passed to the `fit` method.   |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance.set_params)(\*\*params)             | Set estimator parameters.                                                          |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance.set_score_request)(\*[, X_test])    | Configure whether metadata should be requested to be passed to the `score` method. |

### References

* <a id='rc0964e4bf4fd-1'>**[1]**</a> “New evidence on the implied-realized volatility relation”. Christensen & Hansen (2002).
* <a id='rc0964e4bf4fd-2'>**[2]**</a> “The relation between implied and realized volatility”. Christensen & Prabhala (2002).
* <a id='rc0964e4bf4fd-3'>**[3]**</a> “Can implied volatility predict returns on the carry trade?”. Egbers & Swinkels (2015).
* <a id='rc0964e4bf4fd-4'>**[4]**</a> “Volatility and correlation forecasting”. Egbers & Swinkels (2015).
* <a id='rc0964e4bf4fd-5'>**[5]**</a> “Volatility and correlation forecasting”. Andersen, Bollerslev, Christoffersen & Diebol (2006).
* <a id='rc0964e4bf4fd-6'>**[6]**</a> “How Well Does Implied Volatility Predict Future Stock Index Returns and Volatility? : A Study of Option-Implied Volatility Derived from OMXS30 Index Options”. Sara Vikberg & Julia Björkman (2020).

<a id="skfolio.moments.ImpliedCovariance.fit"></a>

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

Fit the implied covariance 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.

  **implied_vol** *array-like of shape (n_observations, n_assets)*
  : Implied volatilities of the assets.

  **\*\*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** *ImpliedCovariance*
  : Fitted estimator.

<a id="skfolio.moments.ImpliedCovariance.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.moments.ImpliedCovariance.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.moments.ImpliedCovariance.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.ImpliedCovariance.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.ImpliedCovariance.set_fit_request"></a>

#### set_fit_request(\*, implied_vol='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **implied_vol** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `implied_vol` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.moments.ImpliedCovariance.set_params"></a>

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

Set estimator parameters.

<a id="skfolio.moments.ImpliedCovariance.set_score_request"></a>

#### set_score_request(\*, X_test='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **X_test** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `X_test` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.LedoitWolf.html.md

<a id="skfolio-moments-ledoitwolf"></a>

# skfolio.moments.LedoitWolf

<a id="skfolio.moments.LedoitWolf"></a>

### *class* skfolio.moments.LedoitWolf(store_precision=True, assume_centered=False, block_size=1000, nearest=True, higham=False, higham_max_iteration=100)

LedoitWolf Covariance Estimator.

Ledoit-Wolf is a particular form of shrinkage, where the shrinkage
coefficient is computed using O. Ledoit and M. Wolf’s formula as
described in [[1]](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#r0d45a9683dee-1).

Read more in [scikit-learn](https://scikit-learn.org/stable/modules/generated/sklearn.covariance.ShrunkCovariance.html).

* **Parameters:**
  **store_precision** *bool, default=True*
  : Specify if the estimated precision is stored.

  **assume_centered** *bool, default=False*
  : If True, data will not be centered before computation.
    Useful when working with data whose mean is almost, but not exactly
    zero.
    If False (default), data will be centered before computation.

  **block_size** *int, default=1000*
  : Size of blocks into which the covariance matrix will be split
    during its Ledoit-Wolf estimation. This is purely a memory
    optimization and does not affect results.

  **nearest** *bool, default=True*
  : If this is set to True, the covariance is replaced by the nearest covariance
    matrix that is positive definite and with a Cholesky decomposition that can be
    computed. The variance is left unchanged.
    A covariance matrix that is not positive definite often occurs in high
    dimensional problems. It can be due to multicollinearity, floating-point
    inaccuracies, or when the number of observations is smaller than the number of
    assets. For more details, see [`cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest).
    The default is `True`.

  **higham** *bool, default=False*
  : If this is set to True, the Higham (2002) algorithm is used to find the
    nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
    above zeros (1e-13). The default is `False` and uses the clipping method as the
    Higham algorithm can be slow for large datasets.

  **higham_max_iteration** *int, default=100*
  : Maximum number of iterations of the Higham (2002) algorithm.
    The default value is `100`.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location, i.e. the estimated mean.

  **precision_** *ndarray of shape (n_assets, n_assets)*
  : Estimated pseudo inverse matrix.
    (stored only if store_precision is True)

  **shrinkage_** *float*
  : Coefficient in the convex combination used for the computation
    of the shrunk estimate. Range is [0, 1].

  **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

| [`error_norm`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf.error_norm)(comp_cov[, norm, scaling, squared])   | Compute the Mean Squared Error between two covariance estimators.          |
|---------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| [`fit`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf.fit)(X[, y])                                      | Fit the Ledoit-Wolf shrunk covariance model to X.                          |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf.get_metadata_routing)()                           | Get metadata routing of this object.                                       |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf.get_params)([deep])                               | Get parameters for this estimator.                                         |
| [`get_precision`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf.get_precision)()                                  | Getter for the precision matrix.                                           |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf.mahalanobis)(X_test)                              | Compute the squared Mahalanobis distance of observations.                  |
| [`score`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf.score)(X_test[, y])                               | Compute the mean log-likelihood of observations under the estimated model. |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf.set_params)(\*\*params)                           | Set the parameters of this estimator.                                      |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf.set_score_request)()                              | No-op.                                                                     |

### Notes

The regularised covariance is:

(1 - shrinkage) \* cov + shrinkage \* mu \* np.identity(n_features)

where mu = trace(cov) / n_features
and shrinkage is given by the Ledoit and Wolf formula (see References)

### References

* <a id='r0d45a9683dee-1'>**[1]**</a> “A Well-Conditioned Estimator for Large-Dimensional Covariance Matrices”. Ledoit and Wolf, Journal of Multivariate Analysis, Volume 88, Issue 2. February 2004, pages 365-41.

<a id="skfolio.moments.LedoitWolf.error_norm"></a>

#### error_norm(comp_cov, norm='frobenius', scaling=True, squared=True)

Compute the Mean Squared Error between two covariance estimators.

* **Parameters:**
  **comp_cov** *array-like of shape (n_features, n_features)*
  : The covariance to compare with.

  **norm** *{“frobenius”, “spectral”}, default=”frobenius”*
  : The type of norm used to compute the error. Available error types:
    - ‘frobenius’ (default): sqrt(tr(A^t.A))
    - ‘spectral’: sqrt(max(eigenvalues(A^t.A))
    where A is the error `(comp_cov - self.covariance_)`.

  **scaling** *bool, default=True*
  : If True (default), the squared error norm is divided by n_features.
    If False, the squared error norm is not rescaled.

  **squared** *bool, default=True*
  : Whether to compute the squared error norm or the error norm.
    If True (default), the squared error norm is returned.
    If False, the error norm is returned.
* **Returns:**
  **result** *float*
  : The Mean Squared Error (in the sense of the Frobenius norm) between
    `self` and `comp_cov` covariance estimators.

<a id="skfolio.moments.LedoitWolf.fit"></a>

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

Fit the Ledoit-Wolf shrunk covariance model to X.

* **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.
* **Returns:**
  **self** *LedoitWolf*
  : Fitted estimator.

<a id="skfolio.moments.LedoitWolf.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.moments.LedoitWolf.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.moments.LedoitWolf.get_precision"></a>

#### get_precision()

Getter for the precision matrix.

* **Returns:**
  **precision_** *array-like of shape (n_features, n_features)*
  : The precision matrix associated to the current covariance object.

<a id="skfolio.moments.LedoitWolf.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.LedoitWolf.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.LedoitWolf.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.

<a id="skfolio.moments.LedoitWolf.set_score_request"></a>

#### set_score_request()

No-op.

Calling this method has no effect.

* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.OAS.html.md

<a id="skfolio-moments-oas"></a>

# skfolio.moments.OAS

<a id="skfolio.moments.OAS"></a>

### *class* skfolio.moments.OAS(store_precision=True, assume_centered=False, nearest=True, higham=False, higham_max_iteration=100)

Oracle Approximating Shrinkage Estimator as proposed in [[1]](https://skfolio.org/generated/skfolio.moments.OAS.html.md#re9a22b087643-1).

Read more in [scikit-learn](https://scikit-learn.org/stable/modules/generated/sklearn.covariance.ShrunkCovariance.html).

* **Parameters:**
  **store_precision** *bool, default=True*
  : Specify if the estimated precision is stored.

  **assume_centered** *bool, default=False*
  : If True, data will not be centered before computation.
    Useful when working with data whose mean is almost, but not exactly
    zero.
    If False (default), data will be centered before computation.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location, i.e. the estimated mean.

  **precision_** *ndarray of shape (n_assets, n_assets)*
  : Estimated pseudo inverse matrix.
    (stored only if store_precision is True)

  **shrinkage_** *float*
  : Coefficient in the convex combination used for the computation
    of the shrunk estimate. Range is [0, 1].

  **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

| [`error_norm`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS.error_norm)(comp_cov[, norm, scaling, squared])   | Compute the Mean Squared Error between two covariance estimators.          |
|---------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| [`fit`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS.fit)(X[, y])                                      | Fit the Oracle Approximating Shrinkage covariance model to X.              |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS.get_metadata_routing)()                           | Get metadata routing of this object.                                       |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS.get_params)([deep])                               | Get parameters for this estimator.                                         |
| [`get_precision`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS.get_precision)()                                  | Getter for the precision matrix.                                           |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS.mahalanobis)(X_test)                              | Compute the squared Mahalanobis distance of observations.                  |
| [`score`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS.score)(X_test[, y])                               | Compute the mean log-likelihood of observations under the estimated model. |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS.set_params)(\*\*params)                           | Set the parameters of this estimator.                                      |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS.set_score_request)()                              | No-op.                                                                     |

### Notes

The regularised covariance is:

(1 - shrinkage) \* cov + shrinkage \* mu \* np.identity(n_features),

where mu = trace(cov) / n_features and shrinkage is given by the OAS formula
(see [[1]](https://skfolio.org/generated/skfolio.moments.OAS.html.md#re9a22b087643-1)).

The shrinkage formulation implemented here differs from Eq. 23 in [[1]](https://skfolio.org/generated/skfolio.moments.OAS.html.md#re9a22b087643-1). In
the original article, formula (23) states that 2/p (p being the number of
features) is multiplied by Trace(cov\*cov) in both the numerator and
denominator, but this operation is omitted because for a large p, the value
of 2/p is so small that it doesn’t affect the value of the estimator.

### References

* <a id='re9a22b087643-1'>**[1]**</a> “Shrinkage algorithms for MMSE covariance estimation”. Chen, Y., Wiesel, A., Eldar, Y. C., & Hero, A. O. IEEE Transactions on Signal Processing, 58(10), 5016-5029, 2010.

<a id="skfolio.moments.OAS.error_norm"></a>

#### error_norm(comp_cov, norm='frobenius', scaling=True, squared=True)

Compute the Mean Squared Error between two covariance estimators.

* **Parameters:**
  **comp_cov** *array-like of shape (n_features, n_features)*
  : The covariance to compare with.

  **norm** *{“frobenius”, “spectral”}, default=”frobenius”*
  : The type of norm used to compute the error. Available error types:
    - ‘frobenius’ (default): sqrt(tr(A^t.A))
    - ‘spectral’: sqrt(max(eigenvalues(A^t.A))
    where A is the error `(comp_cov - self.covariance_)`.

  **scaling** *bool, default=True*
  : If True (default), the squared error norm is divided by n_features.
    If False, the squared error norm is not rescaled.

  **squared** *bool, default=True*
  : Whether to compute the squared error norm or the error norm.
    If True (default), the squared error norm is returned.
    If False, the error norm is returned.
* **Returns:**
  **result** *float*
  : The Mean Squared Error (in the sense of the Frobenius norm) between
    `self` and `comp_cov` covariance estimators.

<a id="skfolio.moments.OAS.fit"></a>

#### fit(X, y=None)

Fit the Oracle Approximating Shrinkage covariance model to X.

* **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.
* **Returns:**
  **self** *OAS*
  : Fitted estimator.

<a id="skfolio.moments.OAS.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.moments.OAS.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.moments.OAS.get_precision"></a>

#### get_precision()

Getter for the precision matrix.

* **Returns:**
  **precision_** *array-like of shape (n_features, n_features)*
  : The precision matrix associated to the current covariance object.

<a id="skfolio.moments.OAS.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.OAS.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.OAS.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.

<a id="skfolio.moments.OAS.set_score_request"></a>

#### set_score_request()

No-op.

Calling this method has no effect.

* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md

<a id="skfolio-moments-regimeadjustedewcovariance"></a>

# skfolio.moments.RegimeAdjustedEWCovariance

<a id="skfolio.moments.RegimeAdjustedEWCovariance"></a>

### *class* skfolio.moments.RegimeAdjustedEWCovariance(half_life=40, corr_half_life=None, hac_lags=None, regime_half_life=None, regime_target=PORTFOLIO, regime_method=FIRST_MOMENT, regime_portfolio_weights=None, regime_multiplier_clip=(0.7, 1.6), regime_min_observations=None, min_observations=None, assume_centered=True, nearest=True, higham=False, higham_max_iteration=100)

Exponentially weighted covariance estimator with regime adjustment via the
Short-Term Volatility Update (STVU) [[1]](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#r9fdb90a74052-1).

This estimator computes an exponentially weighted covariance and applies a scalar
multiplier $\phi_t$ to improve risk calibration when volatility regimes change
more quickly than a plain EWMA can track.

This estimator also supports separate half life for variance and correlation.
Lower half life for variance allows the model to adapt faster to volatility shifts,
while higher half life for correlation enables more stable estimation of
co-movements, which typically require more data for reliable inference and reduces
estimation noise. This choice also aligns with empirical evidence that volatility
tends to mean-revert faster than correlation. Using a lower (more responsive) decay
factor for variance can capture this behavior.

Additionally, this estimator supports optional Newey-West HAC (Heteroskedasticity
and Autocorrelation Consistent) correction via the `hac_lags` parameter. This
adjusts for serial correlation in returns.

The STVU is configured by two parameters:

- [`RegimeAdjustmentTarget`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustmentTarget.html.md#skfolio.moments.RegimeAdjustmentTarget): determines the statistic used to detect volatility regime
  changes (see the enum docstring for details and formulae).
- [`RegimeAdjustmentMethod`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustmentMethod.html.md#skfolio.moments.RegimeAdjustmentMethod): determines how the raw statistic is transformed into the
  regime multiplier $\phi$ (see the enum docstring for details and formulae).

**NaN handling:**

The estimator handles missing data (NaN returns) caused by late listings,
delistings, and holidays using EWMA updates together with `active_mask`. An asset
with `active_mask=True` is treated as active at time $t$. If its return is
finite, the EWMA is updated normally. If its return is NaN, the observation is
treated as a holiday and covariance entries involving this asset are kept unchanged.
An asset with `active_mask=False` is treated as inactive, for example during
pre-listing or post-delisting periods, and covariance entries involving this asset
are set to NaN.

* **Active with valid return**: Normal EWMA update.
* **Active with NaN return (holiday)**: Freeze; covariance entries involving this
  asset are kept unchanged.
* **Inactive** (`active_mask=False`): Covariance entries involving this asset are
  set to NaN.

When `active_mask` is not provided, trailing NaN returns are ambiguous: they could
correspond either to holidays, in which case covariance is frozen, or to inactive
periods, in which case covariance is set to NaN.

The `min_observations` parameter controls a warm-up period: an asset’s
covariance entries remain NaN in the output until it has accumulated enough valid
observations for a reliable estimate.

**Late-listing bias correction:**

The EWMA recursion is initialized at zero for every asset. This guarantees that
the internal covariance state remains positive semi-definite at every step, but
introduces a transient downward scale bias: after $n_i$ observations, the
raw EWMA for asset $i$ is damped by a factor $(1 - \lambda^{n_i})$.
At output time, a per-asset correction removes this bias:

$$
\hat{\Sigma}_{ij} = \frac{S_{ij}}{\sqrt{(1 - \lambda^{n_i})(1 - \lambda^{n_j})}}
$$

where $S$ is the raw internal EWMA. This is a congruence transform
$D S D$ with $D = \text{diag}(1 / \sqrt{1 - \lambda^{n_i}})$,
which preserves positive semi-definiteness while restoring the correct variance
scale.

When `corr_half_life` is provided, the same bias correction is applied independently
to the variance state (using $\lambda$) and the correlation state (using
$\lambda_c$), then the covariance is reconstructed from the corrected
components. The correlation bias correction uses pairwise co-observation counts
rather than per-asset counts, so asynchronous late listings, holidays, and
delistings are corrected at the pair level.

**Estimation universe for STVU:**

An optional `estimation_mask` defines the estimation universe used for the STVU
regime multiplier without affecting pairwise covariance EWMA updates. The STVU
is computed in a one-step-ahead manner: the return observed at time $t$
is standardized by the bias-corrected covariance estimate available at time
$t-1$, and only assets that were already above `min_observations`
before time $t$ contribute to the regime signal. This is important
because the STVU statistic is sensitive to poorly-estimated assets. Noisy
or illiquid assets with unreliable covariance estimates can inflate or
deflate the distance, distorting the regime multiplier for the entire
covariance matrix.

For standard exponentially weighted covariance without regime adjustment,
see [`EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance).

* **Parameters:**
  **half_life** *float, default=40*
  : Half-life of the exponential weights for variance estimation, in number of
    observations.
    <br/>
    When `corr_half_life` is None (default), this also controls the correlation
    estimation, resulting in standard EWMA covariance:
    $\Sigma_t = \lambda \Sigma_{t-1} + (1-\lambda) r_t r_t^\top$
    <br/>
    When `corr_half_life` is provided, variance and correlation are updated
    with different half-lives to capture their different dynamics.
    <br/>
    The half-life controls how quickly older observations lose their influence:
    * **Larger half-life**: More stable estimates, slower to adapt (robust to noise)
    * **Smaller half-life**: More responsive estimates, faster to adapt (sensitive to noise)
    <br/>
    The decay factor $\lambda$ is computed as:
    $\lambda = 2^{-1/\text{half-life}}$
    <br/>
    For example:
    : * half-life = 40: $\lambda \approx 0.983$
      * half-life = 23: $\lambda \approx 0.970$
      * half-life = 11: $\lambda \approx 0.939$
      * half-life = 6: $\lambda \approx 0.891$
    <br/>
    #### NOTE
    For portfolio optimization, larger half-lives (>= 20) are generally
    preferred to avoid excessive turnover from estimation noise.

  **corr_half_life** *float, optional*
  : Half-life for correlation estimation, in number of observations.
    <br/>
    If None (default), the same `half_life` is used for both variance and
    correlation, resulting in standard EWMA covariance.
    <br/>
    If provided, enables separate half-lives: `half_life` governs variance
    and `corr_half_life` governs correlation. This is useful because volatility
    typically mean-reverts faster than correlation, so using a smaller (more
    responsive) half-life for variance can better capture regime changes.

  **hac_lags** *int, optional*
  : Number of lags for Newey-West HAC (Heteroskedasticity and Autocorrelation
    Consistent) correction. If None (default), no HAC correction is applied.
    <br/>
    When enabled, the covariance update uses HAC-adjusted cross-products instead
    of simple outer products, accounting for autocorrelation in returns:
    $$
    r_t r_t^T + \sum_{j=1}^{L} w_j (r_t r_{t-j}^T + r_{t-j} r_t^T)
    $$
    <br/>
    where $w_j = 1 - j/(L+1)$ is the Bartlett kernel weight.
    <br/>
    Typical values:
    : * Daily equity data: 3-5 lags (weak autocorrelation from microstructure)
      * High-frequency data: 5-10 lags (stronger autocorrelation)
      * Monthly data: 1-2 lags
    <br/>
    Must be a positive integer if specified.

  **regime_half_life** *float, optional*
  : Half-life for smoothing the volatility regime signal, in number of
    observations.
    <br/>
    The regime signal is built from one-step-ahead standardized risk
    statistics and then transformed into the multiplier $\phi$
    according to `regime_target` and `regime_method`. A shorter
    `regime_half_life` makes the multiplier react faster to abrupt
    changes in realized risk; a longer one produces a smoother, slower
    moving adjustment.
    <br/>
    If None (default), it is automatically calibrated as:
    $\text{regime-half-life} = 0.5 \times \text{half-life}$
    <br/>
    This makes the STVU more responsive (shorter half-life) than the covariance,
    allowing it to quickly rescale risk when realized volatility deviates from
    the slower EWMA estimate.

  **regime_target** *RegimeAdjustmentTarget, default=RegimeAdjustmentTarget.PORTFOLIO*
  : Target dimension used to calibrate the short-term volatility update:
    - `PORTFOLIO`: Portfolio variance $((w^T r)^2/(w^T \Sigma w))$
    - `DIAGONAL`: Individual volatilities $(\sum_i (r_i/\sigma_i)^2)$
    - `MAHALANOBIS`: Full covariance $(r^T \Sigma^{-1} r)$

  **regime_method** *RegimeAdjustmentMethod, default=RegimeAdjustmentMethod.FIRST_MOMENT*
  : Method used to transform the update statistic into the volatility multiplier $\phi$:
    - `LOG`: Robust to outliers (log compresses extremes)
    - `FIRST_MOMENT`: Calibrates the first moment of the standardized risk
      statistic
    - `RMS`: $\chi^2$ calibration (sensitive to extremes)

  **regime_portfolio_weights** *array-like of shape (n_assets,) or (n_portfolios, n_assets) or None, default=None*
  : Portfolio weights used by the STVU `PORTFOLIO` target. Only used when
    `regime_target=RegimeAdjustmentTarget.PORTFOLIO`.
    <br/>
    If None (default), uses inverse-volatility weights, which neutralizes asset
    volatility dispersion so high-volatility assets don’t dominate the calibration
    statistic. These weights are recomputed dynamically as variances evolve.
    <br/>
    If a 1D array is provided, a single static portfolio is used. If a 2D array of
    shape `(n_portfolios, n_assets)` is provided, the STVU statistic is computed
    independently for each portfolio, transformed, and then averaged into a single
    regime signal. This calibrates the covariance along multiple traded directions
    without being affected by noise in uninvestable eigenvector directions (unlike
    `MAHALANOBIS`).
    <br/>
    Weights are automatically normalized so each row sums to 1.
    <br/>
    For equal-weight calibration, pass
    `regime_portfolio_weights=np.ones(n_assets)/n_assets`.

  **regime_multiplier_clip** *tuple[float, float] or None, default=(0.7, 1.6)*
  : Clip $\phi$ to avoid extreme swings in the regime multiplier.
    Set to None to disable clipping. The multiplier is applied to the covariance
    as $\phi^2 \Sigma$. With the default bounds, the covariance scale remains
    between $0.7^2 = 0.49$ and $1.6^2 = 2.56$.

  **regime_min_observations** *int, optional*
  : Minimum number of one-step-ahead comparisons before enabling STVU.
    If insufficient data, STVU defaults to 1.0 (no adjustment).
    <br/>
    If None (default), it is automatically set to `int(regime_half_life)`,
    ensuring the STVU EWMA has seen roughly one half-life of data before being
    applied.

  **min_observations** *int, optional*
  : Minimum number of valid observations per asset before its covariance entries
    are considered reliable and exposed in the output `covariance_`. Until this
    threshold is reached, the asset’s covariance entries remain NaN.
    <br/>
    This warm-up prevents noisy estimates from a few initial observations from being
    used by downstream optimizers.
    <br/>
    The default (`None`) uses `int(max(half_life, corr_half_life))` as the
    threshold when `corr_half_life` is set, or `int(half_life)` otherwise. This
    ensures both variance and correlation bias-correction factors have decayed to
    at most 50%. Set to 1 to disable warm-up entirely.

  **assume_centered** *bool, default=True*
  : If True (default), the EWMA update uses raw returns without demeaning. This
    is the standard convention for EWMA covariance estimation in finance.
    If False, returns are demeaned using an EWMA mean estimate before computing
    the covariance update, and `location_` tracks the EWMA mean.

  **nearest** *bool, default=True*
  : If this is set to True, the covariance is replaced by the nearest covariance
    matrix that is positive definite and with a Cholesky decomposition that can be
    computed. The variance is left unchanged.
    The default is `True`.

  **higham** *bool, default=False*
  : If this is set to True, the Higham (2002) algorithm is used to find the
    nearest PD covariance, otherwise the eigenvalues are clipped to a threshold
    above zeros (1e-13). The default is `False` and uses the clipping method as
    the Higham algorithm can be slow for large datasets.

  **higham_max_iteration** *int, default=100*
  : Maximum number of iterations of the Higham (2002) algorithm.
    The default value is `100`.
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance matrix. Contains NaN for assets that are inactive
    or have not yet accumulated `min_observations` valid observations.

  **regime_multiplier_** *float*
  : The volatility regime adjustment factor applied.
    Equal to 1.0 if insufficient data.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location (mean). If `assume_centered=True`, this is zeros.
    Otherwise, it tracks the EWMA mean of returns. Contains NaN for inactive
    assets.

  **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`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance.fit)(X[, y, active_mask, estimation_mask])         | Fit the Regime-Adjusted Exponentially Weighted Covariance estimator.                     |
|----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance.get_metadata_routing)()                            | Get metadata routing of this object.                                                     |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance.get_params)([deep])                                | Get parameters for this estimator.                                                       |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance.mahalanobis)(X_test)                               | Compute the squared Mahalanobis distance of observations.                                |
| [`partial_fit`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance.partial_fit)(X[, y, active_mask, estimation_mask]) | Incrementally fit the Regime-Adjusted EW Covariance estimator.                           |
| [`score`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance.score)(X_test[, y])                                | Compute the mean log-likelihood of observations under the estimated model.               |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance.set_fit_request)(\*[, active_mask, ...])           | Configure whether metadata should be requested to be passed to the `fit` method.         |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance.set_params)(\*\*params)                            | Set the parameters of this estimator.                                                    |
| [`set_partial_fit_request`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance.set_partial_fit_request)(\*[, active_mask, ...])   | Configure whether metadata should be requested to be passed to the `partial_fit` method. |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance.set_score_request)(\*[, X_test])                   | Configure whether metadata should be requested to be passed to the `score` method.       |

#### SEE ALSO
[Online Covariance Forecast Evaluation](https://skfolio.org/auto_examples/online_learning/plot_1_online_covariance_forecast_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-1-online-covariance-forecast-evaluation-py)
: Online covariance forecast evaluation with `EWCovariance` and `RegimeAdjustedEWCovariance`.

[Online Covariance Hyperparameter Tuning](https://skfolio.org/auto_examples/online_learning/plot_2_online_hyperparameter_tuning.html.md#sphx-glr-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py)
: Online covariance hyperparameter tuning with `RegimeAdjustedEWCovariance`.

[Online Evaluation of Portfolio Optimization](https://skfolio.org/auto_examples/online_learning/plot_3_online_portfolio_optimization_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-3-online-portfolio-optimization-evaluation-py)
: Online evaluation of portfolio optimization using `MeanRisk` with exponentially weighted moments.

### Notes

The STVU compares predicted versus realized risk using a one-step-ahead
standardized statistic $d^2_{t+1}$ computed from the covariance
estimate at time $t$ and the return observed at time $t+1$.
The exact statistic depends on `regime_target`:

* `PORTFOLIO` calibrates covariance along one or more portfolio
  directions.
* `DIAGONAL` calibrates the diagonal risk scale and ignores
  correlations.
* `MAHALANOBIS` calibrates the full covariance structure.

Under correct calibration, the transformed statistic has unit scale in
expectation. Persistent values above that level imply realized risk is
higher than predicted, so $\phi > 1$ scales the covariance up.
Persistent values below that level imply over-prediction, so
$\phi < 1$ scales it down.

This approach is related to volatility updating in multivariate GARCH
models, but implemented here as a multiplicative adjustment on top of an
EWMA covariance estimator.

### References

* <a id='r9fdb90a74052-1'>**[1]**</a> “The Elements of Quantitative Investing”, Wiley Finance, Giuseppe Paleologo (2025).
* <a id='r9fdb90a74052-2'>**[2]**</a> “Multivariate exponentially weighted moving covariance matrix”, Technometrics, Hawkins & Maboudou-Tchao (2008).
* <a id='r9fdb90a74052-3'>**[3]**</a> “Dynamic conditional correlation: A simple class of multivariate GARCH models”, Journal of Business & Economic Statistics, Engle (2002).
* <a id='r9fdb90a74052-4'>**[4]**</a> “Computing the nearest correlation matrix - A problem from finance”, IMA Journal of Numerical Analysis, Higham (2002)
* <a id='r9fdb90a74052-5'>**[5]**</a> “An Introduction to Multivariate Statistical Analysis”, Wiley, Anderson (2003).

### Examples

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.moments import RegimeAdjustedEWCovariance, RegimeAdjustmentTarget, RegimeAdjustmentMethod
>>> from skfolio.preprocessing import prices_to_returns
>>> import numpy as np
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # Portfolio target with inverse-vol weights and FIRST_MOMENT method (default)
>>> model = RegimeAdjustedEWCovariance(half_life=23)
>>> model.fit(X)
RegimeAdjustedEWCovariance(half_life=23)
>>> print(model.regime_multiplier_)
0.869...
>>>
>>> # DIAGONAL target (individual asset volatilities)
>>> model2 = RegimeAdjustedEWCovariance(
...     regime_target=RegimeAdjustmentTarget.DIAGONAL,
...     regime_method=RegimeAdjustmentMethod.RMS,
... )
>>> model2.fit(X)
RegimeAdjustedEWCovariance(regime_method=RMS, regime_target=DIAGONAL)
>>>
>>> # Mahalanobis target (full covariance structure)
>>> model_maha = RegimeAdjustedEWCovariance(
...     regime_target=RegimeAdjustmentTarget.MAHALANOBIS,
...     regime_method=RegimeAdjustmentMethod.FIRST_MOMENT,
... )
>>> model_maha.fit(X)
RegimeAdjustedEWCovariance(regime_target=MAHALANOBIS)
>>>
>>> # Portfolio target with equal weights
>>> n_assets = X.shape[1]
>>> model_equal = RegimeAdjustedEWCovariance(
...     regime_target=RegimeAdjustmentTarget.PORTFOLIO,
...     regime_portfolio_weights=np.ones(n_assets) / n_assets,
... )
>>> model_equal.fit(X)
RegimeAdjustedEWCovariance(...)
>>>
>>> # With Newey-West HAC correction
>>> model_hac = RegimeAdjustedEWCovariance(
...     half_life=23,
...     hac_lags=5
... )
>>> model_hac.fit(X)
RegimeAdjustedEWCovariance(hac_lags=5, half_life=23)
```

<a id="skfolio.moments.RegimeAdjustedEWCovariance.fit"></a>

#### fit(X, y=None, \*, active_mask=None, estimation_mask=None)

Fit the Regime-Adjusted Exponentially Weighted Covariance estimator.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. May contain NaN for missing data
    (holidays, late listings, delistings).

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

  **active_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset is structurally active at
    each observation. Use this to distinguish between holidays
    (`active_mask=True` and NaN return: covariance is frozen) and
    inactive periods such as pre-listing or post-delisting
    (`active_mask=False`: covariance is set to NaN). If `None`
    (default), all pairs are assumed active.

  **estimation_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating which active assets should belong to the
    estimation universe for the STVU statistic computation on each day.
    - If None (default), all active assets with finite returns and finite
      covariance estimates are used.
    - If provided, only assets where the mask is True contribute to the
      regime multiplier calculation.
    <br/>
    Pairwise covariance EWMA updates still use all active assets with valid
    observations; this mask only affects the STVU regime multiplier calculation.
    <br/>
    This is important because the STVU statistic is sensitive to
    poorly-estimated assets. Noisy or illiquid assets with unreliable covariance
    estimates can inflate or deflate the distance, distorting the regime
    multiplier for the entire covariance matrix.
    <br/>
    Use cases:
    : * Focus on liquid assets to reduce noise in regime detection
      * Exclude recently-listed assets whose covariance is still poorly
        estimated
      * Match the estimation universe used in a factor model
* **Returns:**
  **self** *RegimeAdjustedEWCovariance*
  : Fitted estimator.

<a id="skfolio.moments.RegimeAdjustedEWCovariance.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.moments.RegimeAdjustedEWCovariance.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.moments.RegimeAdjustedEWCovariance.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.RegimeAdjustedEWCovariance.partial_fit"></a>

#### partial_fit(X, y=None, \*, active_mask=None, estimation_mask=None)

Incrementally fit the Regime-Adjusted EW Covariance estimator.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. May contain NaN for missing data (holidays,
    late listings, delistings).

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

  **active_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset is structurally active at each
    observation. Use this to distinguish between holidays (`active_mask=True`
    and NaN return: covariance is frozen) and inactive periods such as
    pre-listing or post-delisting (`active_mask=False`: covariance is set to
    NaN). If `None` (default), all pairs are assumed active.

  **estimation_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating which active assets should belong to the
    estimation universe for the STVU statistic computation on each day.
    See `fit` for details.
* **Returns:**
  **self** *RegimeAdjustedEWCovariance*
  : Fitted estimator.

<a id="skfolio.moments.RegimeAdjustedEWCovariance.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.RegimeAdjustedEWCovariance.set_fit_request"></a>

#### set_fit_request(\*, active_mask='$UNCHANGED$', estimation_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **active_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `active_mask` parameter in `fit`.

  **estimation_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `estimation_mask` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.moments.RegimeAdjustedEWCovariance.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.

<a id="skfolio.moments.RegimeAdjustedEWCovariance.set_partial_fit_request"></a>

#### set_partial_fit_request(\*, active_mask='$UNCHANGED$', estimation_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `partial_fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `partial_fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `partial_fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **active_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `active_mask` parameter in `partial_fit`.

  **estimation_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `estimation_mask` parameter in `partial_fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.moments.RegimeAdjustedEWCovariance.set_score_request"></a>

#### set_score_request(\*, X_test='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `score` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `score` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `score`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **X_test** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `X_test` parameter in `score`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.RegimeAdjustedEWVariance.html.md

<a id="skfolio-moments-regimeadjustedewvariance"></a>

# skfolio.moments.RegimeAdjustedEWVariance

<a id="skfolio.moments.RegimeAdjustedEWVariance"></a>

### *class* skfolio.moments.RegimeAdjustedEWVariance(half_life=40, hac_lags=None, regime_method=FIRST_MOMENT, regime_half_life=None, regime_multiplier_clip=(0.7, 1.6), regime_min_observations=None, min_observations=None, assume_centered=True)

Exponentially weighted variance estimator with regime adjustment via the
Short-Term Volatility Update (STVU) [[1]](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#r1cff04c74aab-1).

This is the variance-only counterpart of
`RegimeAdjustedEWCovariance`, assuming zero
correlation. This is appropriate when:

* Estimating **idiosyncratic (specific) risk** in factor models, where residual
  returns are uncorrelated by construction
* Working with **orthogonalized** or **uncorrelated** return series
* The full covariance structure is not needed or is constructed separately

This estimator computes per-asset exponentially weighted variances and applies a
scalar multiplier $\phi_t$ to improve risk calibration when volatility
regimes change more quickly than a plain EWMA can track.

Additionally, this estimator supports optional Newey-West HAC (Heteroskedasticity
and Autocorrelation Consistent) correction via the `hac_lags` parameter. This
adjusts for serial correlation in returns.

**NaN handling:**

The estimator handles missing data (NaN returns) caused by late listings,
delistings, and holidays using EWMA updates together with `active_mask`.
An asset with `active_mask=True` is treated as active at time $t$.
If its return is finite, the EWMA is updated normally. If its return is
NaN, the observation is treated as a holiday and the previous variance is
kept. An asset with `active_mask=False` is treated as inactive, for
example during pre-listing or post-delisting periods, and its variance is
set to NaN.

* **Active with valid return**: Normal EWMA update.
* **Active with NaN return (holiday)**: Freeze; the previous variance is
  kept.
* **Inactive** (`active_mask=False`): Variance is set to NaN.

When `active_mask` is not provided, trailing NaN returns are treated as
holidays and the variance is frozen. When an asset becomes active again
after an inactive period, its variance restarts from a zero prior and
receives per-asset bias correction at output time.

**Late-listing bias correction:**

The EWMA recursion is initialized at zero for every asset. This
zero-initialization introduces a transient downward scale bias: after
$n_i$ valid observations, the raw EWMA weights sum to
$(1 - \lambda^{n_i})$ instead of 1. At output time, a per-asset
correction removes this bias:

$$
\hat{\sigma}^2_i = \frac{S_i}{1 - \lambda^{n_i}}
$$

where $S_i$ is the raw internal EWMA accumulator. For assets with a
long history, the correction is negligible ($\lambda^{n_i} \to 0$).

The `min_observations` parameter controls a warm-up period: an asset’s
variance estimate remains NaN in the output until it has accumulated enough
valid observations for a reliable estimate.

**Estimation universe for STVU:**

An optional `estimation_mask` defines the estimation universe used for the
cross-sectional STVU statistic without affecting per-asset EWMA variance
updates. The STVU is computed in a one-step-ahead manner: the return
observed at time $t$ is standardized by the bias-corrected variance
estimate available at time $t-1$, and only assets that were already
above `min_observations` before time $t$ contribute to the regime
signal. This is important because the STVU multiplier is derived from a
cross-sectional average of standardized squared returns: noisy or illiquid
assets with unreliable variance estimates can inflate or deflate the
statistic, distorting the regime multiplier applied to all variances.

* **Parameters:**
  **half_life** *float, default=40*
  : Half-life of the exponential weights in number of observations.
    <br/>
    The half-life controls how quickly older observations lose their influence:
    * **Larger half-life**: More stable estimates, slower to adapt (robust to noise)
    * **Smaller half-life**: More responsive estimates, faster to adapt (sensitive to noise)
    <br/>
    The decay factor $\lambda$ is computed as:
    $\lambda = 2^{-1/\text{half-life}}$
    <br/>
    For example:
    : * half-life = 40: $\lambda \approx 0.983$
      * half-life = 23: $\lambda \approx 0.970$
      * half-life = 11: $\lambda \approx 0.939$
      * half-life = 6: $\lambda \approx 0.891$
    <br/>
    #### NOTE
    For portfolio optimization, larger half-lives (>= 20) are generally
    preferred to avoid excessive turnover from estimation noise.

  **hac_lags** *int, optional*
  : Number of lags for Newey-West HAC (Heteroskedasticity and Autocorrelation
    Consistent) correction. If None (default), no HAC correction is applied.
    <br/>
    When enabled, the variance update uses HAC-adjusted squared returns instead
    of simple squared returns, accounting for autocorrelation:
    $$
    \text{hac\_var}_i = r_{i,t}^2 + 2 \sum_{j=1}^{L} w_j \cdot r_{i,t} \cdot r_{i,t-j}
    $$
    <br/>
    where $w_j = 1 - j/(L+1)$ is the Bartlett kernel weight.
    <br/>
    Typical values:
    : * Daily equity data: 3-5 lags (weak autocorrelation from microstructure)
      * High-frequency data: 5-10 lags (stronger autocorrelation)
      * Monthly data: 1-2 lags
    <br/>
    Must be a positive integer if specified.

  **regime_method** *RegimeAdjustmentMethod, default=RegimeAdjustmentMethod.FIRST_MOMENT*
  : Method used to transform the update statistic into the volatility multiplier $\phi$:
    - `LOG`: Robust to outliers (log compresses extremes)
    - `FIRST_MOMENT`: Calibrates the first moment of the standardized risk
      statistic
    - `RMS`: $\chi^2$ calibration (sensitive to extremes)

  **regime_half_life** *float, optional*
  : Half-life for smoothing the volatility regime signal, in number of
    observations.
    <br/>
    The regime signal is built from one-step-ahead standardized returns
    and then transformed into the multiplier $\phi$ according to
    `regime_method`. A shorter `regime_half_life` makes the multiplier
    react faster to abrupt changes in realized risk. A longer one
    produces a smoother, slower moving adjustment.
    <br/>
    If None (default), it is automatically calibrated as:
    $\text{regime-half-life} = 0.5 \times \text{half-life}$
    <br/>
    This makes the STVU more responsive (shorter half-life) than the variance,
    allowing it to quickly rescale risk when realized volatility deviates from
    the slower EWMA estimate.

  **regime_multiplier_clip** *tuple[float, float] or None, default=(0.7, 1.6)*
  : Clip to avoid extreme swings in the regime multiplier.
    Set to None to disable clipping. The multiplier is applied to the covariance
    as $\phi^2 \Sigma$.
    <br/>
    Default bounds rationale:
    : * Lower bound (0.7): Limits volatility reduction to 30%, equivalent to a
        minimum variance scale of $0.7^2 = 0.49$
      * Upper bound (1.6): Limits volatility increase to 60%, equivalent to a
        maximum variance scale of $1.6^2 = 2.56$

  **regime_min_observations** *int, optional*
  : Minimum number of one-step-ahead comparisons before enabling STVU.
    If insufficient data, STVU defaults to 1.0 (no adjustment).
    <br/>
    If None (default), it is automatically set to
    `int(regime_half_life)`, ensuring the STVU EWMA has seen roughly one
    half-life of data before being applied.

  **min_observations** *int, optional*
  : Minimum number of valid observations per asset before its variance estimate
    is considered reliable and exposed in the output `variance_`. Until this
    threshold is reached, the asset’s variance estimate remains NaN.
    <br/>
    The default (`None`) uses `int(half_life)` as the threshold, ensuring
    the late-listing initialization bias has decayed to at most 50%. Set to
    1 to disable warm-up entirely.

  **assume_centered** *bool, default=True*
  : If True (default), the EWMA update uses raw returns without demeaning. This
    is the standard convention for EWMA variance estimation in finance.
    If False, returns are demeaned using an EWMA mean estimate before computing
    the variance update, and `location_` tracks the EWMA mean.
    <br/>
    #### NOTE
    For factor model residuals, centering is typically not needed as residuals
    should already have zero mean by construction. Set to False only if
    residuals exhibit persistent non-zero means.
* **Attributes:**
  **variance_** *ndarray of shape (n_assets,)*
  : Estimated regime-adjusted variances.

  **regime_multiplier_** *float*
  : The volatility regime adjustment factor applied.
    Equal to 1.0 if insufficient data or no regime adjustment needed.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location, i.e. the estimated mean.
    When `assume_centered=True`, this is zero.
    When `assume_centered=False`, this is the EWMA mean estimate.

  **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`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance.fit)(X[, y, estimation_mask, active_mask])         | Fit the Regime-Adjusted Exponentially Weighted Variance estimator.                       |
|----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance.get_metadata_routing)()                            | Get metadata routing of this object.                                                     |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance.get_params)([deep])                                | Get parameters for this estimator.                                                       |
| [`partial_fit`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance.partial_fit)(X[, y, estimation_mask, active_mask]) | Incrementally fit the estimator with new observations.                                   |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance.set_fit_request)(\*[, active_mask, ...])           | Configure whether metadata should be requested to be passed to the `fit` method.         |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance.set_params)(\*\*params)                            | Set the parameters of this estimator.                                                    |
| [`set_partial_fit_request`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance.set_partial_fit_request)(\*[, active_mask, ...])   | Configure whether metadata should be requested to be passed to the `partial_fit` method. |

### References

* <a id='r1cff04c74aab-1'>**[1]**</a> “The Elements of Quantitative Investing”, Wiley Finance, Giuseppe Paleologo (2025).
* <a id='r1cff04c74aab-2'>**[2]**</a> “Multivariate exponentially weighted moving covariance matrix”, Technometrics, Hawkins & Maboudou-Tchao (2008).

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.moments import RegimeAdjustedEWVariance, RegimeAdjustmentMethod
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>> # Standard EWMA with STVU
>>> model = RegimeAdjustedEWVariance(half_life=23)
>>> model.fit(X)
RegimeAdjustedEWVariance(half_life=23)
>>> print(model.regime_multiplier_)
0.810...
>>>
>>> # With LOG method for robustness to outliers
>>> model2 = RegimeAdjustedEWVariance(
...     half_life=11,
...     regime_method=RegimeAdjustmentMethod.LOG
... )
>>> model2.fit(X)
RegimeAdjustedEWVariance(half_life=11, regime_method=LOG)
>>>
>>> # With Newey-West HAC correction for autocorrelation
>>> model3 = RegimeAdjustedEWVariance(
...     half_life=23,
...     hac_lags=5    # 5-lag Newey-West correction
... )
>>> model3.fit(X)
RegimeAdjustedEWVariance(hac_lags=5, half_life=23)
>>>
>>> # With an estimation universe focused on specific assets
>>> estimation_mask = np.ones((len(X), X.shape[1]), dtype=bool)
>>> estimation_mask[:, :5] = False  # Exclude first 5 assets from STVU
>>> model4 = RegimeAdjustedEWVariance(half_life=23)
>>> model4.fit(X, estimation_mask=estimation_mask)
RegimeAdjustedEWVariance(half_life=23)
```

<a id="skfolio.moments.RegimeAdjustedEWVariance.fit"></a>

#### fit(X, y=None, \*, estimation_mask=None, active_mask=None)

Fit the Regime-Adjusted Exponentially Weighted Variance estimator.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Idiosyncratic (specific) residual returns per asset, typically obtained
    from a factor model regression. NaN values are allowed and handled robustly.

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

  **estimation_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating which active assets should belong to the
    estimation universe for the cross-sectional STVU statistic on each day.
    - If None (default), all active assets with finite returns are used.
    - If provided, only assets where the mask is True contribute to the
      regime multiplier calculation on that day.
    <br/>
    Per-asset EWMA variance updates still use all active assets with finite
    returns; this parameter only affects the cross-sectional regime adjustment
    calculation.
    <br/>
    Use cases:
    : * Focus on liquid assets to reduce noise from thinly traded securities
      * Exclude assets with suspected data quality issues
      * Match the estimation universe used in downstream models

  **active_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset is structurally active at each
    observation. Use this to distinguish between holidays (`active_mask=True`
    and NaN return: variance is frozen) and inactive periods such as pre-listing
    or post-delisting (`active_mask=False`: variance is set to NaN). If `None`
    (default), all pairs are assumed active and NaN returns are treated as
    holidays (variance frozen).
    <br/>
    When an asset becomes active again after an inactive period, its variance
    restarts from a zero prior with per-asset bias correction.
* **Returns:**
  **self** *RegimeAdjustedEWVariance*
  : Fitted estimator.

<a id="skfolio.moments.RegimeAdjustedEWVariance.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.moments.RegimeAdjustedEWVariance.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.moments.RegimeAdjustedEWVariance.partial_fit"></a>

#### partial_fit(X, y=None, \*, estimation_mask=None, active_mask=None)

Incrementally fit the estimator with new observations.

This method allows online/streaming updates to the variance estimates.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Idiosyncratic (specific) residual returns per asset.
    NaN values are allowed and handled robustly.

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

  **estimation_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating which active assets belong to the estimation
    universe for the cross-sectional STVU statistic on each day. See
    `fit` for details.

  **active_mask** *array-like of shape (n_observations, n_assets), optional*
  : Boolean mask indicating whether each asset is structurally active at
    each observation. See `fit` for details.
* **Returns:**
  **self** *RegimeAdjustedEWVariance*
  : Fitted estimator.

<a id="skfolio.moments.RegimeAdjustedEWVariance.set_fit_request"></a>

#### set_fit_request(\*, active_mask='$UNCHANGED$', estimation_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **active_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `active_mask` parameter in `fit`.

  **estimation_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `estimation_mask` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.moments.RegimeAdjustedEWVariance.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.

<a id="skfolio.moments.RegimeAdjustedEWVariance.set_partial_fit_request"></a>

#### set_partial_fit_request(\*, active_mask='$UNCHANGED$', estimation_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `partial_fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `partial_fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `partial_fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **active_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `active_mask` parameter in `partial_fit`.

  **estimation_mask** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `estimation_mask` parameter in `partial_fit`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.RegimeAdjustmentMethod.html.md

<a id="skfolio-moments-regimeadjustmentmethod"></a>

# skfolio.moments.RegimeAdjustmentMethod

<a id="skfolio.moments.RegimeAdjustmentMethod"></a>

### *class* skfolio.moments.RegimeAdjustmentMethod(\*values)

Transformation used to map the STVU statistic to the volatility multiplier.

Determines how the raw STVU statistic $d^2$ is transformed into the
regime multiplier $\phi$ applied by the estimator.

| Method       | Multiplier $\phi$                                                            | Characteristics                                                                                                 |
|--------------|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| LOG          | $\phi = \exp(\text{EWMA}(\log d^2 - \kappa)/2)$ where $\kappa = E[\log d^2]$ | Robust to outliers (log compresses extremes).                                                                   |
| FIRST_MOMENT | $\phi = \text{EWMA}(d / \mathbb{E}[d])$                                      | Calibrates the first moment of the standardized risk statistic.<br/>More robust than RMS, less robust than LOG. |
| RMS          | $\phi = \sqrt{\text{EWMA}(d^2/n)}$                                           | $\chi^2$ calibration. Sensitive to outliers (RMS ≥ mean).                                                       |

### References

* <a id='r8bf02d06c694-1'>**[1]**</a> “The Elements of Quantitative Investing”, Wiley Finance, Giuseppe Paleologo (2025).

<a id="skfolio.moments.RegimeAdjustmentMethod.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.moments.RegimeAdjustmentTarget.html.md

<a id="skfolio-moments-regimeadjustmenttarget"></a>

# skfolio.moments.RegimeAdjustmentTarget

<a id="skfolio.moments.RegimeAdjustmentTarget"></a>

### *class* skfolio.moments.RegimeAdjustmentTarget(\*values)

Target dimension used to calibrate the short-term volatility update (STVU).

Determines what statistic is computed to detect volatility regime changes.

The STVU uses a statistic $d^2$ that measures the discrepancy between predicted
and realized risk. The target determines which aspect of the covariance
matrix is calibrated.

| Target      | Formula                                    | What it calibrates                                                       |
|-------------|--------------------------------------------|--------------------------------------------------------------------------|
| PORTFOLIO   | $d^2 = n \cdot (w^T r)^2 / (w^T \Sigma w)$ | Portfolio variance along a single aggregated direction                   |
| DIAGONAL    | $d^2 = \sum_i (r_i / \sigma_i)^2$          | Individual asset volatilities across the universe (ignores correlations) |
| MAHALANOBIS | $d^2 = r^T \Sigma^{-1} r$                  | Full covariance structure (all eigenvalue directions)                    |

#### NOTE
`PORTFOLIO` (the default) calibrates the covariance along economically
relevant directions. `MAHALANOBIS` weights all eigenvector directions
equally, including the smallest-eigenvalue directions whose estimates
are typically the least stable. In practice this can make the regime
multiplier sensitive to returns along poorly estimated directions
that carry little portfolio relevance.

### References

* <a id='r75698832297b-1'>**[1]**</a> “The Elements of Quantitative Investing”, Wiley Finance, Giuseppe Paleologo (2025).

<a id="skfolio.moments.RegimeAdjustmentTarget.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.moments.ShrunkCovariance.html.md

<a id="skfolio-moments-shrunkcovariance"></a>

# skfolio.moments.ShrunkCovariance

<a id="skfolio.moments.ShrunkCovariance"></a>

### *class* skfolio.moments.ShrunkCovariance(store_precision=True, assume_centered=False, shrinkage=0.1, nearest=True, higham=False, higham_max_iteration=100)

Covariance estimator with shrinkage.

Read more in [scikit-learn](https://scikit-learn.org/stable/modules/generated/sklearn.covariance.ShrunkCovariance.html).

* **Parameters:**
  **store_precision** *bool, default=True*
  : Specify if the estimated precision is stored.

  **assume_centered** *bool, default=False*
  : If True, data will not be centered before computation.
    Useful when working with data whose mean is almost, but not exactly
    zero.
    If False (default), data will be centered before computation.

  **shrinkage** *float, default=0.1*
  : Coefficient in the convex combination used for the computation
    of the shrunk estimate. Range is [0, 1].
* **Attributes:**
  **covariance_** *ndarray of shape (n_assets, n_assets)*
  : Estimated covariance.

  **location_** *ndarray of shape (n_assets,)*
  : Estimated location, i.e. the estimated mean.

  **precision_** *ndarray of shape (n_assets, n_assets)*
  : Estimated pseudo inverse matrix.
    (stored only if store_precision is True)

  **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

| [`error_norm`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance.error_norm)(comp_cov[, norm, scaling, squared])   | Compute the Mean Squared Error between two covariance estimators.          |
|---------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| [`fit`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance.fit)(X[, y])                                      | Fit the shrunk covariance model to X.                                      |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance.get_metadata_routing)()                           | Get metadata routing of this object.                                       |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance.get_params)([deep])                               | Get parameters for this estimator.                                         |
| [`get_precision`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance.get_precision)()                                  | Getter for the precision matrix.                                           |
| [`mahalanobis`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance.mahalanobis)(X_test)                              | Compute the squared Mahalanobis distance of observations.                  |
| [`score`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance.score)(X_test[, y])                               | Compute the mean log-likelihood of observations under the estimated model. |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance.set_params)(\*\*params)                           | Set the parameters of this estimator.                                      |
| [`set_score_request`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance.set_score_request)()                              | No-op.                                                                     |

### Notes

The regularized covariance is given by:

(1 - shrinkage) \* cov + shrinkage \* mu \* np.identity(n_features)

where mu = trace(cov) / n_features

<a id="skfolio.moments.ShrunkCovariance.error_norm"></a>

#### error_norm(comp_cov, norm='frobenius', scaling=True, squared=True)

Compute the Mean Squared Error between two covariance estimators.

* **Parameters:**
  **comp_cov** *array-like of shape (n_features, n_features)*
  : The covariance to compare with.

  **norm** *{“frobenius”, “spectral”}, default=”frobenius”*
  : The type of norm used to compute the error. Available error types:
    - ‘frobenius’ (default): sqrt(tr(A^t.A))
    - ‘spectral’: sqrt(max(eigenvalues(A^t.A))
    where A is the error `(comp_cov - self.covariance_)`.

  **scaling** *bool, default=True*
  : If True (default), the squared error norm is divided by n_features.
    If False, the squared error norm is not rescaled.

  **squared** *bool, default=True*
  : Whether to compute the squared error norm or the error norm.
    If True (default), the squared error norm is returned.
    If False, the error norm is returned.
* **Returns:**
  **result** *float*
  : The Mean Squared Error (in the sense of the Frobenius norm) between
    `self` and `comp_cov` covariance estimators.

<a id="skfolio.moments.ShrunkCovariance.fit"></a>

#### fit(X, y=None)

Fit the shrunk covariance model to X.

* **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.
* **Returns:**
  **self** *ShrunkCovariance*
  : Fitted estimator.

<a id="skfolio.moments.ShrunkCovariance.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.moments.ShrunkCovariance.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.moments.ShrunkCovariance.get_precision"></a>

#### get_precision()

Getter for the precision matrix.

* **Returns:**
  **precision_** *array-like of shape (n_features, n_features)*
  : The precision matrix associated to the current covariance object.

<a id="skfolio.moments.ShrunkCovariance.mahalanobis"></a>

#### mahalanobis(X_test)

Compute the squared Mahalanobis distance of observations.

The squared Mahalanobis distance of an observation $r$ is defined as:

$$
d^2 = (r - \mu)^T \Sigma^{-1} (r - \mu)

$$

where $\Sigma$ is the estimated covariance matrix (`self.covariance_`)
and $\mu$ is the estimated mean (`self.location_` if available, otherwise
zero).

This distance measure accounts for correlations between assets and is useful
for:

* Outlier detection in portfolio returns
* Risk-adjusted distance calculations
* Identifying unusual market regimes

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets) or (n_assets,)*
  : Observations for which to compute the squared Mahalanobis distance.
    Each row represents one observation. If 1D, treated as a single
    observation. Assets with non-finite fitted variance are excluded from
    inference. After this asset-level filtering, each row is evaluated
    using the remaining available values only, covering row-level missing
    values such as market holidays or pre/post-listing. When rows have
    different observation patterns, the returned distances follow
    $\chi^2$ distributions with different degrees of freedom.
    Rows with no finite retained observation return NaN.
* **Returns:**
  **distances** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distance for each observation. Returns a scalar
    if input is 1D.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance
>>> rng = np.random.default_rng(0)
>>> X = rng.standard_normal((100, 3))
>>> model = EmpiricalCovariance()
>>> model.fit(X)
EmpiricalCovariance()
>>> distances = model.mahalanobis(X)
>>> # The mean squared distance should be close to the number of assets (3).
>>> print(distances.mean())
2.9...
```

<a id="skfolio.moments.ShrunkCovariance.score"></a>

#### score(X_test, y=None)

Compute the mean log-likelihood of observations under the estimated model.

Evaluates how well the fitted covariance matrix explains new observations,
assuming a multivariate Gaussian distribution. This is useful for:

* Model selection (comparing different covariance estimators)
* Cross-validation of covariance estimation methods
* Assessing goodness-of-fit

The log-likelihood for a single observation $r$ is:

$$
\log p(r | \mu, \Sigma) = -\frac{1}{2} \left[
    n \log(2\pi) + \log|\Sigma| + (r - \mu)^T \Sigma^{-1} (r - \mu)
\right]

$$

where $n$ is the number of assets, $\Sigma$ is the estimated
covariance matrix (`self.covariance_`), and $\mu$ is the estimated
mean (`self.location_` if available, otherwise zero).

* **Parameters:**
  **X_test** *array-like of shape (n_observations, n_assets)*
  : Observations for which to compute the log-likelihood.
    Typically held-out test data not used during fitting.
    Assets with non-finite fitted variance are excluded from inference. This
    typically happens when the fitted covariance cannot be estimated for an
    asset, for example before listing, after delisting, or during a warmup
    period. After this asset-level filtering, each row of `X_test` is scored
    using the remaining available values only. This covers row-level missing
    values in `X_test`, such as market holidays or pre/post-listing.

  **y** *Ignored*
  : Not used, present for scikit-learn API consistency.
* **Returns:**
  **score** *float*
  : Mean log-likelihood of the observations. Higher values indicate better fit.
    The score is averaged over all observations.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.moments import EmpiricalCovariance, LedoitWolf
>>> rng = np.random.default_rng(0)
>>> X_train = rng.standard_normal((100, 5))
>>> X_test = rng.standard_normal((50, 5))
>>> emp = EmpiricalCovariance().fit(X_train)
>>> lw = LedoitWolf().fit(X_train)
>>> # Compare models on held-out data
>>> print("Empirical:", emp.score(X_test))
Empirical: -6.97...
>>> print("LedoitWolf:", lw.score(X_test))
LedoitWolf: -6.88...
```

<a id="skfolio.moments.ShrunkCovariance.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.

<a id="skfolio.moments.ShrunkCovariance.set_score_request"></a>

#### set_score_request()

No-op.

Calling this method has no effect.

* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.moments.ShrunkMu.html.md

<a id="skfolio-moments-shrunkmu"></a>

# skfolio.moments.ShrunkMu

<a id="skfolio.moments.ShrunkMu"></a>

### *class* skfolio.moments.ShrunkMu(covariance_estimator=None, vol_weighted_target=False, method=JAMES_STEIN)

Shrinkage Expected Returns (Mu) estimator.

Estimates the expected returns using shrinkage.

The sample mean estimator is unbiased but has high variance.
Stein (1955) proved that it’s possible to find an estimator with reduced total
error using shrinkage by trading a small bias against high variance.

The estimator shrinks the sample mean toward a target vector:

> $$
> \hat{\mu} = \alpha\bar{\mu}+\beta \mu_{target}

> $$

with $\bar{\mu}$ the sample mean, $\mu_{target}$ the target vector
and $\alpha$ and $\beta$ two constants to determine.

There are two choices for the target vector $\mu_{target}$ :

> * Grand Mean: constant vector of the mean of the sample mean
> * Volatility-Weighted Grand Mean: volatility-weighted sample mean

And three methods for $\alpha$ and $\beta$ :

> * James-Stein
> * Bayes-Stein
> * Bodnar Okhrin Parolya
* **Parameters:**
  **covariance_estimator** *BaseCovariance, optional*
  : [Covariance estimator](https://skfolio.org/user_guide/covariance.html.md#covariance-estimator) used to estimate the
    covariance in the shrinkage formulae.
    The default (`None`) is to use [`EmpiricalCovariance`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance).

  **vol_weighted_target** *bool, default=False*
  : If this is set to True, the target vector $\mu_{target}$ is the
    Volatility-Weighted Grand Mean otherwise it is the Grand Mean.
    The default is `False`.

  **method** *ShrunkMuMethods, default=ShrunkMuMethods.JAMES_STEIN*
  : Shrinkage method [`ShrunkMuMethods`](https://skfolio.org/generated/skfolio.moments.ShrunkMuMethods.html.md#skfolio.moments.ShrunkMuMethods).
    <br/>
    Possible values are:
    > * JAMES_STEIN
    > * BAYES_STEIN
    > * BODNAR_OKHRIN
    <br/>
    The default value is `ShrunkMuMethods.JAMES_STEIN`.
* **Attributes:**
  **mu_** *ndarray of shape (n_assets,)*
  : Estimated expected returns of the assets.

  **covariance_estimator_** *BaseCovariance*
  : Fitted `covariance_estimator`.

  **mu_target_** *ndarray of shape (n_assets,)*
  : Target vector $\mu_{target}$.

  **alpha_** *float*
  : Alpha value $\alpha$.

  **beta_** *float*
  : Beta value $\beta$.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.moments.ShrunkMu.html.md#skfolio.moments.ShrunkMu.fit)(X[, y])            | Fit the ShrunkMu estimator model.     |
|-------------------------------------------------------------------------|---------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.moments.ShrunkMu.html.md#skfolio.moments.ShrunkMu.get_metadata_routing)() | Get metadata routing of this object.  |
| [`get_params`](https://skfolio.org/generated/skfolio.moments.ShrunkMu.html.md#skfolio.moments.ShrunkMu.get_params)([deep])     | Get parameters for this estimator.    |
| [`set_params`](https://skfolio.org/generated/skfolio.moments.ShrunkMu.html.md#skfolio.moments.ShrunkMu.set_params)(\*\*params) | Set the parameters of this estimator. |

### References

* <a id='r579f13f50985-1'>**[1]**</a> “Risk and Asset Allocation”, Attilio Meucci (2005)
* <a id='r579f13f50985-2'>**[2]**</a> “Bayes-stein estimation for portfolio analysis”, Philippe Jorion (1986)
* <a id='r579f13f50985-3'>**[3]**</a> “Optimal shrinkage estimator for high-dimensional mean vector” Bodnar, Okhrin and Parolya (2019)

<a id="skfolio.moments.ShrunkMu.fit"></a>

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

Fit the ShrunkMu estimator model.

* **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** *ShrunkMu*
  : Fitted estimator.

<a id="skfolio.moments.ShrunkMu.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.moments.ShrunkMu.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.moments.ShrunkMu.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.

# generated/skfolio.moments.ShrunkMuMethods.html.md

<a id="skfolio-moments-shrunkmumethods"></a>

# skfolio.moments.ShrunkMuMethods

<a id="skfolio.moments.ShrunkMuMethods"></a>

### *class* skfolio.moments.ShrunkMuMethods(\*values)

Shrinkage methods for the ShrunkMu estimator.

* **Parameters:**
  **JAMES_STEIN** *str*
  : James-Stein method

  **BAYES_STEIN** *str*
  : Bayes-Stein method

  **BODNAR_OKHRIN** *str*
  : Bodnar Okhrin Parolya method

<a id="skfolio.moments.ShrunkMuMethods.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.optimization.BaseHierarchicalOptimization.html.md

<a id="skfolio-optimization-basehierarchicaloptimization"></a>

# skfolio.optimization.BaseHierarchicalOptimization

<a id="skfolio.optimization.BaseHierarchicalOptimization"></a>

### *class* skfolio.optimization.BaseHierarchicalOptimization(risk_measure=Variance, prior_estimator=None, distance_estimator=None, hierarchical_clustering_estimator=None, min_weights=0.0, max_weights=1.0, transaction_costs=0.0, management_fees=0.0, previous_weights=None, portfolio_params=None, fallback=None, raise_on_failure=True)

Base Hierarchical Clustering Optimization estimator.

* **Parameters:**
  **risk_measure** *RiskMeasure or ExtraRiskMeasure, default=RiskMeasure.VARIANCE*
  : `RiskMeasure` or `ExtraRiskMeasure`
    of the optimization.
    Can be any of:
    > * MEAN_ABSOLUTE_DEVIATION
    > * FIRST_LOWER_PARTIAL_MOMENT
    > * VARIANCE
    > * SEMI_VARIANCE
    > * CVAR
    > * EVAR
    > * WORST_REALIZATION
    > * CDAR
    > * MAX_DRAWDOWN
    > * AVERAGE_DRAWDOWN
    > * EDAR
    > * ULCER_INDEX
    > * GINI_MEAN_DIFFERENCE_RATIO
    > * VALUE_AT_RISK
    > * DRAWDOWN_AT_RISK
    > * ENTROPIC_RISK_MEASURE
    > * FOURTH_CENTRAL_MOMENT
    > * FOURTH_LOWER_PARTIAL_MOMENT
    <br/>
    The default is `RiskMeasure.VARIANCE`.

  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator 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 and
    returns. The moments and returns estimations are used for the risk computation
    and the returns estimation are used by the distance matrix estimator.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **distance_estimator** *BaseDistance, optional*
  : [Distance estimator](https://skfolio.org/user_guide/distance.html.md#distance).
    The distance estimator is used to estimate the codependence and the distance
    matrix needed for the computation of the linkage matrix.
    The default (`None`) is to use [`PearsonDistance`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance).

  **hierarchical_clustering_estimator** *HierarchicalClustering, optional*
  : [Hierarchical Clustering estimator](https://skfolio.org/user_guide/cluster.html.md#hierarchical-clustering).
    The hierarchical clustering estimator is used to compute the linkage matrix
    and the hierarchical clustering of the assets based on the distance matrix.
    The default (`None`) is to use
    [`HierarchicalClustering`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering).

  **min_weights** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Minimum assets weights (weights lower bounds). The default is 0.0 (no short
    selling). Negative weights are not allowed. If a float is provided, it is
    applied to each asset. `None` is equivalent to the default `0.0`. If a
    dictionary is provided, its (key/value) pair must be the (asset name/asset
    minimum weight) and the input `X` of the `fit` methods must be a DataFrame with
    the asset names in columns. When using a dictionary, assets values that are not
    provided are assigned the default  minimum weight of `0.0`.
    <br/>
    Example:
    > * `min_weights = 0.0` –> long only portfolio (default).
    > * `min_weights = {"SX5E": 0.1, "SPX": 0.2}`
    > * `min_weights = [0.1, 0.2]`

  **max_weights** *float | dict[str, float] | array-like of shape (n_assets, ), default=1.0*
  : Maximum assets weights (weights upper bounds). The default is 1.0 (each asset
    is below 100%). Weights above 1.0 are not allowed. If a float is provided, it is
    applied to each asset. `None` is equivalent to the default `1.0`. If a
    dictionary is provided, its (key/value) pair must be the (asset name/asset
    maximum weight) and the input `X` of the `fit` method must be a DataFrame with
    the asset names in columns. When using a dictionary, assets values that are not
    provided are assigned the default maximum weight of `1.0`.
    <br/>
    Example:
    > * `max_weights = 1.0` –> each weight  must be below 100% (default).
    > * `max_weights = 0.5` –> each weight must be below 50%.
    > * `max_weights = {"SX5E": 0.8, "SPX": 0.9}`
    > * `max_weights = [0.8, 0.9]`

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Transaction costs of the assets. It is used to add linear transaction costs to
    the optimization problem:
    $$
    total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|
    <br/>
    $$
    <br/>
    with $c_{i}$ the transaction cost of asset i, $w_{i}$ its weight
    and $w\_prev_{i}$ its previous weight (defined in `previous_weights`).
    The float $total\_cost$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_cost
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the
    vector of assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset cost) and the input `X` of the `fit` method must be a
    DataFrame with the asset names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the transaction costs
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `transaction_costs` need to be
    expressed as **daily** costs. A transaction cost is paid once per
    rebalancing while a position earns its expected return on every period it
    is held, so the one-off cost is converted by dividing it by the expected
    investment duration (e.g. `0.001 / 21` for a 10 bps cost with daily
    returns and a one-month expected holding period).
    (See [Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention))

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Management fees of the assets. It is used to add linear management fees to the
    optimization problem:
    $$
    total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}
    <br/>
    $$
    <br/>
    with $f_{i}$ the management fee of asset i and $w_{i}$ its weight.
    The float $total\_fee$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_fee
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the vector
    of assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset fee) and the input `X` of the `fit` method must be a
    DataFrame with the asset names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the management fees
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `management_fees` need to be
    expressed in **daily** fees. Unlike transaction costs, management fees
    accrue with holding time, so a stated annual fee converts directly to the
    return periodicity (e.g. `0.02 / 252` for a 2% annual fee on daily
    returns).
    <br/>
    #### NOTE
    Another approach is to directly impact the management fees to the input `X`
    in order to express the returns net of fees. However, when estimating the
    $\mu$ parameter using for example Shrinkage estimators, this approach
    would mix a deterministic value with an uncertain one leading to unwanted
    bias in the management fees.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Previous weights of the assets. Previous weights are used to compute the
    portfolio total cost. If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset previous weight) and the input `X` of the `fit` method must
    be a DataFrame with the asset names in columns.
    The default (`None`) means no previous weights.
    Additionally, when `fallback="previous_weights"`, failures will fall back to
    these weights if provided.

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    `transaction_costs`, `management_fees`, `previous_weights` and `risk_free_rate`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,)*
  : Weights of the assets.

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

  **distance_estimator_** *BaseDistance*
  : Fitted `distance_estimator`.

  **hierarchical_clustering_estimator_** *HierarchicalClustering*
  : Fitted `hierarchical_clustering_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.

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.BaseHierarchicalOptimization.html.md#skfolio.optimization.BaseHierarchicalOptimization.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`.   |
|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.BaseHierarchicalOptimization.html.md#skfolio.optimization.BaseHierarchicalOptimization.get_metadata_routing)() | Get metadata routing of this object.                                                                                              |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.BaseHierarchicalOptimization.html.md#skfolio.optimization.BaseHierarchicalOptimization.get_params)([deep])     | Get parameters for this estimator.                                                                                                |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.BaseHierarchicalOptimization.html.md#skfolio.optimization.BaseHierarchicalOptimization.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                   |
| [`score`](https://skfolio.org/generated/skfolio.optimization.BaseHierarchicalOptimization.html.md#skfolio.optimization.BaseHierarchicalOptimization.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                          |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.BaseHierarchicalOptimization.html.md#skfolio.optimization.BaseHierarchicalOptimization.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                             |

| **fit**   |    |
|-----------|----|

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

<a id="skfolio.optimization.BaseHierarchicalOptimization.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.BaseHierarchicalOptimization.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.optimization.BaseHierarchicalOptimization.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.optimization.BaseHierarchicalOptimization.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.BaseHierarchicalOptimization.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.BaseHierarchicalOptimization.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.BaseHierarchicalOptimization.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.

# generated/skfolio.optimization.BaseOptimization.html.md

<a id="skfolio-optimization-baseoptimization"></a>

# skfolio.optimization.BaseOptimization

<a id="skfolio.optimization.BaseOptimization"></a>

### *class* skfolio.optimization.BaseOptimization(portfolio_params=None, fallback=None, previous_weights=None, raise_on_failure=True)

Base class for all portfolio optimizations in skfolio.

* **Parameters:**
  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    Unless set in this dictionary, `transaction_costs`, `management_fees`,
    `previous_weights` and `risk_free_rate` are forwarded from the optimizer when
    available, and `name` defaults to the optimizer class name.
    For example, `portfolio_params={"weight_drift": True}` evaluates the predicted
    portfolios with drifted weights instead of the target weights on every
    observation.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets,), optional*
  : Previous asset weights. Some portfolio optimizers use this to compute costs or
    turnover. Additionally, when `fallback="previous_weights"`, failures will fall
    back to these weights if provided.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,) or (n_optimizations, n_assets)*
  : Weights of the assets.

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

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.BaseOptimization.html.md#skfolio.optimization.BaseOptimization.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`.   |
|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.BaseOptimization.html.md#skfolio.optimization.BaseOptimization.get_metadata_routing)() | Get metadata routing of this object.                                                                                              |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.BaseOptimization.html.md#skfolio.optimization.BaseOptimization.get_params)([deep])     | Get parameters for this estimator.                                                                                                |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.BaseOptimization.html.md#skfolio.optimization.BaseOptimization.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                   |
| [`score`](https://skfolio.org/generated/skfolio.optimization.BaseOptimization.html.md#skfolio.optimization.BaseOptimization.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                          |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.BaseOptimization.html.md#skfolio.optimization.BaseOptimization.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                             |

| **fit**   |    |
|-----------|----|

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

<a id="skfolio.optimization.BaseOptimization.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.BaseOptimization.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.optimization.BaseOptimization.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.optimization.BaseOptimization.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.BaseOptimization.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.BaseOptimization.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.BaseOptimization.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.

# generated/skfolio.optimization.BenchmarkTracker.html.md

<a id="skfolio-optimization-benchmarktracker"></a>

# skfolio.optimization.BenchmarkTracker

<a id="skfolio.optimization.BenchmarkTracker"></a>

### *class* skfolio.optimization.BenchmarkTracker(risk_measure=Standard Deviation, prior_estimator=None, min_weights=0.0, max_weights=1.0, max_short=None, max_long=None, cardinality=None, group_cardinalities=None, threshold_long=None, threshold_short=None, transaction_costs=0.0, management_fees=0.0, previous_weights=None, groups=None, linear_constraints=None, left_inequality=None, right_inequality=None, l1_coef=0.0, l2_coef=0.0, risk_free_rate=0.0, solver='CLARABEL', solver_params=None, scale_objective=None, scale_constraints=None, save_problem=False, add_objective=None, add_constraints=None, portfolio_params=None, fallback=None, raise_on_failure=True)

Benchmark Tracker Optimization estimator.

Optimize a portfolio to track a benchmark by minimizing the risk of
benchmark-relative (excess) returns.

This estimator minimizes the tracking risk between portfolio returns and a
benchmark’s returns by optimizing directly on excess (active) returns, defined as
portfolio returns minus benchmark returns.

Tracking risk can be defined using any of the available risk measures. Typical
choices include standard deviation (tracking-error volatility), semi-deviation and
mean absolute deviation.

#### SEE ALSO
[Tracking Error Optimization](https://skfolio.org/user_guide/optimization.html.md#tracking-error-optimization)

* **Parameters:**
  **risk_measure** *RiskMeasure, default=RiskMeasure.STANDARD_DEVIATION*
  : [`RiskMeasure`](https://skfolio.org/generated/skfolio.measures.RiskMeasure.html.md#skfolio.measures.RiskMeasure) to minimize on excess returns.
    The default is `RiskMeasure.STANDARD_DEVIATION`.

  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator is used to estimate the [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution)
    of excess returns (portfolio returns - benchmark returns).
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **min_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=0.0*
  : Minimum assets weights (weights lower bounds).
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **max_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=1.0*
  : Maximum assets weights (weights upper bounds).
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **max_short** *float, optional*
  : Maximum short position.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **max_long** *float, optional*
  : Maximum long position.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **cardinality** *int, optional*
  : Cardinality constraint to limit the number of invested assets.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **group_cardinalities** *dict[str, int], optional*
  : Cardinality constraints for specific groups of assets.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **threshold_long** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Minimum weight threshold for long positions.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **threshold_short** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Maximum weight threshold for short positions.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Transaction costs of the assets.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Management fees of the assets.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Previous weights of the assets.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **l1_coef** *float, default=0.0*
  : L1 regularization coefficient.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **l2_coef** *float, default=0.0*
  : L2 regularization coefficient.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **groups** *dict[str, list[str]] or array-like of shape (n_groups, n_assets), optional*
  : The assets groups.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **linear_constraints** *array-like of shape (n_constraints,), optional*
  : Linear constraints.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **left_inequality** *array-like of shape (n_constraints, n_assets), optional*
  : Left inequality matrix.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **right_inequality** *array-like of shape (n_constraints, ), optional*
  : Right inequality vector.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **risk_free_rate** *float, default=0.0*
  : Risk-free interest rate.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **solver** *str, default=”CLARABEL”*
  : The solver to use.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **solver_params** *dict, optional*
  : Solver parameters.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **scale_objective** *float, optional*
  : Scale each objective element by this value.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **scale_constraints** *float, optional*
  : Scale each constraint element by this value.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **save_problem** *bool, default=False*
  : If this is set to True, the CVXPY Problem is saved in `problem_`.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **add_objective** *Callable[[cp.Variable], cp.Expression], optional*
  : Add a custom objective to the existing objective expression.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **add_constraints** *Callable[[cp.Variable], cp.Expression | list[cp.Expression]], optional*
  : Add a custom constraint or a list of constraints to the existing constraints.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **portfolio_params** *dict, optional*
  : Portfolio parameters.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or list of estimators.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    See [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) for details.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,)*
  : Weights of the assets.

  **problem_values_** *dict[str, float]*
  : Expression values retrieved from the CVXPY problem.

  **prior_estimator_** *BasePrior*
  : Fitted `prior_estimator` on excess returns.

  **problem_: cvxpy.Problem**
  : CVXPY problem used for the optimization.
    Only when `save_problem` is set to `True`.

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

  **feature_names_in_** *ndarray of shape (`n_features_in_`,)*
  : Names of assets seen during `fit`.

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance that produced the final result.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts.

  **error_** *str | None*
  : Captured error message when `fit` fails.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.BenchmarkTracker.html.md#skfolio.optimization.BenchmarkTracker.fit)(X, y, \*\*fit_params)   | Fit the Return-Based Tracker estimator.                                                                                         |
|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.BenchmarkTracker.html.md#skfolio.optimization.BenchmarkTracker.fit_predict)(X)              | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.BenchmarkTracker.html.md#skfolio.optimization.BenchmarkTracker.get_metadata_routing)()      | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.BenchmarkTracker.html.md#skfolio.optimization.BenchmarkTracker.get_params)([deep])          | Get parameters for this estimator.                                                                                              |
| [`partial_fit`](https://skfolio.org/generated/skfolio.optimization.BenchmarkTracker.html.md#skfolio.optimization.BenchmarkTracker.partial_fit)(X[, y])         | Incrementally fit the Mean-Risk Optimization estimator.                                                                         |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.BenchmarkTracker.html.md#skfolio.optimization.BenchmarkTracker.predict)(X)                  | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.BenchmarkTracker.html.md#skfolio.optimization.BenchmarkTracker.score)(X[, y])               | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.BenchmarkTracker.html.md#skfolio.optimization.BenchmarkTracker.set_params)(\*\*params)      | Set the parameters of this estimator.                                                                                           |

### Notes

It is implemented as a special case of [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) where
the input asset returns `X` and benchmark returns `y` are first transformed to
excess returns `X_excess = X - y` before optimization. A full-investment constraint
(`budget = 1.0`) is always enforced because:

$$
r_t^{excess}(w) = \sum_i w_i(r_{t,i} - r_{b,t}) = r_{p,t} - (\sum_i w_i)r_{b,t}

$$

where $r_{p,t}$ is the portfolio return and $r_{b,t}$ the benchmark
return, coincides with the active (benchmark-relative) return

$$
r_{p,t} - r_{b,t}

$$

when $\sum_i w_i = 1$

### References

* <a id='re9e9e2e23476-1'>**[1]**</a> “Portfolio Optimization: Theory and Application”, Chapter 13, Daniel P. Palomar (2025)

<a id="skfolio.optimization.BenchmarkTracker.fit"></a>

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

Fit the Return-Based Tracker estimator.

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

  **y** *array-like of shape (n_observations, 1) or (n_observations,)*
  : Price returns of the benchmark.

  **\*\*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** *BenchmarkTracker*
  : Fitted estimator.

<a id="skfolio.optimization.BenchmarkTracker.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.BenchmarkTracker.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.optimization.BenchmarkTracker.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.optimization.BenchmarkTracker.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.BenchmarkTracker.partial_fit"></a>

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

Incrementally fit the Mean-Risk Optimization estimator.

This method allows for streaming/online updates. The prior estimator and any
configured uncertainty set estimators must implement `partial_fit` (e.g.,
priors using exponentially weighted moments or online factor models).

The optimization problem is solved fresh on each call using the updated
moments from the prior estimator.

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

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Price returns of factors or a target benchmark.
    The default is `None`.

  **\*\*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** *MeanRisk*
  : Fitted estimator.

<a id="skfolio.optimization.BenchmarkTracker.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.BenchmarkTracker.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.BenchmarkTracker.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.

# generated/skfolio.optimization.ConvexOptimization.html.md

<a id="skfolio-optimization-convexoptimization"></a>

# skfolio.optimization.ConvexOptimization

<a id="skfolio.optimization.ConvexOptimization"></a>

### *class* skfolio.optimization.ConvexOptimization(risk_measure=Variance, prior_estimator=None, min_weights=0.0, max_weights=1.0, budget=1.0, min_budget=None, max_budget=None, max_short=None, max_long=None, cardinality=None, group_cardinalities=None, threshold_long=None, threshold_short=None, transaction_costs=0.0, management_fees=0.0, previous_weights=None, target_weights=None, groups=None, linear_constraints=None, left_inequality=None, right_inequality=None, l1_coef=0.0, l2_coef=0.0, mu_uncertainty_set_estimator=None, covariance_uncertainty_set_estimator=None, risk_free_rate=0.0, min_acceptable_return=None, cvar_beta=0.95, evar_beta=0.95, cdar_beta=0.95, edar_beta=0.95, solver='CLARABEL', solver_params=None, scale_objective=None, scale_constraints=None, save_problem=False, add_objective=None, add_constraints=None, overwrite_expected_return=None, portfolio_params=None, fallback=None, raise_on_failure=True)

Base class for all convex optimization estimators in skfolio.

All risk measures that have a convex formulation are defined in class methods with
naming convention: `_{risk_measure}_risk`. That naming convention is used for
dynamic lookup.

CVX expressions that are shared among multiple risk measures are cached in a
dictionary named `_cvx_cache`.
This is to avoid cvx expression duplication and improve performance and convergence.

* **Parameters:**
  **risk_measure** *RiskMeasure, default=RiskMeasure.VARIANCE*
  : `RiskMeasure` of the optimization.
    Can be any of:
    > * VARIANCE
    > * SEMI_VARIANCE
    > * STANDARD_DEVIATION
    > * SEMI_DEVIATION
    > * MEAN_ABSOLUTE_DEVIATION
    > * FIRST_LOWER_PARTIAL_MOMENT
    > * CVAR
    > * EVAR
    > * WORST_REALIZATION
    > * CDAR
    > * MAX_DRAWDOWN
    > * AVERAGE_DRAWDOWN
    > * EDAR
    > * ULCER_INDEX
    > * GINI_MEAN_DIFFERENCE_RATIO
    <br/>
    The default is `RiskMeasure.VARIANCE`.

  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator 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 of the covariance.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **min_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=0.0*
  : Minimum assets weights (weights lower bounds).
    If a float is provided, it is applied to each asset.
    `None` is equivalent to `-np.Inf` (no lower bound).
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset minimum weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a minimum weight of `0.0`.
    The default value is `0.0` (no short selling).
    <br/>
    Example:
    > * `min_weights = 0` –> long only portfolio (no short selling).
    > * `min_weights = None` –> no lower bound (same as `-np.Inf`).
    > * `min_weights = -2` –> each weight must be above -200%.
    > * `min_weights = {"SX5E": 0, "SPX": -2}`
    > * `min_weights = [0, -2]`

  **max_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=1.0*
  : Maximum assets weights (weights upper bounds).
    If a float is provided, it is applied to each asset.
    `None` is equivalent to `+np.Inf` (no upper bound).
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset maximum weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a minimum weight of `1.0`.
    The default value is `1.0` (each asset is below 100%).
    <br/>
    Example:
    > * `max_weights = 0` –> no long position (short only portfolio).
    > * `max_weights = None` –> no upper bound.
    > * `max_weights = 2` –> each weight must be below 200%.
    > * `max_weights = {"SX5E": 1, "SPX": 2}`
    > * `max_weights = [1, 2]`

  **budget** *float | None, default=1.0*
  : Investment budget. It is the sum of long positions and short positions (sum of
    all weights). `None` means no budget constraints.
    The default value is `1.0` (fully invested portfolio).
    <br/>
    For example:
    > * `budget = 1` –> fully invested portfolio.
    > * `budget = 0` –> market neutral portfolio.
    > * `budget = None` –> no constraints on the sum of weights.

  **min_budget** *float, optional*
  : Minimum budget. It is the lower bound of the sum of long and short positions
    (sum of all weights). If provided, you must set `budget=None`.
    The default (`None`) means no minimum budget constraint.

  **max_budget** *float, optional*
  : Maximum budget. It is the upper bound of the sum of long and short positions
    (sum of all weights). If provided, you must set `budget=None`.
    The default (`None`) means no maximum budget constraint.

  **max_short** *float, optional*
  : Maximum short position. The short position is defined as the sum of negative
    weights (in absolute term).
    The default (`None`) means no maximum short position.

  **max_long** *float, optional*
  : Maximum long position. The long position is defined as the sum of positive
    weights.
    The default (`None`) means no maximum long position.

  **cardinality** *int, optional*
  : Specifies the cardinality constraint to limit the number of invested assets
    (non-zero weights). This feature requires a mixed-integer solver. For an
    open-source option, we recommend using SCIP by setting `solver="SCIP"`.
    To install it, use: `pip install cvxpy[SCIP]`. For commercial solvers,
    supported options include MOSEK, GUROBI, or CPLEX.

  **group_cardinalities** *dict[str, int], optional*
  : A dictionary specifying cardinality constraints for specific groups of assets.
    The keys represent group names (strings), and the values specify the maximum
    number of assets allowed in each group. You must provide the groups using the
    `groups` parameter. This requires a mixed-integer solver (see `cardinality`
    for more details).

  **threshold_long** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Specifies the minimum weight threshold for assets in the portfolio to be
    considered as a long position. Assets with weights below this threshold
    will not be included as part of the portfolio’s long positions. This
    constraint can help eliminate insignificant allocations.
    This requires a mixed-integer solver (see `cardinality` for more details).
    It follows the same format as `min_weights` and `max_weights`.

  **threshold_short** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Specifies the maximum weight threshold for assets in the portfolio to be
    considered as a short position. Assets with weights above this threshold
    will not be included as part of the portfolio’s short positions. This
    constraint can help control the magnitude of short positions.
    This requires a mixed-integer solver (see `cardinality` for more details).
    It follows the same format as `min_weights` and `max_weights`.

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Transaction costs of the assets. It is used to add linear transaction costs to
    the optimization problem:
    $$
    total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|
    <br/>
    $$
    <br/>
    with $c_{i}$ the transaction cost of asset i, $w_{i}$ its weight
    and $w\_prev_{i}$ its previous weight (defined in `previous_weights`).
    The float $total\_cost$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_cost
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the
    vector of assets weights.
    <br/>
    For positions in `previous_weights` whose assets are no longer in the
    investment universe, transaction costs are calculated assuming full
    liquidation. These costs are included in both the optimization and
    `Portfolio.total_cost`. For assets absent from `X`, `transaction_costs`
    must be a single rate applied to all assets or a dictionary keyed by asset name.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset cost) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the transaction costs
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `transaction_costs` need to be
    expressed as **daily** costs. A transaction cost is paid once per
    rebalancing while a position earns its expected return on every period it
    is held, so the one-off cost is converted by dividing it by the expected
    investment duration (e.g. `0.001 / 21` for a 10 bps cost with daily
    returns and a one-month expected holding period).
    (See [Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention))

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Management fees of the assets. It is used to add linear management fees to the
    optimization problem:
    $$
    total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}
    <br/>
    $$
    <br/>
    with $f_{i}$ the management fee of asset i and $w_{i}$ its weight.
    The float $total\_fee$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_fee
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the vector
    of assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset fee) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the management fees
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `management_fees` need to be
    expressed in **daily** fees. Unlike transaction costs, management fees
    accrue with holding time, so a stated annual fee converts directly to the
    return periodicity (e.g. `0.02 / 252` for a 2% annual fee on daily
    returns).
    <br/>
    #### NOTE
    Another approach is to directly impact the management fees to the input `X`
    in order to express the returns net of fees. However, when estimating the
    $\mu$ parameter using for example Shrinkage estimators, this approach
    would mix a deterministic value with an uncertain one leading to unwanted
    bias in the management fees.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Previous weights of the assets. Previous weights are used to compute the
    portfolio cost and the portfolio turnover.
    For named positions in assets absent from `X`, these calculations assume
    full liquidation.
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset previous weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    The default (`None`) means no previous weights.
    Additionally, when `fallback="previous_weights"`, failures will fall back to
    these weights if provided.

  **l1_coef** *float, default=0.0*
  : L1 regularization coefficient.
    It is used to penalize the objective function by the L1 norm:
    $$
    l1\_coef \times \Vert w \Vert_{1} = l1\_coef \times \sum_{i=1}^{N} |w_{i}|
    <br/>
    $$
    <br/>
    Increasing this coefficient will reduce the number of non-zero weights
    (cardinality). It tends to increase robustness (out-of-sample stability) but
    reduces diversification.
    The default value is `0.0`.

  **l2_coef** *float, default=0.0*
  : L2 regularization coefficient.
    It is used to penalize the objective function by the L2 norm:
    $$
    l2\_coef \times \Vert w \Vert_{2}^{2} = l2\_coef \times \sum_{i=1}^{N} w_{i}^2
    <br/>
    $$
    <br/>
    It tends to increase robustness (out-of-sample stability).
    The default value is `0.0`.

  **mu_uncertainty_set_estimator** *BaseMuUncertaintySet, optional*
  : [Mu Uncertainty set estimator](https://skfolio.org/user_guide/uncertainty_set.html.md#uncertainty-set-estimator).
    If provided, the expected asset returns are modelled with a norm-ball
    uncertainty set. It is called worst-case optimization and is a class of robust
    optimization. It reduces the instability that arises from the estimation errors
    of the expected returns.
    The worst-case portfolio expected return is:
    $$
    w^T\hat{\mu} - \kappa_{\mu}\lVert L_{\mu}^Tw\rVert_{q}
    <br/>
    $$
    <br/>
    with $\kappa$ the radius of the uncertainty set (confidence region),
    $L$ its linear geometry map and $q$ the dual norm. For an
    ellipsoidal set with shape matrix $S$, $L$ is a square-root factor
    satisfying $S = L L^T$ and $q$ is $2$.
    The default (`None`) means that no uncertainty set is used.

  **covariance_uncertainty_set_estimator** *BaseCovarianceUncertaintySet, optional*
  : [Covariance Uncertainty set estimator](https://skfolio.org/user_guide/uncertainty_set.html.md#uncertainty-set-estimator).
    If provided, covariance estimation uncertainty is included in the optimized
    variance. This approach is known as worst-case optimization, a form of robust
    optimization. It reduces sensitivity to covariance estimation errors.
    Covariance uncertainty is applied when `risk_measure=RiskMeasure.VARIANCE` or
    when `max_variance` is set.
    The default (`None`) means that no uncertainty set is used.

  **linear_constraints** *array-like of shape (n_constraints,), optional*
  : Linear constraints on portfolio weights or factor exposures.
    <br/>
    Constraint names can reference:
    > * Asset names: individual asset weights (e.g. `"SPX"`, `"AAPL"`)
    > * Group names: sums of weights in groups defined by `groups`
    > * Factor names: portfolio factor exposure (requires factor model prior)
    > * Factor families: sum of portfolio exposures to all factors in one family
    <br/>
    Supported equation patterns include:
    > * `"name <= value"` or `"name >= value"`
    > * `"name == value"`
    > * `"a * name1 + b * name2 <= c * name3 + d"`
    <br/>
    For example:
    > * `"SPX >= 0.10"` –> SPX weight >= 10%
    > * `"SX5E + SPX >= 0.2"` –> sum of SX5E and SPX weights >= 20%
    > * `"US == 0.7"` –> sum of weights in US group == 70%
    > * `"Equity == 3 * Bond"` –> sum of weights in Equity group == 3x sum of weights in Bond group
    > * `"Momentum <= 0.30"` –> portfolio Momentum exposure <= 30%
    > * `"style <= 0.50"` –> sum of all style factor exposures (Momentum, Value, Size, etc.) <= 50%
    <br/>
    Factor constraints require a prior estimator (e.g.
    [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel),
    [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel))
    that provides `loading_matrix`, `factor_names` and optionally `factor_families`
    in its [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel).
    <br/>
    Asset, group, factor, and factor family names must be unique.

  **groups** *dict[str, list[str]] or array-like of shape (n_groups, n_assets), optional*
  : The assets groups referenced in `linear_constraints`.
    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"]]`

  **left_inequality** *array-like of shape (n_constraints, n_assets), optional*
  : Left inequality matrix $A$ of the linear
    constraint $A \cdot w \leq b$.

  **right_inequality** *array-like of shape (n_constraints, ), optional*
  : Right inequality vector $b$ of the linear
    constraint $A \cdot w \leq b$.

  **risk_free_rate** *float, default=0.0*
  : Risk-free interest rate.
    The default value is `0.0`.

  **min_acceptable_return** *float, optional*
  : The minimum acceptable return used to distinguish “downside” and “upside”
    returns for the computation of lower partial moments:
    > * First Lower Partial Moment
    > * Semi-Variance
    > * Semi-Deviation
    <br/>
    The default (`None`) is to use the mean.

  **cvar_beta** *float, default=0.95*
  : CVaR (Conditional Value at Risk) confidence level.
    The default value is `0.95`.

  **evar_beta** *float, default=0.95*
  : EVaR (Entropic Value at Risk) confidence level.
    The default value is `0.95`.

  **cdar_beta** *float, default=0.95*
  : CDaR (Conditional Drawdown at Risk) confidence level.
    The default value is `0.95`.

  **edar_beta** *float, default=0.95*
  : EDaR (Entropic Drawdown at Risk) confidence level.
    The default value is `0.95`.

  **add_objective** *Callable[[cp.Variable], cp.Expression], optional*
  : Add a custom objective to the existing objective expression.
    It is a function that must take as argument the weights `w` and returns a
    CVXPY expression.

  **add_constraints** *Callable[[cp.Variable], cp.Expression | list[cp.Expression]], optional*
  : Add a custom constraint or a list of constraints to the existing constraints.
    It must be a function taking the CVXPY weight variable `w` as its first
    positional argument and, optionally, the estimator instance as its second.
    It must return a CVXPY expression or a list of CVXPY expressions, evaluated
    when `fit` is called.
    <br/>
    For example, to require an effective number of assets of at least 20:
    ```pycon
    >>> import cvxpy as cp
    >>> from skfolio.optimization import MeanRisk
    >>> model = MeanRisk(add_constraints=lambda w: cp.sum_squares(w) <= 1 / 20)
    ```
    <br/>
    The optional second argument gives access to the estimator’s attributes,
    including quantities estimated during `fit`. For example, to cap each
    position size in risk units at 20 bps, using the volatilities estimated
    by the prior:
    ```pycon
    >>> import numpy as np
    >>> def position_risk_cap(w, model):
    ...     covariance = model.prior_estimator_.return_distribution_.covariance
    ...     vols = np.sqrt(np.diag(covariance))
    ...     return cp.multiply(vols, w) <= 0.002
    >>> model = MeanRisk(add_constraints=position_risk_cap)
    ```

  **overwrite_expected_return** *Callable[[cp.Variable], cp.Expression], optional*
  : Overwrite the expected return $\mu \cdot w$ with a custom CVXPY
    expression. It must be a function taking the CVXPY weight variable `w` as
    its first positional argument and, optionally, the estimator instance as
    its second. It must return a concave CVXPY expression, evaluated when
    `fit` is called. The custom expression replaces the expected return in the
    objective function and in the constraints where the expected return is
    used.
    <br/>
    For example, to adjust the expected return for volatility drag,
    approximating the portfolio geometric mean return:
    ```pycon
    >>> import cvxpy as cp
    >>> from skfolio.optimization import MeanRisk
    >>> def geometric_expected_return(w, model):
    ...     dist = model.prior_estimator_.return_distribution_
    ...     return dist.mu @ w - 0.5 * cp.quad_form(w, dist.covariance)
    >>> model = MeanRisk(overwrite_expected_return=geometric_expected_return)
    ```

  **solver** *str, default=”CLARABEL”*
  : The solver to use. The default is “CLARABEL” which is written in Rust and has
    better numerical stability and performance than ECOS and SCS. Cvxpy will replace
    its default solver “ECOS” by “CLARABEL” in future releases.
    For more details about available solvers, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver](https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver)

  **solver_params** *dict, optional*
  : Solver parameters. For example, `solver_params=dict(verbose=True)`.
    The default (`None`) is to use `{"tol_gap_abs": 1e-9, "tol_gap_rel": 1e-9}`
    for the solver “CLARABEL” and the CVXPY default otherwise.
    For more details about solver arguments, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/solvers](https://www.cvxpy.org/tutorial/solvers)

  **scale_objective** *float, optional*
  : Scale each objective element by this value.
    It can be used to increase the optimization accuracies in specific cases.
    The default (`None`) is set depending on the problem.

  **scale_constraints** *float, optional*
  : Scale each constraint element by this value.
    It can be used to increase the optimization accuracies in specific cases.
    The default (`None`) is set depending on the problem.

  **save_problem** *bool, default=False*
  : If this is set to True, the CVXPY Problem is saved in `problem_`.
    The default is `False`.

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    `transaction_costs`, `management_fees`, `previous_weights` and `risk_free_rate`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,) or (n_optimizations, n_assets)*
  : Weights of the assets.

  **problem_values_** *dict[str, float] | list[dict[str, float]] of size n_optimizations*
  : Expression values retrieved from the CVXPY problem.

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

  **mu_uncertainty_set_estimator_** *BaseMuUncertaintySet*
  : Fitted `mu_uncertainty_set_estimator` if provided.

  **covariance_uncertainty_set_estimator_** *BaseCovarianceUncertaintySet*
  : Fitted `covariance_uncertainty_set_estimator` if provided.

  **problem_: cvxpy.Problem**
  : CVXPY problem used for the optimization. Only when `save_problem` is set to
    `True`.

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.ConvexOptimization.html.md#skfolio.optimization.ConvexOptimization.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`.   |
|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.ConvexOptimization.html.md#skfolio.optimization.ConvexOptimization.get_metadata_routing)() | Get metadata routing of this object.                                                                                              |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.ConvexOptimization.html.md#skfolio.optimization.ConvexOptimization.get_params)([deep])     | Get parameters for this estimator.                                                                                                |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.ConvexOptimization.html.md#skfolio.optimization.ConvexOptimization.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                   |
| [`score`](https://skfolio.org/generated/skfolio.optimization.ConvexOptimization.html.md#skfolio.optimization.ConvexOptimization.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                          |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.ConvexOptimization.html.md#skfolio.optimization.ConvexOptimization.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                             |

| **fit**   |    |
|-----------|----|

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

<a id="skfolio.optimization.ConvexOptimization.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.ConvexOptimization.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.optimization.ConvexOptimization.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.optimization.ConvexOptimization.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.ConvexOptimization.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.ConvexOptimization.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.ConvexOptimization.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.

# generated/skfolio.optimization.DistributionallyRobustCVaR.html.md

<a id="skfolio-optimization-distributionallyrobustcvar"></a>

# skfolio.optimization.DistributionallyRobustCVaR

<a id="skfolio.optimization.DistributionallyRobustCVaR"></a>

### *class* skfolio.optimization.DistributionallyRobustCVaR(risk_aversion=1.0, cvar_beta=0.95, wasserstein_ball_radius=0.02, prior_estimator=None, min_weights=0.0, max_weights=1.0, budget=1, min_budget=None, max_budget=None, max_short=None, max_long=None, groups=None, linear_constraints=None, left_inequality=None, right_inequality=None, risk_free_rate=0.0, solver='CLARABEL', solver_params=None, scale_objective=None, scale_constraints=None, save_problem=False, add_objective=None, add_constraints=None, overwrite_expected_return=None, portfolio_params=None, fallback=None, previous_weights=None, raise_on_failure=True)

Distributionally Robust CVaR.

The Distributionally Robust CVaR model constructs a Wasserstein ball in the space of
multivariate and non-discrete probability distributions centered at the uniform
distribution on the training samples and finds the allocation that minimizes the
CVaR of the worst-case distribution within this Wasserstein ball.
Esfahani and Kuhn [[1]](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#r75a2f8fbeddd-1) proved that for piecewise linear objective functions,
which is the case of CVaR [[2]](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#r75a2f8fbeddd-2), the distributionally robust optimization problem
over a Wasserstein ball can be reformulated as finite convex programs.

Only piecewise linear functions are supported, which means that transaction costs
and regularization are not permitted.

A solver like `Mosek` that can handle a high number of constraints is preferred.

* **Parameters:**
  **cvar_beta** *float, default=0.95*
  : CVaR (Conditional Value at Risk) confidence level.

  **risk_aversion** *float, default=1.0*
  : Risk aversion factor of the utility function: return - risk_aversion \* cvar.

  **wasserstein_ball_radius: float, default=0.02**
  : Radius of the Wasserstein ball.

  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator 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 of the covariance.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **min_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=0.0*
  : Minimum assets weights (weights lower bounds).
    If a float is provided, it is applied to each asset.
    `None` is equivalent to `-np.Inf` (no lower bound).
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset minimum weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a minimum weight of `0.0`.
    The default value is `0.0` (no short selling).
    <br/>
    Example:
    > * `min_weights = 0` –> long only portfolio (no short selling).
    > * `min_weights = None` –> no lower bound (same as `-np.Inf`).
    > * `min_weights = -2` –> each weight must be above -200%.
    > * `min_weights = {"SX5E": 0, "SPX": -2}`
    > * `min_weights = [0, -2]`

  **max_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=1.0*
  : Maximum assets weights (weights upper bounds).
    If a float is provided, it is applied to each asset.
    `None` is equivalent to `+np.Inf` (no upper bound).
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset maximum weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a minimum weight of `1.0`.
    The default value is `1.0` (each asset is below 100%).
    <br/>
    Example:
    > * `max_weights = 0` –> no long position (short only portfolio).
    > * `max_weights = None` –> no upper bound.
    > * `max_weights = 2` –> each weight must be below 200%.
    > * `max_weights = {"SX5E": 1, "SPX": 2}`
    > * `max_weights = [1, 2]`

  **budget** *float | None, default=1.0*
  : Investment budget. It is the sum of long positions and short positions (sum of
    all weights). `None` means no budget constraints.
    The default value is `1.0` (fully invested portfolio).
    <br/>
    For example:
    > * `budget = 1` –> fully invested portfolio.
    > * `budget = 0` –> market neutral portfolio.
    > * `budget = None` –> no constraints on the sum of weights.

  **min_budget** *float, optional*
  : Minimum budget. It is the lower bound of the sum of long and short positions
    (sum of all weights). If provided, you must set `budget=None`.
    The default (`None`) means no minimum budget constraint.

  **max_short** *float, optional*
  : Maximum short position. The short position is defined as the sum of negative
    weights (in absolute term).
    The default (`None`) means no maximum short position.

  **max_long** *float, optional*
  : Maximum long position. The long position is defined as the sum of positive
    weights.
    The default (`None`) means no maximum long position.

  **max_budget** *float, optional*
  : Maximum budget. It is the upper bound of the sum of long and short positions
    (sum of all weights). If provided, you must set `budget=None`.
    The default (`None`) means no maximum budget constraint.

  **linear_constraints** *array-like of shape (n_constraints,), optional*
  : Linear constraints on portfolio weights or factor exposures.
    <br/>
    Constraint names can reference:
    > * Asset names: individual asset weights (e.g. `"SPX"`, `"AAPL"`)
    > * Group names: sums of weights in groups defined by `groups`
    > * Factor names: portfolio factor exposure (requires factor model prior)
    > * Factor families: sum of portfolio exposures to all factors in one family
    <br/>
    Supported equation patterns include:
    > * `"name <= value"` or `"name >= value"`
    > * `"name == value"`
    > * `"a * name1 + b * name2 <= c * name3 + d"`
    <br/>
    For example:
    > * `"SPX >= 0.10"` –> SPX weight >= 10%
    > * `"SX5E + SPX >= 0.2"` –> sum of SX5E and SPX weights >= 20%
    > * `"US == 0.7"` –> sum of weights in US group == 70%
    > * `"Equity == 3 * Bond"` –> sum of weights in Equity group == 3x sum of weights in Bond group
    > * `"Momentum <= 0.30"` –> portfolio Momentum exposure <= 30%
    > * `"style <= 0.50"` –> sum of all style factor exposures (Momentum, Value, Size, etc.) <= 50%
    <br/>
    Factor constraints require a prior estimator (e.g.
    [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel),
    [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel))
    that provides `loading_matrix`, `factor_names` and optionally `factor_families`
    in its [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel).
    <br/>
    Asset, group, factor, and factor family names must be unique.

  **groups** *dict[str, list[str]] or array-like of shape (n_groups, n_assets), optional*
  : The assets groups referenced in `linear_constraints`.
    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"]]`

  **left_inequality** *array-like of shape (n_constraints, n_assets), optional*
  : Left inequality matrix $A$ of the linear
    constraint $A \cdot w \leq b$.

  **right_inequality** *array-like of shape (n_constraints, ), optional*
  : Right inequality vector $b$ of the linear
    constraint $A \cdot w \leq b$.

  **risk_free_rate** *float, default=0.0*
  : Risk-free interest rate.
    The default value is `0.0`.

  **add_constraints** *Callable[[cp.Variable], cp.Expression | list[cp.Expression]], optional*
  : Add a custom constraint or a list of constraints to the existing constraints.
    It must be a function taking the CVXPY weight variable `w` as its first
    positional argument and, optionally, the estimator instance as its second.
    It must return a CVXPY expression or a list of CVXPY expressions, evaluated
    when `fit` is called.
    <br/>
    For example, to require an effective number of assets of at least 20:
    ```pycon
    >>> import cvxpy as cp
    >>> from skfolio.optimization import DistributionallyRobustCVaR
    >>> model = DistributionallyRobustCVaR(
    ...     add_constraints=lambda w: cp.sum_squares(w) <= 1 / 20
    ... )
    ```
    <br/>
    The optional second argument gives access to the estimator’s attributes,
    including quantities estimated during `fit`. For example, to cap each
    position size in risk units at 20 bps, using the volatilities estimated
    by the prior:
    ```pycon
    >>> import numpy as np
    >>> def position_risk_cap(w, model):
    ...     covariance = model.prior_estimator_.return_distribution_.covariance
    ...     vols = np.sqrt(np.diag(covariance))
    ...     return cp.multiply(vols, w) <= 0.002
    >>> model = DistributionallyRobustCVaR(add_constraints=position_risk_cap)
    ```

  **overwrite_expected_return** *Callable[[cp.Variable], cp.Expression], optional*
  : Overwrite the expected return $\mu \cdot w$ with a custom CVXPY
    expression. It must be a function taking the CVXPY weight variable `w` as
    its first positional argument and, optionally, the estimator instance as
    its second. It must return a concave CVXPY expression, evaluated when
    `fit` is called. The custom expression replaces the expected return in the
    objective function and in the constraints where the expected return is
    used.
    <br/>
    For example, to adjust the expected return for volatility drag,
    approximating the portfolio geometric mean return:
    ```pycon
    >>> import cvxpy as cp
    >>> from skfolio.optimization import DistributionallyRobustCVaR
    >>> def geometric_expected_return(w, model):
    ...     dist = model.prior_estimator_.return_distribution_
    ...     return dist.mu @ w - 0.5 * cp.quad_form(w, dist.covariance)
    >>> model = DistributionallyRobustCVaR(
    ...     overwrite_expected_return=geometric_expected_return
    ... )
    ```

  **solver** *str, default=”CLARABEL”*
  : The solver to use. The default is “CLARABEL” which is written in Rust and has
    better numerical stability and performance than ECOS and SCS. Cvxpy will replace
    its default solver “ECOS” by “CLARABEL” in future releases.
    For more details about available solvers, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver](https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver)

  **solver_params** *dict, optional*
  : Solver parameters. For example, `solver_params=dict(verbose=True)`.
    The default (`None`) is to use `{"tol_gap_abs": 1e-9, "tol_gap_rel": 1e-9}`
    for the solver “CLARABEL” and the CVXPY default otherwise.
    For more details about solver arguments, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options](https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options)

  **scale_objective** *float, optional*
  : Scale each objective element by this value.
    It can be used to increase the optimization accuracies in specific cases.
    The default (`None`) is set depending on the problem.

  **scale_constraints** *float, optional*
  : Scale each constraint element by this value.
    It can be used to increase the optimization accuracies in specific cases.
    The default (`None`) is set depending on the problem.

  **save_problem** *bool, default=False*
  : If this is set to True, the CVXPY Problem is saved in `problem_`.
    The default is `False`.

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    `transaction_costs`, `management_fees`, `previous_weights` and `risk_free_rate`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets,), optional*
  : When `fallback="previous_weights"`, failures will fall back to these weights if
    provided.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,) or (n_optimizations, n_assets)*
  : Weights of the assets.

  **problem_values_** *dict[str, float] | list[dict[str, float]] of size n_optimizations*
  : Expression values retrieved from the CVXPY problem.

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

  **problem_: cvxpy.Problem**
  : CVXPY problem used for the optimization. Only when `save_problem` is set to
    `True`.

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

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR.fit)(X[, y])            | Fit the Distributionally Robust CVaR Optimization estimator.                                                                    |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

### References

* <a id='r75a2f8fbeddd-1'>**[1]**</a> “Data-driven distributionally robust optimization using the Wasserstein metric: performance guarantees and tractable reformulations”. Esfahani and Kuhn (2018).
* <a id='r75a2f8fbeddd-2'>**[2]**</a> “Optimization of conditional value-at-risk”. Rockafellar and Uryasev (2000).

### Examples

For a complete tutorial on distributionally robust CVaR optimization, see the
[Distributionally Robust CVaR](https://skfolio.org/auto_examples/distributionally_robust_cvar/index.html.md#distributionally-robust-examples) gallery.

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.optimization import DistributionallyRobustCVaR
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> # Use the most recent 252 daily returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices).tail(252)
>>>
>>> # Distributionally robust CVaR optimization
>>> model = DistributionallyRobustCVaR(wasserstein_ball_radius=0.01)
>>> model.fit(X)
DistributionallyRobustCVaR(wasserstein_ball_radius=0.01)
>>> print(model.weights_)
[0.     0.     0.0706 ... 0.0706 0.0706 0.0706]
>>>
>>> # Increasing the radius increases the uncertainty around the distribution,
>>> # which brings the weights closer to equal weighting
>>> model = DistributionallyRobustCVaR(wasserstein_ball_radius=0.10)
>>> model.fit(X)
DistributionallyRobustCVaR(wasserstein_ball_radius=0.1)
>>> print(model.weights_)
[0.05 0.05 0.05 ... 0.05 0.05 0.05]
```

<a id="skfolio.optimization.DistributionallyRobustCVaR.fit"></a>

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

Fit the Distributionally Robust CVaR Optimization estimator.

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

  **y** *array-like of shape (n_observations, n_factors), optional*
  : Price returns of factors.
    The default is `None`.

  **\*\*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** *DistributionallyRobustCVaR*
  : Fitted estimator.

<a id="skfolio.optimization.DistributionallyRobustCVaR.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.DistributionallyRobustCVaR.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.optimization.DistributionallyRobustCVaR.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.optimization.DistributionallyRobustCVaR.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.DistributionallyRobustCVaR.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.DistributionallyRobustCVaR.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.DistributionallyRobustCVaR.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.

# generated/skfolio.optimization.EqualWeighted.html.md

<a id="skfolio-optimization-equalweighted"></a>

# skfolio.optimization.EqualWeighted

<a id="skfolio.optimization.EqualWeighted"></a>

### *class* skfolio.optimization.EqualWeighted(portfolio_params=None, fallback=None, previous_weights=None, raise_on_failure=True)

Equally Weighted estimator.

Each asset weight is equal to `1/n_assets`.

* **Parameters:**
  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    and `previous_weights`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets,), optional*
  : When `fallback="previous_weights"`, failures will fall back to these weights
    if provided.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,) or (n_optimizations, n_assets)*
  : Weights of the assets.

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted.fit)(X[, y])            | Fit the Equal Weighted estimator.                                                                                               |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

<a id="skfolio.optimization.EqualWeighted.fit"></a>

#### fit(X, y=None)

Fit the Equal Weighted 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.
* **Returns:**
  **self** *EqualWeighted*
  : Fitted estimator.

<a id="skfolio.optimization.EqualWeighted.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.EqualWeighted.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.optimization.EqualWeighted.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.optimization.EqualWeighted.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.EqualWeighted.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.EqualWeighted.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.EqualWeighted.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.

# generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md

<a id="skfolio-optimization-hierarchicalequalriskcontribution"></a>

# skfolio.optimization.HierarchicalEqualRiskContribution

<a id="skfolio.optimization.HierarchicalEqualRiskContribution"></a>

### *class* skfolio.optimization.HierarchicalEqualRiskContribution(risk_measure=Variance, prior_estimator=None, distance_estimator=None, hierarchical_clustering_estimator=None, min_weights=0.0, max_weights=1.0, solver='CLARABEL', solver_params=None, transaction_costs=0.0, management_fees=0.0, previous_weights=None, portfolio_params=None, fallback=None, raise_on_failure=True)

Hierarchical Equal Risk Contribution estimator.

The Hierarchical Equal Risk Contribution is a portfolio optimization method
developed by Thomas Raffinot [[2]](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#rc628ffe0b6ca-2).

This algorithm uses a distance matrix to compute hierarchical clusters using the
Hierarchical Tree Clustering algorithm. It then computes, for each cluster, the
total cluster risk of an inverse-risk allocation.

The final step is the top-down recursive division of the dendrogram, where the
assets weights are updated using a naive risk parity within clusters.

It differs from the Hierarchical Risk Parity by exploiting the dendrogram shape
during the top-down recursive division instead of bisecting it.

#### NOTE
The default linkage method is set to the Ward variance minimization algorithm,
which is more stable and has better properties than the single-linkage
method [[4]](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#rc628ffe0b6ca-4).

Also, the initial paper does not provide an algorithm for handling weight
constraints, and no standard solution currently exists.
In contrast to HRP (Hierarchical Risk Parity), where weight constraints
can be applied to the split factor at each bisection step, HERC
(Hierarchical Equal Risk Contribution) cannot incorporate weight constraints
during the intermediate steps of the allocation. Therefore, in HERC, the
weight constraints must be enforced after the top-down allocation has been
completed.
In skfolio, we minimize the relative deviation of the final weights from
the initial weights. This is formulated as a convex optimization problem:

$$
\begin{cases}
\begin{aligned}
&\min_{w} & & \Vert \frac{w - w_{init}}{w_{init}} \Vert_{2}^{2} \\
&\text{s.t.} & & \sum_{i=1}^{N} w_{i} = 1 \\
& & & w_{min} \leq w_i \leq w_{max}, \quad \forall i
\end{aligned}
\end{cases}

$$

The reason for minimizing the relative deviation (as opposed to the absolute
deviation) is that we want to limit the impact on the risk contribution of
each asset. Since HERC allocates inversely to risk, adjusting the weights
based on relative deviation ensures that the assets’ risk contributions
remain proportionally consistent with the initial allocation.

* **Parameters:**
  **risk_measure** *RiskMeasure or ExtraRiskMeasure, default=RiskMeasure.VARIANCE*
  : `RiskMeasure` or `ExtraRiskMeasure`
    of the optimization.
    Can be any of:
    > * MEAN_ABSOLUTE_DEVIATION
    > * FIRST_LOWER_PARTIAL_MOMENT
    > * VARIANCE
    > * SEMI_VARIANCE
    > * CVAR
    > * EVAR
    > * WORST_REALIZATION
    > * CDAR
    > * MAX_DRAWDOWN
    > * AVERAGE_DRAWDOWN
    > * EDAR
    > * ULCER_INDEX
    > * GINI_MEAN_DIFFERENCE_RATIO
    > * VALUE_AT_RISK
    > * DRAWDOWN_AT_RISK
    > * ENTROPIC_RISK_MEASURE
    > * FOURTH_CENTRAL_MOMENT
    > * FOURTH_LOWER_PARTIAL_MOMENT
    <br/>
    The default is `RiskMeasure.VARIANCE`.

  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator 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 and
    returns. The moments and returns estimations are used for the risk computation
    and the returns estimation are used by the distance matrix estimator.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **distance_estimator** *BaseDistance, optional*
  : [Distance estimator](https://skfolio.org/user_guide/distance.html.md#distance).
    The distance estimator is used to estimate the codependence and the distance
    matrix needed for the computation of the linkage matrix.
    The default (`None`) is to use [`PearsonDistance`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance).

  **hierarchical_clustering_estimator** *HierarchicalClustering, optional*
  : [Hierarchical Clustering estimator](https://skfolio.org/user_guide/cluster.html.md#hierarchical-clustering).
    The hierarchical clustering estimator is used to compute the linkage matrix
    and the hierarchical clustering of the assets based on the distance matrix.
    The default (`None`) is to use
    [`HierarchicalClustering`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering).

  **min_weights** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Minimum assets weights (weights lower bounds). The default is 0.0 (no short
    selling). Negative weights are not allowed. If a float is provided, it is
    applied to each asset. `None` is equivalent to the default `0.0`. If a
    dictionary is provided, its (key/value) pair must be the (asset name/asset
    minimum weight) and the input `X` of the `fit` methods must be a DataFrame with
    the asset names in columns. When using a dictionary, assets values that are not
    provided are assigned the default  minimum weight of `0.0`.
    <br/>
    Example:
    > * `min_weights = 0.0` –> long only portfolio (default).
    > * `min_weights = {"SX5E": 0.1, "SPX": 0.2}`
    > * `min_weights = [0.1, 0.2]`

  **max_weights** *float | dict[str, float] | array-like of shape (n_assets, ), default=1.0*
  : Maximum assets weights (weights upper bounds). The default is 1.0 (each asset
    is below 100%). Weights above 1.0 are not allowed. If a float is provided, it is
    applied to each asset. `None` is equivalent to the default `1.0`. If a
    dictionary is provided, its (key/value) pair must be the (asset name/asset
    maximum weight) and the input `X` of the `fit` method must be a DataFrame with
    the asset names in columns. When using a dictionary, assets values that are not
    provided are assigned the default maximum weight of `1.0`.
    <br/>
    Example:
    > * `max_weights = 1.0` –> each weight  must be below 100% (default).
    > * `max_weights = 0.5` –> each weight must be below 50%.
    > * `max_weights = {"SX5E": 0.8, "SPX": 0.9}`
    > * `max_weights = [0.8, 0.9]`

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Transaction costs of the assets. It is used to add linear transaction costs to
    the optimization problem:
    $$
    total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|
    <br/>
    $$
    <br/>
    with $c_{i}$ the transaction cost of asset i, $w_{i}$ its weight
    and $w\_prev_{i}$ its previous weight (defined in `previous_weights`).
    The float $total\_cost$ is impacting the portfolio expected return in the
    optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_cost
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the
    vector of assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset cost) and the input `X` of the `fit` method must be a
    DataFrame with the asset names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the transaction costs
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `transaction_costs` need to be
    expressed as **daily** costs. A transaction cost is paid once per
    rebalancing while a position earns its expected return on every period it
    is held, so the one-off cost is converted by dividing it by the expected
    investment duration (e.g. `0.001 / 21` for a 10 bps cost with daily
    returns and a one-month expected holding period).
    (See [Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention))

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Management fees of the assets. It is used to add linear management fees to the
    optimization problem:
    $$
    total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}
    <br/>
    $$
    <br/>
    with $f_{i}$ the management fee of asset i and $w_{i}$ its weight.
    The float $total\_fee$ is impacting the portfolio expected return in the
    optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_fee
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the vector
    of assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset fee) and the input `X` of the `fit` method must be a
    DataFrame with the asset names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the management fees
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `management_fees` need to be
    expressed in **daily** fees. Unlike transaction costs, management fees
    accrue with holding time, so a stated annual fee converts directly to the
    return periodicity (e.g. `0.02 / 252` for a 2% annual fee on daily
    returns).
    <br/>
    #### NOTE
    Another approach is to directly impact the management fees to the input `X`
    in order to express the returns net of fees. However, when estimating the
    $\mu$ parameter using for example Shrinkage estimators, this approach
    would mix a deterministic value with an uncertain one leading to unwanted
    bias in the management fees.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Previous weights of the assets. Previous weights are used to compute the
    portfolio total cost. If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset previous weight) and the input `X` of the `fit` method must
    be a DataFrame with the asset names in columns.
    The default (`None`) means no previous weights.
    Additionally, when `fallback="previous_weights"`, failures will fall back to
    these weights if provided.

  **solver** *str, default=”CLARABEL”*
  : The solver used for the weights constraints optimization. The default is
    “CLARABEL” which is written in Rust and has better numerical stability and
    performance than ECOS and SCS.
    For more details about available solvers, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver](https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver)

  **solver_params** *dict, optional*
  : Solver parameters. For example, `solver_params=dict(verbose=True)`.
    The default (`None`) is to use the CVXPY default.
    For more details about solver arguments, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options](https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options)

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    `transaction_costs`, `management_fees`, `previous_weights` and `risk_free_rate`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"` 
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary 
    estimator so that `fit` still returns the original instance. For traceability, 
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,)*
  : Weights of the assets.

  **distance_estimator_** *BaseDistance*
  : Fitted `distance_estimator`.

  **hierarchical_clustering_estimator_** *HierarchicalClustering*
  : Fitted `hierarchical_clustering_estimator`.

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

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution.fit)(X[, y])            | Fit the Hierarchical Equal Risk Contribution estimator.                                                                         |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

### References

* <a id='rc628ffe0b6ca-1'>**[1]**</a> “Hierarchical clustering-based asset allocation”, The Journal of Portfolio Management, Thomas Raffinot  (2017).
* <a id='rc628ffe0b6ca-2'>**[2]**</a> “The hierarchical equal risk contribution portfolio”, Thomas Raffinot (2018).
* <a id='rc628ffe0b6ca-3'>**[3]**</a> “Application of two-order difference to gap statistic”. Yue, Wang & Wei (2009).
* <a id='rc628ffe0b6ca-4'>**[4]**</a> “A review of two decades of correlations, hierarchies, networks and clustering in financial markets”, Gautier Marti, Frank Nielsen, Mikołaj Bińkowski, Philippe Donnat (2020).

<a id="skfolio.optimization.HierarchicalEqualRiskContribution.fit"></a>

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

Fit the Hierarchical Equal Risk Contribution 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** *HierarchicalEqualRiskContribution*
  : Fitted estimator.

<a id="skfolio.optimization.HierarchicalEqualRiskContribution.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.HierarchicalEqualRiskContribution.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.optimization.HierarchicalEqualRiskContribution.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.optimization.HierarchicalEqualRiskContribution.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.HierarchicalEqualRiskContribution.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.HierarchicalEqualRiskContribution.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.HierarchicalEqualRiskContribution.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.

# generated/skfolio.optimization.HierarchicalRiskParity.html.md

<a id="skfolio-optimization-hierarchicalriskparity"></a>

# skfolio.optimization.HierarchicalRiskParity

<a id="skfolio.optimization.HierarchicalRiskParity"></a>

### *class* skfolio.optimization.HierarchicalRiskParity(risk_measure=Variance, prior_estimator=None, distance_estimator=None, hierarchical_clustering_estimator=None, min_weights=0.0, max_weights=1.0, transaction_costs=0.0, management_fees=0.0, previous_weights=None, portfolio_params=None, fallback=None, raise_on_failure=True)

Hierarchical Risk Parity estimator.

Hierarchical Risk Parity is a portfolio optimization method developed by Marcos
Lopez de Prado [[1]](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#rc46ad8b9ead3-1).

This algorithm uses a distance matrix to compute hierarchical clusters using the
Hierarchical Tree Clustering algorithm. It then employs seriation to rearrange the
assets in the dendrogram, minimizing the distance between leaves.

The final step is the recursive bisection where each cluster is split between two
sub-clusters by starting with the topmost cluster and traversing in a top-down
manner. For each sub-cluster, we compute the total cluster risk of an inverse-risk
allocation. A weighting factor is then computed from these two sub-cluster risks,
which is used to update the cluster weight.

#### NOTE
The original paper uses the variance as the risk measure and the single-linkage
method for the Hierarchical Tree Clustering algorithm. Here we generalize it to
multiple risk measures and linkage methods.
The default linkage method is set to the Ward
variance minimization algorithm, which is more stable and has better properties
than the single-linkage method [[2]](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#rc46ad8b9ead3-2).

* **Parameters:**
  **risk_measure** *RiskMeasure or ExtraRiskMeasure, default=RiskMeasure.VARIANCE*
  : `RiskMeasure` or `ExtraRiskMeasure`
    of the optimization.
    Can be any of:
    > * MEAN_ABSOLUTE_DEVIATION
    > * FIRST_LOWER_PARTIAL_MOMENT
    > * VARIANCE
    > * SEMI_VARIANCE
    > * CVAR
    > * EVAR
    > * WORST_REALIZATION
    > * CDAR
    > * MAX_DRAWDOWN
    > * AVERAGE_DRAWDOWN
    > * EDAR
    > * ULCER_INDEX
    > * GINI_MEAN_DIFFERENCE_RATIO
    > * VALUE_AT_RISK
    > * DRAWDOWN_AT_RISK
    > * ENTROPIC_RISK_MEASURE
    > * FOURTH_CENTRAL_MOMENT
    > * FOURTH_LOWER_PARTIAL_MOMENT
    <br/>
    The default is `RiskMeasure.VARIANCE`.

  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator 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 and
    returns. The moments and returns estimations are used for the risk computation
    and the returns estimation are used by the distance matrix estimator.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **distance_estimator** *BaseDistance, optional*
  : [Distance estimator](https://skfolio.org/user_guide/distance.html.md#distance).
    The distance estimator is used to estimate the codependence and the distance
    matrix needed for the computation of the linkage matrix.
    The default (`None`) is to use [`PearsonDistance`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance).

  **hierarchical_clustering_estimator** *HierarchicalClustering, optional*
  : [Hierarchical Clustering estimator](https://skfolio.org/user_guide/cluster.html.md#hierarchical-clustering).
    The hierarchical clustering estimator is used to compute the linkage matrix
    and the hierarchical clustering of the assets based on the distance matrix.
    The default (`None`) is to use
    [`HierarchicalClustering`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering).

  **min_weights** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Minimum assets weights (weights lower bounds). The default is 0.0 (no short
    selling). Negative weights are not allowed. If a float is provided, it is
    applied to each asset. `None` is equivalent to the default `0.0`. If a
    dictionary is provided, its (key/value) pair must be the (asset name/asset
    minimum weight) and the input `X` of the `fit` methods must be a DataFrame with
    the asset names in columns. When using a dictionary, assets values that are not
    provided are assigned the default  minimum weight of `0.0`.
    <br/>
    Example:
    > * `min_weights = 0.0` –> long only portfolio (default).
    > * `min_weights = {"SX5E": 0.1, "SPX": 0.2}`
    > * `min_weights = [0.1, 0.2]`

  **max_weights** *float | dict[str, float] | array-like of shape (n_assets, ), default=1.0*
  : Maximum assets weights (weights upper bounds). The default is 1.0 (each asset
    is below 100%). Weights above 1.0 are not allowed. If a float is provided, it is
    applied to each asset. `None` is equivalent to the default `1.0`. If a
    dictionary is provided, its (key/value) pair must be the (asset name/asset
    maximum weight) and the input `X` of the `fit` method must be a DataFrame with
    the asset names in columns. When using a dictionary, assets values that are not
    provided are assigned the default maximum weight of `1.0`.
    <br/>
    Example:
    > * `max_weights = 1.0` –> each weight  must be below 100% (default).
    > * `max_weights = 0.5` –> each weight must be below 50%.
    > * `max_weights = {"SX5E": 0.8, "SPX": 0.9}`
    > * `max_weights = [0.8, 0.9]`

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Transaction costs of the assets. It is used to add linear transaction costs to
    the optimization problem:
    $$
    total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|
    <br/>
    $$
    <br/>
    with $c_{i}$ the transaction cost of asset i, $w_{i}$ its weight
    and $w\_prev_{i}$ its previous weight (defined in `previous_weights`).
    The float $total\_cost$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_cost
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the
    vector of assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset cost) and the input `X` of the `fit` method must be a
    DataFrame with the asset names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the transaction costs
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `transaction_costs` need to be
    expressed as **daily** costs. A transaction cost is paid once per
    rebalancing while a position earns its expected return on every period it
    is held, so the one-off cost is converted by dividing it by the expected
    investment duration (e.g. `0.001 / 21` for a 10 bps cost with daily
    returns and a one-month expected holding period).
    (See [Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention))

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Management fees of the assets. It is used to add linear management fees to the
    optimization problem:
    $$
    total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}
    <br/>
    $$
    <br/>
    with $f_{i}$ the management fee of asset i and $w_{i}$ its weight.
    The float $total\_fee$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_fee
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the vector
    of assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset fee) and the input `X` of the `fit` method must be a
    DataFrame with the asset names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the management fees
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `management_fees` need to be
    expressed in **daily** fees. Unlike transaction costs, management fees
    accrue with holding time, so a stated annual fee converts directly to the
    return periodicity (e.g. `0.02 / 252` for a 2% annual fee on daily
    returns).
    <br/>
    #### NOTE
    Another approach is to directly impact the management fees to the input `X`
    in order to express the returns net of fees. However, when estimating the
    $\mu$ parameter using for example Shrinkage estimators, this approach
    would mix a deterministic value with an uncertain one leading to unwanted
    bias in the management fees.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Previous weights of the assets. Previous weights are used to compute the
    portfolio total cost. If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset previous weight) and the input `X` of the `fit` method must
    be a DataFrame with the asset names in columns.
    The default (`None`) means no previous weights.
    Additionally, when `fallback="previous_weights"`, failures will fall back to
    these weights if provided.

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    `transaction_costs`, `management_fees`, `previous_weights` and `risk_free_rate`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,)*
  : Weights of the assets.

  **distance_estimator_** *BaseDistance*
  : Fitted `distance_estimator`.

  **hierarchical_clustering_estimator_** *HierarchicalClustering*
  : Fitted `hierarchical_clustering_estimator`.

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

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity.fit)(X[, y])            | Fit the Hierarchical Risk Parity Optimization estimator.                                                                        |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

### References

* <a id='rc46ad8b9ead3-1'>**[1]**</a> “A robust estimator of the efficient frontier”, SSRN Electronic Journal, Marcos López de Prado (2019).
* <a id='rc46ad8b9ead3-2'>**[2]**</a> “A review of two decades of correlations, hierarchies, networks and clustering in financial markets”, Gautier Marti, Frank Nielsen, Mikołaj Bińkowski, Philippe Donnat (2020).
* <a id='rc46ad8b9ead3-3'>**[3]**</a> “Portfolio Optimization: Theory and Application”, Chapter 12, Daniel P. Palomar (2025)
* <a id='rc46ad8b9ead3-4'>**[4]**</a> “Building diversified portfolios that outperform out of sample”, The Journal of Portfolio Management, Marcos López de Prado (2016).
* <a id='rc46ad8b9ead3-5'>**[5]**</a> “Machine Learning for Asset Managers”, Elements in Quantitative Finance. Cambridge University Press, Marcos López de Prado (2020).

<a id="skfolio.optimization.HierarchicalRiskParity.fit"></a>

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

Fit the Hierarchical Risk Parity Optimization 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.
* **Returns:**
  **self** *HierarchicalRiskParity*
  : Fitted estimator.

<a id="skfolio.optimization.HierarchicalRiskParity.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.HierarchicalRiskParity.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.optimization.HierarchicalRiskParity.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.optimization.HierarchicalRiskParity.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.HierarchicalRiskParity.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.HierarchicalRiskParity.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.HierarchicalRiskParity.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.

# generated/skfolio.optimization.InverseVolatility.html.md

<a id="skfolio-optimization-inversevolatility"></a>

# skfolio.optimization.InverseVolatility

<a id="skfolio.optimization.InverseVolatility"></a>

### *class* skfolio.optimization.InverseVolatility(prior_estimator=None, portfolio_params=None, fallback=None, previous_weights=None, raise_on_failure=True)

Inverse Volatility estimator.

Each asset weight is computed using the inverse of its volatility and rescaled to
have a sum of weights equal to one. The assets volatilities are derived from the
prior estimator’s covariance matrix.

* **Parameters:**
  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator 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 of the covariance.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    and `previous_weights`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets,), optional*
  : When `fallback="previous_weights"`, failures will fall back to these weights
    if provided.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,) or (n_optimizations, n_assets)*
  : Weights of the assets.

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.InverseVolatility.html.md#skfolio.optimization.InverseVolatility.fit)(X[, y])            | Fit the Inverse Volatility estimator.                                                                                           |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.InverseVolatility.html.md#skfolio.optimization.InverseVolatility.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.InverseVolatility.html.md#skfolio.optimization.InverseVolatility.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.InverseVolatility.html.md#skfolio.optimization.InverseVolatility.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.InverseVolatility.html.md#skfolio.optimization.InverseVolatility.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.InverseVolatility.html.md#skfolio.optimization.InverseVolatility.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.InverseVolatility.html.md#skfolio.optimization.InverseVolatility.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

<a id="skfolio.optimization.InverseVolatility.fit"></a>

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

Fit the Inverse Volatility estimator.

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

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Price returns of factors or a target benchmark.
    The default is `None`.

  **\*\*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** *InverseVolatility*
  : Fitted estimator.

<a id="skfolio.optimization.InverseVolatility.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.InverseVolatility.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.optimization.InverseVolatility.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.optimization.InverseVolatility.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.InverseVolatility.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.InverseVolatility.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.InverseVolatility.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.

# generated/skfolio.optimization.MaximumDiversification.html.md

<a id="skfolio-optimization-maximumdiversification"></a>

# skfolio.optimization.MaximumDiversification

<a id="skfolio.optimization.MaximumDiversification"></a>

### *class* skfolio.optimization.MaximumDiversification(prior_estimator=None, min_weights=0.0, max_weights=1.0, budget=1.0, min_budget=None, max_budget=None, max_short=None, max_long=None, cardinality=None, group_cardinalities=None, threshold_long=None, threshold_short=None, transaction_costs=0.0, management_fees=0.0, previous_weights=None, groups=None, linear_constraints=None, left_inequality=None, right_inequality=None, l1_coef=0.0, l2_coef=0.0, risk_free_rate=0.0, min_return=None, max_tracking_error=None, max_turnover=None, solver='CLARABEL', solver_params=None, scale_objective=None, scale_constraints=None, save_problem=False, add_objective=None, add_constraints=None, portfolio_params=None, fallback=None, raise_on_failure=True)

Maximum Diversification Optimization estimator.

Maximizes the diversification ratio which is the ratio of the weighted volatilities
over the total volatility.

It is a special case of the [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) estimator where
the expected return from the objective function is replaced by the weighted
volatilities.

* **Parameters:**
  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator 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 of the covariance.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **min_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=0.0*
  : Minimum assets weights (weights lower bounds).
    If a float is provided, it is applied to each asset.
    `None` is equivalent to `-np.Inf` (no lower bound).
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset minimum weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a minimum weight of `0.0`.
    The default value is `0.0` (no short selling).
    <br/>
    Example:
    > * `min_weights = 0` –> long only portfolio (no short selling).
    > * `min_weights = None` –> no lower bound (same as `-np.Inf`).
    > * `min_weights = -2` –> each weight must be above -200%.
    > * `min_weights = {"SX5E": 0, "SPX": -2}`
    > * `min_weights = [0, -2]`

  **max_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=1.0*
  : Maximum assets weights (weights upper bounds).
    If a float is provided, it is applied to each asset.
    `None` is equivalent to `+np.Inf` (no upper bound).
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset maximum weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a minimum weight of `1.0`.
    The default value is `1.0` (each asset is below 100%).
    <br/>
    Example:
    > * `max_weights = 0` –> no long position (short only portfolio).
    > * `max_weights = None` –> no upper bound.
    > * `max_weights = 2` –> each weight must be below 200%.
    > * `max_weights = {"SX5E": 1, "SPX": 2}`
    > * `max_weights = [1, 2]`

  **budget** *float | None, default=1.0*
  : Investment budget. It is the sum of long positions and short positions (sum of
    all weights). `None` means no budget constraints.
    The default value is `1.0` (fully invested portfolio).
    <br/>
    For example:
    > * `budget = 1` –> fully invested portfolio.
    > * `budget = 0` –> market neutral portfolio.
    > * `budget = None` –> no constraints on the sum of weights.

  **min_budget** *float, optional*
  : Minimum budget. It is the lower bound of the sum of long and short positions
    (sum of all weights). If provided, you must set `budget=None`.
    The default (`None`) means no minimum budget constraint.

  **max_budget** *float, optional*
  : Maximum budget. It is the upper bound of the sum of long and short positions
    (sum of all weights). If provided, you must set `budget=None`.
    The default (`None`) means no maximum budget constraint.

  **max_short** *float, optional*
  : Maximum short position. The short position is defined as the sum of negative
    weights (in absolute term).
    The default (`None`) means no maximum short position.

  **max_long** *float, optional*
  : Maximum long position. The long position is defined as the sum of positive
    weights.
    The default (`None`) means no maximum long position.

  **cardinality** *int, optional*
  : Specifies the cardinality constraint to limit the number of invested assets
    (non-zero weights). This feature requires a mixed-integer solver. For an
    open-source option, we recommend using SCIP by setting `solver="SCIP"`.
    To install it, use: `pip install cvxpy[SCIP]`. For commercial solvers,
    supported options include MOSEK, GUROBI, or CPLEX.

  **group_cardinalities** *dict[str, int], optional*
  : A dictionary specifying cardinality constraints for specific groups of assets.
    The keys represent group names (strings), and the values specify the maximum
    number of assets allowed in each group. You must provide the groups using the
    `groups` parameter. This requires a mixed-integer solver (see `cardinality`
    for more details).

  **threshold_long** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Specifies the minimum weight threshold for assets in the portfolio to be
    considered as a long position. Assets with weights below this threshold
    will not be included as part of the portfolio’s long positions. This
    constraint can help eliminate insignificant allocations.
    This requires a mixed-integer solver (see `cardinality` for more details).
    It follows the same format as `min_weights` and `max_weights`.

  **threshold_short** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Specifies the maximum weight threshold for assets in the portfolio to be
    considered as a short position. Assets with weights above this threshold
    will not be included as part of the portfolio’s short positions. This
    constraint can help control the magnitude of short positions.
    This requires a mixed-integer solver (see `cardinality` for more details).
    It follows the same format as `min_weights` and `max_weights`.

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Transaction costs of the assets. It is used to add linear transaction costs to
    the optimization problem:
    $$
    total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|
    <br/>
    $$
    <br/>
    with $c_{i}$ the transaction cost of asset i, $w_{i}$ its weight
    and $w\_prev_{i}$ its previous weight (defined in `previous_weights`).
    The float $total\_cost$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_cost
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the
    vector of assets weights.
    <br/>
    For positions in `previous_weights` whose assets are no longer in the
    investment universe, transaction costs are calculated assuming full
    liquidation. These costs are included in both the optimization and
    `Portfolio.total_cost`. For assets absent from `X`, `transaction_costs`
    must be a single rate applied to all assets or a dictionary keyed by asset name.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset cost) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the transaction costs
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `transaction_costs` need to be
    expressed as **daily** costs. A transaction cost is paid once per
    rebalancing while a position earns its expected return on every period it
    is held, so the one-off cost is converted by dividing it by the expected
    investment duration (e.g. `0.001 / 21` for a 10 bps cost with daily
    returns and a one-month expected holding period).
    (See [Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention))

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Management fees of the assets. It is used to add linear management fees to the
    optimization problem:
    $$
    total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}
    <br/>
    $$
    <br/>
    with $f_{i}$ the management fee of asset i and $w_{i}$ its weight.
    The float $total\_fee$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_fee
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the vector
    of assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset fee) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the management fees
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `management_fees` need to be
    expressed in **daily** fees. Unlike transaction costs, management fees
    accrue with holding time, so a stated annual fee converts directly to the
    return periodicity (e.g. `0.02 / 252` for a 2% annual fee on daily
    returns).
    <br/>
    #### NOTE
    Another approach is to directly impact the management fees to the input `X`
    in order to express the returns net of fees. However, when estimating the
    $\mu$ parameter using for example Shrinkage estimators, this approach
    would mix a deterministic value with an uncertain one leading to unwanted
    bias in the management fees.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Previous weights of the assets. Previous weights are used to compute the
    portfolio cost and the portfolio turnover.
    For named positions in assets absent from `X`, these calculations assume
    full liquidation.
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset previous weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    The default (`None`) means no previous weights.
    Additionally, when `fallback="previous_weights"`, failures will fall back to
    these weights if provided.

  **l1_coef** *float, default=0.0*
  : L1 regularization coefficient.
    It is used to penalize the objective function by the L1 norm:
    $$
    l1\_coef \times \Vert w \Vert_{1} = l1\_coef \times \sum_{i=1}^{N} |w_{i}|
    <br/>
    $$
    <br/>
    Increasing this coefficient will reduce the number of non-zero weights
    (cardinality). It tends to increase robustness (out-of-sample stability) but
    reduces diversification.
    The default value is `0.0`.

  **l2_coef** *float, default=0.0*
  : L2 regularization coefficient.
    It is used to penalize the objective function by the L2 norm:
    $$
    l2\_coef \times \Vert w \Vert_{2}^{2} = l2\_coef \times \sum_{i=1}^{N} w_{i}^2
    <br/>
    $$
    <br/>
    It tends to increase robustness (out-of-sample stability).
    The default value is `0.0`.

  **linear_constraints** *array-like of shape (n_constraints,), optional*
  : Linear constraints on portfolio weights or factor exposures.
    <br/>
    Constraint names can reference:
    > * Asset names: individual asset weights (e.g. `"SPX"`, `"AAPL"`)
    > * Group names: sums of weights in groups defined by `groups`
    > * Factor names: portfolio factor exposure (requires factor model prior)
    > * Factor families: sum of portfolio exposures to all factors in one family
    <br/>
    Supported equation patterns include:
    > * `"name <= value"` or `"name >= value"`
    > * `"name == value"`
    > * `"a * name1 + b * name2 <= c * name3 + d"`
    <br/>
    For example:
    > * `"SPX >= 0.10"` –> SPX weight >= 10%
    > * `"SX5E + SPX >= 0.2"` –> sum of SX5E and SPX weights >= 20%
    > * `"US == 0.7"` –> sum of weights in US group == 70%
    > * `"Equity == 3 * Bond"` –> sum of weights in Equity group == 3x sum of weights in Bond group
    > * `"Momentum <= 0.30"` –> portfolio Momentum exposure <= 30%
    > * `"style <= 0.50"` –> sum of all style factor exposures (Momentum, Value, Size, etc.) <= 50%
    <br/>
    Factor constraints require a prior estimator (e.g.
    [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel),
    [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel))
    that provides `loading_matrix`, `factor_names` and optionally `factor_families`
    in its [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel).
    <br/>
    Asset, group, factor, and factor family names must be unique.

  **groups** *dict[str, list[str]] or array-like of shape (n_groups, n_assets), optional*
  : The assets groups referenced in `linear_constraints`.
    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"]]`

  **left_inequality** *array-like of shape (n_constraints, n_assets), optional*
  : Left inequality matrix $A$ of the linear
    constraint $A \cdot w \leq b$.

  **right_inequality** *array-like of shape (n_constraints, ), optional*
  : Right inequality vector $b$ of the linear
    constraint $A \cdot w \leq b$.

  **risk_free_rate** *float, default=0.0*
  : Risk-free interest rate.
    The default value is `0.0`.

  **max_tracking_error** *float, optional*
  : Upper bound constraint on the tracking error.
    The tracking error is defined as the RMSE (root-mean-square error) of the
    portfolio returns compared to target returns. If `max_tracking_error` is
    provided, the target returns `y` must be provided in the `fit` method.

  **max_turnover** *float, optional*
  : Upper bound on each investable asset’s absolute weight change from
    `previous_weights`. For positions outside the investment universe,
    transaction costs and the predicted portfolio’s `turnover` are calculated
    assuming full liquidation, without applying this limit. Transaction costs
    can also be used to control turnover.

  **min_return** *float | array-like of shape (n_optimization), optional*
  : Lower bound constraint on the expected return.

  **add_objective** *Callable[[cp.Variable], cp.Expression], optional*
  : Add a custom objective to the existing objective expression.
    It is a function that must take as argument the weights `w` and returns a
    CVXPY expression.

  **add_constraints** *Callable[[cp.Variable], cp.Expression | list[cp.Expression]], optional*
  : Add a custom constraint or a list of constraints to the existing constraints.
    It must be a function taking the CVXPY weight variable `w` as its first
    positional argument and, optionally, the estimator instance as its second.
    It must return a CVXPY expression or a list of CVXPY expressions, evaluated
    when `fit` is called.
    <br/>
    For example, to require an effective number of assets of at least 20:
    ```pycon
    >>> import cvxpy as cp
    >>> from skfolio.optimization import MaximumDiversification
    >>> model = MaximumDiversification(
    ...     add_constraints=lambda w: cp.sum_squares(w) <= 1 / 20
    ... )
    ```
    <br/>
    The optional second argument gives access to the estimator’s attributes,
    including quantities estimated during `fit`. For example, to cap each
    position size in risk units at 20 bps, using the volatilities estimated
    by the prior:
    ```pycon
    >>> import numpy as np
    >>> def position_risk_cap(w, model):
    ...     covariance = model.prior_estimator_.return_distribution_.covariance
    ...     vols = np.sqrt(np.diag(covariance))
    ...     return cp.multiply(vols, w) <= 0.002
    >>> model = MaximumDiversification(add_constraints=position_risk_cap)
    ```

  **solver** *str, default=”CLARABEL”*
  : The solver to use. The default is “CLARABEL” which is written in Rust and has
    better numerical stability and performance than ECOS and SCS. Cvxpy will replace
    its default solver “ECOS” by “CLARABEL” in future releases.
    For more details about available solvers, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver](https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver)

  **solver_params** *dict, optional*
  : Solver parameters. For example, `solver_params=dict(verbose=True)`.
    The default (`None`) is use `{"tol_gap_abs": 1e-9, "tol_gap_rel": 1e-9}`
    for the solver “CLARABEL” and the CVXPY default otherwise.
    For more details about solver arguments, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options](https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options)

  **scale_objective** *float, optional*
  : Scale each objective element by this value.
    It can be used to increase the optimization accuracies in specific cases.
    The default (`None`) is set depending on the problem.

  **scale_constraints** *float, optional*
  : Scale each constraint element by this value.
    It can be used to increase the optimization accuracies in specific cases.
    The default (`None`) is set depending on the problem.

  **save_problem** *bool, default=False*
  : If this is set to True, the CVXPY Problem is saved in `problem_`.
    The default is `False`.

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    `transaction_costs`, `management_fees`, `previous_weights` and `risk_free_rate`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,) or (n_optimizations, n_assets)*
  : Weights of the assets.

  **problem_values_** *dict[str, float] | list[dict[str, float]] of size n_optimizations*
  : Expression values retrieved from the CVXPY problem.

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

  **problem_: cvxpy.Problem**
  : CVXPY problem used for the optimization. Only when `save_problem` is set to
    `True`.

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

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification.fit)(X[, y])            | Fit the Maximum Diversification Optimization estimator.                                                                         |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`partial_fit`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification.partial_fit)(X[, y])    | Incrementally fit the Mean-Risk Optimization estimator.                                                                         |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

### Examples

For a complete tutorial on maximum diversification optimization, see the
[Maximum Diversification](https://skfolio.org/auto_examples/maximum_diversification/index.html.md#maximum-diversification-examples) gallery.

```pycon
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.optimization import MaximumDiversification
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # Maximum diversification optimization
>>> model = MaximumDiversification()
>>> model.fit(X)
MaximumDiversification()
>>> print(model.weights_)
[0.0821 0.0697 0.0243 ... 0.0945 0.0893 0.0143]
>>>
>>> portfolio = model.predict(X)
>>> print(portfolio.diversification)
1.87...
>>>
>>> # Limit each asset to 8% of the portfolio
>>> model = MaximumDiversification(max_weights=0.08)
>>> model.fit(X)
MaximumDiversification(max_weights=0.08)
>>> print(model.weights_)
[0.08   0.0706 0.0288 ... 0.08   0.08   0.0289]
```

<a id="skfolio.optimization.MaximumDiversification.fit"></a>

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

Fit the Maximum Diversification Optimization estimator.

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

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Price returns of factors or a target benchmark.
    The default is `None`.

  **\*\*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** *MaximumDiversification*
  : Fitted estimator.

<a id="skfolio.optimization.MaximumDiversification.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.MaximumDiversification.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.optimization.MaximumDiversification.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.optimization.MaximumDiversification.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.MaximumDiversification.partial_fit"></a>

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

Incrementally fit the Mean-Risk Optimization estimator.

This method allows for streaming/online updates. The prior estimator and any
configured uncertainty set estimators must implement `partial_fit` (e.g.,
priors using exponentially weighted moments or online factor models).

The optimization problem is solved fresh on each call using the updated
moments from the prior estimator.

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

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Price returns of factors or a target benchmark.
    The default is `None`.

  **\*\*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** *MeanRisk*
  : Fitted estimator.

<a id="skfolio.optimization.MaximumDiversification.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.MaximumDiversification.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.MaximumDiversification.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.

# generated/skfolio.optimization.MeanRisk.html.md

<a id="skfolio-optimization-meanrisk"></a>

# skfolio.optimization.MeanRisk

<a id="skfolio.optimization.MeanRisk"></a>

### *class* skfolio.optimization.MeanRisk(objective_function=MINIMIZE_RISK, risk_measure=Variance, risk_aversion=1.0, efficient_frontier_size=None, prior_estimator=None, min_weights=0.0, max_weights=1.0, budget=1.0, min_budget=None, max_budget=None, max_short=None, max_long=None, cardinality=None, group_cardinalities=None, threshold_long=None, threshold_short=None, transaction_costs=0.0, management_fees=0.0, previous_weights=None, target_weights=None, groups=None, linear_constraints=None, left_inequality=None, right_inequality=None, l1_coef=0.0, l2_coef=0.0, mu_uncertainty_set_estimator=None, covariance_uncertainty_set_estimator=None, risk_free_rate=0.0, min_return=None, max_tracking_error=None, max_turnover=None, max_mean_absolute_deviation=None, max_first_lower_partial_moment=None, max_variance=None, max_standard_deviation=None, max_semi_variance=None, max_semi_deviation=None, max_worst_realization=None, max_cvar=None, max_evar=None, max_max_drawdown=None, max_average_drawdown=None, max_cdar=None, max_edar=None, max_ulcer_index=None, max_gini_mean_difference=None, min_acceptable_return=None, cvar_beta=0.95, evar_beta=0.95, cdar_beta=0.95, edar_beta=0.95, solver='CLARABEL', solver_params=None, scale_objective=None, scale_constraints=None, save_problem=False, add_objective=None, add_constraints=None, overwrite_expected_return=None, portfolio_params=None, fallback=None, raise_on_failure=True)

Mean-Risk Optimization estimator.

The below 4 objective functions can be optimized:

> * Minimize Risk:

> $$
> \begin{cases}
> \begin{aligned}
> &\min_{w} & & risk_{i}(w) \\
> &\text{s.t.} & & w^T \cdot \mu \ge min\_return \\
> & & & A \cdot w \ge b \\
> & & & risk_{j}(w) \le max\_risk_{j} \quad \forall \; j \ne i
> \end{aligned}
> \end{cases}

> $$

> * Maximize Expected Return:

> $$
> \begin{cases}
> \begin{aligned}
> &\max_{w} & & w^T \cdot \mu \\
> &\text{s.t.} & & risk_{i}(w) \le max\_risk_{i} \\
> & & & A \cdot w \ge b \\
> & & & risk_{j}(w) \le max\_risk_{j} \quad \forall \; j \ne i
> \end{aligned}
> \end{cases}

> $$

> * Maximize Utility:

> $$
> \begin{cases}
> \begin{aligned}
> &\max_{w} & & w^T \cdot \mu - \lambda \times risk_{i}(w)\\
> &\text{s.t.} & & risk_{i}(w) \le max\_risk_{i} \\
> & & & w^T \cdot \mu \ge min\_return \\
> & & & A \cdot w \ge b \\
> & & & risk_{j}(w) \le max\_risk_{j} \quad \forall \; j \ne i
> \end{aligned}
> \end{cases}

> $$

> * Maximize Ratio:

> $$
> \begin{cases}
> \begin{aligned}
> &\max_{w} & & \frac{w^T \cdot \mu - r_{f}}{risk_{i}(w)}\\
> &\text{s.t.} & & risk_{i}(w) \le max\_risk_{i} \\
> & & & w^T \cdot \mu \ge min\_return \\
> & & & A \cdot w \ge b \\
> & & & risk_{j}(w) \le max\_risk_{j} \quad \forall \; j \ne i
> \end{aligned}
> \end{cases}

> $$

With $risk_{i}$ a risk measure among:

> * Mean Absolute Deviation
> * First Lower Partial Moment
> * Variance
> * Semi-Variance
> * CVaR (Conditional Value at Risk)
> * EVaR (Entropic Value at Risk)
> * Worst Realization (worst return)
> * CDaR (Conditional Drawdown at Risk)
> * Maximum Drawdown
> * Average Drawdown
> * EDaR (Entropic Drawdown at Risk)
> * Ulcer Index
> * Gini Mean Difference

Cost, regularization, uncertainty set, and additional constraints can also be added
to the optimization problem (see the parameters description).

The expected asset returns, covariance matrix and returns are estimated from the
[prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).

* **Parameters:**
  **objective_function** *ObjectiveFunction, default=ObjectiveFunction.MINIMIZE_RISK*
  : [`ObjectiveFunction`](https://skfolio.org/generated/skfolio.optimization.ObjectiveFunction.html.md#skfolio.optimization.ObjectiveFunction) of the optimization.
    Can be any of:
    > * MINIMIZE_RISK
    > * MAXIMIZE_RETURN
    > * MAXIMIZE_UTILITY
    > * MAXIMIZE_RATIO
    <br/>
    The default is `ObjectiveFunction.MINIMIZE_RISK`.

  **risk_measure** *RiskMeasure, default=RiskMeasure.VARIANCE*
  : `RiskMeasure` of the optimization.
    Can be any of:
    > * VARIANCE
    > * SEMI_VARIANCE
    > * STANDARD_DEVIATION
    > * SEMI_DEVIATION
    > * MEAN_ABSOLUTE_DEVIATION
    > * FIRST_LOWER_PARTIAL_MOMENT
    > * CVAR
    > * EVAR
    > * WORST_REALIZATION
    > * CDAR
    > * MAX_DRAWDOWN
    > * AVERAGE_DRAWDOWN
    > * EDAR
    > * ULCER_INDEX
    > * GINI_MEAN_DIFFERENCE_RATIO
    <br/>
    The default is `RiskMeasure.VARIANCE`.

  **risk_aversion** *float, default=1.0*
  : Risk aversion factor $\lambda$ of the utility function. Only used for
    `objective_function=ObjectiveFunction.MAXIMIZE_UTILITY`.
    The default value is `1.0`.

  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator 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 of the covariance.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **efficient_frontier_size** *int, optional*
  : If provided, it represents the number of Pareto-optimal portfolios along the
    efficient frontier to be computed. This parameter can only be used with
    `objective_function = ObjectiveFunction.MINIMIZE_RISK`.

  **min_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=0.0*
  : Minimum assets weights (weights lower bounds).
    If a float is provided, it is applied to each asset.
    `None` is equivalent to `-np.Inf` (no lower bound).
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset minimum weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a minimum weight of `0.0`.
    The default value is `0.0` (no short selling).
    <br/>
    Example:
    > * `min_weights = 0` –> long only portfolio (no short selling).
    > * `min_weights = None` –> no lower bound (same as `-np.Inf`).
    > * `min_weights = -2` –> each weight must be above -200%.
    > * `min_weights = {"SX5E": 0, "SPX": -2}`
    > * `min_weights = [0, -2]`

  **max_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=1.0*
  : Maximum assets weights (weights upper bounds).
    If a float is provided, it is applied to each asset.
    `None` is equivalent to `+np.Inf` (no upper bound).
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset maximum weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a minimum weight of `1.0`.
    The default value is `1.0` (each asset is below 100%).
    <br/>
    Example:
    > * `max_weights = 0` –> no long position (short only portfolio).
    > * `max_weights = None` –> no upper bound.
    > * `max_weights = 2` –> each weight must be below 200%.
    > * `max_weights = {"SX5E": 1, "SPX": 2}`
    > * `max_weights = [1, 2]`

  **budget** *float | None, default=1.0*
  : Investment budget. It is the sum of long positions and short positions (sum of
    all weights). `None` means no budget constraints.
    The default value is `1.0` (fully invested portfolio).
    <br/>
    For example:
    > * `budget = 1` –> fully invested portfolio.
    > * `budget = 0` –> market neutral portfolio.
    > * `budget = None` –> no constraints on the sum of weights.

  **min_budget** *float, optional*
  : Minimum budget. It is the lower bound of the sum of long and short positions
    (sum of all weights). If provided, you must set `budget=None`.
    The default (`None`) means no minimum budget constraint.

  **max_budget** *float, optional*
  : Maximum budget. It is the upper bound of the sum of long and short positions
    (sum of all weights). If provided, you must set `budget=None`.
    The default (`None`) means no maximum budget constraint.

  **max_short** *float, optional*
  : Maximum short position. The short position is defined as the sum of negative
    weights (in absolute term).
    The default (`None`) means no maximum short position.

  **max_long** *float, optional*
  : Maximum long position. The long position is defined as the sum of positive
    weights.
    The default (`None`) means no maximum long position.

  **cardinality** *int, optional*
  : Specifies the cardinality constraint to limit the number of invested assets
    (non-zero weights). This feature requires a mixed-integer solver. For an
    open-source option, we recommend using SCIP by setting `solver="SCIP"`.
    To install it, use: `pip install cvxpy[SCIP]`. For commercial solvers,
    supported options include MOSEK, GUROBI, or CPLEX.

  **group_cardinalities** *dict[str, int], optional*
  : A dictionary specifying cardinality constraints for specific groups of assets.
    The keys represent group names (strings), and the values specify the maximum
    number of assets allowed in each group. You must provide the groups using the
    `groups` parameter. This requires a mixed-integer solver (see `cardinality`
    for more details).

  **threshold_long** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Specifies the minimum weight threshold for assets in the portfolio to be
    considered as a long position. Assets with weights below this threshold
    will not be included as part of the portfolio’s long positions. This
    constraint can help eliminate insignificant allocations.
    This requires a mixed-integer solver (see `cardinality` for more details).
    It follows the same format as `min_weights` and `max_weights`.

  **threshold_short** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Specifies the maximum weight threshold for assets in the portfolio to be
    considered as a short position. Assets with weights above this threshold
    will not be included as part of the portfolio’s short positions. This
    constraint can help control the magnitude of short positions.
    This requires a mixed-integer solver (see `cardinality` for more details).
    It follows the same format as `min_weights` and `max_weights`.

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Transaction costs of the assets. It is used to add linear transaction costs to
    the optimization problem:
    $$
    total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|
    <br/>
    $$
    <br/>
    with $c_{i}$ the transaction cost of asset i, $w_{i}$ its weight
    and $w\_prev_{i}$ its previous weight (defined in `previous_weights`).
    The float $total\_cost$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_cost
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the
    vector of assets weights.
    <br/>
    For positions in `previous_weights` whose assets are no longer in the
    investment universe, transaction costs are calculated assuming full
    liquidation. These costs are included in both the optimization and
    `Portfolio.total_cost`. For assets absent from `X`, `transaction_costs`
    must be a single rate applied to all assets or a dictionary keyed by asset name.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset cost) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the transaction costs
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `transaction_costs` need to be
    expressed as **daily** costs. A transaction cost is paid once per
    rebalancing while a position earns its expected return on every period it
    is held, so the one-off cost is converted by dividing it by the expected
    investment duration (e.g. `0.001 / 21` for a 10 bps cost with daily
    returns and a one-month expected holding period).
    (See [Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention))

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Management fees of the assets. It is used to add linear management fees to the
    optimization problem:
    $$
    total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}
    <br/>
    $$
    <br/>
    with $f_{i}$ the management fee of asset i and $w_{i}$ its weight.
    The float $total\_fee$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_fee
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the vector
    of assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset fee) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the management fees
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `management_fees` need to be
    expressed in **daily** fees. Unlike transaction costs, management fees
    accrue with holding time, so a stated annual fee converts directly to the
    return periodicity (e.g. `0.02 / 252` for a 2% annual fee on daily
    returns).
    <br/>
    #### NOTE
    Another approach is to directly impact the management fees to the input `X`
    in order to express the returns net of fees. However, when estimating the
    $\mu$ parameter using for example Shrinkage estimators, this approach
    would mix a deterministic value with an uncertain one leading to unwanted
    bias in the management fees.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Previous weights of the assets. Previous weights are used to compute the
    portfolio cost and the portfolio turnover.
    For named positions in assets absent from `X`, these calculations assume
    full liquidation.
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset previous weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    The default (`None`) means no previous weights.
    Additionally, when `fallback="previous_weights"`, failures will fall back to
    these weights if provided.

  **target_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Target weights of the assets. When provided, risk measures are computed on the
    deviation from these target weights (w - target_weights) instead of the
    absolute weights. This is useful for tracking error minimization or when
    optimizing around a specific allocation.
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset target weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a target weight of `0.0`.
    The default (`None`) means no target weights.
    <br/>
    #### SEE ALSO
    [Tracking Error Optimization](https://skfolio.org/user_guide/optimization.html.md#tracking-error-optimization)

  **l1_coef** *float, default=0.0*
  : L1 regularization coefficient.
    It is used to penalize the objective function by the L1 norm:
    $$
    l1\_coef \times \Vert w \Vert_{1} = l1\_coef \times \sum_{i=1}^{N} |w_{i}|
    <br/>
    $$
    <br/>
    Increasing this coefficient will reduce the number of non-zero weights
    (cardinality). It tends to increase robustness (out-of-sample stability) but
    reduces diversification.
    The default value is `0.0`.

  **l2_coef** *float, default=0.0*
  : L2 regularization coefficient.
    It is used to penalize the objective function by the L2 norm:
    $$
    l2\_coef \times \Vert w \Vert_{2}^{2} = l2\_coef \times \sum_{i=1}^{N} w_{i}^2
    <br/>
    $$
    <br/>
    It tends to increase robustness (out-of-sample stability).
    The default value is `0.0`.

  **mu_uncertainty_set_estimator** *BaseMuUncertaintySet, optional*
  : [Mu Uncertainty set estimator](https://skfolio.org/user_guide/uncertainty_set.html.md#uncertainty-set-estimator).
    If provided, the expected asset returns are modelled with a norm-ball
    uncertainty set. It is called worst-case optimization and is a class of robust
    optimization. It reduces the instability that arises from the estimation errors
    of the expected returns.
    The worst-case portfolio expected return is:
    $$
    w^T \cdot \hat{\mu} - \kappa_{\mu} \lVert L_{\mu}^T \cdot w \rVert_{q}
    <br/>
    $$
    <br/>
    with $\kappa$ the radius of the uncertainty set (confidence region),
    $L$ its linear geometry map and $q$ the dual norm. For an
    ellipsoidal set with shape matrix $S$, $L$ is a square-root factor
    satisfying $S = L L^T$ and $q$ is $2$.
    The default (`None`) means that no uncertainty set is used.

  **covariance_uncertainty_set_estimator** *BaseCovarianceUncertaintySet, optional*
  : [Covariance Uncertainty set estimator](https://skfolio.org/user_guide/uncertainty_set.html.md#uncertainty-set-estimator).
    If provided, covariance estimation uncertainty is included in the optimized
    variance. This approach is known as worst-case optimization, a form of robust
    optimization. It reduces sensitivity to covariance estimation errors.
    Covariance uncertainty is applied when `risk_measure=RiskMeasure.VARIANCE` or
    when `max_variance` is set.
    The default (`None`) means that no uncertainty set is used.

  **linear_constraints** *array-like of shape (n_constraints,), optional*
  : Linear constraints on portfolio weights or factor exposures.
    <br/>
    Constraint names can reference:
    > * Asset names: individual asset weights (e.g. `"SPX"`, `"AAPL"`)
    > * Group names: sums of weights in groups defined by `groups`
    > * Factor names: portfolio factor exposure (requires factor model prior)
    > * Factor families: sum of portfolio exposures to all factors in one family
    <br/>
    Supported equation patterns include:
    > * `"name <= value"` or `"name >= value"`
    > * `"name == value"`
    > * `"a * name1 + b * name2 <= c * name3 + d"`
    <br/>
    For example:
    > * `"SPX >= 0.10"` –> SPX weight >= 10%
    > * `"SX5E + SPX >= 0.2"` –> sum of SX5E and SPX weights >= 20%
    > * `"US == 0.7"` –> sum of weights in US group == 70%
    > * `"Equity == 3 * Bond"` –> sum of weights in Equity group == 3x sum of weights in Bond group
    > * `"Momentum <= 0.30"` –> portfolio Momentum exposure <= 30%
    > * `"style <= 0.50"` –> sum of all style factor exposures (Momentum, Value, Size, etc.) <= 50%
    <br/>
    Factor constraints require a prior estimator (e.g.
    [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel),
    [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel))
    that provides `loading_matrix`, `factor_names` and optionally `factor_families`
    in its [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel).
    <br/>
    Asset, group, factor, and factor family names must be unique.

  **groups** *dict[str, list[str]] or array-like of shape (n_groups, n_assets), optional*
  : The assets groups referenced in `linear_constraints`.
    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"]]`

  **left_inequality** *array-like of shape (n_constraints, n_assets), optional*
  : Left inequality matrix $A$ of the linear
    constraint $A \cdot w \leq b$.

  **right_inequality** *array-like of shape (n_constraints, ), optional*
  : Right inequality vector $b$ of the linear
    constraint $A \cdot w \leq b$.

  **risk_free_rate** *float, default=0.0*
  : Risk-free interest rate.
    The default value is `0.0`.

  **max_tracking_error** *float, optional*
  : Upper bound constraint on the tracking error.
    The tracking error is defined as the RMSE (root-mean-square error) of the
    portfolio returns compared to target returns. If `max_tracking_error` is
    provided, the target returns `y` must be provided in the `fit` method.
    <br/>
    #### SEE ALSO
    [Tracking Error Optimization](https://skfolio.org/user_guide/optimization.html.md#tracking-error-optimization)

  **max_turnover** *float, optional*
  : Upper bound on each investable asset’s absolute weight change from
    `previous_weights`. For positions outside the investment universe,
    transaction costs and the predicted portfolio’s `turnover` are calculated
    assuming full liquidation, without applying this limit. Transaction costs
    can also be used to control turnover.

  **max_mean_absolute_deviation** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the Mean Absolute Deviation.

  **max_first_lower_partial_moment** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the First Lower Partial Moment.

  **max_variance** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the Variance.

  **max_standard_deviation** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the Standard deviation.

  **max_semi_variance** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the Semi-Variance (Second Lower Partial Moment or
    Downside Variance).

  **max_semi_deviation** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the Semi-Standard deviation.

  **max_worst_realization** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the Worst Realization (Worst Return).

  **max_cvar** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the CVaR (Conditional Value-at-Risk or Expected
    Shortfall).

  **max_evar** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the EVaR (Entropic Value at Risk).

  **max_max_drawdown** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the Maximum Drawdown.

  **max_average_drawdown** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the Average Drawdown.

  **max_cdar** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the CDaR (Conditional Drawdown at Risk).

  **max_edar** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the EDaR (Entropic Drawdown at Risk).

  **max_ulcer_index** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the Ulcer Index.

  **max_gini_mean_difference** *float | array-like of shape (n_optimization), optional*
  : Upper bound constraint on the Gini Mean Difference.

  **min_return** *float | array-like of shape (n_optimization), optional*
  : Lower bound constraint on the expected return.

  **min_acceptable_return** *float, optional*
  : The minimum acceptable return used to distinguish “downside” and “upside”
    returns for the computation of lower partial moments:
    > * First Lower Partial Moment
    > * Semi-Variance
    > * Semi-Deviation
    <br/>
    The default (`None`) is to use the mean.

  **cvar_beta** *float, default=0.95*
  : CVaR (Conditional Value at Risk) confidence level.
    The default value is `0.95`.

  **evar_beta** *float, default=0.95*
  : EVaR (Entropic Value at Risk) confidence level.
    The default value is `0.95`.

  **cdar_beta** *float, default=0.95*
  : CDaR (Conditional Drawdown at Risk) confidence level.
    The default value is `0.95`.

  **edar_beta** *float, default=0.95*
  : EDaR (Entropic Drawdown at Risk) confidence level.
    The default value is `0.95`.

  **add_objective** *Callable[[cp.Variable], cp.Expression], optional*
  : Add a custom objective to the existing objective expression.
    It is a function that must take as argument the weights `w` and returns a
    CVXPY expression.

  **add_constraints** *Callable[[cp.Variable], cp.Expression | list[cp.Expression]], optional*
  : Add a custom constraint or a list of constraints to the existing constraints.
    It must be a function taking the CVXPY weight variable `w` as its first
    positional argument and, optionally, the estimator instance as its second.
    It must return a CVXPY expression or a list of CVXPY expressions, evaluated
    when `fit` is called.
    <br/>
    For example, to require an effective number of assets of at least 20:
    ```pycon
    >>> import cvxpy as cp
    >>> from skfolio.optimization import MeanRisk
    >>> model = MeanRisk(add_constraints=lambda w: cp.sum_squares(w) <= 1 / 20)
    ```
    <br/>
    The optional second argument gives access to the estimator’s attributes,
    including quantities estimated during `fit`. For example, to cap each
    position size in risk units at 20 bps, using the volatilities estimated
    by the prior:
    ```pycon
    >>> import numpy as np
    >>> def position_risk_cap(w, model):
    ...     covariance = model.prior_estimator_.return_distribution_.covariance
    ...     vols = np.sqrt(np.diag(covariance))
    ...     return cp.multiply(vols, w) <= 0.002
    >>> model = MeanRisk(add_constraints=position_risk_cap)
    ```

  **overwrite_expected_return** *Callable[[cp.Variable], cp.Expression], optional*
  : Overwrite the expected return $\mu \cdot w$ with a custom CVXPY
    expression. It must be a function taking the CVXPY weight variable `w` as
    its first positional argument and, optionally, the estimator instance as
    its second. It must return a concave CVXPY expression, evaluated when
    `fit` is called. The custom expression replaces the expected return in the
    objective function and in the constraints where the expected return is
    used.
    <br/>
    For example, to adjust the expected return for volatility drag,
    approximating the portfolio geometric mean return:
    ```pycon
    >>> import cvxpy as cp
    >>> from skfolio.optimization import MeanRisk
    >>> def geometric_expected_return(w, model):
    ...     dist = model.prior_estimator_.return_distribution_
    ...     return dist.mu @ w - 0.5 * cp.quad_form(w, dist.covariance)
    >>> model = MeanRisk(overwrite_expected_return=geometric_expected_return)
    ```

  **solver** *str, default=”CLARABEL”*
  : The solver to use. The default is “CLARABEL” which is written in Rust and has
    better numerical stability and performance than ECOS and SCS. Cvxpy will replace
    its default solver “ECOS” by “CLARABEL” in future releases.
    For more details about available solvers, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver](https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver)

  **solver_params** *dict, optional*
  : Solver parameters. For example, `solver_params=dict(verbose=True)`.
    The default (`None`) is use `{"tol_gap_abs": 1e-9, "tol_gap_rel": 1e-9}`
    for “CLARABEL”, `{"numerics/feastol": 1e-8, "limits/gap": 1e-8}` for SCIP
    and the solver default otherwise.
    For more details about solver arguments, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/solvers](https://www.cvxpy.org/tutorial/solvers)

  **scale_objective** *float, optional*
  : Scale each objective element by this value.
    It can be used to increase the optimization accuracies in specific cases.
    The default (`None`) is set depending on the problem.

  **scale_constraints** *float, optional*
  : Scale each constraint element by this value.
    It can be used to increase the optimization accuracies in specific cases.
    The default (`None`) is set depending on the problem.

  **save_problem** *bool, default=False*
  : If this is set to True, the CVXPY Problem is saved in `problem_`.
    The default is `False`.

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    `transaction_costs`, `management_fees`, `previous_weights` and `risk_free_rate`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.
    With `partial_fit`, only `fallback="previous_weights"` is supported because
    fallback estimators would not have accumulated the same online state.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
    With `partial_fit`, only solver failures are handled this way and failures
    while updating stateful sub-estimators are always raised.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,) or (n_optimizations, n_assets)*
  : Weights of the assets.

  **problem_values_** *dict[str, float] | list[dict[str, float]] of size n_optimizations*
  : Expression values retrieved from the CVXPY problem.

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

  **mu_uncertainty_set_estimator_** *BaseMuUncertaintySet*
  : Fitted `mu_uncertainty_set_estimator` if provided.

  **covariance_uncertainty_set_estimator_** *BaseCovarianceUncertaintySet*
  : Fitted `covariance_uncertainty_set_estimator` if provided.

  **problem_: cvxpy.Problem**
  : CVXPY problem used for the optimization. Only when `save_problem` is set to
    `True`.

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

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk.fit)(X[, y])            | Fit the Mean-Risk Optimization estimator.                                                                                       |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`partial_fit`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk.partial_fit)(X[, y])    | Incrementally fit the Mean-Risk Optimization estimator.                                                                         |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

### References

* <a id='r653e3d33dad8-1'>**[1]**</a> “Portfolio Optimization: Theory and Application”, Chapter 7, 10, 13 and 14, Daniel P. Palomar (2025)

### Examples

For complete tutorials on mean-risk optimization, see the
[Mean-Risk](https://skfolio.org/auto_examples/mean_risk/index.html.md#mean-risk-examples) gallery.

```pycon
>>> from skfolio import RiskMeasure
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.optimization import MeanRisk, ObjectiveFunction
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # Minimum variance optimization
>>> model = MeanRisk(risk_measure=RiskMeasure.VARIANCE)
>>> model.fit(X)
MeanRisk()
>>> print(model.weights_)
[0.026  0.     0.     ... 0.0097 0.1157 0.0892]
>>>
>>> # Maximum Sharpe Ratio optimization
>>> model = MeanRisk(
...     objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
...     risk_measure=RiskMeasure.STANDARD_DEVIATION,
... )
>>> model.fit(X)
MeanRisk(objective_function=MAXIMIZE_RATIO, risk_measure=Standard Deviation)
>>> print(model.weights_)
[0.1014 0.0009 0.     ... 0.2149 0.0006 0.    ]
>>>
>>> # Minimum CVaR optimization with weight and linear constraints
>>> model = MeanRisk(
...     risk_measure=RiskMeasure.CVAR,
...     max_weights=0.20,
...     linear_constraints=["AMD <= 0.10", "BAC + JPM >= 0.15"],
... )
>>> model.fit(X)
MeanRisk(linear_constraints=['AMD <= 0.10', 'BAC + JPM >= 0.15'],
         max_weights=0.2, risk_measure=CVaR)
>>> print(model.weights_)
[0.0112 0.     0.0147 ... 0.     0.1103 0.0834]
>>>
>>> # Compute portfolios along the mean-variance efficient frontier
>>> model = MeanRisk(
...     risk_measure=RiskMeasure.VARIANCE,
...     efficient_frontier_size=10,
... )
>>> model.fit(X)
MeanRisk(efficient_frontier_size=10)
>>> print(model.weights_.shape)
(10, 20)
>>> population = model.predict(X)
```

<a id="skfolio.optimization.MeanRisk.fit"></a>

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

Fit the Mean-Risk Optimization estimator.

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

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Price returns of factors or a target benchmark.
    The default is `None`.

  **\*\*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** *MeanRisk*
  : Fitted estimator.

<a id="skfolio.optimization.MeanRisk.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.MeanRisk.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.optimization.MeanRisk.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.optimization.MeanRisk.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.MeanRisk.partial_fit"></a>

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

Incrementally fit the Mean-Risk Optimization estimator.

This method allows for streaming/online updates. The prior estimator and any
configured uncertainty set estimators must implement `partial_fit` (e.g.,
priors using exponentially weighted moments or online factor models).

The optimization problem is solved fresh on each call using the updated
moments from the prior estimator.

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

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Price returns of factors or a target benchmark.
    The default is `None`.

  **\*\*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** *MeanRisk*
  : Fitted estimator.

<a id="skfolio.optimization.MeanRisk.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.MeanRisk.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.MeanRisk.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.

# generated/skfolio.optimization.NestedClustersOptimization.html.md

<a id="skfolio-optimization-nestedclustersoptimization"></a>

# skfolio.optimization.NestedClustersOptimization

<a id="skfolio.optimization.NestedClustersOptimization"></a>

### *class* skfolio.optimization.NestedClustersOptimization(inner_estimator=None, outer_estimator=None, distance_estimator=None, clustering_estimator=None, cv=None, quantile=0.5, quantile_measure=Sharpe Ratio, n_jobs=None, verbose=0, portfolio_params=None, fallback=None, previous_weights=None, raise_on_failure=True)

Nested Clusters Optimization estimator.

Nested Clusters Optimization (NCO) is a portfolio optimization method developed by
Marcos Lopez de Prado.

It uses a distance matrix to compute clusters using a clustering algorithm (
Hierarchical Tree Clustering, KMeans, etc.). For each cluster, the inner-cluster
weights are computed by fitting the inner-estimator on each cluster using the whole
training data. Then the outer-cluster weights are computed by training the
outer-estimator using out-of-sample estimates of the inner-estimators with
cross-validation. Finally, the final assets weights are the dot-product of the
inner-weights and outer-weights.

#### NOTE
The original paper uses KMeans as the clustering algorithm, minimum Variance for
the inner-estimator and equal-weighted for the outer-estimator. Here we
generalize it to all `sklearn` and `skfolio` clustering algorithms
(HierarchicalClustering, KMeans, etc.), all portfolio optimizations
(Mean-Variance, HRP, etc.) and risk measures (Variance, CVaR, etc.).
To avoid data leakage at the outer-estimator, we use out-of-sample estimates to
fit the outer estimator.

* **Parameters:**
  **inner_estimator** *BaseOptimization, optional*
  : [Optimization estimator](https://skfolio.org/user_guide/optimization.html.md#optimization) used to estimate the inner-weights
    (also called intra-weights) which are the assets weights inside each cluster.
    The default `None` is to use [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk).

  **outer_estimator** *BaseOptimization, optional*
  : [Optimization estimator](https://skfolio.org/user_guide/optimization.html.md#optimization) used to estimate the outer-weights
    (also called inter-weights) which are the weights applied to each cluster.
    The default `None` is to use [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk).

  **distance_estimator** *BaseDistance, optional*
  : [Distance estimator](https://skfolio.org/user_guide/distance.html.md#distance).
    The distance estimator is used to estimate the codependence and the distance
    matrix needed for the computation of the linkage matrix.
    The default (`None`) is to use [`PearsonDistance`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance).

  **clustering_estimator** *BaseEstimator, optional*
  : Clustering estimator. Must expose a `labels_` attribute after fitting.
    The clustering estimator is used to compute the clusters of the assets based on
    the distance matrix. The default (`None`) is to use
    [`HierarchicalClustering`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering).
    <br/>
    #### NOTE
    Clustering estimators from `sklearn` are also supported. For example:
    `sklearn.cluster.KMeans`.

  **cv** *BaseCrossValidator | BaseCombinatorialCV | int | “ignore”, optional*
  : Determines the cross-validation splitting strategy.
    The default (`None`) is to use the 5-fold cross validation `KFold()`.
    It is applied to the inner-estimators. Its out-of-sample outputs are used to
    train the outer-estimator.
    Possible inputs for `cv` are:
    > * “ignore”: no cross-validation is used (note that it will likely lead to data leakage with a high risk of overfitting)
    > * Integer, to specify the number of folds in a `sklearn.model_selection.KFold`
    > * An object to be used as a cross-validation generator
    > * An iterable yielding train, test splits
    > * A [`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV)
    <br/>
    If a `CombinatorialCV` cross-validator is used, each cluster out-of-sample
    outputs becomes a collection of multiple paths instead of one single path. The
    selected out-of-sample path among this collection of paths is chosen according
    to the `quantile` and `quantile_measure` parameters.

  **n_jobs** *int, optional*
  : The number of jobs to run in parallel for `fit` of all `estimators`.
    The value `-1` means using all processors.
    The default (`None`) means 1 unless in a `joblib.parallel_backend` context.

  **quantile** *float, default=0.5*
  : Quantile for a given measure (`quantile_measure`) of the out-of-sample
    inner-estimator paths when the `cv` parameter is a
    [`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) cross-validator.
    The default value is `0.5` corresponding to the path with the median measure.
    (see `cv`)

  **quantile_measure** *PerfMeasure or RatioMeasure or RiskMeasure or ExtraRiskMeasure, default=RatioMeasure.SHARPE_RATIO*
  : Measure used for the quantile path selection (see `quantile` and `cv`).
    The default is `RatioMeasure.SHARPE_RATIO`.

  **verbose** *int, default=0*
  : The verbosity level. The default value is `0`.

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name` and
    `previous_weights`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets,), optional*
  : When `fallback="previous_weights"`, failures will fall back to these weights
    if provided.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,)*
  : Weights of the assets.

  **distance_estimator_** *BaseDistance*
  : Fitted `distance_estimator`.

  **inner_estimators_** *list[BaseOptimization]*
  : List of fitted `inner_estimator`. One per cluster for clusters containing more
    than one asset.

  **outer_estimator_** *BaseOptimization*
  : Fitted `outer_estimator`.

  **clustering_estimator_** *BaseEstimator*
  : Fitted `clustering_estimator`.

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

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization.fit)(X[, y])            | Fit the Nested Clusters Optimization estimator.                                                                                 |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

### References

* <a id='r28b9d31cd9a7-1'>**[1]**</a> “Building diversified portfolios that outperform out of sample”, The Journal of Portfolio Management, Marcos López de Prado (2016)
* <a id='r28b9d31cd9a7-2'>**[2]**</a> “A robust estimator of the efficient frontier”, SSRN Electronic Journal, Marcos López de Prado (2019)
* <a id='r28b9d31cd9a7-3'>**[3]**</a> “Machine Learning for Asset Managers”, Elements in Quantitative Finance. Cambridge University Press, Marcos López de Prado (2020)

### Examples

For complete tutorials on nested clusters optimization, see the
[Hierarchical Clustering and NCO](https://skfolio.org/auto_examples/clustering/index.html.md#cluster-examples) gallery.

```pycon
>>> from skfolio import RiskMeasure
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.optimization import (
...     MeanRisk,
...     NestedClustersOptimization,
...     ObjectiveFunction,
...     RiskBudgeting,
... )
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # Maximize the Sharpe ratio within each cluster and minimize the CVaR
>>> # computed from the out-of-sample predicted returns of the clusters
>>> inner_estimator = MeanRisk(
...     objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
...     risk_measure=RiskMeasure.STANDARD_DEVIATION,
... )
>>> outer_estimator = RiskBudgeting(risk_measure=RiskMeasure.CVAR)
>>> model = NestedClustersOptimization(
...     inner_estimator=inner_estimator,
...     outer_estimator=outer_estimator,
... )
>>> model.fit(X)
NestedClustersOptimization(...)
>>> print(model.weights_)
[0.0327 0.0029 0.     ... 0.0864 0.0236 0.0736]
>>> print(model.clustering_estimator_.labels_)
[4 4 3 4 2 3 4 1 3 0 1 1 4 0 1 0 2 1 4 2]
```

<a id="skfolio.optimization.NestedClustersOptimization.fit"></a>

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

Fit the Nested Clusters Optimization estimator.

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

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Price returns of factors or a target benchmark.
    The default is `None`.

  **\*\*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** *NestedClustersOptimization*
  : Fitted estimator.

<a id="skfolio.optimization.NestedClustersOptimization.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.NestedClustersOptimization.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.optimization.NestedClustersOptimization.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.optimization.NestedClustersOptimization.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.NestedClustersOptimization.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.NestedClustersOptimization.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.NestedClustersOptimization.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.

# generated/skfolio.optimization.ObjectiveFunction.html.md

<a id="skfolio-optimization-objectivefunction"></a>

# skfolio.optimization.ObjectiveFunction

<a id="skfolio.optimization.ObjectiveFunction"></a>

### *class* skfolio.optimization.ObjectiveFunction(\*values)

Enumeration of objective functions.

* **Attributes:**
  **MINIMIZE_RISK** *str*
  : Minimize the risk measure.

  **MAXIMIZE_RETURN** *str*
  : Maximize the expected return.

  **MAXIMIZE_UTILITY** *str*
  : Maximize the utility  $w^T\mu - \lambda \times risk(w)$.

  **MAXIMIZE_RATIO** *str*
  : Maximize the ratio  $\frac{w^T\mu - R_{f}}{risk(w)}$.

<a id="skfolio.optimization.ObjectiveFunction.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.optimization.Random.html.md

<a id="skfolio-optimization-random"></a>

# skfolio.optimization.Random

<a id="skfolio.optimization.Random"></a>

### *class* skfolio.optimization.Random(portfolio_params=None, fallback=None, previous_weights=None, raise_on_failure=True)

Random weight estimator.

The asset weights are drawn from a Dirichlet distribution and sum to one.

* **Parameters:**
  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    and `previous_weights`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets,), optional*
  : When `fallback="previous_weights"`, failures will fall back to these weights
    if provided.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,) or (n_optimizations, n_assets)*
  : Weights of the assets.

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.Random.html.md#skfolio.optimization.Random.fit)(X[, y])            | Fit the Random Weighted estimator.                                                                                              |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.Random.html.md#skfolio.optimization.Random.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.Random.html.md#skfolio.optimization.Random.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.Random.html.md#skfolio.optimization.Random.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.Random.html.md#skfolio.optimization.Random.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.Random.html.md#skfolio.optimization.Random.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.Random.html.md#skfolio.optimization.Random.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

<a id="skfolio.optimization.Random.fit"></a>

#### fit(X, y=None)

Fit the Random Weighted 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.
* **Returns:**
  **self** *EqualWeighted*
  : Fitted estimator.

<a id="skfolio.optimization.Random.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.Random.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.optimization.Random.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.optimization.Random.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.Random.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.Random.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.Random.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.

# generated/skfolio.optimization.RiskBudgeting.html.md

<a id="skfolio-optimization-riskbudgeting"></a>

# skfolio.optimization.RiskBudgeting

<a id="skfolio.optimization.RiskBudgeting"></a>

### *class* skfolio.optimization.RiskBudgeting(risk_measure=Variance, risk_budget=None, prior_estimator=None, min_weights=0.0, max_weights=1.0, transaction_costs=0.0, management_fees=0.0, previous_weights=None, groups=None, linear_constraints=None, left_inequality=None, right_inequality=None, risk_free_rate=0.0, min_return=None, min_acceptable_return=None, cvar_beta=0.95, evar_beta=0.95, cdar_beta=0.95, edar_beta=0.95, solver='CLARABEL', solver_params=None, scale_objective=None, scale_constraints=None, save_problem=False, raise_on_failure=True, add_objective=None, add_constraints=None, overwrite_expected_return=None, portfolio_params=None, fallback=None)

Risk Budgeting Optimization estimator.

The Risk Budgeting estimator solves the below convex problem:

> $$
> \begin{cases}
> \begin{aligned}
> & \min_{w,s} && \mathrm{Risk}(w) \\
> & \text{s.t.} && budget^{\top}\log(w) \ge 0 \\
> &             && \mathbf{1}^{\top} w = s \\
> &             && expected\_return(w) \ge s\, min\_return \\
> &             && A w \le s\, b \\
> &             && w \ge 0
> \end{aligned}
> \end{cases}

> $$

with $budget$ the risk budget vector and $min\_return$ the minimum
expected return constraint.

And $Risk$ a risk measure among:

> * Mean Absolute Deviation
> * First Lower Partial Moment
> * Variance
> * Semi-Variance
> * CVaR (Conditional Value at Risk)
> * EVaR (Entropic Value at Risk)
> * Worst Realization (worst return)
> * CDaR (Conditional Drawdown at Risk)
> * Maximum Drawdown
> * Average Drawdown
> * EDaR (Entropic Drawdown at Risk)
> * Ulcer Index
> * Gini Mean Difference

Cost and additional constraints can also be added to the optimization problem  (see
the parameters description).

Limitations are imposed on some constraints including long only weights to ensure
convexity.

The expected asset returns, covariance matrix and returns are estimated from the
[prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).

* **Parameters:**
  **risk_measure** *RiskMeasure, default=RiskMeasure.VARIANCE*
  : `RiskMeasure` of the optimization.
    Can be any of:
    > * VARIANCE
    > * SEMI_VARIANCE
    > * STANDARD_DEVIATION
    > * SEMI_DEVIATION
    > * MEAN_ABSOLUTE_DEVIATION
    > * FIRST_LOWER_PARTIAL_MOMENT
    > * CVAR
    > * EVAR
    > * WORST_REALIZATION
    > * CDAR
    > * MAX_DRAWDOWN
    > * AVERAGE_DRAWDOWN
    > * EDAR
    > * ULCER_INDEX
    > * GINI_MEAN_DIFFERENCE
    <br/>
    The default is `RiskMeasure.VARIANCE`.

  **risk_budget** *dict[str, float] | array-like of shape (n_assets,), optional*
  : Risk budget allocated to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset risk budget) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.
    The default (`None`) is to use the identity vector, reducing the risk
    budgeting to a risk-parity (each asset contributing equally to the total risk).

  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator 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 of the covariance.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **min_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=0.0*
  : Minimum assets weights (weights lower bounds).
    If a float is provided, it is applied to each asset.
    `None` is equivalent to `-np.Inf` (no lower bound).
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset minimum weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a minimum weight of `0.0`.
    The default value is `0.0` (no short selling).
    <br/>
    Example:
    > * `min_weights = 0` –> long only portfolio (no short selling).
    > * `min_weights = None` –> no lower bound (same as `-np.Inf`).
    > * `min_weights = -2` –> each weight must be above -200%.
    > * `min_weights = {"SX5E": 0, "SPX": -2}`
    > * `min_weights = [0, -2]`

  **max_weights** *float | dict[str, float] | array-like of shape (n_assets, ) | None, default=1.0*
  : Maximum assets weights (weights upper bounds).
    If a float is provided, it is applied to each asset.
    `None` is equivalent to `+np.Inf` (no upper bound).
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset maximum weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    When using a dictionary, assets values that are not provided are assigned
    a minimum weight of `1.0`.
    The default value is `1.0` (each asset is below 100%).
    <br/>
    Example:
    > * `max_weights = 0` –> no long position (short only portfolio).
    > * `max_weights = None` –> no upper bound.
    > * `max_weights = 2` –> each weight must be below 200%.
    > * `max_weights = {"SX5E": 1, "SPX": 2}`
    > * `max_weights = [1, 2]`

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Transaction costs of the assets. It is used to add linear transaction costs to
    the optimization problem:
    $$
    total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|
    <br/>
    $$
    <br/>
    with $c_{i}$ the transaction cost of asset i, $w_{i}$ its weight
    and $w\_prev_{i}$ its previous weight (defined in `previous_weights`).
    The float $total\_cost$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_cost
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the
    vector of assets weights.
    <br/>
    For positions in `previous_weights` whose assets are no longer in the
    investment universe, transaction costs are calculated assuming full
    liquidation. These costs are included in both the optimization and
    `Portfolio.total_cost`. For assets absent from `X`, `transaction_costs`
    must be a single rate applied to all assets or a dictionary keyed by asset name.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset cost) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the transaction costs
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `transaction_costs` need to be
    expressed as **daily** costs. A transaction cost is paid once per
    rebalancing while a position earns its expected return on every period it
    is held, so the one-off cost is converted by dividing it by the expected
    investment duration (e.g. `0.001 / 21` for a 10 bps cost with daily
    returns and a one-month expected holding period).
    (See [Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention))

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Management fees of the assets. It is used to add linear management fees to the
    optimization problem:
    $$
    total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}
    <br/>
    $$
    <br/>
    with $f_{i}$ the management fee of asset i and $w_{i}$ its weight.
    The float $total\_fee$ is impacting the portfolio expected return in the optimization:
    $$
    expected\_return = \mu^{T} \cdot w - total\_fee
    <br/>
    $$
    <br/>
    with $\mu$ the vector of assets’ expected returns and $w$ the vector
    of assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset fee) and the input `X` of the `fit` method must be a
    DataFrame with the assets names in columns.
    The default value is `0.0`.
    <br/>
    #### WARNING
    Based on the above formula, the periodicity of the management fees
    must match the periodicity of $\mu$. For example, if the input
    `X` is composed of **daily** returns, the `management_fees` need to be
    expressed in **daily** fees. Unlike transaction costs, management fees
    accrue with holding time, so a stated annual fee converts directly to the
    return periodicity (e.g. `0.02 / 252` for a 2% annual fee on daily
    returns).
    <br/>
    #### NOTE
    Another approach is to directly impact the management fees to the input `X`
    in order to express the returns net of fees. However, when estimating the
    $\mu$ parameter using for example Shrinkage estimators, this approach
    would mix a deterministic value with an uncertain one leading to unwanted
    bias in the management fees.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Previous weights of the assets. Previous weights are used to compute the
    portfolio cost and the portfolio turnover.
    For named positions in assets absent from `X`, these calculations assume
    full liquidation.
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset previous weight) and the input `X` of the `fit` method must
    be a DataFrame with the assets names in columns.
    The default (`None`) means no previous weights.
    Additionally, when `fallback="previous_weights"`, failures will fall back to
    these weights if provided.

  **linear_constraints** *array-like of shape (n_constraints,), optional*
  : Linear constraints on portfolio weights or factor exposures.
    <br/>
    Constraint names can reference:
    > * Asset names: individual asset weights (e.g. `"SPX"`, `"AAPL"`)
    > * Group names: sums of weights in groups defined by `groups`
    > * Factor names: portfolio factor exposure (requires factor model prior)
    > * Factor families: sum of portfolio exposures to all factors in one family
    <br/>
    Supported equation patterns include:
    > * `"name <= value"` or `"name >= value"`
    > * `"name == value"`
    > * `"a * name1 + b * name2 <= c * name3 + d"`
    <br/>
    For example:
    > * `"SPX >= 0.10"` –> SPX weight >= 10%
    > * `"SX5E + SPX >= 0.2"` –> sum of SX5E and SPX weights >= 20%
    > * `"US == 0.7"` –> sum of weights in US group == 70%
    > * `"Equity == 3 * Bond"` –> sum of weights in Equity group == 3x sum of weights in Bond group
    > * `"Momentum <= 0.30"` –> portfolio Momentum exposure <= 30%
    > * `"style <= 0.50"` –> sum of all style factor exposures (Momentum, Value, Size, etc.) <= 50%
    <br/>
    Factor constraints require a prior estimator (e.g.
    [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel),
    [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel))
    that provides `loading_matrix`, `factor_names` and optionally `factor_families`
    in its [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel).
    <br/>
    Asset, group, factor, and factor family names must be unique.

  **groups** *dict[str, list[str]] or array-like of shape (n_groups, n_assets), optional*
  : The assets groups referenced in `linear_constraints`.
    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"]]`

  **left_inequality** *array-like of shape (n_constraints, n_assets), optional*
  : Left inequality matrix $A$ of the linear
    constraint $A \cdot w \leq b$.

  **right_inequality** *array-like of shape (n_constraints, ), optional*
  : Right inequality vector $b$ of the linear
    constraint $A \cdot w \leq b$.

  **risk_free_rate** *float, default=0.0*
  : Risk-free interest rate.
    The default value is `0.0`.

  **min_return** *float | array-like of shape (n_optimization), optional*
  : Lower bound constraint on the expected return.

  **min_acceptable_return** *float, optional*
  : The minimum acceptable return used to distinguish “downside” and “upside”
    returns for the computation of lower partial moments:
    > * First Lower Partial Moment
    > * Semi-Variance
    > * Semi-Deviation
    <br/>
    The default (`None`) is to use the mean.

  **cvar_beta** *float, default=0.95*
  : CVaR (Conditional Value at Risk) confidence level.
    The default value is `0.95`.

  **evar_beta** *float, default=0.95*
  : EVaR (Entropic Value at Risk) confidence level.
    The default value is `0.95`.

  **cdar_beta** *float, default=0.95*
  : CDaR (Conditional Drawdown at Risk) confidence level.
    The default value is `0.95`.

  **edar_beta** *float, default=0.95*
  : EDaR (Entropic Drawdown at Risk) confidence level.
    The default value is `0.95`.

  **add_objective** *Callable[[cp.Variable], cp.Expression], optional*
  : Add a custom objective to the existing objective expression.
    It is a function that must take as argument the weights `w` and returns a
    CVXPY expression.

  **add_constraints** *Callable[[cp.Variable], cp.Expression | list[cp.Expression]], optional*
  : Add a custom constraint or a list of constraints to the existing constraints.
    It must be a function taking the CVXPY weight variable `w` as its first
    positional argument and, optionally, the estimator instance as its second.
    It must return a CVXPY expression or a list of CVXPY expressions, evaluated
    when `fit` is called.
    <br/>
    For example, to require an effective number of assets of at least 20:
    ```pycon
    >>> import cvxpy as cp
    >>> from skfolio.optimization import RiskBudgeting
    >>> model = RiskBudgeting(add_constraints=lambda w: cp.sum_squares(w) <= 1 / 20)
    ```
    <br/>
    The optional second argument gives access to the estimator’s attributes,
    including quantities estimated during `fit`. For example, to cap each
    position size in risk units at 20 bps, using the volatilities estimated
    by the prior:
    ```pycon
    >>> import numpy as np
    >>> def position_risk_cap(w, model):
    ...     covariance = model.prior_estimator_.return_distribution_.covariance
    ...     vols = np.sqrt(np.diag(covariance))
    ...     return cp.multiply(vols, w) <= 0.002
    >>> model = RiskBudgeting(add_constraints=position_risk_cap)
    ```

  **overwrite_expected_return** *Callable[[cp.Variable], cp.Expression], optional*
  : Overwrite the expected return $\mu \cdot w$ with a custom CVXPY
    expression. It must be a function taking the CVXPY weight variable `w` as
    its first positional argument and, optionally, the estimator instance as
    its second. It must return a concave CVXPY expression, evaluated when
    `fit` is called. The custom expression replaces the expected return in the
    objective function and in the constraints where the expected return is
    used.
    <br/>
    For example, to adjust the expected return for volatility drag,
    approximating the portfolio geometric mean return:
    ```pycon
    >>> import cvxpy as cp
    >>> from skfolio.optimization import RiskBudgeting
    >>> def geometric_expected_return(w, model):
    ...     dist = model.prior_estimator_.return_distribution_
    ...     return dist.mu @ w - 0.5 * cp.quad_form(w, dist.covariance)
    >>> model = RiskBudgeting(overwrite_expected_return=geometric_expected_return)
    ```

  **solver** *str, default=”CLARABEL”*
  : The solver to use. The default is “CLARABEL” which is written in Rust and has
    better numerical stability and performance than ECOS and SCS. Cvxpy will replace
    its default solver “ECOS” by “CLARABEL” in future releases.
    For more details about available solvers, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver](https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver)

  **solver_params** *dict, optional*
  : Solver parameters. For example, `solver_params=dict(verbose=True)`.
    The default (`None`) is use `{"tol_gap_abs": 1e-9, "tol_gap_rel": 1e-9}`
    for the solver “CLARABEL” and the CVXPY default otherwise.
    For more details about solver arguments, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options](https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options)

  **scale_objective** *float, optional*
  : Scale each objective element by this value.
    It can be used to increase the optimization accuracies in specific cases.
    The default (`None`) is set depending on the problem.

  **scale_constraints** *float, optional*
  : Scale each constraint element by this value.
    It can be used to increase the optimization accuracies in specific cases.
    The default (`None`) is set depending on the problem.

  **save_problem** *bool, default=False*
  : If this is set to True, the CVXPY Problem is saved in `problem_`.
    The default is `False`.

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    `transaction_costs`, `management_fees`, `previous_weights` and `risk_free_rate`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"` 
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary 
    estimator so that `fit` still returns the original instance. For traceability, 
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,) or (n_optimizations, n_assets)*
  : Weights of the assets.

  **problem_values_** *dict[str, float] | list[dict[str, float]] of size n_optimizations*
  : Expression values retrieved from the CVXPY problem.

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

  **problem_: cvxpy.Problem**
  : CVXPY problem used for the optimization. Only when `save_problem` is set to
    `True`.

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

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting.fit)(X[, y])            | Fit the Risk Budgeting Optimization estimator.                                                                                  |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

### References

* <a id='r80d35056dba9-1'>**[1]**</a> “Constrained Risk Budgeting Portfolios: Theory, Algorithms, Applications”, Journal of Portfolio Management, Richard, J.-C., & Roncalli, T. (2019)
* <a id='r80d35056dba9-2'>**[2]**</a> “Portfolio Optimization: Theory and Application”, Chapter 11, Daniel P. Palomar (2025)

### Examples

For complete tutorials on risk budgeting optimization, see the
[Risk Budgeting](https://skfolio.org/auto_examples/risk_budgeting/index.html.md#risk-budgeting-examples) gallery.

```pycon
>>> from skfolio import RiskMeasure
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.optimization import RiskBudgeting
>>> from skfolio.preprocessing import prices_to_returns
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # Variance risk parity optimization
>>> model = RiskBudgeting(risk_measure=RiskMeasure.VARIANCE)
>>> model.fit(X)
RiskBudgeting()
>>> print(model.weights_)
[0.0422 0.0314 0.0343 ... 0.0473 0.0603 0.0565]
>>>
>>> # CVaR risk budgeting with custom asset budgets
>>> risk_budget = {asset: 1.0 for asset in X.columns}
>>> risk_budget["AAPL"] = 1.5
>>> risk_budget["GE"] = 0.2
>>> risk_budget["JPM"] = 0.2
>>> model = RiskBudgeting(
...     risk_measure=RiskMeasure.CVAR,
...     risk_budget=risk_budget,
... )
>>> model.fit(X)
RiskBudgeting(...)
>>> print(model.weights_)
[0.0623 0.0319 0.0347 ... 0.0502 0.0659 0.0595]
>>>
>>> portfolio = model.predict(X)
>>> print(portfolio.cvar)
0.0251...
```

<a id="skfolio.optimization.RiskBudgeting.fit"></a>

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

Fit the Risk Budgeting Optimization estimator.

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

  **y** *array-like of shape (n_observations, n_factors), optional*
  : Price returns of factors.
    The default is `None`.
* **Returns:**
  **self** *RiskBudgeting*
  : Fitted estimator.

<a id="skfolio.optimization.RiskBudgeting.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.RiskBudgeting.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.optimization.RiskBudgeting.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.optimization.RiskBudgeting.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.RiskBudgeting.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.RiskBudgeting.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.RiskBudgeting.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.

# generated/skfolio.optimization.SchurComplementary.html.md

<a id="skfolio-optimization-schurcomplementary"></a>

# skfolio.optimization.SchurComplementary

<a id="skfolio.optimization.SchurComplementary"></a>

### *class* skfolio.optimization.SchurComplementary(gamma=0.5, keep_monotonic=True, prior_estimator=None, distance_estimator=None, hierarchical_clustering_estimator=None, min_weights=0.0, max_weights=1.0, transaction_costs=0.0, management_fees=0.0, previous_weights=None, portfolio_params=None, fallback=None, raise_on_failure=True)

Schur Complementary Allocation estimator.

Schur Complementary Allocation is a portfolio allocation method developed by Peter
Cotton [[1]](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#r8132b7cb9480-1).

It uses Schur-complement-inspired augmentation of sub-covariance matrices,
revealing a link between Hierarchical Risk Parity (HRP) and minimum-variance
portfolios (MVP).

By tuning the regularization factor `gamma`, which governs how much off-diagonal
information is incorporated into the augmented covariance blocks, the method
smoothly interpolates from the heuristic divide-and-conquer allocation of HRP
(`gamma = 0`) to the MVP solution (`gamma -> 1`).

The algorithm begins by computing a distance matrix and performing hierarchical
clustering, then applies seriation to reorder assets in the dendrogram so that
adjacent leaves have minimal distance.

Next, it uses recursive bisection: starting with the top-level cluster, each cluster
is split into two sub-clusters in a top-down traversal.

For each sub-cluster, an augmented covariance matrix is built based on the Schur
complement to incorporate off-diagonal block information. From this matrix, the
total cluster variance under an inverse-variance allocation is computed, and a
weighting factor derived from the variances of the two sub-clusters is used to
update their cluster weights.

* **Parameters:**
  **gamma** *float*
  : Regularization factor in [0, 1].
    When gamma is zero, no off-diagonal information is used (equivalent to HRP).
    As gamma approaches one, the allocation moves toward the minimum variance
    solution. The better the conditioning of the initial covariance matrix, the
    closer the allocation will get to the MVP solution when gamma is near one.

  **keep_monotonic** *bool, default=True*
  : If True, ensures that the portfolio variance decreases monotonically with
    respect to gamma. This is achieved by capping gamma at its maximum permissible
    value (`effective_gamma_`). This constraint guarantees that the solution remains
    variance-bounded by the HRP portfolio (`variance(Schur) <= variance(HRP)`),
    even in the presence of ill-conditioned covariance matrices.
    If False, no monotonicity enforcement or gamma capping is applied.
    For more details, see: [https://github.com/skfolio/skfolio/discussions/3](https://github.com/skfolio/skfolio/discussions/3)

  **prior_estimator** *BasePrior, optional*
  : [Prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).
    The prior estimator 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 and
    returns. The moments and returns estimations are used for the risk computation
    and the returns estimation are used by the distance matrix estimator.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **distance_estimator** *BaseDistance, optional*
  : [Distance estimator](https://skfolio.org/user_guide/distance.html.md#distance).
    The distance estimator is used to estimate the codependence and the distance
    matrix needed for the computation of the linkage matrix.
    The default (`None`) is to use [`PearsonDistance`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance).

  **hierarchical_clustering_estimator** *HierarchicalClustering, optional*
  : [Hierarchical Clustering estimator](https://skfolio.org/user_guide/cluster.html.md#hierarchical-clustering).
    The hierarchical clustering estimator is used to compute the linkage matrix
    and the hierarchical clustering of the assets based on the distance matrix.
    The default (`None`) is to use
    [`HierarchicalClustering`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering).

  **min_weights** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Minimum assets weights (weights lower bounds). The default is 0.0 (no short
    selling). Negative weights are not allowed. If a float is provided, it is
    applied to each asset. `None` is equivalent to the default `0.0`. If a
    dictionary is provided, its (key/value) pair must be the (asset name/asset
    minimum weight) and the input `X` of the `fit` methods must be a DataFrame with
    the asset names in columns. When using a dictionary, assets values that are not
    provided are assigned the default  minimum weight of `0.0`.
    <br/>
    Example:
    > * `min_weights = 0.0` –> long only portfolio (default).
    > * `min_weights = {"SX5E": 0.1, "SPX": 0.2}`
    > * `min_weights = [0.1, 0.2]`

  **max_weights** *float | dict[str, float] | array-like of shape (n_assets, ), default=1.0*
  : Maximum assets weights (weights upper bounds). The default is 1.0 (each asset
    is below 100%). Weights above 1.0 are not allowed. If a float is provided, it is
    applied to each asset. `None` is equivalent to the default `1.0`. If a
    dictionary is provided, its (key/value) pair must be the (asset name/asset
    maximum weight) and the input `X` of the `fit` method must be a DataFrame with
    the asset names in columns. When using a dictionary, assets values that are not
    provided are assigned the default maximum weight of `1.0`.
    <br/>
    Example:
    > * `max_weights = 1.0` –> each weight  must be below 100% (default).
    > * `max_weights = 0.5` –> each weight must be below 50%.
    > * `max_weights = {"SX5E": 0.8, "SPX": 0.9}`
    > * `max_weights = [0.8, 0.9]`

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Transaction costs of the assets.
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset cost) and the input `X` of the `fit` method must be a
    DataFrame with the asset names in columns.
    The default value is `0.0`.

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), default=0.0*
  : Management fees of the assets.
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset fee) and the input `X` of the `fit` method must be a
    DataFrame with the asset names in columns.
    The default value is `0.0`.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Previous weights of the assets. Previous weights are used to compute the
    portfolio total cost. If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset previous weight) and the input `X` of the `fit` method must
    be a DataFrame with the asset names in columns.
    The default (`None`) means no previous weights.
    Additionally, when `fallback="previous_weights"`, failures will fall back to
    these weights if provided.

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    `transaction_costs`, `management_fees`, `previous_weights` and `risk_free_rate`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,)*
  : Weights of the assets.

  **effective_gamma_** *float*
  : If `keep_monotonic` is True, the highest permissible `gamma` that preserves
    monotonic variance decrease; otherwise, equal to the input `gamma`.

  **distance_estimator_** *BaseDistance*
  : Fitted `distance_estimator`.

  **hierarchical_clustering_estimator_** *HierarchicalClustering*
  : Fitted `hierarchical_clustering_estimator`.

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

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#skfolio.optimization.SchurComplementary.fit)(X[, y])            | Fit the Schur Complementary estimator.                                                                                          |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#skfolio.optimization.SchurComplementary.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#skfolio.optimization.SchurComplementary.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#skfolio.optimization.SchurComplementary.get_params)([deep])     | Get parameters for this estimator.                                                                                              |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#skfolio.optimization.SchurComplementary.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#skfolio.optimization.SchurComplementary.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.SchurComplementary.html.md#skfolio.optimization.SchurComplementary.set_params)(\*\*params) | Set the parameters of this estimator.                                                                                           |

### Notes

A poorly conditioned covariance matrix can prevent convergence to the MVP solution
as gamma approaches one. Setting `keep_monotonic=True` (the default) ensures that
the portfolio variance decreases monotonically with respect to gamma and remains
bounded by the variance of the HRP portfolio (`variance(Schur) <= variance(HRP)`),
even in the presence of ill-conditioned covariance matrices. Additionally, you can
apply shrinkage or other conditioning techniques via the `prior_estimator` parameter
to improve numerical stability and estimation accuracy.

### References

* <a id='r8132b7cb9480-1'>**[1]**</a> “Schur Complementary Allocation: A Unification of Hierarchical Risk Parity and Minimum Variance Portfolios”. Peter Cotton (2024).
* <a id='r8132b7cb9480-2'>**[2]**</a> “Portfolio Optimization. Theory and Application”. Chapter 12.3.4 “From Portfolio Risk Minimization to Hierarchical Portfolios” Daniel P. Palomar (2025).
* <a id='r8132b7cb9480-3'>**[3]**</a> “Building diversified portfolios that outperform out of sample”, The Journal of Portfolio Management, Marcos López de Prado (2016).
* <a id='r8132b7cb9480-4'>**[4]**</a> “A robust estimator of the efficient frontier”, SSRN Electronic Journal, Marcos López de Prado (2019).
* <a id='r8132b7cb9480-5'>**[5]**</a> “Machine Learning for Asset Managers”, Elements in Quantitative Finance. Cambridge University Press, Marcos López de Prado (2020).
* <a id='r8132b7cb9480-6'>**[6]**</a> “A review of two decades of correlations, hierarchies, networks and clustering in financial markets”, Gautier Marti, Frank Nielsen, Mikołaj Bińkowski, Philippe Donnat (2020).

### Examples

For a full tutorial on Schur Complementary Allocation, see
[Schur Complementary Allocation](https://skfolio.org/auto_examples/clustering/plot_6_schur.html.md#sphx-glr-auto-examples-clustering-plot-6-schur-py).

```pycon
>>> from skfolio import RiskMeasure
>>> from skfolio.cluster import HierarchicalClustering, LinkageMethod
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.distance import KendallDistance
>>> from skfolio.moments import LedoitWolf
>>> from skfolio.optimization import SchurComplementary
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.prior import EmpiricalPrior
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # Default Schur Complementary allocation
>>> model = SchurComplementary(gamma=0.5)
>>> model.fit(X)
SchurComplementary()
>>> print(model.weights_)
[0.0358 0.0061 0.0262 ... 0.0426 0.1129 0.048 ]
>>>
>>> # Advanced model:
>>> #    * Ledoit-Wolf covariance shrinkage
>>> #    * Kendall's tau distance (absolute) for asset co-dependence
>>> #    * Hierarchical clustering with Ward's linkage
>>> model = SchurComplementary(
...     gamma=0.5,
...     prior_estimator=EmpiricalPrior(covariance_estimator=LedoitWolf()),
...     distance_estimator=KendallDistance(absolute=True),
...     hierarchical_clustering_estimator=HierarchicalClustering(
...         linkage_method=LinkageMethod.WARD,
...     ),
... )
>>> model.fit(X)
SchurComplementary(...)
>>> print(model.weights_)
[0.0323 0.0095 0.0234 ... 0.0402 0.0515 0.0605]
```

<a id="skfolio.optimization.SchurComplementary.fit"></a>

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

Fit the Schur Complementary 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.
* **Returns:**
  **self** *SchurComplementary*
  : Fitted estimator.

<a id="skfolio.optimization.SchurComplementary.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.SchurComplementary.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.optimization.SchurComplementary.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.optimization.SchurComplementary.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.SchurComplementary.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.SchurComplementary.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.SchurComplementary.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.

# generated/skfolio.optimization.StackingOptimization.html.md

<a id="skfolio-optimization-stackingoptimization"></a>

# skfolio.optimization.StackingOptimization

<a id="skfolio.optimization.StackingOptimization"></a>

### *class* skfolio.optimization.StackingOptimization(estimators, final_estimator=None, cv=None, quantile=0.5, quantile_measure=Sharpe Ratio, n_jobs=None, verbose=0, portfolio_params=None, fallback=None, previous_weights=None, raise_on_failure=True)

Stack of optimizations with a final optimization.

Stacking Optimization is an ensemble method that consists of stacking the output of
individual portfolio optimizations with a final portfolio optimization.

The weights are the dot-product of individual optimization weights with the final
optimization weights.

Stacking uses the strength of each individual portfolio optimization by
using their output as input of a final portfolio optimization.

To avoid data leakage, out-of-sample estimates are used to fit the outer
optimization.

Note that `estimators_` are fitted on the full `X` while `final_estimator_`
is trained using cross-validated predictions of the base estimators using
`cross_val_predict`.

* **Parameters:**
  **estimators** *list[tuple[str, BaseOptimization]]*
  : [Optimization estimators](https://skfolio.org/user_guide/optimization.html.md#optimization) which will be stacked together.
    Each element of the list is defined as a tuple of string (i.e. name) and an
    [optimization estimator](https://skfolio.org/user_guide/optimization.html.md#optimization).

  **final_estimator** *BaseOptimization, optional*
  : A final [optimization estimator](https://skfolio.org/user_guide/optimization.html.md#optimization) which will be used to
    combine the base estimators.
    The default (`None`) is to use [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk).

  **cv** *BaseCrossValidator | BaseCombinatorialCV | int | “prefit” | “ignore”, optional*
  : Determines the cross-validation splitting strategy used in `cross_val_predict`
    to train the `final_estimator`.
    The default (`None`) is to use the 5-fold cross validation `KFold()`.
    Possible inputs for `cv` are:
    > * “ignore”: no cross-validation is used (note that it will likely lead to data leakage with a high risk of overfitting)
    > * integer, to specify the number of folds in a `KFold`
    > * An object to be used as a cross-validation generator
    > * An iterable yielding train, test splits
    > * “prefit” to assume the `estimators` are prefit, and skip cross validation
    > * A [`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV)
    <br/>
    If a `CombinatorialCV` cross-validator is used, each cluster out-of-sample
    outputs becomes a collection of multiple paths instead of one single path. The
    selected out-of-sample path among this collection of paths is chosen according
    to the `quantile` and `quantile_measure` parameters.
    <br/>
    If “prefit” is passed, it is assumed that all `estimators` have been fitted
    already. The `final_estimator_` is trained on the `estimators` predictions on
    the full training set and are **not** cross validated predictions.
    Please note that if the models have been trained on the same data to train the
    stacking model, there is a very high risk of overfitting.

  **n_jobs** *int, optional*
  : The number of jobs to run in parallel for `fit` of all `estimators`.
    The value `-1` means using all processors.
    The default (`None`) means 1 unless in a `joblib.parallel_backend` context.

  **quantile** *float, default=0.5*
  : Quantile for a given measure (`quantile_measure`) of the out-of-sample
    inner-estimator paths when the `cv` parameter is a
    [`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) cross-validator.
    The default value is `0.5` corresponding to the path with the median measure.
    (see `cv`)

  **quantile_measure** *PerfMeasure or RatioMeasure or RiskMeasure or ExtraRiskMeasure, default=RatioMeasure.SHARPE_RATIO*
  : Measure used for the quantile path selection (see `quantile` and `cv`).
    The default is `RatioMeasure.SHARPE_RATIO`.

  **verbose** *int, default=0*
  : The verbosity level. The default value is `0`.

  **portfolio_params** *dict, optional*
  : Portfolio parameters forwarded to the resulting `Portfolio` in `predict`.
    If not provided and if available on the estimator, the following
    attributes are propagated to the portfolio by default: `name`,
    `transaction_costs`, `management_fees`, `previous_weights` and `risk_free_rate`.

  **fallback** *BaseOptimization | “previous_weights” | list[BaseOptimization | “previous_weights”], optional*
  : Fallback estimator or a list of estimators to try, in order, when the primary
    optimization raises during `fit`. Alternatively, use `"previous_weights"`
    (alone or in a list) to fall back to the estimator’s `previous_weights`.
    When a fallback succeeds, its fitted `weights_` are copied back to the primary
    estimator so that `fit` still returns the original instance. For traceability,
    `fallback_` stores the successful estimator (or the string `"previous_weights"`)
    and `fallback_chain_` stores each attempt with the associated outcome.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets,), optional*
  : When `fallback="previous_weights"`, failures will fall back to these weights
    if provided.

  **raise_on_failure** *bool, default=True*
  : Controls error handling when fitting fails.
    If True, any failure during `fit` is raised immediately, no `weights_` are
    set and subsequent calls to `predict` will raise a `NotFittedError`.
    If False, errors are not raised; instead, a warning is emitted, `weights_`
    is set to `None` and subsequent calls to `predict` will return a
    `FailedPortfolio`. When fallbacks are specified, this behavior applies only
    after all fallbacks have been exhausted.
* **Attributes:**
  **weights_** *ndarray of shape (n_assets,)*
  : Weights of the assets.

  **estimators_** *list[BaseOptimization]*
  : The elements of the `estimators` parameter, having been fitted on the
    training data. When `cv="prefit"`, `estimators_`
    is set to `estimators` and is not fitted again.

  **named_estimators_** *dict[str, BaseOptimization]*
  : Attribute to access any fitted sub-estimators by name.

  **final_estimator_** *BaseOptimization*
  : The fitted `final_estimator`.

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

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

  **fallback_** *BaseOptimization | “previous_weights” | None*
  : The fallback estimator instance, or the string `"previous_weights"`, that
    produced the final result. `None` if no fallback was used.

  **fallback_chain_** *list[tuple[str, str]] | None*
  : Sequence describing the optimization fallback attempts. Each element is a
    pair `(estimator_repr, outcome)` where `estimator_repr` is the string
    representation of the primary estimator or a fallback (e.g. `"EqualWeighted()"`,
    `"previous_weights"`), and `outcome` is `"success"` if that step produced
    a valid solution, otherwise the stringified error message. For successful
    fits without any fallback, this is `None`.

  **error_** *str | list[str] | None*
  : Captured error message(s) when `fit` fails. For multi-portfolio outputs
    (`weights_` is 2D), this is a list aligned with portfolios.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.optimization.StackingOptimization.html.md#skfolio.optimization.StackingOptimization.fit)(X[, y])            | Fit the Stacking Optimization estimator.                                                                                        |
|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|
| [`fit_predict`](https://skfolio.org/generated/skfolio.optimization.StackingOptimization.html.md#skfolio.optimization.StackingOptimization.fit_predict)(X)         | Perform `fit` on `X` and returns the predicted `Portfolio` or `Population` of `Portfolio` on `X` based on the fitted `weights`. |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.optimization.StackingOptimization.html.md#skfolio.optimization.StackingOptimization.get_metadata_routing)() | Get metadata routing of this object.                                                                                            |
| [`get_params`](https://skfolio.org/generated/skfolio.optimization.StackingOptimization.html.md#skfolio.optimization.StackingOptimization.get_params)([deep])     | Get the parameters of an estimator from the ensemble.                                                                           |
| [`predict`](https://skfolio.org/generated/skfolio.optimization.StackingOptimization.html.md#skfolio.optimization.StackingOptimization.predict)(X)             | Predict the `Portfolio` or a `Population` of portfolios on `X`.                                                                 |
| [`score`](https://skfolio.org/generated/skfolio.optimization.StackingOptimization.html.md#skfolio.optimization.StackingOptimization.score)(X[, y])          | Prediction score using the Sharpe Ratio.                                                                                        |
| [`set_params`](https://skfolio.org/generated/skfolio.optimization.StackingOptimization.html.md#skfolio.optimization.StackingOptimization.set_params)(\*\*params) | Set the parameters of an estimator from the ensemble.                                                                           |

### Notes

All estimators should specify all parameters as explicit keyword arguments in
`__init__` (no `*args` or `**kwargs`), following scikit-learn conventions.

<a id="skfolio.optimization.StackingOptimization.fit"></a>

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

Fit the Stacking Optimization estimator.

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

  **y** *array-like of shape (n_observations, n_targets), optional*
  : Price returns of factors or a target benchmark.
    The default is `None`.

  **\*\*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** *StackingOptimization*
  : Fitted estimator.

<a id="skfolio.optimization.StackingOptimization.fit_predict"></a>

#### fit_predict(X)

Perform `fit` on `X` and returns the predicted `Portfolio` or
`Population` of `Portfolio` on `X` based on the fitted `weights`.
For factor models, use `fit(X, factors=...)` then `predict(X)` separately.

If fitting fails and `raise_on_failure=False`, this returns a
`FailedPortfolio`.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.StackingOptimization.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.optimization.StackingOptimization.get_params"></a>

#### get_params(deep=True)

Get the parameters of an estimator from the ensemble.

Returns the parameters given in the constructor as well as the
estimators contained within the `estimators` parameter.

* **Parameters:**
  **deep** *bool, default=True*
  : Setting it to True gets the various estimators and the parameters
    of the estimators as well.
* **Returns:**
  **params** *dict*
  : Parameter and estimator names mapped to their values or parameter
    names mapped to their values.

<a id="skfolio.optimization.StackingOptimization.named_estimators"></a>

#### *property* named_estimators

Dictionary to access any fitted sub-estimators by name.

* **Returns:**
  `Bunch`

<a id="skfolio.optimization.StackingOptimization.needs_previous_weights"></a>

#### *property* needs_previous_weights

Whether `previous_weights` must be propagated between folds/rebalances.

Used by `cross_val_predict` and `online_predict` to decide whether to run
sequentially and pass the weights from the previous rebalancing to the next.
This is `True` when `portfolio_params` sets `weight_drift=True`, or when
transaction costs, a maximum turnover, or a fallback depending on
`previous_weights` are present.

<a id="skfolio.optimization.StackingOptimization.predict"></a>

#### predict(X)

Predict the `Portfolio` or a `Population` of portfolios on `X`.

Optimization estimators can return a 1D or a 2D array of `weights`.
For a 1D array, the prediction is a single `Portfolio`.
For a 2D array, the prediction is a `Population` of `Portfolio`.

If `name` is not provided in the portfolio parameters, the estimator
class name is used.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets) | ReturnDistribution*
  : Asset returns or a `ReturnDistribution` carrying returns and optional
    sample weights.
* **Returns:**
  Portfolio | Population
  : The predicted `Portfolio` or `Population` based on the fitted `weights`.

<a id="skfolio.optimization.StackingOptimization.score"></a>

#### score(X, y=None)

Prediction score using the Sharpe Ratio.
If the prediction is a single `Portfolio`, the score is its Sharpe Ratio.
If the prediction is a `Population`, the score is the mean Sharpe Ratio
across portfolios.

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

  **y** *Ignored*
  : Not used, present here for API consistency by convention.
* **Returns:**
  **score** *float*
  : The Sharpe Ratio of the portfolio if the prediction is a single `Portfolio`
    or the mean of all the portfolio Sharpe Ratios if the prediction is a
    `Population` of `Portfolio`.

<a id="skfolio.optimization.StackingOptimization.set_params"></a>

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

Set the parameters of an estimator from the ensemble.

Valid parameter keys can be listed with `get_params()`. Note that you
can directly set the parameters of the estimators contained in
`estimators`.

* **Parameters:**
  **\*\*params** *keyword arguments*
  : Specific parameters using e.g.
    `set_params(parameter_name=new_value)`. In addition, to setting the
    parameters of the estimator, the individual estimator of the
    estimators can also be set, or can be removed by setting them to
    ‘drop’.
* **Returns:**
  **self** *object*
  : Estimator instance.

# generated/skfolio.population.Population.html.md

<a id="skfolio-population-population"></a>

# skfolio.population.Population

<a id="skfolio.population.Population"></a>

### *class* skfolio.population.Population(iterable)

Population Class.

A `Population` is a list of [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) or
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) or both.

* **Parameters:**
  **iterable** *list[BasePortfolio]*
  : The list of portfolios. Each item can be of type
    [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) and/or
    [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio).
    Empty list are accepted.

### Methods

| [`append`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.append)(item)                                     | Append portfolio to the end of the population list.                                                              |
|---------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| [`boxplot_measure`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.boxplot_measure)(measure[, tag_list, points])     | Plot a box plot of a measure's distribution, optionally split by tags.                                           |
| [`clear`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.clear)(/)                                         | Remove all items from list.                                                                                      |
| [`composition`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.composition)([display_sub_ptf_name])              | Composition of each portfolio in the population.                                                                 |
| [`contribution`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.contribution)(measure[, spacing, ...])            | Contribution of each asset to a given measure of each portfolio in the population.                               |
| [`copy`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.copy)(/)                                          | Return a shallow copy of the list.                                                                               |
| [`count`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.count)(value, /)                                  | Return number of occurrences of value.                                                                           |
| [`cumulative_returns_df`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.cumulative_returns_df)([use_tag_in_column_name])  | DataFrame of cumulative returns for each portfolio in the population.                                            |
| [`drawdowns_df`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.drawdowns_df)([use_tag_in_column_name])           | DataFrame of drawdowns for each portfolio in the population.                                                     |
| [`extend`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.extend)(other)                                    | Extend population list by appending elements from the iterable.                                                  |
| [`filter`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.filter)([names, tags])                            | Filter the Population of portfolios by names and tags.                                                           |
| [`index`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.index)(value[, start, stop])                      | Return first index of value.                                                                                     |
| [`insert`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.insert)(index, item)                              | Insert portfolio before index.                                                                                   |
| [`max_measure`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.max_measure)(measure)                             | Return the portfolio with the maximum measure.                                                                   |
| [`measures`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.measures)(measure)                                | Vector of portfolios measures for each portfolio from the population.                                            |
| [`measures_mean`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.measures_mean)(measure)                           | Mean of portfolios measures for each portfolio from the population.                                              |
| [`measures_std`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.measures_std)(measure)                            | Standard-deviation of portfolios measures for each portfolio from the population.                                |
| [`min_measure`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.min_measure)(measure)                             | Return the portfolio with the minimum measure.                                                                   |
| [`non_denominated_sort`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.non_denominated_sort)([first_front_only])         | Alias of [`non_dominated_sort`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.non_dominated_sort).                                    |
| [`non_dominated_sort`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.non_dominated_sort)([first_front_only])           | Fast non-dominated sorting.                                                                                      |
| [`plot_composition`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.plot_composition)([display_sub_ptf_name])         | Plot the compositions of the portfolios in the population.                                                       |
| [`plot_contribution`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.plot_contribution)(measure[, spacing, ...])       | Plot the contribution of each asset to a given measure of the portfolios in the population.                      |
| [`plot_cumulative_returns`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.plot_cumulative_returns)([log_scale, idx, ...])   | Plot the cumulative returns of the population's portfolios.                                                      |
| [`plot_distribution`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.plot_distribution)(measure_list[, tag_list, ...]) | Plot the population's distribution for each measure provided in the measure list.                                |
| [`plot_drawdowns`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.plot_drawdowns)([idx, use_tag_in_legend])         | Plot the drawdowns of the population's portfolios.                                                               |
| [`plot_measures`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.plot_measures)(x, y[, z, to_surface, ...])        | Plot the 2D (or 3D) scatter points (or surface) of a given set of measures for each portfolio in the population. |
| [`plot_returns_distribution`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.plot_returns_distribution)([percentile_cutoff])   | Plot the Portfolios returns distribution using Gaussian KDE.                                                     |
| [`plot_rolling_measure`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.plot_rolling_measure)([measure, window])          | Plot the measure over a rolling window for each portfolio in the population.                                     |
| [`pop`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.pop)([index])                                     | Remove and return item at index (default last).                                                                  |
| [`quantile`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.quantile)(measure, q)                             | Return the portfolio corresponding to the `q` quantile for a given portfolio measure.                            |
| [`remove`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.remove)(value, /)                                 | Remove first occurrence of value.                                                                                |
| [`returns_df`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.returns_df)([use_tag_in_column_name])             | DataFrame of returns for each portfolio in the population.                                                       |
| [`reverse`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.reverse)(/)                                       | Reverse *IN PLACE*.                                                                                              |
| [`rolling_measure`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.rolling_measure)([measure, window])               | Compute the measure over a rolling window for each portfolio in the                                              |
| [`set_portfolio_params`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.set_portfolio_params)(\*\*params)                 | Set the parameters of all the portfolios.                                                                        |
| [`sort`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.sort)(\*[, key, reverse])                         | Sort the list in ascending order and return None.                                                                |
| [`sort_measure`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.sort_measure)(measure[, reverse])                 | Sort the population by a given portfolio measure.                                                                |
| [`summary`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.summary)([formatted])                             | Summary of the portfolios in the population.                                                                     |

<a id="skfolio.population.Population.append"></a>

#### append(item)

Append portfolio to the end of the population list.

<a id="skfolio.population.Population.boxplot_measure"></a>

#### boxplot_measure(measure, tag_list=None, points='all')

Plot a box plot of a measure’s distribution, optionally split by tags.

If no tags are provided, the function draws a single box showing the
population distribution of `measure`. If `tag_list` is provided, it draws
one box per tag using values from the portfolio filtered by each tag.

* **Parameters:**
  **measure** *Measure*
  : The measure to plot.

  **tag_list** *list[str], optional*
  : For each tag in this list, filter the portfolio by that tag and plot a
    separate box. If None or empty, plot a single overall distribution.

  **points** *{‘all’, ‘outliers’, ‘suspectedoutliers’, False}, default ‘all’*
  : Passed to `plotly.express.box(..., points=...)` to control which points
    are shown.
* **Returns:**
  go.Figure
  : The Plotly figure.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio import Population, Portfolio, RatioMeasure, RiskMeasure
>>> rng = np.random.default_rng(0)
>>> # Daily returns for two assets.
>>> X = rng.normal(0.0005, [0.02, 0.01], size=(252, 2))
>>> population = Population(
...     [
...         Portfolio(X, weights=[0.6, 0.4], tag="Asset 1 tilt"),
...         Portfolio(X, weights=[0.7, 0.3], tag="Asset 1 tilt"),
...         Portfolio(X, weights=[0.8, 0.2], tag="Asset 1 tilt"),
...         Portfolio(X, weights=[0.4, 0.6], tag="Asset 2 tilt"),
...         Portfolio(X, weights=[0.3, 0.7], tag="Asset 2 tilt"),
...         Portfolio(X, weights=[0.2, 0.8], tag="Asset 2 tilt"),
...     ]
... )
```

Plot all portfolios in one box:

```pycon
>>> fig = population.boxplot_measure(measure=RiskMeasure.STANDARD_DEVIATION)
```

Plot one box per tag:

```pycon
>>> fig = population.boxplot_measure(
...     measure=RatioMeasure.SHARPE_RATIO,
...     tag_list=["Asset 1 tilt", "Asset 2 tilt"],
... )
```

<a id="skfolio.population.Population.clear"></a>

#### clear(/)

Remove all items from list.

<a id="skfolio.population.Population.composition"></a>

#### composition(display_sub_ptf_name=True)

Composition of each portfolio in the population.

* **Parameters:**
  **display_sub_ptf_name** *bool, default=True*
  : If this is set to True, each sub-portfolio name composing a multi-period
    portfolio is displayed.
* **Returns:**
  **df** *DataFrame*
  : Composition of the portfolios in the population.

<a id="skfolio.population.Population.contribution"></a>

#### contribution(measure, spacing=None, display_sub_ptf_name=True)

Contribution of each asset to a given measure of each portfolio in the
population.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$.

  **display_sub_ptf_name** *bool, default=True*
  : If this is set to True, each sub-portfolio name composing a multi-period
    portfolio is displayed.
* **Returns:**
  **df** *DataFrame*
  : Contribution of each asset to a given measure of each portfolio in the
    population.

<a id="skfolio.population.Population.copy"></a>

#### copy(/)

Return a shallow copy of the list.

<a id="skfolio.population.Population.count"></a>

#### count(value, /)

Return number of occurrences of value.

<a id="skfolio.population.Population.cumulative_returns_df"></a>

#### cumulative_returns_df(use_tag_in_column_name=True)

DataFrame of cumulative returns for each portfolio in the population.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

* **Parameters:**
  **use_tag_in_column_name** *bool, default=True*
  : Whether to include the portfolio tag in the DataFrame column names.
    If True, each column name will use the portfolio name followed by its tag;
    if False, only the portfolio name will be used.
* **Returns:**
  **cumulative_returns** *DataFrame*
  : Cumulative returns DataFrame.

<a id="skfolio.population.Population.drawdowns_df"></a>

#### drawdowns_df(use_tag_in_column_name=True)

DataFrame of drawdowns for each portfolio in the population.

* **Parameters:**
  **use_tag_in_column_name** *bool, default=True*
  : Whether to include the portfolio tag in the DataFrame column names.
    If True, each column name will use the portfolio name followed by its tag;
    if False, only the portfolio name will be used.
* **Returns:**
  **drawdowns** *DataFrame*
  : Drawdowns DataFrame.

<a id="skfolio.population.Population.extend"></a>

#### extend(other)

Extend population list by appending elements from the iterable.

<a id="skfolio.population.Population.filter"></a>

#### filter(names=None, tags=None)

Filter the Population of portfolios by names and tags.
If both names and tags are provided, the intersection is returned.

* **Parameters:**
  **names** *str | list[str], optional*
  : If provided, the population is filtered by portfolio names.

  **tags** *str | list[str], optional*
  : If provided, the population is filtered by portfolio tags.
* **Returns:**
  **population** *Population*
  : A new population of portfolios filtered by names and tags.

<a id="skfolio.population.Population.index"></a>

#### index(value, start=0, stop=sys.maxsize, /)

Return first index of value.

Raises ValueError if the value is not present.

<a id="skfolio.population.Population.insert"></a>

#### insert(index, item)

Insert portfolio before index.

<a id="skfolio.population.Population.max_measure"></a>

#### max_measure(measure)

Return the portfolio with the maximum measure.

* **Parameters:**
  **measure: Measure**
  : The portfolio measure.
* **Returns:**
  **values** *BasePortfolio*
  : The portfolio with maximum measure.

<a id="skfolio.population.Population.measures"></a>

#### measures(measure)

Vector of portfolios measures for each portfolio from the
population.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.
* **Returns:**
  **values** *ndarray*
  : The vector of portfolios measures.

<a id="skfolio.population.Population.measures_mean"></a>

#### measures_mean(measure)

Mean of portfolios measures for each portfolio from the
population.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.
* **Returns:**
  **value** *float*
  : The mean of portfolios measures.

<a id="skfolio.population.Population.measures_std"></a>

#### measures_std(measure)

Standard-deviation of portfolios measures for each portfolio from the
population.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.
* **Returns:**
  **value** *float*
  : The standard-deviation of portfolios measures.

<a id="skfolio.population.Population.min_measure"></a>

#### min_measure(measure)

Return the portfolio with the minimum measure.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.
* **Returns:**
  **values** *BasePortfolio*
  : The portfolio with minimum measure.

<a id="skfolio.population.Population.non_denominated_sort"></a>

#### non_denominated_sort(first_front_only=False)

Alias of [`non_dominated_sort`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.non_dominated_sort).

#### Deprecated
Deprecated since version \`non_denominated_sort\`: is deprecated and will be removed in version 2.0.
Use [`non_dominated_sort`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population.non_dominated_sort) instead.

<a id="skfolio.population.Population.non_dominated_sort"></a>

#### non_dominated_sort(first_front_only=False)

Fast non-dominated sorting.
Sort the portfolios into different non-domination levels.
Complexity O(MN^2) where M is the number of objectives and N the number of
portfolios.

* **Parameters:**
  **first_front_only** *bool, default=False*
  : If this is set to True, only the first front is sorted and returned.
    The default is `False`.
* **Returns:**
  **fronts** *list[list[int]]*
  : A list of Pareto fronts (lists), the first list includes
    non-dominated portfolios.

<a id="skfolio.population.Population.plot_composition"></a>

#### plot_composition(display_sub_ptf_name=True)

Plot the compositions of the portfolios in the population.

* **Parameters:**
  **display_sub_ptf_name** *bool, default=True*
  : If this is set to True, each sub-portfolio name composing a multi-period
    portfolio is displayed.
* **Returns:**
  **plot** *Figure*
  : Returns the plotly Figure object.

<a id="skfolio.population.Population.plot_contribution"></a>

#### plot_contribution(measure, spacing=None, display_sub_ptf_name=True)

Plot the contribution of each asset to a given measure of the portfolios
in the population.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$

  **display_sub_ptf_name** *bool, default=True*
  : If this is set to True, each sub-portfolio name composing a multi-period
    portfolio is displayed.
* **Returns:**
  **plot** *Figure*
  : Returns the plotly Figure object.

<a id="skfolio.population.Population.plot_cumulative_returns"></a>

#### plot_cumulative_returns(log_scale=False, idx=None, use_tag_in_legend=True)

Plot the cumulative returns of the population’s portfolios.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

* **Parameters:**
  **log_scale** *bool, default=False*
  : If set to True, the cumulative returns are displayed with a
    logarithm scale on the y-axis. The cumulative returns must be compounded
    otherwise an exception is raise.

  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to take all observations.

  **use_tag_in_legend** *bool, default=True*
  : Whether to include the portfolio tag in legend entries.
    If True, each legend label will show the portfolio name followed by its tag;
    if False, only the portfolio name will be displayed.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.population.Population.plot_distribution"></a>

#### plot_distribution(measure_list, tag_list=None, n_bins=None, \*\*kwargs)

Plot the population’s distribution for each measure provided in the
measure list.

* **Parameters:**
  **measure_list** *list[Measure]*
  : The list of portfolio measures. A different distribution is plotted per
    measure.

  **tag_list** *list[str], optional*
  : If this is provided, an additional distribution is plotted per measure
    for each tag provided.

  **n_bins** *int, optional*
  : Sets the number of bins.
* **Returns:**
  **plot** *Figure*
  : Returns the plotly Figure object.

<a id="skfolio.population.Population.plot_drawdowns"></a>

#### plot_drawdowns(idx=None, use_tag_in_legend=True)

Plot the drawdowns of the population’s portfolios.

* **Parameters:**
  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to take all observations.

  **use_tag_in_legend** *bool, default=True*
  : Whether to include the portfolio tag in legend entries.
    If True, each legend label will show the portfolio name followed by its tag;
    if False, only the portfolio name will be displayed.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.population.Population.plot_measures"></a>

#### plot_measures(x, y, z=None, to_surface=False, hover_measures=None, show_fronts=False, color_scale=None, title='Portfolios')

Plot the 2D (or 3D) scatter points (or surface) of a given set of
measures for each portfolio in the population.

* **Parameters:**
  **x** *Measure*
  : The x-axis measure.

  **y** *Measure*
  : The y-axis measure.

  **z** *Measure, optional*
  : The z-axis measure.

  **to_surface** *bool, default=False*
  : If this is set to True, a surface is estimated.

  **hover_measures** *list[Measure], optional*
  : The list of measure to show on point hover.

  **show_fronts** *bool, default=False*
  : If this is set to True, the Pareto fronts are highlighted.
    The default is `False`.

  **color_scale** *Measure | str, optional*
  : If this is provided, a color scale is displayed.

  **title** *str, default=”Portfolios”*
  : The graph title. The default value is “Portfolios”.
* **Returns:**
  **plot** *Figure*
  : Returns the plotly Figure object.

<a id="skfolio.population.Population.plot_returns_distribution"></a>

#### plot_returns_distribution(percentile_cutoff=None)

Plot the Portfolios returns distribution using Gaussian KDE.

* **Parameters:**
  **percentile_cutoff** *float, default=None*
  : Percentile cutoff for tail truncation (percentile), in percent.
    If a float p is provided, the distribution support is truncated at the p-th
    and (100 - p)-th percentiles.
    If None, no truncation is applied (uses full min/max of returns).
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.population.Population.plot_rolling_measure"></a>

#### plot_rolling_measure(measure=Sharpe Ratio, window=30)

Plot the measure over a rolling window for each portfolio in the population.

* **Parameters:**
  **measure** *Measure, default = RatioMeasure.SHARPE_RATIO*
  : The measure.

  **window** *int, default=30*
  : The window size.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.population.Population.pop"></a>

#### pop(index=-1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

<a id="skfolio.population.Population.quantile"></a>

#### quantile(measure, q)

Return the portfolio corresponding to the `q` quantile for a given portfolio
measure.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.

  **q** *float*
  : The quantile value.
* **Returns:**
  **values** *BasePortfolio*
  : Portfolio corresponding to the `q` quantile for the measure.

<a id="skfolio.population.Population.remove"></a>

#### remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

<a id="skfolio.population.Population.returns_df"></a>

#### returns_df(use_tag_in_column_name=True)

DataFrame of returns for each portfolio in the population.

* **Parameters:**
  **use_tag_in_column_name** *bool, default=True*
  : Whether to include the portfolio tag in the DataFrame column names.
    If True, each column name will use the portfolio name followed by its tag;
    if False, only the portfolio name will be used.
* **Returns:**
  **returns** *DataFrame*
  : Returns DataFrame where each column represents a portfolio’s returns
    time series.

<a id="skfolio.population.Population.reverse"></a>

#### reverse(/)

Reverse *IN PLACE*.

<a id="skfolio.population.Population.rolling_measure"></a>

#### rolling_measure(measure=Sharpe Ratio, window=30)

Compute the measure over a rolling window for each portfolio in the
: population.

* **Parameters:**
  **measure** *Measure, default=RatioMeasure.SHARPE_RATIO*
  : The measure. The default measure is the Sharpe Ratio.

  **window** *int, default=30*
  : The window size. The default value is `30` observations.
* **Returns:**
  **dataframe** *pandas DataFrame*
  : The rolling measures.

<a id="skfolio.population.Population.set_portfolio_params"></a>

#### set_portfolio_params(\*\*params)

Set the parameters of all the portfolios.

* **Parameters:**
  **\*\*params** *Any*
  : Portfolio parameters.
* **Returns:**
  **self** *Population*
  : The Population instance.

<a id="skfolio.population.Population.sort"></a>

#### sort(\*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable
(i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort
them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

<a id="skfolio.population.Population.sort_measure"></a>

#### sort_measure(measure, reverse=False)

Sort the population by a given portfolio measure.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.

  **reverse** *bool, default=False*
  : If this is set to True, the order is reversed.
* **Returns:**
  **values** *Populations*
  : The sorted population.

<a id="skfolio.population.Population.summary"></a>

#### summary(formatted=True)

Summary of the portfolios in the population.

* **Parameters:**
  **formatted** *bool, default=True*
  : If this is set to True, the measures are formatted into rounded string with
    units.
    The default is `True`.
* **Returns:**
  **summary** *pandas DataFrame*
  : The population’s portfolios summary

### Notes

This method returns a static pandas DataFrame. For interactive exploration
(e.g., sortable/filterable/clickable tables or visual summaries), you may want
to use libraries such as `ipydatagrid`, `D-Tale`, or `Lux` in a Jupyter
environment, or `dash_table` / `streamlit.dataframe` when building dashboards.
For example, you can explore the summary with D-Tale:
`dtale.show(population.summary().T)`

# generated/skfolio.portfolio.BasePortfolio.html.md

<a id="skfolio-portfolio-baseportfolio"></a>

# skfolio.portfolio.BasePortfolio

<a id="skfolio.portfolio.BasePortfolio"></a>

### *class* skfolio.portfolio.BasePortfolio(returns, observations, name=None, tag=None, annualization_factor=None, fitness_measures=None, risk_free_rate=0.0, compounded=False, sample_weight=None, min_acceptable_return=None, value_at_risk_beta=0.95, entropic_risk_measure_theta=1.0, entropic_risk_measure_beta=0.95, cvar_beta=0.95, evar_beta=0.95, drawdown_at_risk_beta=0.95, cdar_beta=0.95, edar_beta=0.95, \*\*kwargs)

Base Portfolio class for all portfolios in skfolio.

* **Parameters:**
  **returns** *array-like of shape (n_observations,)*
  : Vector of portfolio returns.

  **observations** *array-like of shape (n_observations,)*
  : Vector of portfolio observations.

  **name** *str, optional*
  : Name of the portfolio.
    The default (`None`) is to use the object id.

  **tag** *str, optional*
  : Tag given to the portfolio.
    Tags are used to manipulate groups of Portfolios from a `Population`.

  **fitness_measures** *list[measures], optional*
  : List of fitness measures.
    Fitness measures are used to compute the portfolio fitness which is used to
    compute domination.
    The default (`None`) is to use the list [PerfMeasure.MEAN, RiskMeasure.VARIANCE]

  **annualization_factor** *float, default=252.0*
  : Factor used to annualize the below measures using the square-root rule:
    > * Annualized Mean = Mean \* factor
    > * Annualized Variance = Variance \* factor
    > * Annualized Semi-Variance = Semi-Variance \* factor
    > * Annualized Standard-Deviation = Standard-Deviation \* sqrt(factor)
    > * Annualized Semi-Deviation = Semi-Deviation \* sqrt(factor)
    > * Annualized Sharpe Ratio = Sharpe Ratio \* sqrt(factor)
    > * Annualized Sortino Ratio = Sortino Ratio \* sqrt(factor)

  **risk_free_rate** *float, default=0.0*
  : Risk-free rate. The default value is `0.0`.

  **compounded** *bool, default=False*
  : If this is set to True, cumulative returns are compounded.
    The default is `False`.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. The weights must sum to one.
    : If None, equal weights are assumed.

  **min_acceptable_return** *float, optional*
  : The minimum acceptable return used to distinguish “downside” and “upside”
    returns for the computation of lower partial moments:
    > * First Lower Partial Moment
    > * Semi-Variance
    > * Semi-Deviation
    <br/>
    The default (`None`) is to use the mean.

  **value_at_risk_beta** *float, default=0.95*
  : The confidence level of the Portfolio VaR (Value At Risk) which represents
    the return on the worst (1-beta)% observations.
    The default value is `0.95`.

  **entropic_risk_measure_theta** *float, default=1.0*
  : The risk aversion level of the Portfolio Entropic Risk Measure.
    The default value is `1.0`.

  **entropic_risk_measure_beta** *float, default=0.95*
  : The confidence level of the Portfolio Entropic Risk Measure.
    The default value is `0.95`.

  **cvar_beta** *float, default=0.95*
  : The confidence level of the Portfolio CVaR (Conditional Value at Risk) which
    represents the expected VaR on the worst (1-beta)% observations.
    The default value is `0.95`.

  **evar_beta** *float, default=0.95*
  : The confidence level of the Portfolio EVaR (Entropic Value at Risk).
    The default value is `0.95`.

  **drawdown_at_risk_beta** *float, default=0.95*
  : The confidence level of the Portfolio Drawdown at Risk (DaR) which represents
    the drawdown on the worst (1-beta)% observations.
    The default value is `0.95`.

  **cdar_beta** *float, default=0.95*
  : The confidence level of the Portfolio CDaR (Conditional Drawdown at Risk) which
    represents the expected drawdown on the worst (1-beta)% observations.
    The default value is `0.95`.

  **edar_beta** *float, default=0.95*
  : The confidence level of the Portfolio EDaR (Entropic Drawdown at Risk).
    The default value is `0.95`.
* **Attributes:**
  [`n_observations`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.n_observations) *float*
  : Number of observations.

  **mean** *float*
  : Mean of the portfolio returns.

  **annualized_mean** *float*
  : Mean annualized by $mean \times annualization\_factor$

  **mean_absolute_deviation** *float*
  : Mean Absolute Deviation. The deviation is the difference between the
    return and a minimum acceptable return (`min_acceptable_return`).

  **first_lower_partial_moment** *float*
  : First Lower Partial Moment. The First Lower Partial Moment is the mean of the
    returns below a minimum acceptable return (`min_acceptable_return`).

  **variance** *float*
  : Variance (Second Moment)

  **annualized_variance** *float*
  : Variance annualized by $variance \times annualization\_factor$

  **semi_variance** *float*
  : Semi-variance (Second Lower Partial Moment).
    The semi-variance is the variance of the returns below a minimum acceptable
    return (`min_acceptable_return`).

  **annualized_semi_variance** *float*
  : Semi-variance annualized by
    $semi\_variance \times annualization\_factor$

  **standard_deviation** *float*
  : Standard Deviation (Square Root of the Second Moment).

  **annualized_standard_deviation** *float*
  : Standard Deviation annualized by
    $standard\_deviation \times \sqrt{annualization\_factor}$

  **semi_deviation** *float*
  : Semi-deviation (Square Root of the Second Lower Partial Moment).
    The Semi Standard Deviation is the Standard Deviation of the returns below a
    minimum acceptable return (`min_acceptable_return`).

  **annualized_semi_deviation** *float*
  : Semi-deviation annualized by
    $semi\_deviation \times \sqrt{annualization\_factor}$

  **skew** *float*
  : Skew. The Skew is a measure of the lopsidedness of the distribution.
    A symmetric distribution have a Skew of zero.
    Higher Skew corresponds to longer right tail.

  **kurtosis** *float*
  : Kurtosis. It is a measure of the heaviness of the tail of the distribution.
    Higher Kurtosis corresponds to greater extremity of deviations (fat tails).

  **fourth_central_moment** *float*
  : Fourth Central Moment.

  **fourth_lower_partial_moment** *float*
  : Fourth Lower Partial Moment. It is a measure of the heaviness of the downside
    tail of the returns below a minimum acceptable return (`min_acceptable_return`).
    Higher Fourth Lower Partial Moment corresponds to greater extremity of downside
    deviations (downside fat tail).

  **worst_realization** *float*
  : Worst Realization which is the worst return.

  **value_at_risk** *float*
  : Historical VaR (Value at Risk).
    The VaR is the maximum loss at a given confidence level (`value_at_risk_beta`).

  **cvar** *float*
  : Historical CVaR (Conditional Value at Risk). The CVaR (or Tail VaR) represents
    the mean shortfall at a specified confidence level (`cvar_beta`).

  **entropic_risk_measure** *float*
  : Historical Entropic Risk Measure. It is a risk measure which depends on the
    risk aversion defined by the investor (`entropic_risk_measure_theta`) through
    the exponential utility function at a given confidence level
    (`entropic_risk_measure_beta`).

  **evar** *float*
  : Historical EVaR (Entropic Value at Risk). It is a coherent risk measure which
    is an upper bound for the VaR and the CVaR, obtained from the Chernoff
    inequality at a given confidence level (`evar_beta`). The EVaR can be
    represented by using the concept of relative entropy.

  **drawdown_at_risk** *float*
  : Historical Drawdown at Risk. It is the maximum drawdown at a given
    confidence level (`drawdown_at_risk_beta`).

  **cdar** *float*
  : Historical CDaR (Conditional Drawdown at Risk) at a given confidence level
    (`cdar_beta`).

  **max_drawdown** *float*
  : Maximum Drawdown.

  **average_drawdown** *float*
  : Average Drawdown.

  **edar** *float*
  : EDaR (Entropic Drawdown at Risk). It is a coherent risk measure which is an
    upper bound for the Drawdown at Risk and the CDaR, obtained from the Chernoff
    inequality at a given confidence level (`edar_beta`). The EDaR can be
    represented by using the concept of relative entropy.

  **ulcer_index** *float*
  : Ulcer Index

  **gini_mean_difference** *float*
  : Gini Mean Difference (GMD). It is the expected absolute difference between two
    realizations. The GMD is a superior measure of variability  for non-normal
    distribution than the variance. It can be used to form necessary conditions
    for second-degree stochastic dominance, while the variance cannot.

  **mean_absolute_deviation_ratio** *float*
  : Mean Absolute Deviation ratio.
    It is the excess mean (mean - risk_free_rate) divided by the MaD.

  **first_lower_partial_moment_ratio** *float*
  : First Lower Partial Moment ratio.
    It is the excess mean (mean - risk_free_rate) divided by the First Lower
    Partial Moment.

  **sharpe_ratio** *float*
  : Sharpe ratio.
    It is the excess mean (mean - risk_free_rate) divided by the standard-deviation.

  **annualized_sharpe_ratio** *float*
  : Sharpe ratio annualized by
    $sharpe\_ratio \times \sqrt{annualization\_factor}$.

  **sortino_ratio** *float*
  : Sortino ratio.
    It is the excess mean (mean - risk_free_rate) divided by the semi
    standard-deviation.

  **annualized_sortino_ratio** *float*
  : Sortino ratio annualized by
    $sortino\_ratio \times \sqrt{annualization\_factor}$.

  **value_at_risk_ratio** *float*
  : VaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Value at Risk
    (VaR).

  **cvar_ratio** *float*
  : CVaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Conditional Value
    at Risk (CVaR).

  **entropic_risk_measure_ratio** *float*
  : Entropic risk measure ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Entropic risk
    measure.

  **evar_ratio** *float*
  : EVaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the EVaR (Entropic
    Value at Risk).

  **worst_realization_ratio** *float*
  : Worst Realization ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Worst Realization
    (worst return).

  **drawdown_at_risk_ratio** *float*
  : Drawdown at Risk ratio.
    It is the excess mean (mean - risk_free_rate) divided by the drawdown at
    risk.

  **cdar_ratio** *float*
  : CDaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the CDaR (conditional
    drawdown at risk).

  **calmar_ratio** *float*
  : Calmar ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Maximum Drawdown.

  **average_drawdown_ratio** *float*
  : Average Drawdown ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Average Drawdown.

  **edar_ratio** *float*
  : EDaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the EDaR (Entropic
    Drawdown at Risk).

  **ulcer_index_ratio** *float*
  : Ulcer Index ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Ulcer Index.

  **gini_mean_difference_ratio** *float*
  : Gini Mean Difference ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Gini Mean
    Difference.

### Methods

| [`clear`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.clear)()                                        | Clear all measures, fitness, cumulative returns and drawdowns in slots.   |
|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| [`contribution`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.contribution)(measure[, spacing, to_df])        | Compute the contribution of each asset to a given measure.                |
| [`copy`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.copy)()                                         | Copy the Portfolio attributes without its measures values.                |
| [`dominates`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.dominates)(other[, idx])                        | Portfolio domination.                                                     |
| [`get_measure`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.get_measure)(measure)                           | Returns the value of a given measure.                                     |
| [`plot_composition`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.plot_composition)()                             | Plot the Portfolio composition.                                           |
| [`plot_contribution`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.plot_contribution)(measure[, spacing])          | Plot the contribution of each asset to a given measure.                   |
| [`plot_cumulative_returns`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.plot_cumulative_returns)([log_scale, idx])      | Plot the Portfolio cumulative returns.                                    |
| [`plot_drawdowns`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.plot_drawdowns)([idx])                          | Plot the Portfolio drawdowns.                                             |
| [`plot_returns`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.plot_returns)([idx])                            | Plot the Portfolio returns.                                               |
| [`plot_returns_distribution`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.plot_returns_distribution)([percentile_cutoff]) | Plot the Portfolio returns distribution using Gaussian KDE.               |
| [`plot_rolling_measure`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.plot_rolling_measure)([measure, window])        | Plot the measure over a rolling window.                                   |
| [`rolling_measure`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.rolling_measure)([measure, window])             | Compute the measure over a rolling window.                                |
| [`summary`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio.summary)([formatted])                           | Portfolio summary of all its measures.                                    |

<a id="skfolio.portfolio.BasePortfolio.annualization_factor"></a>

#### *property* annualization_factor

Portfolio annualization factor.

<a id="skfolio.portfolio.BasePortfolio.annualized_factor"></a>

#### *property* annualized_factor

Deprecated alias for `annualization_factor`.

<a id="skfolio.portfolio.BasePortfolio.clear"></a>

#### clear()

Clear all measures, fitness, cumulative returns and drawdowns in slots.

<a id="skfolio.portfolio.BasePortfolio.composition"></a>

#### *abstract property* composition

DataFrame of the Portfolio composition.

<a id="skfolio.portfolio.BasePortfolio.contribution"></a>

#### *abstractmethod* contribution(measure, spacing=None, to_df=True)

Compute the contribution of each asset to a given measure.

<a id="skfolio.portfolio.BasePortfolio.copy"></a>

#### copy()

Copy the Portfolio attributes without its measures values.

<a id="skfolio.portfolio.BasePortfolio.cumulative_returns"></a>

#### cumulative_returns

Portfolio cumulative returns array.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

<a id="skfolio.portfolio.BasePortfolio.cumulative_returns_df"></a>

#### *property* cumulative_returns_df

Portfolio cumulative returns Series.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

<a id="skfolio.portfolio.BasePortfolio.dominates"></a>

#### dominates(other, idx=None)

Portfolio domination.

Returns true if each objective of the current portfolio fitness is not
strictly worse than the corresponding objective of the other portfolio fitness
and at least one objective is strictly better.

* **Parameters:**
  **other** *BasePortfolio*
  : The other portfolio.

  **idx** *slice | array, optional*
  : Indexes or slice indicating on which objectives the domination is performed.
    The default (`None`) is to use all objectives.
* **Returns:**
  **value** *bool*
  : Returns True if the Portfolio dominates the other one.

<a id="skfolio.portfolio.BasePortfolio.drawdowns"></a>

#### drawdowns

Portfolio drawdowns array.

<a id="skfolio.portfolio.BasePortfolio.drawdowns_df"></a>

#### *property* drawdowns_df

Portfolio drawdowns Series.

<a id="skfolio.portfolio.BasePortfolio.fitness"></a>

#### fitness

Portfolio fitness.

<a id="skfolio.portfolio.BasePortfolio.fitness_measures"></a>

#### *property* fitness_measures

Portfolio fitness measures.

<a id="skfolio.portfolio.BasePortfolio.get_measure"></a>

#### get_measure(measure)

Returns the value of a given measure.

* **Parameters:**
  **measure** *PerfMeasure | RiskMeasure | ExtraRiskMeasure | RatioMeasure*
  : The input measure.
* **Returns:**
  **value** *float*
  : The measure value.

<a id="skfolio.portfolio.BasePortfolio.measures_df"></a>

#### *property* measures_df

DataFrame of all measures.

<a id="skfolio.portfolio.BasePortfolio.n_observations"></a>

#### *property* n_observations

Number of observations.

<a id="skfolio.portfolio.BasePortfolio.plot_composition"></a>

#### plot_composition()

Plot the Portfolio composition.

* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.BasePortfolio.plot_contribution"></a>

#### plot_contribution(measure, spacing=None)

Plot the contribution of each asset to a given measure.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$
* **Returns:**
  **plot** *Figure*
  : The plotly Figure of assets contribution to the measure.

<a id="skfolio.portfolio.BasePortfolio.plot_cumulative_returns"></a>

#### plot_cumulative_returns(log_scale=False, idx=None)

Plot the Portfolio cumulative returns.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

* **Parameters:**
  **log_scale** *bool, default=False*
  : If this is set to True, the cumulative returns are displayed with a
    logarithm scale on the y-axis. The cumulative returns must be compounded
    otherwise an exception is raised.

  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.BasePortfolio.plot_drawdowns"></a>

#### plot_drawdowns(idx=None)

Plot the Portfolio drawdowns.

* **Parameters:**
  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.BasePortfolio.plot_returns"></a>

#### plot_returns(idx=None)

Plot the Portfolio returns.

* **Parameters:**
  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.BasePortfolio.plot_returns_distribution"></a>

#### plot_returns_distribution(percentile_cutoff=None)

Plot the Portfolio returns distribution using Gaussian KDE.

* **Parameters:**
  **percentile_cutoff** *float, default=None*
  : Percentile cutoff for tail truncation (percentile), in percent.
    If a float p is provided, the distribution support is truncated at the p-th
    and (100 - p)-th percentiles.
    If None, no truncation is applied (uses full min/max of returns).
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.BasePortfolio.plot_rolling_measure"></a>

#### plot_rolling_measure(measure=Sharpe Ratio, window=30)

Plot the measure over a rolling window.

* **Parameters:**
  **measure** *Measure, default = RatioMeasure.SHARPE_RATIO*
  : The measure.

  **window** *int, default=30*
  : The window size.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.BasePortfolio.returns_df"></a>

#### *property* returns_df

Portfolio returns DataFrame.

<a id="skfolio.portfolio.BasePortfolio.rolling_measure"></a>

#### rolling_measure(measure=Sharpe Ratio, window=30)

Compute the measure over a rolling window.

* **Parameters:**
  **measure** *Measure, default=RatioMeasure.SHARPE_RATIO*
  : The measure. The default measure is the Sharpe Ratio.

  **window** *int, default=30*
  : The window size. The default value is `30` observations.
* **Returns:**
  **series** *pandas Series*
  : The rolling measure Series.

<a id="skfolio.portfolio.BasePortfolio.sample_weight"></a>

#### *property* sample_weight

Observations sample weights.

<a id="skfolio.portfolio.BasePortfolio.summary"></a>

#### summary(formatted=True)

Portfolio summary of all its measures.

* **Parameters:**
  **formatted** *bool, default=True*
  : If this is set to True, the measures are formatted into rounded string
    with units.
* **Returns:**
  **summary** *pandas Series*
  : The Portfolio summary.

# generated/skfolio.portfolio.FailedPortfolio.html.md

<a id="skfolio-portfolio-failedportfolio"></a>

# skfolio.portfolio.FailedPortfolio

<a id="skfolio.portfolio.FailedPortfolio"></a>

### *class* skfolio.portfolio.FailedPortfolio(X, name=None, tag=None, optimization_error=None, fallback_chain=None, previous_weights=None, transaction_costs=None, management_fees=None, risk_free_rate=0, annualization_factor=None, fitness_measures=None, compounded=False, weight_drift=False, sample_weight=None, min_acceptable_return=None, value_at_risk_beta=0.95, entropic_risk_measure_theta=1, entropic_risk_measure_beta=0.95, cvar_beta=0.95, evar_beta=0.95, drawdown_at_risk_beta=0.95, cdar_beta=0.95, edar_beta=0.95, \*\*kwargs)

Portfolio object returned when an optimization step fails. It acts as a sentinel
value that marks the failure and stores failure diagnostics (`optimization_error`,
`fallback_chain`).

`FailedPortfolio` preserves full API compatibility with `Portfolio` so it
can seamlessly pass through risk measures, aggregation, rolling computations and
plotting without raising. All returns, weights, composition, and derived measures
are NaN.

#### NOTE
In backtesting workflows, when an optimization estimator is configured
with `raise_on_failure=False`, a `FailedPortfolio` is returned on failed
rebalancings. This lets the process complete without raising while preserving
the full timeline for downstream analysis and diagnostics.

In a sequential evaluation, a failed period contributes no returns and no
holdings. The last successful holdings are kept unchanged and supplied as
`previous_weights` to the next fit.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
    If `X` is a DataFrame, the columns will be considered as assets names
    and the indices will be considered as observations. Otherwise, we use
    `["x0", "x1", ..., "x(n_assets - 1)"]` as asset names and
    `[0, 1, ..., n_observations]` as observations.

  **optimization_error** *str, optional*
  : Stringified error message explaining why the optimization failed.
    Propagated from the optimization estimator when `raise_on_failure=False`.
    `None` means the reason is unknown or not provided.

  **name** *str, optional*
  : Name of the portfolio. The default (`None`) is to use the object id.

  **tag** *str, optional*
  : Tag given to the portfolio. Tags are used to manipulate groups of
    Portfolios from a `Population`.

  **fallback_chain** *list[tuple[str, str]] | None, optional*
  : Sequence describing the optimization fallback attempts. Each element is
    a pair `(estimator_repr, outcome)` where:
    * `estimator_repr` is the string representation of the primary
      estimator or a fallback (e.g. `"EqualWeighted()"`,
      `"previous_weights"`).
    * `outcome` is `"success"` if that step produced a valid solution,
      otherwise the stringified error message.
    <br/>
    For successful fits without any fallback, this is `None`. When
    fallbacks are provided and the primary fails, the chain starts with
    `(primary_repr, primary_error)` and is followed by one entry per
    fallback that was attempted, ending with the first `"success"` or the
    last error if all fail. This is set by the optimization estimator and
    propagated to the resulting portfolio objects (including
    `FailedPortfolio`).

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **risk_free_rate** *float, default=0.0*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **annualization_factor** *float, default=252.0*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **fitness_measures** *list[measures], optional*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **compounded** *bool, default=False*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **weight_drift** *bool, default=False*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **sample_weight** *ndarray of shape (n_observations, ), optional*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **min_acceptable_return** *float | None, optional*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **value_at_risk_beta** *float, default=0.95*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **entropic_risk_measure_theta** *float, default=1.0*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **entropic_risk_measure_beta** *float, default=0.95*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **cvar_beta** *float, default=0.95*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **evar_beta** *float, default=0.95*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **drawdown_at_risk_beta** *float, default=0.95*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **cdar_beta** *float, default=0.95*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.

  **edar_beta** *float, default=0.95*
  : Accepted for API compatibility with `Portfolio` but not used by
    `FailedPortfolio`.
* **Attributes:**
  **X**

  [`annualization_factor`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.annualization_factor)
  : Portfolio annualization factor.

  [`annualized_factor`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.annualized_factor)
  : Deprecated alias for `annualization_factor`.

  **annualized_mean**

  **annualized_semi_deviation**

  **annualized_semi_variance**

  **annualized_sharpe_ratio**

  **annualized_sortino_ratio**

  **annualized_standard_deviation**

  **annualized_variance**

  **assets**

  **average_drawdown**

  **average_drawdown_ratio**

  **calmar_ratio**

  **cdar**

  **cdar_beta**

  **cdar_ratio**

  [`composition`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.composition)
  : DataFrame of portfolio composition (weights).

  **compounded**

  **cumulative_returns**
  : Portfolio cumulative returns array.
    Non-compounded (arithmetic) cumulative returns start at 0.
    Compounded (geometric) cumulative returns are expressed as a wealth index,
    starting at 1.0 (i.e., the value of $1 invested).

  [`cumulative_returns_df`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.cumulative_returns_df)
  : Portfolio cumulative returns Series.

  **cvar**

  **cvar_beta**

  **cvar_ratio**

  [`diversification`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.diversification)
  : Weighted average of volatility divided by the portfolio volatility.

  **drawdown_at_risk**

  **drawdown_at_risk_beta**

  **drawdown_at_risk_ratio**

  **drawdowns**
  : Portfolio drawdowns array.

  [`drawdowns_df`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.drawdowns_df)
  : Portfolio drawdowns Series.

  **edar**

  **edar_beta**

  **edar_ratio**

  [`effective_number_assets`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.effective_number_assets)
  : Computes the effective number of assets, defined as the inverse of the Herfindahl index.

  **ending_weights**

  [`ending_weights_dict`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.ending_weights_dict)
  : Dict mapping asset name to ending weight; includes zeros.

  **entropic_risk_measure**

  **entropic_risk_measure_beta**

  **entropic_risk_measure_ratio**

  **entropic_risk_measure_theta**

  **evar**

  **evar_beta**

  **evar_ratio**

  **fallback_chain**

  **first_lower_partial_moment**

  **first_lower_partial_moment_ratio**

  **fitness**
  : Portfolio fitness.

  [`fitness_measures`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.fitness_measures)
  : Portfolio fitness measures.

  **fourth_central_moment**

  **fourth_lower_partial_moment**

  **gini_mean_difference**

  **gini_mean_difference_ratio**

  **kurtosis**

  **management_fees**

  **max_drawdown**

  **mean**

  **mean_absolute_deviation**

  **mean_absolute_deviation_ratio**

  [`measures_df`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.measures_df)
  : DataFrame of all measures.

  **min_acceptable_return**

  **n_assets**

  [`n_observations`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.n_observations)
  : Number of observations.

  **name**

  **nonzero_assets**
  : Invested asset $abs(weights) > 0.001%$.

  **nonzero_assets_index**
  : Indices of invested asset $abs(weights) > 0.001%$.

  **observations**

  **optimization_error**

  **previous_weights**

  [`previous_weights_dict`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.previous_weights_dict)
  : Dict mapping asset name to previous weight; includes zeros.

  **returns**

  [`returns_df`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.returns_df)
  : Portfolio returns DataFrame.

  **risk_free_rate**

  [`sample_weight`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.sample_weight)
  : Observations sample weights.

  **semi_deviation**

  **semi_variance**

  **sharpe_ratio**

  **skew**

  **sortino_ratio**

  [`sric`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.sric)
  : Sharpe Ratio Information Criterion (SRIC).

  **standard_deviation**

  **tag**

  **total_cost**

  **total_fee**

  **transaction_costs**

  [`turnover`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.turnover)
  : Total absolute weight traded at the start of the period.

  **ulcer_index**

  **ulcer_index_ratio**

  **value_at_risk**

  **value_at_risk_beta**

  **value_at_risk_ratio**

  **variance**

  **weight_drift**

  **weights**

  [`weights_dict`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.weights_dict)
  : Dict mapping asset name to weight; includes zeros.

  [`weights_per_observation`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.weights_per_observation)
  : DataFrame of asset weights at the start of each observation.

  **worst_realization**

  **worst_realization_ratio**

### Methods

| [`clear`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.clear)()                                           | Clear all measures, fitness, cumulative returns and drawdowns in slots.                                            |
|----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| [`contribution`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.contribution)(measure[, spacing, to_df])           | Compute the contribution of each asset to a given measure.                                                         |
| [`copy`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.copy)()                                            | Copy the Portfolio attributes without its measures values.                                                         |
| [`dominates`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.dominates)(other[, idx])                           | Portfolio domination.                                                                                              |
| [`expected_returns_from_assets`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.expected_returns_from_assets)(...)                 | Compute the portfolio expected return from expected asset returns, weights, management costs and transaction fees. |
| [`get_measure`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.get_measure)(measure)                              | Returns the value of a given measure.                                                                              |
| [`get_weight`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.get_weight)(asset)                                 | Get the weight of a given asset.                                                                                   |
| [`plot_composition`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.plot_composition)()                                | Plot the Portfolio composition.                                                                                    |
| [`plot_contribution`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.plot_contribution)(measure[, spacing])             | Plot the contribution of each asset to a given measure.                                                            |
| [`plot_cumulative_returns`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.plot_cumulative_returns)([log_scale, idx])         | Plot the Portfolio cumulative returns.                                                                             |
| [`plot_drawdowns`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.plot_drawdowns)([idx])                             | Plot the Portfolio drawdowns.                                                                                      |
| [`plot_returns`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.plot_returns)([idx])                               | Plot the Portfolio returns.                                                                                        |
| [`plot_returns_distribution`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.plot_returns_distribution)([percentile_cutoff])    | Plot the Portfolio returns distribution using Gaussian KDE.                                                        |
| [`plot_rolling_measure`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.plot_rolling_measure)([measure, window])           | Plot the measure over a rolling window.                                                                            |
| [`predicted_attribution`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.predicted_attribution)(factor_model[, ...])        | Ex-ante (predicted) factor risk and performance attribution.                                                       |
| [`realized_attribution`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.realized_attribution)(factor_model[, ...])         | Realized (ex-post) factor risk and performance attribution.                                                        |
| [`rolling_measure`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.rolling_measure)([measure, window])                | Compute the measure over a rolling window.                                                                         |
| [`rolling_realized_attribution`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.rolling_realized_attribution)(factor_model[, ...]) | Rolling realized (ex-post) factor risk and performance attribution.                                                |
| [`summary`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.summary)([formatted])                              | Portfolio summary of all its measures.                                                                             |
| [`variance_from_assets`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio.variance_from_assets)(assets_covariance)           | Compute the Portfolio variance expectation from the assets covariance and weights.                                 |

### Notes

All performance, risk, and contribution measures are computed from NaN
returns and NaN weights in a `FailedPortfolio`. As a result, these
parameters do not affect the outcome: NaNs are carried over to metrics,
contributions, plots, and rolling computations. This class exists solely to
preserve API and type compatibility while signaling a failed optimization.

<a id="skfolio.portfolio.FailedPortfolio.annualization_factor"></a>

#### *property* annualization_factor

Portfolio annualization factor.

<a id="skfolio.portfolio.FailedPortfolio.annualized_factor"></a>

#### *property* annualized_factor

Deprecated alias for `annualization_factor`.

<a id="skfolio.portfolio.FailedPortfolio.clear"></a>

#### clear()

Clear all measures, fitness, cumulative returns and drawdowns in slots.

<a id="skfolio.portfolio.FailedPortfolio.composition"></a>

#### *property* composition

DataFrame of portfolio composition (weights). Rows with zero weights are
filtered out. Use `weights_dict` to access all weights, including zeros.

<a id="skfolio.portfolio.FailedPortfolio.contribution"></a>

#### contribution(measure, spacing=None, to_df=False)

Compute the contribution of each asset to a given measure.

With `weight_drift=True`, the contributions are finite-difference sensitivities
to the target weights. Because drifted returns are nonlinear in the target
weights, the contributions are not guaranteed to sum exactly to the measure.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$

  **to_df** *bool, default=False*
  : If set to True, a DataFrame with asset names in index is returned,
    otherwise a numpy array is returned. When a DataFrame is returned, the
    values are sorted in descending order and assets with zero weights are
    removed.
* **Returns:**
  **values** *numpy array of shape (n_assets,) or DataFrame*
  : The measure contribution of each asset.

<a id="skfolio.portfolio.FailedPortfolio.copy"></a>

#### copy()

Copy the Portfolio attributes without its measures values.

<a id="skfolio.portfolio.FailedPortfolio.cumulative_returns"></a>

#### cumulative_returns

Portfolio cumulative returns array.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

<a id="skfolio.portfolio.FailedPortfolio.cumulative_returns_df"></a>

#### *property* cumulative_returns_df

Portfolio cumulative returns Series.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

<a id="skfolio.portfolio.FailedPortfolio.diversification"></a>

#### *property* diversification

Weighted average of volatility divided by the portfolio volatility.

<a id="skfolio.portfolio.FailedPortfolio.dominates"></a>

#### dominates(other, idx=None)

Portfolio domination.

Returns true if each objective of the current portfolio fitness is not
strictly worse than the corresponding objective of the other portfolio fitness
and at least one objective is strictly better.

* **Parameters:**
  **other** *BasePortfolio*
  : The other portfolio.

  **idx** *slice | array, optional*
  : Indexes or slice indicating on which objectives the domination is performed.
    The default (`None`) is to use all objectives.
* **Returns:**
  **value** *bool*
  : Returns True if the Portfolio dominates the other one.

<a id="skfolio.portfolio.FailedPortfolio.drawdowns"></a>

#### drawdowns

Portfolio drawdowns array.

<a id="skfolio.portfolio.FailedPortfolio.drawdowns_df"></a>

#### *property* drawdowns_df

Portfolio drawdowns Series.

<a id="skfolio.portfolio.FailedPortfolio.effective_number_assets"></a>

#### *property* effective_number_assets

Computes the effective number of assets, defined as the inverse of the
Herfindahl index.

$$
N_{eff} = \frac{1}{\Vert w \Vert_{2}^{2}}

$$

It quantifies portfolio concentration, with a higher value indicating a more
diversified portfolio.

* **Returns:**
  **value** *float*
  : Effective number of assets.

### References

* <a id='r5e81914d8cb5-1'>**[1]**</a> “Banking and Financial Institutions Law in a Nutshell”. Lovett, William Anthony (1988)

<a id="skfolio.portfolio.FailedPortfolio.ending_weights_dict"></a>

#### *property* ending_weights_dict

Dict mapping asset name to ending weight; includes zeros.

<a id="skfolio.portfolio.FailedPortfolio.expected_returns_from_assets"></a>

#### expected_returns_from_assets(assets_expected_returns)

Compute the portfolio expected return from expected asset returns,
weights, management costs and transaction fees.

* **Parameters:**
  **assets_expected_returns** *ndarray of shape (n_assets,)*
  : The vector of expected asset returns.
* **Returns:**
  **value** *float*
  : The portfolio expected return.

<a id="skfolio.portfolio.FailedPortfolio.fitness"></a>

#### fitness

Portfolio fitness.

<a id="skfolio.portfolio.FailedPortfolio.fitness_measures"></a>

#### *property* fitness_measures

Portfolio fitness measures.

<a id="skfolio.portfolio.FailedPortfolio.get_measure"></a>

#### get_measure(measure)

Returns the value of a given measure.

* **Parameters:**
  **measure** *PerfMeasure | RiskMeasure | ExtraRiskMeasure | RatioMeasure*
  : The input measure.
* **Returns:**
  **value** *float*
  : The measure value.

<a id="skfolio.portfolio.FailedPortfolio.get_weight"></a>

#### get_weight(asset)

Get the weight of a given asset.

* **Parameters:**
  **asset** *str*
  : Name of the asset.
* **Returns:**
  **weight** *float*
  : Weight of the asset.

<a id="skfolio.portfolio.FailedPortfolio.measures_df"></a>

#### *property* measures_df

DataFrame of all measures.

<a id="skfolio.portfolio.FailedPortfolio.n_observations"></a>

#### *property* n_observations

Number of observations.

<a id="skfolio.portfolio.FailedPortfolio.nonzero_assets"></a>

#### nonzero_assets

Invested asset $abs(weights) > 0.001%$.

<a id="skfolio.portfolio.FailedPortfolio.nonzero_assets_index"></a>

#### nonzero_assets_index

Indices of invested asset $abs(weights) > 0.001%$.

<a id="skfolio.portfolio.FailedPortfolio.plot_composition"></a>

#### plot_composition()

Plot the Portfolio composition.

* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.FailedPortfolio.plot_contribution"></a>

#### plot_contribution(measure, spacing=None)

Plot the contribution of each asset to a given measure.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$
* **Returns:**
  **plot** *Figure*
  : The plotly Figure of assets contribution to the measure.

<a id="skfolio.portfolio.FailedPortfolio.plot_cumulative_returns"></a>

#### plot_cumulative_returns(log_scale=False, idx=None)

Plot the Portfolio cumulative returns.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

* **Parameters:**
  **log_scale** *bool, default=False*
  : If this is set to True, the cumulative returns are displayed with a
    logarithm scale on the y-axis. The cumulative returns must be compounded
    otherwise an exception is raised.

  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.FailedPortfolio.plot_drawdowns"></a>

#### plot_drawdowns(idx=None)

Plot the Portfolio drawdowns.

* **Parameters:**
  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.FailedPortfolio.plot_returns"></a>

#### plot_returns(idx=None)

Plot the Portfolio returns.

* **Parameters:**
  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.FailedPortfolio.plot_returns_distribution"></a>

#### plot_returns_distribution(percentile_cutoff=None)

Plot the Portfolio returns distribution using Gaussian KDE.

* **Parameters:**
  **percentile_cutoff** *float, default=None*
  : Percentile cutoff for tail truncation (percentile), in percent.
    If a float p is provided, the distribution support is truncated at the p-th
    and (100 - p)-th percentiles.
    If None, no truncation is applied (uses full min/max of returns).
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.FailedPortfolio.plot_rolling_measure"></a>

#### plot_rolling_measure(measure=Sharpe Ratio, window=30)

Plot the measure over a rolling window.

* **Parameters:**
  **measure** *Measure, default = RatioMeasure.SHARPE_RATIO*
  : The measure.

  **window** *int, default=30*
  : The window size.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.FailedPortfolio.predicted_attribution"></a>

#### predicted_attribution(factor_model, compute_asset_breakdowns=True)

Ex-ante (predicted) factor risk and performance attribution.

Decomposes the portfolio’s predicted risk and expected return into contributions
from individual factors and an idiosyncratic component using the factor model’s
latest forecast estimates (`loading_matrix`, `factor_covariance`,
`idio_covariance`, `factor_mu`, `idio_mu`).

The annualization scaling uses `self.annualization_factor`.

Predicted attribution uses only these latest forecast estimates, so no
observation alignment is required. The `factor_model` may therefore cover a
different observation window than the portfolio.

The portfolio may hold a subset of the assets covered by the factor model and
weights are zero-filled for missing assets.

See [`predicted_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.predicted_factor_attribution.html.md#skfolio.attribution.predicted_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **factor_model** *FactorModel*
  : Factor model whose latest forecast estimates are used. Every asset in
    `self.assets` must appear in `factor_model.asset_names`.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset systematic/idiosyncratic decomposition. Set to
    `False` for faster computation when only portfolio-level results are needed.
* **Returns:**
  **attribution** *Attribution*
  : Component-level, factor-level, and optionally asset-level attribution
    results.
* **Raises:**
  ValueError
  : If the portfolio is a failed portfolio or if it holds assets not covered by
    the factor model.

<a id="skfolio.portfolio.FailedPortfolio.previous_weights_dict"></a>

#### *property* previous_weights_dict

Dict mapping asset name to previous weight; includes zeros.

<a id="skfolio.portfolio.FailedPortfolio.realized_attribution"></a>

#### realized_attribution(factor_model, compute_asset_breakdowns=True, compute_uncertainty=True)

Realized (ex-post) factor risk and performance attribution.

Decomposes the portfolio’s realized risk and return into contributions from
individual factors and an idiosyncratic component using actual historical factor
returns, exposures, and residuals.

The annualization scaling uses `self.annualization_factor`.

Realized attribution uses the target weights when `weight_drift=False` and the
weights held during each observation when `weight_drift=True`.

Realized attribution is computed on the overlapping observation window between
the portfolio and the factor model. Portfolio observations outside the factor
model window, commonly caused by factor-model warmup or exposure lag, are
excluded. Missing portfolio observations inside the overlapping window raise
`ValueError`. Time-varying exposures follow the as-of indexing convention
described in
[`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution):
when `exposure_lag > 0`, exposures known at observation
$t-\ell$ are aligned with returns at observation $t$.

The portfolio may hold a subset of the assets covered by the factor model and
weights are zero-filled for missing assets.

See [`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **factor_model** *FactorModel*
  : Factor model containing time-varying fields (`factor_returns`, `exposures`,
    `idio_returns`) that overlap with the portfolio’s observation period. Every
    asset in `self.assets` must appear in `factor_model.asset_names`.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset systematic/idiosyncratic attribution. Set to
    `False` for faster computation when only portfolio-level results are needed.

  **compute_uncertainty** *bool, default=True*
  : If `True`, compute attribution uncertainty (standard errors on the factor
    and idiosyncratic mean-return split).
* **Returns:**
  **attribution** *Attribution*
  : Component-level, factor-level, and optionally asset-level attribution
    results.
* **Raises:**
  ValueError
  : If the portfolio is a failed portfolio, if it holds assets not covered by
    the factor model, if no portfolio observations overlap with the factor model
    or if portfolio observations are missing inside the overlapping window.

<a id="skfolio.portfolio.FailedPortfolio.returns_df"></a>

#### *property* returns_df

Portfolio returns DataFrame.

<a id="skfolio.portfolio.FailedPortfolio.rolling_measure"></a>

#### rolling_measure(measure=Sharpe Ratio, window=30)

Compute the measure over a rolling window.

* **Parameters:**
  **measure** *Measure, default=RatioMeasure.SHARPE_RATIO*
  : The measure. The default measure is the Sharpe Ratio.

  **window** *int, default=30*
  : The window size. The default value is `30` observations.
* **Returns:**
  **series** *pandas Series*
  : The rolling measure Series.

<a id="skfolio.portfolio.FailedPortfolio.rolling_realized_attribution"></a>

#### rolling_realized_attribution(factor_model, window_size=60, step=21, compute_asset_breakdowns=True, compute_asset_factor_contribs=False, compute_uncertainty=True)

Rolling realized (ex-post) factor risk and performance attribution.

Computes [`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution)
over rolling windows, returning an [`Attribution`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution)
where all numeric fields carry an additional leading dimension for the number
of windows.

Rolling realized attribution is computed on the overlapping observation window
between the portfolio and the factor model. Portfolio observations outside the
factor model window, commonly caused by factor-model warmup or exposure lag, are
excluded. Missing portfolio observations inside the overlapping window raise
`ValueError`. Time-varying exposures follow the as-of indexing convention
described in
[`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution).

Each rolling window uses the target weights when `weight_drift=False` and the
weights held during its observations when `weight_drift=True`.

The portfolio may hold a subset of the assets covered by the factor model and
weights are zero-filled for missing assets.

See [`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **factor_model** *FactorModel*
  : Factor model containing time-varying fields that overlap with the
    portfolio’s observation period.

  **window_size** *int, default=60*
  : Number of effective return periods in each rolling window.

  **step** *int, default=21*
  : Number of observations to advance between consecutive windows. The default
    of 21 produces approximately monthly output for daily data.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset attribution for each window.

  **compute_asset_factor_contribs** *bool, default=False*
  : If `True`, compute asset-factor matrix for each window.

  **compute_uncertainty** *bool, default=True*
  : If `True`, compute per-window attribution uncertainty.
* **Returns:**
  **attribution** *Attribution*
  : Rolling attribution results.
* **Raises:**
  ValueError
  : If the portfolio is a failed portfolio, if it holds assets not covered by
    the factor model, if no portfolio observations overlap with the factor model
    or if `window_size` exceeds the number of overlapping observations.

<a id="skfolio.portfolio.FailedPortfolio.sample_weight"></a>

#### *property* sample_weight

Observations sample weights.

<a id="skfolio.portfolio.FailedPortfolio.sric"></a>

#### *property* sric

Sharpe Ratio Information Criterion (SRIC).

It is an unbiased estimator of the Sharpe Ratio adjusting for both sources of
bias which are noise fit and estimation error [[1]](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#r9dee37131fea-1).

### References

* <a id='r9dee37131fea-1'>**[1]**</a> “Noise Fit, Estimation Error and a Sharpe Information Criterion”, Dirk Paulsen (2019)

<a id="skfolio.portfolio.FailedPortfolio.summary"></a>

#### summary(formatted=True)

Portfolio summary of all its measures.

* **Parameters:**
  **formatted** *bool, default=True*
  : If this is set to True, the measures are formatted into rounded string
    with units.
* **Returns:**
  **summary** *series*
  : Portfolio summary.

<a id="skfolio.portfolio.FailedPortfolio.turnover"></a>

#### *property* turnover

Total absolute weight traded at the start of the period.

In a sequential evaluation, `previous_weights` come from the last successful
Portfolio. With `weight_drift=False`, target turnover compares successive
target allocations. With `weight_drift=True`, executed turnover compares the
previous period’s ending weights with the new target allocation. When
`previous_weights` is None, it defaults to zero. Turnover includes the full
absolute weight of positions in assets absent from `X`.

<a id="skfolio.portfolio.FailedPortfolio.variance_from_assets"></a>

#### variance_from_assets(assets_covariance)

Compute the Portfolio variance expectation from the assets covariance and
weights.

* **Parameters:**
  **assets_covariance** *ndarray of shape (n_assets,n_assets)*
  : The matrix of assets covariance expectation.
* **Returns:**
  **value** *float*
  : The Portfolio variance from the assets covariance.

<a id="skfolio.portfolio.FailedPortfolio.weights_dict"></a>

#### *property* weights_dict

Dict mapping asset name to weight; includes zeros.

<a id="skfolio.portfolio.FailedPortfolio.weights_per_observation"></a>

#### *property* weights_per_observation

DataFrame of asset weights at the start of each observation.

With `weight_drift=False`, every row contains the target `weights`. With
`weight_drift=True`, each row incorporates the effect of preceding asset
returns. `ending_weights` contains the weights immediately after the final
observation.

# generated/skfolio.portfolio.MultiPeriodPortfolio.html.md

<a id="skfolio-portfolio-multiperiodportfolio"></a>

# skfolio.portfolio.MultiPeriodPortfolio

<a id="skfolio.portfolio.MultiPeriodPortfolio"></a>

### *class* skfolio.portfolio.MultiPeriodPortfolio(portfolios=None, name=None, tag=None, risk_free_rate=0, annualization_factor=None, fitness_measures=None, compounded=False, sample_weight=None, min_acceptable_return=None, value_at_risk_beta=0.95, entropic_risk_measure_theta=1, entropic_risk_measure_beta=0.95, cvar_beta=0.95, evar_beta=0.95, drawdown_at_risk_beta=0.95, cdar_beta=0.95, edar_beta=0.95, check_observations_order=False, \*\*kwargs)

Multi-Period Portfolio class.

A Multi-Period Portfolio is composed of a list of [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio).

* **Parameters:**
  **portfolios** *list[Portfolio], optional*
  : A list of [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio). The default (`None`) is to initialize with an
    empty list.

  **name** *str, optional*
  : Name of the multi-period portfolio.
    The default (`None`) is to use the object id.

  **tag** *str, optional*
  : Tag given to the multi-period portfolio.
    Tags are used to manipulate groups of portfolios from a `Population`.

  **fitness_measures** *list[measures], optional*
  : List of fitness measures.
    Fitness measures are used to compute the portfolio fitness which is used to
    compute domination.
    The default (`None`) is to use the list [PerfMeasure.MEAN, RiskMeasure.VARIANCE]

  **annualization_factor** *float, default=252.0*
  : Factor used to annualize the below measures using the square-root rule:
    > * Annualized Mean = Mean \* factor
    > * Annualized Variance = Variance \* factor
    > * Annualized Semi-Variance = Semi-Variance \* factor
    > * Annualized Standard-Deviation = Standard-Deviation \* sqrt(factor)
    > * Annualized Semi-Deviation = Semi-Deviation \* sqrt(factor)
    > * Annualized Sharpe Ratio = Sharpe Ratio \* sqrt(factor)
    > * Annualized Sortino Ratio = Sortino Ratio \* sqrt(factor)

  **risk_free_rate** *float, default=0.0*
  : Risk-free rate. The default value is `0.0`.

  **compounded** *bool, default=False*
  : If this is set to True, cumulative returns are compounded.
    The default is `False`.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.

  **min_acceptable_return** *float, optional*
  : The minimum acceptable return used to distinguish “downside” and “upside”
    returns for the computation of lower partial moments:
    > * First Lower Partial Moment
    > * Semi-Variance
    > * Semi-Deviation
    <br/>
    The default (`None`) is to use the mean.

  **value_at_risk_beta** *float, default=0.95*
  : The confidence level of the portfolio VaR (Value At Risk) which represents
    the return on the worst (1-beta)% observations.
    The default value is `0.95`.

  **entropic_risk_measure_theta** *float, default=1.0*
  : The risk aversion level of the portfolio Entropic Risk Measure.
    The default value is `1.0`.

  **entropic_risk_measure_beta** *float, default=0.95*
  : The confidence level of the portfolio Entropic Risk Measure.
    The default value is `0.95`.

  **cvar_beta** *float, default=0.95*
  : The confidence level of the portfolio CVaR (Conditional Value at Risk) which
    represents the expected VaR on the worst (1-beta)% observations.
    The default value is `0.95`.

  **evar_beta** *float, default=0.95*
  : The confidence level of the portfolio EVaR (Entropic Value at Risk).
    The default value is `0.95`.

  **drawdown_at_risk_beta** *float, default=0.95*
  : The confidence level of the portfolio Drawdown at Risk (DaR) which represents
    the drawdown on the worst (1-beta)% observations.
    The default value is `0.95`.

  **cdar_beta** *float, default=0.95*
  : The confidence level of the portfolio CDaR (Conditional Drawdown at Risk) which
    represents the expected drawdown on the worst (1-beta)% observations.
    The default value is `0.95`.

  **edar_beta** *float, default=0.95*
  : The confidence level of the portfolio EDaR (Entropic Drawdown at Risk).
    The default value is `0.95`.

  **check_observations_order** *bool, default=False*
  : If this is set to True, and if the list of portfolios is not chronologically
    sorted, an error is raised. The chronological order is determined by comparing
    the first and last observations of each portfolio.
    The default is `False`.
* **Attributes:**
  [`n_observations`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.n_observations) *float*
  : Number of observations.

  **mean** *float*
  : Mean of the portfolio returns.

  **annualized_mean** *float*
  : Mean annualized by $mean \times annualization\_factor$

  **mean_absolute_deviation** *float*
  : Mean Absolute Deviation. The deviation is the difference between the
    return and a minimum acceptable return (`min_acceptable_return`).

  **first_lower_partial_moment** *float*
  : First Lower Partial Moment. The First Lower Partial Moment is the mean of the
    returns below a minimum acceptable return (`min_acceptable_return`).

  **variance** *float*
  : Variance (Second Moment)

  **annualized_variance** *float*
  : Variance annualized by $variance \times annualization\_factor$

  **semi_variance** *float*
  : Semi-variance (Second Lower Partial Moment).
    The semi-variance is the variance of the returns below a minimum acceptable
    return (`min_acceptable_return`).

  **annualized_semi_variance** *float*
  : Semi-variance annualized by
    $semi\_variance \times annualization\_factor$

  **standard_deviation** *float*
  : Standard Deviation (Square Root of the Second Moment).

  **annualized_standard_deviation** *float*
  : Standard Deviation annualized by
    $standard\_deviation \times \sqrt{annualization\_factor}$

  **semi_deviation** *float*
  : Semi-deviation (Square Root of the Second Lower Partial Moment).
    The Semi Standard Deviation is the Standard Deviation of the returns below a
    minimum acceptable return (`min_acceptable_return`).

  **annualized_semi_deviation** *float*
  : Semi-deviation annualized by
    $semi\_deviation \times \sqrt{annualization\_factor}$

  **skew** *float*
  : Skew. The Skew is a measure of the lopsidedness of the distribution.
    A symmetric distribution have a Skew of zero.
    Higher Skew corresponds to longer right tail.

  **kurtosis** *float*
  : Kurtosis. It is a measure of the heaviness of the tail of the distribution.
    Higher Kurtosis corresponds to greater extremity of deviations (fat tails).

  **fourth_central_moment** *float*
  : Fourth Central Moment.

  **fourth_lower_partial_moment** *float*
  : Fourth Lower Partial Moment. It is a measure of the heaviness of the downside
    tail of the returns below a minimum acceptable return (`min_acceptable_return`).
    Higher Fourth Lower Partial Moment corresponds to greater extremity of downside
    deviations (downside fat tail).

  **worst_realization** *float*
  : Worst Realization which is the worst return.

  **value_at_risk** *float*
  : Historical VaR (Value at Risk).
    The VaR is the maximum loss at a given confidence level (`value_at_risk_beta`).

  **cvar** *float*
  : Historical CVaR (Conditional Value at Risk). The CVaR (or Tail VaR) represents
    the mean shortfall at a specified confidence level (`cvar_beta`).

  **entropic_risk_measure** *float*
  : Historical Entropic Risk Measure. It is a risk measure which depends on the
    risk aversion defined by the investor (`entropic_risk_measure_theta`) through
    the exponential utility function at a given confidence level
    (`entropic_risk_measure_beta`).

  **evar** *float*
  : Historical EVaR (Entropic Value at Risk). It is a coherent risk measure which
    is an upper bound for the VaR and the CVaR, obtained from the Chernoff
    inequality at a given confidence level (`evar_beta`). The EVaR can be
    represented by using the concept of relative entropy.

  **drawdown_at_risk** *float*
  : Historical Drawdown at Risk. It is the maximum drawdown at a given
    confidence level (`drawdown_at_risk_beta`).

  **cdar** *float*
  : Historical CDaR (Conditional Drawdown at Risk) at a given confidence level
    (`cdar_beta`).

  **max_drawdown** *float*
  : Maximum Drawdown.

  **average_drawdown** *float*
  : Average Drawdown.

  **edar** *float*
  : EDaR (Entropic Drawdown at Risk). It is a coherent risk measure which is an
    upper bound for the Drawdown at Risk and the CDaR, obtained from the Chernoff
    inequality at a given confidence level (`edar_beta`). The EDaR can be
    represented by using the concept of relative entropy.

  **ulcer_index** *float*
  : Ulcer Index

  **gini_mean_difference** *float*
  : Gini Mean Difference (GMD). It is the expected absolute difference between two
    realizations. The GMD is a superior measure of variability  for non-normal
    distribution than the variance. It can be used to form necessary conditions
    for second-degree stochastic dominance, while the variance cannot.

  **mean_absolute_deviation_ratio** *float*
  : Mean Absolute Deviation ratio.
    It is the excess mean (mean - risk_free_rate) divided by the MaD.

  **first_lower_partial_moment_ratio** *float*
  : First Lower Partial Moment ratio.
    It is the excess mean (mean - risk_free_rate) divided by the First Lower
    Partial Moment.

  **sharpe_ratio** *float*
  : Sharpe ratio.
    It is the excess mean (mean - risk_free_rate) divided by the standard-deviation.

  **annualized_sharpe_ratio** *float*
  : Sharpe ratio annualized by
    $sharpe\_ratio \times \sqrt{annualization\_factor}$.

  **sortino_ratio** *float*
  : Sortino ratio.
    It is the excess mean (mean - risk_free_rate) divided by the semi
    standard-deviation.

  **annualized_sortino_ratio** *float*
  : Sortino ratio annualized by
    $sortino\_ratio \times \sqrt{annualization\_factor}$.

  **value_at_risk_ratio** *float*
  : VaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Value at Risk
    (VaR).

  **cvar_ratio** *float*
  : CVaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Conditional Value
    at Risk (CVaR).

  **entropic_risk_measure_ratio** *float*
  : Entropic risk measure ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Entropic risk
    measure.

  **evar_ratio** *float*
  : EVaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the EVaR (Entropic
    Value at Risk).

  **worst_realization_ratio** *float*
  : Worst Realization ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Worst Realization
    (worst return).

  **drawdown_at_risk_ratio** *float*
  : Drawdown at Risk ratio.
    It is the excess mean (mean - risk_free_rate) divided by the drawdown at
    risk.

  **cdar_ratio** *float*
  : CDaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the CDaR (conditional
    drawdown at risk).

  **calmar_ratio** *float*
  : Calmar ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Maximum Drawdown.

  **average_drawdown_ratio** *float*
  : Average Drawdown ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Average Drawdown.

  **edar_ratio** *float*
  : EDaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the EDaR (Entropic
    Drawdown at Risk).

  **ulcer_index_ratio** *float*
  : Ulcer Index ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Ulcer Index.

  **gini_mean_difference_ratio** *float*
  : Gini Mean Difference ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Gini Mean
    Difference.

### Methods

| [`append`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.append)(portfolio)                                 | Append a Portfolio to the Portfolio list.                                     |
|----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| [`clear`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.clear)()                                           | Clear all measures, fitness, cumulative returns and drawdowns in slots.       |
| [`contribution`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.contribution)(measure[, spacing, to_df])           | Compute the contribution of each asset to a given measure for each portfolio. |
| [`copy`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.copy)()                                            | Copy the Portfolio attributes without its measures values.                    |
| [`dominates`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.dominates)(other[, idx])                           | Portfolio domination.                                                         |
| [`get_measure`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.get_measure)(measure)                              | Returns the value of a given measure.                                         |
| [`plot_composition`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_composition)()                                | Plot the Portfolio composition.                                               |
| [`plot_contribution`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_contribution)(measure[, spacing])             | Plot the contribution of each asset to a given measure.                       |
| [`plot_cumulative_returns`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_cumulative_returns)([log_scale, idx])         | Plot the Portfolio cumulative returns.                                        |
| [`plot_drawdowns`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_drawdowns)([idx])                             | Plot the Portfolio drawdowns.                                                 |
| [`plot_long_short_exposure`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_long_short_exposure)()                        | Plot long, short, net and gross exposure per observation.                     |
| [`plot_returns`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_returns)([idx])                               | Plot the Portfolio returns.                                                   |
| [`plot_returns_distribution`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_returns_distribution)([percentile_cutoff])    | Plot the Portfolio returns distribution using Gaussian KDE.                   |
| [`plot_rolling_measure`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_rolling_measure)([measure, window])           | Plot the measure over a rolling window.                                       |
| [`plot_weights_per_observation`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_weights_per_observation)()                    | Plot portfolio weights per observation as a stacked-area chart.               |
| [`predicted_attribution`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.predicted_attribution)(factor_model[, ...])        | Ex-ante (predicted) factor attribution for the last portfolio.                |
| [`realized_attribution`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.realized_attribution)(factor_model[, ...])         | Realized (ex-post) factor attribution aggregated over all periods.            |
| [`rolling_measure`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.rolling_measure)([measure, window])                | Compute the measure over a rolling window.                                    |
| [`rolling_realized_attribution`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.rolling_realized_attribution)(factor_model[, ...]) | Rolling realized (ex-post) factor attribution over all periods.               |
| [`summary`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.summary)([formatted])                              | Portfolio summary of all its measures.                                        |

<a id="skfolio.portfolio.MultiPeriodPortfolio.annualization_factor"></a>

#### *property* annualization_factor

Portfolio annualization factor.

<a id="skfolio.portfolio.MultiPeriodPortfolio.annualized_factor"></a>

#### *property* annualized_factor

Deprecated alias for `annualization_factor`.

<a id="skfolio.portfolio.MultiPeriodPortfolio.append"></a>

#### append(portfolio)

Append a Portfolio to the Portfolio list.

* **Parameters:**
  **portfolio** *Portfolio*
  : The Portfolio to append.

<a id="skfolio.portfolio.MultiPeriodPortfolio.assets"></a>

#### *property* assets

List of assets names in each Portfolio.

<a id="skfolio.portfolio.MultiPeriodPortfolio.clear"></a>

#### clear()

Clear all measures, fitness, cumulative returns and drawdowns in slots.

<a id="skfolio.portfolio.MultiPeriodPortfolio.composition"></a>

#### *property* composition

DataFrame of the Portfolio composition.

<a id="skfolio.portfolio.MultiPeriodPortfolio.contribution"></a>

#### contribution(measure, spacing=None, to_df=True)

Compute the contribution of each asset to a given measure for each
portfolio.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$

  **to_df** *bool, default=False*
  : If this is set to True, a DataFrame with asset names in index and portfolio
    names in columns is returned, otherwise a list of numpy array is returned.
    When a DataFrame is returned, the assets with zero weights are removed.
* **Returns:**
  **values** *list of numpy array of shape (n_assets,) for each portfolio or a DataFrame*
  : The measure contribution of each asset for each portfolio.

<a id="skfolio.portfolio.MultiPeriodPortfolio.copy"></a>

#### copy()

Copy the Portfolio attributes without its measures values.

<a id="skfolio.portfolio.MultiPeriodPortfolio.cumulative_returns"></a>

#### cumulative_returns

Portfolio cumulative returns array.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

<a id="skfolio.portfolio.MultiPeriodPortfolio.cumulative_returns_df"></a>

#### *property* cumulative_returns_df

Portfolio cumulative returns Series.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

<a id="skfolio.portfolio.MultiPeriodPortfolio.dominates"></a>

#### dominates(other, idx=None)

Portfolio domination.

Returns true if each objective of the current portfolio fitness is not
strictly worse than the corresponding objective of the other portfolio fitness
and at least one objective is strictly better.

* **Parameters:**
  **other** *BasePortfolio*
  : The other portfolio.

  **idx** *slice | array, optional*
  : Indexes or slice indicating on which objectives the domination is performed.
    The default (`None`) is to use all objectives.
* **Returns:**
  **value** *bool*
  : Returns True if the Portfolio dominates the other one.

<a id="skfolio.portfolio.MultiPeriodPortfolio.drawdowns"></a>

#### drawdowns

Portfolio drawdowns array.

<a id="skfolio.portfolio.MultiPeriodPortfolio.drawdowns_df"></a>

#### *property* drawdowns_df

Portfolio drawdowns Series.

<a id="skfolio.portfolio.MultiPeriodPortfolio.ending_weights_dict"></a>

#### *property* ending_weights_dict

Map each Portfolio name to its weights at the end of its observation window.

For each Portfolio, the nested dictionary contains its `ending_weights_dict`,
as determined by that Portfolio’s `weight_drift` setting. Failed portfolios map
every asset to NaN. In a sequential evaluation, the next optimization uses the
last successful ending weights as `previous_weights`.

<a id="skfolio.portfolio.MultiPeriodPortfolio.failed_portfolios"></a>

#### *property* failed_portfolios

Return the list of `FailedPortfolio` in the multi-period portfolio.

<a id="skfolio.portfolio.MultiPeriodPortfolio.fallback_portfolios"></a>

#### *property* fallback_portfolios

Return the list of portfolios in the multi-period portfolio that used a
fallback (i.e., have a non-None `fallback_chain`). This includes
`FailedPortfolio` instances when fallbacks were attempted.

<a id="skfolio.portfolio.MultiPeriodPortfolio.fitness"></a>

#### fitness

Portfolio fitness.

<a id="skfolio.portfolio.MultiPeriodPortfolio.fitness_measures"></a>

#### *property* fitness_measures

Portfolio fitness measures.

<a id="skfolio.portfolio.MultiPeriodPortfolio.get_measure"></a>

#### get_measure(measure)

Returns the value of a given measure.

* **Parameters:**
  **measure** *PerfMeasure | RiskMeasure | ExtraRiskMeasure | RatioMeasure*
  : The input measure.
* **Returns:**
  **value** *float*
  : The measure value.

<a id="skfolio.portfolio.MultiPeriodPortfolio.long_short_exposure"></a>

#### *property* long_short_exposure

DataFrame of long, short, net and gross exposure per observation.

The long exposure is the sum of positive weights. The short exposure is the
sum of negative weights. Net exposure is the sum of all weights and gross
exposure is the sum of absolute weights.

<a id="skfolio.portfolio.MultiPeriodPortfolio.measures_df"></a>

#### *property* measures_df

DataFrame of all measures.

<a id="skfolio.portfolio.MultiPeriodPortfolio.n_failed_portfolios"></a>

#### *property* n_failed_portfolios

Number of `FailedPortfolio` in the multi-period portfolio.

<a id="skfolio.portfolio.MultiPeriodPortfolio.n_fallback_portfolios"></a>

#### *property* n_fallback_portfolios

Number of portfolios in the multi-period portfolio with a fallback.

<a id="skfolio.portfolio.MultiPeriodPortfolio.n_observations"></a>

#### *property* n_observations

Number of observations.

<a id="skfolio.portfolio.MultiPeriodPortfolio.plot_composition"></a>

#### plot_composition()

Plot the Portfolio composition.

* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.MultiPeriodPortfolio.plot_contribution"></a>

#### plot_contribution(measure, spacing=None)

Plot the contribution of each asset to a given measure.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$
* **Returns:**
  **plot** *Figure*
  : The plotly Figure of assets contribution to the measure.

<a id="skfolio.portfolio.MultiPeriodPortfolio.plot_cumulative_returns"></a>

#### plot_cumulative_returns(log_scale=False, idx=None)

Plot the Portfolio cumulative returns.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

* **Parameters:**
  **log_scale** *bool, default=False*
  : If this is set to True, the cumulative returns are displayed with a
    logarithm scale on the y-axis. The cumulative returns must be compounded
    otherwise an exception is raised.

  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.MultiPeriodPortfolio.plot_drawdowns"></a>

#### plot_drawdowns(idx=None)

Plot the Portfolio drawdowns.

* **Parameters:**
  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.MultiPeriodPortfolio.plot_long_short_exposure"></a>

#### plot_long_short_exposure()

Plot long, short, net and gross exposure per observation.

* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.MultiPeriodPortfolio.plot_returns"></a>

#### plot_returns(idx=None)

Plot the Portfolio returns.

* **Parameters:**
  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.MultiPeriodPortfolio.plot_returns_distribution"></a>

#### plot_returns_distribution(percentile_cutoff=None)

Plot the Portfolio returns distribution using Gaussian KDE.

* **Parameters:**
  **percentile_cutoff** *float, default=None*
  : Percentile cutoff for tail truncation (percentile), in percent.
    If a float p is provided, the distribution support is truncated at the p-th
    and (100 - p)-th percentiles.
    If None, no truncation is applied (uses full min/max of returns).
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.MultiPeriodPortfolio.plot_rolling_measure"></a>

#### plot_rolling_measure(measure=Sharpe Ratio, window=30)

Plot the measure over a rolling window.

* **Parameters:**
  **measure** *Measure, default = RatioMeasure.SHARPE_RATIO*
  : The measure.

  **window** *int, default=30*
  : The window size.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.MultiPeriodPortfolio.plot_weights_per_observation"></a>

#### plot_weights_per_observation()

Plot portfolio weights per observation as a stacked-area chart.

This shows the composition of the portfolio over time, with each asset’s weight
stacked to illustrate how allocations shift.

* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.MultiPeriodPortfolio.portfolios"></a>

#### *property* portfolios

List of portfolios composing the mutli-period portfolio.

<a id="skfolio.portfolio.MultiPeriodPortfolio.predicted_attribution"></a>

#### predicted_attribution(factor_model, compute_asset_breakdowns=True)

Ex-ante (predicted) factor attribution for the last portfolio.

Returns the predicted attribution for the most recent (last) portfolio in the
walk-forward sequence, which represents the current allocation.

The last portfolio’s weights are aligned to `factor_model.asset_names`: assets
not in the portfolio receive zero weight, and assets not in the factor model
raise an error.

Predicted attribution uses the factor model’s latest forecast estimates
(`loading_matrix`, `factor_covariance`, `idio_covariance`, `factor_mu`,
`idio_mu`), so no observation alignment is performed.

The annualization scaling uses `self.annualization_factor`.

See [`predicted_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.predicted_factor_attribution.html.md#skfolio.attribution.predicted_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **factor_model** *FactorModel*
  : Factor model whose latest forecast estimates are used. Every asset
    held by the last portfolio must appear in `factor_model.asset_names`.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset systematic/idiosyncratic decomposition. Set to
    `False` for faster computation when only portfolio-level results are needed.
* **Returns:**
  **attribution** *Attribution*
  : Component-level, factor-level, and optionally asset-level attribution
    results for the last portfolio.
* **Raises:**
  ValueError
  : If the multi-period portfolio is empty, the last portfolio is a
    [`FailedPortfolio`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio), or it holds assets not covered by the factor model.

<a id="skfolio.portfolio.MultiPeriodPortfolio.previous_weights_dict"></a>

#### *property* previous_weights_dict

Dictionary mapping Portfolio name to its previous asset weight allocation.

<a id="skfolio.portfolio.MultiPeriodPortfolio.realized_attribution"></a>

#### realized_attribution(factor_model, compute_asset_breakdowns=True, compute_uncertainty=True)

Realized (ex-post) factor attribution aggregated over all periods.

Builds a time-varying weight matrix from the non-failed child portfolios and
computes a single realized attribution over the full walk-forward observation
window.

Each child portfolio’s static weight vector is broadcast across its
observations. Failed portfolios are skipped (their observations and returns are
excluded).

Weights are aligned to `factor_model.asset_names`: assets not in a given
portfolio receive zero weight, and assets not in the factor model raise an
error.

Realized attribution is computed on the overlapping observation window between
the multi-period portfolio and the factor model. Portfolio observations outside
the factor model window, commonly caused by factor-model warmup or exposure lag,
are excluded. Missing portfolio observations inside the overlapping window raise
`ValueError`. Time-varying exposures follow the as-of indexing convention
described in
[`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution):
when `exposure_lag > 0`, exposures known at observation $t-\ell$ are
aligned with returns at observation $t$.

The annualization scaling uses `self.annualization_factor`.

See [`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution) for
the full mathematical description.

* **Parameters:**
  **factor_model** *FactorModel*
  : Factor model containing time-varying fields (`factor_returns`, `exposures`,
    `idio_returns`) that overlap with the observation periods of non-failed
    child portfolios. Every asset held by any child portfolio must appear in
    `factor_model.asset_names`.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset systematic/idiosyncratic attribution. Set to
    `False` for faster computation when only portfolio-level results are needed.

  **compute_uncertainty** *bool, default=True*
  : If `True`, compute attribution uncertainty (standard errors on the factor
    and idiosyncratic mean-return split).
* **Returns:**
  **attribution** *Attribution*
  : Component-level, factor-level, and optionally asset-level attribution
    results aggregated over all non-failed periods.
* **Raises:**
  ValueError
  : If the multi-period portfolio is empty, all child portfolios are failed, any
    child portfolio holds assets not covered by the factor model, no portfolio
    observations overlap with the factor model, or portfolio observations are
    missing inside the overlapping window.

<a id="skfolio.portfolio.MultiPeriodPortfolio.returns_df"></a>

#### *property* returns_df

Portfolio returns DataFrame.

<a id="skfolio.portfolio.MultiPeriodPortfolio.rolling_measure"></a>

#### rolling_measure(measure=Sharpe Ratio, window=30)

Compute the measure over a rolling window.

* **Parameters:**
  **measure** *Measure, default=RatioMeasure.SHARPE_RATIO*
  : The measure. The default measure is the Sharpe Ratio.

  **window** *int, default=30*
  : The window size. The default value is `30` observations.
* **Returns:**
  **series** *pandas Series*
  : The rolling measure Series.

<a id="skfolio.portfolio.MultiPeriodPortfolio.rolling_realized_attribution"></a>

#### rolling_realized_attribution(factor_model, window_size=60, step=21, compute_asset_breakdowns=True, compute_asset_factor_contribs=False, compute_uncertainty=True)

Rolling realized (ex-post) factor attribution over all periods.

Builds a time-varying weight matrix from the non-failed child portfolios and
computes rolling realized attribution over the full walk-forward observation
window.

Each child portfolio’s static weight vector is broadcast across its
observations. Failed portfolios are skipped.

Rolling realized attribution is computed on the overlapping observation window
between the multi-period portfolio and the factor model. Portfolio observations
outside the factor model window, commonly caused by factor-model warmup or
exposure lag, are excluded. Missing portfolio observations inside the
overlapping window raise `ValueError`. Time-varying exposures follow the as-of
indexing convention described in
[`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution).

See [`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **factor_model** *FactorModel*
  : Factor model containing time-varying fields that overlap with the
    observation periods of non-failed child portfolios.

  **window_size** *int, default=60*
  : Number of effective return periods in each rolling window.

  **step** *int, default=21*
  : Number of observations to advance between consecutive windows. The default
    of 21 produces approximately monthly output for daily data.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset attribution for each window.

  **compute_asset_factor_contribs** *bool, default=False*
  : If `True`, compute asset-factor matrix for each window.

  **compute_uncertainty** *bool, default=True*
  : If `True`, compute per-window attribution uncertainty.
* **Returns:**
  **attribution** *Attribution*
  : Rolling attribution results with an additional leading dimension for the
    number of windows.
* **Raises:**
  ValueError
  : If the multi-period portfolio is empty, all child portfolios are failed, any
    child portfolio holds assets not covered by the factor model, no portfolio
    observations overlap with the factor model, or `window_size` exceeds the
    number of overlapping observations.

<a id="skfolio.portfolio.MultiPeriodPortfolio.sample_weight"></a>

#### *property* sample_weight

Observations sample weights.

<a id="skfolio.portfolio.MultiPeriodPortfolio.summary"></a>

#### summary(formatted=True)

Portfolio summary of all its measures.

* **Parameters:**
  **formatted** *bool, default=True*
  : If this is set to True, the measures are formatted into rounded string with
    units.
* **Returns:**
  **summary** *series*
  : Portfolio summary of all its measures.

<a id="skfolio.portfolio.MultiPeriodPortfolio.turnover"></a>

#### *property* turnover

Turnover of each Portfolio, indexed by its first observation.

In a sequentially evaluated path, `previous_weights` come from the last
successful Portfolio. With `weight_drift=False`, they are its target weights,
so each value measures target turnover. With `weight_drift=True`, they include
the intervening drift, so each value measures executed turnover. Failed
portfolios have a NaN value. Empty portfolios are omitted because they have
no observation to use as a rebalancing date.

<a id="skfolio.portfolio.MultiPeriodPortfolio.weights_dict"></a>

#### *property* weights_dict

Dictionary mapping each Portfolio name to its asset weight allocation.

<a id="skfolio.portfolio.MultiPeriodPortfolio.weights_per_observation"></a>

#### *property* weights_per_observation

DataFrame of the Portfolio weights per observation.

# generated/skfolio.portfolio.Portfolio.html.md

<a id="skfolio-portfolio-portfolio"></a>

# skfolio.portfolio.Portfolio

<a id="skfolio.portfolio.Portfolio"></a>

### *class* skfolio.portfolio.Portfolio(X, weights, previous_weights=None, transaction_costs=None, management_fees=None, risk_free_rate=0, name=None, tag=None, annualization_factor=None, fitness_measures=None, compounded=False, weight_drift=False, sample_weight=None, min_acceptable_return=None, value_at_risk_beta=0.95, entropic_risk_measure_theta=1, entropic_risk_measure_beta=0.95, cvar_beta=0.95, evar_beta=0.95, drawdown_at_risk_beta=0.95, cdar_beta=0.95, edar_beta=0.95, fallback_chain=None, \*\*kwargs)

Portfolio class.

`Portfolio` is returned by the `predict` method of Optimization estimators.

By default, each observation is evaluated at the target `weights`. Portfolio
returns are the dot product of those weights and the asset returns, minus
transaction costs and management fees. This constant-weight convention
(`weight_drift=False`) is consistent with the optimizer’s linear portfolio return
definition and evaluates allocation skill independently of subsequent changes in
weights caused by relative asset returns.

With `weight_drift=True`, the portfolio starts at the target weights and holds the
resulting positions throughout the observation window of `X`. Position values
change with asset returns, so portfolio weights evolve with the relative
performance of the assets. Combined with `compounded=True`, this produces a
compounded wealth path for evaluating realized capital growth and other
path-dependent quantities.

`weight_drift` changes the observation-level portfolio return series, while
`compounded` changes how that series is accumulated. See
[Backtesting and Evaluation](https://skfolio.org/user_guide/backtesting_and_evaluation.html.md#backtesting-and-evaluation).

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets.
    If `X` is a DataFrame or another array containers that implements ‘columns’
    and ‘index’, the columns will be considered as assets names and the
    indices will be considered as observations.
    Otherwise, we use `["x0", "x1", ..., "x(n_assets - 1)"]` as asset names
    and `[0, 1, ..., n_observations]` as observations.
    `NaN` values are treated as zero returns for the portfolio return
    computation (e.g. non-investable assets, delisted assets or trading
    holidays), while the original `X` is preserved.

  **weights** *array-like of shape (n_assets,) | dict[str, float]*
  : Portfolio weights.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset weight) and `X` must be a DataFrame with assets names
    in columns.

  **transaction_costs** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Linear transaction costs of the assets. The Portfolio total transaction cost
    is:
    $$
    total\_cost = \sum_{i=1}^{N} c_{i} \times |w_{i} - w\_prev_{i}|
    <br/>
    $$
    <br/>
    with $c_{i}$ the transaction cost of asset i, $w_{i}$ its weight
    and $w\_prev_{i}$ its previous weight (defined in `previous_weights`).
    The float $total\_cost$ is used in the portfolio returns:
    $$
    ptf\_returns = R \cdot w - total\_cost
    <br/>
    $$
    <br/>
    with $R$ the matrix of assets returns and $w$ the vector of
    assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset weight) and `X` must be a DataFrame with assets names
    in columns.
    The default (`None`) means no transaction costs.
    <br/>
    #### WARNING
    To be consistent with the optimization problems, the periodicity of the
    transaction costs must match the periodicity of the
    returns `X`. For example, if `X` is composed of **daily** returns,
    the `transaction_costs` need to be expressed in **daily** transaction costs.

  **management_fees** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Linear management fees of the assets. The Portfolio total management cost
    is:
    $$
    total\_fee = \sum_{i=1}^{N} f_{i} \times w_{i}
    <br/>
    $$
    <br/>
    with $f_{i}$ the management fee of asset i and $w_{i}$ its weight.
    The float $total\_fee$ is used in the portfolio returns:
    $$
    ptf\_returns = R \cdot w - total\_fee
    <br/>
    $$
    <br/>
    with $R$ the matrix of assets returns and $w$ the vector of
    assets weights.
    <br/>
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset weight) and `X` must be a DataFrame with assets names
    in columns.
    The default (`None`) means no management fees.
    <br/>
    #### WARNING
    To be consistent with the optimization problems, the periodicity of the
    management fees must match the periodicity of the
    returns `X`. For example, if `X` is composed of **daily** returns,
    the `management_fees` need to be expressed in **daily** fees.

  **previous_weights** *float | dict[str, float] | array-like of shape (n_assets, ), optional*
  : Previous portfolio weights.
    Previous weights are used to compute turnover and transaction costs.
    For named positions in assets absent from `X`, these calculations assume
    full liquidation. To specify their transaction costs, `transaction_costs`
    must be a single rate applied to all assets or a dictionary keyed by asset name.
    If a float is provided, it is applied to each asset.
    If a dictionary is provided, its (key/value) pair must be the
    (asset name/asset previous weight) and `X` must be a DataFrame with assets names
    in columns.
    The default (`None`) means no previous weights.

  **name** *str, optional*
  : Name of the portfolio.
    The default (`None`) is to use the object id.

  **tag** *str, optional*
  : Tag given to the portfolio.
    Tags are used to manipulate groups of Portfolios from a `Population`.

  **fitness_measures** *list[measures], optional*
  : List of fitness measures.
    Fitness measures are used to compute the portfolio fitness which is used to
    compute domination.
    The default (`None`) is to use the list [PerfMeasure.MEAN, RiskMeasure.VARIANCE]

  **annualization_factor** *float, default=252.0*
  : Factor used to annualize the below measures using the square-root rule:
    > * Annualized Mean = Mean \* factor
    > * Annualized Variance = Variance \* factor
    > * Annualized Semi-Variance = Semi-Variance \* factor
    > * Annualized Standard-Deviation = Standard-Deviation \* sqrt(factor)
    > * Annualized Semi-Deviation = Semi-Deviation \* sqrt(factor)
    > * Annualized Sharpe Ratio = Sharpe Ratio \* sqrt(factor)
    > * Annualized Sortino Ratio = Sortino Ratio \* sqrt(factor)

  **risk_free_rate** *float, default=0.0*
  : Risk-free rate. The default value is `0.0`.

  **compounded** *bool, default=False*
  : If `True`, cumulative returns are compounded.
    The default is `False`.

  **weight_drift** *bool, default=False*
  : If `True`, the portfolio starts at the target `weights` and the
    weights used for subsequent observations evolve with asset returns following
    the self-financing identity
    $u_{t+1} = u_t \circ (1 + r_t) / (1 + u_t \cdot r_t)$.
    Drift accumulates over the entire window of `X`, and the implicit cash position
    $1 - \sum_i w_i$ earns zero. The same transaction-cost and management-fee
    formulas are used with either setting. With the default (`False`), every
    observation is evaluated at the target `weights`. This attribute is read-only.
    See [Backtesting and Evaluation](https://skfolio.org/user_guide/backtesting_and_evaluation.html.md#backtesting-and-evaluation).

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If None, equal weights are assumed.

  **min_acceptable_return** *float, optional*
  : The minimum acceptable return used to distinguish “downside” and “upside”
    returns for the computation of lower partial moments:
    > * First Lower Partial Moment
    > * Semi-Variance
    > * Semi-Deviation
    <br/>
    The default (`None`) is to use the mean.

  **value_at_risk_beta** *float, default=0.95*
  : The confidence level of the Portfolio VaR (Value At Risk) which represents
    the return on the worst (1-beta)% observations.
    The default value is `0.95`.

  **entropic_risk_measure_theta** *float, default=1.0*
  : The risk aversion level of the Portfolio Entropic Risk Measure.
    The default value is `1.0`.

  **entropic_risk_measure_beta** *float, default=0.95*
  : The confidence level of the Portfolio Entropic Risk Measure.
    The default value is `0.95`.

  **cvar_beta** *float, default=0.95*
  : The confidence level of the Portfolio CVaR (Conditional Value at Risk) which
    represents the expected VaR on the worst (1-beta)% observations.
    The default value is `0.95`.

  **evar_beta** *float, default=0.95*
  : The confidence level of the Portfolio EVaR (Entropic Value at Risk).
    The default value is `0.95`.

  **drawdown_at_risk_beta** *float, default=0.95*
  : The confidence level of the Portfolio Drawdown at Risk (DaR) which represents
    the drawdown on the worst (1-beta)% observations.
    The default value is `0.95`.

  **cdar_beta** *float, default=0.95*
  : The confidence level of the Portfolio CDaR (Conditional Drawdown at Risk) which
    represents the expected drawdown on the worst (1-beta)% observations.
    The default value is `0.95`.

  **edar_beta** *float, default=0.95*
  : The confidence level of the Portfolio EDaR (Entropic Drawdown at Risk).
    The default value is `0.95`.

  **fallback_chain** *list[tuple[str, str]] | None, optional*
  : Sequence describing the optimization fallback attempts. Each element is
    a pair `(estimator_repr, outcome)` where:
    * `estimator_repr` is the string representation of the primary
      estimator or a fallback (e.g. `"EqualWeighted()"`,
      `"previous_weights"`).
    * `outcome` is `"success"` if that step produced a valid solution,
      otherwise the stringified error message.
    <br/>
    For successful fits without any fallback, this is `None`. When
    fallbacks are provided and the primary fails, the chain starts with
    `(primary_repr, primary_error)` and is followed by one entry per
    fallback that was attempted, ending with the first `"success"` or the
    last error if all fail. This is set by the optimization estimator and
    propagated to the resulting portfolio.
* **Attributes:**
  [`n_observations`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.n_observations) *float*
  : Number of observations.

  **mean** *float*
  : Mean of the portfolio returns.

  **annualized_mean** *float*
  : Mean annualized by $mean \times annualization\_factor$

  **mean_absolute_deviation** *float*
  : Mean Absolute Deviation. The deviation is the difference between the
    return and a minimum acceptable return (`min_acceptable_return`).

  **first_lower_partial_moment** *float*
  : First Lower Partial Moment. The First Lower Partial Moment is the mean of the
    returns below a minimum acceptable return (`min_acceptable_return`).

  **variance** *float*
  : Variance (Second Moment)

  **annualized_variance** *float*
  : Variance annualized by $variance \times annualization\_factor$

  **semi_variance** *float*
  : Semi-variance (Second Lower Partial Moment).
    The semi-variance is the variance of the returns below a minimum acceptable
    return (`min_acceptable_return`).

  **annualized_semi_variance** *float*
  : Semi-variance annualized by
    $semi\_variance \times annualization\_factor$

  **standard_deviation** *float*
  : Standard Deviation (Square Root of the Second Moment).

  **annualized_standard_deviation** *float*
  : Standard Deviation annualized by
    $standard\_deviation \times \sqrt{annualization\_factor}$

  **semi_deviation** *float*
  : Semi-deviation (Square Root of the Second Lower Partial Moment).
    The Semi Standard Deviation is the Standard Deviation of the returns below a
    minimum acceptable return (`min_acceptable_return`).

  **annualized_semi_deviation** *float*
  : Semi-deviation annualized by
    $semi\_deviation \times \sqrt{annualization\_factor}$

  **skew** *float*
  : Skew. The Skew is a measure of the lopsidedness of the distribution.
    A symmetric distribution have a Skew of zero.
    Higher Skew corresponds to longer right tail.

  **kurtosis** *float*
  : Kurtosis. It is a measure of the heaviness of the tail of the distribution.
    Higher Kurtosis corresponds to greater extremity of deviations (fat tails).

  **fourth_central_moment** *float*
  : Fourth Central Moment.

  **fourth_lower_partial_moment** *float*
  : Fourth Lower Partial Moment. It is a measure of the heaviness of the downside
    tail of the returns below a minimum acceptable return (`min_acceptable_return`).
    Higher Fourth Lower Partial Moment corresponds to greater extremity of downside
    deviations (downside fat tail).

  **worst_realization** *float*
  : Worst Realization which is the worst return.

  **value_at_risk** *float*
  : Historical VaR (Value at Risk).
    The VaR is the maximum loss at a given confidence level (`value_at_risk_beta`).

  **cvar** *float*
  : Historical CVaR (Conditional Value at Risk). The CVaR (or Tail VaR) represents
    the mean shortfall at a specified confidence level (`cvar_beta`).

  **entropic_risk_measure** *float*
  : Historical Entropic Risk Measure. It is a risk measure which depends on the
    risk aversion defined by the investor (`entropic_risk_measure_theta`) through
    the exponential utility function at a given confidence level
    (`entropic_risk_measure_beta`).

  **evar** *float*
  : Historical EVaR (Entropic Value at Risk). It is a coherent risk measure which
    is an upper bound for the VaR and the CVaR, obtained from the Chernoff
    inequality at a given confidence level (`evar_beta`). The EVaR can be
    represented by using the concept of relative entropy.

  **drawdown_at_risk** *float*
  : Historical Drawdown at Risk. It is the maximum drawdown at a given
    confidence level (`drawdown_at_risk_beta`).

  **cdar** *float*
  : Historical CDaR (Conditional Drawdown at Risk) at a given confidence level
    (`cdar_beta`).

  **max_drawdown** *float*
  : Maximum Drawdown.

  **average_drawdown** *float*
  : Average Drawdown.

  **edar** *float*
  : EDaR (Entropic Drawdown at Risk). It is a coherent risk measure which is an
    upper bound for the Drawdown at Risk and the CDaR, obtained from the Chernoff
    inequality at a given confidence level (`edar_beta`). The EDaR can be
    represented by using the concept of relative entropy.

  **ulcer_index** *float*
  : Ulcer Index

  **gini_mean_difference** *float*
  : Gini Mean Difference (GMD). It is the expected absolute difference between two
    realizations. The GMD is a superior measure of variability  for non-normal
    distribution than the variance. It can be used to form necessary conditions
    for second-degree stochastic dominance, while the variance cannot.

  **mean_absolute_deviation_ratio** *float*
  : Mean Absolute Deviation ratio.
    It is the excess mean (mean - risk_free_rate) divided by the MaD.

  **first_lower_partial_moment_ratio** *float*
  : First Lower Partial Moment ratio.
    It is the excess mean (mean - risk_free_rate) divided by the First Lower
    Partial Moment.

  **sharpe_ratio** *float*
  : Sharpe ratio.
    It is the excess mean (mean - risk_free_rate) divided by the standard-deviation.

  **annualized_sharpe_ratio** *float*
  : Sharpe ratio annualized by
    $sharpe\_ratio \times \sqrt{annualization\_factor}$.

  **sortino_ratio** *float*
  : Sortino ratio.
    It is the excess mean (mean - risk_free_rate) divided by the semi
    standard-deviation.

  **annualized_sortino_ratio** *float*
  : Sortino ratio annualized by
    $sortino\_ratio \times \sqrt{annualization\_factor}$.

  **value_at_risk_ratio** *float*
  : VaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Value at Risk
    (VaR).

  **cvar_ratio** *float*
  : CVaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Conditional Value
    at Risk (CVaR).

  **entropic_risk_measure_ratio** *float*
  : Entropic risk measure ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Entropic risk
    measure.

  **evar_ratio** *float*
  : EVaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the EVaR (Entropic
    Value at Risk).

  **worst_realization_ratio** *float*
  : Worst Realization ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Worst Realization
    (worst return).

  **drawdown_at_risk_ratio** *float*
  : Drawdown at Risk ratio.
    It is the excess mean (mean - risk_free_rate) divided by the drawdown at
    risk.

  **cdar_ratio** *float*
  : CDaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the CDaR (conditional
    drawdown at risk).

  **calmar_ratio** *float*
  : Calmar ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Maximum Drawdown.

  **average_drawdown_ratio** *float*
  : Average Drawdown ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Average Drawdown.

  **edar_ratio** *float*
  : EDaR ratio.
    It is the excess mean (mean - risk_free_rate) divided by the EDaR (Entropic
    Drawdown at Risk).

  **ulcer_index_ratio** *float*
  : Ulcer Index ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Ulcer Index.

  **gini_mean_difference_ratio** *float*
  : Gini Mean Difference ratio.
    It is the excess mean (mean - risk_free_rate) divided by the Gini Mean
    Difference.

  **ending_weights** *ndarray of shape (n_assets,)*
  : Asset weights immediately after the final observation. With
    `weight_drift=False`, they equal the target `weights`. With
    `weight_drift=True`, they reflect the effect of asset returns through the final
    observation. They are calculated before transaction costs and management fees.
    In a sequential evaluation, the `ending_weights` of a successful `Portfolio`
    are used as `previous_weights` for the next optimization. A `FailedPortfolio`
    contains only NaN ending weights.

  [`turnover`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.turnover) *float*
  : Total absolute weight traded at the start of the period.

### Methods

| [`clear`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.clear)()                                           | Clear all measures, fitness, cumulative returns and drawdowns in slots.                                            |
|----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| [`contribution`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.contribution)(measure[, spacing, to_df])           | Compute the contribution of each asset to a given measure.                                                         |
| [`copy`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.copy)()                                            | Copy the Portfolio attributes without its measures values.                                                         |
| [`dominates`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.dominates)(other[, idx])                           | Portfolio domination.                                                                                              |
| [`expected_returns_from_assets`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.expected_returns_from_assets)(...)                 | Compute the portfolio expected return from expected asset returns, weights, management costs and transaction fees. |
| [`get_measure`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.get_measure)(measure)                              | Returns the value of a given measure.                                                                              |
| [`get_weight`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.get_weight)(asset)                                 | Get the weight of a given asset.                                                                                   |
| [`plot_composition`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.plot_composition)()                                | Plot the Portfolio composition.                                                                                    |
| [`plot_contribution`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.plot_contribution)(measure[, spacing])             | Plot the contribution of each asset to a given measure.                                                            |
| [`plot_cumulative_returns`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.plot_cumulative_returns)([log_scale, idx])         | Plot the Portfolio cumulative returns.                                                                             |
| [`plot_drawdowns`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.plot_drawdowns)([idx])                             | Plot the Portfolio drawdowns.                                                                                      |
| [`plot_returns`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.plot_returns)([idx])                               | Plot the Portfolio returns.                                                                                        |
| [`plot_returns_distribution`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.plot_returns_distribution)([percentile_cutoff])    | Plot the Portfolio returns distribution using Gaussian KDE.                                                        |
| [`plot_rolling_measure`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.plot_rolling_measure)([measure, window])           | Plot the measure over a rolling window.                                                                            |
| [`predicted_attribution`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.predicted_attribution)(factor_model[, ...])        | Ex-ante (predicted) factor risk and performance attribution.                                                       |
| [`realized_attribution`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.realized_attribution)(factor_model[, ...])         | Realized (ex-post) factor risk and performance attribution.                                                        |
| [`rolling_measure`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.rolling_measure)([measure, window])                | Compute the measure over a rolling window.                                                                         |
| [`rolling_realized_attribution`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.rolling_realized_attribution)(factor_model[, ...]) | Rolling realized (ex-post) factor risk and performance attribution.                                                |
| [`summary`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.summary)([formatted])                              | Portfolio summary of all its measures.                                                                             |
| [`variance_from_assets`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio.variance_from_assets)(assets_covariance)           | Compute the Portfolio variance expectation from the assets covariance and weights.                                 |

<a id="skfolio.portfolio.Portfolio.annualization_factor"></a>

#### *property* annualization_factor

Portfolio annualization factor.

<a id="skfolio.portfolio.Portfolio.annualized_factor"></a>

#### *property* annualized_factor

Deprecated alias for `annualization_factor`.

<a id="skfolio.portfolio.Portfolio.clear"></a>

#### clear()

Clear all measures, fitness, cumulative returns and drawdowns in slots.

<a id="skfolio.portfolio.Portfolio.composition"></a>

#### *property* composition

DataFrame of portfolio composition (weights). Rows with zero weights are
filtered out. Use `weights_dict` to access all weights, including zeros.

<a id="skfolio.portfolio.Portfolio.contribution"></a>

#### contribution(measure, spacing=None, to_df=False)

Compute the contribution of each asset to a given measure.

With `weight_drift=True`, the contributions are finite-difference sensitivities
to the target weights. Because drifted returns are nonlinear in the target
weights, the contributions are not guaranteed to sum exactly to the measure.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$

  **to_df** *bool, default=False*
  : If set to True, a DataFrame with asset names in index is returned,
    otherwise a numpy array is returned. When a DataFrame is returned, the
    values are sorted in descending order and assets with zero weights are
    removed.
* **Returns:**
  **values** *numpy array of shape (n_assets,) or DataFrame*
  : The measure contribution of each asset.

<a id="skfolio.portfolio.Portfolio.copy"></a>

#### copy()

Copy the Portfolio attributes without its measures values.

<a id="skfolio.portfolio.Portfolio.cumulative_returns"></a>

#### cumulative_returns

Portfolio cumulative returns array.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

<a id="skfolio.portfolio.Portfolio.cumulative_returns_df"></a>

#### *property* cumulative_returns_df

Portfolio cumulative returns Series.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

<a id="skfolio.portfolio.Portfolio.diversification"></a>

#### *property* diversification

Weighted average of volatility divided by the portfolio volatility.

<a id="skfolio.portfolio.Portfolio.dominates"></a>

#### dominates(other, idx=None)

Portfolio domination.

Returns true if each objective of the current portfolio fitness is not
strictly worse than the corresponding objective of the other portfolio fitness
and at least one objective is strictly better.

* **Parameters:**
  **other** *BasePortfolio*
  : The other portfolio.

  **idx** *slice | array, optional*
  : Indexes or slice indicating on which objectives the domination is performed.
    The default (`None`) is to use all objectives.
* **Returns:**
  **value** *bool*
  : Returns True if the Portfolio dominates the other one.

<a id="skfolio.portfolio.Portfolio.drawdowns"></a>

#### drawdowns

Portfolio drawdowns array.

<a id="skfolio.portfolio.Portfolio.drawdowns_df"></a>

#### *property* drawdowns_df

Portfolio drawdowns Series.

<a id="skfolio.portfolio.Portfolio.effective_number_assets"></a>

#### *property* effective_number_assets

Computes the effective number of assets, defined as the inverse of the
Herfindahl index.

$$
N_{eff} = \frac{1}{\Vert w \Vert_{2}^{2}}

$$

It quantifies portfolio concentration, with a higher value indicating a more
diversified portfolio.

* **Returns:**
  **value** *float*
  : Effective number of assets.

### References

* <a id='r52de0fa26f70-1'>**[1]**</a> “Banking and Financial Institutions Law in a Nutshell”. Lovett, William Anthony (1988)

<a id="skfolio.portfolio.Portfolio.ending_weights_dict"></a>

#### *property* ending_weights_dict

Dict mapping asset name to ending weight; includes zeros.

<a id="skfolio.portfolio.Portfolio.expected_returns_from_assets"></a>

#### expected_returns_from_assets(assets_expected_returns)

Compute the portfolio expected return from expected asset returns,
weights, management costs and transaction fees.

* **Parameters:**
  **assets_expected_returns** *ndarray of shape (n_assets,)*
  : The vector of expected asset returns.
* **Returns:**
  **value** *float*
  : The portfolio expected return.

<a id="skfolio.portfolio.Portfolio.fitness"></a>

#### fitness

Portfolio fitness.

<a id="skfolio.portfolio.Portfolio.fitness_measures"></a>

#### *property* fitness_measures

Portfolio fitness measures.

<a id="skfolio.portfolio.Portfolio.get_measure"></a>

#### get_measure(measure)

Returns the value of a given measure.

* **Parameters:**
  **measure** *PerfMeasure | RiskMeasure | ExtraRiskMeasure | RatioMeasure*
  : The input measure.
* **Returns:**
  **value** *float*
  : The measure value.

<a id="skfolio.portfolio.Portfolio.get_weight"></a>

#### get_weight(asset)

Get the weight of a given asset.

* **Parameters:**
  **asset** *str*
  : Name of the asset.
* **Returns:**
  **weight** *float*
  : Weight of the asset.

<a id="skfolio.portfolio.Portfolio.measures_df"></a>

#### *property* measures_df

DataFrame of all measures.

<a id="skfolio.portfolio.Portfolio.n_observations"></a>

#### *property* n_observations

Number of observations.

<a id="skfolio.portfolio.Portfolio.nonzero_assets"></a>

#### nonzero_assets

Invested asset $abs(weights) > 0.001%$.

<a id="skfolio.portfolio.Portfolio.nonzero_assets_index"></a>

#### nonzero_assets_index

Indices of invested asset $abs(weights) > 0.001%$.

<a id="skfolio.portfolio.Portfolio.plot_composition"></a>

#### plot_composition()

Plot the Portfolio composition.

* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.Portfolio.plot_contribution"></a>

#### plot_contribution(measure, spacing=None)

Plot the contribution of each asset to a given measure.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$
* **Returns:**
  **plot** *Figure*
  : The plotly Figure of assets contribution to the measure.

<a id="skfolio.portfolio.Portfolio.plot_cumulative_returns"></a>

#### plot_cumulative_returns(log_scale=False, idx=None)

Plot the Portfolio cumulative returns.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

* **Parameters:**
  **log_scale** *bool, default=False*
  : If this is set to True, the cumulative returns are displayed with a
    logarithm scale on the y-axis. The cumulative returns must be compounded
    otherwise an exception is raised.

  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.Portfolio.plot_drawdowns"></a>

#### plot_drawdowns(idx=None)

Plot the Portfolio drawdowns.

* **Parameters:**
  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.portfolio.Portfolio.plot_returns"></a>

#### plot_returns(idx=None)

Plot the Portfolio returns.

* **Parameters:**
  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to plot all observations.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.Portfolio.plot_returns_distribution"></a>

#### plot_returns_distribution(percentile_cutoff=None)

Plot the Portfolio returns distribution using Gaussian KDE.

* **Parameters:**
  **percentile_cutoff** *float, default=None*
  : Percentile cutoff for tail truncation (percentile), in percent.
    If a float p is provided, the distribution support is truncated at the p-th
    and (100 - p)-th percentiles.
    If None, no truncation is applied (uses full min/max of returns).
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.Portfolio.plot_rolling_measure"></a>

#### plot_rolling_measure(measure=Sharpe Ratio, window=30)

Plot the measure over a rolling window.

* **Parameters:**
  **measure** *Measure, default = RatioMeasure.SHARPE_RATIO*
  : The measure.

  **window** *int, default=30*
  : The window size.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.portfolio.Portfolio.predicted_attribution"></a>

#### predicted_attribution(factor_model, compute_asset_breakdowns=True)

Ex-ante (predicted) factor risk and performance attribution.

Decomposes the portfolio’s predicted risk and expected return into contributions
from individual factors and an idiosyncratic component using the factor model’s
latest forecast estimates (`loading_matrix`, `factor_covariance`,
`idio_covariance`, `factor_mu`, `idio_mu`).

The annualization scaling uses `self.annualization_factor`.

Predicted attribution uses only these latest forecast estimates, so no
observation alignment is required. The `factor_model` may therefore cover a
different observation window than the portfolio.

The portfolio may hold a subset of the assets covered by the factor model and
weights are zero-filled for missing assets.

See [`predicted_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.predicted_factor_attribution.html.md#skfolio.attribution.predicted_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **factor_model** *FactorModel*
  : Factor model whose latest forecast estimates are used. Every asset in
    `self.assets` must appear in `factor_model.asset_names`.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset systematic/idiosyncratic decomposition. Set to
    `False` for faster computation when only portfolio-level results are needed.
* **Returns:**
  **attribution** *Attribution*
  : Component-level, factor-level, and optionally asset-level attribution
    results.
* **Raises:**
  ValueError
  : If the portfolio is a failed portfolio or if it holds assets not covered by
    the factor model.

<a id="skfolio.portfolio.Portfolio.previous_weights_dict"></a>

#### *property* previous_weights_dict

Dict mapping asset name to previous weight; includes zeros.

<a id="skfolio.portfolio.Portfolio.realized_attribution"></a>

#### realized_attribution(factor_model, compute_asset_breakdowns=True, compute_uncertainty=True)

Realized (ex-post) factor risk and performance attribution.

Decomposes the portfolio’s realized risk and return into contributions from
individual factors and an idiosyncratic component using actual historical factor
returns, exposures, and residuals.

The annualization scaling uses `self.annualization_factor`.

Realized attribution uses the target weights when `weight_drift=False` and the
weights held during each observation when `weight_drift=True`.

Realized attribution is computed on the overlapping observation window between
the portfolio and the factor model. Portfolio observations outside the factor
model window, commonly caused by factor-model warmup or exposure lag, are
excluded. Missing portfolio observations inside the overlapping window raise
`ValueError`. Time-varying exposures follow the as-of indexing convention
described in
[`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution):
when `exposure_lag > 0`, exposures known at observation
$t-\ell$ are aligned with returns at observation $t$.

The portfolio may hold a subset of the assets covered by the factor model and
weights are zero-filled for missing assets.

See [`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **factor_model** *FactorModel*
  : Factor model containing time-varying fields (`factor_returns`, `exposures`,
    `idio_returns`) that overlap with the portfolio’s observation period. Every
    asset in `self.assets` must appear in `factor_model.asset_names`.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset systematic/idiosyncratic attribution. Set to
    `False` for faster computation when only portfolio-level results are needed.

  **compute_uncertainty** *bool, default=True*
  : If `True`, compute attribution uncertainty (standard errors on the factor
    and idiosyncratic mean-return split).
* **Returns:**
  **attribution** *Attribution*
  : Component-level, factor-level, and optionally asset-level attribution
    results.
* **Raises:**
  ValueError
  : If the portfolio is a failed portfolio, if it holds assets not covered by
    the factor model, if no portfolio observations overlap with the factor model
    or if portfolio observations are missing inside the overlapping window.

<a id="skfolio.portfolio.Portfolio.returns_df"></a>

#### *property* returns_df

Portfolio returns DataFrame.

<a id="skfolio.portfolio.Portfolio.rolling_measure"></a>

#### rolling_measure(measure=Sharpe Ratio, window=30)

Compute the measure over a rolling window.

* **Parameters:**
  **measure** *Measure, default=RatioMeasure.SHARPE_RATIO*
  : The measure. The default measure is the Sharpe Ratio.

  **window** *int, default=30*
  : The window size. The default value is `30` observations.
* **Returns:**
  **series** *pandas Series*
  : The rolling measure Series.

<a id="skfolio.portfolio.Portfolio.rolling_realized_attribution"></a>

#### rolling_realized_attribution(factor_model, window_size=60, step=21, compute_asset_breakdowns=True, compute_asset_factor_contribs=False, compute_uncertainty=True)

Rolling realized (ex-post) factor risk and performance attribution.

Computes [`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution)
over rolling windows, returning an [`Attribution`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution)
where all numeric fields carry an additional leading dimension for the number
of windows.

Rolling realized attribution is computed on the overlapping observation window
between the portfolio and the factor model. Portfolio observations outside the
factor model window, commonly caused by factor-model warmup or exposure lag, are
excluded. Missing portfolio observations inside the overlapping window raise
`ValueError`. Time-varying exposures follow the as-of indexing convention
described in
[`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution).

Each rolling window uses the target weights when `weight_drift=False` and the
weights held during its observations when `weight_drift=True`.

The portfolio may hold a subset of the assets covered by the factor model and
weights are zero-filled for missing assets.

See [`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **factor_model** *FactorModel*
  : Factor model containing time-varying fields that overlap with the
    portfolio’s observation period.

  **window_size** *int, default=60*
  : Number of effective return periods in each rolling window.

  **step** *int, default=21*
  : Number of observations to advance between consecutive windows. The default
    of 21 produces approximately monthly output for daily data.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset attribution for each window.

  **compute_asset_factor_contribs** *bool, default=False*
  : If `True`, compute asset-factor matrix for each window.

  **compute_uncertainty** *bool, default=True*
  : If `True`, compute per-window attribution uncertainty.
* **Returns:**
  **attribution** *Attribution*
  : Rolling attribution results.
* **Raises:**
  ValueError
  : If the portfolio is a failed portfolio, if it holds assets not covered by
    the factor model, if no portfolio observations overlap with the factor model
    or if `window_size` exceeds the number of overlapping observations.

<a id="skfolio.portfolio.Portfolio.sample_weight"></a>

#### *property* sample_weight

Observations sample weights.

<a id="skfolio.portfolio.Portfolio.sric"></a>

#### *property* sric

Sharpe Ratio Information Criterion (SRIC).

It is an unbiased estimator of the Sharpe Ratio adjusting for both sources of
bias which are noise fit and estimation error [[1]](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#r26ec43111d95-1).

### References

* <a id='r26ec43111d95-1'>**[1]**</a> “Noise Fit, Estimation Error and a Sharpe Information Criterion”, Dirk Paulsen (2019)

<a id="skfolio.portfolio.Portfolio.summary"></a>

#### summary(formatted=True)

Portfolio summary of all its measures.

* **Parameters:**
  **formatted** *bool, default=True*
  : If this is set to True, the measures are formatted into rounded string
    with units.
* **Returns:**
  **summary** *series*
  : Portfolio summary.

<a id="skfolio.portfolio.Portfolio.turnover"></a>

#### *property* turnover

Total absolute weight traded at the start of the period.

In a sequential evaluation, `previous_weights` come from the last successful
Portfolio. With `weight_drift=False`, target turnover compares successive
target allocations. With `weight_drift=True`, executed turnover compares the
previous period’s ending weights with the new target allocation. When
`previous_weights` is None, it defaults to zero. Turnover includes the full
absolute weight of positions in assets absent from `X`.

<a id="skfolio.portfolio.Portfolio.variance_from_assets"></a>

#### variance_from_assets(assets_covariance)

Compute the Portfolio variance expectation from the assets covariance and
weights.

* **Parameters:**
  **assets_covariance** *ndarray of shape (n_assets,n_assets)*
  : The matrix of assets covariance expectation.
* **Returns:**
  **value** *float*
  : The Portfolio variance from the assets covariance.

<a id="skfolio.portfolio.Portfolio.weights_dict"></a>

#### *property* weights_dict

Dict mapping asset name to weight; includes zeros.

<a id="skfolio.portfolio.Portfolio.weights_per_observation"></a>

#### *property* weights_per_observation

DataFrame of asset weights at the start of each observation.

With `weight_drift=False`, every row contains the target `weights`. With
`weight_drift=True`, each row incorporates the effect of preceding asset
returns. `ending_weights` contains the weights immediately after the final
observation.

# generated/skfolio.pre_selection.DropCorrelated.html.md

<a id="skfolio-pre-selection-dropcorrelated"></a>

# skfolio.pre_selection.DropCorrelated

<a id="skfolio.pre_selection.DropCorrelated"></a>

### *class* skfolio.pre_selection.DropCorrelated(threshold=0.95, absolute=False)

Transformer for dropping highly correlated assets.

Simply removing all correlation pairs above the threshold will remove more assets
than necessary and a naive sequential removal is suboptimal and depends on the
initial assets ordering.

Let’s suppose X,Y,Z are three random variables with corr(X,Y) and corr(X,Z) above
the threshold and corr(Y,Z) below.
The first approach would remove X,Y,Z and the second approach would remove either
Y and Z or X depending on the initial ordering.

To avoid these shortcomings, we implement the below algorithm:

> * Step 1: select all correlation pairs above the threshold.
> * Step 2: sort all the selected correlation pairs from highest to lowest.
> * Step 3: for each pair, if none of the two assets has been removed, keep the
>   asset with the lowest average correlation against the other assets.
* **Parameters:**
  **threshold** *float, default=0.95*
  : Correlation threshold. The default value is `0.95`.

  **absolute** *bool, default=False*
  : If this is set to True, we take the absolute value of the correlation. This has
    for effect to also include negatively correlated assets.
* **Attributes:**
  **to_keep_** *ndarray of shape (n_assets, )*
  : Boolean array indicating which assets are remaining.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.fit)(X[, y])                             | Run the correlation transformer and get the appropriate assets.   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.fit_transform)(X[, y])                   | Fit to data, then transform it.                                   |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.get_feature_names_out)([input_features]) | Mask feature names according to selected features.                |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.get_metadata_routing)()                  | Get metadata routing of this object.                              |
| [`get_params`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.get_params)([deep])                      | Get parameters for this estimator.                                |
| [`get_support`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.get_support)([indices])                  | Get a mask, or integer index, of the features selected.           |
| [`inverse_transform`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.inverse_transform)(X)                    | Reverse the transformation operation.                             |
| [`set_output`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.set_output)(\*[, transform])             | Set output container.                                             |
| [`set_params`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.set_params)(\*\*params)                  | Set the parameters of this estimator.                             |
| [`transform`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.transform)(X)                            | Reduce X to the selected features.                                |

<a id="skfolio.pre_selection.DropCorrelated.fit"></a>

#### fit(X, y=None)

Run the correlation transformer and get the appropriate assets.

* **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.
* **Returns:**
  **self** *DropCorrelated*
  : Fitted estimator.

<a id="skfolio.pre_selection.DropCorrelated.fit_transform"></a>

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

Fit to data, then transform it.

Fits transformer to `X` and `y` with optional parameters `fit_params`
and returns a transformed version of `X`.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_features)*
  : Input samples.

  **y** *array-like of shape (n_samples,) or (n_samples, n_outputs), default=None*
  : Target values (None for unsupervised transformations).

  **\*\*fit_params** *dict*
  : Additional fit parameters.
    Pass only if the estimator accepts additional params in its `fit` method.
* **Returns:**
  **X_new** *ndarray array of shape (n_samples, n_features_new)*
  : Transformed array.

<a id="skfolio.pre_selection.DropCorrelated.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Mask feature names according to selected features.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Transformed feature names.

<a id="skfolio.pre_selection.DropCorrelated.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.pre_selection.DropCorrelated.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.pre_selection.DropCorrelated.get_support"></a>

#### get_support(indices=False)

Get a mask, or integer index, of the features selected.

* **Parameters:**
  **indices** *bool, default=False*
  : If True, the return value will be an array of integers, rather
    than a boolean mask.
* **Returns:**
  **support** *array*
  : An index that selects the retained features from a feature vector.
    If `indices` is False, this is a boolean array of shape
    [# input features], in which an element is True iff its
    corresponding feature is selected for retention. If `indices` is
    True, this is an integer array of shape [# output features] whose
    values are indices into the input feature vector.

<a id="skfolio.pre_selection.DropCorrelated.inverse_transform"></a>

#### inverse_transform(X)

Reverse the transformation operation.

* **Parameters:**
  **X** *array of shape [n_samples, n_selected_features]*
  : The input samples.
* **Returns:**
  **X_original** *array of shape [n_samples, n_original_features]*
  : `X` with columns of zeros inserted where features would have
    been removed by [`transform`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated.transform).

<a id="skfolio.pre_selection.DropCorrelated.set_output"></a>

#### set_output(\*, transform=None)

Set output container.

Refer to the user guide for more details
and sphx_glr_auto_examples_miscellaneous_plot_set_output.py for an
example on how to use the API.

* **Parameters:**
  **transform** *{“default”, “pandas”, “polars”}, default=None*
  : Configure output of `transform` and `fit_transform`.
    - `"default"`: Default output format of a transformer
    - `"pandas"`: DataFrame output
    - `"polars"`: Polars output
    - `None`: Transform configuration is unchanged
    <br/>
    #### Versionadded
    Added in version 1.4: `"polars"` option was added.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.

<a id="skfolio.pre_selection.DropCorrelated.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.

<a id="skfolio.pre_selection.DropCorrelated.transform"></a>

#### transform(X)

Reduce X to the selected features.

* **Parameters:**
  **X** *array of shape [n_samples, n_features]*
  : The input samples.
* **Returns:**
  **X_r** *array of shape [n_samples, n_selected_features]*
  : The input samples with only the selected features.

# generated/skfolio.pre_selection.DropZeroVariance.html.md

<a id="skfolio-pre-selection-dropzerovariance"></a>

# skfolio.pre_selection.DropZeroVariance

<a id="skfolio.pre_selection.DropZeroVariance"></a>

### *class* skfolio.pre_selection.DropZeroVariance(threshold=1e-08)

Transformer for dropping assets with near-zero variance.

On short windows, some assets can experience a near-zero variance, making
the covariance matrix improper for optimization. This simple transformer drops
assets whose variance is below some threshold.

* **Parameters:**
  **threshold** *float, default=1e-8*
  : Minimum variance threshold. The default value is 1e-8. For daily asset returns,
    this value filters out assets whose daily standard deviation is below 1e-4
    (0.01%), which corresponds to an annual standard deviation of approximately
    0.16%, assuming 252 trading days.
* **Attributes:**
  **to_keep_** *ndarray of shape (n_assets, )*
  : Boolean array indicating which assets are remaining.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.fit)(X[, y])                             | Fit the transformer on some assets.                     |
|------------------------------------------------------------------------------------------|---------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.fit_transform)(X[, y])                   | Fit to data, then transform it.                         |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.get_feature_names_out)([input_features]) | Mask feature names according to selected features.      |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.get_metadata_routing)()                  | Get metadata routing of this object.                    |
| [`get_params`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.get_params)([deep])                      | Get parameters for this estimator.                      |
| [`get_support`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.get_support)([indices])                  | Get a mask, or integer index, of the features selected. |
| [`inverse_transform`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.inverse_transform)(X)                    | Reverse the transformation operation.                   |
| [`set_output`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.set_output)(\*[, transform])             | Set output container.                                   |
| [`set_params`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.set_params)(\*\*params)                  | Set the parameters of this estimator.                   |
| [`transform`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.transform)(X)                            | Reduce X to the selected features.                      |

<a id="skfolio.pre_selection.DropZeroVariance.fit"></a>

#### fit(X, y=None)

Fit the transformer on some assets.

* **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.
* **Returns:**
  **self** *DropZeroVariance*
  : Fitted estimator.

<a id="skfolio.pre_selection.DropZeroVariance.fit_transform"></a>

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

Fit to data, then transform it.

Fits transformer to `X` and `y` with optional parameters `fit_params`
and returns a transformed version of `X`.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_features)*
  : Input samples.

  **y** *array-like of shape (n_samples,) or (n_samples, n_outputs), default=None*
  : Target values (None for unsupervised transformations).

  **\*\*fit_params** *dict*
  : Additional fit parameters.
    Pass only if the estimator accepts additional params in its `fit` method.
* **Returns:**
  **X_new** *ndarray array of shape (n_samples, n_features_new)*
  : Transformed array.

<a id="skfolio.pre_selection.DropZeroVariance.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Mask feature names according to selected features.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Transformed feature names.

<a id="skfolio.pre_selection.DropZeroVariance.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.pre_selection.DropZeroVariance.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.pre_selection.DropZeroVariance.get_support"></a>

#### get_support(indices=False)

Get a mask, or integer index, of the features selected.

* **Parameters:**
  **indices** *bool, default=False*
  : If True, the return value will be an array of integers, rather
    than a boolean mask.
* **Returns:**
  **support** *array*
  : An index that selects the retained features from a feature vector.
    If `indices` is False, this is a boolean array of shape
    [# input features], in which an element is True iff its
    corresponding feature is selected for retention. If `indices` is
    True, this is an integer array of shape [# output features] whose
    values are indices into the input feature vector.

<a id="skfolio.pre_selection.DropZeroVariance.inverse_transform"></a>

#### inverse_transform(X)

Reverse the transformation operation.

* **Parameters:**
  **X** *array of shape [n_samples, n_selected_features]*
  : The input samples.
* **Returns:**
  **X_original** *array of shape [n_samples, n_original_features]*
  : `X` with columns of zeros inserted where features would have
    been removed by [`transform`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance.transform).

<a id="skfolio.pre_selection.DropZeroVariance.set_output"></a>

#### set_output(\*, transform=None)

Set output container.

Refer to the user guide for more details
and sphx_glr_auto_examples_miscellaneous_plot_set_output.py for an
example on how to use the API.

* **Parameters:**
  **transform** *{“default”, “pandas”, “polars”}, default=None*
  : Configure output of `transform` and `fit_transform`.
    - `"default"`: Default output format of a transformer
    - `"pandas"`: DataFrame output
    - `"polars"`: Polars output
    - `None`: Transform configuration is unchanged
    <br/>
    #### Versionadded
    Added in version 1.4: `"polars"` option was added.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.

<a id="skfolio.pre_selection.DropZeroVariance.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.

<a id="skfolio.pre_selection.DropZeroVariance.transform"></a>

#### transform(X)

Reduce X to the selected features.

* **Parameters:**
  **X** *array of shape [n_samples, n_features]*
  : The input samples.
* **Returns:**
  **X_r** *array of shape [n_samples, n_selected_features]*
  : The input samples with only the selected features.

# generated/skfolio.pre_selection.SelectComplete.html.md

<a id="skfolio-pre-selection-selectcomplete"></a>

# skfolio.pre_selection.SelectComplete

<a id="skfolio.pre_selection.SelectComplete"></a>

### *class* skfolio.pre_selection.SelectComplete(drop_assets_with_internal_nan=False)

Transformer to select assets with complete data across the entire observation
period.

This transformer removes assets (columns) that have missing values (NaNs) at the
beginning or end of the period.

This transformer is especially useful for financial datasets where assets
(e.g., stocks, bonds) may have data gaps due to late inception (assets that started
trading later), early expiry or default (assets that stopped trading before the
end of the period).

If missing values are not at the beginning or end but occur between non-missing
values, the asset is not removed unless `drop_assets_with_internal_nan` is set to
`True`.

* **Parameters:**
  **drop_assets_with_internal_nan** *bool, default=False*
  : If set to True, assets with missing values (NaNs) that appear between
    non-missing values (i.e., internal NaNs) will also be removed. By default,
    only assets with leading or trailing NaNs are removed.
* **Attributes:**
  **to_keep_** *ndarray of shape (n_assets, )*
  : Boolean array indicating which assets are remaining.

  **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`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.fit)(X[, y])                             | Run the SelectComplete transformer and get the appropriate assets.   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.fit_transform)(X[, y])                   | Fit to data, then transform it.                                      |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.get_feature_names_out)([input_features]) | Mask feature names according to selected features.                   |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.get_metadata_routing)()                  | Get metadata routing of this object.                                 |
| [`get_params`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.get_params)([deep])                      | Get parameters for this estimator.                                   |
| [`get_support`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.get_support)([indices])                  | Get a mask, or integer index, of the features selected.              |
| [`inverse_transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.inverse_transform)(X)                    | Reverse the transformation operation.                                |
| [`set_output`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.set_output)(\*[, transform])             | Set output container.                                                |
| [`set_params`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.set_params)(\*\*params)                  | Set the parameters of this estimator.                                |
| [`transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.transform)(X)                            | Reduce X to the selected features.                                   |

### Examples

```pycon
>>> import numpy as np
>>> import pandas as pd
>>> from skfolio.pre_selection import SelectComplete
>>> X = pd.DataFrame({
...     'asset1': [np.nan, np.nan, 2, 3, 4],    # Starts late (inception)
...     'asset2': [1, 2, 3, 4, 5],         # Complete data
...     'asset3': [1, 2, 3, np.nan, 5], # Missing values within data
...     'asset4': [1, 2, 3, 4, np.nan]      # Ends early (expiration)
... })
>>> selector = SelectComplete()
>>> selector.fit_transform(X)
 array([[ 1.,  1.],
        [ 2.,  2.],
        [ 3.,  3.],
        [ 4., nan],
        [ 5.,  5.]])
>>> selector = SelectComplete(drop_assets_with_internal_nan=True)
>>> selector.fit_transform(X)
 array([[1.],
       [2.],
       [3.],
       [4.],
       [5.]])
```

<a id="skfolio.pre_selection.SelectComplete.fit"></a>

#### fit(X, y=None)

Run the SelectComplete transformer and get the appropriate assets.

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

  **y** *Ignored*
  : Not used, present for API consistency by convention.
* **Returns:**
  **self** *SelectComplete*
  : Fitted estimator.

<a id="skfolio.pre_selection.SelectComplete.fit_transform"></a>

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

Fit to data, then transform it.

Fits transformer to `X` and `y` with optional parameters `fit_params`
and returns a transformed version of `X`.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_features)*
  : Input samples.

  **y** *array-like of shape (n_samples,) or (n_samples, n_outputs), default=None*
  : Target values (None for unsupervised transformations).

  **\*\*fit_params** *dict*
  : Additional fit parameters.
    Pass only if the estimator accepts additional params in its `fit` method.
* **Returns:**
  **X_new** *ndarray array of shape (n_samples, n_features_new)*
  : Transformed array.

<a id="skfolio.pre_selection.SelectComplete.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Mask feature names according to selected features.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Transformed feature names.

<a id="skfolio.pre_selection.SelectComplete.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.pre_selection.SelectComplete.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.pre_selection.SelectComplete.get_support"></a>

#### get_support(indices=False)

Get a mask, or integer index, of the features selected.

* **Parameters:**
  **indices** *bool, default=False*
  : If True, the return value will be an array of integers, rather
    than a boolean mask.
* **Returns:**
  **support** *array*
  : An index that selects the retained features from a feature vector.
    If `indices` is False, this is a boolean array of shape
    [# input features], in which an element is True iff its
    corresponding feature is selected for retention. If `indices` is
    True, this is an integer array of shape [# output features] whose
    values are indices into the input feature vector.

<a id="skfolio.pre_selection.SelectComplete.inverse_transform"></a>

#### inverse_transform(X)

Reverse the transformation operation.

* **Parameters:**
  **X** *array of shape [n_samples, n_selected_features]*
  : The input samples.
* **Returns:**
  **X_original** *array of shape [n_samples, n_original_features]*
  : `X` with columns of zeros inserted where features would have
    been removed by [`transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete.transform).

<a id="skfolio.pre_selection.SelectComplete.set_output"></a>

#### set_output(\*, transform=None)

Set output container.

Refer to the user guide for more details
and sphx_glr_auto_examples_miscellaneous_plot_set_output.py for an
example on how to use the API.

* **Parameters:**
  **transform** *{“default”, “pandas”, “polars”}, default=None*
  : Configure output of `transform` and `fit_transform`.
    - `"default"`: Default output format of a transformer
    - `"pandas"`: DataFrame output
    - `"polars"`: Polars output
    - `None`: Transform configuration is unchanged
    <br/>
    #### Versionadded
    Added in version 1.4: `"polars"` option was added.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.

<a id="skfolio.pre_selection.SelectComplete.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.

<a id="skfolio.pre_selection.SelectComplete.transform"></a>

#### transform(X)

Reduce X to the selected features.

* **Parameters:**
  **X** *array of shape [n_samples, n_features]*
  : The input samples.
* **Returns:**
  **X_r** *array of shape [n_samples, n_selected_features]*
  : The input samples with only the selected features.

# generated/skfolio.pre_selection.SelectKExtremes.html.md

<a id="skfolio-pre-selection-selectkextremes"></a>

# skfolio.pre_selection.SelectKExtremes

<a id="skfolio.pre_selection.SelectKExtremes"></a>

### *class* skfolio.pre_selection.SelectKExtremes(k=10, measure=Sharpe Ratio, highest=True)

Transformer for selecting the `k` best or worst assets.

Keep the `k` best or worst assets according to a given measure.

* **Parameters:**
  **k** *int, default=10*
  : Number of assets to select. If `k` is higher than the number of assets, all
    assets are selected.

  **measure** *Measure, default=RatioMeasure.SHARPE_RATIO*
  : The [measure](https://skfolio.org/api.html.md#measures-ref) used to sort the assets.
    The default is `RatioMeasure.SHARPE_RATIO`.

  **highest** *bool, default=True*
  : If this is set to True, the `k` assets with the highest `measure` are selected,
    otherwise it is the `k` lowest.
* **Attributes:**
  **to_keep_** *ndarray of shape (n_assets, )*
  : Boolean array indicating which assets are remaining.

  **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`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.fit)(X[, y])                             | Run the SelectKExtremes transformer and get the appropriate assets.   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.fit_transform)(X[, y])                   | Fit to data, then transform it.                                       |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.get_feature_names_out)([input_features]) | Mask feature names according to selected features.                    |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.get_metadata_routing)()                  | Get metadata routing of this object.                                  |
| [`get_params`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.get_params)([deep])                      | Get parameters for this estimator.                                    |
| [`get_support`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.get_support)([indices])                  | Get a mask, or integer index, of the features selected.               |
| [`inverse_transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.inverse_transform)(X)                    | Reverse the transformation operation.                                 |
| [`set_output`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.set_output)(\*[, transform])             | Set output container.                                                 |
| [`set_params`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.set_params)(\*\*params)                  | Set the parameters of this estimator.                                 |
| [`transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.transform)(X)                            | Reduce X to the selected features.                                    |

<a id="skfolio.pre_selection.SelectKExtremes.fit"></a>

#### fit(X, y=None)

Run the SelectKExtremes transformer and get the appropriate assets.

* **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.
* **Returns:**
  **self** *SelectKExtremes*
  : Fitted estimator.

<a id="skfolio.pre_selection.SelectKExtremes.fit_transform"></a>

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

Fit to data, then transform it.

Fits transformer to `X` and `y` with optional parameters `fit_params`
and returns a transformed version of `X`.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_features)*
  : Input samples.

  **y** *array-like of shape (n_samples,) or (n_samples, n_outputs), default=None*
  : Target values (None for unsupervised transformations).

  **\*\*fit_params** *dict*
  : Additional fit parameters.
    Pass only if the estimator accepts additional params in its `fit` method.
* **Returns:**
  **X_new** *ndarray array of shape (n_samples, n_features_new)*
  : Transformed array.

<a id="skfolio.pre_selection.SelectKExtremes.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Mask feature names according to selected features.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Transformed feature names.

<a id="skfolio.pre_selection.SelectKExtremes.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.pre_selection.SelectKExtremes.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.pre_selection.SelectKExtremes.get_support"></a>

#### get_support(indices=False)

Get a mask, or integer index, of the features selected.

* **Parameters:**
  **indices** *bool, default=False*
  : If True, the return value will be an array of integers, rather
    than a boolean mask.
* **Returns:**
  **support** *array*
  : An index that selects the retained features from a feature vector.
    If `indices` is False, this is a boolean array of shape
    [# input features], in which an element is True iff its
    corresponding feature is selected for retention. If `indices` is
    True, this is an integer array of shape [# output features] whose
    values are indices into the input feature vector.

<a id="skfolio.pre_selection.SelectKExtremes.inverse_transform"></a>

#### inverse_transform(X)

Reverse the transformation operation.

* **Parameters:**
  **X** *array of shape [n_samples, n_selected_features]*
  : The input samples.
* **Returns:**
  **X_original** *array of shape [n_samples, n_original_features]*
  : `X` with columns of zeros inserted where features would have
    been removed by [`transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes.transform).

<a id="skfolio.pre_selection.SelectKExtremes.set_output"></a>

#### set_output(\*, transform=None)

Set output container.

Refer to the user guide for more details
and sphx_glr_auto_examples_miscellaneous_plot_set_output.py for an
example on how to use the API.

* **Parameters:**
  **transform** *{“default”, “pandas”, “polars”}, default=None*
  : Configure output of `transform` and `fit_transform`.
    - `"default"`: Default output format of a transformer
    - `"pandas"`: DataFrame output
    - `"polars"`: Polars output
    - `None`: Transform configuration is unchanged
    <br/>
    #### Versionadded
    Added in version 1.4: `"polars"` option was added.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.

<a id="skfolio.pre_selection.SelectKExtremes.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.

<a id="skfolio.pre_selection.SelectKExtremes.transform"></a>

#### transform(X)

Reduce X to the selected features.

* **Parameters:**
  **X** *array of shape [n_samples, n_features]*
  : The input samples.
* **Returns:**
  **X_r** *array of shape [n_samples, n_selected_features]*
  : The input samples with only the selected features.

# generated/skfolio.pre_selection.SelectNonDominated.html.md

<a id="skfolio-pre-selection-selectnondominated"></a>

# skfolio.pre_selection.SelectNonDominated

<a id="skfolio.pre_selection.SelectNonDominated"></a>

### *class* skfolio.pre_selection.SelectNonDominated(min_n_assets=None, threshold=-0.5, fitness_measures=None)

Transformer for selecting non dominated assets.

Pre-selection based on the Assets Preselection Process 2 [[1]](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#ra08cd64e7a9c-1).

Good single asset (for example with high return and low risk) is likely to
contribute to the final optimized portfolio. Each asset is considered as a portfolio
and these assets are ranked using the non-domination sorting method. The selection
is based on the ranks assigned to each asset based on their fitness until the number
of selected assets reaches the user-defined number.

Considering only the fitness of individual asset is insufficient because a pair of
negatively correlated assets has the potential to reduce the risk. Therefore,
negatively correlated pairs of assets are also considered.

* **Parameters:**
  **min_n_assets** *int, optional*
  : The minimum number of assets to select. If `min_n_assets` is reached before the
    end of the current non-dominated front, we return the remaining assets of this
    front. This is because all assets in the same front have the same rank.
    The default (`None`) is to select the first front.

  **threshold** *float, default=0.0*
  : Asset pairs with a correlation below this threshold are included in the
    non-domination sorting. The default value is `0.0`.

  **fitness_measures** *list[Measure], optional*
  : A list of [measure](https://skfolio.org/api.html.md#measures-ref) used to compute the portfolio fitness.
    The fitness is used to compare portfolios in terms of domination, compute the
    Pareto fronts and run the portfolio selection using non-dominated sorting.
    The default (`None`) is to use the list [PerfMeasure.MEAN, RiskMeasure.VARIANCE]
* **Attributes:**
  **to_keep_** *ndarray of shape (n_assets, )*
  : Boolean array indicating which assets are remaining.

  **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`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.fit)(X[, y])                             | Run the Non Dominated transformer and get the appropriate assets.   |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.fit_transform)(X[, y])                   | Fit to data, then transform it.                                     |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.get_feature_names_out)([input_features]) | Mask feature names according to selected features.                  |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.get_metadata_routing)()                  | Get metadata routing of this object.                                |
| [`get_params`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.get_params)([deep])                      | Get parameters for this estimator.                                  |
| [`get_support`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.get_support)([indices])                  | Get a mask, or integer index, of the features selected.             |
| [`inverse_transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.inverse_transform)(X)                    | Reverse the transformation operation.                               |
| [`set_output`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.set_output)(\*[, transform])             | Set output container.                                               |
| [`set_params`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.set_params)(\*\*params)                  | Set the parameters of this estimator.                               |
| [`transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.transform)(X)                            | Reduce X to the selected features.                                  |

### References

* <a id='ra08cd64e7a9c-1'>**[1]**</a> “Large-Scale Portfolio Optimization Using Multi-objective Evolutionary Algorithms and Preselection Methods”, B.Y. Qu and Q.Zhou (2017).

<a id="skfolio.pre_selection.SelectNonDominated.fit"></a>

#### fit(X, y=None)

Run the Non Dominated transformer and get the appropriate assets.

* **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.
* **Returns:**
  **self** *SelectNonDominated*
  : Fitted estimator.

<a id="skfolio.pre_selection.SelectNonDominated.fit_transform"></a>

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

Fit to data, then transform it.

Fits transformer to `X` and `y` with optional parameters `fit_params`
and returns a transformed version of `X`.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_features)*
  : Input samples.

  **y** *array-like of shape (n_samples,) or (n_samples, n_outputs), default=None*
  : Target values (None for unsupervised transformations).

  **\*\*fit_params** *dict*
  : Additional fit parameters.
    Pass only if the estimator accepts additional params in its `fit` method.
* **Returns:**
  **X_new** *ndarray array of shape (n_samples, n_features_new)*
  : Transformed array.

<a id="skfolio.pre_selection.SelectNonDominated.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Mask feature names according to selected features.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Transformed feature names.

<a id="skfolio.pre_selection.SelectNonDominated.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.pre_selection.SelectNonDominated.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.pre_selection.SelectNonDominated.get_support"></a>

#### get_support(indices=False)

Get a mask, or integer index, of the features selected.

* **Parameters:**
  **indices** *bool, default=False*
  : If True, the return value will be an array of integers, rather
    than a boolean mask.
* **Returns:**
  **support** *array*
  : An index that selects the retained features from a feature vector.
    If `indices` is False, this is a boolean array of shape
    [# input features], in which an element is True iff its
    corresponding feature is selected for retention. If `indices` is
    True, this is an integer array of shape [# output features] whose
    values are indices into the input feature vector.

<a id="skfolio.pre_selection.SelectNonDominated.inverse_transform"></a>

#### inverse_transform(X)

Reverse the transformation operation.

* **Parameters:**
  **X** *array of shape [n_samples, n_selected_features]*
  : The input samples.
* **Returns:**
  **X_original** *array of shape [n_samples, n_original_features]*
  : `X` with columns of zeros inserted where features would have
    been removed by [`transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated.transform).

<a id="skfolio.pre_selection.SelectNonDominated.set_output"></a>

#### set_output(\*, transform=None)

Set output container.

Refer to the user guide for more details
and sphx_glr_auto_examples_miscellaneous_plot_set_output.py for an
example on how to use the API.

* **Parameters:**
  **transform** *{“default”, “pandas”, “polars”}, default=None*
  : Configure output of `transform` and `fit_transform`.
    - `"default"`: Default output format of a transformer
    - `"pandas"`: DataFrame output
    - `"polars"`: Polars output
    - `None`: Transform configuration is unchanged
    <br/>
    #### Versionadded
    Added in version 1.4: `"polars"` option was added.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.

<a id="skfolio.pre_selection.SelectNonDominated.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.

<a id="skfolio.pre_selection.SelectNonDominated.transform"></a>

#### transform(X)

Reduce X to the selected features.

* **Parameters:**
  **X** *array of shape [n_samples, n_features]*
  : The input samples.
* **Returns:**
  **X_r** *array of shape [n_samples, n_selected_features]*
  : The input samples with only the selected features.

# generated/skfolio.pre_selection.SelectNonExpiring.html.md

<a id="skfolio-pre-selection-selectnonexpiring"></a>

# skfolio.pre_selection.SelectNonExpiring

<a id="skfolio.pre_selection.SelectNonExpiring"></a>

### *class* skfolio.pre_selection.SelectNonExpiring(expiration_dates=None, expiration_lookahead=None)

Transformer to select assets that do not expire within a specified lookahead period
after the end of the observation period.

This transformer removes assets (columns) that have expiration dates within a
given lookahead period from the end of the dataset, allowing only assets that
remain active beyond this lookahead period to be selected.

This is useful when an exit strategy is needed before asset expiration, such as
for bonds or options with known end dates, or when applying WalkForward
cross-validation. It ensures that assets expiring during the test period are
excluded, so that only live assets are included in each training and test period.

* **Parameters:**
  **expiration_dates** *dict[str, dt.datetime | pd.Timestamp], optional*
  : Dictionary with asset names as keys and expiration dates as values.
    Used to check if each asset expires within the date offset.
    Assets with no expiration date will be retained by default.

  **expiration_lookahead** *pd.offsets.BaseOffset | dt.timedelta, optional*
  : The lookahead period after the end of the dataset within which assets with
    expiration dates will be removed.
* **Attributes:**
  **to_keep_** *ndarray of shape (n_assets, )*
  : Boolean array indicating which assets are remaining.

  **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`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.fit)(X[, y])                             | Run the SelectNonExpiring transformer and get the appropriate assets.   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.fit_transform)(X[, y])                   | Fit to data, then transform it.                                         |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.get_feature_names_out)([input_features]) | Mask feature names according to selected features.                      |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.get_metadata_routing)()                  | Get metadata routing of this object.                                    |
| [`get_params`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.get_params)([deep])                      | Get parameters for this estimator.                                      |
| [`get_support`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.get_support)([indices])                  | Get a mask, or integer index, of the features selected.                 |
| [`inverse_transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.inverse_transform)(X)                    | Reverse the transformation operation.                                   |
| [`set_output`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.set_output)(\*[, transform])             | Set output container.                                                   |
| [`set_params`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.set_params)(\*\*params)                  | Set the parameters of this estimator.                                   |
| [`transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.transform)(X)                            | Reduce X to the selected features.                                      |

### Notes

This transformer only supports DataFrames with a DateTime index.

### Examples

```pycon
>>> import pandas as pd
>>> import datetime as dt
>>> from sklearn import set_config
>>> set_config(transform_output="pandas")
>>> X = pd.DataFrame(
...    {
...        'asset1': [1, 2, 3, 4],
...        'asset2': [2, 3, 4, 5],
...        'asset3': [3, 4, 5, 6],
...        'asset4': [4, 5, 6, 7]
...    }, index=pd.date_range("2023-01-01", periods=4, freq="D")
... )
>>> expiration_dates = {
...    'asset1': pd.Timestamp("2023-01-10"),
...    'asset2': pd.Timestamp("2023-01-02"),
...    'asset3': pd.Timestamp("2023-01-06"),
...    'asset4': dt.datetime(2023, 5, 1)
... }
>>> selector = SelectNonExpiring(
...    expiration_dates=expiration_dates,
...    expiration_lookahead=pd.DateOffset(days=5)
... )
>>> selector.fit_transform(X)
           asset1  asset4
2023-01-01      1      4
2023-01-02      2      5
2023-01-03      3      6
2023-01-04      4      7
```

<a id="skfolio.pre_selection.SelectNonExpiring.fit"></a>

#### fit(X, y=None)

Run the SelectNonExpiring transformer and get the appropriate assets.

* **Parameters:**
  **X** *pd.DataFrame of shape (n_observations, n_assets)*
  : Returns of the assets.

  **y** *Ignored*
  : Not used, present for API consistency by convention.
* **Returns:**
  **self** *SelectNonExpiring*
  : Fitted estimator.

<a id="skfolio.pre_selection.SelectNonExpiring.fit_transform"></a>

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

Fit to data, then transform it.

Fits transformer to `X` and `y` with optional parameters `fit_params`
and returns a transformed version of `X`.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_features)*
  : Input samples.

  **y** *array-like of shape (n_samples,) or (n_samples, n_outputs), default=None*
  : Target values (None for unsupervised transformations).

  **\*\*fit_params** *dict*
  : Additional fit parameters.
    Pass only if the estimator accepts additional params in its `fit` method.
* **Returns:**
  **X_new** *ndarray array of shape (n_samples, n_features_new)*
  : Transformed array.

<a id="skfolio.pre_selection.SelectNonExpiring.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Mask feature names according to selected features.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Transformed feature names.

<a id="skfolio.pre_selection.SelectNonExpiring.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.pre_selection.SelectNonExpiring.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.pre_selection.SelectNonExpiring.get_support"></a>

#### get_support(indices=False)

Get a mask, or integer index, of the features selected.

* **Parameters:**
  **indices** *bool, default=False*
  : If True, the return value will be an array of integers, rather
    than a boolean mask.
* **Returns:**
  **support** *array*
  : An index that selects the retained features from a feature vector.
    If `indices` is False, this is a boolean array of shape
    [# input features], in which an element is True iff its
    corresponding feature is selected for retention. If `indices` is
    True, this is an integer array of shape [# output features] whose
    values are indices into the input feature vector.

<a id="skfolio.pre_selection.SelectNonExpiring.inverse_transform"></a>

#### inverse_transform(X)

Reverse the transformation operation.

* **Parameters:**
  **X** *array of shape [n_samples, n_selected_features]*
  : The input samples.
* **Returns:**
  **X_original** *array of shape [n_samples, n_original_features]*
  : `X` with columns of zeros inserted where features would have
    been removed by [`transform`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring.transform).

<a id="skfolio.pre_selection.SelectNonExpiring.set_output"></a>

#### set_output(\*, transform=None)

Set output container.

Refer to the user guide for more details
and sphx_glr_auto_examples_miscellaneous_plot_set_output.py for an
example on how to use the API.

* **Parameters:**
  **transform** *{“default”, “pandas”, “polars”}, default=None*
  : Configure output of `transform` and `fit_transform`.
    - `"default"`: Default output format of a transformer
    - `"pandas"`: DataFrame output
    - `"polars"`: Polars output
    - `None`: Transform configuration is unchanged
    <br/>
    #### Versionadded
    Added in version 1.4: `"polars"` option was added.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.

<a id="skfolio.pre_selection.SelectNonExpiring.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.

<a id="skfolio.pre_selection.SelectNonExpiring.transform"></a>

#### transform(X)

Reduce X to the selected features.

* **Parameters:**
  **X** *array of shape [n_samples, n_features]*
  : The input samples.
* **Returns:**
  **X_r** *array of shape [n_samples, n_selected_features]*
  : The input samples with only the selected features.

# generated/skfolio.preprocessing.BaseCSTransformer.html.md

<a id="skfolio-preprocessing-basecstransformer"></a>

# skfolio.preprocessing.BaseCSTransformer

<a id="skfolio.preprocessing.BaseCSTransformer"></a>

### *class* skfolio.preprocessing.BaseCSTransformer

Base class for all cross-sectional transformers in skfolio.

Cross-sectional transformers process each observation of a 2D input array using
values from the same observation only.

These transformers are stateless. The default `fit` method validates the estimator
parameters, validates `X`, and records `n_features_in_` for scikit-learn
compatibility.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.preprocessing.BaseCSTransformer.html.md#skfolio.preprocessing.BaseCSTransformer.fit)(X[, y, cs_weights, cs_groups])                 | Fit the transformer.                                                                   |
|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.preprocessing.BaseCSTransformer.html.md#skfolio.preprocessing.BaseCSTransformer.fit_transform)(X[, y, cs_weights, cs_groups])       | Fit to `X` and return the transformed values.                                          |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.preprocessing.BaseCSTransformer.html.md#skfolio.preprocessing.BaseCSTransformer.get_feature_names_out)([input_features])            | Get output feature names for transformation.                                           |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.preprocessing.BaseCSTransformer.html.md#skfolio.preprocessing.BaseCSTransformer.get_metadata_routing)()                             | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.preprocessing.BaseCSTransformer.html.md#skfolio.preprocessing.BaseCSTransformer.get_params)([deep])                                 | Get parameters for this estimator.                                                     |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.preprocessing.BaseCSTransformer.html.md#skfolio.preprocessing.BaseCSTransformer.set_fit_request)(\*[, cs_groups, cs_weights])       | Configure whether metadata should be requested to be passed to the `fit` method.       |
| [`set_params`](https://skfolio.org/generated/skfolio.preprocessing.BaseCSTransformer.html.md#skfolio.preprocessing.BaseCSTransformer.set_params)(\*\*params)                             | Set the parameters of this estimator.                                                  |
| [`set_transform_request`](https://skfolio.org/generated/skfolio.preprocessing.BaseCSTransformer.html.md#skfolio.preprocessing.BaseCSTransformer.set_transform_request)(\*[, cs_groups, cs_weights]) | Configure whether metadata should be requested to be passed to the `transform` method. |
| [`transform`](https://skfolio.org/generated/skfolio.preprocessing.BaseCSTransformer.html.md#skfolio.preprocessing.BaseCSTransformer.transform)(X[, cs_weights, cs_groups])              | Transform `X` observation by observation.                                              |

### Notes

All estimators should specify all the parameters that can be set at the class level
in their `__init__` as explicit keyword arguments (no `*args` or `**kwargs`).

<a id="skfolio.preprocessing.BaseCSTransformer.fit"></a>

#### fit(X, y=None, cs_weights=None, cs_groups=None)

Fit the transformer.

Cross-sectional transformers are stateless and do not learn data-dependent
parameters. This method validates the estimator parameters, validates `X`, and
records `n_features_in_` for scikit-learn compatibility.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights accepted for API consistency with
    `transform`. They are ignored during fitting.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels accepted for API consistency with
    `transform`. They are ignored during fitting.
* **Returns:**
  **self** *BaseCSTransformer*
  : Fitted estimator.

<a id="skfolio.preprocessing.BaseCSTransformer.fit_transform"></a>

#### fit_transform(X, y=None, cs_weights=None, cs_groups=None)

Fit to `X` and return the transformed values.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights forwarded to `transform`.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels forwarded to `transform`.
* **Returns:**
  **X_new** *ndarray of shape (n_observations, n_assets)*
  : Transformed array.

<a id="skfolio.preprocessing.BaseCSTransformer.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Get output feature names for transformation.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Same as input features.

<a id="skfolio.preprocessing.BaseCSTransformer.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.preprocessing.BaseCSTransformer.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.preprocessing.BaseCSTransformer.set_fit_request"></a>

#### set_fit_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `fit`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.BaseCSTransformer.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.

<a id="skfolio.preprocessing.BaseCSTransformer.set_transform_request"></a>

#### set_transform_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `transform` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `transform` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `transform`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `transform`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `transform`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.BaseCSTransformer.transform"></a>

#### *abstractmethod* transform(X, cs_weights=None, cs_groups=None)

Transform `X` observation by observation.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights used by the concrete transformer.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels used by the concrete transformer.
* **Returns:**
  **X_transformed** *ndarray of shape (n_observations, n_assets)*
  : Transformed values.

# generated/skfolio.preprocessing.CSGaussianRankScaler.html.md

<a id="skfolio-preprocessing-csgaussianrankscaler"></a>

# skfolio.preprocessing.CSGaussianRankScaler

<a id="skfolio.preprocessing.CSGaussianRankScaler"></a>

### *class* skfolio.preprocessing.CSGaussianRankScaler(\*, min_group_size=8, scale=True, atol=1e-12)

Cross-sectional rank Gaussianization.

Computes percentile ranks within each cross-section (see [`CSPercentileRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler)),
maps them through the inverse standard normal CDF $\Phi^{-1}$, and recenters
to weighted mean zero over the estimation universe. When `scale=True`, the result is
also rescaled to unit equal-weighted standard deviation.

When `cs_weights` is provided, the estimation universe is defined by
`cs_weights > 0`. Assets outside that universe still receive Gaussianized scores
relative to it. `cs_weights` is used to define the estimation universe and to
compute the final weighted recentering; ranking itself remains equal-weighted over
the selected assets.

NaNs are treated as missing values. They are ignored when computing cross-sectional
ranks and are preserved in the output.

For observation $t$, the Gaussianized value of asset $i$ is:

$$
z_{t,i} = \frac{\Phi^{-1}(p_{t,i}) - \mu_t}{\sigma_t}
$$

where $p_{t,i}$ is the percentile rank, $\mu_t$ the weighted mean of
$\Phi^{-1}(p_{t,\cdot})$ over the estimation universe, and
$\sigma_t$ its unbiased equal-weighted standard deviation. When `scale=False`,
the rescaling step is skipped and only weighted recentering is applied.

When `cs_groups` is provided, the same scheme is applied within each group. Groups
with fewer than `min_group_size` estimation assets, and missing groups
(`cs_groups == -1`), fall back to the global cross-section. Recentering and
rescaling are always performed over the full cross-section, not within groups.

This transformer is stateless.

* **Parameters:**
  **min_group_size** *int, default=8*
  : Minimum number of estimation assets required in a group. Smaller groups fall
    back to the global cross-section.

  **scale** *bool, default=True*
  : If True, rescale final exposures to unit equal-weighted standard deviation over
    the estimation universe. If False, only weighted recentering is applied.
    Use this when feeding the output to a scale-invariant downstream model
    (e.g. gradient-boosted trees) and you want to avoid injecting per-cross-section
    noise from the unbiased standard-deviation estimate.

  **atol** *float, default=1e-12*
  : Absolute tolerance used to guard against division by a near-zero equal-weighted
    standard deviation. Must be finite and non-negative.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler.fit)(X[, y, cs_weights, cs_groups])                 | Fit the transformer.                                                                   |
|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler.fit_transform)(X[, y, cs_weights, cs_groups])       | Fit to `X` and return the transformed values.                                          |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler.get_feature_names_out)([input_features])            | Get output feature names for transformation.                                           |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler.get_metadata_routing)()                             | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler.get_params)([deep])                                 | Get parameters for this estimator.                                                     |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler.set_fit_request)(\*[, cs_groups, cs_weights])       | Configure whether metadata should be requested to be passed to the `fit` method.       |
| [`set_params`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler.set_params)(\*\*params)                             | Set the parameters of this estimator.                                                  |
| [`set_transform_request`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler.set_transform_request)(\*[, cs_groups, cs_weights]) | Configure whether metadata should be requested to be passed to the `transform` method. |
| [`transform`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler.transform)(X[, cs_weights, cs_groups])              | Transform values into cross-sectional Gaussianized exposures.                          |

#### SEE ALSO
[`CSPercentileRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler)

[`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler)

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.preprocessing import CSGaussianRankScaler
>>>
>>> X = np.array([[1.0, np.nan, 3.0, 4.0],
...               [4.0, 3.0, 2.0, 1.0],
...               [10.0, 20.0, np.nan, 40.0]])
>>>
>>> transformer = CSGaussianRankScaler()
>>> transformer.fit_transform(X)
array([[-1.        ,         nan,  0.        ,  1.        ],
       [ 1.180302  ,  0.32693605, -0.32693605, -1.180302  ],
       [-1.        ,  0.        ,         nan,  1.        ]])
>>>
>>> # Use cs_weights for the estimation universe and weighted recentering, and rank within groups.
>>> cs_weights = np.array([[3.0, 0.0, 1.0, 2.0],
...                        [4.0, 0.0, 2.0, 3.0],
...                        [2.0, 3.0, 0.0, 5.0]])
>>> cs_groups = np.array([[0, 0, 1, 1],
...                       [0, 0, 1, 1],
...                       [0, 0, 1, 1]])
>>>
>>> transformer = CSGaussianRankScaler(min_group_size=2)
>>> transformer.fit_transform(X, cs_weights=cs_weights, cs_groups=cs_groups)
array([[-0.6791367 ,         nan, -0.34541391,  1.19141201],
       [ 0.69857792,  0.0863589 ,  0.36442412, -1.17438663],
       [-1.33305449,  0.13413753,         nan,  0.45273928]])
```

<a id="skfolio.preprocessing.CSGaussianRankScaler.fit"></a>

#### fit(X, y=None, cs_weights=None, cs_groups=None)

Fit the transformer.

Cross-sectional transformers are stateless and do not learn data-dependent
parameters. This method validates the estimator parameters, validates `X`, and
records `n_features_in_` for scikit-learn compatibility.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights accepted for API consistency with
    `transform`. They are ignored during fitting.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels accepted for API consistency with
    `transform`. They are ignored during fitting.
* **Returns:**
  **self** *BaseCSTransformer*
  : Fitted estimator.

<a id="skfolio.preprocessing.CSGaussianRankScaler.fit_transform"></a>

#### fit_transform(X, y=None, cs_weights=None, cs_groups=None)

Fit to `X` and return the transformed values.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights forwarded to `transform`.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels forwarded to `transform`.
* **Returns:**
  **X_new** *ndarray of shape (n_observations, n_assets)*
  : Transformed array.

<a id="skfolio.preprocessing.CSGaussianRankScaler.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Get output feature names for transformation.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Same as input features.

<a id="skfolio.preprocessing.CSGaussianRankScaler.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.preprocessing.CSGaussianRankScaler.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.preprocessing.CSGaussianRankScaler.set_fit_request"></a>

#### set_fit_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `fit`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.CSGaussianRankScaler.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.

<a id="skfolio.preprocessing.CSGaussianRankScaler.set_transform_request"></a>

#### set_transform_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `transform` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `transform` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `transform`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `transform`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `transform`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.CSGaussianRankScaler.transform"></a>

#### transform(X, cs_weights=None, cs_groups=None)

Transform values into cross-sectional Gaussianized exposures.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.
    NaNs are allowed and preserved.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional non-negative cross-sectional weights. They define the estimation
    universe through `cs_weights > 0` and drive the final weighted recentering.
    Ranking itself remains equal-weighted over the selected assets. If `None`,
    all finite assets are included in the estimation universe.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Integer group labels >= -1. Missing groups (`-1`) and groups with fewer than
    `min_group_size` estimation assets fall back to the global cross-section.
    If `None`, ranking is performed on the full cross-section of each
    observation.
* **Returns:**
  **Z** *ndarray of shape (n_observations, n_assets)*
  : Gaussianized exposures. Each cross-section has weighted mean zero over its
    estimation universe and, when `scale=True`, unit equal-weighted standard
    deviation. NaNs from `X` are preserved.
* **Raises:**
  ValueError
  : If `min_group_size` is not an integer `>= 1`, `atol` is not finite or
    `< 0`, `X` is not a non-empty 2D array, `cs_weights` is invalid, or
    `cs_groups` is invalid.

# generated/skfolio.preprocessing.CSPercentileRankScaler.html.md

<a id="skfolio-preprocessing-cspercentilerankscaler"></a>

# skfolio.preprocessing.CSPercentileRankScaler

<a id="skfolio.preprocessing.CSPercentileRankScaler"></a>

### *class* skfolio.preprocessing.CSPercentileRankScaler(\*, min_group_size=8)

Cross-sectional percentile rank.

Computes the percentile rank of each finite value within an observation’s
cross-section.

When `cs_weights` is provided, percentile ranks are estimated only on the estimation
universe, defined by `cs_weights > 0`. Assets outside that universe still receive
percentile ranks relative to it. For this estimator, `cs_weights` is used only to
define the estimation universe; percentile estimation itself remains equal-weighted
over the selected assets.

NaNs are treated as missing values. They are ignored when computing cross-sectional
ranks and are preserved in the output.

When `cs_groups` is `None`, ranks are computed globally within each observation
using the formula:

$$
p_{t,i} = \frac{r_{t,i} - 0.5}{N_{\mathcal{E}_t}}
$$

where $\mathcal{E}_t$ is the estimation universe at observation $t$,
$N_{\mathcal{E}_t}$ its size, and $r_{t,i} \in
[1, N_{\mathcal{E}_t}]$ is the rank of asset $i$ within that universe. Tied
values share the average of the ranks they would otherwise occupy (equivalent to
`scipy.stats.rankdata(method="average")`).

The $-0.5$ shift centers the rank inside its bin, so percentiles sit strictly
in $(0, 1)$, on the closed interval
$[0.5 / N_{\mathcal{E}_t},\, 1 - 0.5 / N_{\mathcal{E}_t}]$. This keeps
downstream inverse-normal mappings always finite.

When `cs_groups` is provided, the same ranking scheme is applied within each group.
Groups with fewer than `min_group_size` estimation assets, and missing groups
(`cs_groups == -1`), fall back to the global cross-section.

This transformer is stateless.

* **Parameters:**
  **min_group_size** *int, default=8*
  : Minimum number of estimation assets required in a group. Smaller groups fall
    back to the global cross-section.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler.fit)(X[, y, cs_weights, cs_groups])                 | Fit the transformer.                                                                   |
|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler.fit_transform)(X[, y, cs_weights, cs_groups])       | Fit to `X` and return the transformed values.                                          |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler.get_feature_names_out)([input_features])            | Get output feature names for transformation.                                           |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler.get_metadata_routing)()                             | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler.get_params)([deep])                                 | Get parameters for this estimator.                                                     |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler.set_fit_request)(\*[, cs_groups, cs_weights])       | Configure whether metadata should be requested to be passed to the `fit` method.       |
| [`set_params`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler.set_params)(\*\*params)                             | Set the parameters of this estimator.                                                  |
| [`set_transform_request`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler.set_transform_request)(\*[, cs_groups, cs_weights]) | Configure whether metadata should be requested to be passed to the `transform` method. |
| [`transform`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler.transform)(X[, cs_weights, cs_groups])              | Transform values into cross-sectional percentile ranks.                                |

#### SEE ALSO
[`CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler)

[`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler)

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.preprocessing import CSPercentileRankScaler
>>>
>>> X = np.array([[1.0, np.nan, 3.0, 4.0],
...               [4.0, 3.0, 2.0, 1.0],
...               [10.0, 20.0, np.nan, 40.0]])
>>>
>>> transformer = CSPercentileRankScaler()
>>> transformer.fit_transform(X)
array([[0.16666667,        nan, 0.5       , 0.83333333],
       [0.875     , 0.625     , 0.375     , 0.125     ],
       [0.16666667, 0.5       ,        nan, 0.83333333]])
>>>
>>> # Restrict the estimation universe with cs_weights and rank within groups.
>>> cs_weights = np.array([[1.0, 0.0, 1.0, 1.0],
...                        [1.0, 0.0, 1.0, 1.0],
...                        [1.0, 1.0, 0.0, 1.0]])
>>> cs_groups = np.array([[0, 0, 1, 1],
...                       [0, 0, 1, 1],
...                       [0, 0, 1, 1]])
>>>
>>> transformer = CSPercentileRankScaler(min_group_size=2)
>>> transformer.fit_transform(X, cs_weights=cs_weights, cs_groups=cs_groups)
array([[0.16666667,        nan, 0.25      , 0.75      ],
       [0.83333333, 0.66666667, 0.75      , 0.25      ],
       [0.25      , 0.75      ,        nan, 0.83333333]])
```

<a id="skfolio.preprocessing.CSPercentileRankScaler.fit"></a>

#### fit(X, y=None, cs_weights=None, cs_groups=None)

Fit the transformer.

Cross-sectional transformers are stateless and do not learn data-dependent
parameters. This method validates the estimator parameters, validates `X`, and
records `n_features_in_` for scikit-learn compatibility.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights accepted for API consistency with
    `transform`. They are ignored during fitting.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels accepted for API consistency with
    `transform`. They are ignored during fitting.
* **Returns:**
  **self** *BaseCSTransformer*
  : Fitted estimator.

<a id="skfolio.preprocessing.CSPercentileRankScaler.fit_transform"></a>

#### fit_transform(X, y=None, cs_weights=None, cs_groups=None)

Fit to `X` and return the transformed values.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights forwarded to `transform`.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels forwarded to `transform`.
* **Returns:**
  **X_new** *ndarray of shape (n_observations, n_assets)*
  : Transformed array.

<a id="skfolio.preprocessing.CSPercentileRankScaler.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Get output feature names for transformation.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Same as input features.

<a id="skfolio.preprocessing.CSPercentileRankScaler.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.preprocessing.CSPercentileRankScaler.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.preprocessing.CSPercentileRankScaler.set_fit_request"></a>

#### set_fit_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `fit`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.CSPercentileRankScaler.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.

<a id="skfolio.preprocessing.CSPercentileRankScaler.set_transform_request"></a>

#### set_transform_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `transform` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `transform` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `transform`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `transform`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `transform`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.CSPercentileRankScaler.transform"></a>

#### transform(X, cs_weights=None, cs_groups=None)

Transform values into cross-sectional percentile ranks.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.
    NaNs are allowed and preserved.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional non-negative cross-sectional weights used only to define the
    estimation universe through the convention `cs_weights > 0`. Percentile
    ranks are then estimated in an equal-weighted way over the selected
    assets. Non-estimation assets still receive percentile ranks relative to
    that universe. If `None`, all finite assets are included in the
    estimation universe.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Integer group labels >= -1. Missing groups (`-1`) and groups with fewer
    than `min_group_size` estimation assets fall back to the global
    cross-section. If `None`, ranking is performed globally within each
    observation.
* **Returns:**
  **P** *ndarray of shape (n_observations, n_assets)*
  : Percentile ranks in
    $[0.5 / N_{\mathcal{E}_t},\, 1 - 0.5 / N_{\mathcal{E}_t}]$, where
    $N_{\mathcal{E}_t}$ is the size of the cross-section or group fallback
    used at observation $t$. NaNs from `X` are preserved.
* **Raises:**
  ValueError
  : If `min_group_size` is not an integer `>= 1`, `X` is not a non-empty 2D
    array, `cs_weights` is invalid, or `cs_groups` is invalid.

# generated/skfolio.preprocessing.CSStandardScaler.html.md

<a id="skfolio-preprocessing-csstandardscaler"></a>

# skfolio.preprocessing.CSStandardScaler

<a id="skfolio.preprocessing.CSStandardScaler"></a>

### *class* skfolio.preprocessing.CSStandardScaler(\*, min_group_size=8, atol=1e-12)

Cross-sectional standardization.

Standardizes each finite value within an observation’s cross-section to have
weighted mean zero and unit equal-weighted standard deviation over the estimation
universe.

When `cs_weights` is provided, weighted means and unbiased equal-weighted standard
deviations are estimated only on the estimation universe, defined by
`cs_weights > 0`. Assets outside that universe still receive standardized values
relative to the estimation universe. For this estimator, `cs_weights` is used to
define the estimation universe and to compute the cross-sectional mean, while the
standard deviation remains equal-weighted over the selected assets.

NaNs are treated as missing values. They are ignored when computing cross-sectional
statistics and are preserved in the output.

When `cs_groups` is `None`, standardization is performed globally within each
observation. For observation $t$, the standardized value $z_{t,i}$ is
defined by:

$$
z_{t,i} = \frac{x_{t,i} - \mu_t}{\sigma_t}
$$

where $\mu_t$ is the weighted mean,
$\sigma_t$ is the unbiased equal-weighted standard deviation,
$\mathcal{E}_t$ is the estimation universe, and
$N_{\mathcal{E}_t}$ is its number of assets:

$$
\mu_t = \frac{\sum_{i \in \mathcal{E}_t} w_{t,i} x_{t,i}}
             {\sum_{i \in \mathcal{E}_t} w_{t,i}},
\quad
\sigma_t = \sqrt{\frac{1}{N_{\mathcal{E}_t} - 1}
           \sum_{i \in \mathcal{E}_t} (x_{t,i} - \mu_t)^2}
$$

When `cs_groups` is provided, the same centering and scaling scheme is first applied
within each group. Groups with fewer than `min_group_size` estimation assets, and
missing groups (`cs_groups == -1`), fall back to global cross-sectional statistics.
The grouped result is then globally recentered to weighted mean zero and globally
rescaled to unit equal-weighted standard deviation over the estimation universe.

This transformer is stateless.

* **Parameters:**
  **min_group_size** *int, default=8*
  : Minimum number of estimation assets required in a group. Smaller groups fall
    back to global cross-sectional statistics.

  **atol** *float, default=1e-12*
  : Absolute tolerance below which the cross-sectional standard deviation is treated
    as zero. When `cs_groups` is `None`, this means that the observation has no
    measurable cross-sectional dispersion on its estimation universe, so finite
    outputs are set to zero rather than `NaN` and the row is treated as a neutral
    exposure. When `cs_groups` is provided, the same convention applies to the
    within-group standardization step and to the final global rescaling step.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler.fit)(X[, y, cs_weights, cs_groups])                 | Fit the transformer.                                                                   |
|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler.fit_transform)(X[, y, cs_weights, cs_groups])       | Fit to `X` and return the transformed values.                                          |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler.get_feature_names_out)([input_features])            | Get output feature names for transformation.                                           |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler.get_metadata_routing)()                             | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler.get_params)([deep])                                 | Get parameters for this estimator.                                                     |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler.set_fit_request)(\*[, cs_groups, cs_weights])       | Configure whether metadata should be requested to be passed to the `fit` method.       |
| [`set_params`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler.set_params)(\*\*params)                             | Set the parameters of this estimator.                                                  |
| [`set_transform_request`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler.set_transform_request)(\*[, cs_groups, cs_weights]) | Configure whether metadata should be requested to be passed to the `transform` method. |
| [`transform`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler.transform)(X[, cs_weights, cs_groups])              | Standardize each observation into cross-sectional z-scores.                            |

#### SEE ALSO
[`CSPercentileRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler)

[`CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler)

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.preprocessing import CSStandardScaler
>>>
>>> X = np.array([[1.0, np.nan, 3.0, 4.0],
...               [4.0, 3.0, 2.0, 1.0],
...               [10.0, 20.0, np.nan, 40.0]])
>>>
>>> transformer = CSStandardScaler()
>>> transformer.fit_transform(X)
array([[-1.09108945,         nan,  0.21821789,  0.87287156],
       [ 1.161895  ,  0.38729833, -0.38729833, -1.161895  ],
       [-0.87287156, -0.21821789,         nan,  1.09108945]])
>>>
>>> # Use cs_weights for the estimation universe and weighted means, then standardize within groups.
>>> cs_weights = np.array([[3.0, 0.0, 1.0, 2.0],
...                        [4.0, 0.0, 2.0, 3.0],
...                        [2.0, 3.0, 0.0, 5.0]])
>>> cs_groups = np.array([[0, 0, 1, 1],
...                       [0, 0, 1, 1],
...                       [0, 0, 1, 1]])
>>>
>>> transformer = CSStandardScaler(min_group_size=2)
>>> transformer.fit_transform(X, cs_weights=cs_weights, cs_groups=cs_groups)
array([[-0.55454325,         nan, -0.62182063,  1.1427252 ],
       [ 0.62254586, -0.15324206,  0.5035012 , -1.16572861],
       [-1.33736075,  0.20821245,         nan,  0.41001683]])
```

<a id="skfolio.preprocessing.CSStandardScaler.fit"></a>

#### fit(X, y=None, cs_weights=None, cs_groups=None)

Fit the transformer.

Cross-sectional transformers are stateless and do not learn data-dependent
parameters. This method validates the estimator parameters, validates `X`, and
records `n_features_in_` for scikit-learn compatibility.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights accepted for API consistency with
    `transform`. They are ignored during fitting.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels accepted for API consistency with
    `transform`. They are ignored during fitting.
* **Returns:**
  **self** *BaseCSTransformer*
  : Fitted estimator.

<a id="skfolio.preprocessing.CSStandardScaler.fit_transform"></a>

#### fit_transform(X, y=None, cs_weights=None, cs_groups=None)

Fit to `X` and return the transformed values.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights forwarded to `transform`.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels forwarded to `transform`.
* **Returns:**
  **X_new** *ndarray of shape (n_observations, n_assets)*
  : Transformed array.

<a id="skfolio.preprocessing.CSStandardScaler.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Get output feature names for transformation.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Same as input features.

<a id="skfolio.preprocessing.CSStandardScaler.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.preprocessing.CSStandardScaler.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.preprocessing.CSStandardScaler.set_fit_request"></a>

#### set_fit_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `fit`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.CSStandardScaler.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.

<a id="skfolio.preprocessing.CSStandardScaler.set_transform_request"></a>

#### set_transform_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `transform` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `transform` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `transform`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `transform`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `transform`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.CSStandardScaler.transform"></a>

#### transform(X, cs_weights=None, cs_groups=None)

Standardize each observation into cross-sectional z-scores.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row represents an observation and
    each column represents an asset. NaNs are allowed and
    preserved.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional non-negative cross-sectional weights. Positive
    weights define the estimation universe and are used to
    compute weighted means. The standard deviation remains
    equal-weighted over the selected assets. If `None`, all
    finite assets are included in the estimation universe with
    unit weight.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Integer group labels >= -1. Missing groups (`-1`) and
    groups with fewer than `min_group_size` estimation assets
    fall back to global cross-sectional statistics. If `None`,
    standardization is performed globally within each
    observation.
* **Returns:**
  **Z** *ndarray of shape (n_observations, n_assets)*
  : Standardized values with weighted mean zero and unit
    equal-weighted standard deviation over the estimation
    universe.
* **Raises:**
  ValueError
  : If `min_group_size < 1`, `atol < 0`, `X` is not a non-empty
    2D array, `cs_weights` is invalid, or `cs_groups` is invalid.

# generated/skfolio.preprocessing.CSTanhShrinker.html.md

<a id="skfolio-preprocessing-cstanhshrinker"></a>

# skfolio.preprocessing.CSTanhShrinker

<a id="skfolio.preprocessing.CSTanhShrinker"></a>

### *class* skfolio.preprocessing.CSTanhShrinker(\*, knee=3.0, atol=1e-12)

Cross-sectional tanh outlier shrinker.

Smoothly shrinks extreme values within an observation toward the cross-sectional
center while preserving the original scale and units of the input values. Values
near the center are left nearly unchanged, while extreme values are compressed
inward.

NaNs are treated as missing values. They are ignored when computing the
cross-sectional median and MAD and are preserved in the output.

Compared to winsorization ([`CSWinsorizer`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer)):

* No hard threshold. The mapping is smooth, so small data changes do not create
  discontinuous jumps at a clipping boundary.
* Strict monotonicity. Tail ordering is preserved because distinct inputs remain
  distinct after transformation.
* Smooth transformed values. This can lead to better-conditioned cross-sectional
  regressions and more stable coefficient estimates in downstream models.

For observation $t$ with cross-section $\mathbf{x}_t$, the
transformation is

$$
x_{t,i}' = m_t + h_t \cdot \tanh\!\left(\frac{x_{t,i} - m_t}{h_t}\right),
\quad
h_t = c \cdot s_t
$$

where $m_t = \operatorname{median}(\mathbf{x}_t)$,
$s_t = 1.4826 \cdot \operatorname{MAD}(\mathbf{x}_t)$ is a robust scale
estimator consistent for the standard deviation under normality, and $c$ is
the knee parameter (see `knee`). The quantity $h_t = c \cdot s_t$ is the half-width
of the near-linear region for observation $t$.

When `cs_weights` is provided, median and MAD are computed from the estimation
universe, defined by `cs_weights > 0`. Assets outside the estimation universe still
receive shrunk values using those statistics. For this estimator, `cs_weights` is
used only to define the estimation universe; the median and MAD remain
equal-weighted over the selected assets.

This transformer is stateless.

* **Parameters:**
  **knee** *float, default=3.0*
  : Compression knee in robust standard deviations. It controls the width of the
    near-linear region around the median. Larger values reduce shrinkage. Must be
    finite and strictly positive.

  **atol** *float, default=1e-12*
  : Absolute tolerance for the robust scale. If $s$ is below `atol`, the
    observation is returned unchanged. Must be finite and non-negative.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker.fit)(X[, y, cs_weights, cs_groups])                 | Fit the transformer.                                                                   |
|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker.fit_transform)(X[, y, cs_weights, cs_groups])       | Fit to `X` and return the transformed values.                                          |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker.get_feature_names_out)([input_features])            | Get output feature names for transformation.                                           |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker.get_metadata_routing)()                             | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker.get_params)([deep])                                 | Get parameters for this estimator.                                                     |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker.set_fit_request)(\*[, cs_groups, cs_weights])       | Configure whether metadata should be requested to be passed to the `fit` method.       |
| [`set_params`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker.set_params)(\*\*params)                             | Set the parameters of this estimator.                                                  |
| [`set_transform_request`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker.set_transform_request)(\*[, cs_groups, cs_weights]) | Configure whether metadata should be requested to be passed to the `transform` method. |
| [`transform`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker.transform)(X[, cs_weights, cs_groups])              | Shrink outliers within each observation using a tanh mapping.                          |

#### SEE ALSO
[`CSWinsorizer`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer)
: Hard percentile-based clipping.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.preprocessing import CSTanhShrinker
>>>
>>> X = np.array([[1.0, np.nan, 3.0, 4.0],
...               [4.0, 3.0, 2.0, 1.0],
...               [10.0, 20.0, np.nan, 40.0]])
>>>
>>> transformer = CSTanhShrinker()
>>> transformer.fit_transform(X)
array([[ 1.12471866,         nan,  3.        ,  3.98348436],
       [ 3.94560619,  2.99790441,  2.00209559,  1.05439381],
       [10.16515641, 20.        ,         nan, 38.75281341]])
>>>
>>> # Use cs_weights for the estimation universe before computing the median and MAD.
>>> cs_weights = np.array([[1.0, 0.0, 1.0, 1.0],
...                        [1.0, 0.0, 1.0, 1.0],
...                        [1.0, 1.0, 0.0, 1.0]])
>>>
>>> transformer.fit_transform(X, cs_weights=cs_weights)
array([[ 1.12471866,         nan,  3.        ,  3.98348436],
       [ 3.87528134,  2.98348436,  2.        ,  1.01651564],
       [10.16515641, 20.        ,         nan, 38.75281341]])
```

<a id="skfolio.preprocessing.CSTanhShrinker.fit"></a>

#### fit(X, y=None, cs_weights=None, cs_groups=None)

Fit the transformer.

Cross-sectional transformers are stateless and do not learn data-dependent
parameters. This method validates the estimator parameters, validates `X`, and
records `n_features_in_` for scikit-learn compatibility.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights accepted for API consistency with
    `transform`. They are ignored during fitting.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels accepted for API consistency with
    `transform`. They are ignored during fitting.
* **Returns:**
  **self** *BaseCSTransformer*
  : Fitted estimator.

<a id="skfolio.preprocessing.CSTanhShrinker.fit_transform"></a>

#### fit_transform(X, y=None, cs_weights=None, cs_groups=None)

Fit to `X` and return the transformed values.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights forwarded to `transform`.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels forwarded to `transform`.
* **Returns:**
  **X_new** *ndarray of shape (n_observations, n_assets)*
  : Transformed array.

<a id="skfolio.preprocessing.CSTanhShrinker.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Get output feature names for transformation.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Same as input features.

<a id="skfolio.preprocessing.CSTanhShrinker.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.preprocessing.CSTanhShrinker.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.preprocessing.CSTanhShrinker.set_fit_request"></a>

#### set_fit_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `fit`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.CSTanhShrinker.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.

<a id="skfolio.preprocessing.CSTanhShrinker.set_transform_request"></a>

#### set_transform_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `transform` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `transform` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `transform`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `transform`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `transform`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.CSTanhShrinker.transform"></a>

#### transform(X, cs_weights=None, cs_groups=None)

Shrink outliers within each observation using a tanh mapping.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.
    NaNs are allowed and preserved.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional non-negative cross-sectional weights used only to define the
    estimation universe through the convention `cs_weights > 0`. The median and
    MAD are then computed in an equal-weighted way over the selected assets.
    Non-estimation assets still receive shrunk values using those statistics.
    If `None`, all finite assets are used.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Not used, present for API consistency by convention.
* **Returns:**
  **X_shrunk** *ndarray of shape (n_observations, n_assets)*
  : Shrunk values in the original scale. NaN values from the input are preserved.
* **Raises:**
  ValueError
  : If `knee` is not finite or `<= 0`, `atol` is not finite or `< 0`, `X` is
    not a non-empty 2D array, or `cs_weights` is invalid.

# generated/skfolio.preprocessing.CSWinsorizer.html.md

<a id="skfolio-preprocessing-cswinsorizer"></a>

# skfolio.preprocessing.CSWinsorizer

<a id="skfolio.preprocessing.CSWinsorizer"></a>

### *class* skfolio.preprocessing.CSWinsorizer(\*, low=0.01, high=0.99)

Cross-sectional winsorization.

Clips each finite value within an observation to the interval between the `low` and
`high` percentiles of that observation’s cross-section.

NaNs are treated as missing values. They are ignored when computing cross-sectional
percentiles and are preserved in the output.

When `cs_weights` is provided, percentile boundaries are computed on the estimation
universe, defined by `cs_weights > 0`. Assets outside the estimation universe still
receive clipped values using those boundaries. For this estimator, `cs_weights` is
used only to define the estimation universe; percentile estimation itself remains
equal-weighted over the selected assets.

This transformer is stateless.

* **Parameters:**
  **low** *float, default=0.01*
  : Lower percentile used for clipping.
    Must satisfy $0 \le \text{low} < \text{high} \le 1$.

  **high** *float, default=0.99*
  : Upper percentile used for clipping.
    Must satisfy $0 \le \text{low} < \text{high} \le 1$.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer.fit)(X[, y, cs_weights, cs_groups])                 | Fit the transformer.                                                                   |
|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| [`fit_transform`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer.fit_transform)(X[, y, cs_weights, cs_groups])       | Fit to `X` and return the transformed values.                                          |
| [`get_feature_names_out`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer.get_feature_names_out)([input_features])            | Get output feature names for transformation.                                           |
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer.get_metadata_routing)()                             | Get metadata routing of this object.                                                   |
| [`get_params`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer.get_params)([deep])                                 | Get parameters for this estimator.                                                     |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer.set_fit_request)(\*[, cs_groups, cs_weights])       | Configure whether metadata should be requested to be passed to the `fit` method.       |
| [`set_params`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer.set_params)(\*\*params)                             | Set the parameters of this estimator.                                                  |
| [`set_transform_request`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer.set_transform_request)(\*[, cs_groups, cs_weights]) | Configure whether metadata should be requested to be passed to the `transform` method. |
| [`transform`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer.transform)(X[, cs_weights, cs_groups])              | Winsorize each observation to low/high percentiles.                                    |

#### SEE ALSO
[`CSTanhShrinker`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker)
: Smoothly shrinks extreme values.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.preprocessing import CSWinsorizer
>>>
>>> X = np.array([[1.0, np.nan, 3.0, 4.0],
...               [4.0, 3.0, 2.0, 1.0],
...               [10.0, 20.0, np.nan, 40.0]])
>>>
>>> transformer = CSWinsorizer(low=0.1, high=0.9)
>>> transformer.fit_transform(X)
array([[ 1.4,  nan,  3. ,  3.8],
       [ 3.7,  3. ,  2. ,  1.3],
       [12. , 20. ,  nan, 36. ]])
>>>
>>> # Use cs_weights for the estimation universe before computing the clip bounds.
>>> cs_weights = np.array([[1.0, 0.0, 1.0, 1.0],
...                        [1.0, 0.0, 1.0, 1.0],
...                        [1.0, 1.0, 0.0, 1.0]])
>>>
>>> transformer.fit_transform(X, cs_weights=cs_weights)
array([[ 1.4,  nan,  3. ,  3.8],
       [ 3.6,  3. ,  2. ,  1.2],
       [12. , 20. ,  nan, 36. ]])
```

<a id="skfolio.preprocessing.CSWinsorizer.fit"></a>

#### fit(X, y=None, cs_weights=None, cs_groups=None)

Fit the transformer.

Cross-sectional transformers are stateless and do not learn data-dependent
parameters. This method validates the estimator parameters, validates `X`, and
records `n_features_in_` for scikit-learn compatibility.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights accepted for API consistency with
    `transform`. They are ignored during fitting.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels accepted for API consistency with
    `transform`. They are ignored during fitting.
* **Returns:**
  **self** *BaseCSTransformer*
  : Fitted estimator.

<a id="skfolio.preprocessing.CSWinsorizer.fit_transform"></a>

#### fit_transform(X, y=None, cs_weights=None, cs_groups=None)

Fit to `X` and return the transformed values.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.

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

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional weights forwarded to `transform`.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Optional cross-sectional group labels forwarded to `transform`.
* **Returns:**
  **X_new** *ndarray of shape (n_observations, n_assets)*
  : Transformed array.

<a id="skfolio.preprocessing.CSWinsorizer.get_feature_names_out"></a>

#### get_feature_names_out(input_features=None)

Get output feature names for transformation.

* **Parameters:**
  **input_features** *array-like of str or None, default=None*
  : Input features.
    - If `input_features` is `None`, then `feature_names_in_` is
      used as feature names in. If `feature_names_in_` is not defined,
      then the following input feature names are generated:
      `["x0", "x1", ..., "x(n_features_in_ - 1)"]`.
    - If `input_features` is an array-like, then `input_features` must
      match `feature_names_in_` if `feature_names_in_` is defined.
* **Returns:**
  **feature_names_out** *ndarray of str objects*
  : Same as input features.

<a id="skfolio.preprocessing.CSWinsorizer.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.preprocessing.CSWinsorizer.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.preprocessing.CSWinsorizer.set_fit_request"></a>

#### set_fit_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `fit`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.CSWinsorizer.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.

<a id="skfolio.preprocessing.CSWinsorizer.set_transform_request"></a>

#### set_transform_request(\*, cs_groups='$UNCHANGED$', cs_weights='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `transform` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `transform` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `transform`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **cs_groups** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_groups` parameter in `transform`.

  **cs_weights** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `cs_weights` parameter in `transform`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.preprocessing.CSWinsorizer.transform"></a>

#### transform(X, cs_weights=None, cs_groups=None)

Winsorize each observation to low/high percentiles.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Input matrix where each row is an observation and each column is an asset.
    NaNs are allowed and preserved.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Optional non-negative cross-sectional weights used only to define the
    estimation universe through the convention `cs_weights > 0`. Percentile
    boundaries are then estimated in an equal-weighted way over the selected
    assets. Non-estimation assets still receive clipped values using those
    boundaries. If `None`, all finite assets are used to compute percentiles.

  **cs_groups** *array-like of shape (n_observations, n_assets), optional*
  : Not used, present for API consistency by convention.
* **Returns:**
  **X_clipped** *ndarray of shape (n_observations, n_assets)*
  : Winsorized values. NaN values from the input are preserved.
* **Raises:**
  ValueError
  : If `low` / `high` are invalid, `X` is not a non-empty 2D array, or
    `cs_weights` is invalid.

# generated/skfolio.preprocessing.prices_to_returns.html.md

<a id="skfolio-preprocessing-prices-to-returns"></a>

# skfolio.preprocessing.prices_to_returns

<a id="skfolio.preprocessing.prices_to_returns"></a>

### skfolio.preprocessing.prices_to_returns(X, y=None, log_returns=False, nan_threshold=1, join='outer', drop_inceptions_nan=True, fill_nan=True)

Transform a DataFrame of prices to linear or logarithmic returns.

Linear returns (also called simple returns) are defined as:
: $$
  \frac{S_{t}}{S_{t-1}} - 1
  <br/>
  $$

Logarithmic returns (also called continuously compounded return) are defined as:
: $$
  ln\Biggl(\frac{S_{t}}{S_{t-1}}\Biggr)
  <br/>
  $$

With $S_{t}$ the asset price at time $t$.

#### WARNING
The linear returns aggregate across securities, meaning that the linear return
of the portfolio is the weighted average of the linear returns of the
securities. For this reason, **portfolio optimization should be performed
using linear returns** [[1]](https://skfolio.org/generated/skfolio.preprocessing.prices_to_returns.html.md#r9af81b715b17-1).

On the other hand, the logarithmic returns aggregate across time, meaning that
the total logarithmic return over K time periods is the sum of all K
single-period logarithmic returns.

#### SEE ALSO
[data preparation](https://skfolio.org/user_guide/data_preparation.html.md#data-preparation)

* **Parameters:**
  **X** *DataFrame*
  : The DataFrame of assets prices.

  **y** *DataFrame, optional*
  : The DataFrame of target or factors prices.
    If provided, it is joined with the DataFrame of prices to ensure identical
    observations.

  **log_returns** *bool, default=False*
  : If this is set to True, logarithmic returns are used instead of simple returns.

  **join** *str, default=”outer”*
  : The join method between `X` and `y` when `y` is provided.

  **nan_threshold** *float, default=1.0*
  : Drop observations (rows) that have a percentage of missing assets prices above
    this threshold. The default (`1.0`) is to keep all the observations.

  **drop_inceptions_nan** *bool, default=True*
  : If set to True, observations at the beginning are dropped if any of
    the asset values are missing, otherwise we keep the NaNs. This is useful when
    you work with a large universe of assets with different inception dates coupled
    with a pre-selection Transformer.

  **fill_nan** *bool, default=True*
  : If set to True, missing prices (NaNs) are forward filled using the previous
    price. Otherwise, NaNs are kept.
* **Returns:**
  **X** *DataFrame*
  : The DataFrame of price returns of the input `X`.

  **y** *DataFrame, optional*
  : The DataFrame of price returns of the input `y` when provided.

### References

* <a id='r9af81b715b17-1'>**[1]**</a> “Linear vs. Compounded Returns - Common Pitfalls in Portfolio Management”. GARP Risk Professional. Attilio Meucci (2010).

# generated/skfolio.prior.BaseLoadingMatrix.html.md

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

# skfolio.prior.BaseLoadingMatrix

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

### *class* skfolio.prior.BaseLoadingMatrix

Base class for all Loading Matrix estimators.

### Methods

| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.prior.BaseLoadingMatrix.html.md#skfolio.prior.BaseLoadingMatrix.get_metadata_routing)()   | Get metadata routing of this object.   |
|---------------------------------------------------------------------------|----------------------------------------|
| [`get_params`](https://skfolio.org/generated/skfolio.prior.BaseLoadingMatrix.html.md#skfolio.prior.BaseLoadingMatrix.get_params)([deep])       | Get parameters for this estimator.     |
| [`set_params`](https://skfolio.org/generated/skfolio.prior.BaseLoadingMatrix.html.md#skfolio.prior.BaseLoadingMatrix.set_params)(\*\*params)   | Set the parameters of this estimator.  |

| **fit**   |    |
|-----------|----|

### Notes

All estimators should specify all the parameters that can be set
at the class level in their `__init__` as explicit keyword
arguments (no `*args` or `**kwargs`).

<a id="skfolio.prior.BaseLoadingMatrix.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.BaseLoadingMatrix.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.BaseLoadingMatrix.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.

# generated/skfolio.prior.BasePrior.html.md

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

# skfolio.prior.BasePrior

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

### *class* skfolio.prior.BasePrior

Base class for all prior estimators in skfolio.

### Methods

| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.prior.BasePrior.html.md#skfolio.prior.BasePrior.get_metadata_routing)()   | Get metadata routing of this object.   |
|---------------------------------------------------------------------------|----------------------------------------|
| [`get_params`](https://skfolio.org/generated/skfolio.prior.BasePrior.html.md#skfolio.prior.BasePrior.get_params)([deep])       | Get parameters for this estimator.     |
| [`set_params`](https://skfolio.org/generated/skfolio.prior.BasePrior.html.md#skfolio.prior.BasePrior.set_params)(\*\*params)   | Set the parameters of this estimator.  |

| **fit**   |    |
|-----------|----|

### Notes

All estimators should specify all the parameters that can be set
at the class level in their `__init__` as explicit keyword
arguments (no `*args` or `**kwargs`).

<a id="skfolio.prior.BasePrior.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.BasePrior.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.BasePrior.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.

# generated/skfolio.prior.BlackLitterman.html.md

<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]](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#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]](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#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`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman.fit)(X[, y])            | Fit the Black & Litterman estimator.   |
|-------------------------------------------------------------------------|----------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman.get_metadata_routing)() | Get metadata routing of this object.   |
| [`get_params`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman.get_params)([deep])     | Get parameters for this estimator.     |
| [`set_params`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#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.

# generated/skfolio.prior.CharacteristicsFactorModel.html.md

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

# skfolio.prior.CharacteristicsFactorModel

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

### *class* skfolio.prior.CharacteristicsFactorModel(\*, factors, currency_factor=None, exposure_lag=1, cs_regressor=None, neutralize_against=None, constrained_families=None, benchmark_mcap_power=1.0, regression_mcap_power=0.5, inv_idio_variance_weight_shrinkage=0.0, inv_idio_variance_max_weight_ratio=20.0, factor_prior_estimator=None, alpha_estimator=None, spanned_alpha_shrinkage=1.0, orthogonal_alpha_confidence=1.0, idio_variance_estimator=None, idio_corr_estimator=None, idio_corr_threshold=0.0, max_history=None, min_regression_assets=None, n_jobs=1)

Characteristics-based cross-sectional factor model.

`CharacteristicsFactorModel` estimates a point-in-time, cross-sectional equity
factor model from asset characteristics stored in an
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) [[1]](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#r3935960e9387-1).

The model is fitted as follows:

1. Start from point-in-time asset characteristics stored as panel fields (e.g.,
   `returns`, `market_cap`, `book_equity`, `industry`, `country`).
2. Compute descriptor values from these fields, or pass through existing fields
   unchanged, using descriptor estimators (e.g.
   [`BookToPrice`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice),
   [`EWMomentum`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum),
   [`Passthrough`](https://skfolio.org/generated/skfolio.descriptor.Passthrough.html.md#skfolio.descriptor.Passthrough)).
3. Build factor exposures. Style factors are typically formed by combining one or
   more descriptors and applying cross-sectional transformation such as
   winsorization and z-scoring, for example with
   [`FixedWeightedFactor`](https://skfolio.org/generated/skfolio.factor_exposure.FixedWeightedFactor.html.md#skfolio.factor_exposure.FixedWeightedFactor). Categorical
   factors (e.g. industry, country, currency) are represented by one-hot exposures
   with [`OneHotCategoricalFactors`](https://skfolio.org/generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md#skfolio.factor_exposure.OneHotCategoricalFactors).
4. Orthogonalize selected exposures against other factors or families when
   `neutralize_against` is provided.
5. Reparameterize constrained families when `constrained_families` is
   provided. This enforces the benchmark-weighted zero-sum constraint on factor
   returns within each constrained family and produces a full-rank basis for
   factor-level estimators, such as the factor covariance estimator.
6. Lag exposures by `exposure_lag` periods and estimate realized factor returns
   with `cs_regressor` on the estimation universe defined by the panel’s
   `estimation_mask`. By default, regression weights are based on market
   capitalization through `regression_mcap_power`. When
   `inv_idio_variance_weight_shrinkage > 0`, a two-pass procedure blends those
   weights with inverse-idiosyncratic-variance weights estimated from first-pass
   residuals.
7. Estimate the factor return distribution with `factor_prior_estimator`,
   including expected factor returns (factor premia), factor covariance, and factor
   return scenarios. This step can introduce factor covariance shrinkage,
   short-term volatility updating, or Newey-West HAC correction.
8. Estimate idiosyncratic variances with `idio_variance_estimator`, then form
   the idiosyncratic covariance as a diagonal matrix or, when
   `idio_corr_threshold > 0`, as a sparse covariance using correlation thresholding.
9. If provided, fit `alpha_estimator` to produce an alpha forecast. Decompose it
   into factor-spanned and orthogonal alphas, blend factor-implied asset expected
   returns with the spanned alpha using `spanned_alpha_shrinkage`, shrink the
   orthogonal alpha with `orthogonal_alpha_confidence` and assemble the final
   $\mu$, $\Sigma$ and asset return scenarios on the investment
   universe.

For asset $i$ and observation $t$, factor returns are estimated from the
cross-sectional regression

$$
R_i(t) = B_i(t - \ell)\,f(t) + \epsilon_i(t)
$$

where $R_i(t)$ is the local excess return, $B_i(t-\ell)$ denotes
asset $i$’s factor exposure vector, $f(t)$ is the vector of realized
factor returns, $\ell$ is the exposure lag and $\epsilon_i(t)$ is the
idiosyncratic return.

At each observation, this regression estimates realized factor returns and
idiosyncratic returns [[2]](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#r3935960e9387-2). Expected asset returns are subsequently constructed from
expected factor returns and, when configured, an alpha forecast.

The estimator follows skfolio’s as-of time-indexing convention: all time-varying
inputs at observation $t$ reflect information available up to and including
the end of period $t$. Point-in-time fields and derived values store the
latest available value for observation $t$. Returns stored at observation
$t$ cover the period ending at $t$, namely $(t-1, t]$.

Factor-return regressions estimate the factor returns realized over
$(t-1, t]$. The exposure matrix must therefore describe the assets before
that return interval begins. `exposure_lag` selects that exposure date.

The fitted covariance uses the latest available exposures $B(T)$:

$$
\Sigma = B(T)\,F\,B(T)^\top + D
$$

where $F$ is the factor return covariance and $D$ is the idiosyncratic
covariance.

With the default settings and no alpha estimator, the fitted expected-return vector
is $\mu = B(T)\,\mu_f$, where $\mu_f$ contains expected factor returns.
When an alpha estimator is provided, its forecast is decomposed as

$$
\alpha = \alpha^{\parallel} + \alpha^{\perp},
\qquad
\alpha^{\parallel} = B(T)\,g
$$

where $\alpha^{\parallel}$ is the spanned alpha and
$\alpha^{\perp}$ is the orthogonal alpha. Expected returns are assembled as

$$
\mu
= \lambda\,B(T)\,\mu_f
+ (1 - \lambda)\,\alpha^{\parallel}
+ c\,\alpha^{\perp},
$$

where $\lambda$ is `spanned_alpha_shrinkage` and $c$ is
`orthogonal_alpha_confidence`. Direct currency expected returns are added when
currency factors are present.

Asset return scenarios in `return_distribution_.returns` are built by mapping
factor-prior scenarios through the latest loading matrix and adding idiosyncratic
scenarios calibrated to the latest idiosyncratic-risk forecast. They therefore
include both factor and idiosyncratic return components for downstream optimizers
that use scenario-based risk measures such as CVaR.

The estimator distinguishes the coverage, estimation and investment universes:

* The coverage universe is the set of assets stored in `characteristics`. The
  panel’s `active_mask` identifies which asset-observation pairs are active
  within that universe. If `active_mask=True` and a value is NaN, the observation
  is treated as missing data (e.g., holiday or missing quote). If
  `active_mask=False`, the asset is inactive at that observation (e.g.,
  pre-listing or post-delisting period). `AssetPanel` applies each field’s
  `inactive_policy` outside `active_mask`, commonly NaN for numeric fields and
  `MISSING=-1` for categorical fields.
* The estimation universe is defined by the panel’s `estimation_mask`, which is
  enforced as a subset of `active_mask`. It selects the active pairs used to fit
  cross-sectional statistics, factor-return regressions, benchmark and regression
  weights, alpha estimators and regime statistics. Other active pairs can still
  receive transformed values, exposures and forecasts, but they do not contribute to
  those fitted statistics.
* The investment universe is defined by `X.columns` when `X` is provided. `X` is
  the skfolio API input for asset returns and is used by downstream workflows for
  validation, cross-validation, prediction, and scoring. If `X` is `None`, the
  investment universe is the full coverage universe.

Fitting is performed on the coverage universe to use all available cross-sectional
information, then the outputs are reduced to the investment universe. Within that
investment universe, NaNs in fitted moments mark assets that are currently
unavailable or not yet warmed up. Compatible downstream optimizers infer the
investable subset from finite moments, solve on that subset and expand weights back
with zero weight for unavailable assets.

For the complete factor-model user guide, see
[Factor Models](https://skfolio.org/user_guide/factor_models.html.md#factor-models). For more details on the input panel format,
see [Asset Data Representation](https://skfolio.org/user_guide/data_representation.html.md#asset-data-representation).

* **Parameters:**
  **factors** *list of (str, BaseFactorExposure) tuples*
  : Named factor exposure estimators. Each tuple `(name, estimator)` defines a
    factor whose exposure is computed from the [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel).
    Every estimator must have a `family` attribute (e.g., `"market"`, `"style"`,
    `"industry"`, `"country"`). Factor families are used for neutralization,
    zero-sum constraints and reporting.

  **currency_factor** *BaseFactorExposure, optional*
  : Optional factor exposure estimator for a multi-currency universe. This is
    expected to be a `OneHotCategoricalFactors` estimator on the point-in-time asset
    currency field, or an equivalent estimator returning one-hot currency exposures.
    <br/>
    For asset $i$ with primary currency $C_i(t)$ at observation
    $t$, the exposure to currency factor $c$ is:
    $$
    x^{ccy}_{i,c}(t) =
    \begin{cases}
        1, & C_i(t) = c, \\
        0, & C_i(t) \ne c.
    \end{cases}
    $$
    <br/>
    Currency factor returns are supplied through `currency_excess_returns`. The
    base-currency excess return is:
    $$
    R^{excess,base}_i(t)
    = R^{excess,local}_i(t) + R^{ccy}_{C_i(t)}(t)
    $$
    <br/>
    where:
    $$
    R^{ccy}_{C_i(t)}(t)
    = R^{FX}_{C_i(t)}(t) + r^{cash}_{C_i(t)}(t)
    - r^{cash}_{base}(t) + R^{local}_i(t) R^{FX}_{C_i(t)}(t).
    $$
    <br/>
    Non-currency factor returns are estimated from local excess returns by
    cross-sectional regression. Currency factor returns are not estimated by that
    regression because they are observed FX series in the investor’s numeraire.
    They are appended directly to the factor return distribution with family
    `"currency"`. The family name `"currency"` is reserved for this estimator.

  **exposure_lag** *int, default=1*
  : Number of periods by which factor exposures are lagged in the cross-sectional
    regression. Must be >= 1.
    <br/>
    The estimator follows skfolio’s as-of time-indexing convention: all
    time-varying inputs at observation $t$ reflect information available up
    to and including the end of period $t$. Point-in-time fields and derived
    values store the latest available value for observation $t$. Returns
    stored at observation $t$ cover the period ending at $t$, namely
    $(t-1, t]$.
    <br/>
    Factor-return regressions estimate the factor returns realized over
    $(t-1, t]$. The exposure matrix must therefore describe the assets before
    that return interval begins. `exposure_lag` selects that exposure date. The
    regression model is:
    $$
    R(t) = B(t - \ell)\,f(t) + \epsilon(t)
    $$
    <br/>
    where $\ell$ is `exposure_lag`. With the default $\ell = 1$,
    returns over $(t-1, t]$ are regressed on exposures measured at
    $t-1$.

  **cs_regressor** *BaseCSLinearModel, optional*
  : Cross-sectional regression estimator used to estimate factor returns from asset
    returns and lagged exposures. Must have `fit_intercept=False`. To model an
    cross-sectional intercept, include a
    [`GlobalFactor`](https://skfolio.org/generated/skfolio.factor_exposure.GlobalFactor.html.md#skfolio.factor_exposure.GlobalFactor) in `factors`. The default
    (`None`) is to use
    [`CSLinearRegression`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression).
    <br/>
    #### NOTE
    Unlike factor exposures, which are typically winsorized and standardized
    by the exposure estimators, asset returns enter the cross-sectional
    regression unadjusted. Cleaning return data errors is an upstream
    responsibility, since the same returns drive benchmark weights, realized
    performance and downstream optimization. Winsorizing legitimate extreme
    returns would break the reconciliation of
    $R = B\,f + \epsilon$ and understate idiosyncratic risk for
    heavy-tailed assets; outlier influence is instead limited through
    exposure winsorization, `regression_mcap_power` and
    `inv_idio_variance_weight_shrinkage`. For bounded-influence estimation
    of factor returns, supply a robust `cs_regressor`.

  **neutralize_against** *dict of {str: list[str]}, optional*
  : Keys are factor names or family names to neutralize and values are lists of
    factor names or family names to neutralize against. When a key is a family name,
    every factor in that family is neutralized independently against the same
    targets. Entries are processed in insertion order: later entries see exposures
    already modified by earlier ones.
    <br/>
    For example:
    * `{"volatility": ["beta"]}`: orthogonalizes the volatility factor exposure
      against the beta factor exposure.
    * `{"momentum": ["industry"]}`: orthogonalizes the momentum factor exposure
      against all industry factor exposures.
    * `{"style": ["industry"]}`: orthogonalizes every style factor exposure against
      all industry factor exposures.
    <br/>
    #### NOTE
    When industry factors are one-hot encoded, neutralizing against industry is
    equivalent to applying within-industry demeaning. Using
    `FixedWeightedFactor` with `transform_by_group="industry"` and
    cross-sectional scoring that support group demeaning (e.g.
    `CSStandardScaler`) achieves the same result and is preferred for
    performance.

  **constrained_families** *list[tuple[str, str | None]], optional*
  : Zero-sum constraints applied within factor families. This is useful for one-hot
    families such as industry or country, whose exposures are collinear with
    [`GlobalFactor`](https://skfolio.org/generated/skfolio.factor_exposure.GlobalFactor.html.md#skfolio.factor_exposure.GlobalFactor) when all categories are
    included.
    <br/>
    Economically, the market factor captures the benchmark portfolio return.
    Constrained family factors capture relative effects around it. For example,
    constrained industry factors measure industry effects whose benchmark-weighted
    average is zero.
    <br/>
    Each tuple `(family, factor_to_drop)` specifies a family to reparameterize.
    The model removes one redundant factor and rewrites the family exposures in
    an equivalent full-rank basis. If `factor_to_drop` is `None`, the redundant
    factor is selected automatically to improve numerical conditioning.
    <br/>
    The same full-rank basis is used by downstream factor-level estimators, such
    as the factor prior and covariance estimator.

  **benchmark_mcap_power** *float, default=1.0*
  : Exponent applied to market capitalization to define the model benchmark weights:
    $$
    w_i \propto \mathrm{mcap}_i^p
    $$
    <br/>
    where $p$ is `benchmark_mcap_power`. These weights are used for weighted
    cross-sectional centering, zero-sum family constraints and the reference
    portfolio associated with the global factor.
    <br/>
    Typical choices:
    * `0.0`: equal-weighted
    * `0.5`: square-root market-cap-weighted
    * `1.0`: market-cap-weighted (default)

  **regression_mcap_power** *float, default=0.5*
  : Exponent applied to market capitalization to define the initial weights used in
    the cross-sectional regression:
    $$
    w_i \propto \mathrm{mcap}_i^p
    $$
    <br/>
    where $p$ is `regression_mcap_power`. These weights are used for
    regression estimation only and do not affect the model benchmark weights.
    When `inv_idio_variance_weight_shrinkage > 0`, these market-cap-based weights
    are blended with inverse-idiosyncratic-variance weights before the second-pass
    cross-sectional regression.
    <br/>
    Like the exposures, market caps are lagged by `exposure_lag`. Regression
    weights at observation $t$ use market caps from the selected exposure
    date, so the weights are fixed before the return interval being regressed.
    <br/>
    Typical choices:
    * `0.0`: equal-weighted
    * `0.5`: square-root market-cap-weighted (default)
    * `1.0`: market-cap-weighted

  **inv_idio_variance_weight_shrinkage** *float, default=0.0*
  : Shrinkage toward inverse-idiosyncratic-variance regression weights.
    When nonzero, the initial market-cap-based regression weights are blended with
    inverse idiosyncratic-variance weights in a two-pass WLS procedure. This
    approximates GLS by using estimated idiosyncratic variances as regression
    weights.
    <br/>
    The blended regression weight for each asset is:
    $$
    w_i = \lambda\,w_i^{\text{inv-var}} + (1 - \lambda)\,w_i^{\text{cap}}
    $$
    <br/>
    where $\lambda$ is `inv_idio_variance_weight_shrinkage`. Larger values
    give more weight to inverse idiosyncratic variance, while `0.0` uses only the
    market-cap-based regression weights. Must satisfy
    `0 <= inv_idio_variance_weight_shrinkage <= 1`.
    <br/>
    This is a standard two-step feasible GLS: the variances feeding the weights
    are estimated from the cap-weighted first-pass residuals, so the regression
    weights never depend on their own output, avoiding the feedback loop of
    recursive weighting schemes where a low estimated variance increases an
    asset’s weight and, in turn, its influence on later residuals. The weights
    used at date $t$ are estimated from residuals up to $t - 1$ only.

  **inv_idio_variance_max_weight_ratio** *float, default=20*
  : Maximum ratio between any inverse-idiosyncratic-variance weight and the
    cross-sectional median inverse-idiosyncratic-variance weight. This caps extreme
    regression weights for assets with very low estimated idiosyncratic variance.

  **factor_prior_estimator** *BasePrior, optional*
  : Prior estimator for the factor return distribution: expected returns (factor
    premia), covariance and factor return scenarios. It is fitted on the estimated
    factor return time series.
    <br/>
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior) with
    [`EWMu`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu) and
    [`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance).

  **alpha_estimator** *BaseAlpha, optional*
  : Estimator producing an expected-return forecast for each asset from
    idiosyncratic returns and alpha signals computed from `AssetPanel` fields.
    The forecast is subsequently decomposed into spanned alpha and orthogonal
    alpha.
    <br/>
    If `None` (default), expected asset returns are determined entirely by the
    expected factor returns estimated by `factor_prior_estimator` (factor premia).
    <br/>
    The alpha should be expressed in expected-return units when it is combined with
    expected factor returns or used by optimizers that trade it off against
    realized-return quantities (e.g., transaction costs, market impact, turnover
    constraints or return targets). Unitless cross-sectional scores are appropriate
    only when the downstream objective treats them purely as ordinal signals.

  **spanned_alpha_shrinkage** *float, default=1.0*
  : Shrinkage applied to spanned alpha. The alpha forecast is decomposed as
    $\alpha = \alpha^{\parallel} + \alpha^{\perp}$, with
    $\alpha^{\parallel} = B(T)\,g$. The factor-implied asset expected returns
    $B(T)\,\mu_f$ are blended with the spanned alpha:
    $$
    \mu^{\parallel}
    = \lambda\,B(T)\,\mu_f + (1 - \lambda)\,\alpha^{\parallel}
    $$
    <br/>
    where $\mu_f$ contains expected factor returns and $\lambda$ is
    `spanned_alpha_shrinkage`.
    * `0`: use only the spanned alpha. When `alpha_estimator=None`, this sets the
      non-currency factor-spanned expected return to zero.
    * `1` (default): use only factor-implied asset expected returns.
    * Between 0 and 1: blend factor-implied asset expected returns with the
      spanned alpha.
    <br/>
    Must satisfy `0 <= spanned_alpha_shrinkage <= 1`.

  **orthogonal_alpha_confidence** *float, default=1.0*
  : Confidence weight applied to orthogonal alpha. After the alpha forecast is
    decomposed into $\alpha^{\parallel}$ and $\alpha^{\perp}$, the
    orthogonal alpha is shrunk toward zero:
    $$
    \mu = \mu^{\parallel} + c\,\alpha^{\perp}
    $$
    <br/>
    where $c$ is `orthogonal_alpha_confidence`.
    * `0`: discard the orthogonal alpha.
    * `1` (default): use the orthogonal alpha as-is.
    * Between 0 and 1: partially shrink the orthogonal alpha toward zero.
    <br/>
    Must satisfy `0 <= orthogonal_alpha_confidence <= 1`.
    <br/>
    As an alternative to shrinking the point estimate, orthogonal uncertainty can be
    handled at the optimizer level with
    [`OrthogonalMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet) or
    [`OrthogonalCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet).

  **idio_variance_estimator** *BaseVariance, optional*
  : Variance estimator for idiosyncratic returns. It must support `partial_fit` so
    the model can recover per-asset variance estimates at each observation. These
    estimates are stored in `factor_model_.idio_variances`. The default (`None`) is
    [`RegimeAdjustedEWVariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance).

  **idio_corr_estimator** *BaseCovariance, optional*
  : Estimator for idiosyncratic correlation thresholding. Although this parameter
    accepts a [`BaseCovariance`](https://skfolio.org/generated/skfolio.moments.BaseCovariance.html.md#skfolio.moments.BaseCovariance) estimator, only the
    correlation component of its output is retained.
    <br/>
    The estimator is fitted on idiosyncratic returns standardized by their
    contemporaneous idiosyncratic volatility from `idio_variance_estimator`. The
    resulting covariance matrix is converted to a correlation matrix, thresholded
    with `idio_corr_threshold` and recombined with the latest per-asset
    idiosyncratic variances to produce the final idiosyncratic covariance.
    <br/>
    By construction, idiosyncratic returns should be nearly uncorrelated after
    removing the factor structure, so the idiosyncratic covariance is diagonal by
    default. Correlation thresholding addresses cases where this assumption can
    break down, such as linked securities, multiple share classes, ADRs versus
    ordinary shares, or dual listings. Without it, optimizers may treat highly
    related securities as diversified sources of idiosyncratic risk.
    <br/>
    Variances and correlations are estimated separately because a single full
    covariance estimator would mix per-asset variance estimation with off-diagonal
    correlation noise. This keeps per-asset variances driven by
    `idio_variance_estimator` and applies correlation thresholding only where
    residual correlations are large enough to retain.
    <br/>
    The default (`None`) is [`EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance) [[3]](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#r3935960e9387-3).
    Correlation thresholding is used only when `idio_corr_threshold > 0`.

  **idio_corr_threshold** *float, default=0.0*
  : Absolute correlation threshold $\tau$ used for idiosyncratic correlation
    thresholding. Off-diagonal correlations with $|\rho_{ij}| \le \tau$ are
    set to zero. If `0` (default), correlation thresholding is disabled and the
    idiosyncratic covariance is diagonal.

  **max_history** *int, optional*
  : Maximum number of fitted observations to retain in time-series outputs and asset
    return scenarios. This applies to `return_distribution_.returns` and to fitted
    `factor_model_` histories such as `factor_returns`, `idio_returns`,
    `idio_variances`, `exposures`, and `regression_weights`.
    <br/>
    In incremental learning, setting `max_history` limits memory usage and keeps
    optimization with scenario-based risk measures, such as CVaR, computed on a
    rolling window of recent scenarios.
    * If `None` (default), all fitted observations are retained.
    * If an integer, only the last `max_history` fitted observations are retained.

  **min_regression_assets** *int, optional*
  : Minimum number of assets that must have all factor exposures finite and belong
    to the estimation universe at every post-warmup observation. If any observation
    falls below this threshold, a ValueError is raised. If `None` (default), the
    threshold is set automatically to `max(2 * n_factors, 30)` to reduce the risk
    of underspecified regressions and unstable factor-return estimates.

  **n_jobs** *int, default=1*
  : Number of parallel jobs used to compute factor exposures. Factors in the same
    dependency layer are computed in parallel using threads, avoiding copies of the
    underlying `AssetPanel`. Set to `-1` to use all available processors.
* **Attributes:**
  **return_distribution_** *ReturnDistribution*
  : Fitted [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) containing the expected
    asset returns, covariance matrix, asset return scenarios and reference to
    the fitted [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel).

  **factor_model_** *FactorModel*
  : Fitted [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel) containing factor exposures, factor
    returns, factor covariance, idiosyncratic returns, idiosyncratic variances and
    idiosyncratic covariance. Stored `exposures` follow the as-of time-indexing
    convention for each observation.

  **cs_regressor_** *BaseCSLinearModel*
  : Fitted cross-sectional regression estimator.

  **factor_prior_estimator_** *BasePrior*
  : Fitted factor prior estimator.

  **alpha_estimator_** *BaseAlpha or None*
  : Fitted alpha estimator or `None` if no alpha estimator was provided.

  **idio_variance_estimator_** *BaseVariance*
  : Fitted idiosyncratic variance estimator.

  **idio_corr_estimator_** *BaseCovariance*
  : Fitted idiosyncratic correlation estimator.

  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names in the coverage universe.

  **n_features_in_** *int*
  : Number of assets in the investment universe.

  **feature_names_in_** *ndarray of shape (n_features_in,)*
  : Asset names in the investment universe. When `X` is `None`, equals
    `asset_names_`.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel.fit)([X, y, currency_excess_returns])         | Fit the characteristics factor model.                                                    |
|-----------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel.get_metadata_routing)()                       | Get metadata routing for this estimator.                                                 |
| [`get_params`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel.get_params)([deep])                           | Get the parameters of this estimator.                                                    |
| [`partial_fit`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel.partial_fit)([X, y, currency_excess_returns]) | Incrementally fit the characteristics factor model.                                      |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel.set_fit_request)(\*[, characteristics, ...])  | Configure whether metadata should be requested to be passed to the `fit` method.         |
| [`set_params`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel.set_params)(\*\*params)                       | Set the parameters of this estimator.                                                    |
| [`set_partial_fit_request`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel.set_partial_fit_request)(\*[, ...])           | Configure whether metadata should be requested to be passed to the `partial_fit` method. |

### Notes

When the factor list includes a
[`GlobalFactor`](https://skfolio.org/generated/skfolio.factor_exposure.GlobalFactor.html.md#skfolio.factor_exposure.GlobalFactor), that factor acts as
the cross-sectional regression intercept because its exposure is one for every
asset. Its estimated return is close to the return of the market (defined as the
benchmark-weighted portfolio on the estimation universe).

When remaining factor exposures are centered so their benchmark-weighted average is
zero, as produced by [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler) and family
constraints, they satisfy:

$$
\sum_i w_i^{\text{bench}}\,B_{ij} = 0 \quad \forall\; j \neq 0
$$

This centers these factors around the market, so the global factor captures the
market return. If regression weights differ from benchmark weights, small tilts
can remain:

$$
\sum_i w_i^{\text{reg}} B_{ij}
$$

These tilts explain why the global factor return may differ slightly from the
exact market return.

When `regression_mcap_power == benchmark_mcap_power` and
`inv_idio_variance_weight_shrinkage == 0`, regression weights are proportional to
benchmark weights, the tilts vanish and the identity becomes exact:

$$
\hat{f}_0(t) = \sum_i \hat{w}_i^{\text{bench}} R_i(t)
$$

### References

* <a id='r3935960e9387-1'>**[1]**</a> “The Elements of Quantitative Investing”, Wiley Finance, Giuseppe A. Paleologo (2025).
* <a id='r3935960e9387-2'>**[2]**</a> “Active Portfolio Management: A Quantitative Approach for Producing Superior Returns and Controlling Risk”, McGraw-Hill, Grinold & Kahn (1999).
* <a id='r3935960e9387-3'>**[3]**</a> “Multivariate Exponentially Weighted Moving Covariance Matrix”, Technometrics, Hawkins & Maboudou-Tchao (2008).

### Examples

Build a characteristics factor model from market, industry and style exposures:

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import (
...     BookToPrice,
...     EWMomentum,
...     EWMarketBeta,
...     ForwardEarningsToPrice,
...     LogMarketCap,
... )
>>> from skfolio.factor_exposure import (
...     DerivedFactor,
...     FixedWeightedFactor,
...     GlobalFactor,
...     OneHotCategoricalFactors,
... )
>>> from skfolio.moments import EWMu, RegimeAdjustedEWCovariance
>>> from skfolio.prior import CharacteristicsFactorModel, EmpiricalPrior
>>>
>>> characteristics = make_synthetic_characteristics(
...     n_assets=100, n_observations=504, n_industries=5, random_state=0
... )
>>>
>>> # Market and industry factors.
>>> market_factor = GlobalFactor()
>>> industry_factors = OneHotCategoricalFactors(
...     category="industry",
...     family="industry",
... )
>>>
>>> # Style factors built from descriptors.
>>> beta_factor = FixedWeightedFactor(
...     descriptors=[("market_beta", EWMarketBeta(half_life=63))],
...     family="style",
...     transform_by_group="industry",
... )
>>> momentum_factor = FixedWeightedFactor(
...     descriptors=[("momentum", EWMomentum(half_life=126, skip=21))],
...     family="style",
...     transform_by_group="industry",
... )
>>> size_factor = FixedWeightedFactor(
...     descriptors=[("log_market_cap", LogMarketCap())],
...     family="style",
...     transform_by_group="industry",
... )
>>> earnings_yield_factor = FixedWeightedFactor(
...     descriptors=[
...         ("book_to_price", BookToPrice()),
...         ("forward_earnings_to_price", ForwardEarningsToPrice()),
...     ],
...     weights=[0.5, 0.5],
...     family="style",
...     transform_by_group="industry",
... )
>>>
>>> # Style exposure derived from an existing factor.
>>> non_linear_size_factor = DerivedFactor(
...     source="size",
...     func=lambda x: x**3,
...     transform_by_group="industry",
... )
>>>
>>> model = CharacteristicsFactorModel(
...     factors=[
...         ("market", market_factor),
...         ("industry", industry_factors),
...         ("beta", beta_factor),
...         ("momentum", momentum_factor),
...         ("size", size_factor),
...         ("earnings_yield", earnings_yield_factor),
...         ("non_linear_size", non_linear_size_factor),
...     ],
...     neutralize_against={
...         "momentum": ["industry"],
...         "non_linear_size": ["size"],
...     },
...     constrained_families=[("industry", None)],
...     factor_prior_estimator=EmpiricalPrior(
...         mu_estimator=EWMu(),
...         covariance_estimator=RegimeAdjustedEWCovariance(
...             half_life=40,
...             corr_half_life=60,
...         ),
...     ),
...     inv_idio_variance_weight_shrinkage=0.5,
...     n_jobs=-1,
... )
>>> model.fit(characteristics=characteristics)
CharacteristicsFactorModel(...)
>>>
>>> # Inspect the fitted factor model and diagnostics.
>>> fm = model.factor_model_
>>> fm.summary().head(3)
             annualized_mean  annualized_vol  ...  coverage  stability
market              0.250...        0.188...  ...       1.0        1.0
Real Estate        -0.000...        0.083...  ...       1.0        1.0
Software           -0.107...        0.118...  ...       1.0        1.0

[3 rows x 9 columns]
>>> fm.idio_calibration_summary()
mean_cs_std                0.997...
median_cs_std              0.988...
mean_cs_excess_kurtosis    0.116...
mean_cs_skewness           0.012...
mean_tail_rate_3sigma      0.003...
Name: idio_calibration, dtype: float64
>>> fm.idio_vol_ic.tail(3)
2016-12-02    0.418...
2016-12-05    0.496...
2016-12-06    0.488...
Name: Idio Vol IC (Spearman), dtype: float64
>>> fm.idio_tail_rate().tail(3)
2016-12-02    0.000000
2016-12-05    0.000000
2016-12-06    0.011...
Name: Tail Rate, dtype: float64
>>> fm.factor_returns_df.head(3)
              market  Real Estate  ...  earnings_yield  non_linear_size
2015-07-27 -0.001...     0.001...  ...        0.000...        -0.002...
2015-07-28  0.010...     0.000...  ...        0.003...         0.001...
2015-07-29 -0.006...     0.011...  ...       -0.000...         0.002...

[3 rows x 11 columns]
>>> # Last three size exposures for the first three assets.
>>> fm.exposures_df["size"].iloc[-3:, :3]
asset         A00000    A00001    A00002
2016-12-02 -2.314... -1.344... -0.283...
2016-12-05 -2.312... -1.339... -0.283...
2016-12-06 -2.313... -1.339... -0.287...
```

Use [`partial_fit`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel.partial_fit) for online updates:

```pycon
>>> model.fit(characteristics=characteristics[:400])
CharacteristicsFactorModel(...)
>>> model.partial_fit(characteristics=characteristics[400:405])
CharacteristicsFactorModel(...)
```

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

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

Fit the characteristics factor model.

Resets all fitted state and estimates the full model pipeline on the provided
data. For incremental updates, use [`partial_fit`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel.partial_fit).

* **Parameters:**
  **X** *DataFrame of shape (n_observations, n_assets), optional*
  : Asset returns whose columns define the investment universe, following the
    standard skfolio estimator API. In this estimator, `X.columns` define the
    assets returned in `return_distribution_` and `factor_model_`.
    <br/>
    Factor estimation uses the `"returns"` field of `characteristics`, which can
    cover a broader point-in-time universe than `X`. This keeps the estimator
    compatible with skfolio pipelines, cross-validation, prediction and scoring,
    while allowing the factor model to use a wider coverage universe for
    estimation.

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

  **characteristics** *AssetPanel*
  : Point-in-time [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) for the coverage
    universe. Must include `"returns"` and, when market-cap weighting is used,
    `"market_cap"`. The panel’s `active_mask` identifies active
    asset-observation pairs within the coverage universe and `estimation_mask`
    identifies which active pairs contribute to estimation. For more details see
    [Asset Data Representation](https://skfolio.org/user_guide/data_representation.html.md#asset-data-representation).

  **currency_excess_returns** *DataFrame, optional*
  : Currency excess returns. Required only when `currency_factor` is set.
    Columns must contain the unique currency factor names produced by
    `currency_factor`. Assets are mapped to these columns through the one-hot
    currency exposures.

  **\*\*fit_params** *dict*
  : Parameters passed to underlying estimators. Only available when
    `enable_metadata_routing=True`, set with
    `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** *CharacteristicsFactorModel*
  : Fitted estimator.
* **Raises:**
  ValueError
  : If the data does not contain enough observations to estimate the model after
    warmup and exposure-lag trimming.

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

#### get_metadata_routing()

Get metadata routing for this estimator.

* **Returns:**
  **routing** *MetadataRouter*
  : Metadata routing configuration.

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

#### get_params(deep=True)

Get the parameters of this estimator.

Returns the parameters given in the constructor as well as the
factor estimators contained within the `factors` parameter.

* **Parameters:**
  **deep** *bool, default=True*
  : Setting it to True gets the various estimators and the parameters
    of the estimators as well.
* **Returns:**
  **params** *dict*
  : Parameter and estimator names mapped to their values or parameter
    names mapped to their values.

<a id="skfolio.prior.CharacteristicsFactorModel.named_factors"></a>

#### *property* named_factors

Dictionary for accessing factors by name.

* **Returns:**
  `Bunch`

<a id="skfolio.prior.CharacteristicsFactorModel.partial_fit"></a>

#### partial_fit(X=None, y=None, \*, characteristics, currency_excess_returns=None, \*\*fit_params)

Incrementally fit the characteristics factor model.

This method allows for streaming/online updates. Each call updates the internal
state with new observations without resetting previously accumulated state. All
sub-estimators (`factor_prior_estimator`, `idio_variance_estimator`, etc.)
must implement `partial_fit` for this method to work.

* **Parameters:**
  **X** *DataFrame of shape (n_observations, n_assets), optional*
  : Asset returns whose columns define the investment universe, following the
    standard skfolio estimator API. In this estimator, `X.columns` define the
    assets returned in `return_distribution_` and `factor_model_`.
    <br/>
    Factor estimation uses the `"returns"` field of `characteristics`, which can
    cover a broader point-in-time universe than `X`. This keeps the estimator
    compatible with skfolio pipelines, cross-validation, prediction and scoring,
    while allowing the factor model to use a wider coverage universe for
    estimation.

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

  **characteristics** *AssetPanel*
  : Point-in-time [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) for the coverage
    universe. Must include `"returns"` and, when market-cap weighting is used,
    `"market_cap"`. The panel’s `active_mask` identifies active
    asset-observation pairs within the coverage universe and `estimation_mask`
    identifies which active pairs contribute to estimation. For more details see
    [Asset Data Representation](https://skfolio.org/user_guide/data_representation.html.md#asset-data-representation).

  **currency_excess_returns** *DataFrame, optional*
  : Currency excess returns. Required only when `currency_factor` is set.
    Columns must contain the unique currency factor names produced by
    `currency_factor`. Assets are mapped to these columns through the one-hot
    currency exposures.

  **\*\*fit_params** *dict*
  : Parameters passed to underlying estimators. Only available when
    `enable_metadata_routing=True`, set with
    `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** *CharacteristicsFactorModel*
  : Fitted estimator.

<a id="skfolio.prior.CharacteristicsFactorModel.set_fit_request"></a>

#### set_fit_request(\*, characteristics='$UNCHANGED$', currency_excess_returns='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **characteristics** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `characteristics` parameter in `fit`.

  **currency_excess_returns** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `currency_excess_returns` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

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

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

Set the parameters of this estimator.

Valid parameter keys can be listed with `get_params()`. Note that you
can directly set the parameters of the factor estimators contained in
`factors`.

* **Parameters:**
  **\*\*params** *keyword arguments*
  : Specific parameters using e.g.
    `set_params(parameter_name=new_value)`. In addition to setting the
    parameters of the estimator, the individual factor estimators can
    also be set, or can be removed by setting them to ‘drop’.
* **Returns:**
  **self** *object*
  : Estimator instance.

<a id="skfolio.prior.CharacteristicsFactorModel.set_partial_fit_request"></a>

#### set_partial_fit_request(\*, characteristics='$UNCHANGED$', currency_excess_returns='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `partial_fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `partial_fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `partial_fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **characteristics** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `characteristics` parameter in `partial_fit`.

  **currency_excess_returns** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `currency_excess_returns` parameter in `partial_fit`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.prior.CovarianceSqrt.html.md

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

# skfolio.prior.CovarianceSqrt

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

### *class* skfolio.prior.CovarianceSqrt(components=(), diagonal=None)

Matrix square root decomposition of a covariance matrix.

Encodes $\Sigma = \sum_i A_i A_i^\top + \operatorname{diag}(d)^2$ in a form
suitable for second-order cone (SOC) constraints:

$$
\left\lVert
\begin{pmatrix}
    A_1^\top w \\
    \vdots \\
    A_m^\top w \\
    d \odot w
\end{pmatrix}
\right\rVert_2
\le v
\;\Longleftrightarrow\;
w^\top \Sigma\, w \le v^2
$$

This representation avoids forming a full $(n \times n)$ Cholesky factor when
the covariance has lower-dimensional components and a diagonal component.

* **Attributes:**
  **components** *tuple of ndarray of shape (n, k_i)*
  : Matrices $A_i$ of shape $(n, k_i)$ contributing
    $\sum_i A_i A_i^\top$ to the covariance.

  **diagonal** *ndarray of shape (n,) or None*
  : Vector $d$ contributing $\operatorname{diag}(d)^2$ to the
    covariance.

# generated/skfolio.prior.EmpiricalPrior.html.md

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

# skfolio.prior.EmpiricalPrior

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

### *class* skfolio.prior.EmpiricalPrior(mu_estimator=None, covariance_estimator=None, is_log_normal=False, investment_horizon=None, max_history=None)

Empirical Prior estimator.

The Empirical Prior estimates the [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) by
fitting a `mu_estimator` and a `covariance_estimator` separately.

**NaN handling:**

Missing data (NaN returns) caused by late listings, delistings and holidays is
accepted when both `mu_estimator` and `covariance_estimator` support it (for
example [`EWMu`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu) and
[`EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance)). The moment estimators receive the data
unchanged and apply their own NaN treatment.

In `return_distribution_.returns`, the scenario columns of non-investable
assets (NaN in the estimated `mu` and/or covariance diagonal) are left
unchanged and are removed downstream by
[`investable_subset`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution.investable_subset). Missing
observations of investable assets are replaced by zero.

Zero-filling long gaps, such as the pre-listing history of a late-listed
asset, understates its risk in scenario-based measures (CVaR, EVaR, CDaR,
worst realization, …). A `UserWarning` is emitted when more than 5% of an
investable asset’s scenario history is zero-filled. The moments estimation is
not affected. To reduce the zero-filled share, set `max_history` or use a
factor model prior such as [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel).

* **Parameters:**
  **mu_estimator** *BaseMu, optional*
  : The assets [expected returns estimator](https://skfolio.org/user_guide/expected_returns.html.md#mu-estimator).
    The default (`None`) is to use [`EmpiricalMu`](https://skfolio.org/generated/skfolio.moments.EmpiricalMu.html.md#skfolio.moments.EmpiricalMu).

  **covariance_estimator** *BaseCovariance , optional*
  : The assets [covariance matrix estimator](https://skfolio.org/user_guide/covariance.html.md#covariance-estimator).
    The default (`None`) is to use  [`EmpiricalCovariance`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance).

  **is_log_normal** *bool, default=False*
  : If this is set to True, the moments are estimated on the logarithmic returns
    as opposed to the linear returns. Then the moments estimations of the
    logarithmic returns are projected to the investment horizon and transformed
    to obtain the moments estimation of the linear returns at the investment
    horizon. If True, `investment_horizon` must be provided. The input `X` must be
    **linear returns**. They will be converted into logarithmic returns only for the
    moments estimation.
    <br/>
    #### SEE ALSO
    [data preparation](https://skfolio.org/user_guide/data_preparation.html.md#data-preparation)

  **investment_horizon** *float, optional*
  : The investment horizon used for the moments estimation of the linear returns
    when `is_log_normal` is `True`.

  **max_history** *int, optional*
  : Maximum number of observations to keep in `return_distribution_.returns`.
    This is useful for controlling memory usage during incremental learning
    with [`partial_fit`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior.partial_fit).
    * If `None` (default), all returns are accumulated.
    * If an integer, only the last `max_history` observations are kept
      (rolling window).
* **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 moments estimation.

  **mu_estimator_** *BaseMu*
  : Fitted `mu_estimator`.

  **covariance_estimator_** *BaseCovariance*
  : Fitted `covariance_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`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior.fit)(X[, y])            | Fit the Empirical Prior estimator.               |
|-------------------------------------------------------------------------|--------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior.get_metadata_routing)() | Get metadata routing of this object.             |
| [`get_params`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior.get_params)([deep])     | Get parameters for this estimator.               |
| [`partial_fit`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior.partial_fit)(X[, y])    | Incrementally fit the Empirical Prior estimator. |
| [`set_params`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior.set_params)(\*\*params) | Set the parameters of this estimator.            |

### References

* <a id='r2751d933e841-1'>**[1]**</a> “Linear vs. Compounded Returns - Common Pitfalls in Portfolio Management”. GARP Risk Professional. Attilio Meucci (2010).

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

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

Fit the Empirical Prior estimator.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. May contain NaN (holidays, late
    listings, delistings) when both `mu_estimator` and
    `covariance_estimator` handle missing data.

  **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** *EmpiricalPrior*
  : Fitted estimator.

<a id="skfolio.prior.EmpiricalPrior.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.EmpiricalPrior.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.EmpiricalPrior.partial_fit"></a>

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

Incrementally fit the Empirical Prior estimator.

This method allows for streaming/online updates to the prior estimate.
Each call updates the internal state with new observations.

Both `mu_estimator` and `covariance_estimator` must implement
`partial_fit` for this method to work.

* **Parameters:**
  **X** *array-like of shape (n_observations, n_assets)*
  : Price returns of the assets. May contain NaN (holidays, late
    listings, delistings) when both `mu_estimator` and
    `covariance_estimator` handle missing data.

  **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** *EmpiricalPrior*
  : Fitted estimator.

<a id="skfolio.prior.EmpiricalPrior.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.

# generated/skfolio.prior.EntropyPooling.html.md

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

# skfolio.prior.EntropyPooling

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

### *class* skfolio.prior.EntropyPooling(prior_estimator=None, mean_views=None, variance_views=None, correlation_views=None, skew_views=None, kurtosis_views=None, value_at_risk_views=None, cvar_views=None, value_at_risk_beta=0.95, cvar_beta=0.95, groups=None, solver='TNC', solver_params=None)

Entropy Pooling estimator.

Entropy Pooling, introduced by Attilio Meucci in 2008 as a generalization of the
Black-Litterman framework, is a nonparametric method for adjusting a baseline
(“prior”) probability distribution to incorporate user-defined views by finding the
posterior distribution closest to the prior while satisfying those views.

User-defined views can be **elicited** from domain experts or **derived** from
quantitative analyses.

Grounded in information theory, it updates the distribution in the least-informative
way by minimizing the Kullback-Leibler divergence (relative entropy) under the
specified view constraints.

Mathematically, the problem is formulated as:

$$
\begin{aligned}
\min_{\mathbf{q}} \quad & \sum_{i=1}^T q_i \log\left(\frac{q_i}{p_i}\right) \\
\text{subject to} \quad & \sum_{i=1}^T q_i = 1 \quad \text{(normalization constraint)} \\
                        & \mathbb{E}_q[f_j(X)] = v_j \quad(\text{or } \le v_j, \text{ or } \ge v_j), \quad j = 1,\dots,k, \text{(view constraints)} \\
                        & q_i \ge 0, \quad i = 1, \dots, T
\end{aligned}
$$

Where:

- $T$ is the number of observations (number of scenarios).
- $p_i$ is the prior probability of scenario $x_i$.
- $q_i$ is the posterior probability of scenario $x_i$.
- $X$ is the scenario matrix of shape (n_observations, n_assets).
- $f_j$ is the j <sub>th</sub> view function.
- $v_j$ is the target value imposed by the j <sub>th</sub> view.
- $k$ is the total number of views.

The `skfolio` implementation supports the following views:
: * Equalities
  * Inequalities
  * Ranking
  * Linear combinations (e.g. relative views)
  * Views on groups of assets

On the following measures:
: * Mean
  * Variance
  * Skew
  * Kurtosis
  * Correlation
  * Value-at-Risk (VaR)
  * Conditional Value-at-Risk (CVaR)

* **Parameters:**
  **prior_estimator** *BasePrior, optional*
  : Estimator of the asset’s prior distribution, fitted from a
    [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior). The default (`None`) is to use the
    empirical prior [`EmpiricalPrior()`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior). To perform Entropy
    Pooling on synthetic data, you can use [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData)
    by setting `prior_estimator = SyntheticData()`.

  **mean_views** *list[str], optional*
  : Views on asset means.
    The views must match any of following patterns:
    > * `"ref1 >= a"`
    > * `"ref1 == b"`
    > * `"ref1 <= ref1"`
    > * `"ref1 >= a * prior(ref1)"`
    > * `"ref1 == b * prior(ref2)"`
    > * `"a * ref1 + b * ref2 + c <= d * ref3"`
    <br/>
    With `"ref1"`, `"ref2"` … the assets names or the groups names provided
    in the parameter `groups`. Assets names can be referenced without the need of
    `groups` if the input `X` of the `fit` method is a DataFrame with assets names
    in columns. Otherwise, the default asset names `x0, x1, ...` are assigned.
    By using the term `prior(...)`, you can reference the asset prior mean.
    <br/>
    For example:
    > * `"SPX >= 0.0015"` –> The mean of SPX is greater than 0.15% (daily mean if
    >   `X` is daily)
    > * `"SX5E == 0.002"` –> The mean of SX5E equals 0.2%
    > * `"AAPL <= 0.003"` –> The mean of AAPL is less than to 0.3%
    > * `"SPX <= SX5E"` –> Ranking view: the mean of SPX is less than SX5E
    > * `"SPX >= 1.5 * prior(SPX)"` –> The mean of SPX increases by at least 50% (versus its prior)
    > * `"SX5E == 2 * prior(SX5E)"` –> The mean of SX5E doubles (versus its prior)
    > * `"AAPL <= 0.8 * prior(SPX)"` –> The mean of AAPL is less than 0.8 times the SPX prior
    > * `"SX5E + SPX >= 0"` –> The sum of SX5E and SPX mean is greater than zero
    > * `"US == 0.007"` –> The sum of means of US assets equals 0.7%
    > * `"Equity == 3 * Bond"` –> The sum of means of Equity assets equals
    >   three times the  sum of means of Bond assets.
    > * `"2*SPX + 3*Europe <= Bond + 0.05"` –> Mixing assets and group mean views

  **variance_views** *list[str], optional*
  : Views on asset variances.
    It supports the same patterns as `mean_views`.
    <br/>
    For example:
    > * `"SPX >= 0.0009"` –> SPX variance is greater than 0.0009 (daily)
    > * `"SX5E == 1.5 * prior(SX5E)"` –> SX5E variance increases by 150% (versus
    >   its prior)

  **skew_views** *list[str], optional*
  : Views on asset skews.
    It supports the same patterns as `mean_views`.
    <br/>
    For example:
    > * `"SPX >= 2.0"` –> SPX skew is greater than 2.0
    > * `"SX5E == 1.5 * prior(SX5E)"` –> SX5E skew increases by 150% (versus its
    >   prior)

  **kurtosis_views** *list[str], optional*
  : Views on asset kurtosis.
    It supports the same patterns as `mean_views`.
    <br/>
    For example:
    > * `"SPX >= 9.0"` –> SPX kurtosis is greater than 9.0
    > * `"SX5E == 1.5 * prior(SX5E)"` –> SX5E kurtosis increases by 150% (versus
    >   its prior)

  **correlation_views** *list[str], optional*
  : Views on asset correlations.
    The views must match any of following patterns:
    > * `"(asset1, asset2) >= a"`
    > * `"(asset1, asset2) == a"`
    > * `"(asset1, asset2) <= a"`
    > * `"(asset1, asset2) >= a * prior(asset1, asset2)"`
    > * `"(asset1, asset2) == a * prior(asset1, asset2)"`
    > * `"(asset1, asset2) <= a * prior(asset1, asset2)"`
    <br/>
    For example:
    > * `"(SPX, SX5E) >= 0.8"` –> the correlation between SPX and SX5E is greater than 80%
    > * `"(SPX, SX5E) == 1.5 * prior(SPX, SX5E)"` –> the correlation between SPX
    >   and SX5E increases by 150% (versus its prior)

  **value_at_risk_views** *list[str], optional*
  : Views on asset Value-at-Risks (VaR).
    <br/>
    For example:
    > * `"SPX >= 0.03"` –> SPX VaR is greater than 3%
    > * `"SX5E == 1.5 * prior(SX5E)"` –> SX5E VaR increases by 150% (versus its prior)

  **cvar_views** *list[str], optional*
  : Views on asset Conditional Value-at-Risks (CVaR).
    It only supports equalities.
    <br/>
    For example:
    > * `"SPX == 0.05"` –> SPX CVaR equals 5%
    > * `"SX5E == 1.5 * prior(SX5E)"` –> SX5E CVaR increases by 150% (versus its prior)

  **value_at_risk_beta** *float, default=0.95*
  : Confidence level for VaR views, by default 95%.

  **cvar_beta** *float, default=0.95*
  : Confidence level for CVaR views, by default 95%.

  **groups** *dict[str, list[str]] or array-like of strings of shape (n_groups, n_assets), optional*
  : Asset grouping for use in group-based views. If a dict is provided, keys are
    asset names and values are lists of group labels; then `X` must be a DataFrame
    whose columns match those asset names.
    <br/>
    For example:
    > * `groups = {"SX5E": ["Equity", "Europe"], "SPX": ["Equity", "US"], "TLT": ["Bond", "US"]}`
    > * `groups = [["Equity", "Equity", "Bond"], ["Europe", "US", "US"]]`

  **solver** *str, default=”TNC”*
  : The solver to use.
    - “TNC” (default) solves the entropic-pooling dual via SciPy’s Truncated Newton
      Constrained method. By exploiting the smooth Fenchel dual and its
      closed-form gradient, it operates in $\mathbb{R}^k$ (the number of
      constraints) rather than $\mathbb{R}^T$ (the number of scenarios),
      yielding an order-of-magnitude speedup over primal CVXPY interior-point
      solvers.
    - CVXPY solvers (e.g. “CLARABEL”) solve the entropic-pooling problem in its
      primal form using interior-point methods. While they tend to be slower than
      the dual-based approach, they often achieve higher accuracy by enforcing
      stricter primal feasibility and duality-gap tolerances. See the CVXPY
      documentation for supported solvers:
      [https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver](https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver).

  **solver_params** *dict, optional*
  : Additional parameters to pass to the chosen solver.
    - When using **SciPy TNC**, supported options include (but are not limited to)
      `gtol`, `ftol`, `eps`, `maxfun`, `maxCGit`, `stepmx`, `disp`. See the SciPy
      documentation for a full list and descriptions:
      [https://docs.scipy.org/doc/scipy/reference/optimize.minimize-tnc.html](https://docs.scipy.org/doc/scipy/reference/optimize.minimize-tnc.html)
    - When using a **CVXPY** solver (e.g. `"CLARABEL"`), supply any
      solver-specific parameters here. Refer to the CVXPY solver guide for
      details: [https://www.cvxpy.org/tutorial/solvers](https://www.cvxpy.org/tutorial/solvers)
* **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 assets distribution, moments estimation and the EP
    posterior probabilities (sample weights).

  **relative_entropy_** *float*
  : The KL-divergence between the posterior and prior distributions.

  **effective_number_of_scenarios_** *float*
  : Effective number of scenarios defined as the perplexity of sample weight
    (exponential of entropy).

  **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`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling.fit)(X[, y])            | Fit the Entropy Pooling estimator.    |
|-------------------------------------------------------------------------|---------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling.get_metadata_routing)() | Get metadata routing of this object.  |
| [`get_params`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling.get_params)([deep])     | Get parameters for this estimator.    |
| [`set_params`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling.set_params)(\*\*params) | Set the parameters of this estimator. |

### Notes

Entropy Pooling re-weights the sample probabilities of the prior distribution and is
therefore constrained by the support (completeness) of that distribution. For
example, if the historical distribution contains no returns below -10% for a given
asset, we cannot impose a CVaR view of 15%: no matter how we adjust the sample
probabilities, such tail data do not exist.

Therefore, to impose extreme views on a sparse historical distribution, one must
generate synthetic data. In that case, the EP posterior is only as reliable as the
synthetic scenarios. It is thus essential to use a generator capable of
extrapolating tail dependencies, such as [`VineCopula`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula),
to model joint extreme events accurately.

Two methods are available:
: * Dual form: solves the Fenchel dual of the EP problem using Truncated
    Newton Constrained method.
  * Primal form: solves the original relative-entropy projection in
    probability-space via interior-point algorithms.

See the solver parameter’s docstring for full details on available solvers and
options.

To handle nonlinear views, constraints are linearized by fixing the relevant asset
moments (e.g., means or variances) and then solved via **nested entropic tilting**.
At each stage, the KL-divergence is minimized relative to the original prior,
while nesting all previously enforced (linearized) views into the feasible set:

* Stage 1: impose views on asset means, VaR and CVaR.
* Stage 2: carry forward Stage 1 constraints and add variance, fixing the
  mean at its Stage 1 value.
* Stage 3: carry forward Stage 2 constraints and add skewness, kurtosis and
  pairwise correlations, fixing both mean and variance at their Stage 2 values.

Because each entropic projection nests the prior views, every constraint from
earlier stages is preserved as new ones are added, yielding a final distribution
that satisfies all original nonlinear views while staying as close as possible to
the original prior.

Only the necessary moments are fixed. Slack variables with an L1 norm penalty are
introduced to avoid solver infeasibility that may arise from overly tight
constraints.

CVaR view constraints cannot be directly expressed as linear functions of the
posterior probabilities. Therefore, when CVaR views are present, the EP problem is
solved by recursively solving a series of convex programs that approximate the
nonlinear CVaR constraint.

This implementation improves upon Meucci’s algorithm [[1]](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#rf4c236d00083-1) by formulating the problem
in continuous space as a function of the dual variables etas (VaR levels), rather
than searching over discrete tail sizes. This formulation not only handles the
CVaR constraint more directly but also supports multiple CVaR views on different
assets.

Although the overall problem is convex in the dual variables etas, it remains
non-smooth due to the presence of the positive-part operator in the CVaR
definition. Consequently, we employ derivative-free optimization methods.
Specifically, for a single CVaR view we use a one-dimensional root-finding
method (Brent’s method), and for the multivariate case (supporting multiple
CVaR views) we use Powell’s method for derivative-free convex descent.

### References

* <a id='rf4c236d00083-1'>**[1]**</a> “Fully Flexible Extreme Views”, Journal of Risk, Meucci, Ardia & Keel (2011)
* <a id='rf4c236d00083-2'>**[2]**</a> “Fully Flexible Views: Theory and Practice”, Risk, Meucci (2013).
* <a id='rf4c236d00083-3'>**[3]**</a> “Effective Number of Scenarios in Fully Flexible Probabilities”, GARP Risk Professional, Meucci (2012)
* <a id='rf4c236d00083-4'>**[4]**</a> “I-Divergence Geometry of Probability Distributions and Minimization Problems”, The Annals of Probability, Csiszar (1975)

### Examples

For a full tutorial on entropy pooling, see [Entropy Pooling](https://skfolio.org/auto_examples/entropy_pooling/plot_1_entropy_pooling.html.md#sphx-glr-auto-examples-entropy-pooling-plot-1-entropy-pooling-py).

```pycon
>>> from skfolio import RiskMeasure
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.prior import EntropyPooling
>>> from skfolio.optimization import HierarchicalRiskParity
>>>
>>> prices = load_sp500_dataset()
>>> prices = prices[["AMD", "BAC", "GE", "JNJ", "JPM", "LLY", "PG"]]
>>> X = prices_to_returns(prices)
>>>
>>> groups = {
...     "AMD": ["Technology", "Growth"],
...     "BAC": ["Financials", "Value"],
...     "GE": ["Industrials", "Value"],
...     "JNJ": ["Healthcare", "Defensive"],
...     "JPM": ["Financials", "Income"],
...     "LLY": ["Healthcare", "Defensive"],
...     "PG": ["Consumer", "Defensive"],
... }
>>>
>>> entropy_pooling = EntropyPooling(
...     mean_views=[
...         "JPM == -0.002",
...         "PG >= LLY",
...         "BAC >= prior(BAC) * 1.2",
...         "Financials == 2 * Growth",
...     ],
...     variance_views=[
...         "BAC == prior(BAC) * 4",
...     ],
...     correlation_views=[
...         "(BAC,JPM) == 0.80",
...         "(BAC,JNJ) <= prior(BAC,JNJ) * 0.5",
...     ],
...     skew_views=[
...         "BAC == -0.05",
...     ],
...     cvar_views=[
...         "GE == 0.08",
...     ],
...     cvar_beta=0.90,
...     groups=groups,
... )
>>>
>>> entropy_pooling.fit(X)
EntropyPooling(correlation_views=...
>>>
>>> print(entropy_pooling.relative_entropy_)
0.18...
>>> print(entropy_pooling.effective_number_of_scenarios_)
687...
>>> print(entropy_pooling.return_distribution_.sample_weight)
[0.00010... 0.00009... ... 0.00010... 0.00010...]
>>>
>>> # CVaR Hierarchical Risk Parity optimization on Entropy Pooling
>>> model = HierarchicalRiskParity(
...     risk_measure=RiskMeasure.CVAR,
...     prior_estimator=entropy_pooling
... )
>>> model.fit(X)
HierarchicalRiskParity(prior_estimator=...
>>> print(model.weights_)
[0.073... 0.054... 0.076... 0.20... 0.063... 0.32... 0.20...]
>>>
>>> # Stress Test the Portfolio
>>> entropy_pooling = EntropyPooling(cvar_views=["AMD == 0.10"])
>>> entropy_pooling.fit(X)
EntropyPooling(cvar_views=['AMD == 0.10'])
>>>
>>> stressed_dist = entropy_pooling.return_distribution_
>>>
>>> stressed_ptf = model.predict(stressed_dist)
```

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

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

Fit the Entropy Pooling 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** *EntropyPooling*
  : Fitted estimator.

<a id="skfolio.prior.EntropyPooling.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.EntropyPooling.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.EntropyPooling.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.

# generated/skfolio.prior.FactorModel.html.md

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

# skfolio.prior.FactorModel

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

### *class* skfolio.prior.FactorModel(observations, asset_names, factor_names, factor_families, loading_matrix, exposures, factor_covariance, factor_mu, factor_returns, idio_covariance, idio_mu, idio_returns, idio_variances, exposure_lag=1, regression_weights=None, benchmark_weights=None, family_constraint_basis=None)

Factor model decomposition of asset returns.

Holds the loading matrix, factor moments and idiosyncratic covariance, together with
the optional time series of exposures, factor returns and idiosyncratic returns.
Exposes a factor-structured covariance square root, plus cross-sectional regression
diagnostics, idiosyncratic-calibration metrics and factor attribution when the
relevant fields are populated.

Produced by factor-model prior estimators:

> * [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel),
> * [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel)

and consumed downstream via `factor_model`.

* **Attributes:**
  **observations** *ndarray of shape (n_observations,)*
  : Time index labels.

  **asset_names** *ndarray of shape (n_assets,)*
  : Asset names.

  **factor_names** *ndarray of shape (n_factors,)*
  : Factor names (e.g. `"value"`, `"momentum"`).

  **factor_families** *ndarray of shape (n_factors,) or None*
  : Family label for each factor (e.g. `"style"`, `"industry"`).
    Populated by cross-sectional factor models.

  **loading_matrix** *ndarray of shape (n_assets, n_factors)*
  : Asset-by-factor loading (exposure) matrix. Time-invariant for time-series factor
    models; the most recent point-in-time loadings for cross-sectional factor models
    (full history in `exposures`).

  **exposures** *ndarray of shape (n_observations, n_assets, n_factors) or None*
  : Full historical time series of asset-by-factor exposure (loading) matrices
    following the as-of time-indexing convention. Populated for cross-sectional
    factor models. `None` for time-series factor models, which use the single
    time-invariant `loading_matrix`.

  **factor_covariance** *ndarray of shape (n_factors, n_factors)*
  : Factor return covariance matrix. Under family constraints this full-basis
    matrix is rank-deficient; use [`effective_factor_covariance`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.effective_factor_covariance) (paired with
    [`effective_loading_matrix`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.effective_loading_matrix)) for decompositions such as Cholesky.

  **factor_mu** *ndarray of shape (n_factors,)*
  : Expected factor returns.

  **factor_returns** *ndarray of shape (n_observations, n_factors) or None*
  : Per-period factor returns. For time-series factor models, this is the input
    factor return series; for cross-sectional factor models, this is the per-period
    factor returns estimated from the cross-sectional regression.

  **idio_covariance** *ndarray of shape (n_assets, n_assets) or (n_assets,)*
  : Idiosyncratic covariance (diagonal vector or full matrix).

  **idio_mu** *ndarray of shape (n_assets,) or None*
  : Factor-orthogonal expected return for each asset, also called orthogonal alpha.
    With the default weighted least-squares projection, it satisfies
    $B^\top W\,\text{idio\_mu}=0$. Custom robust or regularized
    cross-sectional regressors may produce a component that is only approximately
    orthogonal. Distinct from the time-series mean of `idio_returns`, which is not
    enforced to be factor-orthogonal. Populated by cross-sectional factor models.

  **idio_returns** *ndarray of shape (n_observations, n_assets) or None*
  : Per-period idiosyncratic returns, obtained from the corresponding factor
    regression. For time-series factor models, these are
    $r - a - Bf$, where $a$ is the vector of time-series regression
    intercepts. For cross-sectional factor models, these are
    $R(t) - B(t-\ell)f(t)$.

  **idio_variances** *ndarray of shape (n_observations, n_assets) or None*
  : Time-varying per-asset predicted idiosyncratic variances
    $\hat\sigma^2_{i,t}$. Populated by cross-sectional factor models.

  **exposure_lag** *int, default=1*
  : Lag applied to time-varying exposures under the as-of time-indexing convention.
    The default value of `1` aligns exposures at $t-1$ with returns over
    $(t-1, t]$. Meaningful only when `exposures` is populated; ignored by
    time-series factor models, where the loading matrix is constant.

  **regression_weights** *ndarray of shape (n_observations, n_assets) or None*
  : Cross-sectional WLS regression weights. Non-negative. Assets with zero weight
    are excluded from the estimation universe. Row $t$ holds the weights
    used by the regression at date $t$; like the lagged exposures, they are
    built from market caps at $t - \text{lag}$ and idiosyncratic variances
    estimated up to $t - 1$. `None` for time-series factor models.

  **benchmark_weights** *ndarray of shape (n_observations, n_assets) or None*
  : Benchmark weights used for weighted cross-sectional diagnostics. Non-negative.
    `None` for time-series factor models.

  **family_constraint_basis** *FamilyConstraintBasis or None*
  : Compact basis encoding the family-constraint change of coordinates. Used by
    cross-sectional factor models with linear constraints across factor families
    (e.g. industry sum-to-zero). When present, diagnostics (t-statistics, VIF,
    condition number) and adjusted $R^2$ are computed in the reduced basis
    where constrained families are full-rank.

### Methods

| [`cs_regression_t_stat_exceedance_rate`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.cs_regression_t_stat_exceedance_rate)([threshold])   | Fraction of observations with significant cross-sectional regression t-statistics.                                       |
|------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| [`enrich_asset_panel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.enrich_asset_panel)(panel[, copy])                   | Add factor-model fields to an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel). |
| [`exposure_correlation`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.exposure_correlation)([factors, families, ...])      | Time-average pairwise correlation matrix of factor exposures.                                                            |
| [`exposure_ic_summary`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.exposure_ic_summary)([correlation_method, ...])      | Summary statistics for exposure Information Coefficients (ICs).                                                          |
| [`factor_forecast_correlation`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.factor_forecast_correlation)([factors, families])    | Factor return correlation forecast from `factor_covariance`.                                                             |
| [`idio_calibration_summary`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.idio_calibration_summary)()                          | Summary statistics for the calibration quality of standardized idiosyncratic                                             |
| [`idio_tail_rate`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.idio_tail_rate)([threshold])                         | Fraction of assets with extreme standardized idiosyncratic returns.                                                      |
| [`plot_cs_regression_scores`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_cs_regression_scores)([score, window, title])   | Plot a cross-sectional regression score over time.                                                                       |
| [`plot_cs_regression_t_stat_exceedance_rate`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_cs_regression_t_stat_exceedance_rate)([...])    | Bar chart of the cross-sectional regression t-statistic exceedance rate.                                                 |
| [`plot_cs_regression_t_stats`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_cs_regression_t_stats)([factors, ...])          | Plot absolute cross-sectional regression t-statistics over time per factor.                                              |
| [`plot_cumulative_exposure_ic`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_cumulative_exposure_ic)([...])                  | Cumulative exposure Information Coefficient (IC) over time.                                                              |
| [`plot_exposure_condition_number`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_condition_number)([window, title])     | Plot the exposure Gram-matrix condition number over time.                                                                |
| [`plot_exposure_correlation`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_correlation)([factors, ...])           | Time-average pairwise correlation heatmap of factor exposures.                                                           |
| [`plot_exposure_dispersion`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_dispersion)([factors, ...])            | Cross-sectional standard deviation of exposures over time.                                                               |
| [`plot_exposure_distribution`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_distribution)(factor[, ...])           | Cross-sectional histogram of exposures for a single factor.                                                              |
| [`plot_exposure_stability`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_stability)([factors, families, ...])   | Weighted cross-sectional correlation of exposures between observation $t$ and $t + \text{step}$ over time.               |
| [`plot_exposure_vif`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_vif)([factors, families, ...])         | Plot exposure Variance Inflation Factors over time per factor.                                                           |
| [`plot_factor_cumulative_returns`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_factor_cumulative_returns)([factors, ...])      | Cumulative (non-compounded) factor returns over time.                                                                    |
| [`plot_factor_forecast_correlation`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_factor_forecast_correlation)([factors, ...])    | Factor return correlation forecast heatmap from `factor_covariance`.                                                     |
| [`plot_factor_forecast_volatilities`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_factor_forecast_volatilities)([factors, ...])   | Bar chart of annualized factor volatility forecasts.                                                                     |
| [`plot_idio_calibration`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_calibration)([window, title])              | Cross-sectional std of standardized idiosyncratic returns over time.                                                     |
| [`plot_idio_kurtosis`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_kurtosis)([window, title])                 | Cross-sectional excess kurtosis of standardised idiosyncratic returns over time.                                         |
| [`plot_idio_skewness`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_skewness)([window, title])                 | Cross-sectional skewness of standardised idiosyncratic returns over time.                                                |
| [`plot_idio_tail_rate`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_tail_rate)([threshold, window, title])     | Plot the idiosyncratic tail exceedance rate over time.                                                                   |
| [`plot_idio_vol_ic`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_vol_ic)([window, title])                   | Information Coefficient (IC) of idiosyncratic volatility estimates.                                                      |
| [`plot_idio_vol_residual_dependence`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_vol_residual_dependence)([window, ...])    | Residual dependence of standardized idiosyncratic returns on predicted idiosyncratic volatility.                         |
| [`predicted_attribution`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.predicted_attribution)(weights[, ...])               | Compute ex-ante (predicted) factor volatility and return attribution.                                                    |
| [`realized_attribution`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.realized_attribution)(weights, portfolio_returns)    | Compute realized (ex-post) factor volatility and return attribution.                                                     |
| [`rolling_realized_attribution`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.rolling_realized_attribution)(weights, ...[, ...])   | Compute rolling realized (ex-post) factor attribution.                                                                   |
| [`select_assets`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.select_assets)([assets, slim])                       | Return a new `FactorModel` restricted to selected assets.                                                                |
| [`select_observations`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.select_observations)(observations)                   | Return a new `FactorModel` restricted to selected observations.                                                          |
| [`summary`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.summary)([factors, families, ...])                   | Summary statistics for the factor model.                                                                                 |

<a id="skfolio.prior.FactorModel.covariance_sqrt"></a>

#### *property* covariance_sqrt

Covariance square root exploiting the factor structure.

Decomposes the asset covariance $\Sigma = B\,\Sigma_f\,B^\top + D$ into a
[`CovarianceSqrt`](https://skfolio.org/generated/skfolio.prior.CovarianceSqrt.html.md#skfolio.prior.CovarianceSqrt) that separates the systematic and
idiosyncratic contributions, allowing SOC-based optimizers to work with smaller
matrices.

When idiosyncratic covariance is diagonal, the decomposition avoids an
$(n \times n)$ Cholesky entirely and represents the idiosyncratic part as
an element-wise multiply.

When family constraints are present, the full-basis factor covariance
$R\,\Sigma_f^{\mathrm{red}}\,R^\top$ is rank-deficient. The systematic
square root is then built from the full-rank [`effective_loading_matrix`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.effective_loading_matrix)
and [`effective_factor_covariance`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.effective_factor_covariance), which keeps the Cholesky exact and the
systematic component minimal.

* **Returns:**
  CovarianceSqrt

<a id="skfolio.prior.FactorModel.cs_regression_scores"></a>

#### *property* cs_regression_scores

Fit diagnostics for each cross-sectional factor regression.

This property is available when the model contains point-in-time
exposures, estimated factor returns and idiosyncratic returns, as in
characteristics-based cross-sectional factor models. It is not available
for time-series factor models without point-in-time exposures.

* `r2`: cross-sectional $R^2$,

$$
R^2_t = 1 - \frac{\sum_i w_{ti}\,\varepsilon_{ti}^2}
                 {\sum_i w_{ti}\,(r_{ti} - \bar{r}_t)^2}
$$

* `adjusted_r2`: $R^2$ adjusted for the effective number of regressors
  $k$,

$$
\bar{R}^2_t = 1 - (1 - R^2_t)\,\frac{n_t - 1}{n_t - k - 1}
$$

* `aic`: Akaike Information Criterion,

$$
\mathrm{AIC}_t = n_t \ln\!\left(\frac{\mathrm{RSS}_t}{n_t}\right) + 2k
$$

* `bic`: Bayesian Information Criterion,

$$
\mathrm{BIC}_t = n_t \ln\!\left(\frac{\mathrm{RSS}_t}{n_t}\right)
+ k \ln(n_t)
$$

Here $n_t$ is the number of valid samples at observation $t$ and
$k = \text{n\_regressors}$ is the effective number of regressors (reduced
dimension when family constraints are active). Lower AIC/BIC indicate a better
fit-complexity trade-off; BIC penalises complexity more heavily than AIC for
large cross-sections.

* **Returns:**
  **scores** *DataFrame of shape (n_observations - exposure_lag, 4)*
  : Index aligned with the lagged regression observations.
    Columns: `r2`, `adjusted_r2`, `aic`, `bic`.

<a id="skfolio.prior.FactorModel.cs_regression_t_stat_exceedance_rate"></a>

#### cs_regression_t_stat_exceedance_rate(threshold=2.0)

Fraction of observations with significant cross-sectional regression t-statistics.

The t-statistic exceedance rate measures how often a factor’s cross-sectional
t-statistic exceeds the absolute threshold: $|t| > \text{threshold}$.
With `threshold=2.0`, a factor whose true cross-sectional coefficient is zero
and whose t-statistics are approximately Gaussian would exceed the threshold
about 5 % of the time. Rates above this reference level indicate that the factor
is repeatedly significant across observations.

* **Parameters:**
  **threshold** *float, default=2.0*
  : Absolute t-statistic threshold for significance.
* **Returns:**
  **cs_regression_t_stat_exceedance_rate** *Series*
  : Shape `(n_reduced_factors,)`.
    Fraction of significant observations per factor.

<a id="skfolio.prior.FactorModel.cs_regression_t_stats"></a>

#### *property* cs_regression_t_stats

Cross-sectional regression coefficient t-statistics.

$$
t_{tj} = \frac{\hat{\beta}_{tj}}{\mathrm{SE}(\hat{\beta}_{tj})}
$$

where $\hat{\beta}_{tj}$ is the estimated coefficient of factor
$j$ at observation $t$. In a cross-sectional factor model,
this coefficient is the per-observation factor return. The standard error is
derived from $\hat\sigma^2_t (X^\top W X)^{-1}$.

A common rule of thumb is that $|t| > 2$ suggests significance at
approximately the 5 % level.

When `family_constraint_basis` is set, the design matrix and factor
returns are projected into the reduced (full-rank) basis, so the columns are the
reduced-basis factor names rather than the full `factor_names`.

* **Returns:**
  **cs_regression_t_stats** *DataFrame*
  : Time-indexed t-statistics of shape
    `(n_observations - exposure_lag, n_reduced_factors)`.

<a id="skfolio.prior.FactorModel.effective_exposures"></a>

#### *property* effective_exposures

Full-rank historical exposures, reduced when family constraints are present.

When the factor model uses family constraints, the full-basis exposure tensor is
rank-deficient because constrained factor families introduce linear dependencies
among columns. This property converts the historical exposures to the same
reduced full-rank basis as [`effective_loading_matrix`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.effective_loading_matrix).

When `family_constraint_basis` is `None`, the historical exposures are
returned unchanged.

* **Returns:**
  **exposures** *ndarray of shape (n_observations, n_assets, n_reduced_factors)*
  : Historical full-rank exposure tensor.

<a id="skfolio.prior.FactorModel.effective_factor_covariance"></a>

#### *property* effective_factor_covariance

Full-rank factor covariance, reduced when family constraints are present.

When the factor model uses family constraints, the full-basis factor covariance
$R\,\Sigma_f^{\mathrm{red}}\,R^\top$ is rank-deficient. This property
returns the reduced full-rank covariance aligned with
[`effective_loading_matrix`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.effective_loading_matrix), so that decompositions (e.g. Cholesky) and
SOC-based optimizers operate on a positive definite matrix.

When `family_constraint_basis` is `None`, the covariance is returned
unchanged.

* **Returns:**
  **factor_covariance** *ndarray of shape (n_reduced_factors, n_reduced_factors)*
  : Full-rank factor covariance.

<a id="skfolio.prior.FactorModel.effective_factor_families"></a>

#### *property* effective_factor_families

Factor families aligned with the effective reduced basis.

<a id="skfolio.prior.FactorModel.effective_factor_names"></a>

#### *property* effective_factor_names

Factor names aligned with the effective reduced basis.

<a id="skfolio.prior.FactorModel.effective_loading_matrix"></a>

#### *property* effective_loading_matrix

Full-rank loading matrix, reduced when family constraints are present.

When the factor model uses family constraints, the full-basis loading matrix is
rank-deficient because constrained factor families introduce linear dependencies
among columns. This property converts it to the reduced (full-rank) basis so
that downstream computations (e.g. orthogonal projectors) correctly identify the
factor span.

When `family_constraint_basis` is `None`, the loading matrix is returned
unchanged.

* **Returns:**
  **loading** *ndarray of shape (n_assets, n_reduced_factors)*
  : Full-rank loading matrix.

<a id="skfolio.prior.FactorModel.enrich_asset_panel"></a>

#### enrich_asset_panel(panel, copy=True)

Add factor-model fields to an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel).

The returned panel contains the fields required by alpha estimators:
`idio_returns`, `idio_variances`, `regression_weights` and `exposures`.
Observations and assets are aligned by label. Panel observations that are not
present in the factor model are kept and filled with missing values, except
`regression_weights`, which is filled with zero. The asset set must match
exactly, although the order may differ. If `panel` is an
[`AssetPanelView`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView), enriched fields are added as
view-local fields.

When family constraints are present, `exposures` are added in the reduced
full-rank basis used by the cross-sectional regression and factor covariance
estimator.

* **Parameters:**
  **panel** *AssetPanel or AssetPanelView*
  : Panel or observation view to enrich.

  **copy** *bool, default=True*
  : If `True`, enrich a shallow copy of `panel`. If `False`, mutate `panel`.
* **Returns:**
  **enriched_panel** *AssetPanel or AssetPanelView*
  : Panel or view containing the factor-model fields.
* **Raises:**
  TypeError
  : If `panel` is not an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) or
    [`AssetPanelView`](https://skfolio.org/generated/skfolio.containers.AssetPanelView.html.md#skfolio.containers.AssetPanelView).

  ValueError
  : If required factor-model histories are unavailable, if labels cannot be
    aligned, or if any target field already exists.

<a id="skfolio.prior.FactorModel.exposure_condition_number"></a>

#### *property* exposure_condition_number

Condition number of the exposure Gram matrix per observation.

The condition number $\kappa(X^\top W X)$ is the ratio of the largest to
smallest singular value. Large values indicate near-singular design matrices
and numerically unstable coefficient estimates. When `family_constraint_basis`
is set, the Gram matrix is built in the reduced (full-rank) basis.

* **Returns:**
  **exposure_condition_number** *Series*
  : Time-indexed condition numbers of shape
    `(n_observations - exposure_lag,)`.

<a id="skfolio.prior.FactorModel.exposure_correlation"></a>

#### exposure_correlation(factors=None, families=None, cs_weighting=BENCHMARK)

Time-average pairwise correlation matrix of factor exposures.

Highly correlated exposures indicate redundant factors. They are a
cross-sectional analogue of multicollinearity diagnostics used in regression,
where redundant predictors can inflate variance inflation factors (VIFs).

Pairs involving a factor with degenerate cross-sectional variance (e.g. the
constant global factor exposure) have an undefined correlation and are
reported as zero by convention. When two factors are never finite on at
least 3 common assets at any observation, their correlation cannot be
estimated and is reported as NaN.

* **Parameters:**
  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over `families` when
    specified.

  **families** *str, list of str, or None, optional*
  : Factor families to include. `None` includes all factors. Ignored when
    `factors` is given or when `factor_families` is `None`.

  **cs_weighting** *CSWeighting, default=CSWeighting.BENCHMARK*
  : Cross-sectional weights for the correlation computation. Falls back
    to `CSWeighting.IDENTITY` with a warning when unavailable.
* **Returns:**
  **corr** *ndarray of shape (n_selected_factors, n_selected_factors)*
  : Time-average correlation matrix.

<a id="skfolio.prior.FactorModel.exposure_ic_summary"></a>

#### exposure_ic_summary(correlation_method=SPEARMAN, horizon=1, factors=None, families=None)

Summary statistics for exposure Information Coefficients (ICs).

Measures the cross-sectional correlation between factor exposures at $t$
and the forward mean asset return from $t + 1$ to $t + h$, where
$h$ is the forecast *horizon*.

#### NOTE
The IC quantifies **return-predictive** power. In a **risk model**, factors
are designed to explain covariance structure, not to predict expected
returns. A factor can be an excellent risk factor even when
$\mathbb{E}[\text{IC}] \approx 0$. Do not discard a risk factor solely
because its IC is low: use exposure stability, bias statistics, and variance
contribution instead.

* **Parameters:**
  **correlation_method** *CorrelationMethod, default=CorrelationMethod.SPEARMAN*
  : Correlation method used for the exposure IC. `SPEARMAN` computes
    Spearman rank IC. `PEARSON` computes Pearson IC, weighted by
    `regression_weights` when available.

  **horizon** *int, default=1*
  : Forward window in number of observations. The mean return from
    $t + 1$ to $t + h$ is used.

  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over `families` when
    specified.

  **families** *str, list of str, optional*
  : Factor families to include. `None` includes all factors.
* **Returns:**
  **summary** *DataFrame of shape (n_selected_factors, 4)*
  : Columns: `mean_ic`, `std_ic`, `ic_ir`, `hit_rate`.

<a id="skfolio.prior.FactorModel.exposure_vif"></a>

#### *property* exposure_vif

Variance Inflation Factor of the exposure design per observation.

VIF measures how much the variance of a cross-sectional regression coefficient
is inflated due to collinearity among factor exposures:

$$
\mathrm{VIF}_k = (X^\top W X)_{kk} \cdot
                 [(X^\top W X)^{-1}]_{kk}
$$

A VIF of 1 indicates no collinearity; values above 5-10 suggest problematic
multicollinearity.

When `family_constraint_basis` is set, VIFs are computed in the reduced
(full-rank) basis.

* **Returns:**
  **exposure_vif** *DataFrame*
  : Time-indexed VIF values of shape
    `(n_observations - exposure_lag, n_reduced_factors)`.

<a id="skfolio.prior.FactorModel.exposures_df"></a>

#### *property* exposures_df

Exposures as a MultiIndex DataFrame of shape
(n_observations, n_factors \* n_assets).

<a id="skfolio.prior.FactorModel.factor_forecast_correlation"></a>

#### factor_forecast_correlation(factors=None, families=None)

Factor return correlation forecast from `factor_covariance`.

* **Parameters:**
  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over
    `families` when specified.

  **families** *str, list of str, optional*
  : Factor families to include. `None` includes all factors.
    Ignored when `factors` is given or when
    `factor_families` is `None`.
* **Returns:**
  **corr** *ndarray of shape (n_selected_factors, n_selected_factors)*
  : Symmetric factor return correlation matrix with diagonal entries
    fixed to 1.

<a id="skfolio.prior.FactorModel.factor_returns_df"></a>

#### *property* factor_returns_df

Factor returns DataFrame of shape (n_observations, n_factors).

<a id="skfolio.prior.FactorModel.idio_calibration"></a>

#### *property* idio_calibration

Cross-sectional std of standardized idiosyncratic returns.

<a id="skfolio.prior.FactorModel.idio_calibration_summary"></a>

#### idio_calibration_summary()

Summary statistics for the calibration quality of standardized idiosyncratic
: returns.

Computes time-aggregated statistics of the cross-sectional distribution of
standardized idiosyncratic returns
$z_{it} = \epsilon_{it} / \hat\sigma_{i,t}$.

Under a Gaussian assumption, the expected values are $\text{std}(z) = 1$,
excess kurtosis $= 0$, skewness $= 0$, and the 3-$\sigma$ tail
rate $\approx 0.27\%$. In practice, standardized idiosyncratic returns
exhibit fat tails, so the tail rate is typically well above 0.27% (values
around 1–3% are common for equity factor models).

- `mean_cs_std` close to 1.0 indicates correctly scaled specific risk.
  Values persistently above 1 suggest underestimated risk; below 1 suggests
  overestimated risk.
- `mean_tail_rate_3sigma` is expected to exceed the Gaussian reference due to
  fat tails.
- `mean_cs_excess_kurtosis` > 0 (fat tails) and moderate `mean_cs_skewness` are
  typical.

* **Returns:**
  **summary** *Series*
  : Index: `mean_cs_std`, `median_cs_std`, `mean_cs_excess_kurtosis`,
    `mean_cs_skewness`, `mean_tail_rate_3sigma`.

<a id="skfolio.prior.FactorModel.idio_kurtosis"></a>

#### *property* idio_kurtosis

Cross-sectional excess kurtosis of standardized idiosyncratic returns.

<a id="skfolio.prior.FactorModel.idio_returns_df"></a>

#### *property* idio_returns_df

Idiosyncratic returns DataFrame of shape (n_observations, n_assets).

<a id="skfolio.prior.FactorModel.idio_skewness"></a>

#### *property* idio_skewness

Cross-sectional skewness of standardized idiosyncratic returns.

<a id="skfolio.prior.FactorModel.idio_tail_rate"></a>

#### idio_tail_rate(threshold=3.0)

Fraction of assets with extreme standardized idiosyncratic returns.

For each observation, computes the cross-sectional fraction of available
standardized idiosyncratic returns whose absolute value exceeds
`threshold`:

$$
\frac{1}{n_t}\sum_i \mathbf{1}\{|z_{i,t}| > c\},
$$

where $z_{i,t}$ is the standardized idiosyncratic return, $c$
is `threshold`, and $n_t$ is the number of finite standardized
idiosyncratic returns at observation $t$.

Under a Gaussian reference model, the expected rate is
$2\Phi(-c)$. Higher realized rates indicate that the standardized
residuals have heavier tails than implied by the idiosyncratic volatility
estimates. In equity factor models, standardized idiosyncratic returns
are often fat-tailed, so rates above the Gaussian reference are common.

* **Parameters:**
  **threshold** *float, default=3.0*
  : Absolute standardized-return threshold $c$.
* **Returns:**
  **tail_rate** *Series of shape (n_observations,)*
  : Time series of cross-sectional tail exceedance rates, indexed by
    `observations`.

<a id="skfolio.prior.FactorModel.idio_vol_ic"></a>

#### *property* idio_vol_ic

Information Coefficient of idiosyncratic volatility estimates.

Computes the cross-sectional rank correlation (Spearman) between the predicted
specific volatility $\hat\sigma_{i,t}$ and the next-period absolute
idiosyncratic return $|\epsilon_{i,t+1}|$.

If the model captures the cross-sectional scale of idiosyncratic shocks, then
assets with larger $\hat\sigma_{i,t}$ should tend to realize larger
absolute moves at $t + 1$.

* High positive values indicate that the model ranks cross-sectional differences
  in idiosyncratic volatility well.
* This diagnostic can also pick up broad cross-sectional scale effects such as
  size or liquidity, so it should be read together with
  [`idio_vol_residual_dependence`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.idio_vol_residual_dependence) which checks whether the standardized
  idiosyncratic return magnitude $|z_{i,t+1}|$ still depends on the
  predicted volatility level.

<a id="skfolio.prior.FactorModel.idio_vol_residual_dependence"></a>

#### *property* idio_vol_residual_dependence

Residual dependence of standardized idiosyncratic returns on predicted
idiosyncratic volatility.

Computes the cross-sectional rank correlation (Spearman) between the predicted
specific volatility $\hat\sigma_{i,t}$ and the next-period standardized
absolute idiosyncratic return
$|\epsilon_{i,t+1}| / \hat\sigma_{i,t} = |z_{i,t+1}|$.
If the volatility forecast is well calibrated, this standardized magnitude
should be roughly independent of $\hat\sigma_{i,t}$, so the correlation
should be close to 0.

Read together with [`idio_vol_ic`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.idio_vol_ic), this diagnostic helps separate ranking
power from calibration. A desirable pattern is a high [`idio_vol_ic`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.idio_vol_ic)
combined with residual dependence near 0.

<a id="skfolio.prior.FactorModel.plot_cs_regression_scores"></a>

#### plot_cs_regression_scores(score='adjusted_r2', window=30, title=None)

Plot a cross-sectional regression score over time.

Draws the selected per-observation score as a faded line and overlays its
rolling mean over `window` observations to highlight changes in fit quality.
A horizontal line marks the full-sample average and is annotated with its
numerical value.

* **Parameters:**
  **score** *str, default=”adjusted_r2”*
  : Score to plot. Must be one of `"r2"`, `"adjusted_r2"`, `"aic"`, or `"bic"`.

  **window** *int, default=30*
  : Number of observations required for the rolling mean.

  **title** *str, optional*
  : Custom title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_cs_regression_t_stat_exceedance_rate"></a>

#### plot_cs_regression_t_stat_exceedance_rate(factors=None, families=None, threshold=2.0, title=None)

Bar chart of the cross-sectional regression t-statistic exceedance rate.

The t-statistic exceedance rate is the fraction of observations where
$|t| >$ `threshold`. A vertical reference line at 5% marks the
conventional null-rate benchmark used at `threshold = 2`; for other thresholds
it is only an approximate guide and the exact Gaussian null rate is
$2\,\Phi(-\text{threshold})$.

* **Parameters:**
  **factors** *list of str, optional*
  : Subset of factor names to include. Takes precedence over `families` when
    specified.

  **families** *str, list of str, optional*
  : Factor families to include. Ignored when `factors` is given.

  **threshold** *float, default=2.0*
  : Absolute t-statistic threshold.

  **title** *str, optional*
  : Custom title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_cs_regression_t_stats"></a>

#### plot_cs_regression_t_stats(factors=None, families=None, window=None, title=None)

Plot absolute cross-sectional regression t-statistics over time per factor.

When `window` is provided, plots the rolling mean of $|t|$ over
`window` observations instead of the raw values. A horizontal reference line
at $|t| = 2$ marks the conventional significance threshold.

* **Parameters:**
  **factors** *list of str, optional*
  : Subset of factor names to include.

  **families** *str, list of str, optional*
  : Factor families to include. Ignored when `factors` is given.

  **window** *int, optional*
  : If provided, plot the rolling mean of $|t|$.

  **title** *str, optional*
  : Custom title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_cumulative_exposure_ic"></a>

#### plot_cumulative_exposure_ic(correlation_method=SPEARMAN, factors=None, families=None, title=None)

Cumulative exposure Information Coefficient (IC) over time.

Plots the cumulative sum of the single-period cross-sectional correlation
between factor exposures at $t$ and asset returns at $t + 1$.

- A monotonically rising curve indicates persistent predictive power
  (positive alpha signal).
- A flat curve means the factor carries no return-predictive information.
- A declining curve indicates a contrarian signal (negative alpha).

For IC decay analysis across different holding periods, use
[`exposure_ic_summary`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.exposure_ic_summary) with varying `horizon` values instead.

#### NOTE
The IC quantifies **return-predictive** power. In a **risk model**, factors
are designed to explain covariance structure, not to predict expected
returns. A factor can be an excellent risk factor even when
$\mathbb{E}[\text{IC}] \approx 0$.

* **Parameters:**
  **correlation_method** *CorrelationMethod, default=CorrelationMethod.SPEARMAN*
  : Correlation method used for the exposure IC. `SPEARMAN` computes
    Spearman rank IC. `PEARSON` computes Pearson IC, weighted by
    `regression_weights` when available.

  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over `families` when
    specified.

  **families** *str, list of str, optional*
  : Factor families to include. `None` includes all factors.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_exposure_condition_number"></a>

#### plot_exposure_condition_number(window=30, title=None)

Plot the exposure Gram-matrix condition number over time.

Draws the per-observation condition number as a faded line and overlays its
rolling mean over `window` observations. Large values indicate near-collinear
exposures and less stable coefficient estimates.

* **Parameters:**
  **window** *int, default=30*
  : Number of observations required for the rolling mean.

  **title** *str, optional*
  : Custom title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_exposure_correlation"></a>

#### plot_exposure_correlation(factors=None, families=None, cs_weighting=BENCHMARK, title=None)

Time-average pairwise correlation heatmap of factor exposures.

Highly correlated exposures indicate redundant factors and may
inflate VIF.

* **Parameters:**
  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over `families` when
    specified.

  **families** *str, list of str, or None, default=”style”*
  : Factor families to include. `None` includes all factors. Ignored when
    `factors` is given or when `factor_families` is `None`.

  **cs_weighting** *CSWeighting, default=CSWeighting.BENCHMARK*
  : Cross-sectional weights for the correlation computation. Falls back
    to `CSWeighting.IDENTITY` with a warning when unavailable.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_exposure_dispersion"></a>

#### plot_exposure_dispersion(factors=None, families='style', cs_weighting=BENCHMARK, title=None)

Cross-sectional standard deviation of exposures over time.

The absolute level depends on how exposures were standardized upstream. When
the model uses weighted-mean centering or a different variance normalization,
the equal-weighted cross-sectional std computed here will not be 1.0. Focus on
temporal stability rather than the absolute level: a collapse may signal
data-feed issues and an explosion may indicate an outlier.

* **Parameters:**
  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over `families` when
    specified.

  **families** *str, list of str, or None, default=”style”*
  : Factor families to include. `None` includes all factors. Ignored when
    `factors` is given or when `factor_families` is `None`.

  **cs_weighting** *CSWeighting, default=CSWeighting.BENCHMARK*
  : Cross-sectional weights for the std computation. Falls back to
    `CSWeighting.IDENTITY` with a warning when unavailable.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_exposure_distribution"></a>

#### plot_exposure_distribution(factor, observation_idx=None, n_bins=None, title=None)

Cross-sectional histogram of exposures for a single factor.

When `observation` is `None` (default), all observations are pooled into one
histogram showing the typical distribution. When an integer index is provided,
only the exposures at that observation are plotted.

* **Parameters:**
  **factor** *str*
  : Name of the factor to plot.

  **observation_idx** *int , optional*
  : Observation index. `None` pools all dates, `-1` selects the last
    observation, `0` the first, etc.

  **n_bins** *int , optional*
  : Number of histogram bins. `None` lets Plotly choose automatically.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_exposure_stability"></a>

#### plot_exposure_stability(factors=None, families='style', step=21, cs_weighting=BENCHMARK, title=None)

Weighted cross-sectional correlation of exposures between observation
$t$ and $t + \text{step}$ over time.

Measures whether the cross-sectional exposures are stable across the chosen
horizon.

The expected level depends on the factor’s investment horizon. Slow-moving
factors (e.g. value, size) should maintain high correlation at the default
monthly step and values consistently below 0.80 may indicate noisy or poorly
constructed exposures. Fast-turnover factors (e.g. reversal, short-term
momentum) are designed to reshuffle quickly and will naturally show low monthly
stability. For these factors, use a shorter `step` (e.g., 1-5 for daily data) to
assess stability at the relevant horizon.

* **Parameters:**
  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over `families` when
    specified.

  **families** *str, list of str, or None, default=”style”*
  : Factor families to include. `None` includes all factors. Ignored when
    `factors` is given or when `factor_families` is `None`.

  **step** *int, default=21*
  : Number of observations between the two cross-sections being compared (e.g.,
    21 for approximately monthly stability with daily data).

  **cs_weighting** *CSWeighting, default=CSWeighting.BENCHMARK*
  : Cross-sectional weights for the correlation computation. Falls back
    to `CSWeighting.IDENTITY` with a warning when unavailable.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_exposure_vif"></a>

#### plot_exposure_vif(factors=None, families=None, window=None, title=None)

Plot exposure Variance Inflation Factors over time per factor.

When `window` is provided, plots the rolling mean over `window` observations
instead of raw per-observation values. A horizontal reference line at VIF = 5
marks the conventional collinearity threshold.

* **Parameters:**
  **factors** *list of str, optional*
  : Subset of factor names to include.

  **families** *str, list of str, optional*
  : Factor families to include. Ignored when `factors` is given.

  **window** *int, optional*
  : If provided, plot the rolling mean.

  **title** *str, optional*
  : Custom title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_factor_cumulative_returns"></a>

#### plot_factor_cumulative_returns(factors=None, families=None, title=None)

Cumulative (non-compounded) factor returns over time.

* **Parameters:**
  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over `families` when
    specified.

  **families** *str, list of str, or None, default=”style”*
  : Factor families to include. `None` includes all factors. Ignored when
    `factors` is given or when `factor_families` is `None`.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_factor_forecast_correlation"></a>

#### plot_factor_forecast_correlation(factors=None, families=None, title=None)

Factor return correlation forecast heatmap from `factor_covariance`.

* **Parameters:**
  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over `families` when
    specified.

  **families** *str, list of str, or None, default=”style”*
  : Factor families to include. `None` includes all factors. Ignored when
    `factors` is given or when `factor_families` is `None`.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_factor_forecast_volatilities"></a>

#### plot_factor_forecast_volatilities(factors=None, families=None, annualization_factor=252.0, title=None)

Bar chart of annualized factor volatility forecasts.

Computes annualized volatility as
$\sqrt{\mathrm{diag}(\Sigma_F) \cdot \text{annualization\_factor}}$
from `factor_covariance`. Distinct from realized historical volatility
in [`summary`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.summary).

* **Parameters:**
  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over `families` when
    specified.

  **families** *str, list of str, or None, default=”style”*
  : Factor families to include. `None` includes all factors. Ignored when
    `factors` is given or when `factor_families` is `None`.

  **annualization_factor** *float, default=252.0*
  : Number of observations per year.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_idio_calibration"></a>

#### plot_idio_calibration(window=None, title=None)

Cross-sectional std of standardized idiosyncratic returns over time.

Under correct calibration, $\text{std}(z_t) \approx 1$. Persistent
deviations indicate mis-specified specific risk.

* **Parameters:**
  **window** *int, optional*
  : Rolling-mean smoothing window.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_idio_kurtosis"></a>

#### plot_idio_kurtosis(window=None, title=None)

Cross-sectional excess kurtosis of standardised idiosyncratic returns over
time.

Each point is the excess kurtosis of $z_{it}$ computed across assets at a
single observation. The Gaussian reference is zero, but positive values are
expected because standardised idiosyncratic returns typically have fat tails.

* **Parameters:**
  **window** *int, optional*
  : Rolling-mean smoothing window.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_idio_skewness"></a>

#### plot_idio_skewness(window=None, title=None)

Cross-sectional skewness of standardised idiosyncratic returns over time.

Each point is the skewness of $z_{it}$ computed across assets at a single
observation. The Gaussian reference is zero. Mild negative skewness is common
for equity factor models.

* **Parameters:**
  **window** *int, optional*
  : Rolling-mean smoothing window.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_idio_tail_rate"></a>

#### plot_idio_tail_rate(threshold=3.0, window=None, title=None)

Plot the idiosyncratic tail exceedance rate over time.

For each observation, the plotted value is the fraction of assets whose
finite standardized idiosyncratic return satisfies
$|z_{i,t}| > \text{threshold}$. When `window` is provided, the rolling
mean is plotted to smooth short-lived cross-sectional tail spikes.

A dashed reference line shows the Gaussian rate
$2\,\Phi(-\text{threshold})$, which is about 0.27% when `threshold = 3`.
Persistent values above this reference indicate heavier idiosyncratic residual
tails than implied by the volatility estimates. In equity factor models,
standardized idiosyncratic returns are often fat-tailed, so observed rates above
the Gaussian reference are common.

* **Parameters:**
  **threshold** *float, default=3.0*
  : Absolute standardized-return threshold.

  **window** *int, optional*
  : Rolling-mean smoothing window.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_idio_vol_ic"></a>

#### plot_idio_vol_ic(window=60, title=None)

Information Coefficient (IC) of idiosyncratic volatility estimates.

Plots the cross-sectional rank correlation (Spearman) between the predicted
specific volatility $\hat\sigma_{i,t}$ and the next-period absolute
idiosyncratic return $|\epsilon_{i,t+1}|$.

This is a ranking diagnostic: do names predicted to have larger
$\hat\sigma_{i,t}$ tend to realize larger raw absolute moves.

- High positive values indicate that the model ranks cross-sectional differences
  in idiosyncratic volatility well.
- This diagnostic can also pick up broad cross-sectional scale effects such as
  size or liquidity.

This is a ranking diagnostic, not a calibration diagnostic. For the
post-standardization check, see [`plot_idio_vol_residual_dependence`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_vol_residual_dependence).

* **Parameters:**
  **window** *int, default=60*
  : Rolling window for the smoothed mean.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.plot_idio_vol_residual_dependence"></a>

#### plot_idio_vol_residual_dependence(window=60, title=None)

Residual dependence of standardized idiosyncratic returns on predicted
idiosyncratic volatility.

Plots the cross-sectional rank correlation (Spearman) between the predicted
specific volatility $\hat\sigma_{i,t}$ and the next-period standardized
absolute idiosyncratic return
$|\epsilon_{i,t+1}| / \hat\sigma_{i,t} = |z_{i,t+1}|$.
If the volatility forecast is well calibrated, this standardized magnitude
should be roughly independent of $\hat\sigma_{i,t}$, so the correlation
should be close to 0.

Read together with [`plot_idio_vol_ic`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_vol_ic), this helps distinguish ranking
power from calibration. A desirable pattern is high [`plot_idio_vol_ic`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_vol_ic)
together with residual dependence near 0.

* **Parameters:**
  **window** *int, default=60*
  : Rolling window for the smoothed mean.

  **title** *str, optional*
  : Custom figure title.
* **Returns:**
  **fig** *go.Figure*

<a id="skfolio.prior.FactorModel.predicted_attribution"></a>

#### predicted_attribution(weights, annualization_factor=252.0, compute_asset_breakdowns=True)

Compute ex-ante (predicted) factor volatility and return attribution.

Decomposes portfolio volatility using the exposure-volatility-correlation
framework ($x$-$\sigma$-$\rho$) and, when
`factor_mu` is available, decomposes expected return into factor-spanned
and factor-orthogonal components.

See [`predicted_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.predicted_factor_attribution.html.md#skfolio.attribution.predicted_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **weights** *array-like of shape (n_assets,)*
  : Portfolio weights vector.

  **annualization_factor** *float, default=252.0*
  : Annualization factor applied to variances and expected returns
    (volatilities are scaled by $\sqrt{\text{annualization\_factor}}$).
    Use 1.0 to disable annualization.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset systematic/idiosyncratic
    decomposition. Set to `False` for faster computation when
    only portfolio-level results are needed.
* **Returns:**
  **attribution** *Attribution*
  : Component-level, factor-level, and optionally asset-level
    attribution results.

<a id="skfolio.prior.FactorModel.realized_attribution"></a>

#### realized_attribution(weights, portfolio_returns, annualization_factor=252.0, compute_asset_breakdowns=True, compute_uncertainty=True)

Compute realized (ex-post) factor volatility and return attribution.

Decomposes realized portfolio risk and return into contributions
from individual factors and idiosyncratic sources using actual
historical data rather than model-predicted covariances.

See [`realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.realized_factor_attribution.html.md#skfolio.attribution.realized_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **weights** *array-like of shape (n_assets,) or (n_observations, n_assets)*
  : Portfolio weights. If 1D, the same weights are used for all
    observations. If 2D, time-varying weights are used.

  **portfolio_returns** *array-like of shape (n_observations,)*
  : Portfolio return time series.

  **annualization_factor** *float, default=252.0*
  : Annualization factor applied to variances and mean returns
    (volatilities are scaled by $\sqrt{\text{annualization\_factor}}$).
    Use 1.0 to disable annualization.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset attribution breakdowns. Set to `False`
    for faster computation when only portfolio-level results are
    needed.

  **compute_uncertainty** *bool, default=True*
  : If `True`, compute attribution uncertainty (standard errors on
    the factor/idiosyncratic PnL split). Requires both
    `regression_weights` and `idio_variances` to be available
    in this factor model; raises `ValueError` otherwise.
* **Returns:**
  **attribution** *Attribution*
  : Component-level, factor-level, and optionally asset-level
    attribution results.
* **Raises:**
  ValueError
  : If `factor_returns`, `exposures`, or `idio_returns` is
    not available, or if `compute_uncertainty=True` but
    `regression_weights` or `idio_variances` is missing.

<a id="skfolio.prior.FactorModel.rolling_realized_attribution"></a>

#### rolling_realized_attribution(weights, portfolio_returns, annualization_factor=252.0, window_size=60, step=21, compute_asset_breakdowns=True, compute_asset_factor_contribs=False, compute_uncertainty=True)

Compute rolling realized (ex-post) factor attribution.

Runs [`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution)
over rolling windows of the factor model’s time-varying data.

See [`rolling_realized_factor_attribution`](https://skfolio.org/generated/skfolio.attribution.rolling_realized_factor_attribution.html.md#skfolio.attribution.rolling_realized_factor_attribution)
for the full mathematical description.

* **Parameters:**
  **weights** *array-like of shape (n_assets,) or (n_observations, n_assets)*
  : Portfolio weights. If 1D, the same weights are used for all
    observations. If 2D, time-varying weights are used.

  **portfolio_returns** *array-like of shape (n_observations,)*
  : Portfolio return time series.

  **annualization_factor** *float, default=252.0*
  : Annualization factor applied to variances and mean returns
    (volatilities are scaled by $\sqrt{\text{annualization\_factor}}$).
    Use 1.0 to disable annualization.

  **window_size** *int, default=60*
  : Number of effective return periods in each rolling window.

  **step** *int, default=21*
  : Number of observations to advance between consecutive windows.
    The default of 21 produces approximately monthly output for
    daily data.

  **compute_asset_breakdowns** *bool, default=True*
  : If `True`, compute per-asset attribution breakdowns for each window.

  **compute_asset_factor_contribs** *bool, default=False*
  : If `True`, compute asset-by-factor contributions for each window.

  **compute_uncertainty** *bool, default=True*
  : If `True`, compute per-window attribution uncertainty
    (standard errors on the factor/idiosyncratic PnL split).
    Requires both `regression_weights` and `idio_variances`
    to be available in this factor model; raises `ValueError`
    otherwise.
* **Returns:**
  **attribution** *Attribution*
  : Rolling attribution results with an additional leading dimension
    for the number of windows.
* **Raises:**
  ValueError
  : If `factor_returns`, `exposures`, or `idio_returns` are
    not available, or if `window_size` exceeds `n_observations`.

<a id="skfolio.prior.FactorModel.select_assets"></a>

#### select_assets(assets=None, slim=False)

Return a new `FactorModel` restricted to selected assets.

Per-asset fields (`asset_names`, `loading_matrix`, `exposures`,
`idio_covariance`, `idio_mu`, `idio_returns`, `idio_variances`,
`regression_weights`, `benchmark_weights`) are subsetted along the asset axis.
Per-factor and time-only fields (`factor_names`, `factor_families`,
`factor_covariance`, `factor_mu`, `factor_returns`, `observations`) and
`family_constraint_basis` are passed through by reference. When `assets` keeps
every asset in order and `slim` is `False`, `self` is returned directly.

* **Parameters:**
  **assets** *array-like, slice , optional*
  : Assets to keep. Boolean arrays are treated as masks, integer arrays and
    slices are positional selectors and other arrays are matched against
    `asset_names`. The selection must be duplicate-free. If `None`, keep all
    assets.

  **slim** *bool, default=False*
  : When `True`, heavy time-series fields not used by downstream portfolio
    optimization (`exposures`, `idio_returns`, `idio_variances`,
    `benchmark_weights`) are set to `None` to save memory.
* **Returns:**
  **subset** *FactorModel*

<a id="skfolio.prior.FactorModel.select_observations"></a>

#### select_observations(observations)

Return a new `FactorModel` restricted to selected observations.

Slices all time-varying fields (`factor_returns`, `exposures`, `idio_returns`,
`idio_variances`, `regression_weights`, `benchmark_weights`) to match
`observations` while passing through all static fields (`loading_matrix`,
`factor_covariance`, `idio_covariance`, `factor_mu`, `idio_mu`) unchanged.

When the target observations map to a contiguous range inside the model’s
observation axis, numpy views are used to avoid copies.

#### NOTE
Static fields are shared by reference.  In particular, `loading_matrix`
is **not** updated to `exposures[-1]` of the sliced model. It retains the
value set by the estimator that produced this `FactorModel`.

* **Parameters:**
  **observations** *array-like or slice*
  : Observations to keep. Boolean arrays are treated as masks, integer arrays
    and slices are positional selectors, and other arrays are matched against
    `self.observations`. The selection must be duplicate-free and preserve the
    original observation order.
* **Returns:**
  **subset** *FactorModel*
  : A `FactorModel` whose time-varying arrays cover only the requested
    observations. If `observations` already matches `self.observations`, `self`
    is returned directly (zero-cost no-op).
* **Raises:**
  ValueError
  : If any element of `observations` is not found in `self.observations`, or if
    the requested labels are repeated or not in increasing order relative to
    `self.observations`.

<a id="skfolio.prior.FactorModel.summary"></a>

#### summary(factors=None, families=None, annualization_factor=252.0, stability_step=21, stability_cs_weighting=BENCHMARK, t_stat_threshold=2.0)

Summary statistics for the factor model.

Combines factor-return statistics, Gram-matrix diagnostics, and exposure-quality
metrics:

> * `annualized_mean`: factor annualized mean return.
> * `annualized_vol`: factor annualized volatility.
> * `annualized_sharpe`: factor annualized Sharpe ratio.
> * `autocorrelation`: factor return lag-1 autocorrelation.
> * `mean_abs_t_stat`: factor mean absolute cross-sectional t-statistic.
> * `t_stat_exceedance_rate`: fraction of observations where $|t| > \text{threshold}$.
> * `mean_vif`: factor mean Variance Inflation Factor.
> * `stability`: factor median exposure stability coefficient over the chosen step.
> * `coverage`: average fraction of estimation-universe assets (positive
>   regression weight) with non-missing factor exposure.

For characteristics-based models, `annualized_mean` and `annualized_vol` are
computed from model-native factor returns: the cross-sectional regression
coefficients per one unit of exposure. Equivalently, each factor return is the
WLS factor-mimicking portfolio return with unit exposure to that factor and zero
exposure to the other regression factors, without additional rescaling to fixed
gross exposure or volatility. The sign follows the exposure convention; for
example, a size factor built from log market capitalization is large-minus-small,
the opposite sign of the Fama-French SMB convention.

* **Parameters:**
  **factors** *list of str, optional*
  : Explicit subset of factor names. Takes precedence over `families` when
    specified.

  **families** *str, list of str, optional*
  : Factor families to include. `None` includes all factors. Ignored when
    `factors` is given or when `factor_families` is `None`.

  **annualization_factor** *float, default=252.0*
  : Number of observations per year (e.g., 252 for daily data) to annualize
    mean, volatility and sharpe ratio.

  **stability_step** *int, default=21*
  : Number of observations between the two cross-sections used for the exposure
    stability coefficient (e.g. 21 for approximately monthly stability with
    daily data).

  **stability_cs_weighting** *CSWeighting, default=CSWeighting.BENCHMARK*
  : Cross-sectional weights for the stability computation. Falls back
    to `CSWeighting.IDENTITY` with a warning when unavailable.

  **t_stat_threshold** *float, default=2.0*
  : Absolute t-statistic threshold for the exceedance rate.

# generated/skfolio.prior.LoadingMatrixRegression.html.md

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

# skfolio.prior.LoadingMatrixRegression

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

### *class* skfolio.prior.LoadingMatrixRegression(linear_regressor=None, n_jobs=None)

Loading Matrix Regression estimator.

Estimate the loading matrix by fitting one linear regressor per asset.

* **Parameters:**
  **linear_regressor** *BaseEstimator, optional*
  : Linear regressor used to fit the factors on each asset separately.
    The default (`None`) is to use `LassoCV(fit_intercept=False)`.

  **n_jobs** *int, optional*
  : The number of jobs to run in parallel.
    <br/>
    When individual estimators are fast to train or predict,
    using `n_jobs > 1` can result in slower performance due
    to the parallelism overhead.
    <br/>
    The value `-1` means using all processors.
    The default (`None`) means 1 unless in a `joblib.parallel_backend` context.
* **Attributes:**
  **loading_matrix_** *ndarray of shape (n_assets, n_factors)*
  : The asset-by-factor loading (exposure) matrix.

  **intercepts_: ndarray of shape (n_assets,)**
  : The intercepts.

  **multi_output_regressor_: MultiOutputRegressor**
  : Fitted `sklearn.multioutput.MultiOutputRegressor`

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.prior.LoadingMatrixRegression.html.md#skfolio.prior.LoadingMatrixRegression.fit)(X, y, \*\*fit_params)   | Fit the Loading Matrix Regression Estimator.   |
|------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.prior.LoadingMatrixRegression.html.md#skfolio.prior.LoadingMatrixRegression.get_metadata_routing)()      | Get metadata routing of this object.           |
| [`get_params`](https://skfolio.org/generated/skfolio.prior.LoadingMatrixRegression.html.md#skfolio.prior.LoadingMatrixRegression.get_params)([deep])          | Get parameters for this estimator.             |
| [`set_params`](https://skfolio.org/generated/skfolio.prior.LoadingMatrixRegression.html.md#skfolio.prior.LoadingMatrixRegression.set_params)(\*\*params)      | Set the parameters of this estimator.          |

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

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

Fit the Loading Matrix Regression Estimator.

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

  **y** *array-like of shape (n_observations, n_factors)*
  : Price returns of the factors.

  **\*\*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** *LoadingMatrixRegression*
  : Fitted estimator.

<a id="skfolio.prior.LoadingMatrixRegression.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.LoadingMatrixRegression.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.LoadingMatrixRegression.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.

# generated/skfolio.prior.OpinionPooling.html.md

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

# skfolio.prior.OpinionPooling

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

### *class* skfolio.prior.OpinionPooling(estimators, opinion_probabilities=None, prior_estimator=None, is_linear_pooling=True, divergence_penalty=0.0, n_jobs=None)

Opinion Pooling estimator.

Opinion Pooling (also called Belief Aggregation or Risk Aggregation) is a process
in which different probability distributions (opinions), produced by different
experts, are combined to yield a single probability distribution (consensus).

Expert opinions (also called individual prior distributions) can be
**elicited** from domain experts or **derived** from quantitative analyses.

The `OpinionPooling` estimator takes a list of prior estimators, each of which
produces scenario probabilities (which we use as `sample_weight`), and pools them
into a single consensus probability .

You can choose between linear (arithmetic) pooling or logarithmic (geometric)
pooling, and optionally apply robust pooling using a Kullback-Leibler divergence
penalty to down-weight experts whose views deviate strongly from the group
consensus.

* **Parameters:**
  **estimators** *list of (str, BasePrior)*
  : A list of [prior estimators](https://skfolio.org/user_guide/prior.html.md#prior) representing opinions to be pooled
    into a single consensus.
    Each element of the list is defined as a tuple of string (i.e. name) and an
    estimator instance. Each must expose `sample_weight` such as in
    [`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling).

  **opinion_probabilities** *array-like of float, optional*
  : Probability mass assigned to each opinion, in [0,1] summing to ≤1.
    Any leftover mass is assigned to the uniform (uninformative) prior.
    The default (None), is to assign the same probability to each opinion.

  **prior_estimator** *BasePrior, optional*
  : Common prior for all `estimators`. If provided, each estimator from `estimators`
    will be fitted using this common prior before pooling. Setting `prior_estimator`
    inside individual `estimators` is disabled to avoid mixing different prior
    scenarios (each estimator must have the same underlying distribution).
    For example, using `prior_estimator = SyntheticData(n_samples=10_000)` will
    generate 10,000 synthetic data points from a Vine Copula before fitting the
    estimators on this common distribution.

  **is_linear_pooling** *bool, default=True*
  : If True, combine each opinion via Linear Opinion Pooling
    (arithmetic mean); if False, use Logarithmic Opinion Pooling (geometric
    mean).
    <br/>
    Linear Opinion Pooling:
    : * Retains all nonzero support (no “zero-forcing”).
      * Produces an averaging that is more evenly spread across all expert opinions.
    <br/>
    Logarithmic Opinion Pooling:
    : * Zero-Preservation. Any scenario assigned zero probability by any expert
        remains zero in the aggregate.
      * Information-Theoretic Optimality. Yields the distribution that minimizes
        the weighted sum of KL-divergences from each expert’s distribution.
      * Robust to Extremes: down-weight extreme or contrarian views more severely.

  **divergence_penalty** *float, default=0.0*
  : Non-negative factor ($\alpha$) that penalizes each opinion’s divergence
    from the group consensus, yielding more robust pooling.
    A higher value more strongly down-weights deviating opinions.
    <br/>
    The robust opinion probabilities are given by:
    $$
    \tilde{p}_i = \frac{p_i \exp\bigl(-\alpha D_i\bigr)}
    {\displaystyle \sum_{k=1}^N p_k \exp\bigl(-\alpha D_k\bigr)}
    \quad\text{for }i = 1,\dots,N
    <br/>
    $$
    <br/>
    where
    * $N$ is the number of experts `len(estimators)`
    * $M$ is the number of scenarios `len(observations)`
    * $D_i$ is the KL-divergence of expert *i*’s distribution from consensus:
      $$
      D_i = \mathrm{KL}\bigl(w_i \,\|\, c\bigr)
          = \sum_{j=1}^M w_{ij}\,\ln\!\frac{w_{ij}}{c_j}
      \quad\text{for }i = 1,\dots,N.
    <br/>
      $$
    * $w_i$ is the sample-weight vector (scenario probabilities) from expert
      *i*,  with $\sum_{j=1}^M w_{ij} = 1$.
    * $p_i$ is the initial opinion probability of expert *i*, with
      $\sum_{i=1}^N p_i \le 1$ (any leftover mass goes to a uniform prior).
    * $c_j$ is the consensus of scenario $j$:
      $$
      c_j = \sum_{i=1}^N p_i \, w_{ij} \quad\text{for }j = 1,\dots,M.
    <br/>
      $$

  **n_jobs** *int, optional*
  : The number of jobs to run in parallel for `fit` of all `estimators`.
    The value `-1` means using all processors.
    The default (`None`) means 1 unless in a `joblib.parallel_backend` context.
* **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 assets distribution, moments estimation and the
    opinion-pooling sample weights.

  **estimators_** *list[BasePrior]*
  : The elements of the `estimators` parameter, having been fitted on the
    training data.

  **named_estimators_** *dict[str, BasePrior]*
  : Attribute to access any fitted sub-estimators by name.

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

  **opinion_probabilities_** *ndarray of shape (n_opinions,)*
  : Final opinion probabilities after applying the KL-divergence penalty.
    If the initial `opinion_probabilities` doesn’t sum to one, the last element of
    `opinion_probabilities_` is the probability assigned to the uniform prior.

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

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling.fit)(X[, y])            | Fit the Opinion Pooling estimator.                    |
|-------------------------------------------------------------------------|-------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling.get_metadata_routing)() | Get metadata routing of this object.                  |
| [`get_params`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling.get_params)([deep])     | Get the parameters of an estimator from the ensemble. |
| [`set_params`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling.set_params)(\*\*params) | Set the parameters of an estimator from the ensemble. |

### References

* <a id='rf208bb6d5a69-1'>**[1]**</a> “Probabilistic opinion pooling generalized”, Social Choice and Welfare, Dietrich & List (2017)
* <a id='rf208bb6d5a69-2'>**[2]**</a> “Opinion Aggregation and Individual Expertise”, Oxford University Press, Martini & Sprenger (2017)
* <a id='rf208bb6d5a69-3'>**[3]**</a> “Rational Decisions”, Journal of the Royal Statistical Society, Good  (1952)

### Examples

For a full tutorial on entropy pooling, see [Opinion Pooling](https://skfolio.org/auto_examples/entropy_pooling/plot_2_opinion_pooling.html.md#sphx-glr-auto-examples-entropy-pooling-plot-2-opinion-pooling-py).

```pycon
>>> from skfolio import RiskMeasure
>>> from skfolio.datasets import load_sp500_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.prior import EntropyPooling, OpinionPooling
>>> from skfolio.optimization import RiskBudgeting
>>>
>>> prices = load_sp500_dataset()
>>> X = prices_to_returns(prices)
>>>
>>> # We consider two expert opinions, each generated via Entropy Pooling with
>>> # user-defined views.
>>> # We assign probabilities of 40% to Expert 1, 50% to Expert 2, and by default
>>> # the remaining 10% is allocated to the prior distribution:
>>> opinion_1 = EntropyPooling(cvar_views=["AMD == 0.10"])
>>> opinion_2 = EntropyPooling(
...     mean_views=["AMD >= BAC", "JPM <= prior(JPM) * 0.8"],
...     cvar_views=["GE == 0.12"],
... )
>>>
>>> opinion_pooling = OpinionPooling(
...     estimators=[("opinion_1", opinion_1), ("opinion_2", opinion_2)],
...     opinion_probabilities=[0.4, 0.5],
... )
>>>
>>> opinion_pooling.fit(X)
OpinionPooling(...)
>>>
>>> print(opinion_pooling.return_distribution_.sample_weight)
[0.000117... 0.000117... 0.000117... ... 0.000117... 0.000117...
 0.000117...]
>>>
>>> # CVaR Risk Parity optimization on opinion Pooling
>>> model = RiskBudgeting(
...     risk_measure=RiskMeasure.CVAR,
...     prior_estimator=opinion_pooling
... )
>>> model.fit(X)
>>> print(model.weights_)
>>>
>>> # Stress Test the Portfolio
>>> opinion_1 = EntropyPooling(cvar_views=["AMD == 0.05"])
>>> opinion_2 = EntropyPooling(cvar_views=["AMD == 0.10"])
>>> opinion_pooling = OpinionPooling(
...     estimators=[("opinion_1", opinion_1), ("opinion_2", opinion_2)],
...     opinion_probabilities=[0.6, 0.4],
... )
>>> opinion_pooling.fit(X)
OpinionPooling(...)
>>>
>>> stressed_dist = opinion_pooling.return_distribution_
>>>
>>> stressed_ptf = model.predict(stressed_dist)
```

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

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

Fit the Opinion Pooling 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** *OpinionPooling*
  : Fitted estimator.

<a id="skfolio.prior.OpinionPooling.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.OpinionPooling.get_params"></a>

#### get_params(deep=True)

Get the parameters of an estimator from the ensemble.

Returns the parameters given in the constructor as well as the
estimators contained within the `estimators` parameter.

* **Parameters:**
  **deep** *bool, default=True*
  : Setting it to True gets the various estimators and the parameters
    of the estimators as well.
* **Returns:**
  **params** *dict*
  : Parameter and estimator names mapped to their values or parameter
    names mapped to their values.

<a id="skfolio.prior.OpinionPooling.named_estimators"></a>

#### *property* named_estimators

Dictionary to access any fitted sub-estimators by name.

* **Returns:**
  `Bunch`

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

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

Set the parameters of an estimator from the ensemble.

Valid parameter keys can be listed with `get_params()`. Note that you
can directly set the parameters of the estimators contained in
`estimators`.

* **Parameters:**
  **\*\*params** *keyword arguments*
  : Specific parameters using e.g.
    `set_params(parameter_name=new_value)`. In addition, to setting the
    parameters of the estimator, the individual estimator of the
    estimators can also be set, or can be removed by setting them to
    ‘drop’.
* **Returns:**
  **self** *object*
  : Estimator instance.

# generated/skfolio.prior.ReturnDistribution.html.md

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

# skfolio.prior.ReturnDistribution

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

### *class* skfolio.prior.ReturnDistribution(mu, covariance, returns, sample_weight=None, factor_model=None)

Return distribution estimated by a prior estimator.

Prior estimators always return the **full universe** (all assets that have ever been
part of the investment universe). Assets that are not investable at the current
point in time (e.g. delisted, not yet listed, warm-up period) are represented with
`NaN` in `mu`, `covariance`, and/or `returns`.

An asset is considered investable when both `mu[i]` and `covariance[i, i]` are
finite. The `investable_mask` property infers this condition on first access
and reconciles warm-up periods across independent moment estimators.

NaN values in `returns` are restricted to the columns of non-investable assets.
Prior estimators resolve missing observations of investable assets into finite
scenario values (for example, [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior) zero-fills
them), so that `investable_subset` returns fully finite arrays.

Use `investable_subset` before passing the distribution to downstream routines that
operate only on the investable universe.

* **Attributes:**
  **mu** *ndarray of shape (n_assets,)*
  : Estimation of expected asset returns.

  **covariance** *ndarray of shape (n_assets, n_assets)*
  : Estimation of the assets covariance matrix.

  **returns** *ndarray of shape (n_observations, n_assets)*
  : Estimation of the assets returns.

  **sample_weight** *ndarray of shape (n_observations,), optional*
  : Sample weights for each observation. If `None`, equal weights are assumed.

  **factor_model** *FactorModel, optional*
  : Factor model decomposition and diagnostics. The default is `None`.

### Methods

| [`investable_subset`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution.investable_subset)([slim])   | Return a `ReturnDistribution` restricted to investable assets.   |
|------------------------------------------------------------------------------|------------------------------------------------------------------|

<a id="skfolio.prior.ReturnDistribution.covariance_sqrt"></a>

#### *property* covariance_sqrt

Covariance square root for SOC-based optimization.

When a [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel) is available, delegates to
[`FactorModel.covariance_sqrt`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.covariance_sqrt) to exploit the low-rank factor structure.
Otherwise, falls back to the Cholesky decomposition of `covariance`.

When non-investable assets are represented with `NaN` entries and no factor
model is available, callers should apply `investable_subset` first.

* **Returns:**
  CovarianceSqrt

<a id="skfolio.prior.ReturnDistribution.investable_mask"></a>

#### *property* investable_mask

Boolean mask where `True` marks investable assets.

The mask is inferred as the intersection of finite `mu` values and a finite
diagonal in `covariance`. Returns `None` when all assets are investable.

* **Raises:**
  ValueError
  : If no asset is investable (all `NaN` in `mu` and/or `covariance`).

<a id="skfolio.prior.ReturnDistribution.investable_subset"></a>

#### investable_subset(slim=False)

Return a `ReturnDistribution` restricted to investable assets.

* **Parameters:**
  **slim** *bool, default=False*
  : When `True`, heavy diagnostic fields on the nested `FactorModel` (e.g.
    `exposures`, `idio_returns`, `idio_variances`, `benchmark_weights`) are set
    to `None` to reduce memory usage. This is typically used by optimization
    estimators that only need `loading_matrix`, covariance, and return series.
* **Returns:**
  **subset** *ReturnDistribution*
  : Distribution over the investable assets only. If all assets are already
    investable and `slim=False`, `self` is returned.

<a id="skfolio.prior.ReturnDistribution.n_assets"></a>

#### *property* n_assets

Total number of assets in the full universe.

<a id="skfolio.prior.ReturnDistribution.n_investable_assets"></a>

#### *property* n_investable_assets

Number of investable assets.

# generated/skfolio.prior.SyntheticData.html.md

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

# skfolio.prior.SyntheticData

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

### *class* skfolio.prior.SyntheticData(distribution_estimator=None, n_samples=1000, sample_args=None)

Synthetic Data Estimator.

The Synthetic Data model estimates a [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) by
fitting a `distribution_estimator` and sampling new returns data from it.

The default `distribution_estimator` is a Regular Vine Copula model. Other common
choices are Generative Adversarial Networks (GANs) or Variational Autoencoders
(VAEs).

This class is particularly useful when the historical distribution tail dependencies
are sparse and need extrapolation for tail optimizations or when optimizing under
conditional or stressed scenarios.

* **Parameters:**
  **distribution_estimator** *BaseEstimator, optional*
  : Estimator to model the distribution of asset returns. It must inherit from
    `BaseEstimator` and implements a `sample` method. If None, the default
    `VineCopula()` model is used.

  **n_samples** *int, default=1000*
  : Number of samples to generate from the `distribution_estimator`, default is
    1000.

  **sample_args** *dict, optional*
  : Additional keyword arguments to pass to the `sample` method of the
    `distribution_estimator`.
* **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 assets syntehtic data distribution and moments
    estimation.

  **distribution_estimator_** *BaseEstimator*
  : The fitted distribution 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`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData.fit)(X[, y])            | Fit the Synthetic Data estimator.     |
|-------------------------------------------------------------------------|---------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData.get_metadata_routing)() | Get metadata routing of this object.  |
| [`get_params`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData.get_params)([deep])     | Get parameters for this estimator.    |
| [`set_params`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData.set_params)(\*\*params) | Set the parameters of this estimator. |

### Examples

```pycon
>>> import numpy as np
>>> from skfolio.datasets import load_sp500_dataset, load_factors_dataset
>>> from skfolio.preprocessing import prices_to_returns
>>> from skfolio.distribution import VineCopula
>>> from skfolio.optimization import MeanRisk
>>> from skfolio.prior import TimeSeriesFactorModel, SyntheticData
>>> from skfolio import RiskMeasure
>>>
>>> # Load historical prices and convert them to returns
>>> prices = load_sp500_dataset()
>>> factor_prices = load_factors_dataset()
>>> X, factors = prices_to_returns(prices, factor_prices)
>>>
>>> # Instantiate the SyntheticData model and fit it
>>> model = SyntheticData()
>>> model.fit(X)
SyntheticData()
>>> print(model.return_distribution_)
ReturnDistribution(...)
>>>
>>> # Minimum CVaR optimization on synthetic returns
>>> model = MeanRisk(
...    risk_measure=RiskMeasure.CVAR,
...    prior_estimator=SyntheticData(
...        distribution_estimator=VineCopula(
...            log_transform=True, n_jobs=-1, random_state=0
...        ),
...        n_samples=2000,
...    )
... )
>>> model.fit(X)
MeanRisk(...)
>>> print(model.weights_)
[0.0021 0.     0.     ... 0.     0.1559 0.0641]
>>>
>>> # Minimum CVaR optimization on Stressed Factors
>>> factor_model = TimeSeriesFactorModel(
...    factor_prior_estimator=SyntheticData(
...        distribution_estimator=VineCopula(
...            central_assets=["QUAL"],
...            log_transform=True,
...            n_jobs=-1,
...            random_state=0,
...        ),
...        n_samples=5000,
...        sample_args=dict(conditioning={"QUAL": -0.2}),
...    )
... )
>>> model = MeanRisk(risk_measure=RiskMeasure.CVAR, prior_estimator=factor_model)
>>> model.fit(X, factors=factors)
MeanRisk(...)
>>> print(model.weights_)
[0.     0.     0.     ... 0.0616 0.     0.9384 0.    ]
>>>
>>> # Stress Test the Portfolio
>>> factor_model.set_params(factor_prior_estimator__sample_args=dict(
...     conditioning={"QUAL": -0.5}
... ))
TimeSeriesFactorModel(...)
>>> factor_model.fit(X, factors=factors)
TimeSeriesFactorModel(...)
>>> stressed_dist = factor_model.return_distribution_
>>> stressed_ptf = model.predict(stressed_dist)
```

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

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

Fit the Synthetic Data 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** *SyntheticData*
  : Fitted estimator.

<a id="skfolio.prior.SyntheticData.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.SyntheticData.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.SyntheticData.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.

# generated/skfolio.prior.TimeSeriesFactorModel.html.md

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

# skfolio.prior.TimeSeriesFactorModel

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

### *class* skfolio.prior.TimeSeriesFactorModel(loading_matrix_estimator=None, factor_prior_estimator=None, factor_families=None, higham=False, max_iteration=100)

Time-series factor model estimator.

The purpose of factor models is to impose a structure on financial
variables and their covariance matrix by explaining them through a small
number of common factors. This reduces the number of free parameters in
the estimation problem, making portfolio optimization more robust against
noise. Factor models also provide a decomposition of risk into systematic
and idiosyncratic components.

This estimator implements a time-series regression approach: for each
asset $i$, the return is regressed on a common set of factor return
series:

$$
r_i(t) = a_i + B_i \, f(t) + \epsilon_i(t)
$$

where $B_i$ is the factor loadings (exposures), $f(t)$ is the
vector of factor returns, $a_i$ is the intercept of asset $i$’s
time-series regression, and $\epsilon_i(t)$ is the idiosyncratic return,
obtained as the regression residual.

The expected return vector is:

$$
\mu = B \, \mathbb{E}[f] + a
$$

and the covariance matrix is:

$$
\Sigma = B \, F \, B^\top + D
$$

where $F$ is the factor covariance matrix and $D$ is the
diagonal matrix of idiosyncratic variances.

#### NOTE
This formulation assumes that the factors are tradable assets or portfolios
(e.g. long-short equity factors or ETF returns), so that the
factor sample mean is a valid estimate of the factor risk premium.
When factors are non-tradable variables (e.g. macroeconomic series),
sometimes called a *macroeconomic factor model* in the literature,
the sample mean no longer equals the risk premium and a two-pass
procedure such as Fama-MacBeth (1973) is required to estimate the
cross-sectional price of risk $\lambda$. That procedure also
requires a large estimation universe in order to reliably identify the
factor risk premia.

* **Parameters:**
  **loading_matrix_estimator** *LoadingMatrixEstimator, optional*
  : Estimator of the loading matrix (betas) of the factors.
    The default (`None`) is to use [`LoadingMatrixRegression`](https://skfolio.org/generated/skfolio.prior.LoadingMatrixRegression.html.md#skfolio.prior.LoadingMatrixRegression)
    which fits the factors using `LassoCV` on each asset separately.

  **factor_prior_estimator** *BasePrior, optional*
  : Estimator of the factor return distribution. It is used to estimate
    the [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) containing expected factor
    returns and the factor covariance matrix.
    The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **factor_families** *array-like of shape (n_factors,), optional*
  : Family label for each factor. When provided, the labels are stored in the
    [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel) and can be used by downstream diagnostics,
    plots and optimization constraints referencing factor families. The default
    (`None`) means that no family labels are attached to the factors.

  **higham** *bool, default=False*
  : If this is set to True, the Higham (2002) algorithm is used to find
    the nearest positive semi-definite covariance matrix. It is more
    accurate but slower than the default clipping method. For more
    information see [`cov_nearest`](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#skfolio.utils.stats.cov_nearest).

  **max_iteration** *int, default=100*
  : Only used when `higham` is set to True. Maximum number of iterations
    of the Higham (2002) algorithm.
* **Attributes:**
  **return_distribution_** *ReturnDistribution*
  : Fitted [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) containing the
    asset distribution and moments estimation based on the factor model.

  **factor_prior_estimator_** *BasePrior*
  : Fitted `factor_prior_estimator`.

  **loading_matrix_estimator_** *BaseLoadingMatrix*
  : Fitted `loading_matrix_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`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel.fit)(X[, y])                    | Fit the Time-series factor model estimator.                                      |
|---------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel.get_metadata_routing)()         | Get metadata routing of this object.                                             |
| [`get_params`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel.get_params)([deep])             | Get parameters for this estimator.                                               |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel.set_fit_request)(\*[, factors]) | Configure whether metadata should be requested to be passed to the `fit` method. |
| [`set_params`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel.set_params)(\*\*params)         | Set the parameters of this estimator.                                            |

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

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

Fit the Time-series factor model estimator.

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

  **y** *None*
  : Not used, present for scikit-learn compatibility.

  **factors** *array-like of shape (n_observations, n_factors)*
  : Factors’ returns.

  **\*\*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** *TimeSeriesFactorModel*
  : Fitted estimator.

<a id="skfolio.prior.TimeSeriesFactorModel.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.TimeSeriesFactorModel.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.TimeSeriesFactorModel.set_fit_request"></a>

#### set_fit_request(\*, factors='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **factors** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `factors` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.prior.TimeSeriesFactorModel.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.

# generated/skfolio.uncertainty_set.BaseCovarianceUncertaintySet.html.md

<a id="skfolio-uncertainty-set-basecovarianceuncertaintyset"></a>

# skfolio.uncertainty_set.BaseCovarianceUncertaintySet

<a id="skfolio.uncertainty_set.BaseCovarianceUncertaintySet"></a>

### *class* skfolio.uncertainty_set.BaseCovarianceUncertaintySet(prior_estimator=None)

Base class for all Covariance Uncertainty Set estimators in `skfolio`.

### Methods

| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.uncertainty_set.BaseCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.BaseCovarianceUncertaintySet.get_metadata_routing)()   | Get metadata routing of this object.   |
|---------------------------------------------------------------------------|----------------------------------------|
| [`get_params`](https://skfolio.org/generated/skfolio.uncertainty_set.BaseCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.BaseCovarianceUncertaintySet.get_params)([deep])       | Get parameters for this estimator.     |
| [`set_params`](https://skfolio.org/generated/skfolio.uncertainty_set.BaseCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.BaseCovarianceUncertaintySet.set_params)(\*\*params)   | Set the parameters of this estimator.  |

| **fit**   |    |
|-----------|----|

### Notes

All estimators should specify all the parameters that can be set
at the class level in their `__init__` as explicit keyword
arguments (no `*args` or `**kwargs`).

<a id="skfolio.uncertainty_set.BaseCovarianceUncertaintySet.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.uncertainty_set.BaseCovarianceUncertaintySet.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.uncertainty_set.BaseCovarianceUncertaintySet.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.

# generated/skfolio.uncertainty_set.BaseMuUncertaintySet.html.md

<a id="skfolio-uncertainty-set-basemuuncertaintyset"></a>

# skfolio.uncertainty_set.BaseMuUncertaintySet

<a id="skfolio.uncertainty_set.BaseMuUncertaintySet"></a>

### *class* skfolio.uncertainty_set.BaseMuUncertaintySet(prior_estimator=None)

Base class for all Mu Uncertainty Set estimators in `skfolio`.

### Methods

| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.uncertainty_set.BaseMuUncertaintySet.html.md#skfolio.uncertainty_set.BaseMuUncertaintySet.get_metadata_routing)()   | Get metadata routing of this object.   |
|---------------------------------------------------------------------------|----------------------------------------|
| [`get_params`](https://skfolio.org/generated/skfolio.uncertainty_set.BaseMuUncertaintySet.html.md#skfolio.uncertainty_set.BaseMuUncertaintySet.get_params)([deep])       | Get parameters for this estimator.     |
| [`set_params`](https://skfolio.org/generated/skfolio.uncertainty_set.BaseMuUncertaintySet.html.md#skfolio.uncertainty_set.BaseMuUncertaintySet.set_params)(\*\*params)   | Set the parameters of this estimator.  |

| **fit**   |    |
|-----------|----|

### Notes

All estimators should specify all the parameters that can be set
at the class level in their `__init__` as explicit keyword
arguments (no `*args` or `**kwargs`).

<a id="skfolio.uncertainty_set.BaseMuUncertaintySet.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.uncertainty_set.BaseMuUncertaintySet.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.uncertainty_set.BaseMuUncertaintySet.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.

# generated/skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.html.md

<a id="skfolio-uncertainty-set-bootstrapcovarianceuncertaintyset"></a>

# skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet

<a id="skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet"></a>

### *class* skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet(prior_estimator=None, confidence_level=0.95, diagonal=True, n_bootstrap_samples=1000, block_size=None, seed=None)

Bootstrap Covariance Uncertainty set.

Compute the covariance ellipsoidal uncertainty set using stationary bootstrap:

$$
U_{\Sigma}
=
\left\{
    \Sigma :
    d^\top S^{-1} d \le \kappa^2,
    \Sigma \succeq 0
\right\},
\quad
d =
\operatorname{vec}(\Sigma) - \operatorname{vec}(\hat{\Sigma}).
$$

The radius of the ellipsoid $\kappa$ (confidence region) is computed using:

$$
\kappa^2 = \chi^2_{n_{\text{assets}}^2}(\beta)

$$

with $\chi^2_{n_{\text{assets}}^2}(\beta)$ the inverse cumulative
distribution function of the chi-squared distribution with $n_{\text{assets}}^2$
degrees of freedom at the $\beta$ confidence level.

The shape matrix $S$ of the ellipsoid is the covariance matrix of the
bootstrapped vectorized covariance estimator. If `diagonal` is `True`, only the
diagonal of $S$ is retained and the linear geometry map $L$ is built
directly from it. Otherwise, the estimator stores a full square-root factor
$L = S^{1/2}$.

* **Parameters:**
  **prior_estimator** *BasePrior, optional*
  : The [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior) used to estimate the assets return
    distribution. The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **confidence_level** *float , default=0.95*
  : Confidence level $\beta$ of the inverse cumulative distribution function
    of the chi-squared distribution. The default value is `0.95`.

  **diagonal** *bool, default=True*
  : If `True`, only the diagonal of the ellipsoid shape matrix in vectorized
    covariance space is retained.

  **n_bootstrap_samples** *int, default=1000*
  : Number of bootstrap samples to generate. The default value is `1000`.

  **block_size** *float, optional*
  : Bootstrap block size. The default (`None`) is to estimate the optimal block size
    using Politis & White algorithm for all individual assets.

  **seed** *int, optional*
  : Random seed used to initialize the pseudo-random number generator.
* **Attributes:**
  **uncertainty_set_** *UncertaintySet*
  : Covariance Uncertainty set [`UncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.UncertaintySet.html.md#skfolio.uncertainty_set.UncertaintySet).

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.fit)(X[, y])            | Fit the Bootstrap Covariance Uncertainty set estimator.   |
|-------------------------------------------------------------------------|-----------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.get_metadata_routing)() | Get metadata routing of this object.                      |
| [`get_params`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.get_params)([deep])     | Get parameters for this estimator.                        |
| [`set_params`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.set_params)(\*\*params) | Set the parameters of this estimator.                     |

### References

* <a id='r53ffc7e1ab60-1'>**[1]**</a> “Portfolio Optimization: Theory and Application”, Chapter 14, Daniel P. Palomar (2025)
* <a id='r53ffc7e1ab60-2'>**[2]**</a> “Robustness properties of mean-variance portfolios”, Optimization: A Journal of Mathematical Programming and Operations Research, Schöttle & Werner (2009).
* <a id='r53ffc7e1ab60-3'>**[3]**</a> “Automatic Block-Length Selection for the Dependent Bootstrap”, Politis & White (2004).
* <a id='r53ffc7e1ab60-4'>**[4]**</a> “Correction to Automatic Block-Length Selection for the Dependent Bootstrap”, Patton, Politis & White (2009).

<a id="skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.fit"></a>

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

Fit the Bootstrap Covariance Uncertainty set estimator.

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

  **y** *array-like of shape (n_observations, n_factors), optional*
  : Price returns of factors.
    The default is `None`.

  **\*\*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** *BootstrapCovarianceUncertaintySet*
  : Fitted estimator.

<a id="skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.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.uncertainty_set.BootstrapCovarianceUncertaintySet.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.uncertainty_set.BootstrapCovarianceUncertaintySet.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.

# generated/skfolio.uncertainty_set.BootstrapMuUncertaintySet.html.md

<a id="skfolio-uncertainty-set-bootstrapmuuncertaintyset"></a>

# skfolio.uncertainty_set.BootstrapMuUncertaintySet

<a id="skfolio.uncertainty_set.BootstrapMuUncertaintySet"></a>

### *class* skfolio.uncertainty_set.BootstrapMuUncertaintySet(prior_estimator=None, confidence_level=0.95, diagonal=True, n_bootstrap_samples=1000, block_size=None, seed=None)

Bootstrap Mu Uncertainty set.

Compute the expected returns ellipsoidal uncertainty set using stationary bootstrap:

$$
U_{\mu}
=
\left\{
    \mu :
    (\mu - \hat{\mu})^\top S^{-1}(\mu - \hat{\mu})
    \le \kappa^2
\right\}.
$$

The radius of the ellipsoid $\kappa$ (confidence region) is computed using:

$$
\kappa^2 = \chi^2_{n_{\text{assets}}}(\beta)

$$

with $\chi^2_{n_{\text{assets}}}(\beta)$ the inverse cumulative distribution
function of the chi-squared distribution with $n_{\text{assets}}$ degrees of
freedom at the $\beta$ confidence level.

The shape matrix $S$ of the ellipsoid is computed using stationary bootstrap,
with the option to retain only its diagonal. The estimator stores the square-root
factor as the linear geometry map:math:`L = S^{1/2}`.

* **Parameters:**
  **prior_estimator** *BasePrior, optional*
  : The [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior) used to estimate the assets return
    distribution. The default (`None`) is to use
    [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **confidence_level** *float , default=0.95*
  : Confidence level $\beta$ of the inverse cumulative distribution function
    of the chi-squared distribution. The default value is `0.95`.

  **diagonal** *bool, default=True*
  : If `True`, only the diagonal of the ellipsoid shape matrix is retained.

  **n_bootstrap_samples** *int, default=1000*
  : Number of bootstrap samples to generate. The default value is `1000`.

  **block_size** *float, optional*
  : Bootstrap block size. The default (`None`) is to estimate the optimal block size
    using Politis & White algorithm for all individual assets.

  **seed** *int, optional*
  : Random seed used to initialize the pseudo-random number generator.
* **Attributes:**
  **uncertainty_set_** *UncertaintySet*
  : Mu Uncertainty set [`UncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.UncertaintySet.html.md#skfolio.uncertainty_set.UncertaintySet).

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

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapMuUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapMuUncertaintySet.fit)(X[, y])            | Fit the Bootstrap Mu Uncertainty set estimator.   |
|-------------------------------------------------------------------------|---------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapMuUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapMuUncertaintySet.get_metadata_routing)() | Get metadata routing of this object.              |
| [`get_params`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapMuUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapMuUncertaintySet.get_params)([deep])     | Get parameters for this estimator.                |
| [`set_params`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapMuUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapMuUncertaintySet.set_params)(\*\*params) | Set the parameters of this estimator.             |

### References

* <a id='ra14fcabb7c03-1'>**[1]**</a> “Portfolio Optimization: Theory and Application”, Chapter 14, Daniel P. Palomar (2025)
* <a id='ra14fcabb7c03-2'>**[2]**</a> “Robustness properties of mean-variance portfolios”, Optimization: A Journal of Mathematical Programming and Operations Research, Schöttle & Werner (2009).
* <a id='ra14fcabb7c03-3'>**[3]**</a> “Automatic Block-Length Selection for the Dependent Bootstrap”, Politis & White (2004).
* <a id='ra14fcabb7c03-4'>**[4]**</a> “Correction to Automatic Block-Length Selection for the Dependent Bootstrap”, Patton, Politis & White (2009).

<a id="skfolio.uncertainty_set.BootstrapMuUncertaintySet.fit"></a>

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

Fit the Bootstrap Mu Uncertainty set estimator.

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

  **y** *array-like of shape (n_observations, n_factors), optional*
  : Price returns of factors.
    The default is `None`.

  **\*\*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** *BootstrapMuUncertaintySet*
  : Fitted estimator.

<a id="skfolio.uncertainty_set.BootstrapMuUncertaintySet.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.uncertainty_set.BootstrapMuUncertaintySet.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.uncertainty_set.BootstrapMuUncertaintySet.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.

# generated/skfolio.uncertainty_set.CompactCovarianceUncertaintySet.html.md

<a id="skfolio-uncertainty-set-compactcovarianceuncertaintyset"></a>

# skfolio.uncertainty_set.CompactCovarianceUncertaintySet

<a id="skfolio.uncertainty_set.CompactCovarianceUncertaintySet"></a>

### *class* skfolio.uncertainty_set.CompactCovarianceUncertaintySet(radius, metric_sqrt, basis)

Compact representation of a quadratic covariance uncertainty penalty.

This object stores the data needed to evaluate a worst-case variance penalty in
reduced projection form, without materializing the equivalent dense positive
semidefinite matrix.

Let $C$ be a diagonal metric square root and let $Q$ be an orthonormal
basis. For portfolio weights $w$, the optimizer evaluates

$$
\kappa \min_z \lVert C w - Q z \rVert_2^2.
$$

This is equivalent to adding the following positive semidefinite matrix to the
quadratic variance term:

$$
\kappa C^\top (I - Q Q^\top) C.
$$

The compact representation avoids building this dense matrix. The optimizer only
needs the diagonal entries of $C$ and the basis $Q$.

* **Parameters:**
  **radius** *float*
  : Non-negative multiplier $\kappa$ applied to the quadratic covariance
    penalty.

  **metric_sqrt** *ndarray of shape (n_assets,)*
  : Diagonal of the metric square root $C$.

  **basis** *ndarray of shape (n_assets, rank)*
  : Orthonormal basis $Q$ of the subspace projected out by the quadratic
    penalty.
* **Attributes:**
  **radius** *float*
  : Non-negative multiplier $\kappa$.

  **metric_sqrt** *ndarray of shape (n_assets,)*
  : Diagonal of the metric square root $C$.

  **basis** *ndarray of shape (n_assets, rank)*
  : Orthonormal basis $Q$.

# generated/skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.html.md

<a id="skfolio-uncertainty-set-empiricalcovarianceuncertaintyset"></a>

# skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet

<a id="skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet"></a>

### *class* skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet(prior_estimator=None, confidence_level=0.95, diagonal=True, n_eff=None)

Empirical Covariance Uncertainty set.

Compute the covariance ellipsoidal uncertainty set [[1]](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.html.md#r6b35a4f504b5-1):

$$
U_{\Sigma}
=
\left\{
    \Sigma :
    d^\top S^{-1} d \le \kappa^2,
    \Sigma \succeq 0
\right\},
\quad
d =
\operatorname{vec}(\Sigma) - \operatorname{vec}(\hat{\Sigma}).
$$

We consider the Wishart distribution for the covariance matrix:

$$
\hat{\Sigma}\sim W(\frac{1}{T-1}\Sigma, T-1)

$$

The radius of the ellipsoid $\kappa$ (confidence region) is computed using:

$$
\kappa^2 = \chi^2_{n_{\text{assets}}^2}(\beta)

$$

with $\chi^2_{n_{\text{assets}}^2}(\beta)$ the inverse cumulative distribution
function of the chi-squared distribution with $n_{\text{assets}}^2$ degrees of
freedom at the $\beta$ confidence level.

The shape matrix $S$ of the ellipsoid is based on the covariance matrix of the
Wishart distributed random variable using the vector notation
$\operatorname{vec}(x)$:

$$
\operatorname{Cov}[\operatorname{vec}(\hat{\Sigma})]
=
\frac{1}{n_{\text{eff}}}
(I_{n^2} + K_{nn})(\Sigma \otimes \Sigma).
$$

where $K_{nn}$ denotes a commutation matrix and $\otimes$ represents
the Kronecker product. If `diagonal` is `True`, the asset covariance estimate is
diagonalized and the linear geometry map $L$ is built directly from the
diagonal of $S$. Otherwise, the estimator stores a full square-root factor
$L = S^{1/2}$.

* **Parameters:**
  **prior_estimator** *BasePrior, optional*
  : The [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior) used to estimate the assets covariance
    matrix. The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **confidence_level** *float , default=0.95*
  : Confidence level $\beta$ of the inverse cumulative distribution function
    of the chi-squared distribution. The default value is `0.95`.

  **diagonal** *bool, default=True*
  : If `True`, the non-diagonal elements of the asset covariance matrix are set to
    zero before building the ellipsoid shape matrix.

  **n_eff** *float, optional*
  : Effective number of observations used for the covariance estimator. If `None`,
    the number of observations in `X` is used. This is useful when the covariance
    matrix is estimated using a different window length or a weighted estimator
    (e.g. EWMA), in which case `n_eff` should be set to the corresponding effective
    sample size.
* **Attributes:**
  **uncertainty_set_** *UncertaintySet*
  : Covariance Uncertainty set [`UncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.UncertaintySet.html.md#skfolio.uncertainty_set.UncertaintySet).

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

  **n_eff_** *float*
  : Effective number of observations actually used to build the uncertainty set.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.fit)(X[, y])            | Fit the Empirical Covariance Uncertainty set estimator.   |
|-------------------------------------------------------------------------|-----------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.get_metadata_routing)() | Get metadata routing of this object.                      |
| [`get_params`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.get_params)([deep])     | Get parameters for this estimator.                        |
| [`set_params`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.set_params)(\*\*params) | Set the parameters of this estimator.                     |

### References

* <a id='r6b35a4f504b5-1'>**[1]**</a> “Robustness properties of mean-variance portfolios”, Optimization: A Journal of Mathematical Programming and Operations Research, Schöttle & Werner (2009).
* <a id='r6b35a4f504b5-2'>**[2]**</a> “Portfolio Optimization: Theory and Application”, Chapter 14, Daniel P. Palomar (2025)

<a id="skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.fit"></a>

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

Fit the Empirical Covariance Uncertainty set estimator.

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

  **y** *array-like of shape (n_observations, n_factors), optional*
  : Price returns of factors.
    The default is `None`.

  **\*\*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** *EmpiricalCovarianceUncertaintySet*
  : Fitted estimator.

<a id="skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.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.uncertainty_set.EmpiricalCovarianceUncertaintySet.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.uncertainty_set.EmpiricalCovarianceUncertaintySet.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.

# generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md

<a id="skfolio-uncertainty-set-empiricalmuuncertaintyset"></a>

# skfolio.uncertainty_set.EmpiricalMuUncertaintySet

<a id="skfolio.uncertainty_set.EmpiricalMuUncertaintySet"></a>

### *class* skfolio.uncertainty_set.EmpiricalMuUncertaintySet(prior_estimator=None, confidence_level=0.95, diagonal=True, n_eff=None)

Empirical Mu Uncertainty Set.

Compute the expected returns ellipsoidal uncertainty set [[1]](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md#r9d3b3fa25b42-1):

$$
U_{\mu}
=
\left\{
    \mu :
    (\mu - \hat{\mu})^\top S^{-1}(\mu - \hat{\mu})
    \le \kappa^2
\right\}.
$$

Under the assumption that $\Sigma$ is given, the distribution of the sample
estimator $\hat{\mu}$ based on an i.i.d. sample
$R_{t}\sim N(\mu, \Sigma), t=1,...,T$ is given by
$\hat{\mu}\sim N(\mu, \frac{1}{T}\Sigma)$.

The radius of the ellipsoid $\kappa$ (confidence region) is computed using:

$$
\kappa^2 = \chi^2_{n_{\text{assets}}}(\beta)

$$

with $\chi^2_{n_{\text{assets}}}(\beta)$ the inverse cumulative distribution
function of the chi-squared distribution with $n_{\text{assets}}$ degrees of
freedom at the $\beta$ confidence level.

The shape matrix $S$ of the ellipsoid is computed using:

$$
S = \frac{1}{T}\Sigma

$$

with the option to force the non-diagonal elements of the covariance matrix to zero.
The estimator stores the square-root factor as the linear geometry map
$L = S^{1/2}$.

* **Parameters:**
  **prior_estimator** *BasePrior, optional*
  : The [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior) used to estimate the assets covariance
    matrix. The default (`None`) is to use [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior).

  **confidence_level** *float, default=0.95*
  : Confidence level $\beta$ of the inverse cumulative distribution function
    of the chi-squared distribution. The default value is `0.95`.

  **diagonal** *bool, default=True*
  : If `True`, the non-diagonal elements of the covariance matrix are set to zero.

  **n_eff** *float, optional*
  : Effective number of observations used for the mean estimator. If `None`,
    the number of observations in `X` is used. This is useful when the expected
    returns are estimated using a different window length or a weighted estimator
    (e.g. EWMA), in which case `n_eff` should be set to the corresponding effective
    sample size.
* **Attributes:**
  **uncertainty_set_** *UncertaintySet*
  : Mu Uncertainty set [`UncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.UncertaintySet.html.md#skfolio.uncertainty_set.UncertaintySet).

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

  **n_eff_** *float*
  : Effective number of observations actually used to build the uncertainty set.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalMuUncertaintySet.fit)(X[, y])            | Fit the Empirical Mu Uncertainty set estimator.   |
|-------------------------------------------------------------------------|---------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalMuUncertaintySet.get_metadata_routing)() | Get metadata routing of this object.              |
| [`get_params`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalMuUncertaintySet.get_params)([deep])     | Get parameters for this estimator.                |
| [`set_params`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalMuUncertaintySet.set_params)(\*\*params) | Set the parameters of this estimator.             |

### References

* <a id='r9d3b3fa25b42-1'>**[1]**</a> “Robustness properties of mean-variance portfolios”, Optimization: A Journal of Mathematical Programming and Operations Research, Schöttle & Werner (2009).
* <a id='r9d3b3fa25b42-2'>**[2]**</a> “Portfolio Optimization: Theory and Application”, Chapter 14, Daniel P. Palomar (2025)

<a id="skfolio.uncertainty_set.EmpiricalMuUncertaintySet.fit"></a>

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

Fit the Empirical Mu Uncertainty set estimator.

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

  **y** *array-like of shape (n_observations, n_factors), optional*
  : Price returns of factors.
    The default is `None`.

  **\*\*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** *EmpiricalMuUncertaintySet*
  : Fitted estimator.

<a id="skfolio.uncertainty_set.EmpiricalMuUncertaintySet.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.uncertainty_set.EmpiricalMuUncertaintySet.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.uncertainty_set.EmpiricalMuUncertaintySet.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.

# generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md

<a id="skfolio-uncertainty-set-orthogonalcovarianceuncertaintyset"></a>

# skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet

<a id="skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet"></a>

### *class* skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet(radius=1.0, cs_weighting=INVERSE_IDIO_VARIANCE)

Covariance uncertainty set estimator for directions outside the factor span.

This estimator builds a compact covariance uncertainty set for robust portfolio
optimization [[1]](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#read94a27047e-1) [[2]](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#read94a27047e-2) [[3]](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#read94a27047e-3). The robust penalty assigns additional covariance uncertainty to
portfolio directions that are in the subspace orthogonal to the factor-model
loading matrix, under the selected cross-sectional weighting metric.

The base covariance is assumed to have the factor structure

$$
\Sigma = B F B^\top + D
$$

where $B$ is the loading matrix, $F$ is the factor covariance matrix
and $D$ is the idiosyncratic covariance matrix.

Under this uncertainty set, the worst-case variance for a portfolio with weights
$w$ is

$$
\sup_{\Sigma \in U} w^\top \Sigma\, w
=
w^\top \hat{\Sigma} w
+
\kappa
\min_z
\lVert C w - Q z \rVert_2^2.
$$

Here, $Q$ is an orthonormal basis of the weighted factor span
$\operatorname{col}(W^{1/2} B)$ and $C = W^{-1/2}$.

The expression is the compact form of the quadratic penalty

$$
\kappa C^\top (I - Q Q^\top) C.
$$

This structured form avoids the lifted SDP formulation used for fully generic
covariance uncertainty sets and avoids materializing the dense matrix [[4]](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#read94a27047e-4)
$C^\top (I - Q Q^\top) C$.

If the factor model uses basket-neutral constraints, the loading matrix is first
reduced to its effective full-rank basis before the orthogonal subspace is computed.

* **Parameters:**
  **radius** *float, default=1.0*
  : Penalty radius $\kappa$. Controls the magnitude of the orthogonal
    covariance penalty. Must be non-negative.

  **cs_weighting** *CSWeighting, default=CSWeighting.INVERSE_IDIO_VARIANCE*
  : Cross-sectional weighting used to define the orthogonality metric.
* **Attributes:**
  **uncertainty_set_** *CompactCovarianceUncertaintySet*
  : Fitted solver-ready uncertainty set containing the radius, diagonal metric
    square root and basis.

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.fit)(X[, y, return_distribution])                   | Fit the orthogonal covariance uncertainty set.                                           |
|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.get_metadata_routing)()                             | Get metadata routing of this object.                                                     |
| [`get_params`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.get_params)([deep])                                 | Get parameters for this estimator.                                                       |
| [`partial_fit`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.partial_fit)(X[, y, return_distribution])           | Update the orthogonal covariance uncertainty set.                                        |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.set_fit_request)(\*[, return_distribution])         | Configure whether metadata should be requested to be passed to the `fit` method.         |
| [`set_params`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.set_params)(\*\*params)                             | Set the parameters of this estimator.                                                    |
| [`set_partial_fit_request`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.set_partial_fit_request)(\*[, return_distribution]) | Configure whether metadata should be requested to be passed to the `partial_fit` method. |

### Notes

This estimator requires a factor model in the return distribution. When used inside
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk), the `return_distribution` metadata is
passed automatically by `fit` and `partial_fit`. Covariance uncertainty is applied
when `risk_measure=RiskMeasure.VARIANCE` or when `max_variance` is set.

### References

* <a id='read94a27047e-1'>**[1]**</a> “Robustness properties of mean-variance portfolios”, Optimization: A Journal of Mathematical Programming and Operations Research, Schöttle & Werner (2009).
* <a id='read94a27047e-2'>**[2]**</a> “Portfolio Optimization: Theory and Application”, Chapter 14, Daniel P. Palomar (2025)
* <a id='read94a27047e-3'>**[3]**</a> “Robust Portfolio Selection Problems”, Mathematics of Operations Research, Goldfarb and Iyengar (2003).
* <a id='read94a27047e-4'>**[4]**</a> “Robust Convex Optimization”, Mathematics of Operations Research, Ben-Tal and Nemirovski (1998).

<a id="skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.fit"></a>

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

Fit the orthogonal covariance uncertainty set.

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

  **y** *array-like of shape (n_observations, n_factors), optional*
  : Price returns of factors. The default is `None`.

  **return_distribution** *ReturnDistribution, optional*
  : The fitted return distribution from the prior estimator.
    Passed internally by [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk). Must contain a
    `factor_model` with `loading_matrix` and `idio_covariance`.

  **\*\*fit_params** *dict*
  : Additional parameters (unused).
* **Returns:**
  **self** *OrthogonalCovarianceUncertaintySet*
  : Fitted estimator.

<a id="skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.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.uncertainty_set.OrthogonalCovarianceUncertaintySet.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.uncertainty_set.OrthogonalCovarianceUncertaintySet.partial_fit"></a>

#### partial_fit(X, y=None, \*, return_distribution=None, \*\*fit_params)

Update the orthogonal covariance uncertainty set.

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

  **y** *array-like of shape (n_observations, n_factors), optional*
  : Price returns of factors. The default is `None`.

  **return_distribution** *ReturnDistribution, optional*
  : The fitted return distribution from the prior estimator.
    Passed internally by [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk). Must contain a
    `factor_model` with `loading_matrix` and `idio_covariance`.

  **\*\*fit_params** *dict*
  : Additional parameters (unused).
* **Returns:**
  **self** *OrthogonalCovarianceUncertaintySet*
  : Updated estimator.

<a id="skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.set_fit_request"></a>

#### set_fit_request(\*, return_distribution='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **return_distribution** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `return_distribution` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.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.

<a id="skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.set_partial_fit_request"></a>

#### set_partial_fit_request(\*, return_distribution='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `partial_fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `partial_fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `partial_fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **return_distribution** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `return_distribution` parameter in `partial_fit`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md

<a id="skfolio-uncertainty-set-orthogonalmuuncertaintyset"></a>

# skfolio.uncertainty_set.OrthogonalMuUncertaintySet

<a id="skfolio.uncertainty_set.OrthogonalMuUncertaintySet"></a>

### *class* skfolio.uncertainty_set.OrthogonalMuUncertaintySet(confidence_level=0.95, cs_weighting=INVERSE_IDIO_VARIANCE, uncertainty_shape='identity')

Expected return uncertainty set estimator for directions outside the factor span.

This estimator builds a norm-ball uncertainty set for expected returns that are in
the subspace orthogonal to the factor-model loading matrix, under the selected
cross-sectional weighting metric.

It is intended for cases where orthogonal expected returns are considered less
reliable than spanned expected returns and is designed to reduce the tendency of
optimizers to overallocate in these directions. Rather than shrinking the orthogonal
expected returns in the prior, this estimator keeps the point estimate
$\hat{\mu}$ unchanged and adds a portfolio-dependent worst-case penalty that
grows with exposure to the orthogonal subspace [[1]](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#r87c7fb2dc395-1) [[2]](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#r87c7fb2dc395-2) [[3]](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#r87c7fb2dc395-3).

Under this uncertainty set, the worst-case expected return for a portfolio with
weights $w$ is

$$
\inf_{\mu \in U_\mu} w^\top \mu
\;=\;
w^\top \hat{\mu}
-
\kappa \, \lVert L^\top w \rVert_2,
$$

where the low-rank geometry factor is

$$
L = G \Lambda^{1/2}.
$$

Here, $G$ is a basis for the subspace orthogonal to the factor-model span and
$\Lambda$ is a positive semidefinite scaling matrix that controls the
uncertainty assigned to each orthogonal direction.

Equivalently, the ellipsoidal shape matrix is [[4]](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#r87c7fb2dc395-4):

$$
S_\mu = L L^\top = G \Lambda G^\top.
$$

If the factor model uses basket-neutral constraints, the loading matrix is first
reduced to its effective full-rank basis before the orthogonal subspace is computed.

* **Parameters:**
  **confidence_level** *float, default=0.95*
  : Confidence level $\beta$ used to set the uncertainty size
    $$
    \kappa = \sqrt{\chi^2_{\mathrm{rank}}(\beta)}.
    $$

  **cs_weighting** *CSWeighting, default=CSWeighting.INVERSE_IDIO_VARIANCE*
  : Cross-sectional weighting used to define the orthogonality metric.

  **uncertainty_shape** *{“identity”, “idio_variance”}, default=”identity”*
  : Shape used inside the orthogonal subspace.
    * `"identity"` assigns the same uncertainty to all orthogonal directions.
    * `"idio_variance"` scales uncertainty using projected idiosyncratic variance
      in the orthogonal subspace.
* **Attributes:**
  **uncertainty_set_** *UncertaintySet*
  : Fitted solver-ready uncertainty set with:
    * `uncertainty_set_.radius = kappa`
    * `uncertainty_set_.geometry = L = G Lambda^{1/2}`
    * `uncertainty_set_.norm = 2`

### Methods

| [`fit`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet.fit)(X[, y, return_distribution])                   | Fit the orthogonal mu uncertainty set.                                                   |
|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| [`get_metadata_routing`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet.get_metadata_routing)()                             | Get metadata routing of this object.                                                     |
| [`get_params`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet.get_params)([deep])                                 | Get parameters for this estimator.                                                       |
| [`partial_fit`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet.partial_fit)(X[, y, return_distribution])           | Update the orthogonal mu uncertainty set.                                                |
| [`set_fit_request`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet.set_fit_request)(\*[, return_distribution])         | Configure whether metadata should be requested to be passed to the `fit` method.         |
| [`set_params`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet.set_params)(\*\*params)                             | Set the parameters of this estimator.                                                    |
| [`set_partial_fit_request`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet.set_partial_fit_request)(\*[, return_distribution]) | Configure whether metadata should be requested to be passed to the `partial_fit` method. |

### Notes

This estimator requires a factor model in the fitted return distribution. When used
inside [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk), the `return_distribution` metadata
is passed automatically by `fit` and `partial_fit`.

### References

* <a id='r87c7fb2dc395-1'>**[1]**</a> “Robustness properties of mean-variance portfolios”, Optimization: A Journal of Mathematical Programming and Operations Research, Schöttle & Werner (2009).
* <a id='r87c7fb2dc395-2'>**[2]**</a> “Portfolio Optimization: Theory and Application”, Chapter 14, Daniel P. Palomar (2025)
* <a id='r87c7fb2dc395-3'>**[3]**</a> “Robust Portfolio Selection Problems”, Mathematics of Operations Research, Goldfarb and Iyengar (2003).
* <a id='r87c7fb2dc395-4'>**[4]**</a> “Robust Convex Optimization”, Mathematics of Operations Research, Ben-Tal and Nemirovski (1998).

<a id="skfolio.uncertainty_set.OrthogonalMuUncertaintySet.fit"></a>

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

Fit the orthogonal mu uncertainty set.

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

  **y** *array-like of shape (n_observations, n_factors), optional*
  : Price returns of factors. The default is `None`.

  **return_distribution** *ReturnDistribution, optional*
  : The fitted return distribution from the prior estimator.
    Passed internally by [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk). Must contain a
    `factor_model` with `loading_matrix` and `idio_covariance`.

  **\*\*fit_params** *dict*
  : Additional parameters (unused).
* **Returns:**
  **self** *OrthogonalMuUncertaintySet*
  : Fitted estimator.

<a id="skfolio.uncertainty_set.OrthogonalMuUncertaintySet.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.uncertainty_set.OrthogonalMuUncertaintySet.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.uncertainty_set.OrthogonalMuUncertaintySet.partial_fit"></a>

#### partial_fit(X, y=None, \*, return_distribution=None, \*\*fit_params)

Update the orthogonal mu uncertainty set.

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

  **y** *array-like of shape (n_observations, n_factors), optional*
  : Price returns of factors. The default is `None`.

  **return_distribution** *ReturnDistribution, optional*
  : The fitted return distribution from the prior estimator.
    Passed internally by [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk). Must contain a
    `factor_model` with `loading_matrix` and `idio_covariance`.

  **\*\*fit_params** *dict*
  : Additional parameters (unused).
* **Returns:**
  **self** *OrthogonalMuUncertaintySet*
  : Updated estimator.

<a id="skfolio.uncertainty_set.OrthogonalMuUncertaintySet.set_fit_request"></a>

#### set_fit_request(\*, return_distribution='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **return_distribution** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `return_distribution` parameter in `fit`.
* **Returns:**
  **self** *object*
  : The updated object.

<a id="skfolio.uncertainty_set.OrthogonalMuUncertaintySet.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.

<a id="skfolio.uncertainty_set.OrthogonalMuUncertaintySet.set_partial_fit_request"></a>

#### set_partial_fit_request(\*, return_distribution='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the `partial_fit` method.

Note that this method is only relevant when this estimator is used as a
sub-estimator within a meta-estimator and metadata routing is enabled
with `enable_metadata_routing=True` (see `sklearn.set_config`).
Please check the [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

The options for each parameter are:

- `True`: metadata is requested, and passed to `partial_fit` if provided. The request is ignored if metadata is not provided.
- `False`: metadata is not requested and the meta-estimator will not pass it to `partial_fit`.
- `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
- `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (`sklearn.utils.metadata_routing.UNCHANGED`) retains the
existing request. This allows you to change the request for some
parameters and not others.

#### Versionadded
Added in version 1.3.

* **Parameters:**
  **return_distribution** *str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED*
  : Metadata routing for `return_distribution` parameter in `partial_fit`.
* **Returns:**
  **self** *object*
  : The updated object.

# generated/skfolio.uncertainty_set.UncertaintySet.html.md

<a id="skfolio-uncertainty-set-uncertaintyset"></a>

# skfolio.uncertainty_set.UncertaintySet

<a id="skfolio.uncertainty_set.UncertaintySet"></a>

### *class* skfolio.uncertainty_set.UncertaintySet(radius, geometry, norm)

Norm-ball uncertainty set.

A norm-ball uncertainty set represents deviations of a parameter vector $z$
from an estimate $\hat{z}$ as

$$
z - \hat{z} = L u,
\quad
\lVert u \rVert_p \le \kappa.
$$

Equivalently, the uncertainty set is

$$
\mathcal{U}
=
\left\{
    \hat{z} + L u :
    \lVert u \rVert_p \le \kappa
\right\}.
$$

All common uncertainty sets, including ellipsoidal, box and diamond sets, can be
represented by choosing the radius $\kappa$, the norm $p$ and the
linear map $L$.

The radius $\kappa$ controls the size of the normalized uncertainty ball.
The norm $p$ selects its canonical shape:

* $p = 2$: Euclidean ball
* $p = \infty$: Box
* $p = 1$: Diamond / Cross-polytope

The `geometry` parameter stores the linear geometry map $L$. It maps the
normalized ball into parameter space by scaling and mixing uncertainty directions to
form deviations of $z$ from $\hat{z}$. The estimator precomputes this
map so the optimizer can work directly with $L$, which may be low-rank
$(n \times r)$ with $r \ll n$.

For a linear exposure vector $e$, the worst-case deviation over
$\mathcal{U}$ is

$$
\sup_{z \in \mathcal{U}}
e^\top(z - \hat{z})
=
\kappa \,
\lVert L^\top e \rVert_q,
$$

where $q$ is the dual norm of $p$.

Downstream optimizers use this support-function as the uncertainty penalty.
For expected-return uncertainty, $z$ is $\mu$ and $e$ is the
portfolio weight vector. For covariance uncertainty, $z$ is
$\operatorname{vec}(\Sigma)$ (the vector obtained by stacking the columns of
$\Sigma$) and $e$ has the same vectorized shape.

Standard choices are:

* **Ellipsoidal set:** Use `norm=2`. For a full-rank shape matrix $S$, set
  `geometry` to a square-root factor $L$ satisfying $S = L L^\top$. This
  gives $(z - \hat{z})^\top S^{-1} (z - \hat{z}) \le \kappa^2$. For a low-rank
  representation $S = G \Lambda G^\top$, set `geometry` to $G \Lambda^{1/2}$.
* **Box set:** Use `norm=np.inf`. With axis widths $\delta_i$, set `geometry`
  to $\operatorname{diag}(\delta)$. This gives
  $|z_i - \hat{z}_i| \le \kappa \delta_i$ for each coordinate and the dual
  norm is $1$.
* **Diamond set:** Use `norm=1`. With axis scales $\delta_i$, set `geometry`
  to $\operatorname{diag}(\delta)$. This gives
  $\sum_i |z_i - \hat{z}_i| / \delta_i \le \kappa$ and the dual norm is
  $\infty$.

* **Parameters:**
  **radius** *float*
  : Radius $\kappa$ of the normalized uncertainty ball
    $\lVert u \rVert_p \le \kappa$.

  **geometry** *ndarray of shape (n_parameters, n_uncertainties)*
  : Linear geometry map $L$ mapping normalized uncertainty coordinates into
    deviations from $\hat{z}$:
    $$
    z - \hat{z} = L u.
    $$
    <br/>
    For ellipsoidal uncertainty with shape matrix $S$, `geometry` is a
    square-root factor $L$ satisfying $S = L L^\top$.
    <br/>
    For axis-aligned box or diamond uncertainty with widths `delta`, `geometry` is
    typically $\operatorname{diag}(\delta)$.

  **norm** *float or int, default=2*
  : Norm $p$ defining the normalized uncertainty ball. Must be greater than or
    equal to 1. Common choices are `2` for ellipsoidal uncertainty, `np.inf` for box
    uncertainty, and `1` for diamond uncertainty.
* **Attributes:**
  [`dual_norm`](https://skfolio.org/generated/skfolio.uncertainty_set.UncertaintySet.html.md#skfolio.uncertainty_set.UncertaintySet.dual_norm) *float*
  : Dual norm associated with `norm`.

<a id="skfolio.uncertainty_set.UncertaintySet.dual_norm"></a>

#### *property* dual_norm

Dual norm associated with `norm`.

# generated/skfolio.utils.stats.CSWeighting.html.md

<a id="skfolio-utils-stats-csweighting"></a>

# skfolio.utils.stats.CSWeighting

<a id="skfolio.utils.stats.CSWeighting"></a>

### *class* skfolio.utils.stats.CSWeighting(\*values)

Cross-sectional weighting.

<a id="skfolio.utils.stats.CSWeighting.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.utils.stats.CorrelationMethod.html.md

<a id="skfolio-utils-stats-correlationmethod"></a>

# skfolio.utils.stats.CorrelationMethod

<a id="skfolio.utils.stats.CorrelationMethod"></a>

### *class* skfolio.utils.stats.CorrelationMethod(\*values)

Correlation method.

<a id="skfolio.utils.stats.CorrelationMethod.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.utils.stats.NBinsMethod.html.md

<a id="skfolio-utils-stats-nbinsmethod"></a>

# skfolio.utils.stats.NBinsMethod

<a id="skfolio.utils.stats.NBinsMethod"></a>

### *class* skfolio.utils.stats.NBinsMethod(\*values)

Enumeration of the Number of Bins Methods.

* **Parameters:**
  **FREEDMAN** *str*
  : Freedman method

  **KNUTH** *str*
  : Knuth method

<a id="skfolio.utils.stats.NBinsMethod.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.utils.stats.assert_is_distance.html.md

<a id="skfolio-utils-stats-assert-is-distance"></a>

# skfolio.utils.stats.assert_is_distance

<a id="skfolio.utils.stats.assert_is_distance"></a>

### skfolio.utils.stats.assert_is_distance(x)

Raises an error if the matrix is not a distance matrix.

* **Parameters:**
  **x** *ndarray of shape (n, n)*
  : The matrix.
* **Raises:**
  ValueError: if the matrix is a distance matrix.

# generated/skfolio.utils.stats.assert_is_square.html.md

<a id="skfolio-utils-stats-assert-is-square"></a>

# skfolio.utils.stats.assert_is_square

<a id="skfolio.utils.stats.assert_is_square"></a>

### skfolio.utils.stats.assert_is_square(x)

Raises an error if the matrix is not square.

* **Parameters:**
  **x** *ndarray of shape (n, n)*
  : The matrix.
* **Raises:**
  ValueError: if the matrix is not square.

# generated/skfolio.utils.stats.assert_is_symmetric.html.md

<a id="skfolio-utils-stats-assert-is-symmetric"></a>

# skfolio.utils.stats.assert_is_symmetric

<a id="skfolio.utils.stats.assert_is_symmetric"></a>

### skfolio.utils.stats.assert_is_symmetric(x, \*, rtol=1e-05, atol=1e-08)

Raises an error if the matrix is not symmetric.

* **Parameters:**
  **x** *ndarray of shape (n, m)*
  : The matrix.

  **rtol** *float, default=1e-5*
  : Relative tolerance for `numpy.allclose`.

  **atol** *float, default=1e-8*
  : Absolute tolerance for `numpy.allclose`.
* **Raises:**
  ValueError: if the matrix is not symmetric.

# generated/skfolio.utils.stats.combination_by_index.html.md

<a id="skfolio-utils-stats-combination-by-index"></a>

# skfolio.utils.stats.combination_by_index

<a id="skfolio.utils.stats.combination_by_index"></a>

### skfolio.utils.stats.combination_by_index(idx, n, k)

Retrieve the k-combination at a given lexicographic position without enumerating
all combinations.

This function implements the *unranking* algorithm (also known as the combinatorial
number system or “combinadic”) to retrieve the specific k-combination corresponding
to a given lexicographic `idx` without generating all C(n, k) possible subsets.

Given a universe of size `n`, there are M = C(n, k) possible subsets of size k.
This function returns the subset corresponding to the `idx` in lex order.

This approach is crucial when M = C(n, k) is too large to generate or store all
combinations, and you need to draw random subsets uniformly (sampling k=5 from n=100
gives M ≈ 7.5e7).

Time complexity: O(k)
Space complexity: O(k)

* **Parameters:**
  **idx** *int*
  : Index (rank) of the desired combination in lex order. Must satisfy
    0 <= idx < C(n, k).

  **n** *int*
  : Size of the universe.

  **k** *int*
  : Size of each combination (0 <= k <= n).
* **Returns:**
  **combination** *ndarray of shape (k,)*
  : 1D integer array of length k containing the sorted k-combination.
* **Raises:**
  ValueError
  : If parameters are out of valid range.

### References

..[1] “The Art of Computer Programming”, Vol. 4A: Combinatorial Algorithms,
: Section 7.2.1.3. Knuth, D. E. (1998).

# generated/skfolio.utils.stats.commutation_matrix.html.md

<a id="skfolio-utils-stats-commutation-matrix"></a>

# skfolio.utils.stats.commutation_matrix

<a id="skfolio.utils.stats.commutation_matrix"></a>

### skfolio.utils.stats.commutation_matrix(x)

Compute the commutation matrix.

* **Parameters:**
  **x** *ndarray of shape (n, m)*
  : The matrix.
* **Returns:**
  **K** *ndarray of shape (m \* n, m \* n)*
  : The commutation matrix.

# generated/skfolio.utils.stats.compute_optimal_n_clusters.html.md

<a id="skfolio-utils-stats-compute-optimal-n-clusters"></a>

# skfolio.utils.stats.compute_optimal_n_clusters

<a id="skfolio.utils.stats.compute_optimal_n_clusters"></a>

### skfolio.utils.stats.compute_optimal_n_clusters(distance, linkage_matrix)

Compute the optimal number of clusters based on Two-Order Difference to Gap
Statistic [[1]](https://skfolio.org/generated/skfolio.utils.stats.compute_optimal_n_clusters.html.md#re0e718a4c413-1).

The Two-Order Difference to Gap Statistic has been developed to improve the
performance and stability of the Tibshiranis Gap statistic.
It applies the two-order difference of the within-cluster dispersion to replace the
reference null distribution in the Gap statistic.

The number of cluster $k$ is determined by:

$$
\begin{cases}
\begin{aligned}
&\max_{k} & & W_{k+2} + W_{k} - 2 W_{k+1} \\
&\text{s.t.} & & 1 \ge c \ge max\bigl(8, \sqrt{n}\bigr) \\
\end{aligned}
\end{cases}

$$

with $n$ the sample size and $W_{k}$ the within-cluster dispersions
defined as:

$$
W_{k} = \sum_{i=1}^{k} \frac{D_{i}}{2|C_{i}|}

$$

where $|C_{i}|$ is the cardinality of cluster $i$ and $D_{i}$ its
density defined as:

$$
D_{i} = \sum_{u \in C_{i}} \sum_{v \in C_{i}} d(u,v)

$$

with $d(u,v)$ the distance between u and v.

* **Parameters:**
  **distance** *ndarray of shape (n, n)*
  : Distance matrix.

  **linkage_matrix** *ndarray of shape (n - 1, 4)*
  : Linkage matrix.
* **Returns:**
  **value** *int*
  : Optimal number of clusters.

### References

* <a id='re0e718a4c413-1'>**[1]**</a> “Application of two-order difference to gap statistic”. Yue, Wang & Wei (2009)

# generated/skfolio.utils.stats.corr_to_cov.html.md

<a id="skfolio-utils-stats-corr-to-cov"></a>

# skfolio.utils.stats.corr_to_cov

<a id="skfolio.utils.stats.corr_to_cov"></a>

### skfolio.utils.stats.corr_to_cov(corr, std)

Convert a correlation matrix to a covariance matrix given its
standard-deviation vector.

* **Parameters:**
  **corr** *ndarray of shape (n, n)*
  : Correlation matrix.

  **std** *ndarray of shape (n, )*
  : Standard-deviation vector.
* **Returns:**
  **cov** *ndarray of shape (n, n)*
  : Covariance matrix

# generated/skfolio.utils.stats.cov_nearest.html.md

<a id="skfolio-utils-stats-cov-nearest"></a>

# skfolio.utils.stats.cov_nearest

<a id="skfolio.utils.stats.cov_nearest"></a>

### skfolio.utils.stats.cov_nearest(cov, higham=False, higham_max_iteration=100, warn=False)

Compute the nearest covariance matrix that is positive definite and with a
cholesky decomposition that can be computed. The variance is left unchanged.
A covariance matrix that is not positive definite often occurs in high
dimensional problems. It can be due to multicollinearity, floating-point
inaccuracies, or when the number of observations is smaller than the number of
assets.

First, it converts the covariance matrix to a correlation matrix.
Then, it finds the nearest correlation matrix and converts it back to a covariance
matrix using the initial standard deviation.

Cholesky decomposition can fail for symmetric positive definite (SPD) matrix due
to floating point error and inversely, Cholesky decomposition can succeed for
non-SPD matrix. Therefore, we need to test for both. We always start by testing
for Cholesky decomposition which is significantly faster than checking for positive
eigenvalues.

* **Parameters:**
  **cov** *ndarray of shape (n, n)*
  : Covariance matrix.

  **higham** *bool, default=False*
  : If this is set to True, the Higham (2002) algorithm [[1]](https://skfolio.org/generated/skfolio.utils.stats.cov_nearest.html.md#r06f528358d09-1) is used,
    otherwise the eigenvalues are clipped to threshold above zeros (1e-13).
    The default (`False`) is to use the clipping method as the Higham
    algorithm can be slow for large datasets.

  **higham_max_iteration** *int, default=100*
  : Maximum number of iterations of the Higham (2002) algorithm.
    The default value is `100`.

  **warn** *bool, default=False*
  : If this is set to True, a user warning is emitted when the covariance matrix
    is not positive definite and replaced by the nearest. The default is False.
* **Returns:**
  **cov** *ndarray*
  : The nearest covariance matrix.

### References

* <a id='r06f528358d09-1'>**[1]**</a> “Computing the nearest correlation matrix - a problem from finance” IMA Journal of Numerical Analysis Higham (2002)

# generated/skfolio.utils.stats.cov_to_corr.html.md

<a id="skfolio-utils-stats-cov-to-corr"></a>

# skfolio.utils.stats.cov_to_corr

<a id="skfolio.utils.stats.cov_to_corr"></a>

### skfolio.utils.stats.cov_to_corr(cov)

Convert a covariance matrix to a correlation matrix.

* **Parameters:**
  **cov** *ndarray of shape (n, n)*
  : Covariance matrix.
* **Returns:**
  **corr, std** *tuple[ndarray of shape (n, n), ndarray of shape (n, )]*
  : Correlation matrix and standard-deviation vector

# generated/skfolio.utils.stats.cs_pearson_correlation.html.md

<a id="skfolio-utils-stats-cs-pearson-correlation"></a>

# skfolio.utils.stats.cs_pearson_correlation

<a id="skfolio.utils.stats.cs_pearson_correlation"></a>

### skfolio.utils.stats.cs_pearson_correlation(a, b, weights=None, axis=0, min_count=3, eps=1e-12)

Weighted cross-sectional Pearson correlation.

Computes the weighted Pearson correlation between *a* and *b* along `axis`.
All other dimensions are treated as independent batch dimensions over which the
computation is vectorized.

For vectors $a$ and $b$ with weights $w$:

$$
\rho = \frac{
    \sum_n w_n \,(a_n - \bar a)\,(b_n - \bar b)
}{
    \sqrt{\sum_n w_n \,(a_n - \bar a)^2}\;
    \sqrt{\sum_n w_n \,(b_n - \bar b)^2}
}
$$

where $\bar a = \sum_n w_n a_n / \sum_n w_n$ (and likewise for $\bar b$).

* **Parameters:**
  **a** *ndarray*
  : First array.

  **b** *ndarray*
  : Second array, broadcastable to the same shape as *a*.

  **weights** *ndarray, optional*
  : Non-negative weights, broadcastable to *a* along `axis`.
    `None` uses equal weights. Non-finite and zero weights are excluded
    from weighted correlations.

  **axis** *int, default=0*
  : The cross-sectional axis along which correlation is computed.

  **min_count** *int, default=3*
  : Minimum number of effective observations along `axis`. Without
    `weights`, this is the number of jointly finite observations. With
    `weights`, this is the number of jointly finite observations with
    finite strictly positive weight.

  **eps** *float, default=1e-12*
  : Denominator threshold below which `NaN` is returned to guard against
    near-constant vectors.
* **Returns:**
  **corr** *float or ndarray*
  : Scalar when inputs are 1D, otherwise an array with `axis`
    removed.

# generated/skfolio.utils.stats.cs_rank.html.md

<a id="skfolio-utils-stats-cs-rank"></a>

# skfolio.utils.stats.cs_rank

<a id="skfolio.utils.stats.cs_rank"></a>

### skfolio.utils.stats.cs_rank(a, axis=0)

Cross-sectional rank along an axis.

Ranks are 1-based. `NaN` values remain `NaN` and are excluded from the ranking
(i.e. only finite values receive ranks).

* **Parameters:**
  **a** *ndarray*
  : Input array.

  **axis** *int, default=0*
  : Axis along which to rank.
* **Returns:**
  **ranks** *ndarray*
  : Same shape as *a*, dtype `float64`.

# generated/skfolio.utils.stats.cs_spearman_correlation.html.md

<a id="skfolio-utils-stats-cs-spearman-correlation"></a>

# skfolio.utils.stats.cs_spearman_correlation

<a id="skfolio.utils.stats.cs_spearman_correlation"></a>

### skfolio.utils.stats.cs_spearman_correlation(a, b, axis=0, min_count=3, eps=1e-12)

Cross-sectional Spearman rank correlation.

Ranks the jointly finite values of *a* and *b* along `axis` with [`cs_rank`](https://skfolio.org/generated/skfolio.utils.stats.cs_rank.html.md#skfolio.utils.stats.cs_rank),
then computes their Pearson correlation via [`cs_pearson_correlation`](https://skfolio.org/generated/skfolio.utils.stats.cs_pearson_correlation.html.md#skfolio.utils.stats.cs_pearson_correlation)
(unweighted).

* **Parameters:**
  **a** *ndarray*
  : First array.

  **b** *ndarray*
  : Second array, same shape as *a*.

  **axis** *int, default=0*
  : The cross-sectional axis along which correlation is computed.

  **min_count** *int, default=3*
  : Minimum number of jointly finite observations along `axis`.

  **eps** *float, default=1e-12*
  : Denominator threshold below which `NaN` is returned.
* **Returns:**
  **corr** *float or ndarray*
  : Scalar when inputs are 1D, otherwise an array with `axis`
    removed.

# generated/skfolio.utils.stats.inverse_multiply.html.md

<a id="skfolio-utils-stats-inverse-multiply"></a>

# skfolio.utils.stats.inverse_multiply

<a id="skfolio.utils.stats.inverse_multiply"></a>

### skfolio.utils.stats.inverse_multiply(a, b)

Multiply the inverse of matrix a by matrix b.
We use np.linalg.solve as it tends to produce more accurate results than
np.linalg.inv.

* **Parameters:**
  **a** *ndarray of shape (n, n)*
  : Square matrix.

  **b** *ndarray of shape (n, m)*
  : Matrix.
* **Returns:**
  **m** *ndarray of shape (n, m)*
  : The inverse of matrix a multiplied by matrix b.

# generated/skfolio.utils.stats.inverse_volatility_weights.html.md

<a id="skfolio-utils-stats-inverse-volatility-weights"></a>

# skfolio.utils.stats.inverse_volatility_weights

<a id="skfolio.utils.stats.inverse_volatility_weights"></a>

### skfolio.utils.stats.inverse_volatility_weights(covariance)

Inverse-volatility portfolio weights from a covariance matrix.

Computes weights proportional to the inverse standard deviation:
$w_i \propto 1/\sigma_i$, normalized to sum to 1.

* **Parameters:**
  **covariance** *ndarray of shape (n, n)*
  : Covariance matrix.
* **Returns:**
  **w** *ndarray of shape (n,)*
  : Normalized weights summing to 1.

# generated/skfolio.utils.stats.is_cholesky_dec.html.md

<a id="skfolio-utils-stats-is-cholesky-dec"></a>

# skfolio.utils.stats.is_cholesky_dec

<a id="skfolio.utils.stats.is_cholesky_dec"></a>

### skfolio.utils.stats.is_cholesky_dec(x)

Returns True if Cholesky decomposition can be computed.
The matrix must be Hermitian (symmetric if real-valued) and positive-definite.
No checking is performed to verify whether the matrix is Hermitian or not.

* **Parameters:**
  **x** *ndarray of shape (n, m)*
  : The matrix.
* **Returns:**
  **value** *bool*
  : True if Cholesky decomposition can be applied to the matrix, False otherwise.

# generated/skfolio.utils.stats.minimize_relative_weight_deviation.html.md

<a id="skfolio-utils-stats-minimize-relative-weight-deviation"></a>

# skfolio.utils.stats.minimize_relative_weight_deviation

<a id="skfolio.utils.stats.minimize_relative_weight_deviation"></a>

### skfolio.utils.stats.minimize_relative_weight_deviation(weights, min_weights, max_weights, solver='CLARABEL', solver_params=None)

Apply weight constraints to an initial array of weights by minimizing the relative
weight deviation of the final weights from the initial weights.

$$
\begin{cases}
\begin{aligned}
&\min_{w} & & \Vert \frac{w - w_{init}}{w_{init}} \Vert_{2}^{2} \\
&\text{s.t.} & & \sum_{i=1}^{N} w_{i} = 1 \\
& & & w_{min} \leq w_i \leq w_{max}, \quad \forall i
\end{aligned}
\end{cases}

$$

* **Parameters:**
  **weights** *ndarray of shape (n_assets,)*
  : Strictly positive initial weights summing to one.

  **min_weights** *ndarray of shape (n_assets,)*
  : Minimum assets weights (weights lower bounds).

  **max_weights** *ndarray of shape (n_assets,)*
  : Maximum assets weights (weights upper bounds).

  **solver** *str, default=”CLARABEL”*
  : The solver to use. The default is “CLARABEL” which is written in Rust and has
    better numerical stability and performance than ECOS and SCS.
    For more details about available solvers, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver](https://www.cvxpy.org/tutorial/advanced/index.html#choosing-a-solver)

  **solver_params** *dict, optional*
  : Solver parameters. For example, `solver_params=dict(verbose=True)`.
    The default (`None`) is to use the CVXPY default.
    For more details about solver arguments, check the CVXPY documentation:
    [https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options](https://www.cvxpy.org/tutorial/advanced/index.html#setting-solver-options)

# generated/skfolio.utils.stats.multiply_by_inverse.html.md

<a id="skfolio-utils-stats-multiply-by-inverse"></a>

# skfolio.utils.stats.multiply_by_inverse

<a id="skfolio.utils.stats.multiply_by_inverse"></a>

### skfolio.utils.stats.multiply_by_inverse(a, b)

Multiply matrix a by the inverse of matrix b.
We use np.linalg.solve as it tends to produce more accurate results than
np.linalg.inv.

* **Parameters:**
  **a** *ndarray of shape (n, m)*
  : Matrix.

  **b** *ndarray of shape (n, n)*
  : Square matrix.
* **Returns:**
  **m** *ndarray of shape (n, m)*
  : The matrix a multiplied by the inverse of matrix b.

# generated/skfolio.utils.stats.n_bins_freedman.html.md

<a id="skfolio-utils-stats-n-bins-freedman"></a>

# skfolio.utils.stats.n_bins_freedman

<a id="skfolio.utils.stats.n_bins_freedman"></a>

### skfolio.utils.stats.n_bins_freedman(x)

Compute the optimal histogram bin size using the Freedman-Diaconis rule [[1]](https://skfolio.org/generated/skfolio.utils.stats.n_bins_freedman.html.md#r8d5b646da1d1-1).

* **Parameters:**
  **x** *ndarray of shape (n_observations,)*
  : The input array.
* **Returns:**
  **n_bins** *int*
  : The optimal bin size.

### References

* <a id='r8d5b646da1d1-1'>**[1]**</a> “On the histogram as a density estimator: L2 theory”. Freedman & Diaconis (1981).

# generated/skfolio.utils.stats.n_bins_knuth.html.md

<a id="skfolio-utils-stats-n-bins-knuth"></a>

# skfolio.utils.stats.n_bins_knuth

<a id="skfolio.utils.stats.n_bins_knuth"></a>

### skfolio.utils.stats.n_bins_knuth(x)

Compute the optimal histogram bin size using Knuth’s rule [[1]](https://skfolio.org/generated/skfolio.utils.stats.n_bins_knuth.html.md#r8c3fe88ee915-1).

* **Parameters:**
  **x** *ndarray of shape (n_observations,)*
  : The input array.
* **Returns:**
  **n_bins** *int*
  : The optimal bin size.

### References

* <a id='r8c3fe88ee915-1'>**[1]**</a> “Optimal Data-Based Binning for Histograms”. Knuth.

# generated/skfolio.utils.stats.rand_weights.html.md

<a id="skfolio-utils-stats-rand-weights"></a>

# skfolio.utils.stats.rand_weights

<a id="skfolio.utils.stats.rand_weights"></a>

### skfolio.utils.stats.rand_weights(n, zeros=0, seed=None)

Produces n random weights that sum to one from a uniform distribution
(non-uniform distribution over a simplex).

* **Parameters:**
  **n** *int*
  : Number of weights.

  **zeros** *int, default=0*
  : The number of weights to randomly set to zeros.

  **seed** *int, optional*
  : Seed for reproducibility. If None, use an unseeded generator.
* **Returns:**
  **weights** *ndarray of shape (n, )*
  : The vector of weights.

# generated/skfolio.utils.stats.rand_weights_dirichlet.html.md

<a id="skfolio-utils-stats-rand-weights-dirichlet"></a>

# skfolio.utils.stats.rand_weights_dirichlet

<a id="skfolio.utils.stats.rand_weights_dirichlet"></a>

### skfolio.utils.stats.rand_weights_dirichlet(n)

Produces n random weights that sum to one from a Dirichlet distribution
(uniform distribution over a simplex).

* **Parameters:**
  **n** *int*
  : Number of weights.
* **Returns:**
  **weights** *ndarray of shape (n, )*
  : The vector of weights.

# generated/skfolio.utils.stats.safe_cholesky.html.md

<a id="skfolio-utils-stats-safe-cholesky"></a>

# skfolio.utils.stats.safe_cholesky

<a id="skfolio.utils.stats.safe_cholesky"></a>

### skfolio.utils.stats.safe_cholesky(covariance, ridge_scale=1e-12, max_tries=3)

Compute a Cholesky factor $L$ from covariance $\Sigma$.

Fast path: try plain Cholesky on the input as-is.
Fallback: symmetrize and add ridge $\lambda I$ with escalation until SPD:

$$
\Sigma_{reg} = (\Sigma + \Sigma^T)/2 + \lambda I \approx L L^T

$$

* **Parameters:**
  **covariance** *ndarray of shape (n_assets, n_assets)*
  : Covariance matrix $\Sigma$.

  **ridge_scale** *float, default=1e-12*
  : Relative ridge size, as a fraction of the average absolute covariance
    diagonal. If that scale is zero, a positive numerical floor is used.

  **max_tries** *int, default=3*
  : Maximum number of ridge escalations before raising an error.
* **Returns:**
  **chol** *ndarray of shape (n_assets, n_assets)*
  : Lower triangular Cholesky factor $L$ such that
    $\Sigma \approx L L^T$.
* **Raises:**
  ValueError
  : If Cholesky decomposition fails after all retry attempts.

# generated/skfolio.utils.stats.sample_unique_subsets.html.md

<a id="skfolio-utils-stats-sample-unique-subsets"></a>

# skfolio.utils.stats.sample_unique_subsets

<a id="skfolio.utils.stats.sample_unique_subsets"></a>

### skfolio.utils.stats.sample_unique_subsets(n, k, n_subsets, random_state=None)

Generate unique k-element subsets from a universe of size n using combinatorial
unranking.

Each subset is drawn without replacement (elements within subset are distinct) and
no subset is repeated across draws. Ranks are sampled uniformly without replacement
over [0, C(n, k)).

Time complexity: O(n_subsets \* k)
Space complexity: O(n_subsets \* k)

* **Parameters:**
  **n** *int*
  : Universe size.

  **k** *int*
  : Subset size (0 <= k <= n).

  **n_subsets** *int*
  : Number of distinct subsets to generate (0 <= n_subsets <= C(n, k)).

  **random_state** *int, RandomState instance, optional*
  : Seed or random state to ensure reproducibility.
* **Returns:**
  **subsets** *ndarray of shape (n_subsets, k)*
  : 2D integer array of shape (n_subsets, k) where each row is a sorted
    k-combination.
* **Raises:**
  ValueError
  : If any parameters are out of valid ranges.

# generated/skfolio.utils.stats.squared_mahalanobis_dist.html.md

<a id="skfolio-utils-stats-squared-mahalanobis-dist"></a>

# skfolio.utils.stats.squared_mahalanobis_dist

<a id="skfolio.utils.stats.squared_mahalanobis_dist"></a>

### skfolio.utils.stats.squared_mahalanobis_dist(X, covariance, mean=None, ridge_scale=1e-12, max_tries=3)

Squared Mahalanobis distance via Cholesky decomposition.

$$
d^2 = (r - \mu)^\top \Sigma^{-1} (r - \mu)

$$

* **Parameters:**
  **X** *ndarray of shape (n_observations, n_assets) or (n_assets,)*
  : Price returns of the assets. If 1-D, treated as a single observation and a
    scalar is returned.

  **covariance** *ndarray of shape (n_assets, n_assets)*
  : Covariance matrix $\Sigma$.

  **mean** *ndarray of shape (n_assets,), optional*
  : Mean vector $\mu$ subtracted from each row.  If `None`, data
    are assumed already centred.

  **ridge_scale** *float, default=1e-12*
  : Relative ridge size, as a fraction of the average covariance diagonal.

  **max_tries** *int, default=3*
  : Maximum number of ridge escalations before raising an error.
* **Returns:**
  **d2** *ndarray of shape (n_observations,) or float*
  : Squared Mahalanobis distances (non-negative).

# generated/skfolio.utils.stats.squared_standardized_euclidean_dist.html.md

<a id="skfolio-utils-stats-squared-standardized-euclidean-dist"></a>

# skfolio.utils.stats.squared_standardized_euclidean_dist

<a id="skfolio.utils.stats.squared_standardized_euclidean_dist"></a>

### skfolio.utils.stats.squared_standardized_euclidean_dist(returns, covariance)

Squared standardized Euclidean distance.

$$
d^2 = \sum_i (r_i\,/\,\sigma_i)^2

$$

This is the squared Mahalanobis distance using only the diagonal of the
covariance matrix (ignoring correlations).

* **Parameters:**
  **returns** *ndarray of shape (n_assets,)*
  : Asset return vector.

  **covariance** *ndarray of shape (n_assets, n_assets)*
  : Covariance matrix.
* **Returns:**
  float
  : Sum of squared standardized returns (non-negative).
    Under correct calibration: $\mathbb{E}[d^2] = n_{\text{assets}}$.

# generated/skfolio.utils.stats.symmetric_step_up_matrix.html.md

<a id="skfolio-utils-stats-symmetric-step-up-matrix"></a>

# skfolio.utils.stats.symmetric_step_up_matrix

<a id="skfolio.utils.stats.symmetric_step_up_matrix"></a>

### skfolio.utils.stats.symmetric_step_up_matrix(n1, n2)

Compute the Symmetric step-up matrix M such that `M @ np.ones(n2) = np.ones(n1)`.

* **Parameters:**
  **n1** *int*
  : First dimension.

  **n2** *int*
  : Second dimension.
* **Returns:**
  **m** *ndarray of shape (n1, n2)*
  : The Symmetric step-up matrix.

# generated/skfolio.utils.stats.symmetrize.html.md

<a id="skfolio-utils-stats-symmetrize"></a>

# skfolio.utils.stats.symmetrize

<a id="skfolio.utils.stats.symmetrize"></a>

### skfolio.utils.stats.symmetrize(matrix, where=None)

In-place symmetrization: $M \leftarrow (M + M^T) / 2$.

When `where` is provided, only the sub-block indexed by the mask is
symmetrized, leaving the rest of the matrix untouched. This is useful for
matrices that contain NaN rows/columns where a full transpose would
propagate NaNs into the finite block.

* **Parameters:**
  **matrix** *ndarray of shape (n, n)*
  : Square matrix to symmetrize in-place.

  **where** *ndarray of shape (n,), optional*
  : Boolean mask indicating which rows/columns to include. If `None`,
    the full matrix is symmetrized.

# generated/skfolio.utils.tools.AutoEnum.html.md

<a id="skfolio-utils-tools-autoenum"></a>

# skfolio.utils.tools.AutoEnum

<a id="skfolio.utils.tools.AutoEnum"></a>

### *class* skfolio.utils.tools.AutoEnum(new_class_name, /, names, \*, module=None, qualname=None, type=None, start=1, boundary=None)

Base Enum class used in `skfolio`.

<a id="skfolio.utils.tools.AutoEnum.has"></a>

#### *classmethod* has(value)

Check if a value is in the Enum.

* **Parameters:**
  **value** *str*
  : Input value.
* **Returns:**
  **x** *bool*
  : True if the value is in the Enum, False otherwise.

# generated/skfolio.utils.tools.apply_window_size.html.md

<a id="skfolio-utils-tools-apply-window-size"></a>

# skfolio.utils.tools.apply_window_size

<a id="skfolio.utils.tools.apply_window_size"></a>

### skfolio.utils.tools.apply_window_size(X, window_size)

Return the last `window_size` observations from the array X.

* **Parameters:**
  **X** *ndarray of shape (n_observations,) or (n_observations, n_assets)*
  : Input array from which to extract the last observations.
    Can be 1D or 2D.

  **window_size** *int or None*
  : Number of observations to keep from the end of X.
    If None, returns X unchanged.
* **Returns:**
  **X_windowed** *ndarray*
  : The last `window_size` rows of X. If `window_size` is None,
    returns the original array unchanged.
* **Raises:**
  ValueError
  : If `window_size` is not a positive integer or cannot be converted to int.

  ValueError
  : If `window_size` exceeds the number of observations in X.

### Examples

```pycon
>>> import numpy as np
>>> X = np.array([[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]])
>>> apply_window_size(X, window_size=3)
array([[ 5,  6],
       [ 7,  8],
       [ 9, 10]])
```

# generated/skfolio.utils.tools.args_names.html.md

<a id="skfolio-utils-tools-args-names"></a>

# skfolio.utils.tools.args_names

<a id="skfolio.utils.tools.args_names"></a>

### skfolio.utils.tools.args_names(func)

Returns the argument names of a function.

* **Parameters:**
  **func** *object*
  : Function.
* **Returns:**
  **args** *list[str]*
  : The list of function arguments.

# generated/skfolio.utils.tools.bisection.html.md

<a id="skfolio-utils-tools-bisection"></a>

# skfolio.utils.tools.bisection

<a id="skfolio.utils.tools.bisection"></a>

### skfolio.utils.tools.bisection(x)

Generator to bisect a list of arrays.

* **Parameters:**
  **x** *list[ndarray]*
  : A list of arrays.
* **Yields:**
  **arr** *Iterator[list[ndarray, ndarray]]*
  : Bisected array.

# generated/skfolio.utils.tools.cache_method.html.md

<a id="skfolio-utils-tools-cache-method"></a>

# skfolio.utils.tools.cache_method

<a id="skfolio.utils.tools.cache_method"></a>

### skfolio.utils.tools.cache_method(cache_name)

Decorator that caches class method results into a class dictionary.

* **Parameters:**
  **cache_name** *str*
  : Name of the dictionary class attribute.
* **Returns:**
  **func** *Callable*
  : Decorating function that caches class methods.

# generated/skfolio.utils.tools.cached_property_slots.html.md

<a id="skfolio-utils-tools-cached-property-slots"></a>

# skfolio.utils.tools.cached_property_slots

<a id="skfolio.utils.tools.cached_property_slots"></a>

### *class* skfolio.utils.tools.cached_property_slots(func)

Cached property decorator for slots.

# generated/skfolio.utils.tools.check_estimator.html.md

<a id="skfolio-utils-tools-check-estimator"></a>

# skfolio.utils.tools.check_estimator

<a id="skfolio.utils.tools.check_estimator"></a>

### skfolio.utils.tools.check_estimator(estimator, default, check_type)

Check the estimator type and return its cloned version if provided, otherwise
return the default estimator.

* **Parameters:**
  **estimator** *BaseEstimator | “passthrough”, optional*
  : Estimator.

  **default** *BaseEstimator, optional*
  : Default estimator to return when `estimator` is `None`.

  **check_type** *Any*
  : Expected type of the estimator to check against.
* **Returns:**
  **estimator** *Estimator | “passthrough”*
  : The checked estimator or the default.

# generated/skfolio.utils.tools.deduplicate_names.html.md

<a id="skfolio-utils-tools-deduplicate-names"></a>

# skfolio.utils.tools.deduplicate_names

<a id="skfolio.utils.tools.deduplicate_names"></a>

### skfolio.utils.tools.deduplicate_names(names)

Rename duplicated names by appending “_{duplicate_nb}” at the end.

This function is inspired by the pandas function `_maybe_dedup_names`.

* **Parameters:**
  **names** *array-like of shape (n_names,)*
  : List of names.
* **Returns:**
  **names** *list[str]*
  : Deduplicate names.

# generated/skfolio.utils.tools.default_asset_names.html.md

<a id="skfolio-utils-tools-default-asset-names"></a>

# skfolio.utils.tools.default_asset_names

<a id="skfolio.utils.tools.default_asset_names"></a>

### skfolio.utils.tools.default_asset_names(n_assets)

Default asset names are `["x0", "x1", ..., "x(n_assets - 1)"]`.

* **Parameters:**
  **n_assets** *int*
  : Number of assets.
* **Returns:**
  **asset_names** *ndarray of str*
  : Default assets names.

# generated/skfolio.utils.tools.fit_and_predict.html.md

<a id="skfolio-utils-tools-fit-and-predict"></a>

# skfolio.utils.tools.fit_and_predict

<a id="skfolio.utils.tools.fit_and_predict"></a>

### skfolio.utils.tools.fit_and_predict(estimator, X, y, train, test, fit_params, method, column_indices=None)

Fit the estimator and predict values for a given dataset split.

* **Parameters:**
  **estimator** *estimator object implementing ‘fit’ and ‘predict’*
  : The object to use to fit the data.

  **X** *array-like of shape (n_observations, n_assets)*
  : The data to fit.

  **y** *array-like of shape (n_observations, n_factors) or None*
  : The factor array if provided

  **train** *ndarray of int of shape (n_train_observations,)*
  : Indices of training samples.

  **test** *ndarray of int of shape (n_test_samples,) or list of ndarray*
  : Indices of test samples or list of indices.

  **fit_params** *dict*
  : Parameters that will be passed to `estimator.fit`.

  **method** *str*
  : Invokes the passed method name of the passed estimator.

  **column_indices** *ndarray, optional*
  : Indices of columns to select.
    The default (`None`) is to select all columns.
* **Returns:**
  **predictions** *array-like or list of array-like*
  : If `test` is an array, it returns the array-like result of calling
    ‘estimator.method’ on `test`.
    Otherwise, if `test` is a list of arrays, it returns a list of array-like
    results of calling ‘estimator.method’ on each test set in `test`.

# generated/skfolio.utils.tools.fit_single_estimator.html.md

<a id="skfolio-utils-tools-fit-single-estimator"></a>

# skfolio.utils.tools.fit_single_estimator

<a id="skfolio.utils.tools.fit_single_estimator"></a>

### skfolio.utils.tools.fit_single_estimator(estimator, X, y, fit_params, indices=None, axis=0, method='fit')

Fit (or partial-fit) an estimator on a subset of the data.

* **Parameters:**
  **estimator** *estimator object implementing ‘fit’ and ‘predict’*
  : The object to use to fit the data.

  **X** *array-like of shape (n_observations, n_assets)*
  : The data to fit.

  **y** *array-like of shape (n_observations, n_targets), optional*
  : The target array if provided.

  **fit_params** *dict*
  : Parameters that will be passed to the estimator method.

  **indices** *ndarray, slice, optional*
  : Rows or columns to select from X, y, and fit_params.
    The default (`None`) is to select the entire data.

  **axis** *int, default=0*
  : The axis along which `X` will be sub-sampled. `axis=0` will select
    rows while `axis=1` will select columns.

  **method** *str, default=”fit”*
  : Estimator method to call (e.g. `"fit"` or `"partial_fit"`).
* **Returns:**
  **fitted_estimator** *estimator*
  : The fitted estimator.

# generated/skfolio.utils.tools.format_measure.html.md

<a id="skfolio-utils-tools-format-measure"></a>

# skfolio.utils.tools.format_measure

<a id="skfolio.utils.tools.format_measure"></a>

### skfolio.utils.tools.format_measure(x, percent=False)

Format a measure number into a user-friendly string.

* **Parameters:**
  **x** *float*
  : Number to format.

  **percent** *bool, default=False*
  : If this is set to True, the number is formatted in percentage.
* **Returns:**
  **formatted** *str*
  : Formatted string.

# generated/skfolio.utils.tools.get_feature_names.html.md

<a id="skfolio-utils-tools-get-feature-names"></a>

# skfolio.utils.tools.get_feature_names

<a id="skfolio.utils.tools.get_feature_names"></a>

### skfolio.utils.tools.get_feature_names(X)

Get feature names from X.

Support for other array containers should place its implementation here.

* **Parameters:**
  **X** *{ndarray, dataframe} of shape (n_samples, n_features)*
  : Array container to extract feature names.
    - pandas dataframe : The columns will be considered to be feature
      names. If the dataframe contains non-string feature names, `None` is
      returned.
    - All other array containers will return `None`.
* **Returns:**
  names: ndarray or None
  : Feature names of `X`. Unrecognized array containers will return `None`.

# generated/skfolio.utils.tools.half_life_to_decay_factor.html.md

<a id="skfolio-utils-tools-half-life-to-decay-factor"></a>

# skfolio.utils.tools.half_life_to_decay_factor

<a id="skfolio.utils.tools.half_life_to_decay_factor"></a>

### skfolio.utils.tools.half_life_to_decay_factor(half_life)

Convert half-life to exponential decay factor.

The decay factor ($\lambda$) determines how much weight is given to past
observations in exponentially weighted calculations. It is computed from the
half-life using:

$$
\lambda = 2^{-1/\text{half-life}}
$$

* **Parameters:**
  **half_life** *float*
  : Half-life in number of observations. This is the number of observations
    for the weight to decay to 50%. Must be positive.
* **Returns:**
  **decay_factor** *float*
  : The exponential decay factor ($\lambda$), satisfying
    $0 < \lambda < 1$.

### Examples

```pycon
>>> half_life_to_decay_factor(40)
0.9828...
```

# generated/skfolio.utils.tools.input_to_array.html.md

<a id="skfolio-utils-tools-input-to-array"></a>

# skfolio.utils.tools.input_to_array

<a id="skfolio.utils.tools.input_to_array"></a>

### skfolio.utils.tools.input_to_array(items, n_assets, fill_value, dim, assets_names, name, investable_mask=None)

Convert a collection of items (array-like or dictionary) into
a numpy array and verify its shape.

When `investable_mask` is provided, dictionary inputs are resolved against
the full `assets_names` and then subsetted, while array inputs sized to the
full universe are sliced down to the investable assets.  This allows callers
to pass user-facing parameters (keyed by asset name or sized for the full
universe) and transparently obtain arrays sized for the investable subset.

* **Parameters:**
  **items** *FloatArray | dict | list*
  : Items to verify and convert to array.

  **n_assets** *int*
  : Expected number of assets in the **output** array (i.e. the investable
    count when `investable_mask` is provided).

  **fill_value** *Any*
  : When `items` is a dictionary, elements that are not in `asset_names` are filled
    with `fill_value` in the converted array.

  **dim** *int*
  : Dimension of the final array.
    Possible values are `1` or `2`.

  **assets_names** *ndarray, optional*
  : Asset names used when `items` is a dictionary.  When `investable_mask`
    is provided, this must contain the **full-universe** names.

  **name** *str*
  : Name of the items used for error messages.

  **investable_mask** *ndarray of shape (n_full_assets,), optional*
  : Boolean mask selecting investable assets from the full universe.
    When provided, dictionary inputs are first resolved against the full
    universe then sliced, and array-like inputs sized to the full universe
    are sliced along the last axis.
* **Returns:**
  **values** *ndarray of shape (n_assets) for dim=1 or (n_groups, n_assets) for dim=2*
  : Converted array.

# generated/skfolio.utils.tools.optimal_rounding_decimals.html.md

<a id="skfolio-utils-tools-optimal-rounding-decimals"></a>

# skfolio.utils.tools.optimal_rounding_decimals

<a id="skfolio.utils.tools.optimal_rounding_decimals"></a>

### skfolio.utils.tools.optimal_rounding_decimals(x)

Return the optimal rounding decimal number for a user-friendly formatting.

* **Parameters:**
  **x** *float*
  : Number to round.
* **Returns:**
  **n** *int*
  : Rounding decimal number.

# generated/skfolio.utils.tools.safe_indexing.html.md

<a id="skfolio-utils-tools-safe-indexing"></a>

# skfolio.utils.tools.safe_indexing

<a id="skfolio.utils.tools.safe_indexing"></a>

### skfolio.utils.tools.safe_indexing(X, indices, axis=0)

Return rows, items or columns of X using indices.

* **Parameters:**
  **X** *array-like*
  : Data from which to sample rows.

  **indices** *array-like, slice, or None*
  : Indices, slice, or None. When `None`, the entire data is returned.
    When a `slice`, standard Python slicing is used (zero-copy for
    NumPy arrays and [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel)).

  **axis** *int, default=0*
  : The axis along which `X` will be sub-sampled. `axis=0` will select
    rows while `axis=1` will select columns.
* **Returns:**
  subset
  : Subset of X on axis 0.

# generated/skfolio.utils.tools.safe_split.html.md

<a id="skfolio-utils-tools-safe-split"></a>

# skfolio.utils.tools.safe_split

<a id="skfolio.utils.tools.safe_split"></a>

### skfolio.utils.tools.safe_split(X, y=None, indices=None, axis=0)

Create subset of dataset.

Slice X, y according to indices for cross-validation.

* **Parameters:**
  **X** *array-like*
  : Data to be indexed.

  **y** *array-like*
  : Data to be indexed.

  **indices** *ndarray of int, optional*
  : Rows or columns to select from X and y.
    The default (`None`) is to select the entire data.

  **axis** *int, default=0*
  : The axis along which `X` will be sub-sampled. `axis=0` will select
    rows while `axis=1` will select columns.
* **Returns:**
  **X_subset** *array-like*
  : Indexed data.

  **y_subset** *array-like*
  : Indexed targets.

# generated/skfolio.utils.tools.validate_input_list.html.md

<a id="skfolio-utils-tools-validate-input-list"></a>

# skfolio.utils.tools.validate_input_list

<a id="skfolio.utils.tools.validate_input_list"></a>

### skfolio.utils.tools.validate_input_list(items, n_assets, assets_names, name, raise_if_string_missing=True)

Convert a list of items (asset indices or asset names) into a list of
validated asset indices.

* **Parameters:**
  **items** *list[int | str]*
  : List of asset indices or asset names.

  **n_assets** *int*
  : Expected number of assets.
    Used for verification.

  **assets_names** *ndarray, optional*
  : Asset names used when `items` contain strings.

  **name** *str*
  : Name of the items used for error messages.

  **raise_if_string_missing** *bool, default=True*
  : If set to True, raises an error if an item string is missing from assets_names;
    otherwise, issue a User Warning.
* **Returns:**
  **values** *list[int]*
  : Converted and validated list.

# generated/skfolio.utils.validation.validate_asset_panel.html.md

<a id="skfolio-utils-validation-validate-asset-panel"></a>

# skfolio.utils.validation.validate_asset_panel

<a id="skfolio.utils.validation.validate_asset_panel"></a>

### skfolio.utils.validation.validate_asset_panel(\_estimator, /, asset_panel, required_fields=None, reserved_fields=None, finite_or_nan=None, finite_when_active=None, strictly_positive_or_nan=None, strictly_positive_when_active=None, non_negative_or_nan=None, reset=True, copy=False)

Validate an AssetPanel and set estimator metadata attributes.

This function validates that the panel contains required fields, doesn’t contain
reserved ones and sets standard metadata attributes on the estimator.

* **Parameters:**
  **\_estimator** *estimator instance*
  : The estimator on which to set validation attributes.

  **asset_panel** *AssetPanel or AssetPanelView*
  : AssetPanel. AssetPanel already validates that all fields have consistent shapes
    and consistent masks, allowing this validation to be lightweight.

  **required_fields** *list of str, optional*
  : Fields that must be present in the AssetPanel. If any are missing, a ValueError
    is raised.

  **reserved_fields** *list of str, optional*
  : Fields that must NOT be present in the AssetPanel. These are typically names the
    estimator will create internally. If any are found, a ValueError is raised.

  **finite_or_nan** *list of str, optional*
  : Fields whose values must be finite or NaN.

  **finite_when_active** *list of str, optional*
  : Fields whose values must be finite wherever `active_mask` is True. This is
    typically used for fields like “market_cap” that must be forward-filled for
    holidays before constructing the AssetPanel.

  **strictly_positive_or_nan** *list of str, optional*
  : Fields whose values must be strictly positive and finite, or NaN.

  **strictly_positive_when_active** *list of str, optional*
  : Fields whose values must be strictly positive and finite wherever
    `active_mask` is True.

  **non_negative_or_nan** *list of str, optional*
  : Fields whose values must be non-negative and finite, or NaN.

  **reset** *bool, default=True*
  : If True, sets metadata attributes on the estimator:
    - `asset_names_`: array of asset identifiers
    - `n_assets_`: number of assets
    <br/>
    If False, validates that existing attributes match the panel.

  **copy** *bool, default=False*
  : If True, returns a shallow copy of the panel (new dict containers with shared
    arrays). Use this when the estimator needs to add fields without mutating the
    user’s input.
* **Returns:**
  AssetPanel or AssetPanelView
  : The validated panel, or a shallow copy if `copy=True`.
* **Raises:**
  TypeError
  : If asset_panel is not an AssetPanel or AssetPanelView.

  ValueError
  : If required fields are missing, reserved fields are present, a
    field validation rule is violated or (when reset=False) panel doesn’t match
    stored metadata.

# generated/skfolio.utils.validation.validate_cross_sectional_data.html.md

<a id="skfolio-utils-validation-validate-cross-sectional-data"></a>

# skfolio.utils.validation.validate_cross_sectional_data

<a id="skfolio.utils.validation.validate_cross_sectional_data"></a>

### skfolio.utils.validation.validate_cross_sectional_data(\_estimator, /, X, y='no_validation', cs_weights=None, \*, reset=True, copy=False)

Validate cross-sectional data.

This helper follows the design of scikit-learn’s `validate_data` and is specialized
for cross-sectional arrays with shape `(n_observations, n_assets, n_features)`.
The target `y` and the optional cross-sectional weights must have shape
`(n_observations, n_assets)`.

Missing values encoded as NaN are allowed in `X` and `y`. Infinite values
are rejected. The weights must be finite and non-negative.

* **Parameters:**
  **\_estimator** *estimator instance*
  : Estimator on which `n_features_in_` is set or checked.

  **X** *array-like of shape (n_observations, n_assets, n_features)*
  : Input feature tensor.

  **y** *array-like of shape (n_observations, n_assets), None, or “no_validation”, default=”no_validation”*
  : Target values.
    - `"no_validation"`: skip target validation and return only the validated `X`.
      This is the default and is used by methods like `predict` that only need `X`.
    - `None`: skip target validation, but check the estimator’s
      `target_tags.required` tag. If the tag is `True`, a `ValueError` is raised.
    - array-like: validate as a numeric 2D array.

  **cs_weights** *array-like of shape (n_observations, n_assets), optional*
  : Cross-sectional weights for each (observation, asset) pair.
    - `None` with `y` provided: return a matrix of ones.
    - `None` with `y` skipped: weights are not validated.
    - array-like: validate as a finite, non-negative 2D array.

  **reset** *bool, default=True*
  : If `True`, set `n_features_in_` on the estimator. If `False`, check consistency
    with the stored number of features.

  **copy** *bool, default=False*
  : If `True`, force a copy of the validated arrays.
* **Returns:**
  **X_validated** *ndarray of shape (n_observations, n_assets, n_features)*
  : Validated feature tensor, returned alone when `y` is `"no_validation"` or `None`.

  **X_validated, y_validated, cs_weights_validated** *tuple of ndarrays*
  : Validated `X`, `y`, and weights, returned when `y` is an array-like.
* **Raises:**
  ValueError
  : If `X` is not a 3D array.

  ValueError
  : If `y` is `None` and the estimator’s `target_tags.required` tag is `True`.

  ValueError
  : If `y` is provided but its shape does not match the first two dimensions of `X`.

  ValueError
  : If `cs_weights` is provided without `y`.

  ValueError
  : If `cs_weights` contains negative or non-finite values.

  ValueError
  : If `cs_weights` shape does not match the first two dimensions of `X`.

  ValueError
  : If `reset` is `False` and the number of features in `X` differs from
    `n_features_in_`.

# user_guide/backtesting_and_evaluation.html.md

<a id="backtesting-and-evaluation"></a>

<a id="id1"></a>

# Backtesting and Evaluation

In `skfolio`, portfolio construction methods produce **target weights** that specify
the allocation selected at each rebalancing date. Evaluating these allocations over
subsequent observations involves two separate modelling choices:

* whether to compute portfolio returns at fixed target weights throughout each
  holding period or at weights that evolve with asset returns between rebalances
* whether to sum the resulting portfolio returns arithmetically or compound them
  into a wealth index

The choice of weights determines the portfolio return series, while the accumulation
method determines cumulative returns and drawdown measures. The same target
allocations can therefore produce different performance statistics under these
conventions. The appropriate settings depend on the evaluation objective:

* **Allocation skill (ex-ante).** Estimate the expected return and risk attributable
  to the target allocations selected by the portfolio construction process. The aim
  is to evaluate the allocation decisions themselves, independently of subsequent
  changes in weights caused by relative asset returns.
* **Expected performance of the implemented strategy.** Estimate the expected
  return and risk of rebalancing to the target weights at scheduled dates and
  allowing the resulting holdings to evolve with asset returns between those
  rebalances. Turnover and transaction costs are computed relative to the previous
  period’s ending weights, including drift, rather than its target weights.
* **Relative strategy performance.** Estimate the difference in expected
  performance between portfolio strategies. The appropriate implementation
  convention depends on whether the comparison concerns the target allocation
  decisions or the strategies as they would be implemented between rebalances.
  When strategies are evaluated on the same out-of-sample dates, common biases may
  cancel and positively correlated sampling errors can reduce the uncertainty of
  the difference.
* **Historical realization (ex-post).** Reconstruct the holdings, trades, wealth
  and drawdowns that would have occurred along the observed return path under the
  stated implementation assumptions.

The first three objectives involve estimating expected performance from
out-of-sample returns. The observed history is one finite realization of the process
generating returns, so these estimates may be biased and are subject to sampling
uncertainty.

In an ex-post evaluation, holdings, trades, wealth and drawdowns are reconstructed
along the observed return path under the stated implementation assumptions. A more
accurate reconstruction does not necessarily improve estimates of expected
performance on another sample of returns.

In `skfolio` two parameters control these modelling choices:

* `weight_drift` determines the weights used to compute each observation’s return.
  With `False`, returns are computed at the **target weights (no drift)**, which
  remain constant within each holding period. With `True`, each holding period
  starts at the target weights, but the weights used for subsequent observations
  evolve with asset returns until the next scheduled rebalance. Returns are therefore
  computed from **drifted weights**.
* `compounded` determines how the resulting portfolio returns are accumulated. With
  `False`, cumulative returns are an arithmetic sum. With `True`, they form a
  compounded wealth index. This setting affects drawdown measures, but leaves the
  underlying return series unchanged.

Both default to `False`. The default therefore evaluates **allocation skill (ex-ante)**
at target weights, consistent with the optimizer’s linear portfolio return definition,
and accumulates returns arithmetically.

<a id="choosing-the-settings"></a>

## Choosing the settings

`weight_drift` and `compounded` are independent, and all four combinations are valid.
The table gives suggested settings for each evaluation objective.

#### Suggested starting points

| Objective                                                         | `weight_drift`                                               | `compounded`   |
|-------------------------------------------------------------------|--------------------------------------------------------------|----------------|
| Allocation skill (ex-ante), before transaction costs              | `False`: target weights (no drift)                           | `False`        |
| Expected performance of the implemented strategy                  | `True`: drifted weights                                      | `False`        |
| Relative strategy performance                                     | `False`: target weights (no drift). `True`: drifted weights. | `False`        |
| Historical realization (ex-post): wealth and percentage drawdowns | `True`: drifted weights                                      | `True`         |

`compounded` changes cumulative returns, drawdown measures and ratios based on
drawdowns. Measures computed from individual returns, such as mean return, variance,
VaR, CVaR, and the Sharpe and Sortino ratios, are unchanged, as are their sampling
variances.

`weight_drift` changes the underlying returns and can change both the bias and
sampling variance of performance estimates for the chosen evaluation objective.

Reconstructing holdings and trades more accurately does not necessarily improve
estimates of expected performance. An evaluation at target weights can have lower
mean squared error if its reduction in sampling variance outweighs its squared bias.
See [Estimating expected return](https://skfolio.org/user_guide/backtesting_and_evaluation.html.md#weight-drift-mse).

The figure below compares the effects of weight drift and compounding on two
illustrative ten-year paths from the same asset return model. The simulations use
equal target weights and annual rebalancing, with identical target allocations
across settings. The paths were selected to illustrate the differences. The
observed gaps do not estimate the typical effect of drift or compounding.

<figure class="backtesting-figure">
  <img src="../_static/backtesting/plots/weight_drift_and_compounding.webp"
       alt="Two simulated portfolio paths evaluated with target weights, drifted weights, and drifted weights with compounding"
       width="1100" height="1050"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

<a id="weight-drift-evaluation"></a>

<a id="how-weight-drift-changes-returns"></a>

## How weight drift changes returns

Let $r_t$ be the vector of asset returns during observation $t$, and
$w_k$ the target weights set at rebalancing date $t_k$. The holding
period runs from $t_k$ to just before $t_{k+1}$. The equations in this
section describe returns before transaction costs and fees.

<a id="target-weights-no-drift"></a>

### Target weights (no drift)

With `weight_drift=False`, every observation within the holding period uses the same
target weights:

$$
r^{target}_t = w_k \cdot r_t,
\qquad t_k \le t < t_{k+1}.
$$

It is consistent with the optimizer’s linear portfolio definition and is the default
convention for evaluating allocation skill: the expected return and risk of the
target allocations are assessed independently of subsequent holdings drift.
Economically, it is equivalent to restoring the target weights after every
observation without charging for those within-period trades.

<a id="drifted-weights"></a>

### Drifted weights

With `weight_drift=True`, let $u_t$ be the weights held at the start of
observation $t$. Each position grows with its asset’s return:

$$
r^{drifted}_t = u_t \cdot r_t,
\qquad
u_{t+1} = \frac{u_t \circ (1 + r_t)}{1 + u_t \cdot r_t},
\qquad u_{t_k} = w_k,
$$

where $\circ$ denotes element-wise multiplication. The weights reset to
the next targets at $t_{k+1}$.

For example, starting with 50% in each of two assets, if the first asset gains 10%
and the second is unchanged, the portfolio gains 5%. The next observation then starts
with weights of 52.38% and 47.62% under `weight_drift=True`, whereas an evaluation
at target weights continues to use 50% and 50% again.

If the first asset outperforms again, the portfolio with holdings drift has a higher
return than the target-weight portfolio because it now has greater exposure to that
asset. If relative performance reverses, it has a lower return. Momentum and
reversal can therefore affect the performance of the strategy under the two
modelling conventions.

The drift equation is self-financing, with changes in weights arising from asset
returns rather than from external cash entering the portfolio. A portfolio that is
rebalanced to its target weights can also be self-financing, since purchases can be
funded by sales of other assets. The conventions differ in whether target weights
are restored within the holding period.

`Portfolio` raises an error when wealth becomes non-positive because the weights for
the next observation are then undefined. This can occur, for example, in leveraged
or short portfolios following sufficiently large adverse returns.

<a id="turnover-and-transaction-costs"></a>

## Turnover and transaction costs

At each scheduled rebalancing, turnover is computed from the difference between the
new target weights and either the previous target weights or the drifted ending
weights, depending on the evaluation convention.

Let $\tilde w_k$ denote the weights held at the end of holding period
$k$. The two conventions give

$$
\text{target turnover} = \|w_{k+1}-w_k\|_1,
\qquad
\text{executed turnover} = \|w_{k+1}-\tilde w_k\|_1.
$$

With `weight_drift=False`, `previous_weights` contains the previous portfolio’s
target weights. **Target turnover** measures the change between successive target
allocations.

With `weight_drift=True`, `previous_weights` contains the weights held at the end of
the previous holding period. **Executed turnover** measures the trades required to
move from these holdings to the new target allocation.

Drift reduces turnover when relative asset returns move the existing holdings toward
the next target and increases it when they move the holdings away from that target.
This can reduce trading for momentum strategies and increase it for reversal
strategies.

For any given pair of targets, the triangle inequality gives

$$
|\text{executed turnover} - \text{target turnover}|
\le \|\tilde w_k-w_k\|_1.
$$

With a sequential splitter, `cross_val_predict` passes each successful portfolio’s
`ending_weights` as `previous_weights` to the next fit when previous holdings are
needed. With drift disabled, `ending_weights` contains the target weights. With
drift enabled, it contains the weights held at the end of the period. Transaction
costs and turnover constraints are computed from these previous weights. Enabling
drift therefore makes the folds run sequentially and propagates ending weights even
without costs or a turnover constraint. When fits are independent, previous weights
are assigned to the predicted portfolios afterward for turnover and cost calculations.

When asset selection changes between rebalances, turnover and transaction costs are
calculated assuming full liquidation of positions in assets absent from the new
universe. In a pipeline, `set_output(transform="pandas")` preserves the asset names
needed to match previous holdings to the new selection. For assets absent from `X`,
`transaction_costs` must be a single rate applied to all assets or a dictionary
keyed by asset name.

For a direct `predict` call, transaction costs use the supplied `previous_weights`
under either drift setting.

The following example rebalances every five observations, applies a one-off cost
rate of 10 basis points on traded notional, and limits turnover in each asset to
30% of portfolio value at each rebalance:

```python
from skfolio.optimization import MeanRisk

holding_period = 5
tc_rate = 0.001
model = MeanRisk(
    transaction_costs=tc_rate / holding_period,
    max_turnover=0.3,
)
pred = cross_val_predict(
    model,
    X,
    cv=WalkForward(train_size=252, test_size=holding_period),
    portfolio_params={"weight_drift": True, "compounded": False},
    entry_rebalancing_params={"max_turnover": None},
)
```

`max_turnover=0.3` is a per-asset constraint. Total portfolio turnover can exceed
30%. `entry_rebalancing_params` removes this constraint for the initial trade from
cash. The constraint applies from the second rebalance onward. This limit does not
apply to the assumed liquidation of positions outside the investment universe.

With transaction costs or turnover constraints, the next target allocation can also
differ depending on whether the optimization uses the previous target weights or the
portfolio weights at the end of the holding period. Evaluating the same sequence of
targets under both settings isolates the effect of holdings drift on returns and
turnover.

<a id="transaction-cost-timing"></a>

<a id="transaction-cost-convention"></a>

### Transaction cost convention

The optimizer expresses expected returns per observation, while transaction costs are
paid once when a rebalance occurs. To express the two quantities on the same basis,
a one-off transaction cost is divided by the expected holding period to obtain a cost
per observation. Portfolio evaluation uses the same convention.
See [periodicity convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention) for the rationale and
conversion examples.

For a one-off transaction cost rate $c$ and an intended holding period of
$n$ observations, set `transaction_costs` to $c/n$, as in the example
above.

If turnover is $q_k$, each observation in that period is reduced by
$cq_k/n$. Over exactly $n$ observations, these deductions sum to
$cq_k$ in arithmetic-return units.

Charging the full transaction cost on the trade date would produce a different
observation-level return series and, after compounding, a different wealth path. It
would also change tail-risk and drawdown measures.

Both weight conventions use the same transaction-cost convention. If the actual
holding period contains $m$ observations, a fixed input $c/n$ deducts a
total of $mcq_k/n$ in arithmetic-return units. This matters for calendar-based
rebalancing and incomplete periods, where the number of observations varies.

`ending_weights` are the portfolio weights at the end of the holding period. With
`weight_drift=False`, they equal the target weights. With `weight_drift=True`, they
reflect the effect of asset returns through the final observation. They are calculated
before transaction costs and management fees because those costs reduce reported
portfolio returns but are not deducted from a modelled cash balance or individual
position.

Management fees remain based on the target weights selected for the holding period
rather than on subsequent changes in weights caused by asset returns.

<a id="return-aggregation-and-compounding"></a>

## Return aggregation and compounding

For a given portfolio return series $r^{ptf}_t$, arithmetic accumulation is

$$
A_T = \sum_{t=1}^T r^{ptf}_t.
$$

Compounding produces a wealth index, expressed per unit of starting capital:

$$
W_T = \prod_{t=1}^T(1+r^{ptf}_t).
$$

`skfolio` reports the compounded series as this wealth index. Its total return is
$W_T-1$.

Use `compounded=True` for measures based on compounded wealth, including compounded
total return and percentage drawdown. This applies to both out-of-sample estimation
and historical reconstruction.

Changing `compounded` does not change the optimizer’s objective or the underlying
observation-level portfolio returns.

See [Data Preparation](https://skfolio.org/user_guide/data_preparation.html.md#data-preparation) for the discussion of simple and logarithmic returns.

For fixed targets within one holding period, before costs and fees, compounding
gives

$$
W^{target} = \prod_t(1+w_k\cdot r_t),
\qquad
W^{drifted} = \sum_i w_{k,i}\prod_t(1+r_{i,t})
             + 1-\sum_i w_{k,i}.
$$

The first expression describes restoring the target weights after every observation.
The second describes implementing the target allocation and holding the resulting
positions until the next scheduled rebalance. The final term is the implicit
zero-return cash position when the explicit asset weights do not sum to one.

Changing the order of asset returns within this holding period leaves both terminal
wealth values unchanged, provided wealth stays positive. At target weights, it also
leaves mean return and variance unchanged. With holdings drift, the portfolio
return series can change because holdings depend on earlier returns. Intermediate
wealth and drawdowns depend on return order in both settings.

<a id="configuring-evaluation"></a>

<a id="configuring-an-evaluation"></a>

## Configuring an evaluation

For a direct call to an optimizer’s `predict`, set the options in the optimizer’s
`portfolio_params`. For [`cross_val_predict`](https://skfolio.org/generated/skfolio.model_selection.cross_val_predict.html.md#skfolio.model_selection.cross_val_predict) and
[`online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict), pass them in the function’s
`portfolio_params`.

The following example applies three combinations of the settings to the same
historical data, with rebalancing every 21 observations. `X` contains asset returns
in decimal form, ordered by date, with one column per asset.

```python
from skfolio.datasets import load_sp500_dataset
from skfolio.model_selection import WalkForward, cross_val_predict
from skfolio.optimization import EqualWeighted
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)

model = EqualWeighted()
cv = WalkForward(train_size=252, test_size=21)

target_evaluation = cross_val_predict(model, X, cv=cv)

drifted = cross_val_predict(
    model, X, cv=cv, portfolio_params={"weight_drift": True, "compounded": False}
)

compounded_wealth = cross_val_predict(
    model, X, cv=cv, portfolio_params={"weight_drift": True, "compounded": True}
)
```

`target_evaluation` evaluates the target weights and accumulates the resulting
returns arithmetically.
`drifted` starts each holding period at the same target weights but allows the
holdings to evolve with asset returns until the next rebalance. Its returns are also
accumulated arithmetically.
`compounded_wealth` uses the same holdings-based return construction as `drifted`
and compounds those returns into a wealth index.

The example illustrates the settings on historical data. It does not reproduce the
simulated figure. With daily equity data, 21 observations approximate a month. Use
calendar-based splits when rebalancing must occur on specific dates.

Each walk-forward call returns a [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio)
containing one [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) per test period.
`weight_drift` applies to each child portfolio. `compounded` applies to both
the children and the resulting `MultiPeriodPortfolio`. Function-level values
override the optimizer’s `portfolio_params`. Omitted values are inherited. See
[Cross-Validation Prediction](https://skfolio.org/user_guide/model_selection.html.md#cross-validation) for the complete routing rules.

`compounded` can also be changed after construction. To compound the existing
`drifted` return series without repeating the evaluation, use:

```python
drifted.compounded = True
drifted.plot_cumulative_returns()
```

This changes the aggregate object’s cumulative returns and drawdown measures. Each
child portfolio has its own `compounded` setting. `weight_drift` is fixed at
construction because changing it would change the portfolio return series.

<a id="holding-periods-and-validation"></a>

### Holding periods and validation

A direct `predict(X)` call treats all of `X` as one holding period. With drift
enabled, the portfolio starts at its target weights and positions are held throughout
that window. In a walk-forward evaluation, each test period starts at its predicted
target weights. The length of the test period therefore sets the interval between
scheduled rebalances.

Different validation schemes can represent different types of evaluation path:

* [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) produces one sequential path.
* [`online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict) builds a path from a single
  stateful estimator updated with `partial_fit`. See [Online Learning](https://skfolio.org/user_guide/online_learning.html.md#online-learning).
* [`MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV) runs walk-forward
  evaluations on randomly selected asset subsets and, optionally, contiguous time
  windows.
* [`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) evaluates combinations of
  test blocks and can train on observations later than a given test block. Its
  reconstructed paths therefore do not represent strictly forward historical
  simulations.

See [Cross-Validation Prediction](https://skfolio.org/user_guide/model_selection.html.md#cross-validation) for purging, embargoing and supported splitters.

<a id="weight-drift-mse"></a>

<a id="estimating-expected-return"></a>

## Estimating expected return

The sample means of the portfolio returns, computed with and without weight drift,
are two estimators of expected return. For the same target allocations, the bias
introduced by the choice of weights depends on the evaluation objective.

Before transaction costs, the return contribution from drift at observation
$t$ is

$$
d_t = r^{drifted}_t-r^{target}_t = (u_t-w_k)\cdot r_t.
$$

Its expected contribution to the sample mean over $T$ observations is
$\bar d = \frac{1}{T}\sum_{t=1}^T\mathbb{E}[d_t]$.
The expected transaction cost difference per observation, $b$, is the
expected cost of executed turnover minus the expected cost of target turnover.

* **Allocation skill (ex-ante).** Before transaction costs, `weight_drift=False`
  evaluates the target allocations directly and introduces no bias from subsequent
  holdings drift. `weight_drift=True` introduces drift contribution
  $\bar d$.
* **Expected performance of the implemented strategy.** For expected net return,
  `weight_drift=True` includes both holdings drift and the transaction costs
  associated with executed turnover. `weight_drift=False` introduces bias
  $b-\bar d$.

The expected gross-return difference between the two settings can be negligible
with frequent rebalancing. In two illustrative simulations, it is about
**0.2 bp p.a.** for a diversified 50-asset portfolio rebalanced weekly and about
**2% p.a.** for a concentrated four-asset high-volatility portfolio rebalanced
quarterly.

These are stylized simulations, not empirical estimates for particular asset
classes. They use equal target weights and geometric Brownian asset prices. The
[calculation appendix](https://skfolio.org/user_guide/backtesting_and_evaluation.html.md#backtesting-calculation-details) gives the assumptions
and formulas.

The sample means also vary from one sample to another. Their sampling variances
measure this variability. In the same examples, drift increases the sampling
variance of the estimated gross mean by **less than 0.01%** for the diversified
portfolio and about **3%** for the concentrated high-volatility portfolio. Serial
correlation also affects sampling variance. A long-run variance estimate <sup>[1](#id3)</sup>
accounts for dependence between observations.

Mean squared error (MSE) combines squared bias with sampling variance.
$V_{\mathrm{target}}$ and $V_{\mathrm{drifted}}$ denote the sampling
variances of the two estimated net means. When the drifted mean is unbiased for
the implemented strategy’s expected net return under the return model, the MSEs
are

$$
\operatorname{MSE}_{\mathrm{target}}=(b-\bar d)^2+V_{\mathrm{target}},
\qquad
\operatorname{MSE}_{\mathrm{drifted}}=V_{\mathrm{drifted}}.
$$

The estimate at target weights has lower MSE when its reduction in sampling variance
exceeds its squared bias. Including holdings drift can also reduce sampling variance,
in which case the drifted estimate has lower MSE.

For the concentrated high-volatility example, a portfolio volatility of 66% p.a.
gives a standard error of about **30%** for the annualized target-weight mean over
five years ($66\%/\sqrt{5}$). When estimating the implemented strategy’s expected
gross return, its squared bias is only about **0.45%** of its sampling variance.
Its MSE is therefore close to that of the drifted estimate. With longer samples,
sampling variance decreases while a persistent bias remains.

<a id="backtesting-calculation-details"></a>

<a id="appendix-calculation-details"></a>

## Appendix: Calculation details

The illustrative examples assume $N$ equally weighted assets, rebalanced
every $n$ observations, with $A$ observations p.a. Asset prices follow
geometric Brownian motions with equal exposure to a common market factor and
independent asset-specific shocks. Returns are independent across observations,
and transaction costs are excluded.

Let $\sigma_p$ be the annual portfolio volatility at target weights,
$\sigma_\epsilon$ the annual asset-specific volatility, and $s$ the
standard deviation of annualized expected arithmetic asset returns.
With $h=(n-1)/A$, the annualized expected gross drift contribution
$\bar d_{\mathrm{ann}}$ and relative change in sampling variance
$\gamma$ are, to leading order,

$$
\bar d_{\mathrm{ann}} \approx \frac{h s^2}{2},
\qquad
\gamma \approx
\frac{h(N-1)\sigma_\epsilon^4}{2N^2\sigma_p^2}.
$$

The variance change $\gamma$ is measured relative to the sampling variance
of the estimated gross mean at target weights.

* **Diversified weekly-rebalancing example.** $N=50$, $n=5$,
  $A=252$, $\sigma_p=15\%$, $\sigma_\epsilon=21\%$
  and $s=5\%$.
* **Concentrated high-volatility quarterly-rebalancing example.**
  $N=4$, $n=91$, $A=365$, $\sigma_p=66\%$,
  $\sigma_\epsilon=87\%$ and $s=40\%$.

### References

* <a id='id3'>**[1]**</a> Newey, W. K. and West, K. D. (1987). A Simple, Positive Semi-Definite, Heteroskedasticity and Autocorrelation Consistent Covariance Matrix. *Econometrica*, 55(3), 703-708.

# user_guide/cluster.html.md

<a id="cluster"></a>

<a id="hierarchical-clustering"></a>

<a id="clustering-estimators"></a>

# Clustering Estimators

The `skfolio.cluster` module complements `sklearn.cluster` with additional clustering
estimators including the [`HierarchicalClustering`](https://skfolio.org/generated/skfolio.cluster.HierarchicalClustering.html.md#skfolio.cluster.HierarchicalClustering) that forms hierarchical
clusters from a distance matrix. It is used in the following portfolio optimizations:

> * [`HierarchicalRiskParity`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity)
> * [`HierarchicalEqualRiskContribution`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution)
> * [`NestedClustersOptimization`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization)

**Example:**

```python
from skfolio.cluster import HierarchicalClustering
from skfolio.datasets import load_sp500_dataset
from skfolio.distance import PearsonDistance
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)

distance_estimator = PearsonDistance()
distance_estimator.fit(X)
distance = distance_estimator.distance_

model = HierarchicalClustering()
model.fit(distance)
print(model.linkage_matrix_)
```

# user_guide/covariance.html.md

<a id="covariance-estimator"></a>

<a id="id1"></a>

# Covariance Estimator

A [covariance estimator](https://skfolio.org/api.html.md#covariance-ref) estimates the covariance matrix of the
assets.

It follows the same API as scikit-learn’s `estimator`: the `fit` method takes `X` as the
assets returns and stores the covariance in its `covariance_` attribute.

`X` can be any array-like structure (numpy array, pandas DataFrame, etc.)

`covariance_` is expressed in the periodicity of `X` (daily returns give a daily
covariance) and is consumed as is by the optimizers, without annualization (see
[Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention)).

Available estimators are:
: * [`EmpiricalCovariance`](https://skfolio.org/generated/skfolio.moments.EmpiricalCovariance.html.md#skfolio.moments.EmpiricalCovariance)
  * [`EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance)
  * [`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance)
  * [`GerberCovariance`](https://skfolio.org/generated/skfolio.moments.GerberCovariance.html.md#skfolio.moments.GerberCovariance)
  * [`DenoiseCovariance`](https://skfolio.org/generated/skfolio.moments.DenoiseCovariance.html.md#skfolio.moments.DenoiseCovariance)
  * [`DetoneCovariance`](https://skfolio.org/generated/skfolio.moments.DetoneCovariance.html.md#skfolio.moments.DetoneCovariance)
  * [`LedoitWolf`](https://skfolio.org/generated/skfolio.moments.LedoitWolf.html.md#skfolio.moments.LedoitWolf)
  * [`OAS`](https://skfolio.org/generated/skfolio.moments.OAS.html.md#skfolio.moments.OAS)
  * [`ShrunkCovariance`](https://skfolio.org/generated/skfolio.moments.ShrunkCovariance.html.md#skfolio.moments.ShrunkCovariance)
  * [`GraphicalLassoCV`](https://skfolio.org/generated/skfolio.moments.GraphicalLassoCV.html.md#skfolio.moments.GraphicalLassoCV)
  * [`ImpliedCovariance`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance)

For online learning and streaming workflows, [`EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance) and
[`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance) support incremental updates with
`partial_fit`. They also support NaN-aware updates with `active_mask`, which
helps distinguish assets that belong to the universe but have missing returns,
(e.g. holidays) or assets outside the universe (e.g. during pre-listing or
post-delisting periods).
See [Online Learning](https://skfolio.org/user_guide/online_learning.html.md#online-learning) for the full online workflow, including covariance
forecast evaluation and online hyper-parameter tuning.
See [Missing Data and Changing Universes](https://skfolio.org/user_guide/data_representation.html.md#missing-data) for the full convention
on NaNs, universe membership, estimator warmup and investability.

**Example:**

```python
from skfolio.datasets import load_sp500_dataset
from skfolio.moments import EmpiricalCovariance
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)

model = EmpiricalCovariance()
model.fit(X)
print(model.covariance_)
```

# user_guide/cross_sectional_transformers.html.md

<a id="cross-sectional-transformers"></a>

<a id="id1"></a>

# Cross-Sectional Transformers

A [Cross-Sectional Transformer](https://skfolio.org/api.html.md#preprocessing-ref) normalizes each value
within an observation’s cross-section using only values from that same
cross-section, i.e. row by row across assets.

All transformers follow the scikit-learn API and accept any array-like input
(numpy array, pandas DataFrame, etc.). They are stateless: `fit` only
validates, and `transform` returns the normalized array. NaNs are treated as
missing values, ignored when computing cross-sectional statistics, and
preserved in the output.

Available transformers:
: * [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler): cross-sectional z-score, optionally computed
    within groups (e.g. sectors).
  * [`CSPercentileRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler): cross-sectional percentile rank in
    $(0, 1)$.
  * [`CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler): cross-sectional rank gaussianization via
    the inverse standard normal CDF $\Phi^{-1}$.
  * [`CSWinsorizer`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer): cross-sectional clipping at low and high
    percentiles.
  * [`CSTanhShrinker`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker): smooth shrinkage of extreme values toward the
    cross-sectional center, preserving the original scale.

<a id="shared-arguments"></a>

## Shared arguments

`cs_weights`
: Cross-sectional weights as a non-negative array of shape
  `(n_observations, n_assets)`. Assets with `cs_weights > 0` define the
  *estimation universe* used to compute the cross-sectional statistics,
  while assets outside still receive a transformed value relative to it.
  [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler) and [`CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler) also use
  `cs_weights` to weight the cross-sectional mean used for centering.

`cs_groups`
: Cross-sectional groups as an integer array of shape
  `(n_observations, n_assets)` with labels `>= -1`. Statistics are then
  computed within each group rather than over the full cross-section. Use
  `-1` to mark unclassified assets. Such assets, together with groups
  smaller than `min_group_size`, fall back to the global cross-section.
  Useful for keeping exposures neutral within sectors or countries.
  Supported by [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler), [`CSPercentileRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler)
  and [`CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler).

<a id="choosing-a-transformer"></a>

## Choosing a transformer

| Transformer                                                                                                          | Output           | Outlier handling   | `cs_groups`   | `cs_weights`                 |
|----------------------------------------------------------------------------------------------------------------------|------------------|--------------------|---------------|------------------------------|
| [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler)             | Z-scores         | None               | Yes           | Universe + weighted mean     |
| [`CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler)     | Gaussian scores  | Rank-based         | Yes           | Universe + weighted recenter |
| [`CSPercentileRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler) | Percentile ranks | Rank-based         | Yes           | Universe mask only           |
| [`CSTanhShrinker`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker)                 | Original scale   | Smooth tails       | No            | Universe mask only           |
| [`CSWinsorizer`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer)                     | Original scale   | Hard clip          | No            | Universe mask only           |

Across all transformers, `cs_weights > 0` picks the assets that enter the *estimation universe*. Ranks,
medians, MAD, percentiles and standard deviations are always equal-weighted on that set. Only the
cross-sectional mean used for centering depends on the magnitude of the weights: [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler)
centers `X` by its weighted mean (*Universe + weighted mean*), and [`CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler) recenters
the Gaussianized scores by their weighted mean (*Universe + weighted recenter*).

<a id="example"></a>

## Example

The example below uses [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler) to illustrate the common
cross-sectional API, including NaN preservation.

```python
import numpy as np

from skfolio.preprocessing import CSStandardScaler

X = np.array([[1.0, np.nan, 3.0, 4.0],
              [4.0, 3.0, 2.0, 1.0],
              [10.0, 20.0, np.nan, 40.0]])

transformer = CSStandardScaler()
transformer.fit_transform(X)
# array([[-1.09108945,         nan,  0.21821789,  0.87287156],
#        [ 1.161895  ,  0.38729833, -0.38729833, -1.161895  ],
#        [-0.87287156, -0.21821789,         nan,  1.09108945]])
```

Here `cs_weights` defines a custom estimation universe and weighted mean, while
`cs_groups` applies the scaling within groups first. `min_group_size=2` is
required because these are two-asset groups (the default is 8); when a group’s
estimation universe shrinks below this threshold (e.g. due to NaN or zero
weights), it falls back to the global cross-section:

```python
cs_weights = np.array([[3.0, 0.0, 1.0, 2.0],
                       [4.0, 0.0, 2.0, 3.0],
                       [2.0, 3.0, 0.0, 5.0]])
cs_groups = np.array([[0, 0, 1, 1],
                      [0, 0, 1, 1],
                      [0, 0, 1, 1]])

transformer = CSStandardScaler(min_group_size=2)
transformer.fit_transform(X, cs_weights=cs_weights, cs_groups=cs_groups)
# array([[-0.55454325,         nan, -0.62182063,  1.1427252 ],
#        [ 0.62254586, -0.15324206,  0.5035012 , -1.16572861],
#        [-1.33736075,  0.20821245,         nan,  0.41001683]])
```

# user_guide/data_preparation.html.md

<a id="data-preparation"></a>

<a id="id1"></a>

# Data Preparation

Most `fit` methods of `skfolio` estimators take the assets returns as input `X`.
Therefore, the choice of methodology to convert prices to returns is left to the user.
For datasets with missing returns or a changing asset universe, see
[Missing Data and Changing Universes](https://skfolio.org/user_guide/data_representation.html.md#missing-data).

There are two different notions of return:

<a id="linear-return"></a>

## Linear return

Linear return (or simple return) is defined as:

$$
R^{Lin}_{t} = \frac{S_{t}}{S_{t-1}} - 1

$$

**Linear returns aggregate across securities**, meaning that the linear return
of a portfolio is the sum of the weighted linear returns of its components:

$$
R^{Lin}_{t} = \sum_{i=1}^{N} w_{i} \times  R^{Lin}_{i,t}

$$

This property is needed to properly compute portfolio return and risk <sup>[1](#id10)</sup>.
However, linear returns cannot be aggregated across time.

<a id="logarithmic-return"></a>

## Logarithmic return

Logarithmic return (or continuously compounded return) is defined as:

$$
R^{Log}_{t} = ln\Biggl(\frac{S_{t}}{S_{t-1}}\Biggr)

$$

**Logarithmic returns aggregate across time**, meaning that the logarithmic return over
k periods is the sum of all single-period logarithmic returns:

$$
R^{Log}_{t..k} = ln\Biggl(\frac{S_{t+k}}{S_{t}}\Biggr) = \sum_{j=1}^{k} ln\Biggl(\frac{S_{t+j}}{S_{t+j-1}}\Biggr)= \sum_{j=1}^{k-1} R^{Log}_{t+j}

$$

Given this property, it is easy to scale logarithmic return from one time period to another.
However, logarithmic return cannot be aggregated across securities:

$$
R^{Log}_{t} = ln\Biggl(\frac{S_{t}}{S_{t-1}}\Biggr) = ln\Biggl(1+\sum_{i=1}^{N} w_{i} \times  R^{Lin}_{i,t}\Biggr)

$$

<a id="pitfall-in-portfolio-optimization"></a>

## Pitfall in Portfolio Optimization

Given the similarities of linear and logarithmic returns in the short run, they are
sometimes used interchangeably.
It is not uncommon to witness the following steps <sup>[2](#id11)</sup>, <sup>[3](#id12)</sup>, <sup>[4](#id13)</sup>:

1. Take the daily prices $S_{t}, S_{t+1}, ...,$ for all the n securities
2. Transform the daily prices to daily logarithmic returns
3. Estimate the expected returns vector $\mu$ and covariance matrix $\Sigma$ from the daily logarithmic returns
4. Determine the investment horizon, for example k = 252 days
5. Project the expected returns and covariance to the horizon using the square-root rule: $\mu_{k} ≡ k \times \mu$ and $\Sigma_{k} ≡ k \times \Sigma$
6. Compute the mean-variance efficient frontier $\max_{w} \Biggl\{ w^T \mu - \lambda \times w^T \Sigma w \Biggr\}$

The above approach is incorrect. First, the square-root rule in (5) only applies under
the assumption that the logarithmic returns are invariants (they behave identically and
independently across time). It is approximately true for stocks; long-term dependence
requires additional care in optimization <sup>[5](#id14)</sup>. It is not true for bonds nor most
derivatives like options.
Secondly, even for stocks, the optimization (6) is ill-posed: $w^T \mu$
is not the expected return of the portfolio over the horizon and $w^T \Sigma w$
is not its variance.
These would lead to suboptimal allocations and the efficient frontier would not depend on
the investment horizon.

<a id="the-correct-approach"></a>

## The correct approach

The correct general approach is the following:

1. Find the market invariants (logarithmic return for stocks, change in yield to maturity for bonds, etc.)
2. Estimate the joint distribution of the market invariant over the time period of estimation
3. Project the distribution of invariants to the time period of investment
4. Map the distribution of invariants into the distribution of security prices at the investment horizon through a pricing function
5. Compute the distribution of linear returns from the distribution of prices

<a id="example-for-stocks"></a>

## Example for stocks

1. Take the prices $S_{t}, S_{t+1}, ...,$ (for example daily) for all the n securities
2. Transform the daily prices to daily logarithmic returns. Note that linear return is also a market invariant for stock, however logarithmic return is going to simplify step 3) and 4).
3. Estimate the joint distribution of market invariants by fitting parametrically the daily logarithmic returns to a multivariate normal distribution: estimate the joint distribution parameters $\mu^{Log}_{daily}$ and $\Sigma^{Log}_{daily}$
4. Project the distribution of invariants to the time period of investment (for example one year i.e. 252 business days). Because logarithmic returns are additive across time, we have <sup>[6](#id15)</sup>, <sup>[7](#id16)</sup>:
   > * $$
   >   \mu^{Log}_{yearly} = 252 \times \mu^{Log}_{daily}

   >   $$
   > * $$
   >   \Sigma^{Log}_{yearly} = 252 \times \Sigma^{Log}_{daily}

   >   $$
5. Compute the distribution of linear returns at the investment horizon. Using the characteristic function of the normal distribution, and the pricing function $S_{yearly} = S_{0} e^{R^{Log}_{yearly}}$, we get:
   > * $$
   >   \mathbb{E}(S_{yearly}) = \pmb{s}_{0} \circ exp\Biggl(\pmb{\mu}^{Log}_{yearly} + \frac{1}{2} diag\Biggl(\pmb{\Sigma}^{Log}_{yearly}\Biggr)\Biggr)

   >   $$
   > * $$
   >   Cov(S_{yearly}) = \mathbb{E}(S_{yearly})\mathbb{E}(S_{yearly})^T \circ \Biggl(exp\Biggl(\pmb{\Sigma}^{Log}_{yearly}\Biggr)-1\Biggr)

   >   $$

   From which we can estimate the moments of the linear returns at the time horizon:
   > * $$
   >   \pmb{\mu}^{Lin}_{yearly} = \frac{1}{\pmb{s}_{0} } \circ \mathbb{E}(S_{yearly}) -1

   >   $$
   > * $$
   >   \pmb{\Sigma}^{Lin}_{yearly} = \frac{1}{\pmb{s}_{0}\pmb{s}_{0}^{T} } \circ Cov(S_{yearly})

   >   $$

Where $\circ$ denotes the Hadamard product (element-wise product).

Note that we could have derived the distribution of linear returns from the distribution of logarithmic returns directly in this case.
Here we demonstrated the general procedure.

<a id="in-skfolio"></a>

## In skfolio

In `skfolio`, the above can be achieved using [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior)
by setting `is_log_normal` to `True` and providing `investment_horizon`. The input `X`
must be linear returns. The conversion to logarithmic returns is performed inside the estimator.

However, as seen in the example [Investment Horizon](https://skfolio.org/auto_examples/data_preparation/plot_1_investment_horizon.html.md#sphx-glr-auto-examples-data-preparation-plot-1-investment-horizon-py),
for frequently rebalanced portfolios (investment horizon less than a year), the general procedure and the
below simplified one will give very close results:

1. Take the prices $S_{t}, S_{t+1}, ...,$ (for example daily) for all the n securities
2. Transform the daily prices to daily linear returns
3. Estimate the expected returns vector $\mu$ and covariance matrix $\Sigma$ from the daily linear returns
4. Compute the mean-variance efficient frontier $\max_{w} \Biggl\{w^T \mu - \lambda \times w^T \Sigma w\Biggr\}$

This simplified procedure is the default one used in all `skfolio` examples as most
portfolios are rebalanced with a frequency less than a year.

**In both cases, it is highly recommended to use linear return for the input \`X\`**
If you need to estimate the moments from logarithmic returns, the conversion from linear
to logarithmic returns should be reformed inside the estimator.

For bonds and options, the general procedure will be implemented in a future release. In the meantime
you can use your own custom [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior).

<a id="periodicity-convention"></a>

<a id="id9"></a>

## Periodicity Convention

skfolio estimators work in the periodicity of the input `X`. With daily returns,
moment estimators produce daily expected returns and covariance, prior estimators
produce daily return scenarios, and optimizers consume these per-period inputs
directly. Nothing is projected to the investment horizon inside the optimization.
When horizon projection is needed, it is performed inside the prior estimator (see
[`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior) with `investment_horizon` above), not by
scaling the optimization inputs.

This convention has several benefits:

* It avoids the incorrect moment projection described in the pitfall above.
* Variance-based and scenario-based risk measures stay consistent within a single
  optimization: scenario-based measures (e.g. CVaR, CDaR) consume the return
  scenarios directly, and scenarios have no meaningful horizon-scaled equivalent.
* For ratio objectives such as maximizing the Sharpe ratio, consistent scaling of
  the return-based inputs changes the objective value but not the optimal weights,
  so projecting the inputs adds conversion risk without changing the solution.
* Walk-forward and online evaluation rebalance in units of observations, so
  per-period inputs compose with any rebalancing frequency without rescaling.

Quantities that are paid once rather than earned per period must be converted to
the periodicity of `X`. A transaction cost is paid once per rebalancing while a
position earns its expected return on every period it is held, so the one-off cost
is divided by the expected investment duration: for a 10 basis point cost, daily
returns and a one-month expected holding period, `transaction_costs=0.001 / 21`
(see [Transaction Costs](https://skfolio.org/auto_examples/mean_risk/plot_6_transaction_costs.html.md#sphx-glr-auto-examples-mean-risk-plot-6-transaction-costs-py)).
Management fees accrue with holding time, so a stated annual fee converts directly
to the return periodicity (e.g. `0.02 / 252` for a 2% annual fee on daily returns).

Annualization happens only at reporting time. [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio)
computes measures on the per-observation return series and scales them for display
in the annualized variants (e.g. `annualized_sharpe_ratio`), using its
`annualization_factor` parameter.

### References

* <a id='id10'>**[1]**</a> Note on simple and logarithmic return, Panna Miskolczi (2017)
* <a id='id11'>**[2]**</a> Quant nugget 2: linear vs. compounded returns – common pitfalls in portfolio management, GARP Risk Professional, Meucci (2010)
* <a id='id12'>**[3]**</a> Quant nugget 4: annualization and general projection of skewness, kurtosis and all summary statistics, GARP Risk Professional, Meucci (2010)
* <a id='id13'>**[4]**</a> Quant nugget 5: return calculations for leveraged securities and portfolios, GARP Risk Professional, Meucci (2010)
* <a id='id14'>**[5]**</a> Portfolio optimization and long-term dependence, Carlos León and Alejandro Reveiz
* <a id='id15'>**[6]**</a> Efficient Asset Management: A Practical Guide to Stock Portfolio Optimization and Asset Allocation, Oxford University Press, Richard Michaud and Robert Michaud.
* <a id='id16'>**[7]**</a> Portfolio Optimization Cookbook, Mosek

# user_guide/data_representation.html.md

<a id="asset-data-representation"></a>

<a id="id1"></a>

# Asset Data Representation

The choice of data structure, data container and missing-data handling matters
for portfolio workflows, cross-sectional factor models and alpha pipelines. This page discusses the main
choices, their trade-offs and the convention used by `skfolio`.

<a id="wide-and-long-format"></a>

## Wide and Long Format

Asset data (e.g. market data, fundamental data) can be represented in either wide
or long format.

In **wide format**, each field is stored as a date-by-asset matrix, with dates as
rows and assets as columns. A single field (e.g. returns) is a 2D table.
Missingness is represented as NaNs:

```text
date          AAPL    MSFT    BMW
2024-01-01    0.01    0.02    NaN
2024-01-02   -0.01    NaN     0.03
```

In **long format**, each row represents a `(date, asset)` pair. For a single field
(e.g. returns), the values are stored in one column. Missingness can be represented
either by a NaN or by the absence of a row:

```text
date          asset   returns
2024-01-01    AAPL     0.01
2024-01-01    MSFT     0.02
2024-01-02    AAPL    -0.01
2024-01-02    BMW      0.03
```

With several fields, long format keeps the same `(date, asset)` rows and adds one
column per field:

```text
date          asset   returns   volume   industry
2024-01-01    AAPL      0.01      1200    tech
2024-01-01    MSFT      0.02       900    tech
2024-01-02    AAPL     -0.01       NaN    tech
2024-01-02    BMW       0.03       700    auto
```

In wide format, the multi-field case is less direct and discussed below.

Both representations have trade-offs and serve different purposes.

Long format is often convenient for storage, database queries, joins, filtering and are
more memory efficient when the universe changes through time. It can also naturally
distinguish missing data for an asset that belongs to the universe (e.g. holidays),
represented by a NaN, from an asset that is not in the universe (e.g. delisting),
represented by the absence of a row.

The drawback is that most estimators in an end-to-end quant pipeline do not directly
consume long-format data. When they do (e.g. ML alpha prediction treating each
`(date, asset)` pair as one sample with one column per feature), they often sit in
the middle of the pipeline. Before them, the data usually needs time-aware and/or
cross-sectional transformations (e.g. cross-sectional z-scores, ranking,
winsorization, time-series estimates, factor neutralization). After them, their
outputs usually need to be time and asset aligned again for risk estimation,
portfolio optimization and evaluation. Many steps would need to handle date group-by,
pivoting, reindexing and asset alignment internally before the data can be used. These
transformations add overhead and code complexity and they increase the risk of indexing
mistakes, either on the time index, which can introduce look-ahead bias, or on the asset
index. They also make cross-validation and hyper-parameter tuning more complex when the
whole workflow must remain time-aware.

On the contrary, wide format uses more memory when the universe changes through time,
because assets that are not present at a given date are represented by NaNs. For example,
if a universe changes by about 2% per year, a 10-year history carries roughly 20%
additional entries for assets that were not present during the full period. In return,
wide format keeps the data in a dense `date × asset` representation expected by most
transformers and estimators. This allows vectorized implementations to operate on
already-aligned arrays, avoids repeated date group-by, pivoting and reindexing,
simplifies cross-validation and hyper-parameter tuning and reduces asset-alignment
errors.

`skfolio` is opinionated and follows the wide-format convention because it often provides
a worthwhile trade-off: higher memory usage, which is cheap for typical use cases,
in exchange for improved computational efficiency, simpler code and clearer temporal
and asset alignment.

One challenge is representing the multi-field case in wide format. Several choices
are possible, such as a 3D array, xarray object, DataFrame with MultiIndex columns,
or dictionary of 2D arrays. However, these choices are not optimal for portfolio workflows:
they either lack field metadata, require repeated expensive reindexing, don’t handle
zero-copy views or expose a suboptimal API for this use case.

For this reason, `skfolio` developed [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel), a
dedicated container for aligned cross-sectional asset data. It keeps the wide layout,
stores field metadata, supports categorical and tensor fields, and keeps masks
aligned with the data. See [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) for details.

<a id="missing-data"></a>

<a id="missing-data-and-changing-universes"></a>

## Missing Data and Changing Universes

Financial datasets often contain missing returns and changing asset universes. Over a
given history, assets can:

* enter the investment universe (e.g. new listing)
* leave the investment universe (e.g. delisting, default, expiry)
* remain in the universe while having missing data on some dates (e.g. holidays,
  trading interruptions, missing quotes)

Each source of missingness has different modelling implications. The right treatment
depends on the modelling choice and on what the downstream estimators support. A poor
choice can introduce bias, including universe-selection bias, survivorship bias,
non-synchronous trading bias or imputation bias.

Because wide format can encode distinct data states with the same NaN marker,
`skfolio` uses explicit conventions to distinguish:

* missing data for assets that belong to the universe (e.g. holidays)
* assets that are outside the universe at a given date (e.g. new listing, delisting)
* assets that are in the universe but not yet investable (e.g. not enough estimation data)

`skfolio` provides two main ways to handle missing data:

* make the input finite before fitting, using pre-selection, imputation, or both via a
  scikit-learn `Pipeline`
* use estimators that handle NaNs natively when they support it

<a id="pre-selection-and-imputation"></a>

## Pre-Selection and Imputation

When an estimator requires finite input, NaNs must be handled before the estimator is
fitted. This can be done with [pre-selection transformers](https://skfolio.org/user_guide/pre_selection.html.md#pre-selection), with
imputation, or with both.

For example, [`SelectComplete`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete) keeps only assets with a
complete history over the fitted period, and
[`SelectNonExpiring`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring) can remove assets according to known
expiration dates. These transformers can be combined with imputers and optimizers in a
standard `Pipeline`.

This approach is useful when:

* the downstream estimator requires finite inputs
* the missingness rule can be expressed as an asset selection rule
* imputing missing data is an acceptable modelling assumption

See [Handling Incomplete Datasets: Inception, Expiry, and Default](https://skfolio.org/auto_examples/pre_selection/plot_4_incomplete_dataset.html.md#sphx-glr-auto-examples-pre-selection-plot-4-incomplete-dataset-py) for an
example using inception, default, expiration, imputation and walk-forward validation in
a single pipeline.

This approach makes the input finite before estimation. Asset selection removes columns
from the fitted dataset, while imputation inserts chosen values for the remaining
missing observations. These rules are appropriate when they match the intended
modelling choice. They are not equivalent to native missing-data handling: for example,
filling a holiday return with zero is different from freezing the estimator state for
that observation. They also cannot represent estimator-specific readiness in the same
way: an EWMA covariance estimator can keep an asset in the universe while exposing NaNs
in its fitted covariance until the asset has enough observations for the estimate to be
used.

<a id="native-nan-aware-approach"></a>

## Native NaN-Aware Approach

Some estimators explicitly accept NaNs.

This is useful when the estimator can work with partial information. For example, a
covariance estimator can update covariance entries from non-missing pairs instead of
dropping the asset or imputing the missing returns. It can also keep its own state, such
as freezing an estimate during a holiday or exposing NaNs while an asset is still in
its warmup period. This avoids replacing missing returns with artificial values that
can bias expected returns, volatilities or correlations, and lets the estimator signal
when an estimate is not ready yet.

The native approach is also better suited to online learning. NaN-aware estimators can
update their state with `partial_fit`. The pipeline-based approach described above
cannot currently be applied in `skfolio` online learning workflows, because
scikit-learn pipelines do not provide the required online update interface for
pre-selection and imputation.

<a id="native-nan-aware-convention"></a>

## Native NaN-Aware Convention

This section applies to the native NaN-aware approach. It describes the convention used
by compatible estimators and by optimizers that consume their outputs.

For this approach, `skfolio` separates three concepts:

* missing observations in `X` (e.g. holidays)
* universe membership through time (e.g. new listings, delistings, defaults,
  expirations)
* investability at optimization time (e.g. an asset that has entered the universe but
  has not yet accumulated enough data for stable moment estimation)

<a id="universe-membership"></a>

### Universe Membership

Some estimators accept an `active_mask` parameter. It is a boolean array with the same
shape as `X`:

$$
active\_mask_{t,i} \in \{\mathrm{True}, \mathrm{False}\}
$$

It indicates whether asset $i$ is active in the universe at observation
$t$.

If `active_mask=True` and `X` is NaN, the value is considered missing for that
observation (e.g. holiday). NaN-aware estimators handle this according to their own rule
(e.g. skipping the missing pairwise update or freezing the current estimate).

If `active_mask=False`, the asset is inactive for that observation (e.g.
pre-listing or post-delisting periods). Estimators use this information to mark the
asset as unavailable.

When data is stored in an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel), each field applies
its `inactive_policy` outside `active_mask`. The default policy stores NaN for
floating numeric fields and `MISSING=-1` for categorical fields. Some generated
fields can use zero or leave inactive values unchanged when that is the field’s
convention.

<a id="estimation-universe"></a>

### Estimation Universe

Some estimators also accept an `estimation_mask` parameter. It is used for
estimator-specific calculations.

For example, a covariance estimator may compute a regime statistic on a restricted set
of liquid assets while still updating pairwise covariance estimates for all assets that
belong to the universe.

`estimation_mask` should be read as “use this asset in this estimator statistic”.

<a id="moment-estimators"></a>

### Moment Estimators

In the native NaN-aware convention, moment estimators expose unavailable assets through
NaNs in their fitted outputs.

If an expected return cannot be estimated for asset $i$, then $\mu_i$ is
set to NaN. If a variance cannot be estimated for asset $i$, then
$\Sigma_{i,i}$ is set to NaN.

Covariance estimators keep this convention consistent across the covariance matrix. If
an asset cannot belong to a finite covariance block, the corresponding row and column
of $\Sigma$ are set to NaN.

A NaN in the fitted moments marks the asset as not usable by downstream optimization,
even though the asset remains present in the full asset universe.

<a id="prior-estimators"></a>

### Prior Estimators

Prior estimators store a full-universe
[`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) in `return_distribution_`.

The full universe contains all assets passed to `fit`, including assets that are not
currently investable. Non-investable assets remain present in the arrays, but are
represented by NaNs in $\mu$, $\Sigma$, or both.

The investable universe is inferred from the fitted moments:

$$
investable_i =
\operatorname{isfinite}(\mu_i) \land
\operatorname{isfinite}(\Sigma_{i,i})
$$

An asset is investable only when both its expected return and variance are finite.

<a id="optimization"></a>

### Optimization

Before building the optimization problem, compatible portfolio optimizers extract the
investable subset from the prior’s full-universe
[`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution).

The optimization problem is solved only on assets with finite $\mu_i$ and finite
$\Sigma_{i,i}$. After solving, the weights are expanded back to the full input
universe. Assets outside the investable subset receive a weight of zero.

This keeps `weights_` aligned with the original columns of `X`, while ensuring that
the solver only receives a finite optimization problem.

<a id="native-convention-summary"></a>

### Native Convention Summary

The convention is:

1. `X` may contain NaNs.
2. `active_mask` identifies whether each asset belongs to the universe at each
   observation.
3. `estimation_mask` optionally restricts estimator-specific statistics.
4. Moment estimators encode unavailable assets with NaNs in $\mu$ or
   $\Sigma$.
5. Prior estimators keep the full asset universe in `return_distribution_`.
6. Optimizers solve on the investable subset and expand `weights_` back to the full
   universe.

# user_guide/datasets.html.md

<a id="datasets"></a>

<a id="id1"></a>

# Datasets

`skfolio` comes with three native datasets available via:

> * [`load_sp500_dataset`](https://skfolio.org/generated/skfolio.datasets.load_sp500_dataset.html.md#skfolio.datasets.load_sp500_dataset)
> * [`load_sp500_index`](https://skfolio.org/generated/skfolio.datasets.load_sp500_index.html.md#skfolio.datasets.load_sp500_index)
> * [`load_factors_dataset`](https://skfolio.org/generated/skfolio.datasets.load_factors_dataset.html.md#skfolio.datasets.load_factors_dataset)

Larger datasets are downloaded from the GitHub repo and cached locally to a data
directory. They are available via:

> * [`load_ftse100_dataset`](https://skfolio.org/generated/skfolio.datasets.load_ftse100_dataset.html.md#skfolio.datasets.load_ftse100_dataset)
> * [`load_nasdaq_dataset`](https://skfolio.org/generated/skfolio.datasets.load_nasdaq_dataset.html.md#skfolio.datasets.load_nasdaq_dataset)
> * [`load_sp500_implied_vol_dataset`](https://skfolio.org/generated/skfolio.datasets.load_sp500_implied_vol_dataset.html.md#skfolio.datasets.load_sp500_implied_vol_dataset)

By default the data directory is set to a folder named “skfolio_data” in the user home
folder. Alternatively, it can be set by the `SKFOLIO_DATA` environment variable.
If the folder does not already exist, it is automatically created.

For characteristics-based factor models, [`make_synthetic_characteristics`](https://skfolio.org/generated/skfolio.datasets.make_synthetic_characteristics.html.md#skfolio.datasets.make_synthetic_characteristics)
generates a synthetic [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) with the market and
fundamental fields used by the default descriptors and
[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel). Use it for examples, tests, and
local prototyping when you do not have a point-in-time fundamentals feed.

#### CAUTION
This dataset is provided solely for testing and example purposes. It is a stale
dataset and does not reflect current or accurate market prices. It is not
intended for investment, trading, or commercial use and should not be relied
upon as authoritative market data.

**Example:**

Loading the S&P 500 dataset, which contains daily adjusted closing prices for 20
selected constituents of the S&P 500 Index, covering the period from 1990-01-02 to
2022-12-28:

```python
from skfolio.datasets import load_sp500_dataset

prices = load_sp500_dataset()
print(prices.head())
```

Generating a synthetic characteristics panel:

```python
from skfolio.datasets import make_synthetic_characteristics

panel = make_synthetic_characteristics(n_assets=200, n_observations=1000)
print(panel.n_assets, panel.n_observations)
```

# user_guide/distance.html.md

<a id="distance"></a>

<a id="distance-estimator"></a>

# Distance Estimator

A [distance estimator](https://skfolio.org/api.html.md#distance-ref) estimates the codependence and distance
matrix of the assets.

It follows the same API as scikit-learn’s `estimator`: the `fit` method takes `X` as the
assets returns and stores the codependence and distance matrix in its `codependence_`
and `distance_` attributes.

`X` can be any array-like structure (numpy array, pandas DataFrame, etc.)

Available estimators are:
: * [`PearsonDistance`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance)
  * [`KendallDistance`](https://skfolio.org/generated/skfolio.distance.KendallDistance.html.md#skfolio.distance.KendallDistance)
  * [`SpearmanDistance`](https://skfolio.org/generated/skfolio.distance.SpearmanDistance.html.md#skfolio.distance.SpearmanDistance)
  * [`CovarianceDistance`](https://skfolio.org/generated/skfolio.distance.CovarianceDistance.html.md#skfolio.distance.CovarianceDistance)
  * [`DistanceCorrelation`](https://skfolio.org/generated/skfolio.distance.DistanceCorrelation.html.md#skfolio.distance.DistanceCorrelation)
  * [`MutualInformation`](https://skfolio.org/generated/skfolio.distance.MutualInformation.html.md#skfolio.distance.MutualInformation)

**Example:**

```python
from skfolio.datasets import load_sp500_dataset
from skfolio.distance import PearsonDistance
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)

model = PearsonDistance()
model.fit(X)
print(model.codependence_)
print(model.distance_)
```

# user_guide/expected_returns.html.md

<a id="mu-estimator"></a>

<a id="expected-return-estimator"></a>

# Expected Return Estimator

An [expected return estimator](https://skfolio.org/api.html.md#mu-ref) estimates the expected returns (`mu`) of
the assets.

It follows the same API as scikit-learn’s `estimator`: the `fit` method takes `X` as
the assets returns and stores the expected returns in its  `mu_` attribute.
`X` can be any array-like structure (numpy array, pandas DataFrame, etc.)

`mu_` is expressed in the periodicity of `X` (daily returns give daily expected
returns) and is consumed as is by the optimizers, without annualization (see
[Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention)).

Available estimators are:
: * [`EmpiricalMu`](https://skfolio.org/generated/skfolio.moments.EmpiricalMu.html.md#skfolio.moments.EmpiricalMu)
  * [`EWMu`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu)
  * [`EquilibriumMu`](https://skfolio.org/generated/skfolio.moments.EquilibriumMu.html.md#skfolio.moments.EquilibriumMu)
  * [`ShrunkMu`](https://skfolio.org/generated/skfolio.moments.ShrunkMu.html.md#skfolio.moments.ShrunkMu)

For online learning and streaming workflows, [`EWMu`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu) supports
incremental updates with `partial_fit`. It also supports NaN-aware updates with
`active_mask`, which helps distinguish assets that belong to the universe but have
missing returns (e.g. holidays), from assets outside the universe (e.g. pre-listing
or post-delisting periods).
See [Online Learning](https://skfolio.org/user_guide/online_learning.html.md#online-learning) for the full online workflow, including online
portfolio optimization evaluation with incremental moments.
See [Missing Data and Changing Universes](https://skfolio.org/user_guide/data_representation.html.md#missing-data) for the full convention
on NaNs, universe membership, estimator warmup and investability.

**Example:**

```python
from skfolio.datasets import load_sp500_dataset
from skfolio.moments import EmpiricalMu
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)

model = EmpiricalMu()
model.fit(X)
print(model.mu_)
```

# user_guide/factor_models.html.md

<a id="factor-models"></a>

<a id="id1"></a>

# Factor Models

This guide covers skfolio’s factor model implementations, their API and their
theoretical foundations. It focuses on the characteristics-based cross-sectional factor
model [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel). This model family has
become foundational in quantitative asset management, and implementing it correctly
requires addressing many practical challenges (e.g. point-in-time data, changing
universes, look-ahead bias, zero-sum constraints, alpha integration, diagnostics,
attribution and computational performance on large universes).

The results in this guide were obtained by fitting a 58-factor US equity model on
the FactSet
[Fundamentals Point-in-Time](https://www.factset.com/marketplace/catalog/product/factset-fundamentals-point-in-time),
[Estimates Point-in-Time Consensus](https://www.factset.com/marketplace/catalog/product/factset-estimates-point-in-time-consensus)
and [RBICS](https://www.factset.com/marketplace/catalog/product/factset-rbics-api)
datasets. The [Factor Models gallery](https://skfolio.org/auto_examples/factor_models/index.html.md#factor-models-examples) provides complete,
runnable tutorials using synthetic characteristics data, so users can explore the full API
while respecting data vendor licences.

For complementary references, see “The Elements of Quantitative Investing” by Giuseppe
Paleologo <sup>[1](#id6)</sup>, “Active Portfolio Management” by Grinold and Kahn <sup>[2](#id7)</sup>, and
“Portfolio Optimization: Theory and Application” by Daniel P. Palomar <sup>[3](#id8)</sup>.

<a id="introduction"></a>

## Introduction

<a id="motivation-and-use-cases"></a>

### Motivation and Use Cases

Directly estimating the covariance matrix of a large asset universe is impractical.
The sample covariance matrix of 5,000 assets has over 12 million free parameters and
requires more than 5,000 observations (~20 years of daily data) in order to reach full
rank. The resulting estimate is ill-conditioned, unstable and slow to react to change,
and an optimizer using that estimate will also tend to allocate toward the parts of the
covariance structure where estimation noise is largest.

A factor model addresses this problem by assuming that a small set of pervasive
factors (e.g. market, industries, countries, currencies, styles) drives the
co-movement of assets, and the remainder is asset-specific (i.e. idiosyncratic).
Estimation then reduces to a small factor covariance plus one idiosyncratic variance
per asset, requiring far fewer parameters and a much shorter history.

Factor models are used for:

* **Risk forecasting**: estimate a stable asset covariance matrix for large universes.
* **Risk decomposition**: express portfolio risk as systematic exposures plus
  idiosyncratic risk, separating intended from unintended exposures.
* **Performance attribution**: explain realized returns factor by factor,
  distinguishing systematic factor premia from asset-specific returns, and separating
  skill from luck.
* **Portfolio construction**: supply expected returns, covariance, scenarios and
  factor exposures to an optimizer, with exposures that can be monitored and
  constrained.
* **Alpha research**: provide the ingredients of the alpha workflow, such as
  idiosyncratic returns as a prediction target, idiosyncratic variances
  for signal scaling, and factor exposures for neutralization.
* **Alpha decomposition**: split an alpha forecast into spanned alpha and orthogonal
  alpha before optimization.

<a id="model-definition"></a>

### Model Definition

A factor model decomposes asset returns into systematic and idiosyncratic
components:

$$
r_t = B \, f_t + \epsilon_t
$$

where:

* $B \in \mathbb{R}^{N \times K}$ is the factor exposure matrix, also called
  the loading matrix: the sensitivity of each asset to each factor.
* $f_t \in \mathbb{R}^{K}$ is the vector of factor returns: the return per unit
  of exposure at time $t$, common to all assets.
* $\epsilon_t \in \mathbb{R}^{N}$ is the vector of idiosyncratic returns: the
  part of asset returns not explained by the factors.

The factor structure assumes that common co-movement is captured by the factors, and
that the remaining idiosyncratic covariance is diagonal or sparse. The asset
covariance matrix is:

$$
\Sigma = B \, F \, B^\top + D
$$

where $F \in \mathbb{R}^{K \times K}$ is the factor covariance matrix and
$D$ is the diagonal or sparse idiosyncratic covariance matrix.

The [Expected Returns](https://skfolio.org/user_guide/factor_models.html.md#factor-model-expected-returns) section explains how
[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel) estimates expected asset returns
from expected factor returns and an optional alpha forecast.

The rest of this guide covers the estimation of $B$, $f_t$, $F$,
and $D$, and their use in optimization and attribution.

<a id="types-of-factor-models"></a>

### Types of Factor Models

Factor model families differ by what is observed before fitting: factor returns,
factor exposures, or neither.

**Time-series factor models** observe the factor returns and estimate asset exposures.
Factors are observable time series such as factor ETF returns, long-short factor portfolio
returns, or macroeconomic series (e.g. inflation, rates, GDP growth), hence the
alternative name “macroeconomic factor models”. Each asset’s exposures come from a
time-series regression of its returns on those factor series. They are interpretable,
straightforward to estimate, and they can work on small universes because each
asset is estimated independently. However, they require long return histories per asset,
exposures react slowly to asset-level change because they only update through the
regression window, and the risk of misspecification is higher. When factors are
tradable, their return history can be used to estimate factor premia. For
non-tradable variables, factor premia are estimated with a second-pass
cross-sectional procedure such as Fama-MacBeth on a sufficiently broad universe.
Implemented in [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel).

**Characteristics-based factor models**, also called “fundamental factor models”, observe
exposures and estimate factor returns. Exposures are built from point-in-time
asset characteristics (e.g. industry classification, country, market capitalization,
book equity, sales, operating cash flow, analyst estimates), and factor returns are derived
from one cross-sectional regression of asset returns on exposures at each date.
Exposures react immediately to asset-level change, new assets need no return history to
receive exposures, and factors can be neutralized against each other to produce pure
factor definitions. The challenges of this model are the complexity of the estimation
procedure and the heavier data requirement, both of which are covered in this guide.
Implemented in [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel).

#### NOTE
The Fama-French procedure also starts from characteristics, but follows a different
construction. It uses characteristics to sort assets into quantile long-short
portfolios whose returns define the factors. It is primarily a factor-pricing
framework for explaining the cross-section of expected returns, as opposed to a full
risk model. To use those factor returns as a risk model for arbitrary assets, exposures
must be estimated by time-series regression, inheriting the drawbacks of
time-series factor models.

Moreover, quantile portfolios are not pure factors in the characteristics
risk-model sense. A value portfolio, for example, can also carry industry, size,
profitability, investment or momentum tilts because the sorting procedure only
controls the characteristics used to build the portfolio. Intersection procedures
reduce this contamination by sorting on several characteristics at the same time,
but they do not scale to a large number of factors.

**Statistical factor models** observe neither factor returns nor exposures and instead
extract both from asset returns using methods such as PCA. They are adaptive and need
returns only, but factors have no economic identity and may drift across regimes.
Currently not implemented in skfolio.

<a id="historical-background"></a>

### Historical Background

Characteristics factor models originate with Barr Rosenberg, whose 1974 work on
extra-market components of covariance <sup>[4](#id9)</sup> showed that asset characteristics predict
return covariation, and that a small set of common factors explains most
cross-sectional variation while the residual is asset-specific. Rosenberg founded
Barra (now part of MSCI) to commercialize the approach, and the first US equity model
(USE1) was released in 1975. Specialist competitors followed, including Northfield
(1985), Axioma (1998) and Wolfe Research (2008). Data vendors later entered the market
by adding proprietary factor models to their data and analytics platforms, including
Bloomberg, FactSet, S&P Global and Morningstar. Factor risk models have since become
standard infrastructure across quantitative hedge funds, asset managers and banks.

These models were initially built for risk estimation, but practitioners observed
that some risk factors (e.g. value, momentum) also earn persistent premia. Modern
implementations therefore estimate expected factor returns alongside factor
covariances, enabling deliberate tilts toward specific factors in optimization, the
foundation of what became known as “smart beta”.

Today, commercial factor risk models are often distributed as model catalogues, usually segmented by
region and horizon. skfolio now provides a toolkit for building and customizing factor models directly
from user-defined data, rather than selecting a single predefined model from a catalogue. This enables a
continuum of specifications, recognizing the view that there is no “one size fits all” factor model.

<a id="alternatives-to-a-single-centralized-factor-model"></a>

### Alternatives to a Single Centralized Factor Model

A factor model is an estimate. Its exposures, factor covariance and
idiosyncratic variances carry estimation error, and its specification is never
complete, as no factor set captures all common co-movement.

The traditional commercial offering can lead to a single house risk model
being shared by all strategies and risk management teams. skfolio supports
this approach but also allows for an alternative approach where the factor model is
itself an estimator parameter, such that each strategy can embed its own specific
factor model. The strategy and its factor model then form a single meta-model that is fitted,
evaluated and tuned jointly.

Multiple factor models allow portfolio construction and risk monitoring to use different model
specifications. A portfolio may be constructed with a factor model tailored to its universe,
horizon and alpha process, while risk management evaluates exposures and covariance with a
broader firm-wide model. At the book level, using different factor models across portfolios
and strategies introduces model diversification. Estimation error and specification error are
then distributed across model specifications rather than concentrated in a single shared model.

<a id="model-overview"></a>

## Model Overview

<a id="estimation-pipeline"></a>

### Estimation Pipeline

[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel) is a meta-estimator following
scikit-learn conventions. It composes sub-estimators, descriptors, factor exposure
estimators, a cross-sectional regressor, prior estimators for factor and idiosyncratic
risk and an optional alpha estimator, each of which can be replaced, tuned and
customized independently. The input is a point-in-time
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) of asset characteristics and the output is a
[`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) consumed by all skfolio optimizations,
together with a [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel) container holding the full
decomposition and diagnostics.

The model is fitted as follows:

1. Start from point-in-time asset characteristics stored as panel fields (e.g.
   `returns`, `market_cap`, `book_equity`, `industry`).
2. Compute descriptor values from these fields, or pass through existing fields
   unchanged, using descriptor estimators.
3. Build factor exposures. Style factors are typically formed by combining one or
   more descriptors and applying cross-sectional transformations (e.g. winsorization,
   z-scoring). Categorical factors (e.g. industry, country, currency) are represented
   by one-hot exposures.
4. Orthogonalize selected exposures against other factors or families when
   `neutralize_against` is provided.
5. Reparameterize constrained families when `constrained_families` is provided. This
   enforces the benchmark-weighted zero-sum constraint on factor returns within each
   constrained family and produces a full-rank basis for factor-level estimators.
6. Estimate realized factor returns with
   `cs_regressor` on the estimation universe defined by the panel’s
   `estimation_mask`. By default, regression weights are based on market
   capitalization through `regression_mcap_power`. When
   `inv_idio_variance_weight_shrinkage > 0`, a two-pass procedure blends those weights
   with inverse-idiosyncratic-variance weights estimated from first-pass residuals.
7. Estimate the factor return distribution with `factor_prior_estimator`, including
   expected factor returns (factor premia), factor covariance and factor return
   scenarios. This step can introduce factor covariance shrinkage, short-term
   volatility updating or Newey-West HAC correction.
8. Estimate idiosyncratic variances with `idio_variance_estimator`, then form the
   idiosyncratic covariance as a diagonal matrix or, when `idio_corr_threshold > 0`,
   as a sparse covariance using correlation thresholding.
9. If provided, fit `alpha_estimator` to produce an alpha forecast. Decompose it into
   spanned alpha and orthogonal alpha, blend factor-implied asset expected returns with
   the spanned alpha using `spanned_alpha_shrinkage`, shrink the orthogonal alpha
   with `orthogonal_alpha_confidence` and assemble the final $\mu$,
   $\Sigma$ and asset return scenarios on the investment universe.

Each step is detailed in the following sections.

<a id="factor-model-code-example"></a>

<a id="code-example"></a>

### Code Example

The model below is used throughout this guide. It is a medium-horizon US equity model
with 58 factors: 1 global factor, 44 industry factors and 13 style factors built from
29 descriptors. It uses within-industry scoring, neutralization, a zero-sum constraint
on the industry family, regression weights that blend market-capitalization weights
with inverse-idiosyncratic-variance weights and a regime-adjusted factor covariance
estimator. The model was fitted on the FactSet point-in-time datasets of 2,000 US
equities with daily data from 2013 to 2026. The parametrization is intentionally
simple and has not been fine-tuned. This simplified model is used as the standard
example for presenting the API. See [Hyperparameter Tuning](https://skfolio.org/user_guide/factor_models.html.md#factor-model-hyper-parameter-tuning) for guidance on tuning the model to your data
and goals.

```python
from skfolio.descriptor import (
    AssetsGrowthRate,
    AssetTurnover,
    BookLeverage,
    BookToPrice,
    CapexToAssetsChangeInIntensity,
    CashFlowToAssets,
    CashFlowToPrice,
    DebtToAssets,
    DividendToPrice,
    EarningsChangeToPrice,
    EarningsToPrice,
    EbitdaToEnterpriseValue,
    EWAmihudIlliquidity,
    EWMarketBeta,
    EWMomentum,
    EWResidualVolatility,
    EWShareTurnover,
    EWVolatility,
    ForwardEarningsToPrice,
    GrossMargin,
    GrossProfitability,
    IssuanceGrowthRate,
    LogMarketCap,
    MarketLeverage,
    ReturnOnAssets,
    ReturnOnEquity,
    SalesGrowthRate,
    SalesToPrice,
    ShareholderYield,
)
from skfolio.factor_exposure import (
    DerivedFactor,
    FixedWeightedFactor,
    GlobalFactor,
    OneHotCategoricalFactors,
)
from skfolio.moments import EWMu, RegimeAdjustedEWCovariance
from skfolio.prior import CharacteristicsFactorModel, EmpiricalPrior

month = 21
quarter = 3 * month
half_year = 6 * month
year = 12 * month

# Global factor
global_factor = GlobalFactor(family="market")

# Industry factors
industry_factors = OneHotCategoricalFactors(category="industry", family="industry")

# Style factors
beta_factor = FixedWeightedFactor(
    descriptors=[("market_beta", EWMarketBeta(half_life=year))],
    transform_by_group="industry",
)

momentum_factor = FixedWeightedFactor(
    descriptors=[("momentum", EWMomentum(half_life=half_year, skip=month))],
    transform_by_group="industry",
)

size_factor = FixedWeightedFactor(
    descriptors=[("log_mcap", LogMarketCap())], transform_by_group="industry"
)

non_linear_size_factor = DerivedFactor(
    source="size", func=lambda x: x**3, transform_by_group="industry"
)

value_factor = FixedWeightedFactor(
    descriptors=[
        ("book_to_price", BookToPrice()),
        ("sales_to_price", SalesToPrice()),
        ("cash_flow_to_price", CashFlowToPrice()),
    ],
    weights=[0.8, 0.1, 0.1],
    transform_by_group="industry",
)

earnings_yield_factor = FixedWeightedFactor(
    descriptors=[
        ("fwd_earnings_to_price", ForwardEarningsToPrice()),
        ("earnings_to_price", EarningsToPrice()),
        ("enterprise_multiple", EbitdaToEnterpriseValue()),
    ],
    transform_by_group="industry",
)

growth_factor = FixedWeightedFactor(
    descriptors=[
        ("earnings_change_to_price", EarningsChangeToPrice(lag=year)),
        ("sales_growth", SalesGrowthRate(lag=year)),
    ],
    transform_by_group="industry",
)

profitability_factor = FixedWeightedFactor(
    descriptors=[
        ("asset_turnover", AssetTurnover()),
        ("gross_profitability", GrossProfitability()),
        ("gross_margin", GrossMargin()),
        ("return_on_assets", ReturnOnAssets()),
        ("return_on_equity", ReturnOnEquity()),
        ("cash_flow_to_assets", CashFlowToAssets()),
    ],
    transform_by_group="industry",
)

investment_factor = FixedWeightedFactor(
    descriptors=[
        ("asset_growth", AssetsGrowthRate(lag=year)),
        ("issuance_growth", IssuanceGrowthRate(lag=year)),
        ("capex_growth", CapexToAssetsChangeInIntensity(lag=year)),
    ],
    transform_by_group="industry",
)

dividend_yield_factor = FixedWeightedFactor(
    descriptors=[
        ("dividend_to_price", DividendToPrice()),
        ("shareholder_yield", ShareholderYield()),
    ],
    weights=[0.7, 0.3],
    transform_by_group="industry",
)

leverage_factor = FixedWeightedFactor(
    descriptors=[
        ("market_leverage", MarketLeverage()),
        ("debt_to_assets", DebtToAssets()),
        ("book_leverage", BookLeverage()),
    ],
    transform_by_group="industry",
)

liquidity_factor = FixedWeightedFactor(
    descriptors=[
        ("share_turnover", EWShareTurnover(half_life=quarter)),
        ("amihud_illiquidity", EWAmihudIlliquidity()),
    ],
    transform_by_group="industry",
)

volatility_factor = FixedWeightedFactor(
    descriptors=[
        ("vol", EWVolatility(half_life=quarter)),
        (
            "residual_vol",
            EWResidualVolatility(half_life=quarter, beta_half_life=quarter),
        ),
    ],
    transform_by_group="industry",
)

# Characteristics Factor Model
model = CharacteristicsFactorModel(
    factors=[
        ("market", global_factor),
        ("industry", industry_factors),
        ("beta", beta_factor),
        ("momentum", momentum_factor),
        ("size", size_factor),
        ("non_linear_size", non_linear_size_factor),
        ("value", value_factor),
        ("earnings_yield", earnings_yield_factor),
        ("growth", growth_factor),
        ("profitability", profitability_factor),
        ("investment", investment_factor),
        ("dividend_yield", dividend_yield_factor),
        ("leverage", leverage_factor),
        ("liquidity", liquidity_factor),
        ("volatility", volatility_factor),
    ],
    neutralize_against={
        "non_linear_size": ["size"],
        "volatility": ["beta"],
    },
    constrained_families=[("industry", None)],
    exposure_lag=1,
    inv_idio_variance_weight_shrinkage=0.5,
    factor_prior_estimator=EmpiricalPrior(
        covariance_estimator=RegimeAdjustedEWCovariance(
            half_life=half_year, corr_half_life=year, regime_half_life=month
        ),
        mu_estimator=EWMu(half_life=year),
    ),
    n_jobs=-1,
)
```

The model is fitted on a point-in-time [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) whose
construction is covered in the [Input Data](https://skfolio.org/user_guide/factor_models.html.md#factor-model-input-data) section:

```python
model.fit(characteristics=characteristics)
```

For incremental updates on new observations, use `partial_fit`, covered in the
[Online Learning](https://skfolio.org/user_guide/factor_models.html.md#factor-model-online-learning) section:

```python
model.partial_fit(characteristics=new_characteristics)
```

After fitting, the model exposes two main attributes.

`return_distribution_` is the [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) consumed by
skfolio optimizations. It contains the expected asset returns `mu`, the asset
covariance matrix `covariance` and the asset return scenarios `returns`, all on the
investment universe. Assets that are not investable at the current point in time
(e.g. delisted, not yet listed, or still in [warmup](https://skfolio.org/user_guide/factor_models.html.md#factor-model-warmup))
are represented with NaN.

`factor_model_` is the [`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel) container holding the full
decomposition: factor exposures, loading matrix, factor returns, expected factor
returns and factor covariance, idiosyncratic returns, variances and covariance,
regression and benchmark weights. It provides DataFrame accessors (`factor_returns_df`,
`idio_returns_df`, `exposures_df`), slicing (`select_assets`, `select_observations`),
a `summary` method and the diagnostic statistics and plots covered in the
[Diagnostics](https://skfolio.org/user_guide/factor_models.html.md#factor-model-diagnostics) section.

```python
distribution = model.return_distribution_
distribution.mu          # expected returns, shape (n_assets,)
distribution.covariance  # asset covariance, shape (n_assets, n_assets)
distribution.returns     # return scenarios, shape (n_observations, n_assets)

factor_model = model.factor_model_
factor_model.summary()
factor_model.factor_returns_df()
```

The fitted sub-estimators are also available with the usual scikit-learn trailing
underscore convention: `cs_regressor_`, `factor_prior_estimator_`,
`idio_variance_estimator_`, `idio_corr_estimator_` and `alpha_estimator_`.

The `X` argument of `fit` is optional. When provided, `X` selects the investment
universe: its columns define the assets returned in `return_distribution_` and
`factor_model_`. Factor estimation still uses the `returns` field of
`characteristics`, which can cover a broader point-in-time universe. This keeps the
estimator compatible with skfolio pipelines, cross-validation, prediction and scoring.
When `X` is `None`, the investment universe equals the coverage universe.

<a id="factor-model-input-data"></a>

<a id="input-data"></a>

## Input Data

The model consumes a point-in-time [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) of asset
characteristics. The panel must include a `returns` field and, when market-cap
weighting is used, a `market_cap` field. The remaining fields depend on the chosen
descriptors and alpha estimators. The [example](https://skfolio.org/user_guide/factor_models.html.md#factor-model-code-example)
model uses market data (e.g.
`adj_close`, `adj_volume`, `adj_shares_outstanding`), fundamentals (e.g.
`book_equity`, `sales_ttm`, `total_assets`, `operating_cash_flow_ttm`), analyst
estimates (e.g. `eps_ntm`, `dps_ntm`) and a categorical `industry` field.

<a id="assetpanel-container"></a>

### AssetPanel Container

A factor model pipeline applies many cross-sectional and time-series transformations
to the same date-by-asset data. With general-purpose containers (e.g. DataFrames, xarray),
each step must re-align indexes, group by date or pivot before computing. This adds
overhead and increases the risk of indexing errors, either on the time index, which
can introduce look-ahead bias, or on the asset index. To address this, skfolio provides
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel), a dedicated container for aligned
cross-sectional asset data. An [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) validates
alignment once so that estimators operate on already-aligned numeric arrays and stores
universe masks explicitly, which is needed for point-in-time estimation on changing
universes (e.g. listing, delisting, inclusion/exclusion rules).

The rationale behind the container, the wide-format convention and the NaN-handling
conventions are covered in [Asset Data Representation](https://skfolio.org/user_guide/data_representation.html.md#asset-data-representation).

Every field shares the same two axes with shape `(n_observations, n_assets)`. Three
kinds of fields are supported:

* 2D numeric fields (e.g. `returns`, `market_cap`)
* 2D categorical fields (e.g. `industry`, `country`), stored as integer codes with
  their category labels
* 3D numeric fields (e.g. factor exposures), with labeled third axis

The panel also carries two boolean masks aligned with the data, `active_mask` and
`estimation_mask`, described in [Coverage, Estimation and Investment
Universes](https://skfolio.org/user_guide/factor_models.html.md#factor-model-universes).

This layout has additional practical benefits:

* The container is scikit-learn compatible: `len(panel)` returns the number of
  observations and `panel[start:stop]` returns a zero-copy view, so the panel can be
  passed directly to cross-validation and hyper-parameter tuning utilities, and
  walk-forward folds reuse the same field arrays instead of copying them.
* With thread-based parallelism, workers read the same panel in memory instead of
  receiving separate process copies, which is significant for large panels.
* Panels are saved as `.npy` files and support memory-mapped loading for fast
  startup on large datasets.

```python
import numpy as np
from skfolio.containers import AssetPanel
from skfolio.datasets import make_synthetic_characteristics

# Build a panel from aligned date-by-asset arrays.
panel = AssetPanel(
    fields={
        "returns": returns,        # ndarray (n_observations, n_assets)
        "market_cap": market_cap,  # ndarray (n_observations, n_assets)
    },
    observations=dates,
    asset_names=assets,
    active_mask=active_mask,
    estimation_mask=estimation_mask,
)
panel.add_categorical_field(
    name="industry",
    values=industry_codes,  # integer codes (n_observations, n_assets)
    levels=["energy", "bank", "technology"],
)

# Inspect dimensions, fields, missing values and mask coverage.
panel.info()

# Save and reload a panel.
panel.save("path/to/saved_panel")
saved_panel = AssetPanel.load("path/to/saved_panel")

# Generate a synthetic panel for examples and tests.
characteristics = make_synthetic_characteristics()
```

<a id="factor-model-universes"></a>

<a id="coverage-estimation-and-investment-universes"></a>

### Coverage, Estimation and Investment Universes

A factor model distinguishes three universes:

* The **coverage universe** is the full set of assets stored in the
  [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel). It contains the estimation universe and
  the investment universe.
* The **estimation universe**, defined by the panel’s `estimation_mask`, is the
  subset of observation-asset pairs used to fit cross-sectional statistics,
  factor-return regressions, benchmark and regression weights, alpha estimators and
  regime statistics. Pairs outside it still receive transformed values, exposures and
  forecasts, but do not contribute to those fitted statistics.
* The **investment universe** is the set of assets selected for portfolio
  optimization. It is returned in `return_distribution_` and
  `factor_model_`. When `X` is provided to `fit`, its columns select this universe.
  When `X` is `None`, the investment universe equals the coverage universe. This lets
  the model estimate factors on a broader cross-section, then return outputs only for
  the assets used downstream.

Membership within the coverage universe varies through time and is tracked by the
panel’s `active_mask`. `False` marks an asset outside the universe at that date
(e.g. pre-listing, post-delisting), while `True` with a NaN value marks missing data
for an active asset (e.g. holiday, missing quote). The `estimation_mask` is enforced
as a subset of `active_mask`.

The estimation universe must be broad enough to represent the investment opportunity
set, liquid enough to avoid spurious return relationships and stable enough for factor
exposures to behave consistently through time. For a US equity model, a typical
estimation universe is 1,000 to 3,000 names. It should also be large enough relative to the
factor set. The number of estimation assets $N$ should be well above the number of
factors $K$ for a stable cross-sectional regression, and best practice is to have
at least 20 estimation assets per industry (e.g. 50 industries require at least
1,000 assets in a well-balanced universe, and more if some industries are sparsely
represented).

The effective size of the estimation universe also depends on the regression weights.
The default square-root market-capitalization weights are commonly used as a proxy for
inverse idiosyncratic variance. Under this default weighting, the contribution of
small stocks decreases rapidly: relative to the full universe of investable US
equities, the largest 2,000 stocks represent about 99% of total market capitalization
and would carry roughly 90% of the total regression weight. Extending the universe
beyond this point can still be useful when the additional names improve estimation
of small-cap-sensitive factors or increase coverage of sparsely represented industries.
Otherwise, extending the estimation universe further mostly adds memory and compute cost
and may add noise from illiquid securities (e.g. stale prices, zero-return days,
bid-ask bounce, missing fundamentals).

<a id="factor-model-point-in-time-data"></a>

<a id="point-in-time-data"></a>

### Point-in-Time Data

AssetPanel characteristics should be built from point-in-time (PIT) datasets. For
fundamentals, this means respecting reporting lags and using the figures as reported
at the time, before later restatements. Data vendors offer point-in-time datasets for
this purpose, and the example in this guide is constructed using FactSet point-in-time datasets.
When actual availability dates are not available, a common fallback is to apply a
conservative lag from the fiscal period end, such as 90 days, before making the value
available to the model.

Let’s suppose ABC’s fiscal Q2 ends on 2024-06-30, Q2 sales are reported as 100m
on 2024-08-05, and later restated to 96m on 2024-11-12. If the latest available
Q1 sales value is 90m before the Q2 report, a daily `AssetPanel` stores:

| Observation date   | Sales value in the PIT panel   | Source available on that date   |
|--------------------|--------------------------------|---------------------------------|
| 2024-08-01         | 90m                            | Latest available Q1 value       |
| 2024-08-02         | 90m                            | Latest available Q1 value       |
| 2024-08-05         | 100m                           | 2024 Q2 report                  |
| 2024-08-06         | 100m                           | Latest available Q2 value       |
| 2024-11-12         | 96m                            | 2024 Q2 restatement             |

Universe membership must also be point-in-time. The universe is formed by applying
eligibility rules at each observation date, using fields known on that date such as
listing status, market capitalization, liquidity, sector, country, exchange and
security type. Fitting history on the current constituent list introduces survivorship
bias as assets that were delisted, acquired or defaulted disappear from the sample,
biasing both estimates. See
[data representation](https://skfolio.org/user_guide/data_representation.html.md#asset-data-representation) for missing data, changing
universes and `active_mask`.

<a id="factor-model-time-alignment"></a>

<a id="time-alignment-and-look-ahead-bias"></a>

### Time Alignment and Look-Ahead Bias

To avoid look-ahead bias from inconsistent time indexing and manual lagging across
characteristic fields, exposures and returns, skfolio uses a single as-of
time-indexing convention across all estimators, so data is aligned once and lags
enter as model parameters.

Under this convention, all time-varying inputs at observation $t$ reflect
information available up to and including the end of period $t$. Point-in-time
fields and derived values (e.g. prices, fundamentals, industry labels and factor
exposures) store the latest available value for observation $t$. Returns
stored at observation $t$ cover the period ending at $t$, namely
$(t-1, t]$.

Factor-return regressions estimate the factor returns realized over
$(t-1, t]$. The exposure matrix must therefore describe the assets before that
return interval begins, at $t-1$. `exposure_lag` selects that
exposure date and defaults to 1:

$$
R(t) = B(t - \ell)\,f(t) + \epsilon(t)
$$

where $\ell$ is `exposure_lag`. With the default $\ell = 1$, returns over
$(t-1, t]$ are regressed on exposures measured at $t-1$.
At each observation, this regression estimates realized factor returns and
idiosyncratic returns $\epsilon(t)$. Expected asset returns are subsequently
constructed from expected factor returns and, when configured, an alpha forecast.

The same alignment applies to regression weights. Market capitalization weights are
lagged by `exposure_lag`, and inverse-idiosyncratic-variance weights at date
$t$ are estimated from residuals up to $t-1$. Both are detailed in the
[Regression Weights](https://skfolio.org/user_guide/factor_models.html.md#factor-model-regression-weights) section.

Stored outputs follow the as-of time-indexing convention. `factor_model_.exposures` at $t$
stores the exposures measured at $t$, and the covariance forecast pairs the
factor covariance with the latest exposures $B(T)$. The lag is applied
internally when estimating realized factor returns and regression-based statistics.

<a id="split-dividend-and-excess-return-conventions"></a>

### Split, Dividend and Excess Return Conventions

The `returns` field should contain total returns, computed from split and dividend
adjusted prices. It is the dependent variable of the cross-sectional regression and
the input to all return-based descriptors (beta, volatility, momentum, reversal).

Other market data used by descriptors, such as prices, trading volumes and shares
outstanding, should be split adjusted but not dividend adjusted. These enter
descriptors as price and quantity levels, for example as the denominator of a
valuation ratio or in turnover and liquidity measures, where reinvested dividends
would distort the level. The corresponding fields are detailed in the
[Descriptors](https://skfolio.org/user_guide/factor_models.html.md#factor-model-descriptor-input-fields) section. The `market_cap`
field should contain the market value of common equity at each date.

In a single-currency model, raw and excess returns give nearly identical regression
results, as subtracting a common risk-free rate shifts the cross-section by a constant
that the global factor absorbs. Excess returns remain preferable because
some descriptors estimate time-series regressions (e.g.
[`EWMarketBeta`](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#skfolio.descriptor.EWMarketBeta),
[`EWResidualVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility)) whose time-series intercept should
capture residual return without absorbing the risk-free rate. In a multi-currency model,
`returns` should contain local excess returns, and currency excess returns are
supplied through the `currency_excess_returns` argument. See the [Currency
Factors](https://skfolio.org/user_guide/factor_models.html.md#factor-model-currency-factors) section.

<a id="factor-model-factor-exposures"></a>

<a id="factor-exposures"></a>

## Factor Exposures

Factor exposure estimators transform an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) into
factor exposure arrays. Some estimators compute
exposures without descriptors, such as the global market factor or one-hot industry
factors. Others compute one or more descriptors and transform them into standardized
style exposures.

skfolio provides four factor exposure estimators:

* [`GlobalFactor`](https://skfolio.org/generated/skfolio.factor_exposure.GlobalFactor.html.md#skfolio.factor_exposure.GlobalFactor) creates one common factor by
  assigning every asset an exposure of 1.0. In the cross-sectional regression,
  this factor acts as the cross-sectional regression intercept or broad market
  factor. With the
  benchmark-weighted centering and zero-sum constraints described in
  [Global Factor and Benchmark Portfolio](https://skfolio.org/user_guide/factor_models.html.md#factor-model-global-factor), its
  estimated factor return captures the benchmark portfolio return.
* [`OneHotCategoricalFactors`](https://skfolio.org/generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md#skfolio.factor_exposure.OneHotCategoricalFactors) turns a categorical
  field into binary membership factors, one factor per category level. An asset has
  exposure 1.0 to the factor matching its category and 0.0 to the other
  category factors.
* [`FixedWeightedFactor`](https://skfolio.org/generated/skfolio.factor_exposure.FixedWeightedFactor.html.md#skfolio.factor_exposure.FixedWeightedFactor) builds a factor from one or
  more descriptors. Each descriptor is computed, passed through the outlier and
  scoring transforms, and converted into a cross-sectional score. The descriptor
  scores are then aggregated with the fixed descriptor weights. For each
  asset-observation pair, non-finite scores are ignored and the weighted average is
  divided by the weight assigned to the remaining finite scores, so an asset missing
  a descriptor (e.g. gross margin for financial firms, which do not report cost of
  goods sold) can still receive a composite score from its valid descriptors. The
  `min_coverage` parameter sets the minimum fraction of descriptor weight that must
  be finite and when below this threshold, the composite is NaN. When multiple descriptors
  are combined and scoring is enabled, the composite is scored again cross-sectionally
  so partial-coverage composites remain on a comparable scale.
* [`DerivedFactor`](https://skfolio.org/generated/skfolio.factor_exposure.DerivedFactor.html.md#skfolio.factor_exposure.DerivedFactor) applies a function to another
  factor’s exposure, then optionally applies outlier and scoring transforms. In
  the [example](https://skfolio.org/user_guide/factor_models.html.md#factor-model-code-example), it builds the non-linear size
  factor from the size exposure (`func=lambda x: x**3`). Dependencies between
  factors are resolved automatically through topological sorting.

Custom exposure estimators are created by subclassing
[`BaseFactorExposure`](https://skfolio.org/generated/skfolio.factor_exposure.BaseFactorExposure.html.md#skfolio.factor_exposure.BaseFactorExposure).

Every factor exposure estimator carries a `family` attribute (e.g. `"market"`,
`"style"`, `"industry"`, `"country"`, `"currency"`). Families group related factors and
are used in neutralization, zero-sum constraints, attribution and reporting.

<a id="factor-model-descriptors"></a>

<a id="descriptors"></a>

### Descriptors

A descriptor is a transformer that reads one or more
[`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) fields and returns a value array of shape
`(n_observations, n_assets)`. Descriptors follow the as-of time-indexing convention: values at
observation $t$ use information available up to and including the end of period
$t$.

skfolio provides descriptors covering the standard factor literature:

| Category         | Descriptors                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Value            | * [`BookToPrice`](https://skfolio.org/generated/skfolio.descriptor.BookToPrice.html.md#skfolio.descriptor.BookToPrice)<br/>* [`CashFlowToPrice`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToPrice.html.md#skfolio.descriptor.CashFlowToPrice)<br/>* [`SalesToPrice`](https://skfolio.org/generated/skfolio.descriptor.SalesToPrice.html.md#skfolio.descriptor.SalesToPrice)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Earnings yield   | * [`EarningsToPrice`](https://skfolio.org/generated/skfolio.descriptor.EarningsToPrice.html.md#skfolio.descriptor.EarningsToPrice)<br/>* [`ForwardEarningsToPrice`](https://skfolio.org/generated/skfolio.descriptor.ForwardEarningsToPrice.html.md#skfolio.descriptor.ForwardEarningsToPrice)<br/>* [`EbitdaToEnterpriseValue`](https://skfolio.org/generated/skfolio.descriptor.EbitdaToEnterpriseValue.html.md#skfolio.descriptor.EbitdaToEnterpriseValue)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Growth           | * [`AssetsGrowthRate`](https://skfolio.org/generated/skfolio.descriptor.AssetsGrowthRate.html.md#skfolio.descriptor.AssetsGrowthRate)<br/>* [`SalesGrowthRate`](https://skfolio.org/generated/skfolio.descriptor.SalesGrowthRate.html.md#skfolio.descriptor.SalesGrowthRate)<br/>* [`EarningsChangeToPrice`](https://skfolio.org/generated/skfolio.descriptor.EarningsChangeToPrice.html.md#skfolio.descriptor.EarningsChangeToPrice)<br/>* [`IssuanceGrowthRate`](https://skfolio.org/generated/skfolio.descriptor.IssuanceGrowthRate.html.md#skfolio.descriptor.IssuanceGrowthRate)<br/>* [`CapexToAssetsChangeInIntensity`](https://skfolio.org/generated/skfolio.descriptor.CapexToAssetsChangeInIntensity.html.md#skfolio.descriptor.CapexToAssetsChangeInIntensity)<br/>* [`GrowthRate`](https://skfolio.org/generated/skfolio.descriptor.GrowthRate.html.md#skfolio.descriptor.GrowthRate)<br/>* [`ChangeToScale`](https://skfolio.org/generated/skfolio.descriptor.ChangeToScale.html.md#skfolio.descriptor.ChangeToScale)<br/>* [`ChangeInIntensity`](https://skfolio.org/generated/skfolio.descriptor.ChangeInIntensity.html.md#skfolio.descriptor.ChangeInIntensity) |
| Profitability    | * [`GrossProfitability`](https://skfolio.org/generated/skfolio.descriptor.GrossProfitability.html.md#skfolio.descriptor.GrossProfitability)<br/>* [`GrossMargin`](https://skfolio.org/generated/skfolio.descriptor.GrossMargin.html.md#skfolio.descriptor.GrossMargin)<br/>* [`ReturnOnAssets`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets)<br/>* [`ReturnOnEquity`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnEquity.html.md#skfolio.descriptor.ReturnOnEquity)<br/>* [`AssetTurnover`](https://skfolio.org/generated/skfolio.descriptor.AssetTurnover.html.md#skfolio.descriptor.AssetTurnover)<br/>* [`CashFlowToAssets`](https://skfolio.org/generated/skfolio.descriptor.CashFlowToAssets.html.md#skfolio.descriptor.CashFlowToAssets)<br/>* [`SalesToEnterpriseValue`](https://skfolio.org/generated/skfolio.descriptor.SalesToEnterpriseValue.html.md#skfolio.descriptor.SalesToEnterpriseValue)                                                                                                                                             |
| Earnings quality | * [`AccrualsCashFlow`](https://skfolio.org/generated/skfolio.descriptor.AccrualsCashFlow.html.md#skfolio.descriptor.AccrualsCashFlow)<br/>* [`AnalystDispersionToPrice`](https://skfolio.org/generated/skfolio.descriptor.AnalystDispersionToPrice.html.md#skfolio.descriptor.AnalystDispersionToPrice)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Dividend yield   | * [`DividendToPrice`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice)<br/>* [`ForwardDividendToPrice`](https://skfolio.org/generated/skfolio.descriptor.ForwardDividendToPrice.html.md#skfolio.descriptor.ForwardDividendToPrice)<br/>* [`ShareholderYield`](https://skfolio.org/generated/skfolio.descriptor.ShareholderYield.html.md#skfolio.descriptor.ShareholderYield)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Leverage         | * [`MarketLeverage`](https://skfolio.org/generated/skfolio.descriptor.MarketLeverage.html.md#skfolio.descriptor.MarketLeverage)<br/>* [`BookLeverage`](https://skfolio.org/generated/skfolio.descriptor.BookLeverage.html.md#skfolio.descriptor.BookLeverage)<br/>* [`DebtToAssets`](https://skfolio.org/generated/skfolio.descriptor.DebtToAssets.html.md#skfolio.descriptor.DebtToAssets)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Size             | * [`LogMarketCap`](https://skfolio.org/generated/skfolio.descriptor.LogMarketCap.html.md#skfolio.descriptor.LogMarketCap)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Momentum         | * [`EWMomentum`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum)<br/>* [`RollingMomentum`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Reversal         | * [`Reversal`](https://skfolio.org/generated/skfolio.descriptor.Reversal.html.md#skfolio.descriptor.Reversal)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Volatility       | * [`EWVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWVolatility.html.md#skfolio.descriptor.EWVolatility)<br/>* [`EWResidualVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWResidualVolatility.html.md#skfolio.descriptor.EWResidualVolatility)<br/>* [`EWDownsideVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideVolatility.html.md#skfolio.descriptor.EWDownsideVolatility)<br/>* [`EWResidualDownsideVolatility`](https://skfolio.org/generated/skfolio.descriptor.EWResidualDownsideVolatility.html.md#skfolio.descriptor.EWResidualDownsideVolatility)                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Sensitivity      | * [`EWMarketBeta`](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#skfolio.descriptor.EWMarketBeta)<br/>* [`EWMacroSensitivity`](https://skfolio.org/generated/skfolio.descriptor.EWMacroSensitivity.html.md#skfolio.descriptor.EWMacroSensitivity)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Downside risk    | * [`EWDownsideBeta`](https://skfolio.org/generated/skfolio.descriptor.EWDownsideBeta.html.md#skfolio.descriptor.EWDownsideBeta)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Liquidity        | * [`EWShareTurnover`](https://skfolio.org/generated/skfolio.descriptor.EWShareTurnover.html.md#skfolio.descriptor.EWShareTurnover)<br/>* [`EWAmihudIlliquidity`](https://skfolio.org/generated/skfolio.descriptor.EWAmihudIlliquidity.html.md#skfolio.descriptor.EWAmihudIlliquidity)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Lottery demand   | * [`MaxReturn`](https://skfolio.org/generated/skfolio.descriptor.MaxReturn.html.md#skfolio.descriptor.MaxReturn)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Short interest   | * [`ShortInterest`](https://skfolio.org/generated/skfolio.descriptor.ShortInterest.html.md#skfolio.descriptor.ShortInterest)<br/>* [`DaysToCover`](https://skfolio.org/generated/skfolio.descriptor.DaysToCover.html.md#skfolio.descriptor.DaysToCover)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

[`Passthrough`](https://skfolio.org/generated/skfolio.descriptor.Passthrough.html.md#skfolio.descriptor.Passthrough) exposes an existing panel field
as a descriptor without transformation, which is useful for vendor-supplied or
externally computed values. Custom descriptors are created by subclassing
[`BaseDescriptor`](https://skfolio.org/generated/skfolio.descriptor.BaseDescriptor.html.md#skfolio.descriptor.BaseDescriptor).

<a id="factor-model-descriptor-input-fields"></a>

Each descriptor requires specific panel fields. The table below covers all fields used
by the built-in descriptors. A model only needs the fields used by the descriptors it
configures.

| Field                     | Description                                                                        |
|---------------------------|------------------------------------------------------------------------------------|
| `returns`                 | Asset returns                                                                      |
| `market_cap`              | Market value of common equity                                                      |
| `adj_close`               | Split-adjusted close price                                                         |
| `adj_volume`              | Split-adjusted traded volume                                                       |
| `adj_shares_outstanding`  | Split-adjusted common shares outstanding                                           |
| `book_equity`             | Common shareholders’ equity                                                        |
| `sales_ttm`               | Trailing 12-month sales                                                            |
| `operating_cash_flow_ttm` | Trailing 12-month operating cash flow                                              |
| `net_income_ttm`          | Trailing 12-month net income                                                       |
| `cost_of_revenue_ttm`     | Trailing 12-month cost of revenue                                                  |
| `ebitda_ttm`              | Trailing 12-month EBITDA                                                           |
| `dividends_ttm`           | Trailing 12-month cash dividends paid on common shares                             |
| `net_buybacks_ttm`        | Trailing 12-month net share repurchases, positive when repurchases exceed issuance |
| `total_assets`            | Total assets                                                                       |
| `total_debt`              | Total debt                                                                         |
| `enterprise_value`        | Enterprise value (market capitalization plus debt minus cash)                      |
| `capex_ttm`               | Trailing 12-month capital expenditures                                             |
| `eps_ntm`                 | Consensus next-12-month earnings per share                                         |
| `dps_ntm`                 | Consensus next-12-month dividends per share                                        |
| `eps_ntm_std`             | Cross-analyst standard deviation of next-12-month EPS estimates                    |
| `short_interest`          | Shares sold short                                                                  |

The `adj_` fields should be split adjusted but not dividend adjusted, since descriptors use them as price and
quantity levels where reinvested dividends would distort the level. The per-share estimate fields `eps_ntm`,
`dps_ntm` and `eps_ntm_std` must share the same split-adjustment basis as `adj_close`,
so that per-share ratios such as forward earnings yield are consistent.

<a id="factor-model-cross-sectional-transformers"></a>

<a id="cross-sectional-transformers"></a>

### Cross-Sectional Transformers

Raw descriptor values have heavy tails and incomparable units (a book-to-price ratio
and a turnover rate are on different scales). Each descriptor is therefore passed
through two cross-sectional transformers before being combined:

* `outlier_transformer`, defaulting to
  [`CSWinsorizer`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer), caps extreme values.
* `scoring_transformer`, defaulting to
  [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler), converts values into
  cross-sectional z-scores.

With the default scoring, each descriptor is centered on the benchmark-weighted
mean (market-cap-weighted by default) and scaled by the equal-weighted standard
deviation. Benchmark-weighted centering gives the benchmark portfolio zero exposure
to every style factor. Equal-weighted scaling keeps the dispersion estimate from
being dominated by the largest assets.

An exposure of 1.0 means the asset is one standard deviation above the
benchmark-weighted average. The zero benchmark exposure determines the
interpretation of the global factor return, described in
[Global Factor and Benchmark Portfolio](https://skfolio.org/user_guide/factor_models.html.md#factor-model-global-factor).
Transform statistics are computed on the estimation universe and applied to the
full coverage universe.

The `transform_by_group` parameter applies both transforms within groups defined by a
categorical panel field (e.g. “industry”, “country”). For example, with
`transform_by_group="industry"`, each descriptor is scored within
its own industry group, making cross-sectional scores more comparable across industries.
This is useful because book-to-price, profitability, leverage, and similar descriptors
can have very different distributions across industries. Group-level scoring also makes
the resulting factor industry-neutral (see [Neutralization](https://skfolio.org/user_guide/factor_models.html.md#factor-model-neutralization))
and prevents a single industry from dominating the factor’s variation.

The following transformers are available:

**Outlier transformers**

* [`CSWinsorizer`](https://skfolio.org/generated/skfolio.preprocessing.CSWinsorizer.html.md#skfolio.preprocessing.CSWinsorizer)
* [`CSTanhShrinker`](https://skfolio.org/generated/skfolio.preprocessing.CSTanhShrinker.html.md#skfolio.preprocessing.CSTanhShrinker)

**Scoring transformers**

* [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler)
* [`CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler)
* [`CSPercentileRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSPercentileRankScaler.html.md#skfolio.preprocessing.CSPercentileRankScaler)

See [Cross-Sectional Transformers](https://skfolio.org/user_guide/cross_sectional_transformers.html.md#cross-sectional-transformers) for details.

<a id="factor-model-neutralization"></a>

<a id="neutralization"></a>

### Neutralization

Style exposures are often correlated with other factors. For example, volatility
correlates with beta, and an un-neutralized value exposure can carry industry tilts.
Neutralization (also called orthogonalization) removes these overlaps, producing “pure”
factor definitions, reducing collinearity in the cross-sectional regression and making
factor returns easier to interpret.

The `neutralize_against` parameter maps each factor (or family) to the target
factors or families. The [example](https://skfolio.org/user_guide/factor_models.html.md#factor-model-code-example) uses:

```python
neutralize_against={
    "non_linear_size": ["size"],
    "volatility": ["beta"],
}
```

Neutralization is a weighted least squares projection. For a style exposure $z$
and target exposures $D$ under benchmark weights $W$:

$$
z^{\perp} = z - D\,(D^\top W D)^{-1}\,D^\top W z
$$

The residual $z^{\perp}$ is orthogonal to the target factors under the
benchmark-weighted inner product and is re-standardized afterwards. Entries are
processed in insertion order such that later entries operate on exposures already
modified by earlier ones.

When the target factors form a one-hot categorical family, the projection reduces
to demeaning within each group. Taking industry as an example, neutralizing a
style against “industry” through `neutralize_against` and scoring it within
industries through `transform_by_group="industry"` will produce the same neutrality
because the exposure has zero benchmark-weighted mean within every industry
($D^\top W z = 0$). The resulting exposures differ only in per-industry
scaling: the projection removes the per-industry mean, while within-industry
scoring also divides each industry by its own standard deviation, keeping the
factor from being dominated by the industry with the largest spread in the raw
descriptor. For one-hot target factors, `transform_by_group` is preferred as it both
normalizes per-industry scale and is cheaper (group demeaning instead of a full
projection). When both are applied, the projection has no effect because the
exposure already satisfies the same orthogonality condition.

<a id="factor-model-diagnostics"></a>

<a id="exposure-diagnostics"></a>

### Exposure Diagnostics

Exposure diagnostics assess the stability and conditioning of the factor
exposure matrix. Strong collinearity between exposures inflates the variance of
the estimated factor returns and can make attribution unstable.
[`exposure_correlation`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.exposure_correlation) reports the
time-average pairwise correlation of exposures,
[`exposure_vif`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.exposure_vif) the per-factor variance inflation
factors and [`exposure_condition_number`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.exposure_condition_number) the
conditioning of the regression design. When zero-sum constraints are active, VIF
and condition number are computed in the reduced full-rank basis.

`exposure_correlation` accepts a `cs_weighting` parameter. The default
`"benchmark"` measures orthogonality in the metric used by neutralization,
`"identity"` (equal weighting) uses a different inner product and can show a
residual correlation of 0.1 to 0.3 even when the factor is exactly
benchmark-neutral, and `"regression"` measures multicollinearity as seen by the
WLS regression.

```python
factor_model.plot_exposure_correlation(families=["market", "style"])
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/factor_model_exposure_correlation.webp"
       alt="Time-average correlation heatmap for market and style factor exposures"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

In the [example](https://skfolio.org/user_guide/factor_models.html.md#factor-model-code-example), the market exposure is constant
(every asset has unit exposure), so its correlation row is uninformative and
displays as zero. Market neutrality is instead guaranteed by benchmark-weighted
centering: every exposure has a zero benchmark-weighted mean, so no factor
carries net market exposure. The volatility-beta correlation and the correlation
between non-linear size and size are zero, as expected from the neutralization.
The remaining correlations are moderate, indicating no redundant factors. The
`families` argument excludes the 44 industry factors for readability. When
included, their correlations with the style factors are zero as well, the result
of within-industry scoring through `transform_by_group="industry"`, and the
industry-industry correlations are slightly negative rather than zero. Each asset
belongs to exactly one industry, so membership in one industry rules out
membership in all others. Zero correlation would mean industry memberships are
independent, while this exclusion is a negative relationship.

[`plot_exposure_stability`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_stability) shows the
cross-sectional correlation of each factor’s exposures between observations
with `step` determining how far apart the observations are sampled (21 by default).
Slow-moving factors (e.g. value, size) should stay highly correlated at a monthly
step. Fast-turnover factors (e.g. reversal, short-term momentum) reshuffle quickly
by construction and naturally show lower stability at that horizon. It is therefore
recommended to assess these factors with a shorter `step` (e.g. 1 to 5 days).

```python
factor_model.plot_exposure_stability(families=["market", "style"])
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/factor_model_exposure_stability.webp"
       alt="Monthly exposure stability through time for market and style factors"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

In the [example](https://skfolio.org/user_guide/factor_models.html.md#factor-model-code-example), monthly stability stays above
0.8 for nearly all factors and dates, with short-lived dips during stress
episodes (e.g. March 2020). Stable exposures keep the risk decomposition
consistent between rebalancings and limit the turnover induced by exposure noise.

[`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel) provides additional exposure diagnostics:

* [`plot_exposure_vif`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_vif)
* [`plot_exposure_condition_number`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_condition_number)
* [`plot_exposure_distribution`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_distribution)
* [`plot_exposure_dispersion`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_exposure_dispersion)

<a id="factor-model-cross-sectional-regression"></a>

<a id="cross-sectional-regression"></a>

## Cross-Sectional Regression

After factor exposures are computed, the cross-sectional regression uses the
exposure tensor of shape `(n_observations, n_assets, n_factors)` together with
the asset return matrix of shape `(n_observations, n_assets)`. For each
observation, the model estimates factor returns and idiosyncratic returns by
regressing the cross-section of asset returns on the corresponding lagged exposures.

<a id="regression-model"></a>

### Regression Model

For each observation $t$, factor returns solve the weighted least squares
problem:

$$
\hat{f}(t) = \arg\min_{f} \sum_{i} w_i(t)\,
\big(R_i(t) - B_i(t - \ell)^\top f\big)^2
$$

where $w_i(t)$ are the weights described in
[Regression Weights](https://skfolio.org/user_guide/factor_models.html.md#factor-model-regression-weights),
$B_i(t - \ell)$ is asset $i$’s lagged exposure vector and $\ell$ is
`exposure_lag`. Idiosyncratic returns are obtained as the regression residuals:

$$
\hat{\epsilon}_i(t) = R_i(t) - B_i(t - \ell)^\top \hat{f}(t)
$$

The regression is performed by `cs_regressor`, defaulting to
[`CSLinearRegression`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegression.html.md#skfolio.linear_model.CSLinearRegression), a weighted least-squares
estimator that solves all observations in one vectorized pass over the exposure
tensor. For robust or regularized cross-sectional estimation, skfolio allows
scikit-learn-compatible estimators (e.g. `HuberRegressor` for outlier-robust
regression) to be passed through
[`CSLinearRegressorWrapper`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper), which applies the
wrapped estimator separately to each observation.

#### NOTE
Unlike factor exposures, which are typically winsorized and standardized by
the exposure estimators, asset returns enter the cross-sectional regression
unadjusted. Cleaning return data errors is an upstream responsibility, since
the same returns drive benchmark weights, realized performance and downstream
optimization. Winsorizing legitimate extreme returns would break the
reconciliation of $R = B\,f + \epsilon$ and understate idiosyncratic
risk for heavy-tailed assets. Extreme observations are already moderated by
regression weights (`regression_mcap_power` and `inv_idio_variance_weight_shrinkage`).
When the factor-return regression needs to further reduce the influence of extreme
asset returns, use a robust regressor such as `HuberRegressor` through
[`CSLinearRegressorWrapper`](https://skfolio.org/generated/skfolio.linear_model.CSLinearRegressorWrapper.html.md#skfolio.linear_model.CSLinearRegressorWrapper) as described above.

<a id="factor-model-regression-weights"></a>

<a id="regression-weights"></a>

### Regression Weights

Idiosyncratic returns are heteroskedastic, meaning idiosyncratic variance differs widely
across the cross-section. An unweighted regression would give excessive influence to the
noisiest names. Under heteroskedasticity, the best linear unbiased estimator (BLUE) is the
weighted least squares regression whose weights are proportional to inverse idiosyncratic
variance, known as generalized least squares (GLS).

Idiosyncratic variances are not observable before the regression is run. It is common practice
to approximate the inverse-variance weights with square-root market-cap weights (empirically,
idiosyncratic variance decreases roughly as the inverse square root of market capitalization).
The `regression_mcap_power` parameter controls this weighting as a power
$p$ of market capitalization:

$$
w_i \propto \mathrm{mcap}_i^{\,p}
$$

with `0.5` (default) for square-root cap weighting, `0.0` for equal weighting and
`1.0` for cap weighting. Market cap moves with the return being regressed,
$\mathrm{mcap}_i(t) \approx \mathrm{mcap}_i(t-1)\,(1 + R_i(t))$, and
weighting the regression at $t$ by caps at $t$ would correlate the
weights with the regressed returns and bias the estimated factor returns.
Because of this, market caps are also lagged by `exposure_lag`.

The model also supports inverse-idiosyncratic-variance weighting with a two-step
feasible GLS. A first pass runs with the cap-based weights and then the variances
estimated from its residuals (up to $t - 1$ only) feed the weights of the
second pass. The regression weights never depend on their own output, avoiding
the feedback loop of recursive weighting schemes where a low estimated variance
increases an asset’s weight and, in turn, its influence on later residuals.
`inv_idio_variance_max_weight_ratio` (default 20) caps each inverse-variance
weight at a multiple of the cross-sectional median, preventing assets with very
low estimated variance from dominating the regression.

Estimated variances are noisy, and `inv_idio_variance_weight_shrinkage` blends
the two weightings for robustness:

$$
w_i = \lambda\,w_i^{\text{inv-var}} + (1 - \lambda)\,w_i^{\text{cap}}
$$

where $\lambda = 0$ (default) uses the cap-based weights only and
$\lambda = 1$ the inverse-variance weights only.

The weights used at each date are stored in `factor_model_.regression_weights`: row
$t$ holds the weights used by the regression at $t$, built from market
caps at $t - \ell$ and idiosyncratic variances estimated up to $t - 1$.

<a id="factor-model-zero-sum-constraints"></a>

<a id="zero-sum-constraints"></a>

### Zero-Sum Constraints

One-hot factor families are exactly collinear with the global factor: each
asset’s industry exposures sum to one, which is the global exposure. Including
both leaves the factor returns unidentified as adding a constant to every industry
return and subtracting it from the global return leaves the fit unchanged, and
the exposure design is rank-deficient.

The `constrained_families` parameter resolves this by imposing a benchmark-weighted
zero-sum constraint on the factor returns of each constrained family. Economically,
the global factor captures the benchmark portfolio return and the constrained family
factors capture relative effects around it.

Each tuple `(family, factor_to_drop)` specifies a family to reparameterize.
Instead of solving a constrained regression, the model applies an equivalent
change of basis. For a constrained family with exposure columns $x_j$ and
factor returns $\beta_j$, the constraint reads
$\sum_j w_j \beta_j = 0$, where $w_j$ is the benchmark weight
aggregated per factor (for one-hot industries, the benchmark weight of each
industry). Solving the constraint for one factor $k$ and substituting into
the regression yields an unconstrained regression on transformed features
$z_j$, with the dropped factor’s return reconstructed from the constraint
after fitting:

$$
z_j = x_j - \frac{w_j}{w_k}\,x_k,
\qquad
\hat{\beta}_k = -\frac{1}{w_k} \sum_{j \neq k} w_j \hat{\beta}_j
$$

The full family is reported with no loss of information, and all downstream
computations such as the factor covariance estimator and the
[regression diagnostics](https://skfolio.org/user_guide/factor_models.html.md#factor-model-regression-diagnostics) (t-statistics,
VIF, condition number, adjusted $R^2$) operate on a full-rank design.
Any choice of $k$ yields the same constrained solution. When `factor_to_drop` is `None`,
the model drops the factor with the largest $|w_k|$, keeping the ratios
$|w_j / w_k|$ bounded by 1.0 for most factors and preserving the
conditioning of the reduced design. The basis is stored in
`factor_model_.family_constraint_basis` and follows the same timing as the
regression. Realized factor returns are reconstructed with the lagged ratios used
by the regression, while expected factor returns and covariance are expanded with
the latest as-of basis.

<a id="factor-model-global-factor"></a>

<a id="global-factor-and-benchmark-portfolio"></a>

### Global Factor and Benchmark Portfolio

Under the exposure centering and zero-sum constraints described in
[Zero-Sum Constraints](https://skfolio.org/user_guide/factor_models.html.md#factor-model-zero-sum-constraints), the global
factor return captures the benchmark portfolio return. Aggregating the
cross-sectional regression over the assets $i$ of the estimation
universe under benchmark weights gives (time indices omitted):

$$
\underbrace{\sum_i w_i^{\text{bench}} R_i}_{\text{benchmark return}}
= \hat{f}_0
+ \underbrace{\sum_{j \in \text{industry, country}} w_j\,\hat{f}_j}_{=\,0
\text{ (zero-sum constraint)}}
+ \sum_{j \in \text{styles}} \underbrace{\Big(\sum_i w_i^{\text{bench}}
B_{ij}\Big)}_{=\,0 \text{ (benchmark-centered)}} \hat{f}_j
+ \underbrace{\sum_i w_i^{\text{bench}}\,\hat{\epsilon}_i}_{\approx\,0}
$$

where $\hat{f}_0$ is the global factor return, $\hat{f}_j$ the
other factor returns, $B_{ij}$ the exposure of asset $i$ to factor
$j$ and $\hat{\epsilon}_i$ its idiosyncratic return.

* For a constrained one-hot family such as industry or country, the benchmark
  exposure to factor $j$ is the total benchmark weight of the assets in
  that category, $w_j = \sum_i w_i^{\text{bench}} B_{ij}$ (the industry
  cap share when `benchmark_mcap_power=1`). The family term
  $\sum_j w_j \hat{f}_j$ is the benchmark-weighted average of the
  family’s factor returns, set to zero by the zero-sum constraint.
* Style exposures are centered so that the benchmark-weighted average
  exposure $\sum_i w_i^{\text{bench}} B_{ij}$ is zero (the default
  [`CSStandardScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSStandardScaler.html.md#skfolio.preprocessing.CSStandardScaler) behavior). The benchmark
  has no style tilt and style factor returns do not contribute to its
  return.
* The residual term is the benchmark-weighted average of the idiosyncratic
  returns. The weighted residuals sum to zero under the regression weights,
  and the remaining difference between benchmark and regression weights is
  diversified across the cross-section.

The estimated global factor return tracks the benchmark portfolio return on
the estimation universe (e.g. the market-cap portfolio when
`benchmark_mcap_power=1`), with deviations limited to the residual term when
regression weights differ from benchmark weights. When
`regression_mcap_power == benchmark_mcap_power` and
`inv_idio_variance_weight_shrinkage == 0`, the regression weights are
proportional to the benchmark weights and the residual term is exactly zero:
the WLS normal equations make the weighted residuals orthogonal to every
column of the exposure design, including the global column of ones, so
$\sum_i w_i^{\text{bench}} \hat{\epsilon}_i = 0$ and the identity is
exact:

$$
\hat{f}_0(t) = \sum_i w_i^{\text{bench}}\,R_i(t)
$$

The benchmark weights are stored in `factor_model_.benchmark_weights`. Under this
structure, each factor return reads as a portfolio return relative to the
benchmark. The global factor is the benchmark return itself. An industry factor
return is a benchmark-relative industry effect meaning it captures the return earned by that industry
in excess of the benchmark, net of the other factors. A style factor return is the
return to a standardized characteristic tilt, representing the return earned by holding one
standard deviation of exposure to that characteristic while keeping all other
factor exposures at zero.

<a id="factor-model-missing-data"></a>

<a id="missing-data-and-changing-universes"></a>

### Missing Data and Changing Universes

Because the regression is re-estimated independently at each date, changing universes
are handled naturally, with newly listed assets joining the regression as soon as their
exposures are available, delisted assets dropping out, and assets on holiday
excluded for that date only. No realignment or imputation is needed.

At each date, an asset participates in the regression when it belongs to the
estimation universe and its lagged exposures and return are finite. All other pairs
receive zero regression weight. Assets outside the estimation universe still receive
exposures, idiosyncratic returns and forecasts where computable.

As a guard against underspecified regressions, `min_regression_assets` sets the
minimum number of participating assets required at every observation after the
[warmup period](https://skfolio.org/user_guide/factor_models.html.md#factor-model-warmup) (default
`max(2 * n_factors, 30)`). A ValueError is raised when a cross-section falls below
this minimum.

<a id="factor-model-currency-factors"></a>

<a id="currency-factors"></a>

### Currency Factors

In a multi-currency universe, asset returns in the investor’s numeraire mix equity
risk with currency risk. The model separates the two components by estimating non-currency
factors from local excess returns and adding currency risk through dedicated currency factors.

The `currency_factor` parameter takes a one-hot exposure estimator on the asset currency
field (typically [`OneHotCategoricalFactors`](https://skfolio.org/generated/skfolio.factor_exposure.OneHotCategoricalFactors.html.md#skfolio.factor_exposure.OneHotCategoricalFactors)),
and the `currency_excess_returns` argument of `fit` supplies the currency excess return
series. The base-currency excess return of asset $i$ decomposes as:

$$
R^{excess,base}_i(t) = R^{excess,local}_i(t) + R^{ccy}_{C_i(t)}(t)
$$

where $R^{excess,local}_i(t)$ is the asset’s local-currency return in
excess of the cash rate of its currency $C_i(t)$ and
$R^{ccy}_{C_i(t)}(t)$ is the currency excess return from converting that
local-currency asset return into the investor’s base currency:

$$
R^{ccy}_{C_i(t)}(t) = R^{FX}_{C_i(t)}(t) + r^{cash}_{C_i(t)}(t)
- r^{cash}_{base}(t) + R^{local}_i(t)\,R^{FX}_{C_i(t)}(t)
$$

The identity follows from compounding the local return with the FX return and
subtracting the cash rates defining each excess return (time indices omitted):

$$
R^{base}_i &= (1 + R^{local}_i)(1 + R^{FX}_{C_i}) - 1
= R^{local}_i + R^{FX}_{C_i} + R^{local}_i\,R^{FX}_{C_i} \\
R^{excess,base}_i &= R^{base}_i - r^{cash}_{base} \\
&= \big(R^{local}_i - r^{cash}_{C_i}\big)
+ R^{FX}_{C_i} + r^{cash}_{C_i} - r^{cash}_{base}
+ R^{local}_i\,R^{FX}_{C_i} \\
&= R^{excess,local}_i + R^{ccy}_{C_i}
$$

The currency excess return series are computed by the user and supplied through
`currency_excess_returns`, with one column per currency factor.

Unlike equity factor returns, currency factor returns are not estimated by the
regression but instead are observed FX series in the investor’s numeraire which are then
appended directly to the factor return distribution with family `"currency"`. The factor
covariance then captures both equity and currency factor risk, and each asset loads
on its currency through the one-hot exposures.

<a id="factor-model-regression-diagnostics"></a>

<a id="regression-diagnostics"></a>

### Regression Diagnostics

[`plot_factor_cumulative_returns`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_factor_cumulative_returns) displays the
estimated factor returns accumulated through time:

```python
fig = factor_model.plot_factor_cumulative_returns(families=["market", "style"])
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/factor_model_factor_cumulative_returns.webp"
       alt="Cumulative realized returns through time for market and style factors"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

Summary statistics of the style factors from the fitted model:

```python
factor_model.summary(families="style")[
    ["annualized_mean", "annualized_vol", "annualized_sharpe", "mean_vif"]
]
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>annualized_mean</th>
      <th>annualized_vol</th>
      <th>annualized_sharpe</th>
      <th>mean_vif</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>beta</th>
      <td>0.015</td>
      <td>0.056</td>
      <td>0.265</td>
      <td>1.530</td>
    </tr>
    <tr>
      <th>momentum</th>
      <td>0.028</td>
      <td>0.044</td>
      <td>0.622</td>
      <td>1.461</td>
    </tr>
    <tr>
      <th>size</th>
      <td>0.016</td>
      <td>0.041</td>
      <td>0.385</td>
      <td>3.658</td>
    </tr>
    <tr>
      <th>non_linear_size</th>
      <td>-0.016</td>
      <td>0.019</td>
      <td>-0.833</td>
      <td>1.518</td>
    </tr>
    <tr>
      <th>value</th>
      <td>-0.001</td>
      <td>0.019</td>
      <td>-0.072</td>
      <td>2.324</td>
    </tr>
    <tr>
      <th>earnings_yield</th>
      <td>0.012</td>
      <td>0.023</td>
      <td>0.530</td>
      <td>1.958</td>
    </tr>
    <tr>
      <th>growth</th>
      <td>-0.004</td>
      <td>0.016</td>
      <td>-0.228</td>
      <td>1.330</td>
    </tr>
    <tr>
      <th>profitability</th>
      <td>0.007</td>
      <td>0.015</td>
      <td>0.443</td>
      <td>1.814</td>
    </tr>
    <tr>
      <th>investment</th>
      <td>0.003</td>
      <td>0.011</td>
      <td>0.294</td>
      <td>1.256</td>
    </tr>
    <tr>
      <th>dividend_yield</th>
      <td>0.002</td>
      <td>0.015</td>
      <td>0.114</td>
      <td>1.518</td>
    </tr>
    <tr>
      <th>leverage</th>
      <td>-0.004</td>
      <td>0.016</td>
      <td>-0.225</td>
      <td>1.248</td>
    </tr>
    <tr>
      <th>liquidity</th>
      <td>0.012</td>
      <td>0.032</td>
      <td>0.379</td>
      <td>4.587</td>
    </tr>
    <tr>
      <th>volatility</th>
      <td>-0.001</td>
      <td>0.032</td>
      <td>-0.046</td>
      <td>1.900</td>
    </tr>
  </tbody>
</table>
</div>

In the [example](https://skfolio.org/user_guide/factor_models.html.md#factor-model-code-example), momentum carries the highest
annualized Sharpe ratio (0.62) and the largest cumulative return, with the sharp
2020 reversal characteristic of momentum crashes. The beta, size, earnings yield
and profitability factors show positive premia over the sample while value is
flat. The mean VIFs are all below 5, consistent with the moderate exposure
correlations observed in [Exposure Diagnostics](https://skfolio.org/user_guide/factor_models.html.md#factor-model-diagnostics).

#### NOTE
These are pure-factor returns, not sorted long-short factor portfolio returns
such as the Fama-French factors. Their numerical scale is generally smaller
than that of familiar academic factor portfolios. Each factor return can be
interpreted as the return of a factor-mimicking portfolio constructed by the
cross-sectional regression. This portfolio is not rescaled to a fixed gross
exposure or volatility, whereas academic factors are often constructed as
100% long and 100% short (200% gross exposure) and may carry several units
of factor exposure together with incidental exposures to other factors.
Factor-return series should therefore only be compared after matching
exposure scaling and portfolio normalization conventions. Sharpe ratios are
more comparable because rescaling changes the mean and volatility proportionally.

In a characteristics factor model, each factor return is the cross-sectional
regression coefficient for one unit of exposure. For style factors built from
standardized exposures, this corresponds to one cross-sectional standard
deviation of exposure after winsorization, within-industry scoring and
neutralization. Equivalently, the factor-mimicking portfolio has unit
exposure to that factor and zero exposure to the other factors.

Factor-return signs follow the exposure convention. The size factor is built
from `LogMarketCap`, so a positive size factor return means large-cap
exposure was rewarded, the opposite of the Fama-French small-minus-big
convention. The sign convention only matters when comparing to external
factor series and it does not affect covariance decomposition, attribution or
optimization because exposures and factor returns are used consistently
within the model.

[`cs_regression_scores`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.cs_regression_scores) returns per-observation
fit statistics: `r2`, `adjusted_r2` (adjusted for the effective number of
regressors, reduced when constraints are active), `aic` and `bic`.

```python
factor_model.cs_regression_scores.mean()
```

```text
r2                 0.312856
adjusted_r2        0.278087
aic           -10183.548079
bic            -9894.130723
```

[`plot_cs_regression_scores`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_cs_regression_scores) displays them
through time:

```python
factor_model.plot_cs_regression_scores(score="adjusted_r2", window=20)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/factor_model_cs_regression_scores_adjusted_r2.webp"
       alt="Rolling 20-day adjusted R-squared of the daily cross-sectional factor regressions"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The mean $R^2$ is an in-sample quantity and does not account for model
complexity or overfitting, making it a weak measure of model quality. It does however
remain useful as a sanity check. For daily US equity models, the mean $R^2$ typically
falls between 25% and 40% and the mean adjusted $R^2$ between 20% and 35%.
Values outside these ranges typically warrant investigation. Three caveats apply:

* A mean $R^2$ of 30% does not mean the model explains only 30% of portfolio risk:
  the daily cross-sectional $R^2$ is an in-sample fit statistic for that
  day’s stock returns, while a portfolio’s risk can still be dominated by common
  factors because idiosyncratic terms diversify away and factor terms do not.
* Some vendors report $R^2$ on monthly returns, which is mechanically higher than
  on daily returns, and figures are only comparable at the same frequency.
* $R^2$ should not be used to compare different models as the addition of any
  factor will lead to a larger value.

[`cs_regression_t_stats`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.cs_regression_t_stats) returns the
per-observation t-statistic of each factor return, computed in the reduced basis
when constraints are active. Values of $|t| > 2$ indicate significance at
approximately the 5% level.
[`plot_cs_regression_t_stats`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_cs_regression_t_stats) displays them
through time.

[`cs_regression_t_stat_exceedance_rate`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.cs_regression_t_stat_exceedance_rate)
aggregates this through time. A factor whose true coefficient is zero would
exceed the threshold about 5% of the time. Rates persistently above this
reference indicate a factor that is repeatedly significant in the cross-section.
[`plot_cs_regression_t_stat_exceedance_rate`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_cs_regression_t_stat_exceedance_rate)
displays the exceedance rates:

```python
factor_model.plot_cs_regression_t_stat_exceedance_rate(families=["market", "style"])
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/factor_model_cs_regression_t_stat_exceedance_rate.webp"
       alt="Share of dates on which each market or style factor return has an absolute t-statistic above two"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

<a id="factor-model-risk-forecasting"></a>

<a id="risk-forecasting"></a>

## Risk Forecasting

The risk forecast combines the distribution of factor returns and the idiosyncratic risk of each asset.
This section details their estimation and how they are assembled into the asset covariance and
return scenarios.

<a id="factor-model-factor-return-distribution"></a>

<a id="factor-return-distribution"></a>

### Factor Return Distribution

The estimated factor return time series is passed to `factor_prior_estimator`, a
[prior estimator](https://skfolio.org/user_guide/prior.html.md#prior) that produces the expected factor returns (factor
premia), the factor covariance and factor return scenarios. When zero-sum constraints
are present, the estimation runs in the reduced full-rank basis, making the factor
covariance positive definite by construction.

The default is [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior) with
[`EWMu`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu) for expected returns and
[`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance) for covariance. The latter
addresses two known weaknesses of plain exponentially weighted covariance:

* It applies a scalar regime multiplier (Short-Term Volatility Update) that improves
  risk calibration when volatility regimes change faster than the EWMA half-life can
  track.
* It supports separate half-lives for variance and correlation. Empirically,
  volatility mean-reverts faster than correlation: a shorter variance half-life adapts
  quickly to volatility shifts while a longer correlation half-life reduces
  estimation noise on co-movements.

It also supports optional Newey-West HAC correction through `hac_lags` to adjust for
serial correlation in factor returns.

Because the factor return series is low-dimensional ($K \ll N$), estimators
that would be unstable or expensive on thousands of assets are cheap and reliable on
factors. The factor prior is fully replaceable, e.g. covariance shrinkage or denoising can
be applied at the factor level, and views on factors can be expressed by using
[`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling) or [`OpinionPooling`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling) as
`factor_prior_estimator`. The factor return scenarios produced here feed
scenario-based risk measures (e.g. CVaR) downstream.

[`plot_factor_forecast_correlation`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_factor_forecast_correlation) shows the
factor return correlation forecast from the fitted factor covariance. High values
flag factors whose returns move together and carry overlapping risk. Industry
factors are omitted below for readability:

```python
factor_model.plot_factor_forecast_correlation(families=["market", "style"])
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/factor_model_factor_forecast_correlation.webp"
       alt="Forecast return correlation heatmap for market and style factors"
       width="1100" height="616"
       loading="eager" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

In the [example](https://skfolio.org/user_guide/factor_models.html.md#factor-model-code-example), most correlations are
moderate, indicating that the factors capture distinct risk dimensions. The 0.80 market-beta
correlation is the known exception. The beta factor return is the
reward for holding high-beta names over low-beta names, a spread that widens in
rising markets and reverses in falling markets, making it co-move with the market return
by construction. The two factors remain separated in the regression because their
exposures are near-orthogonal in the cross-section, and the co-movement of their
returns is captured by the factor covariance.

[`plot_factor_forecast_volatilities`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_factor_forecast_volatilities) shows each
factor’s annualized volatility forecast which is calculated as the square root
of the factor covariance diagonal. It ranks the factors by their standalone risk
contribution:

```python
factor_model.plot_factor_forecast_volatilities(families=["market", "style"])
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/factor_model_factor_forecast_volatilities.webp"
       alt="Annualized forecast volatilities for market and style factors"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The market factor dominates at close to 20% annualized volatility. Its return is
the benchmark return, while style factor returns are long-short spreads across
standardized exposures. The beta, momentum, size and liquidity factors form the
next tier around 5% to 8%, and the remaining styles sit near 2%.

<a id="idiosyncratic-risk"></a>

### Idiosyncratic Risk

Per-asset idiosyncratic variances are estimated from the idiosyncratic returns by
`idio_variance_estimator`, defaulting to
[`RegimeAdjustedEWVariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance). The estimator must support
`partial_fit` so the model can recover per-asset variance estimates at each
observation, stored in `factor_model_.idio_variances`. Assets still in their
[warmup period](https://skfolio.org/user_guide/factor_models.html.md#factor-model-warmup) have NaN variances, which propagate
to the fitted moments and mark them as not yet investable.

A factor model assumes the factor structure captures all common risk, leaving
idiosyncratic returns uncorrelated across assets. The idiosyncratic covariance is
therefore diagonal by default. In practice, linked securities remain correlated
after the factor structure is removed (e.g. multiple share classes, ADRs versus
ordinary shares, or dual listings). Without correction, optimizers treat such
pairs as diversified sources of idiosyncratic risk and may over-allocate to them.

Correlation thresholding addresses these cases. When `idio_corr_threshold` is set to
$\tau > 0$, the `idio_corr_estimator` (defaulting to
[`EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance)) is fitted on idiosyncratic returns
standardized by their contemporaneous idiosyncratic volatility. Only the correlation
component of its output is retained: off-diagonal correlations with
$|\rho_{ij}| \le \tau$ are set to zero, and the surviving correlations are
recombined with the latest per-asset variances to form a sparse idiosyncratic
covariance. Variances and correlations are estimated separately because a single full
covariance estimator would mix per-asset variance estimation with off-diagonal
correlation noise. This keeps variances driven by `idio_variance_estimator` and
applies the correlation overlay only where residual correlations are large enough to
retain.

Persistent residual correlation across a broader group, such as sub-industry
peers under a coarse industry classification, signals a missing factor rather
than a thresholding problem. Adding the factor keeps the idiosyncratic covariance
sparse, while lowering $\tau$ to absorb the group reintroduces the
estimation noise the diagonal assumption avoids.

<a id="idiosyncratic-risk-calibration"></a>

### Idiosyncratic Risk Calibration

These diagnostics test the idiosyncratic volatility forecasts through the
standardized idiosyncratic returns
$z_{it} = \epsilon_{it} / \hat\sigma_{it}$. Under correct calibration,
$z$ has cross-sectional standard deviation 1.0.

[`idio_calibration_summary`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.idio_calibration_summary) aggregates the main
statistics:

* `mean_cs_std` close to 1.0 indicates correctly scaled idiosyncratic risk. Values
  persistently above 1.0 indicate underestimated risk and persistently below 1.0
  indicate overestimated risk.
* `mean_tail_rate_3sigma` is the fraction of standardized returns beyond three
  standard deviations. The Gaussian reference is 0.27%, and values of 1% to 3% are
  common for equity factor models due to fat tails.
* `mean_cs_excess_kurtosis` above zero and a moderate `mean_cs_skewness` are typical.

Two complementary statistics separate ranking power from calibration.
[`idio_vol_ic`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.idio_vol_ic) is the Spearman correlation between
predicted volatility and the next-period absolute idiosyncratic return with high
values meaning that the model ranks cross-sectional volatility differences well.
[`idio_vol_residual_dependence`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.idio_vol_residual_dependence) is the same
correlation after standardizing the next-period return by the predicted
volatility: under correct calibration it should be close to 0. The desirable
pattern is a high `idio_vol_ic` combined with residual dependence near 0.

[`plot_idio_calibration`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_calibration) tracks the
cross-sectional standard deviation of the standardized returns through time:

```python
factor_model.plot_idio_calibration(window=20)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/factor_model_idio_calibration.webp"
       alt="Rolling cross-sectional standard deviation of standardized idiosyncratic returns relative to the calibration target"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

In the [example](https://skfolio.org/user_guide/factor_models.html.md#factor-model-code-example), the series oscillates around a
mean of 1.06, a slight average underestimation of idiosyncratic risk. The spike
above 1.5 at the COVID shock shows realized dispersion outrunning the forecasts,
followed by a dip below 0.7 as the variance estimator caught up while volatility
dissipated.

[`plot_idio_vol_ic`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_vol_ic) displays the volatility rank
IC through time:

```python
factor_model.plot_idio_vol_ic()
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/factor_model_idio_vol_ic.webp"
       alt="Information coefficient through time for predicted versus realized idiosyncratic volatility ranks"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The rolling mean holds near 0.4 across the sample: the model consistently
forecasts higher volatility for assets that subsequently realize larger
idiosyncratic moves. Together with the calibration series close to 1.0, the
idiosyncratic risk forecasts are both well ordered and well scaled.

[`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel) provides additional idiosyncratic risk
diagnostics:

* [`plot_idio_tail_rate`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_tail_rate)
* [`plot_idio_kurtosis`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_kurtosis)
* [`plot_idio_skewness`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_skewness)
* [`plot_idio_vol_residual_dependence`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_idio_vol_residual_dependence)

<a id="factor-model-asset-covariance-forecast"></a>

<a id="asset-covariance-forecast"></a>

### Asset Covariance Forecast

The asset covariance forecast assembles the pieces estimated above:

$$
\Sigma = B(T)\,F\,B(T)^\top + D
$$

where $B(T)$ is the latest loading matrix, $F$ the factor covariance
and $D$ the idiosyncratic covariance. The result is positive definite and
well conditioned by construction as the systematic part is low-rank positive
semidefinite and $D$ is positive diagonal (or sparse positive definite).

Asset return scenarios follow the same construction. Factor scenarios from the
factor prior are mapped through the latest loading matrix, and idiosyncratic
scenarios calibrated to the latest idiosyncratic risk forecast are added on top.
Optimizers using scenario-based risk measures (e.g. CVaR) therefore see both
return components.

skfolio exploits this structure when passing the asset covariance to downstream
optimizers. Portfolio variance splits into a factor contribution and an
idiosyncratic contribution:

$$
w^\top \Sigma\, w
= \lVert F^{1/2} B^\top w \rVert^2 + \lVert D^{1/2} w \rVert^2
$$

Both terms involve only small matrices: the $n \times K$ loading matrix,
the $K \times K$ factor covariance and the $n$ idiosyncratic
variances. skfolio’s convex optimizers build their risk constraints on these
directly, through `factor_model_.covariance_sqrt`, instead of assembling and
factorizing the dense $n \times n$ covariance. On a universe of thousands
of assets driven by a few dozen factors, this keeps the risk constraints small
and the optimization fast.

<a id="factor-model-covariance-forecast-evaluation"></a>

<a id="covariance-forecast-evaluation"></a>

### Covariance Forecast Evaluation

In-sample fit does not measure forecast accuracy. The covariance forecast is
evaluated out of sample with
[`covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.covariance_forecast_evaluation.html.md#skfolio.model_selection.covariance_forecast_evaluation) or, using online
learning for speed, [`online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation).
Both walk forward through the data, compare each covariance forecast with the
subsequently realized returns over an evaluation window and return a
[`CovarianceForecastEvaluation`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation) with summary
statistics and plots. Four diagnostics are computed:

* The **Mahalanobis calibration ratio** tests the full covariance structure across
  all eigenvalue directions. The target is 1.0, with values above 1.0 indicating
  underestimated risk and below 1.0 indicating overestimated risk.
* The **diagonal calibration ratio** applies the same test to individual asset
  variances, ignoring correlations.
* The **portfolio bias statistic** tests covariance calibration along
  user-supplied portfolio directions. For each test portfolio, realized
  portfolio returns are divided by their forecast volatility, and the standard
  deviation of that standardized series should be 1.0 under correct
  calibration. Evaluating several representative portfolios can reveal
  direction-specific under or over-estimated risk.
* The **portfolio QLIKE** scores portfolio variance forecasts, with lower values
  indicating better forecasts.

The figures below evaluate the model with
[`online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation) and
`test_size=5`:

```python
from skfolio.model_selection import online_covariance_forecast_evaluation

evaluation = online_covariance_forecast_evaluation(
    model,
    X,
    params={"characteristics": characteristics},
    warmup_size=2 * 252 + 21,
    test_size=5,
)
evaluation.plot_calibration()
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/covariance_eval_calibration.webp"
       alt="Rolling Mahalanobis, diagonal and portfolio bias calibration ratios for the covariance forecast"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

In the [example](https://skfolio.org/user_guide/factor_models.html.md#factor-model-code-example), the diagonal ratio and the bias
statistic oscillate around the target, implying individual asset variances and
test-portfolio volatilities are well scaled. The Mahalanobis ratio stays near 1.5,
indicating that the remaining underestimation is concentrated in the covariance’s
low-variance directions. The Mahalanobis distance gives more weight to errors in
those directions, while the diagonal ratio and portfolio bias statistic are less
sensitive to them. All three ratios spike at the 2020 shock. The diagonal ratio and
bias statistic then fall below 1.0 through 2021 as the forecasts lag the post-crisis
decline in volatility, while the Mahalanobis ratio falls back toward its target
without crossing it. This low-variance underestimation originates mostly in the
idiosyncratic block (residual correlations and missing factors) and is addressed
with `idio_corr_threshold` and the optimizer-level regularization covered in
[Orthogonal Space Regularization](https://skfolio.org/user_guide/factor_models.html.md#factor-model-orthogonal-space-regularization).

The summary table aggregates the four diagnostics over the full evaluation
period:

```python
evaluation.summary()
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>mean</th>
      <th>median</th>
      <th>std</th>
      <th>p5</th>
      <th>p95</th>
      <th>mad_from_target</th>
      <th>target</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Mahalanobis ratio</th>
      <td>1.505</td>
      <td>1.320</td>
      <td>0.789</td>
      <td>0.672</td>
      <td>2.969</td>
      <td>0.606</td>
      <td>1.000</td>
    </tr>
    <tr>
      <th>Diagonal ratio</th>
      <td>1.087</td>
      <td>0.921</td>
      <td>0.817</td>
      <td>0.349</td>
      <td>2.207</td>
      <td>0.453</td>
      <td>1.000</td>
    </tr>
    <tr>
      <th>Portfolio standardized returns</th>
      <td>0.096</td>
      <td>0.140</td>
      <td>0.917</td>
      <td>-1.545</td>
      <td>1.360</td>
      <td>0.695</td>
      <td>mean=0, std=1</td>
    </tr>
    <tr>
      <th>Portfolio QLIKE</th>
      <td>-6.411</td>
      <td>-6.696</td>
      <td>1.700</td>
      <td>-7.919</td>
      <td>-4.387</td>
      <td></td>
      <td>lower is better</td>
    </tr>
  </tbody>
</table>
</div>

[`CovarianceForecastEvaluation`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation) provides
additional plots:

* [`plot_qlike_loss`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.plot_qlike_loss)
* [`plot_exceedance`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation.plot_exceedance)

[`CovarianceForecastComparison`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison) runs the same
evaluation over several models and aggregates the results for side-by-side
comparison. Missing data follows the panel conventions: only finite observations
contribute and inactive assets are excluded.

The comparison below contrasts two
[`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance) regime half-lives for the
factor prior: `regime_half_life=month` (21 trading days) against
`regime_half_life=quarter` (63 trading days), which reacts more slowly to
volatility regime shifts.

```python
from skfolio.model_selection import CovarianceForecastComparison

comparison = CovarianceForecastComparison(
    [eval_month, eval_quarter],
    names=["regime_half_life=month", "regime_half_life=quarter"],
)
comparison.plot_calibration(diagnostics=("bias",))
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/covariance_cmp_calibration.webp"
       alt="Rolling covariance forecast bias for models with one-month and one-quarter regime half-lives"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>
```python
comparison.plot_qlike_loss()
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/covariance_cmp_qlike_loss.webp"
       alt="Rolling QLIKE loss for covariance models with one-month and one-quarter regime half-lives"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The shorter month half-life adapts faster, its bias statistic overshoots less at
the 2020 shock, recovers sooner from the 2021 over-forecast and its QLIKE loss is
lower through the 2020-2021 stress. In calm periods the two models are nearly
indistinguishable, and the summary table shows similar aggregate diagnostics, with
the month half-life slightly lower on mean QLIKE.

```python
comparison.summary()
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr>
      <th>estimator</th>
      <th colspan="7" halign="left">regime_half_life=month</th>
      <th colspan="7" halign="left">regime_half_life=quarter</th>
    </tr>
    <tr>
      <th></th>
      <th>mean</th>
      <th>median</th>
      <th>std</th>
      <th>p5</th>
      <th>p95</th>
      <th>mad_from_target</th>
      <th>target</th>
      <th>mean</th>
      <th>median</th>
      <th>std</th>
      <th>p5</th>
      <th>p95</th>
      <th>mad_from_target</th>
      <th>target</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Mahalanobis ratio</th>
      <td>1.505</td>
      <td>1.320</td>
      <td>0.789</td>
      <td>0.672</td>
      <td>2.969</td>
      <td>0.606</td>
      <td>1.000</td>
      <td>1.504</td>
      <td>1.310</td>
      <td>0.792</td>
      <td>0.672</td>
      <td>2.974</td>
      <td>0.604</td>
      <td>1.000</td>
    </tr>
    <tr>
      <th>Diagonal ratio</th>
      <td>1.087</td>
      <td>0.921</td>
      <td>0.817</td>
      <td>0.349</td>
      <td>2.207</td>
      <td>0.453</td>
      <td>1.000</td>
      <td>1.080</td>
      <td>0.896</td>
      <td>0.964</td>
      <td>0.319</td>
      <td>2.292</td>
      <td>0.470</td>
      <td>1.000</td>
    </tr>
    <tr>
      <th>Portfolio standardized returns</th>
      <td>0.096</td>
      <td>0.140</td>
      <td>0.917</td>
      <td>-1.545</td>
      <td>1.360</td>
      <td>0.695</td>
      <td>mean=0, std=1</td>
      <td>0.086</td>
      <td>0.133</td>
      <td>0.937</td>
      <td>-1.586</td>
      <td>1.324</td>
      <td>0.690</td>
      <td>mean=0, std=1</td>
    </tr>
    <tr>
      <th>Portfolio QLIKE</th>
      <td>-6.411</td>
      <td>-6.696</td>
      <td>1.700</td>
      <td>-7.919</td>
      <td>-4.387</td>
      <td></td>
      <td>lower is better</td>
      <td>-6.346</td>
      <td>-6.694</td>
      <td>2.024</td>
      <td>-7.896</td>
      <td>-4.426</td>
      <td></td>
      <td>lower is better</td>
    </tr>
  </tbody>
</table>
</div>

[`CovarianceForecastComparison`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison) provides
additional plots:

* [`plot_calibration`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison.plot_calibration)
  with full diagnostics (Mahalanobis, diagonal, bias)
* [`plot_exceedance`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastComparison.html.md#skfolio.model_selection.CovarianceForecastComparison.plot_exceedance)

<a id="factor-model-expected-returns"></a>

<a id="expected-returns"></a>

## Expected Returns

[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel) estimates expected asset returns
from factor premia and an optional alpha forecast. The factor prior estimates expected
factor returns, which are mapped to assets through their exposures. This section
explains how these estimates are used together and how they are evaluated.

<a id="expected-factor-returns"></a>

### Expected Factor Returns

With `alpha_estimator=None` and the default `spanned_alpha_shrinkage=1`, expected
asset returns are determined entirely by the factor premia:

$$
\mu = B(T)\,\mu_f
$$

where $\mu_f$ holds the expected factor returns estimated by
`factor_prior_estimator` (see [Factor Return Distribution](https://skfolio.org/user_guide/factor_models.html.md#factor-model-factor-return-distribution)) and $B(T)$ is the latest
loading matrix. Each asset’s expected return is the sum of the premia of the
factors it is exposed to, weighted by its exposures.

<a id="information-coefficient"></a>

### Information Coefficient

[`exposure_ic_summary`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.exposure_ic_summary) measures the
cross-sectional correlation between factor exposures at $t$ and the forward
mean asset return from $t+1$ to $t+h$, where $h$ is the
`horizon` parameter. The default `correlation_method` computes the Spearman rank
IC, with Pearson IC weighted by the regression weights as the alternative. The
summary reports `mean_ic`, `std_ic`, `ic_ir` (mean over standard deviation) and
`hit_rate` per factor.
[`plot_cumulative_exposure_ic`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.plot_cumulative_exposure_ic) shows the
cumulative IC through time:

```python
factor_model.plot_cumulative_exposure_ic(families=["market", "style"])
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/factor_model_cumulative_exposure_ic.webp"
       alt="Cumulative information coefficients between factor exposures and next-period asset returns"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>
```python
factor_model.exposure_ic_summary(families=["market", "style"])
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>mean_ic</th>
      <th>std_ic</th>
      <th>ic_ir</th>
      <th>hit_rate</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>market</th>
      <td>-0.003</td>
      <td>0.095</td>
      <td>-0.029</td>
      <td>0.495</td>
    </tr>
    <tr>
      <th>beta</th>
      <td>-0.004</td>
      <td>0.169</td>
      <td>-0.022</td>
      <td>0.497</td>
    </tr>
    <tr>
      <th>momentum</th>
      <td>0.016</td>
      <td>0.154</td>
      <td>0.103</td>
      <td>0.564</td>
    </tr>
    <tr>
      <th>size</th>
      <td>0.008</td>
      <td>0.141</td>
      <td>0.059</td>
      <td>0.528</td>
    </tr>
    <tr>
      <th>non_linear_size</th>
      <td>0.008</td>
      <td>0.124</td>
      <td>0.063</td>
      <td>0.532</td>
    </tr>
    <tr>
      <th>value</th>
      <td>-0.006</td>
      <td>0.111</td>
      <td>-0.057</td>
      <td>0.459</td>
    </tr>
    <tr>
      <th>earnings_yield</th>
      <td>0.006</td>
      <td>0.119</td>
      <td>0.051</td>
      <td>0.509</td>
    </tr>
    <tr>
      <th>growth</th>
      <td>0.005</td>
      <td>0.068</td>
      <td>0.075</td>
      <td>0.548</td>
    </tr>
    <tr>
      <th>profitability</th>
      <td>0.011</td>
      <td>0.098</td>
      <td>0.117</td>
      <td>0.552</td>
    </tr>
    <tr>
      <th>investment</th>
      <td>-0.000</td>
      <td>0.067</td>
      <td>-0.001</td>
      <td>0.495</td>
    </tr>
    <tr>
      <th>dividend_yield</th>
      <td>0.004</td>
      <td>0.125</td>
      <td>0.031</td>
      <td>0.505</td>
    </tr>
    <tr>
      <th>leverage</th>
      <td>-0.004</td>
      <td>0.075</td>
      <td>-0.052</td>
      <td>0.475</td>
    </tr>
    <tr>
      <th>liquidity</th>
      <td>-0.010</td>
      <td>0.155</td>
      <td>-0.064</td>
      <td>0.475</td>
    </tr>
    <tr>
      <th>volatility</th>
      <td>-0.010</td>
      <td>0.132</td>
      <td>-0.076</td>
      <td>0.464</td>
    </tr>
  </tbody>
</table>
</div>

Daily ICs are small in absolute value, and the persistence of their sign matters
more than their level. In the [example](https://skfolio.org/user_guide/factor_models.html.md#factor-model-code-example),
momentum and profitability accumulate positive IC steadily across the sample
(hit rates of 56% and 55%), while volatility, liquidity and value accumulate
negative IC.

The IC quantifies return-predictive power. In a risk model, factors are designed
to forecast covariance, not expected returns. A factor can
therefore be an excellent risk factor with an IC near zero, and a low IC is not
a reason to discard it. IC is mainly useful for evaluating alpha signals and
factor premia, not for deciding whether a factor should remain in a risk model.

<a id="factor-model-alpha"></a>

<a id="alpha-estimators"></a>

### Alpha Estimators

The `alpha_estimator` parameter accepts any [`BaseAlpha`](https://skfolio.org/generated/skfolio.alpha.BaseAlpha.html.md#skfolio.alpha.BaseAlpha)
estimator producing an expected-return forecast for each asset. Before it is fitted,
the factor model enriches the panel with the quantities it has already estimated:
idiosyncratic returns, idiosyncratic variances, regression weights, benchmark
weights and the factor exposure tensor. In typical alpha research workflows,
idiosyncratic returns serve as the prediction target (typically after
cross-sectional transformation), idiosyncratic variances scale the target and
factor exposures neutralize the features. Targeting idiosyncratic returns rather
than raw returns removes the factor-driven component from the target. The
cross-sectional variation of raw returns includes each asset’s factor exposures
multiplied by the factor returns, so a signal correlated with the exposures would
pick up factor premia already captured by the factor model. The idiosyncratic
target also carries less noise, since common factor volatility is removed.

The alpha forecast should be expressed in expected-return units when it is combined
with expected factor returns or used in an optimization alongside return-denominated
quantities (e.g. transaction costs, turnover constraints, return targets). Unitless
cross-sectional scores are appropriate only when the downstream objective treats
them as ordinal signals.

skfolio provides alpha estimators following the same signal pipeline as
factor exposures with descriptors being transformed into cross-sectional scores
(`outlier_transformer`, `scoring_transformer`, `transform_by_group`), optionally
neutralized against factor exposures (`neutralize_against`) and re-scored. The
estimators differ mainly in how the scored descriptors are combined and how the
result is scaled into expected-return units.

* [`FixedWeightedAlpha`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha) combines multiple descriptors
  with fixed signed weights and a fixed `forecast_scale`. The weights define the
  direction and relative contribution of each descriptor, while `forecast_scale`
  converts one unit of composite score into the selected `forecast_unit`. This is useful
  when the signal combination is specified outside the model and the main decision is
  how strongly it should affect expected returns. `forecast_scale` requires careful
  calibration as a value too large leads the optimizer to over-allocate to the alpha
  forecast, whereas a value which is too small leaves the signal with little effect after
  costs, risk limits and turnover constraints.
* [`EWSharpeOptimalAlpha`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha) combines descriptors linearly and
  estimates their coefficients with exponentially weighted least squares on forward
  idiosyncratic returns, using inverse idiosyncratic variance as regression weights.
  It learns both sign and scale from realized data and accounts for cross-descriptor
  correlations, scaling the signal blend according to its estimated idiosyncratic
  return payoff. `forecast_scale` is then applied to the learned return-unit
  forecast as a final strength multiplier. The learned coefficients are subject to
  sampling error: short half-lives, noisy targets, weak descriptors and descriptors
  whose predictive content is already absorbed by the factor model produce unstable
  coefficients that can degrade an otherwise useful raw signal.
* [`PredictorAlpha`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha) wraps a user-provided
  scikit-learn regressor and treats each observation-asset pair as one training sample.
  It supports nonlinear interactions and non-additive signal effects, for example with
  tree-based models or regularized regressors. With `calibrate_to_return_units=True`,
  the raw predictor output is calibrated to expected-return units by exponentially
  weighted least squares, so `alpha_` is in expected-return units.
  `forecast_scale` is applied after this optional calibration. This flexibility
  increases the need for robust validation, because nonlinear models can fit noise,
  require more data and be sensitive to target construction and cross-validation
  design.

All three estimators produce `alpha_` in expected-return units. The
`forecast_unit` parameter controls the unit of the intermediate forecast
([`ForecastUnit`](https://skfolio.org/generated/skfolio.alpha.ForecastUnit.html.md#skfolio.alpha.ForecastUnit)). With `ForecastUnit.IDIO_RETURN` (default),
the forecast is interpreted directly as expected idiosyncratic return. With
`ForecastUnit.IDIO_SHARPE`, the forecast is interpreted as idiosyncratic Sharpe and
multiplied by the current idiosyncratic volatility before being passed to the
factor model. The Sharpe unit is preferable when a signal is expected to rank
risk-adjusted opportunities rather than raw returns. `forecast_scale` is the
common final multiplier controlling alpha strength.

The following example combines two reversal descriptors, [`return on assets`](https://skfolio.org/generated/skfolio.descriptor.ReturnOnAssets.html.md#skfolio.descriptor.ReturnOnAssets),
and [`Amihud illiquidity`](https://skfolio.org/generated/skfolio.descriptor.EWAmihudIlliquidity.html.md#skfolio.descriptor.EWAmihudIlliquidity) with fixed signed weights and uses a Gaussian rank scorer
for the cross-sectional scoring:

```python
from skfolio.alpha import FixedWeightedAlpha
from skfolio.descriptor import EWAmihudIlliquidity, ReturnOnAssets, Reversal
from skfolio.preprocessing import CSGaussianRankScaler

alpha_estimator = FixedWeightedAlpha(
    descriptors=[
        ("reversal_5d", Reversal(window=5)),
        ("reversal_21d", Reversal(window=21)),
        ("return_on_assets", ReturnOnAssets()),
        ("amihud_illiquidity", EWAmihudIlliquidity()),
    ],
    weights=[1.0, 1.0, -1.0, -1.0],
    forecast_scale=0.0001,
    scoring_transformer=CSGaussianRankScaler(),
    n_jobs=-1,
)
```

In practice, the simplest estimator that matches the research assumption is usually
the most robust starting point. Use [`FixedWeightedAlpha`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha)
when signal direction and relative weights are already specified and the main
decision is scale. Use [`EWSharpeOptimalAlpha`](https://skfolio.org/generated/skfolio.alpha.EWSharpeOptimalAlpha.html.md#skfolio.alpha.EWSharpeOptimalAlpha) when
the signal combination is expected to be approximately linear and there is enough
history to estimate stable payoffs. Use [`PredictorAlpha`](https://skfolio.org/generated/skfolio.alpha.PredictorAlpha.html.md#skfolio.alpha.PredictorAlpha)
when nonlinear effects are important and the additional validation burden is
acceptable. Custom estimators are created by subclassing
[`BaseAlpha`](https://skfolio.org/generated/skfolio.alpha.BaseAlpha.html.md#skfolio.alpha.BaseAlpha). During the alpha estimator’s
[warmup period](https://skfolio.org/user_guide/factor_models.html.md#factor-model-warmup), its forecast is treated as zero.

<a id="factor-model-spanned-alpha"></a>

<a id="spanned-and-orthogonal-alpha"></a>

### Spanned and Orthogonal Alpha

The fitted alpha forecast is decomposed into spanned alpha and orthogonal alpha by
projecting it onto the factor exposure space with a weighted cross-sectional
regression, using the latest exposures and regression weights:

$$
\alpha = \alpha^{\parallel} + \alpha^{\perp}
\qquad \text{with} \qquad
\alpha^{\parallel} = B(T)\,g
$$

where $\alpha^{\parallel}$ is the spanned alpha,
$\alpha^{\perp}$ is the orthogonal alpha and $g$ is the factor-return
vector that reproduces the spanned alpha through $B(T)$.

`spanned_alpha_shrinkage` blends the factor-implied asset expected returns
$B(T)\,\mu_f$ with the spanned alpha:

$$
\mu^{\parallel}
= \lambda\,B(T)\,\mu_f + (1 - \lambda)\,\alpha^{\parallel}
$$

where $\mu_f$ contains expected factor returns estimated from the factor
return time series (see [Factor Return Distribution](https://skfolio.org/user_guide/factor_models.html.md#factor-model-factor-return-distribution)). $\lambda = 1$ (default) uses
factor-implied asset expected returns, $\lambda = 0$ uses the spanned alpha and
intermediate values blend the two. With the default, the alpha forecast contributes
to expected returns only through the orthogonal alpha.

The orthogonal alpha is shrunk towards zero by `orthogonal_alpha_confidence`:

$$
\mu = \mu^{\parallel} + c\,\alpha^{\perp}
$$

where $c = 1$ (default) uses the orthogonal alpha as-is and $c = 0$
discards it. Orthogonal directions are penalized only through idiosyncratic
variances in the covariance forecast, so an optimizer allocates to them
aggressively when they carry alpha. Reducing `orthogonal_alpha_confidence`
tempers this incentive when confidence in the forecast is limited.
[Orthogonal Space Regularization](https://skfolio.org/user_guide/factor_models.html.md#factor-model-orthogonal-space-regularization) covers this behavior and the
optimizer-level alternatives.

The shrunk orthogonal alpha $c\,\alpha^{\perp}$ is stored in
`factor_model_.idio_mu`. When currency factors are present, direct currency expected
returns are added to $\mu$.

With the default weighted least-squares cross-sectional regressor, the decomposition
satisfies $B(T)^\top W\alpha^{\perp}=0$. Custom robust or regularized
cross-sectional regressors may produce a component that is only approximately
orthogonal.

<a id="alpha-and-risk-factor-alignment"></a>

### Alpha and Risk Factor Alignment

A signal may closely resemble an existing risk-model factor while using a modified
definition that produces a stronger expected return. The key question is whether
the modified definition also provides a better representation of systematic risk.

If it explains common return variation better or improves risk forecasts, it should
replace the existing factor definition. Otherwise, the additional systematic
component would remain in idiosyncratic returns, causing the optimizer to underestimate
its risk.

If the modified definition improves expected returns but does not improve the risk
model, the existing risk factor should remain. The resulting alpha forecast can then
be decomposed into spanned alpha and orthogonal alpha. The orthogonal alpha is
diversifiable relative to the validated risk model, so allocating to it is intentional.

A historical example comes from momentum. Earlier commercial risk models measured
momentum over the most recent 12 months, including the latest month. Later
research separated medium-term momentum from short-term reversal by excluding
that latest month. A manager using the revised definition while retaining the older risk
model created a mismatch: the difference between the two definitions appeared
outside the modelled momentum factor and was treated as idiosyncratic risk. The optimizer
could therefore take a large position in that difference without accounting for its
systematic risk.

With skfolio, the definition can be tested directly and, when it provides a better
representation of systematic risk, used immediately in the risk model.

<a id="factor-model-orthogonal-space-regularization"></a>

<a id="orthogonal-space-regularization"></a>

### Orthogonal Space Regularization

The factor structure has an asymmetric effect on the covariance forecast. Systematic
directions carry the full factor covariance, while directions orthogonal to the
factor span are penalized only through the per-asset idiosyncratic variances, since
the idiosyncratic covariance is diagonal or sparse. To an optimizer, orthogonal
directions therefore appear cheap in risk, and any orthogonal alpha makes them
attractive, leading to concentrated allocations in the orthogonal space.

If the model were correctly specified, complete and free of estimation error, this
behavior would be desirable as factor-neutral strategies (e.g. statistical arbitrage)
would exploit these directions. In practice the model is neither complete nor
error-free, so orthogonal risk is understated and some regularization is needed,
without giving up the orthogonal space entirely.

skfolio provides three mechanisms to achieve this. The first is a
[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel) parameter, the other two are
configured at the optimization step:

* `orthogonal_alpha_confidence` shrinks the orthogonal alpha point estimate toward
  zero, reducing the incentive to allocate in orthogonal directions.
* [`OrthogonalMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet), passed to the
  optimizer’s `mu_uncertainty_set_estimator`, applies robust optimization to the
  expected returns in the orthogonal space, penalizing allocations proportionally
  to the uncertainty of the orthogonal alpha.
* [`OrthogonalCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet), passed to
  the optimizer’s `covariance_uncertainty_set_estimator`, inflates the covariance
  in orthogonal directions, raising their variance directly.

An optimizer can allocate in orthogonal directions even when the orthogonal alpha
is zero as binding constraints (e.g. factor-neutrality, long-only) act through
shadow prices and push weights into the orthogonal space. In a model without an
alpha estimator, such allocations carry idiosyncratic risk with no expected
reward, making the covariance-side regularization relevant beyond the alpha term
itself. The [Portfolio Construction](https://skfolio.org/user_guide/factor_models.html.md#factor-model-portfolio-construction)
section shows the optimizer-level configuration, and the regularization strength
(`radius`) can be selected by walk-forward evaluation or
[hyperparameter tuning](https://skfolio.org/user_guide/factor_models.html.md#factor-model-hyper-parameter-tuning).

<a id="alpha-forecast-diagnostics"></a>

### Alpha Forecast Diagnostics

Alpha research can be organized in two ways. The alpha estimator can either be developed
jointly with the factor model, attached through `alpha_estimator` and evaluated
end to end or it can be developed independently by first fitting a factor model without
an alpha estimator and then adding its fitted outputs to the panel with
[`enrich_asset_panel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel.enrich_asset_panel) and finally iterating over
the alpha estimator directly using the enriched panel. The independent workflow avoids
refitting the factor model at each research iteration and is used below.

The [`alpha_forecast_evaluation`](https://skfolio.org/generated/skfolio.alpha.alpha_forecast_evaluation.html.md#skfolio.alpha.alpha_forecast_evaluation) function evaluates the
historical forecasts produced by an alpha estimator against a forward target
field in an [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel). The default target is
`idio_returns`, the part of returns not explained by the factor model. The
function fits the estimator with `fit_transform`, then compares the alpha
forecasts at observation $t$ with the forward mean target over
$[t + \ell, t + \ell + h)$, where $h$ is `holding_period` and
$\ell$ is `signal_lag`:

```python
from skfolio.utils.stats import CSWeighting
from skfolio.alpha import alpha_forecast_evaluation

characteristics_enriched = factor_model.enrich_asset_panel(characteristics)

evaluation = alpha_forecast_evaluation(
    alpha_estimator,
    characteristics_enriched,
    holding_period=5,
    signal_lag=1,
    cs_weighting=CSWeighting.REGRESSION,
    quantiles=(0.1, 0.25),
)

evaluation.ic_summary()
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>mean</th>
      <th>std</th>
      <th>icir</th>
      <th>t_stat</th>
      <th>hit_rate</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>spearman_ic</th>
      <td>0.012</td>
      <td>0.073</td>
      <td>0.164</td>
      <td>3.965</td>
      <td>0.556</td>
    </tr>
    <tr>
      <th>pearson_ic</th>
      <td>0.009</td>
      <td>0.068</td>
      <td>0.135</td>
      <td>3.255</td>
      <td>0.539</td>
    </tr>
  </tbody>
</table>
</div>
```python
evaluation.portfolio_summary()
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>annualized_mean</th>
      <th>annualized_vol</th>
      <th>annualized_ir</th>
      <th>hit_rate</th>
      <th>mean_turnover</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>rank_weighted_portfolio</th>
      <td>0.036</td>
      <td>0.019</td>
      <td>1.869</td>
      <td>0.554</td>
      <td>1.599</td>
    </tr>
    <tr>
      <th>zscore_weighted_portfolio</th>
      <td>0.037</td>
      <td>0.022</td>
      <td>1.710</td>
      <td>0.552</td>
      <td>1.745</td>
    </tr>
  </tbody>
</table>
</div>

The example alpha is deliberately simple. Its Spearman IC averages 0.012 with an
ICIR of 0.16 (t-stat 3.97) and a hit rate of 56%: a genuine but modest
predictive signal, in line with typical daily alpha signals. The simple
portfolios earn an annualized information ratio above 1.7 with substantial
turnover, gross of any trading friction. Whether such a signal can be monetized
depends on transaction costs, borrow costs, market impact and turnover
constraints, which enter at the optimization step and are covered in
[Portfolio Construction](https://skfolio.org/user_guide/factor_models.html.md#factor-model-portfolio-construction).

All diagnostics are computed on the final alpha forecast returned by the
estimator, after any rank transformation. With
`scoring_transformer=CSGaussianRankScaler()`, `spearman_ic` measures the ordering
quality of the forecast and `pearson_ic` the linear relation between
Gaussian-rank scores and future target returns. `zscore_weighted_portfolio` is
the simple portfolio closest to the expected-return vector consumed by an
optimizer, since the optimizer receives alpha values proportional to those
scores.

The [`AlphaForecastEvaluation`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation) result groups the diagnostics
as follows:

* [`ic_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.ic_summary): `spearman_ic`
  measures ordering quality and is invariant to monotonic transformations of the
  forecast. `pearson_ic`, weighted by `cs_weighting`, measures whether forecast
  magnitudes are linearly related to realized targets.
* [`portfolio_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.portfolio_summary): annualized
  statistics of alpha-only, gross-normalized long-short portfolios built from
  centered ranks (`rank_weighted_portfolio`) or centered forecast values
  (`zscore_weighted_portfolio`), before covariance, costs and constraints are
  introduced by the optimizer.
* [`quantile_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.quantile_summary): annualized
  top-minus-bottom target returns per tail quantile, showing whether predictive
  content is concentrated in the tails.
* [`calibration_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.calibration_summary):
  `calibration_slope` is the scale multiplier from a weighted zero-intercept
  regression of realized target on forecast. A slope near 1.0 indicates the
  forecast is already scaled to target units. Values above 1.0 indicate that
  `forecast_scale` is too small, while values below 1.0 indicate that it is too
  large.
* [`coverage_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.coverage_summary): fraction and
  number of assets with finite forecast and target values. Low coverage can make
  the other statistics unstable even when their averages look acceptable.
* [`factor_correlation_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.factor_correlation_summary):
  contemporaneous cross-sectional correlation between the forecast and factor
  exposures, testing whether the forecast is neutral to existing factors.
* [`decay_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.decay_summary) and
  [`holding_period_summary`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.holding_period_summary): IC and
  simple-portfolio statistics across forward periods, showing whether the signal
  is short-lived, persistent or delayed relative to the selected holding horizon.

Together, these diagnostics separate ordering quality from magnitude quality:
`spearman_ic` and `rank_weighted_portfolio` isolate the ordering, while
`pearson_ic`, `zscore_weighted_portfolio` and `calibration_summary` evaluate the
forecast values that an optimizer receives. `coverage_summary` checks data
availability and `decay_summary` aligns the alpha horizon with the intended
rebalancing and holding period. When the rank-based diagnostics are stronger
than the magnitude-based ones, the optimizer should not receive raw alpha
magnitudes as if they were calibrated expected returns.

```python
evaluation.plot_cumulative_ic()
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/alpha_eval_cumulative_ic.webp"
       alt="Cumulative Pearson and Spearman information coefficients for the alpha forecast over time"
       width="1100" height="616"
       loading="eager" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>
```python
evaluation.plot_factor_correlation()
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/alpha_eval_factor_correlation.webp"
       alt="Correlation of the alpha forecast with market and style factor exposures"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>
```python
evaluation.plot_cumulative_returns()
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/alpha_eval_cumulative_returns.webp"
       alt="Cumulative returns of alpha-sorted long-short portfolios across holding periods"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

Both ICs accumulate steadily across the sample, with the strongest run in
2020-2021 and no prolonged negative stretch, indicating stable predictive power
rather than a few favorable periods. The factor correlation plot shows the
forecast is not fully factor-neutral as it carries a positive size correlation and
negative profitability and liquidity correlations, inherited from its
descriptors. If these tilts are unwanted, they can be removed with
`neutralize_against`. The simple portfolios compound consistently, with a sharp
drawdown and recovery around the COVID shock.

[`AlphaForecastEvaluation`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation) provides additional plots:

* [`plot_rolling_ic`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_rolling_ic)
* [`plot_quantile_returns`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_quantile_returns)
* [`plot_calibration`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_calibration)
* [`plot_ic_by_holding_period`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_ic_by_holding_period)
* [`plot_portfolio_by_holding_period`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_portfolio_by_holding_period)
* [`plot_ic_decay`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_ic_decay)
* [`plot_portfolio_decay`](https://skfolio.org/generated/skfolio.alpha.AlphaForecastEvaluation.html.md#skfolio.alpha.AlphaForecastEvaluation.plot_portfolio_decay)

When the diagnostics show reliable ordering but weak magnitude calibration, a
practical approach is to keep the alpha shape rank-based and control its strength
with a single scale parameter. For descriptor-composition estimators, this is
done with a rank-based `scoring_transformer` (e.g.
[`CSGaussianRankScaler`](https://skfolio.org/generated/skfolio.preprocessing.CSGaussianRankScaler.html.md#skfolio.preprocessing.CSGaussianRankScaler)), as in the
[`FixedWeightedAlpha`](https://skfolio.org/generated/skfolio.alpha.FixedWeightedAlpha.html.md#skfolio.alpha.FixedWeightedAlpha) example of the
[Alpha Estimators](https://skfolio.org/user_guide/factor_models.html.md#factor-model-alpha) section. The resulting alpha is
still in expected-return units:

$$
\alpha_i = s \, z_i
$$

where $z_i$ is the cross-sectional Gaussian rank score and $s$ is
`forecast_scale`. The rank transformation defines the relative shape of the forecast,
while `forecast_scale` maps one rank-normal score unit to expected-return units.

This unit conversion is important in mean-risk optimization as the optimizer trades off
expected return, risk, constraints and transaction costs in the same objective. If
transaction costs are expressed in return units, the alpha forecast must also be in
return units. A rank-based alpha satisfies this requirement once it is multiplied by
`forecast_scale`.

With a rank-based alpha, calibration reduces to choosing the scale. If
`forecast_scale` is too small, transaction costs and risk penalties may dominate the
signal and the optimizer will keep positions close to their starting weights. If it is
too large, the optimizer may overtrade the ranked signal. The `calibration_summary`,
`portfolio_summary` and `decay_summary` diagnostics help choose a scale that is
consistent with realized target returns and the expected holding horizon.

<a id="factor-model-portfolio-construction"></a>

<a id="portfolio-construction"></a>

## Portfolio Construction

The factor model is a prior estimator and can be passed to any skfolio optimizer
through the `prior_estimator` parameter. The optimizer fits the
prior internally, then consumes its expected returns, covariance and scenarios.
The `characteristics` panel is forwarded to the prior through scikit-learn
metadata routing.

This section builds two portfolios on the fitted model: a factor-constrained
portfolio that trades factor premia through explicit exposure targets, and a
factor-neutral portfolio built from the orthogonal alpha.

<a id="factor-constrained-portfolio"></a>

### Factor-Constrained Portfolio

The example below builds a dollar-neutral long-short portfolio with positive
momentum and profitability exposures, together with a negative exposure to the
non-linear size factor. The exposure levels are chosen for illustration so their
effects remain clear in the later attribution analysis.

The -2.0 target for `non_linear_size` shows how factor constraints can express
more complex patterns than a simple large-versus-small tilt. The factor is built
as the cube of the size exposure and neutralized against size, which produces
the following approximate tilts:

| Size region      | Portfolio tilt   |
|------------------|------------------|
| Very small       | Long             |
| Moderately small | Short            |
| Moderately large | Long             |
| Very large       | Short            |
```python
from sklearn import set_config
from skfolio import RiskMeasure
from skfolio.optimization import MeanRisk, ObjectiveFunction

set_config(enable_metadata_routing=True)

X = characteristics.to_dataframe(fields="returns")
industry_names = characteristics.fields["industry"].levels

mvo = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    risk_measure=RiskMeasure.VARIANCE,
    prior_estimator=model,  # factor model as prior
    max_weights=0.05,  # limit individual positions to 5%
    min_weights=-0.05,  # allow short positions and limit to -5%
    budget=0.0,  # dollar neutral
    max_long=1.0,  # 100% long and 100% short: 200% gross exposure
    transaction_costs=0.001 / month,  # 10 bps amortized over one month
    fallback="previous_weights",  # keep last valid weights if a fit fails
    linear_constraints=[
        "momentum >= 1.0",
        "profitability == 1.0",
        "non_linear_size == -2.0",

        # Exact neutrality
        "beta == 0",
        "size == 0",
        "volatility == 0",

        # Small bands on the remaining styles
        "growth <= 0.05",
        "growth >= -0.05",

        "investment <= 0.05",
        "investment >= -0.05",

        "value <= 0.05",
        "value >= -0.05",

        "liquidity <= 0.05",
        "liquidity >= -0.05",

        "earnings_yield <= 0.05",
        "earnings_yield >= -0.05",

        "leverage <= 0.05",
        "leverage >= -0.05",

        "dividend_yield <= 0.05",
        "dividend_yield >= -0.05",

        # Industry neutrality
        *[f"{name} == 0.0" for name in industry_names],
    ],
)

mvo.fit(X, characteristics=characteristics)

print(mvo.weights_)

# Factor model fitted inside the optimizer, reused below for attribution
factor_model = mvo.prior_estimator_.factor_model_
```

Here the full coverage universe serves as the investment universe: `X` contains
the returns of every asset in the panel. The factor model fitted inside the optimizer is
available through `mvo.prior_estimator_.factor_model_` and is reused in the
[Attribution](https://skfolio.org/user_guide/factor_models.html.md#factor-model-attribution) section. A separate factor model
can also be fitted for attribution only.

The portfolio is dollar neutral with `budget=0.0` and limited to 100% long
exposure with `max_long=1.0`. Dollar neutrality implies an equally sized short
position, so the maximum gross exposure is 200% (100% long plus 100% short).

Individual positions are limited to $\pm 5\%$. Transaction costs follow the
skfolio convention: a linear cost per unit traded, deducted from the portfolio
expected return, which is expressed per observation period (here daily). A
transaction cost is paid once per rebalancing while a position earns its return
on every period it is held, so the 10 basis points are amortized over the
one-month expected holding period to convert them to a daily cost,
`0.001 / month` (see
[Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention)). Market
impact and borrow costs can be added through the optimizer’s `add_objective` and
`add_constraints` parameters, with native support planned for a future release.

The portfolio targets three equity styles: momentum, profitability and non-linear size.
The beta, size and volatility exposures are set to zero. The remaining styles are
constrained within $\pm 0.05$, and industry exposures are neutralized. In
`linear_constraints`, an expression on a factor name (e.g. `"momentum >= 1.0"`)
applies to the portfolio exposure to that factor, while an expression on a family
name (e.g. `"style <= 0.5"`) applies to the sum of exposures over the family’s
factors. Industry neutrality therefore uses one constraint per industry
factor rather than a single `"industry == 0"` constraint, which would only force
industry exposures to offset each other. No explicit
`"market == 0"` constraint is needed because `budget=0.0` already sets the
global factor exposure to zero.

`fallback="previous_weights"` keeps the latest valid allocation when a
rebalancing problem is infeasible, for example on dates where strict constraints
cannot be satisfied. Fallback estimators and the fallback audit trail are covered
in [Failure and Fallbacks](https://skfolio.org/auto_examples/mean_risk/plot_17_failure_and_fallbacks.html.md#sphx-glr-auto-examples-mean-risk-plot-17-failure-and-fallbacks-py).

The portfolio is evaluated using monthly walk-forward rebalancing:

```python
from skfolio.model_selection import online_predict

# Two years plus one month of observations warm up the model
# before the first rebalancing
warmup_size = 252 * 2 + 21

mpp = online_predict(
    estimator=mvo,
    X=X,
    warmup_size=warmup_size,
    test_size=month,
    params={"characteristics": characteristics},
)
print(mpp.n_fallback_portfolios)
print(mpp.summary())
print(mpp.annualized_sharpe_ratio)
mpp.plot_cumulative_returns()
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/mpp_cumulative_returns.webp"
       alt="Cumulative out-of-sample return of the monthly rebalanced factor-constrained portfolio"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>
```python
mpp.plot_composition()
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/mpp_composition.webp"
       alt="Long and short asset weights of the factor-constrained portfolio across monthly rebalancing dates"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

`online_predict` returns a [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio), one
portfolio per rebalancing. The [Portfolio](https://skfolio.org/user_guide/portfolio.html.md#portfolio) user guide covers the
portfolio objects and their analytics (e.g. `plot_long_short_exposure`,
`plot_contribution`, `summary`). The two-year `warmup_size` covers the stacked
descriptor and estimator warmups (see [Warmup Periods](https://skfolio.org/user_guide/factor_models.html.md#factor-model-warmup)). The out-of-sample portfolio achieves an annualized
Sharpe ratio of 0.91.

The optimizer consumes the factor model with the following conventions:

* For variance-based risk measures, the optimizer consumes the covariance square
  root described in the [Asset Covariance Forecast](https://skfolio.org/user_guide/factor_models.html.md#factor-model-asset-covariance-forecast) section,
  operating in the factor space instead of forming the dense asset covariance.
* For scenario-based risk measures (e.g. `RiskMeasure.CVAR`), the optimizer consumes
  the asset return scenarios from `return_distribution_.returns`, which combine
  factor and idiosyncratic components. With [online learning](https://skfolio.org/user_guide/factor_models.html.md#factor-model-online-learning), `max_history` keeps the
  scenarios on a rolling window.
* Assets that are not investable at the current date (e.g. delisted, in warmup)
  carry NaN moments. The optimizer solves on the investable subset and assigns them
  zero weight, as described in the [Input Data](https://skfolio.org/user_guide/factor_models.html.md#factor-model-input-data) section.

Robust optimization in the orthogonal space is configured at the optimizer level,
following the [Orthogonal Space Regularization](https://skfolio.org/user_guide/factor_models.html.md#factor-model-orthogonal-space-regularization) section:

```python
from skfolio.uncertainty_set import OrthogonalCovarianceUncertaintySet

mvo.set_params(
    covariance_uncertainty_set_estimator=OrthogonalCovarianceUncertaintySet(radius=1.0)
)
```

This example trades factor premia and does not use an alpha forecast. The
factor-neutral case is covered in the [Factor-Neutral Alpha Portfolio](https://skfolio.org/user_guide/factor_models.html.md#factor-model-factor-neutral-alpha-portfolio) section below.

Walk-forward evaluation and hyperparameter tuning of the full
optimization-plus-prior pipeline are covered in the [Walk-Forward Evaluation](https://skfolio.org/user_guide/factor_models.html.md#factor-model-walk-forward-evaluation) and [Hyperparameter Tuning](https://skfolio.org/user_guide/factor_models.html.md#factor-model-hyper-parameter-tuning) sections.

#### NOTE
When the research focus is the optimization itself and the factor model is
fixed, refitting the prior at each iteration can dominate the runtime on
large universes. The factor model outputs can be precomputed over the chosen
observations, stored in a database or local cache, and served back by a custom
prior estimator that reads them for the requested observation range. Native
factor model caching is planned for a future release.

<a id="factor-model-factor-neutral-alpha-portfolio"></a>

<a id="factor-neutral-alpha-portfolio"></a>

### Factor-Neutral Alpha Portfolio

The previous example earns its return from factor premia through explicit
exposure targets. This portfolio keeps factor exposures close to zero and uses the
orthogonal alpha as its modeled expected return, an approach common in statistical
arbitrage. The orthogonal alpha is the residual of the alpha forecast after
projection onto the factor exposure space.

#### NOTE
A factor-neutral portfolio has zero exposure to every factor, so its modeled
expected return reduces to the orthogonal alpha. Without an alpha estimator,
the orthogonal alpha is zero and the optimal allocation is the zero portfolio.

The validated alpha estimator from the [Alpha Estimators](https://skfolio.org/user_guide/factor_models.html.md#factor-model-alpha) section is attached to the factor model, and a
dollar-neutral long-short portfolio is optimized with weekly rebalancing. Style
exposures are bounded within $\pm 0.05$, industry exposures are set to
zero, and individual positions are limited to $\pm 3\%$. Because
factor-neutral strategies typically run at higher gross leverage, `max_long` is raised to
3.0, allowing up to 600% gross exposure. The optimization objective is a mean-variance
utility, balancing the alpha forecast against risk and transaction costs:

```python
from skfolio.model_selection import online_predict
from skfolio import RiskMeasure
from skfolio.optimization import MeanRisk, ObjectiveFunction

week = 5
model.set_params(alpha_estimator=alpha_estimator)

X = characteristics.to_dataframe(fields="returns")
industry_names = characteristics.fields["industry"].levels
style_factors = [
    "beta", "momentum", "profitability", "non_linear_size", "size", "volatility",
    "growth", "investment", "value", "liquidity", "earnings_yield",
    "leverage", "dividend_yield",
]

mvo = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_UTILITY,
    risk_measure=RiskMeasure.VARIANCE,
    risk_aversion=1,
    prior_estimator=model,
    max_weights=0.03,
    min_weights=-0.03,
    budget=0.0,
    max_long=3.0,
    transaction_costs=0.001 / week,
    fallback="previous_weights",
    linear_constraints=[
        *[f"{name} <= 0.05" for name in style_factors],
        *[f"{name} >= -0.05" for name in style_factors],
        *[f"{name} == 0" for name in industry_names],
    ],
)

warmup_size = 2 * 252 + 21
mpp = online_predict(
    estimator=mvo,
    X=X,
    warmup_size=warmup_size,
    test_size=week,
    params={"characteristics": characteristics},
    entry_rebalancing_params={"transaction_costs": 0.0},
)
print(mpp.annualized_sharpe_ratio)
```

`entry_rebalancing_params` applies estimator parameters only while constructing
the first portfolio, which starts from cash while later portfolios rebalance
from the previous weights. Setting `transaction_costs=0.0` at entry avoids
charging costs on the full initial ramp-up from cash, letting the first
rebalancing use the desired allocation directly, up to the 600% gross-exposure
limit, instead of building exposure over several rebalancings. The regular
parameters are then restored for subsequent updates. At
this level of gross and short exposure, borrow costs and market impact become
material. They can be added through the optimizer’s `add_objective` and
`add_constraints` parameters, with native support planned for a future release.
[`plot_cumulative_returns`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_cumulative_returns) and
[`plot_long_short_exposure`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio.plot_long_short_exposure) display
the resulting path and the long and short books.

Realized attribution verifies that the portfolio behaves as intended:

```python
realized_attrib = mpp.realized_attribution(
    factor_model=factor_model,
    compute_uncertainty=True,
    compute_asset_breakdowns=False,
)
realized_attrib.plot_return_contrib(top_n=15)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/alpha_realized_return_contrib.webp"
       alt="Annualized realized return contributions of factors and the idiosyncratic component for the factor-neutral alpha portfolio"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

Factor contributions are negligible and nearly all of the realized return comes
from the idiosyncratic component, around 6.6% annualized with a narrow 95%
confidence interval. The [Attribution](https://skfolio.org/user_guide/factor_models.html.md#factor-model-attribution) section
covers the methodology.

<a id="evaluation-and-tuning"></a>

## Evaluation and Tuning

A factor model pipeline can be evaluated at three complementary levels:

* [Regression diagnostics](https://skfolio.org/user_guide/factor_models.html.md#factor-model-regression-diagnostics) measure how
  well the factor structure explains the cross-section of returns.
* [Covariance forecast evaluation](https://skfolio.org/user_guide/factor_models.html.md#factor-model-covariance-forecast-evaluation) tests the out-of-sample calibration of the risk forecasts.
* [Walk-forward evaluation](https://skfolio.org/user_guide/factor_models.html.md#factor-model-walk-forward-evaluation) measures the realized portfolio outcomes of
  the full pipeline, including the optimizer.

<a id="factor-model-warmup"></a>

<a id="warmup-periods"></a>

### Warmup Periods

Walk-forward evaluation starts with a warmup period. The `warmup_size` observations
are fitted before the first prediction. Its minimum value follows from the history
each stage of the pipeline consumes before producing its first output.

Rolling and exponentially weighted descriptors (e.g.
[`RollingMomentum`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum),
[`EWMarketBeta`](https://skfolio.org/generated/skfolio.descriptor.EWMarketBeta.html.md#skfolio.descriptor.EWMarketBeta)) return NaN during their warmup, and
the cross-sectional regression requires finite exposures, so the longest
descriptor warmup determines the first observation of the factor return
history. The estimators consuming the factor and idiosyncratic return series
add their own warmup on top: the factor prior (covariance and expected returns)
and the idiosyncratic variance estimator. These warmup periods are cumulative.
For example, with one year of descriptor warmup and one year of covariance warmup,
the first usable forecast arrives after about two years of data. The walk-forward
examples in this guide use `warmup_size = 2 * 252 + 21` for this reason.

Alpha estimators also have warmup periods from their own descriptors, but these
run concurrently with the model’s warmup rather than after it. The model passes
the full [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel), enriched with idiosyncratic
returns, idiosyncratic variances and exposures that keep their leading warmup
NaN values, instead of truncating the panel.

<a id="factor-model-walk-forward-evaluation"></a>

<a id="walk-forward-evaluation"></a>

### Walk-Forward Evaluation

[`online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict) simulates the strategy through
time by updating a single stateful estimator with `partial_fit` and predicting
on each subsequent test window:

```python
from skfolio.model_selection import online_predict

portfolio = online_predict(
    estimator=optimization,
    X=X,
    warmup_size=2 * 252 + 21,
    test_size=21,
    params={"characteristics": characteristics},
)
portfolio.summary()
```

Unlike [`cross_val_predict`](https://skfolio.org/generated/skfolio.model_selection.cross_val_predict.html.md#skfolio.model_selection.cross_val_predict), which clones and refits
the estimator on each fold, `online_predict` updates a single stateful estimator
and carries its state forward, making long walk-forward backtests practical for
models of this size. The result is a multi-period portfolio with the usual
skfolio analytics (summary, plots, risk measures).
[`online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score) follows the same pattern.

<a id="factor-model-hyper-parameter-tuning"></a>

<a id="hyperparameter-tuning"></a>

### Hyperparameter Tuning

All model parameters, from descriptor half-lives to weighting powers, shrinkages
and thresholds, follow the scikit-learn convention and can be tuned with
standard model-selection utilities. For walk-forward tuning,
[`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch) and
[`OnlineRandomizedSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch) evaluate each parameter
combination in a single walk-forward pass using `partial_fit`, instead of refitting
the estimator on every fold:

```python
from skfolio.model_selection import OnlineGridSearch

search = OnlineGridSearch(
    estimator=optimization,
    param_grid={
        "prior_estimator__inv_idio_variance_weight_shrinkage": [0.0, 0.5, 1.0],
        "prior_estimator__exposure_lag": [1, 2],
    },
    warmup_size=2 * 252 + 21,
    test_size=21,
)
search.fit(X, characteristics=characteristics)
search.best_params_
```

Scoring can target two levels. Portfolio-level scores (e.g. ratio measures)
evaluate the full pipeline including the optimizer, as in the example above.
Covariance losses from [`skfolio.metrics`](https://skfolio.org/api.html.md#module-skfolio.metrics) evaluate the risk model itself
with the factor model being passed directly as the search estimator, without
an optimizer, and scored on its covariance forecast. In `make_scorer`,
`response_method=None` indicates a non-predictor estimator and
`greater_is_better=False` a loss to minimize:

```python
from skfolio.metrics import make_scorer, portfolio_variance_qlike_loss
from skfolio.model_selection import OnlineGridSearch

qlike_scorer = make_scorer(
    portfolio_variance_qlike_loss,
    greater_is_better=False,
    response_method=None,
)

search = OnlineGridSearch(
    estimator=model,
    param_grid={
        "factor_prior_estimator__covariance_estimator__regime_half_life": [10, 21, 63],
    },
    scoring=qlike_scorer,
    warmup_size=2 * 252 + 21,
    test_size=21,
)
search.fit(X, characteristics=characteristics)
search.best_params_
```

The same workflow is shown on a covariance estimator in
[Online Covariance Hyperparameter Tuning](https://skfolio.org/auto_examples/online_learning/plot_2_online_hyperparameter_tuning.html.md#sphx-glr-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py).

<a id="factor-model-attribution"></a>

<a id="attribution"></a>

## Attribution

Attribution decomposes portfolio risk and return into the contributions of
individual factors, factor families, the idiosyncratic component and,
optionally, individual assets. Applied ex ante, it shows where the forecast
risk and expected return come from. Applied ex post, it shows which factors
delivered the realized performance, with standard errors that separate genuine
contributions from estimation noise.

Attribution is accessed from a [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) or
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio), which supplies the weights
and portfolio returns. Three methods take the fitted factor model as argument:

* `predicted_attribution` computes ex-ante attribution from the fitted loading
  matrix, factor covariance and idiosyncratic covariance. The volatility forecast
  is decomposed using the exposure-volatility-correlation framework
  ($x$-$\sigma$-$\rho$) and, when expected factor returns are
  available, expected return is decomposed into factor-spanned and factor-orthogonal
  components.
* `realized_attribution` computes ex-post attribution from the realized factor
  returns, exposures and idiosyncratic returns.
* `rolling_realized_attribution` runs the realized attribution over rolling
  windows, showing how contributions evolve through time.

The same methods are available at a lower level on the fitted
[`FactorModel`](https://skfolio.org/generated/skfolio.prior.FactorModel.html.md#skfolio.prior.FactorModel), taking `weights` (a single vector or a
time-varying array) and `portfolio_returns` explicitly.

All three return an [`Attribution`](https://skfolio.org/generated/skfolio.attribution.Attribution.html.md#skfolio.attribution.Attribution) object
with the same structure:

* `systematic`, `idio` and `total`: component-level breakdowns with volatility,
  volatility contribution, share of total variance, return and correlation with
  the portfolio. Realized attribution adds `unattributed`, the difference between
  observed portfolio returns and model-attributed returns (transaction costs,
  fees, cash and intra-period trading).
* `factors` and `families`: per-factor breakdowns with exposures, standalone
  statistics and contributions, with the same information aggregated by factor
  family.
* `assets` and `asset_by_factor_contrib`: the per-asset systematic/idiosyncratic
  decomposition and, optionally, the full asset-by-factor contribution matrix.

Realized attribution supports uncertainty estimates (`compute_uncertainty=True`,
the default). Using the stored regression weights and idiosyncratic variances, it
computes standard errors on the factor and idiosyncratic return contributions,
exposed as `mu_contrib_uncertainty` in the factor breakdown.

Results are available as DataFrames through `summary_df`, `families_df` and
`factors_df`, and as plots through `plot_exposure`, `plot_vol_contrib`,
`plot_return_contrib` and `plot_return_vs_vol_contrib`. Rolling attributions
carry an `observations` axis and can be indexed (`attribution[i]`) to retrieve
the attribution of a single window.

Return contributions are reported directly in additive return units. Risk
contributions are additionally normalized as shares of total variance, the
standard scale for comparing risk attribution across portfolios and periods.

The figures below use the constrained mean-variance portfolio from the
[Portfolio Construction](https://skfolio.org/user_guide/factor_models.html.md#factor-model-portfolio-construction) section. That
portfolio is dollar neutral and imposes three main style constraints:
`momentum >= 1.0`, `profitability == 1.0` and `non_linear_size == -2.0`.
It also sets beta, size, volatility and industry exposures to zero and allows
only small exposures to the remaining style factors.

<a id="ex-ante-attribution"></a>

### Ex-Ante Attribution

Ex-ante attribution decomposes the risk and expected-return forecasts of the
optimized portfolio:

```python
# Access via the Portfolio or MultiPeriodPortfolio API
portfolio = mvo.predict(X)
predicted_attrib = portfolio.predicted_attribution(factor_model=factor_model)

# Equivalent access via the FactorModel API, passing the weights explicitly
predicted_attrib = factor_model.predicted_attribution(weights=mvo.weights_)

predicted_attrib.summary_df()
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>Volatility Contribution</th>
      <th>% of Total Variance</th>
      <th>Expected Return Contribution</th>
    </tr>
    <tr>
      <th>Component</th>
      <th></th>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Systematic</th>
      <td>16.00%</td>
      <td>91.57%</td>
      <td>16.69%</td>
    </tr>
    <tr>
      <th>Idiosyncratic</th>
      <td>1.47%</td>
      <td>8.43%</td>
      <td>0.00%</td>
    </tr>
    <tr>
      <th>Total</th>
      <td>17.47%</td>
      <td>100.00%</td>
      <td>16.69%</td>
    </tr>
  </tbody>
</table>
</div>

The predicted annualized volatility of 17.5% splits into a 16.0% systematic
volatility contribution and a 1.5% idiosyncratic volatility contribution. Because
each volatility contribution is the corresponding variance contribution divided
by total volatility, dividing again by total volatility gives the variance share:
91.6% systematic and 8.4% idiosyncratic. The expected return is entirely
systematic: no alpha estimator is attached, so the model forecasts no return in
the orthogonal space.

```python
predicted_attrib.families_df()
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>Exposure</th>
      <th>Volatility Contribution</th>
      <th>% of Total Variance</th>
      <th>Expected Return Contribution</th>
    </tr>
    <tr>
      <th>Family</th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>style</th>
      <td>1.8262</td>
      <td>16.00%</td>
      <td>91.57%</td>
      <td>16.69%</td>
    </tr>
    <tr>
      <th>industry</th>
      <td>-0.0000</td>
      <td>0.00%</td>
      <td>0.00%</td>
      <td>0.00%</td>
    </tr>
    <tr>
      <th>market</th>
      <td>-0.0000</td>
      <td>-0.00%</td>
      <td>-0.00%</td>
      <td>-0.00%</td>
    </tr>
  </tbody>
</table>
</div>

In the family breakdown, the industry and market rows carry zero exposure and
zero contribution, as imposed by the neutrality constraints. All systematic
risk and expected return come from the style family.

```python
predicted_attrib.factors_df().head()
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>Family</th>
      <th>Exposure</th>
      <th>Volatility Contribution</th>
      <th>% of Total Variance</th>
      <th>Expected Return Contribution</th>
      <th>Standalone Volatility</th>
      <th>Standalone Expected Return</th>
      <th>Correlation with Portfolio</th>
    </tr>
    <tr>
      <th>Factor</th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>momentum</th>
      <td>style</td>
      <td>2.5762</td>
      <td>14.51%</td>
      <td>83.05%</td>
      <td>14.25%</td>
      <td>6.24%</td>
      <td>5.53%</td>
      <td>0.9025</td>
    </tr>
    <tr>
      <th>non_linear_size</th>
      <td>style</td>
      <td>-2.0000</td>
      <td>1.27%</td>
      <td>7.29%</td>
      <td>2.97%</td>
      <td>2.42%</td>
      <td>-1.48%</td>
      <td>-0.2629</td>
    </tr>
    <tr>
      <th>profitability</th>
      <td>style</td>
      <td>1.0000</td>
      <td>0.25%</td>
      <td>1.46%</td>
      <td>-0.92%</td>
      <td>2.32%</td>
      <td>-0.92%</td>
      <td>0.1097</td>
    </tr>
    <tr>
      <th>liquidity</th>
      <td>style</td>
      <td>0.0500</td>
      <td>-0.02%</td>
      <td>-0.10%</td>
      <td>0.14%</td>
      <td>5.35%</td>
      <td>2.77%</td>
      <td>-0.0628</td>
    </tr>
    <tr>
      <th>growth</th>
      <td>style</td>
      <td>0.0500</td>
      <td>0.02%</td>
      <td>0.09%</td>
      <td>0.05%</td>
      <td>1.81%</td>
      <td>0.96%</td>
      <td>0.1813</td>
    </tr>
  </tbody>
</table>
</div>

The per-factor breakdown reports each factor’s standalone volatility and
expected return (the statistics of the factor’s own return series) next to its
contributions. The volatility contribution follows the
exposure-volatility-correlation decomposition: portfolio exposure multiplied by
standalone volatility multiplied by correlation with the portfolio. The momentum
factor accounts for 83% of the predicted variance and has a 0.90 correlation
with the portfolio.

```python
predicted_attrib.plot_exposure(top_n=15)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/attribution_predicted_exposure.webp"
       alt="Factor exposures of the factor-constrained portfolio at the prediction date"
       width="1100" height="616"
       loading="eager" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The profitability factor sits at its 1.0 target and the non-linear size factor at
its -2.0 target. The momentum exposure reaches about 2.6, well above its 1.0
floor as the ratio-maximizing objective concentrates in the factor with the
strongest forecast premium.
The market, industry and neutralized style exposures are zero, and the
remaining styles stay within their $\pm 0.05$ bands.

```python
predicted_attrib.plot_vol_contrib(top_n=15)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/attribution_predicted_vol_contrib.webp"
       alt="Predicted annualized volatility contributions by factor and idiosyncratic component"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The momentum factor dominates predicted risk with about 14.5% of the 17.5% total
annualized volatility. The idiosyncratic contribution of about 1.5% is the
second largest: with market and industry exposures forced to zero, part of the
allocation moves into orthogonal directions, which enter the risk forecast only
through the idiosyncratic variances (see [Orthogonal Space Regularization](https://skfolio.org/user_guide/factor_models.html.md#factor-model-orthogonal-space-regularization)).

```python
predicted_attrib.plot_return_contrib(top_n=15)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/attribution_predicted_return_contrib.webp"
       alt="Predicted annualized return contributions by factor and idiosyncratic component"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The momentum factor contributes about 14% of annualized expected return, the
non-linear size factor contributes 3%, and the profitability factor contributes
a small negative amount, in line with their exposures and forecast premia. The
idiosyncratic contribution is exactly zero.

```python
predicted_attrib.plot_return_vs_vol_contrib(top_n=15)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/attribution_predicted_return_vs_vol_contrib.webp"
       alt="Predicted return contribution versus volatility contribution for each factor and the idiosyncratic component"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The scatter plots expected return contribution against volatility contribution.
The momentum factor sits in the top right, driving both, while the idiosyncratic
component lies on the zero-return axis, carrying risk without forecast reward.

<a id="ex-post-attribution"></a>

### Ex-Post Attribution

Ex-post attribution decomposes the realized performance of the walk-forward
portfolio, whose weights vary through time:

```python
# Access via the Portfolio or MultiPeriodPortfolio API
realized_attrib = mpp.realized_attribution(factor_model=factor_model)

# Equivalent access via the FactorModel API, passing the time-varying
# weights and the realized portfolio returns explicitly
realized_attrib = factor_model.realized_attribution(
    weights=weights,
    portfolio_returns=portfolio_returns,
)

realized_attrib.summary_df()
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>Volatility Contribution</th>
      <th>% of Total Variance</th>
      <th>Mean Return Contribution (95% CI)</th>
    </tr>
    <tr>
      <th>Component</th>
      <th></th>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Systematic</th>
      <td>5.07%</td>
      <td>78.09%</td>
      <td>7.51% ± 1.48%</td>
    </tr>
    <tr>
      <th>Idiosyncratic</th>
      <td>1.42%</td>
      <td>21.93%</td>
      <td>-1.39% ± 1.48%</td>
    </tr>
    <tr>
      <th>Unattributed</th>
      <td>-0.00%</td>
      <td>-0.02%</td>
      <td>-0.22%</td>
    </tr>
    <tr>
      <th>Total</th>
      <td>6.49%</td>
      <td>100.00%</td>
      <td>5.90%</td>
    </tr>
  </tbody>
</table>
</div>

Out of sample, the systematic component earned 7.5% ± 1.5% annualized mean
return for a 5.1% volatility contribution. The idiosyncratic component cost
-1.4% ± 1.5%: the risk taken in orthogonal directions was not compensated,
consistent with a zero factor-orthogonal expected-return component.

```python
realized_attrib.families_df()
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>Exposure Mean</th>
      <th>Exposure Std</th>
      <th>Volatility Contribution</th>
      <th>% of Total Variance</th>
      <th>Mean Return Contribution (95% CI)</th>
    </tr>
    <tr>
      <th>Family</th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>style</th>
      <td>0.1468</td>
      <td>0.4464</td>
      <td>5.07%</td>
      <td>78.10%</td>
      <td>7.51% ± 1.48%</td>
    </tr>
    <tr>
      <th>industry</th>
      <td>0.0004</td>
      <td>0.0039</td>
      <td>-0.00%</td>
      <td>-0.03%</td>
      <td>0.00% ± 0.01%</td>
    </tr>
    <tr>
      <th>market</th>
      <td>0.0004</td>
      <td>0.0039</td>
      <td>0.00%</td>
      <td>0.02%</td>
      <td>0.00% ± 0.00%</td>
    </tr>
  </tbody>
</table>
</div>

The realized family breakdown reports the mean and standard deviation of each
exposure over the backtest. Industry and market exposures stay near zero, so
the neutrality constraints held at every rebalancing.

```python
realized_attrib.factors_df().head()
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>Family</th>
      <th>Exposure Mean</th>
      <th>Exposure Std</th>
      <th>Volatility Contribution</th>
      <th>% of Total Variance</th>
      <th>Mean Return Contribution (95% CI)</th>
      <th>Standalone Volatility</th>
      <th>Standalone Mean Return</th>
      <th>Correlation with Portfolio</th>
    </tr>
    <tr>
      <th>Factor</th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>momentum</th>
      <td>style</td>
      <td>1.0852</td>
      <td>0.4029</td>
      <td>3.44%</td>
      <td>53.04%</td>
      <td>3.18% ± 0.67%</td>
      <td>4.60%</td>
      <td>2.56%</td>
      <td>0.6621</td>
    </tr>
    <tr>
      <th>non_linear_size</th>
      <td>style</td>
      <td>-1.9746</td>
      <td>0.0726</td>
      <td>1.09%</td>
      <td>16.81%</td>
      <td>3.19% ± 1.16%</td>
      <td>1.93%</td>
      <td>-1.63%</td>
      <td>-0.2880</td>
    </tr>
    <tr>
      <th>profitability</th>
      <td>style</td>
      <td>0.9970</td>
      <td>0.0400</td>
      <td>0.42%</td>
      <td>6.45%</td>
      <td>0.86% ± 0.56%</td>
      <td>1.58%</td>
      <td>0.83%</td>
      <td>0.2665</td>
    </tr>
    <tr>
      <th>growth</th>
      <td>style</td>
      <td>-0.0042</td>
      <td>0.0827</td>
      <td>0.04%</td>
      <td>0.57%</td>
      <td>0.01% ± 0.05%</td>
      <td>1.65%</td>
      <td>-0.41%</td>
      <td>0.1788</td>
    </tr>
    <tr>
      <th>volatility</th>
      <td>style</td>
      <td>-0.0101</td>
      <td>0.0436</td>
      <td>0.02%</td>
      <td>0.34%</td>
      <td>0.09% ± 0.04%</td>
      <td>3.31%</td>
      <td>-0.06%</td>
      <td>-0.2287</td>
    </tr>
  </tbody>
</table>
</div>

At the factor level, momentum and non-linear size each contributed about 3.2%
of annualized return, but momentum consumed three times the risk budget (53%
of total variance against 17%). Out of sample, the short non-linear-size
position was the more efficient trade.

```python
realized_attrib.plot_exposure(top_n=15)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/attribution_realized_exposure.webp"
       alt="Average realized factor exposures with one-standard-deviation error bars"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

Realized exposures are averaged over the backtest, with error bars showing one
standard deviation of their variation through time. The equality-constrained
factors (profitability, non-linear size) show tight bands, while momentum
averages about 1.1 with a wider band: its floor constraint leaves the optimizer
free to exceed 1.0 when the forecast premium justifies it.

```python
realized_attrib.plot_vol_contrib(top_n=15)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/attribution_realized_vol_contrib.webp"
       alt="Realized annualized volatility contributions by factor and idiosyncratic component"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>
```python
realized_attrib.plot_return_contrib(top_n=15)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/attribution_realized_return_contrib.webp"
       alt="Annualized realized return contributions by factor with 95% confidence intervals"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The error bars show the 95% confidence intervals on the mean return
contributions. The momentum, non-linear size and profitability factors are clearly
positive, while the -1.4% idiosyncratic contribution has an interval crossing
zero, so it is indistinguishable from estimation noise.

```python
realized_attrib.plot_return_vs_vol_contrib(top_n=15)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/attribution_realized_return_vs_vol_contrib.webp"
       alt="Realized return contribution versus volatility contribution for each factor and the idiosyncratic component"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The scatter shows that non-linear size delivered the same return as momentum at
a third of the risk, while the idiosyncratic component sits below the axis,
carrying risk without reward.

<a id="rolling-attribution"></a>

### Rolling Attribution

Rolling attribution repeats the realized attribution over rolling windows,
showing how contributions evolve through time:

```python
rolling_realized_attrib = mpp.rolling_realized_attribution(
    factor_model=factor_model,
    compute_uncertainty=True,
    compute_asset_breakdowns=False,
)
rolling_realized_attrib.summary_df().head(8)
```

<div class="rendered_html">
<table class="dataframe dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th></th>
      <th>Volatility Contribution</th>
      <th>% of Total Variance</th>
      <th>Mean Return Contribution (95% CI)</th>
    </tr>
    <tr>
      <th>Observation</th>
      <th>Component</th>
      <th></th>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th rowspan="4" valign="top">2015-10-09</th>
      <th>Systematic</th>
      <td>6.05%</td>
      <td>61.57%</td>
      <td>34.24% ± 11.08%</td>
    </tr>
    <tr>
      <th>Idiosyncratic</th>
      <td>3.79%</td>
      <td>38.54%</td>
      <td>5.60% ± 11.08%</td>
    </tr>
    <tr>
      <th>Unattributed</th>
      <td>-0.01%</td>
      <td>-0.11%</td>
      <td>-1.19%</td>
    </tr>
    <tr>
      <th>Total</th>
      <td>9.82%</td>
      <td>100.00%</td>
      <td>38.66%</td>
    </tr>
    <tr>
      <th rowspan="4" valign="top">2015-11-09</th>
      <th>Systematic</th>
      <td>7.12%</td>
      <td>80.97%</td>
      <td>30.77% ± 11.05%</td>
    </tr>
    <tr>
      <th>Idiosyncratic</th>
      <td>1.67%</td>
      <td>19.04%</td>
      <td>0.08% ± 11.05%</td>
    </tr>
    <tr>
      <th>Unattributed</th>
      <td>-0.00%</td>
      <td>-0.00%</td>
      <td>-0.64%</td>
    </tr>
    <tr>
      <th>Total</th>
      <td>8.79%</td>
      <td>100.00%</td>
      <td>30.21%</td>
    </tr>
  </tbody>
</table>
</div>

The summary carries one component breakdown per window, dated at the window end.

```python
rolling_realized_attrib.plot_exposure(top_n=15)
```

<figure class="factor-model-figure">
  <img src="../_static/factor_model/plots/attribution_rolling_realized_exposure.webp"
       alt="Rolling factor exposures of the portfolio throughout the backtest"
       width="1100" height="616"
       loading="lazy" decoding="async"
       style="display:block;width:100%;height:auto;">
</figure>

The constraints hold throughout the backtest: profitability stays at its 1.0
target, non-linear size at -2.0, and momentum near its 1.0 floor, rising above
it when the forecast premium strengthens (e.g. in 2018 and from late 2025).
Indexing the rolling attribution (`rolling_realized_attrib[i]`) retrieves a
single window with the same plots and DataFrames as above.

<a id="model-validation-and-review"></a>

## Model Validation and Review

Users who wish to review the implementation can start with the statistical
recovery suite in
`tests/test_prior/test_characteristics_factor_model/test_statistical_recovery.py`.
The tests build synthetic panels from known data-generating processes, fit
[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel) and verify that the estimated
quantities recover the intended model structure.

The suite covers factor returns, loadings, the covariance identity
$\Sigma = B F B^\top + D$, idiosyncratic risk, residual orthogonality,
exposure lagging, estimation masks, zero-sum constraints, neutralization,
inverse-idiosyncratic-variance weighting, time-varying market capitalizations,
changing universes and currency factors. These checks support implementation
review alongside the empirical diagnostics and walk-forward evaluation described
in this guide.

<a id="factor-model-performance"></a>

<a id="computational-performance"></a>

## Computational Performance

A production factor model processes large datasets. For example, a coverage
universe of 5,000 assets with 10 years of daily data and 80 characteristic
fields holds over a billion entries. This section describes how the
implementation handles this scale and what to expect in terms of fitting time and
memory usage.

<a id="factor-model-online-learning"></a>

<a id="online-learning"></a>

### Online Learning

The factor model supports online learning. `partial_fit` appends new
observations without refitting the history, and the result is identical to a
batch `fit` on the concatenated data. This is used in three ways:

* An [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) that does not fit in memory is
  processed chunk by chunk, with only the current chunk held in memory (see
  [Memory Usage](https://skfolio.org/user_guide/factor_models.html.md#factor-model-memory-usage)).
* Walk-forward evaluation and hyper-parameter tuning run in a single pass over
  the data through the online utilities `online_predict`,
  `online_covariance_forecast_evaluation` and `OnlineGridSearch`.
* In production, daily updates only fit the new observation instead of refitting
  the full history. Even for large models, this update runs in well under a
  second in the benchmarks below.

Internal state (estimator warmup, exposure and weight lag buffers, constraint
bases) is carried across calls, and `max_history` bounds the retained
time-series outputs to a rolling window.

```python
model.fit(characteristics=characteristics[:warmup])
for i in range(warmup, len(characteristics), 5):
    model.partial_fit(characteristics=characteristics[i : i + 5])
```

See [Online Learning](https://skfolio.org/user_guide/online_learning.html.md#online-learning) for the general framework.

<a id="benchmarks"></a>

### Benchmarks

The following fitting times were measured on 10 years of daily data (2,520
observations) on a laptop (Ultra 9 275HX, 24 cores, 32 GB RAM), for two models:

* Model 1: 16 factors (1 global, 10 industries, 5 styles) with default parameters.
* Model 2: the 58-factor model used throughout this guide (1 global, 44 industries, 13 styles
  from 29 descriptors), with within-industry scoring, neutralization, zero-sum
  constraints, two-pass inverse-idiosyncratic-variance regression weights and the
  regime-adjusted covariance estimator.

|   Assets | Model 1   | Model 2   |
|----------|-----------|-----------|
|      500 | 3 s       | 14 s      |
|    1,000 | 5 s       | 22 s      |
|    5,000 | 25 s      | 87 s      |

An incremental `partial_fit` on the next observation runs in under a second for both
models.

Achieving this performance relies on two implementation choices. First, the
hot paths are vectorized NumPy operations backed by parallel BLAS kernels.
Second, factor exposures are computed with thread-based parallelism (`n_jobs`),
which avoids copying the panel to worker processes (the computations are
NumPy-dominated and release the GIL, so threads provide effective parallelism
while sharing the panel in memory).

<a id="factor-model-memory-usage"></a>

<a id="memory-usage"></a>

### Memory Usage

By default, all panel data is held in memory for vectorized operations and
thread-based parallelism. A coverage
universe of 5,000 assets with 10 years of daily data (2,500 observations) and 80
characteristic fields holds $5{,}000 \times 80 \times 2{,}500 = 10^9$ entries,
or 8 GB in float64. This fits on a typical 32 GB machine.

When memory becomes a constraint, three options are available:

* Process the data in chunks with `partial_fit`, keeping only the current batch in
  memory and bounding the retained outputs with `max_history`.
* Store selected fields as float32 in the [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel),
  halving their footprint.
* Subclass [`AssetPanel`](https://skfolio.org/generated/skfolio.containers.AssetPanel.html.md#skfolio.containers.AssetPanel) to load characteristic fields
  lazily and release them once descriptors have consumed them.

<a id="references"></a>

## References

* <a id='id6'>**[1]**</a> “The Elements of Quantitative Investing”, Giuseppe A. Paleologo (2025).
* <a id='id7'>**[2]**</a> “Active Portfolio Management: A Quantitative Approach for Producing Superior Returns and Controlling Risk”, Richard C. Grinold & Ronald N. Kahn, McGraw-Hill (1999).
* <a id='id8'>**[3]**</a> “Portfolio Optimization: Theory and Application”, Chapter 3, Daniel P. Palomar (2025).
* <a id='id9'>**[4]**</a> “Extra-Market Components of Covariance in Security Returns”, Barr Rosenberg, Journal of Financial and Quantitative Analysis (1974).

# user_guide/hyper_parameters_tuning.html.md

<a id="hyper-parameters-tuning"></a>

<a id="id1"></a>

# Hyper-Parameters Tuning

Hyper-parameters tuning in `skfolio` follows the same API as `scikit-learn`.

Hyper-parameters are parameters that are not directly learnt within estimators.
They are passed as arguments to the constructor of the estimator classes.

It is possible and recommended to search the hyper-parameter space for the
best [cross validation](https://skfolio.org/user_guide/model_selection.html.md#cross-validation) score.

Any parameter provided when constructing an estimator may be optimized in this
manner. Specifically, to find the names and current values for all parameters
for a given estimator, use:

```default
estimator.get_params()
```

A search consists of:

- an estimator (such as [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk))
- a parameter space
- a method for searching or sampling candidates
- a cross-validation scheme
- a [score function](https://skfolio.org/user_guide/hyper_parameters_tuning.html.md#gridsearch-scoring)

Two generic approaches to parameter search are provided in
scikit-learn: for given values, `GridSearchCV` exhaustively considers
all parameter combinations, while `RandomizedSearchCV` can sample a
given number of candidates from a parameter space with a specified
distribution.

After describing these tools we detail [best practices](https://skfolio.org/user_guide/hyper_parameters_tuning.html.md#grid-search-tips) applicable to these approaches.

<a id="online-hyper-parameter-tuning"></a>

## Online Hyper-Parameter Tuning

In addition to `GridSearchCV` and `RandomizedSearchCV`, `skfolio` provides
stateful online search utilities for estimators that support `partial_fit`:
[`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch) and
[`OnlineRandomizedSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch).

These utilities evaluate each candidate through a full online walk-forward pass
instead of averaging independent fold scores. See [Online Learning](https://skfolio.org/user_guide/online_learning.html.md#online-learning) for
the online tuning workflow and the scoring conventions for component estimators
and portfolio optimizers.

<a id="exhaustive-grid-search"></a>

## Exhaustive Grid Search

The grid search provided by `GridSearchCV` exhaustively generates
candidates from a grid of parameter values specified with the `param_grid`
parameter. For instance, the following `param_grid`:

```default
param_grid = [
    {'l1_coef': [0.001, 0.01, 0.1], 'risk_measure': [RiskMeasure.SEMI_VARIANCE]},
    {'l1_coef': [0.001, 0.01, 0.1], 'l2_coef': [0.01, 0.1, 1], 'risk_measure': [RiskMeasure.CVAR]},
]
```

specifies that two grids should be explored: one with a Semi-Variance risk measure and
l1_coef values in [0.001, 0.01, 0.1], and the second one with a CVaR risk measure,
and the cross-product of l1_coef values ranging in [0.001, 0.01, 0.1] and l2_coef
values in  [0.01, 0.1, 1].

The `GridSearchCV` instance implements the usual estimator API: when
“fitting” it on a dataset all the possible combinations of parameter values are
evaluated and the best combination is retained.

**Example:**

```python
from sklearn.model_selection import GridSearchCV, KFold, train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

param_grid = [
    {'l1_coef': [0.001, 0.01, 0.1], 'risk_measure': [RiskMeasure.SEMI_VARIANCE]},
    {'l1_coef': [0.001, 0.01, 0.1], 'l2_coef': [0.01, 0.1, 1], 'risk_measure': [RiskMeasure.CVAR]},
]

grid_search = GridSearchCV(
    estimator=MeanRisk(min_weights=-1),
    cv=KFold(),
    param_grid=param_grid,
    n_jobs=-1  # using all cores
)
grid_search.fit(X_train)
print(grid_search.cv_results_)

best_model = grid_search.best_estimator_
print(best_model.weights_)
```

<a id="randomized-parameter-search"></a>

<a id="randomized-parameter-optimization"></a>

## Randomized Parameter Optimization

While using a grid of parameter settings is currently the most widely used
method for parameter optimization, other search methods have more
favorable properties.
`RandomizedSearchCV` implements a randomized search over parameters,
where each setting is sampled from a distribution over possible parameter values.
This has two main benefits over an exhaustive search:

* A budget can be chosen independently of the number of parameters and possible values.
* Adding parameters that do not influence the performance does not decrease efficiency.

Specifying how parameters should be sampled is done using a dictionary, very
similar to specifying parameters for `GridSearchCV`. Additionally,
a computation budget, being the number of sampled candidates or sampling
iterations, is specified using the `n_iter` parameter.
For each parameter, either a distribution over possible values or a list of
discrete choices (which will be sampled uniformly) can be specified.

In principle, any function can be passed that provides a `rvs` (random
variate sample) method to sample a value. A call to the `rvs` function should
provide independent random samples from possible parameter values on
consecutive calls.

The `scipy.stats` module contains many useful
distributions for sampling parameters, such as `expon`, `gamma`,
`uniform`, `loguniform` or `randint`.

For continuous parameters, such as `l1_coef` above, it is important to specify
a continuous distribution to take full advantage of the randomization. This way,
increasing `n_iter` will always lead to a finer search.

A continuous log-uniform random variable is the continuous version of
a log-spaced parameter. For example to specify the equivalent of `l2_coef` from above,
`loguniform(0.01,  1)` can be used instead of `[0.01, 0.1, 1]`.

Mirroring the example above in grid search, we can specify a continuous random
variable that is log-uniformly distributed between `0.01` and `1`:

```default
import scipy.stats as stats
{'l1_coef': stats.loguniform(0.01,  1), 'risk_measure': [RiskMeasure.SEMI_VARIANCE]}
```

**Example:**

```python
import scipy.stats as stats
from sklearn.model_selection import KFold, RandomizedSearchCV, train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

param_dist = {'l2_coef': stats.loguniform(0.01,  1), 'risk_measure': [RiskMeasure.CVAR]}

rd_search = RandomizedSearchCV(
    estimator=MeanRisk(min_weights=-1),
    cv=KFold(),
    n_iter=10,
    param_distributions=param_dist,
    n_jobs=-1  # using all cores
)
rd_search.fit(X_train)
print(rd_search.cv_results_)

best_model = rd_search.best_estimator_
print(best_model.weights_)
```

<a id="grid-search-tips"></a>

<a id="tips-for-parameter-search"></a>

## Tips for Parameter Search

<a id="gridsearch-scoring"></a>

<a id="specifying-an-objective-metric"></a>

### Specifying an Objective Metric

By default, all portfolio optimization estimators have the same score function which is
the **Sharpe Ratio**. This score function can be customized with
[`make_scorer`](https://skfolio.org/generated/skfolio.metrics.make_scorer.html.md#skfolio.metrics.make_scorer) by using another [measure](https://skfolio.org/api.html.md#measures-ref) or
by writing your own score function.

**Example:**

In the below example, the Sortino Ratio is used instead of the default Sharpe Ratio:

```python
from sklearn.model_selection import GridSearchCV, KFold, train_test_split

from skfolio import RatioMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.metrics import make_scorer
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

scoring = make_scorer(RatioMeasure.SORTINO_RATIO)

grid_search = GridSearchCV(
    estimator=MeanRisk(min_weights=-1),
    cv=KFold(),
    param_grid={'l2_coef': [0.0001, 0.001,  0.01, 1]},
    scoring=scoring
)

grid_search.fit(X_train)
print(grid_search.cv_results_)

best_model = grid_search.best_estimator_
print(best_model.weights_)

pred = best_model.predict(X_test)
print(pred.sortino_ratio)
```

**Example:**

In this example, we use a custom score function:

```python
def custom_score(pred):
    return pred.mean - 2 * pred.variance - 3 * pred.semi_variance

scoring = make_scorer(custom_score)
```

<a id="composite-grid-search"></a>

<a id="composite-estimators-and-parameter-spaces"></a>

### Composite Estimators and Parameter Spaces

`GridSearchCV` and `RandomizedSearchCV` allow searching over
parameters of composite or nested estimators using a dedicated
`<estimator>__<parameter>` syntax.

**Example:**

In the below example, we search for the optimal parameter `half_life` of the nested
estimator [`EWMu`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu):

```python
from sklearn.model_selection import GridSearchCV, KFold, train_test_split

from skfolio.datasets import load_sp500_dataset
from skfolio.moments import EWMu
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=EmpiricalPrior(mu_estimator=EWMu(half_life=40)),
)

print(model.get_params(deep=True))

param_grid = {"prior_estimator__mu_estimator__half_life": [10, 20, 30, 40]}

grid_search = GridSearchCV(
    estimator=model,
    cv=KFold(),
    param_grid=param_grid,
)

grid_search.fit(X_train)
print(grid_search.best_estimator_)
```

**Example:**

The same logic applies to `Pipeline`. Here we search for the optimal risk measure of
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) which is part of a `Pipeline`:

```python
from sklearn.model_selection import GridSearchCV, KFold, train_test_split
from sklearn.pipeline import Pipeline

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk
from skfolio.pre_selection import SelectKExtremes
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = Pipeline(
    [
        ("pre_selection", SelectKExtremes(k=10, highest=True)),
        ("optimization", MeanRisk()),
    ]
)

param_grid = {
    "optimization__risk_measure": [RiskMeasure.SEMI_VARIANCE, RiskMeasure.CVAR]
}

grid_search = GridSearchCV(
    estimator=model,
    cv=KFold(),
    param_grid=param_grid,
)

grid_search.fit(X_train)
print(grid_search.best_estimator_)
```

<a id="parallelism"></a>

### Parallelism

The parameter search tools evaluate each parameter combination on each data
fold independently. Computations can be run in parallel by using the keyword
`n_jobs=-1`. See function signature for more details.

# user_guide/index.html.md

<a id="user-guide"></a>

<a id="id1"></a>

# User Guide

`skfolio` is a Python library for portfolio optimization, factor model construction,
and risk management, built on top of scikit-learn to perform model selection, validation,
parameter tuning, and stress testing, with tools designed to reduce the risk of data
leakage and overfitting.

The public API is stable from version 1.0.0
onward and follows [semantic versioning](https://semver.org): no backward-incompatible
change within the 1.x series, and anything scheduled for removal raises a
`FutureWarning` before being removed in the next major release.
Upgrading between major versions is covered in the [Migration Guide](https://skfolio.org/user_guide/migration.html.md#migration).

[Skfolio Labs](https://skfoliolabs.com) provides enterprise support and dedicated SLAs for institutions.

# user_guide/install.html.md

<a id="installation"></a>

# Installation

<a id="install-using-pip"></a>

## Install using pip

`skfolio` is available on PyPI and can be installed with:

```console
$ pip install skfolio
```

<a id="install-using-conda"></a>

## Install using conda

```console
$ conda install -c conda-forge skfolio
```

<a id="install-additional-solvers"></a>

## Install Additional Solvers

The solver `Clarabel` is installed by default. Cardinality and threshold constraints
require a mixed-integer solver. To install additional solvers (e.g. `SCIP`, `GUROBI`,
`MOSEK`), please refer to
[the cvxpy documentation](https://www.cvxpy.org/install/index.html)

<a id="dependencies"></a>

## Dependencies

`skfolio` requires:

- python (>= 3.10)
- numpy (>= 1.24.0)
- scipy (>= 1.15.2)
- pandas (>= 2.1.0)
- cvxpy-base (>= 1.5.0)
- clarabel (>= 0.10.0)
- scikit-learn (>= 1.6.0)
- joblib (>= 1.3.2)
- plotly (>= 6.0.0)

# user_guide/metadata_routing.html.md

<a id="metadata-routing"></a>

<a id="id1"></a>

# Metadata Routing

This document shows how you can use the metadata routing mechanism to route metadata
to the estimators consuming them.
For a complete explanation, you can refer to the [scikit-learn documentation](https://scikit-learn.org/stable/auto_examples/miscellaneous/plot_metadata_routing.html#sphx-glr-auto-examples-miscellaneous-plot-metadata-routing-py)

A full example is available here: [Using Implied Volatility with Metadata Routing](https://skfolio.org/auto_examples/metadata_routing/plot_1_implied_volatility.html.md#sphx-glr-auto-examples-metadata-routing-plot-1-implied-volatility-py)

Let’s suppose you use the [`ImpliedCovariance`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance) estimator
inside a [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) estimator.
In addition to the assets’ returns `X`, the `ImpliedCovariance` estimator also needs
the assets’ implied volatilities passed to its `fit` method.
In order to route the implied volatilities time series from the `MeanRisk` estimator
to the `ImpliedCovariance` estimator, we need metadata routing.

First, a few imports and some random data for the rest of the script:

```python
from sklearn import set_config

from skfolio.moments import ImpliedCovariance
from skfolio.optimization import MeanRisk
from skfolio.prior import EmpiricalPrior
from skfolio.preprocessing import prices_to_returns
from skfolio.datasets import load_sp500_dataset, load_sp500_implied_vol_dataset

prices = load_sp500_dataset()
implied_vol = load_sp500_implied_vol_dataset()

X = prices_to_returns(prices)
X = X.loc["2010":]
```

Metadata routing is available only if explicitly enabled:

```python
set_config(enable_metadata_routing=True)
```

Then, in order to route the metadata, you must use `set_fit_request`:

```python
model = MeanRisk(
    prior_estimator=EmpiricalPrior(
        covariance_estimator=ImpliedCovariance(
        ).set_fit_request(implied_vol=True)
    )
)
model.fit(X, implied_vol=implied_vol)
print(model.weights_)
```

# user_guide/migration.html.md

<a id="migration"></a>

<a id="migration-guide"></a>

# Migration Guide

`skfolio` follows [semantic versioning](https://semver.org). The public API remains
backward compatible within a major series. Deprecated functionality raises a
`FutureWarning` and is removed in the next major release.

This page documents the changes required to upgrade between major versions.

<a id="migration-1-0"></a>

<a id="migrating-to-1-0"></a>

## Migrating to 1.0

Version 1.0 introduces the stable public API. The parameters and aliases deprecated
during the 0.x series are removed in this release.

<a id="exponentially-weighted-moments"></a>

### Exponentially Weighted Moments

[`EWMu`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu) and [`EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance) no longer
accept `alpha`. Use `half_life`, the number of observations for a weight to decay
to 50%.

Before:

```python
EWMu(alpha=0.2)
EWCovariance(alpha=0.2)
```

After:

```python
EWMu(half_life=3.11)
EWCovariance(half_life=3.11)
```

The half-life equivalent of a given `alpha` is

$$
\text{half-life} = \frac{-1}{\log_2(1 - \alpha)}

$$

For example, `alpha=0.2` corresponds to a `half_life` of approximately $3.11$
and `alpha=0.02` to $34.31$. The decay factor is
$\lambda = 2^{-1/\text{half-life}}$, computed by
[`half_life_to_decay_factor`](https://skfolio.org/generated/skfolio.utils.tools.half_life_to_decay_factor.html.md#skfolio.utils.tools.half_life_to_decay_factor).

Passing `alpha` raises a `TypeError`.

<a id="walk-forward-cross-validation"></a>

### Walk-Forward Cross-Validation

[`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) no longer accepts `expend_train`. Use
`expand_train`, which has identical behavior.

Before:

```python
WalkForward(test_size=60, train_size=252, expend_train=True)
```

After:

```python
WalkForward(test_size=60, train_size=252, expand_train=True)
```

<a id="factor-models"></a>

### Factor Models

The `FactorModel` prior estimator is replaced by
[`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel), and `factors` is now a keyword-only
argument of `fit`.

Before:

```python
from skfolio.optimization import MeanRisk
from skfolio.prior import FactorModel

model = MeanRisk(prior_estimator=FactorModel())
model.fit(X_train, y_train)
```

After:

```python
from skfolio.optimization import MeanRisk
from skfolio.prior import TimeSeriesFactorModel

model = MeanRisk(prior_estimator=TimeSeriesFactorModel())
model.fit(X_train, factors=factors_train)
```

#### WARNING
`FactorModel` now refers to a different object: the fitted factor model container
exposed on `factor_model`, holding the
loading matrix, the factor and idiosyncratic moments, and the realized factor
returns. The import therefore still resolves, and estimator arguments passed to
`FactorModel` raise a `TypeError` for unexpected keyword arguments rather than an
`ImportError`.

[`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel) provides a cross-sectional
alternative, fitted from point-in-time asset characteristics rather than factor return
time series. See [Factor Models](https://skfolio.org/user_guide/factor_models.html.md#factor-models).

<a id="uncertainty-sets"></a>

### Uncertainty Sets

[`UncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.UncertaintySet.html.md#skfolio.uncertainty_set.UncertaintySet) now describes a general norm-ball
rather than an ellipsoid, which allows box and diamond sets to use the same
representation. The ellipsoid is the $p = 2$ case.

The field names changed as follows:

| Before         | After      | Description                                                                                    |
|----------------|------------|------------------------------------------------------------------------------------------------|
| `k`            | `radius`   | Size $\kappa$ of the normalized uncertainty ball.                                              |
| `sigma`        | `geometry` | Linear map $L$ with $S = L L^{T}$ for an ellipsoid with shape<br/>matrix $S$. May be low-rank. |
| not applicable | `norm`     | Norm $p$ selecting the shape, defaulting to $2$ for an ellipsoid.                              |

This only affects code that constructs an `UncertaintySet` directly or reads the fitted
`uncertainty_set_` attribute. Passing an uncertainty set estimator to
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) is unchanged.

Two factor-model estimators are added:
[`OrthogonalMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet) and
[`OrthogonalCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet). See
[Uncertainty Set](https://skfolio.org/user_guide/uncertainty_set.html.md#uncertainty-set-estimator).

<a id="migration-scheduled-removals"></a>

<a id="scheduled-for-removal-in-2-0"></a>

## Scheduled for Removal in 2.0

The following remain available throughout 1.x and raise a `FutureWarning`:

* `annualized_factor`, on [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) and
  [`ImpliedCovariance`](https://skfolio.org/generated/skfolio.moments.ImpliedCovariance.html.md#skfolio.moments.ImpliedCovariance). Use `annualization_factor`.
* `non_denominated_sort`, as a function and as a
  [`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population) method. Use `non_dominated_sort`.

# user_guide/model_selection.html.md

<a id="model-selection"></a>

<a id="id1"></a>

# Model Selection

The Model Selection module extends `sklearn.model_selection` by adding additional
methods tailored for portfolio selection.

<a id="online-learning"></a>

## Online Learning

In addition to fold-based cross-validation utilities,
`skfolio.model_selection` provides stateful online utilities for estimators
that support `partial_fit`. These utilities update a single estimator through
time instead of fitting an independent clone on each split, which is
particularly useful for exponentially weighted moments and portfolio optimizers
built on top of them.

See [Online Learning](https://skfolio.org/user_guide/online_learning.html.md#online-learning) for the full workflow and the differences between
online evaluation and standard cross-validation.

<a id="cross-validation"></a>

<a id="cross-validation-prediction"></a>

## Cross-Validation Prediction

Every `skfolio` estimator is compatible with `sklearn.model_selection.cross_val_predict`.
We also implement our own [`cross_val_predict`](https://skfolio.org/generated/skfolio.model_selection.cross_val_predict.html.md#skfolio.model_selection.cross_val_predict) for enhanced integration
with `Portfolio` and `Population` objects, as well as compatibility with
[`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) and [`MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV).

<a id="data-leakage"></a>

#### DANGER
When using `scikit-learn` selection tools like `KFold` or `train_test_split`, ensure
that the parameter `shuffle` is set to `False` to avoid data leakage. Financial
features often incorporate series that exhibit serial correlation (like ARMA
processes) and shuffling the data will lead to leakage from the test set to the
training set.

In `cross_val_predict`, the data is split according to the `cv` parameter.
The portfolio optimization estimator is fitted on the training set and portfolios are
predicted on the corresponding test set.

For `scikit-learn` cross-validation methods such as `KFold` and `skfolio`’s
`WalkForward`, the output is a [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio), where
each [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) corresponds to the prediction on a single
train/test split (resulting in K portfolios for `KFold`).

For combinatorial cross-validation methods such as [`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) and
Monte Carlo-style methods such as [`MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV), the output is a
[`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population) containing multiple
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio). This is because each test produces a
collection of multiple paths rather than a single path.

Portfolio parameters can be set in the portfolio optimizer’s `portfolio_params` or
passed to `cross_val_predict`. The parameters shared by
[`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) and
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) (`compounded`, `risk_free_rate`,
`annualization_factor`, `fitness_measures` and the risk measure parameters) are applied
to the resulting `MultiPeriodPortfolio` and to each `Portfolio` it contains. A value
passed to `cross_val_predict` takes precedence over the optimizer’s `portfolio_params`.
When omitted, it is inherited from the optimizer’s `portfolio_params`, and
`risk_free_rate` falls back to the optimizer’s `risk_free_rate` parameter when it has
one. For example, `MeanRisk(portfolio_params={"compounded": True})` produces a
compounded `MultiPeriodPortfolio` from `cross_val_predict` without repeating the
setting. These parameters only affect how the portfolios are measured: a
`risk_free_rate` passed to `cross_val_predict` does not change the optimizer’s own
`risk_free_rate`.

`weight_drift` applies to each `Portfolio` of the path. With `weight_drift=True`, the
weights held within each test window drift with the asset returns, and the path runs
sequentially. A value passed to `cross_val_predict` overrides the optimizer’s
`portfolio_params`. Optimizer parameters such as `transaction_costs`,
`management_fees` and `previous_weights` are not accepted in the function’s
`portfolio_params`: set them on the optimizer, which forwards them to the predicted
`Portfolio` objects. `name`, `tag`, `sample_weight` and `check_observations_order`
apply to the resulting `MultiPeriodPortfolio` only.

For example, to evaluate a drifted, compounded path with transaction costs:

```python
pred = cross_val_predict(
    MeanRisk(transaction_costs=0.001 / 5),
    X,
    cv=WalkForward(test_size=5, train_size=252),
    portfolio_params={"weight_drift": True, "compounded": True},
)
```

With a sequential splitter, the `ending_weights` of each portfolio are passed as
`previous_weights` to the next fit. They equal the target weights when
`weight_drift=False` and the weights after the last observation when
`weight_drift=True`, so transaction costs and `max_turnover` are then measured from the
holdings a fund would trade from. A failed period keeps the last successful ending
weights. The sequential path requires one portfolio per fold and raises for estimators
that return a [`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population). With non-sequential splitters
such as `KFold`, drift is evaluated inside each test fold and is not propagated. See
[Backtesting and Evaluation](https://skfolio.org/user_guide/backtesting_and_evaluation.html.md#backtesting-and-evaluation) for the choice between `weight_drift=False` and
`weight_drift=True`.

**Example:**

```python
import numpy as np
from sklearn.model_selection import KFold

from skfolio.datasets import load_sp500_dataset
from skfolio.model_selection import (
    CombinatorialPurgedCV,
    WalkForward,
    cross_val_predict,
)
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)

# KFold
# One single path -> pred is a MultiPeriodPortfolio
pred = cross_val_predict(MeanRisk(), X, cv=KFold())
print(pred.sharpe_ratio)
np.asarray(pred)  # predicted returns vector

# WalkForward
# One single path -> pred is a MultiPeriodPortfolio
pred = cross_val_predict(
    MeanRisk(),
    X,
    cv=WalkForward(test_size=3, train_size=12, freq="WOM-3FRI")
)
print(pred.sharpe_ratio)
np.asarray(pred)  # predicted returns vector

# CombinatorialPurgedCV
# Multiple paths -> pred is a Population of MultiPeriodPortfolio
pred = cross_val_predict(MeanRisk(), X, cv=CombinatorialPurgedCV())
print(pred.summary())
print(np.asarray(pred))  # predicted returns matrix

# MultipleRandomizedCV
# Multiple paths -> pred is a Population of MultiPeriodPortfolio
pred = cross_val_predict(
    MeanRisk(),
    X,
    cv=MultipleRandomizedCV(
        walk_forward=WalkForward(test_size=1, train_size=2),
        n_subsamples=2,
        asset_subset_size=3,
    )
)
print(pred.summary())
print(np.asarray(pred))  # predicted returns matrix
```

<a id="walk-forward-cross-validation"></a>

## Walk-Forward Cross-Validation

The [`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) splitter divides time series data using a walk‑forward approach.
Unlike `sklearn.model_selection.TimeSeriesSplit`, you specify the number of training
and test samples rather than the number of splits, making it more suitable for portfolio
cross‑validation.

If your data is a DataFrame indexed by a `pandas.DatetimeIndex`, you can split it
using specific datetime frequencies and offsets.

<a id="combinatorial-purged-cross-validation"></a>

## Combinatorial Purged Cross-Validation

Compared to `KFold`, which splits the data into k folds and generates one single testing
path, the [`CombinatorialPurgedCV`](https://skfolio.org/generated/skfolio.model_selection.CombinatorialPurgedCV.html.md#skfolio.model_selection.CombinatorialPurgedCV) uses the combination of multiple
train/test sets to generate multiple testing paths.

To avoid data leakage, purging and embargoing can be performed.

Purging consists of removing from the training set all observations
whose labels overlapped in time with those labels included in the testing set.
Embargoing consists of removing from the training set observations that immediately
follow an observation in the testing set, since financial features often incorporate
series that exhibit serial correlation (like ARMA processes).

When used with [`cross_val_predict`](https://skfolio.org/generated/skfolio.model_selection.cross_val_predict.html.md#skfolio.model_selection.cross_val_predict), the object returned is a
[`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population) of
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) representing each prediction path.

**Example:**

```python
from skfolio import RatioMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.model_selection import CombinatorialPurgedCV, cross_val_predict
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)

pred = cross_val_predict(MeanRisk(), X, cv=CombinatorialPurgedCV())
print(pred.summary())

portfolio = pred.quantile(measure=RatioMeasure.SHARPE_RATIO, q=0.95)
print(portfolio.annualized_sharpe_ratio)
```

The default parameters of the `CombinatorialPurgedCV` are `n_folds=10` and
`n_test_folds=8`. You may want to choose these parameters to target a number of test
paths and an average training size. The latter depends on the number of observations.
For that, you can use the function [`optimal_folds_number`](https://skfolio.org/generated/skfolio.model_selection.optimal_folds_number.html.md#skfolio.model_selection.optimal_folds_number) as shown in the example
[HRP vs HERC](https://skfolio.org/auto_examples/clustering/plot_3_hrp_vs_herc.html.md#sphx-glr-auto-examples-clustering-plot-3-hrp-vs-herc-py).

```python
n_folds, n_test_folds = optimal_folds_number(
    n_observations=X_test.shape[0],
    target_n_test_paths=100,
    target_train_size=252,
)

cv = CombinatorialPurgedCV(n_folds=n_folds, n_test_folds=n_test_folds)
cv.summary(X_test)
```

<a id="multiple-randomized-cross-validation"></a>

## Multiple Randomized Cross-Validation

The [`MultipleRandomizedCV`](https://skfolio.org/generated/skfolio.model_selection.MultipleRandomizedCV.html.md#skfolio.model_selection.MultipleRandomizedCV) cross‑validation strategy, based on the
“Multiple Randomized Backtests” methodology of Palomar, performs a Monte
Carlo–style evaluation by repeatedly sampling **distinct** asset subsets (without
replacement) and **contiguous** time windows. It then applies an inner walk‑forward
split to each subsample, capturing both temporal and cross‑sectional variability in
performance.

When used with [`cross_val_predict`](https://skfolio.org/generated/skfolio.model_selection.cross_val_predict.html.md#skfolio.model_selection.cross_val_predict), the object returned is a
[`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population) of
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) representing each prediction path.

```python
import numpy as np
from skfolio.datasets import load_sp500_dataset, load_factors_dataset
from skfolio.model_selection import WalkForward, MultipleRandomizedCV, cross_val_predict
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)

cv = MultipleRandomizedCV(
    walk_forward=WalkForward(test_size=3, train_size=6, freq="WOM-3FRI"),
    n_subsamples=100,
    asset_subset_size=3,
    window_size=2*252,
)

pred = cross_val_predict(MeanRisk(), X, cv=cv)
print(pred.summary())

portfolio = pred.quantile(measure=RatioMeasure.SHARPE_RATIO, q=0.95)
print(portfolio.annualized_sharpe_ratio)
```

# user_guide/online_learning.html.md

<a id="online-learning"></a>

<a id="id1"></a>

# Online Learning

`skfolio` provides dedicated online utilities for estimators that support
`partial_fit`. By updating a single stateful estimator incrementally rather than
refitting from scratch at every split, online evaluation is significantly faster than
standard cross-validation. These utilities cover stateful walk-forward evaluation,
online covariance forecast diagnostics, and online hyper-parameter tuning.

Examples of supported estimators include
[`EWMu`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu), [`EWCovariance`](https://skfolio.org/generated/skfolio.moments.EWCovariance.html.md#skfolio.moments.EWCovariance),
[`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance),
[`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior) and portfolio
optimizers such as [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) when they embed
incremental moment estimators through a prior estimator.

Online learning is also where native NaN-aware estimators are especially useful:
they can update from available observations while preserving estimator state. Pipeline
based pre-selection and imputation are not currently available in `skfolio` online
learning workflows. See [Missing Data and Changing Universes](https://skfolio.org/user_guide/data_representation.html.md#missing-data)
for details.

<a id="how-online-evaluation-works"></a>

## How Online Evaluation Works

The online utilities all follow the same stateful evaluation pattern:

1. Clone the estimator once, starting from a clean unfitted state.
2. Initialize it on the first `warmup_size` observations with `partial_fit`.
3. Evaluate on the next test window out-of-sample, with optional purging
   between the data seen by the estimator and the test window.
4. Update the same estimator with the newly observed data.
5. Repeat until the end of the sample.

This differs from standard cross-validation, where each split fits an
independent estimator clone. In the online setting, the estimator state is
carried forward through time.

<a id="non-predictor-estimators-versus-portfolio-optimizers"></a>

## Non-Predictor Estimators Versus Portfolio Optimizers

The online API distinguishes between non-predictor estimators and portfolio
optimizers.

* **Non-predictor estimators** such as covariance, expected-return, and prior
  estimators do not implement `predict`. Their scores are computed from the
  fitted estimator and the current test window using callables such as
  `scorer(estimator, X_test)`. When using
  [`make_scorer`](https://skfolio.org/generated/skfolio.metrics.make_scorer.html.md#skfolio.metrics.make_scorer), the appropriate form is
  `make_scorer(..., response_method=None)`.
* **Portfolio optimization estimators** such as
  [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) are evaluated by collecting the
  out-of-sample predictions into a
  [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio). Measures are then computed
  on that aggregate portfolio. In that case, scoring uses
  [`BaseMeasure`](https://skfolio.org/generated/skfolio.measures.BaseMeasure.html.md#skfolio.measures.BaseMeasure) enums directly rather than
  [`make_scorer`](https://skfolio.org/generated/skfolio.metrics.make_scorer.html.md#skfolio.metrics.make_scorer).

Accordingly, [`online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict) is restricted to
portfolio optimizers, while [`online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score) and
[`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch) /
[`OnlineRandomizedSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch) accept both categories.

<a id="online-versus-standard-cross-validation"></a>

## Online Versus Standard Cross-Validation

The standard [`cross_val_predict`](https://skfolio.org/generated/skfolio.model_selection.cross_val_predict.html.md#skfolio.model_selection.cross_val_predict) and its online
counterpart [`online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict) are both designed
exclusively for **portfolio optimization** estimators. The key differences are:

* **Fitting strategy**: standard cross-validation clones and refits the estimator from
  scratch at every fold, while online evaluation maintains a single stateful estimator
  updated incrementally via `partial_fit`, which is significantly faster.
* **Scoring methodology**: standard cross-validation scores each test fold independently
  and averages the results, which can be unreliable when test folds are short (e.g. the
  Sharpe ratio is undefined on a single observation). Online evaluation instead collects
  all out-of-sample predictions into a single
  [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) and computes the metric on the full
  out-of-sample path, which is generally preferred for short rebalancing horizons.

[`online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score) extends online evaluation to both
portfolio optimizers and non-predictor estimators (covariance, expected-return, and
prior estimators). For non-predictor estimators, scores are computed per test window
and averaged by default.

Because the scoring methodology differs for portfolio optimizers, the online utilities
are complementary to the existing cross-validation tools rather than replacements.

<a id="online-covariance-forecast-evaluation"></a>

## Online Covariance Forecast Evaluation

[`online_covariance_forecast_evaluation`](https://skfolio.org/generated/skfolio.model_selection.online_covariance_forecast_evaluation.html.md#skfolio.model_selection.online_covariance_forecast_evaluation)
evaluates the quality of covariance forecasts out-of-sample. It is intended for
covariance estimators rather than portfolio optimizers, which should instead be
evaluated with [`online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict) or
[`online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score).

At each step, the covariance forecast produced after `partial_fit` is compared
to the realized returns over the next test window. The resulting
[`CovarianceForecastEvaluation`](https://skfolio.org/generated/skfolio.model_selection.CovarianceForecastEvaluation.html.md#skfolio.model_selection.CovarianceForecastEvaluation) provides
diagnostics such as:

* Mahalanobis calibration ratio for the full covariance structure across all
  eigenvalue directions.
* Diagonal calibration ratio for asset-level variance calibration.
* Portfolio standardized returns and the associated bias statistic for
  calibration along one portfolio direction by default, or multiple portfolio
  directions when explicit test portfolios are provided.
* Portfolio QLIKE for portfolio variance forecast quality along one or more
  portfolio directions.

When `portfolio_weights=None`, the portfolio diagnostics use a single dynamic
inverse-volatility portfolio direction by default. Passing explicit portfolio
weights extends the evaluation to multiple selected traded directions.

See the example
[Online Covariance Forecast Evaluation](https://skfolio.org/auto_examples/online_learning/plot_1_online_covariance_forecast_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-1-online-covariance-forecast-evaluation-py)
for the complete workflow.

<a id="online-hyper-parameter-tuning"></a>

## Online Hyper-Parameter Tuning

[`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch) and
[`OnlineRandomizedSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch) extend the online
workflow to hyper-parameter selection.

Conceptually, this is the online counterpart of combining
`GridSearchCV` or
`RandomizedSearchCV` with
[`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) using `expand_train=True`.
The key difference is that online search updates each candidate
incrementally via `partial_fit` along one sequential path instead of
refitting it from scratch at every split.

Each candidate parameter configuration is evaluated on one full online
walk-forward path. When `refit=True`, `best_estimator_` exposes the selected
fitted candidate without an additional fit after model selection because it
has already been updated through the full sample during evaluation.

For non-predictor estimators, online tuning typically uses callable scorers
such as QLIKE or calibration losses, typically wrapped with
[`make_scorer`](https://skfolio.org/generated/skfolio.metrics.make_scorer.html.md#skfolio.metrics.make_scorer) using `response_method=None`. For
multi-metric searches, `refit` should be set explicitly to the name of the
metric used to select the best candidate.

See the example
[Online Covariance Hyperparameter Tuning](https://skfolio.org/auto_examples/online_learning/plot_2_online_hyperparameter_tuning.html.md#sphx-glr-auto-examples-online-learning-plot-2-online-hyperparameter-tuning-py)
for covariance tuning with both
[`OnlineGridSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineGridSearch.html.md#skfolio.model_selection.OnlineGridSearch) and
[`OnlineRandomizedSearch`](https://skfolio.org/generated/skfolio.model_selection.OnlineRandomizedSearch.html.md#skfolio.model_selection.OnlineRandomizedSearch).

<a id="online-evaluation-of-portfolio-optimization"></a>

## Online Evaluation of Portfolio Optimization

For portfolio optimizers, the main entry points are
[`online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict) and
[`online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score).

* [`online_predict`](https://skfolio.org/generated/skfolio.model_selection.online_predict.html.md#skfolio.model_selection.online_predict) returns a
  [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) built from the sequence of
  out-of-sample portfolio predictions.
* [`online_score`](https://skfolio.org/generated/skfolio.model_selection.online_score.html.md#skfolio.model_selection.online_score) returns a scalar measure, or a
  dict of measures, computed on the aggregate online evaluation.

This is useful when a portfolio estimator embeds incremental moment estimators such as
[`EWMu`](https://skfolio.org/generated/skfolio.moments.EWMu.html.md#skfolio.moments.EWMu) and
[`RegimeAdjustedEWCovariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWCovariance.html.md#skfolio.moments.RegimeAdjustedEWCovariance).

During online portfolio evaluation, each rebalance is solved after the estimator has
incorporated the observations available at that date. If the optimization problem cannot
be solved and `raise_on_failure=False`, `online_predict` records that rebalance as a
[`FailedPortfolio`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio) and continues with the next window. When the
estimator uses previous weights, the last valid allocation remains the reference for
later rebalances.

Pass `portfolio_params={"weight_drift": True, "compounded": True}` to
`online_predict` to evaluate the path with drifted weights and compounded returns. The
`portfolio_params` of `online_predict` follow the same rules as those of
[`cross_val_predict`](https://skfolio.org/generated/skfolio.model_selection.cross_val_predict.html.md#skfolio.model_selection.cross_val_predict): the parameters shared by
[`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) and
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) are applied to the returned
`MultiPeriodPortfolio` and to each `Portfolio` it contains, take precedence over the
optimizer’s `portfolio_params` and are inherited from it when omitted. `weight_drift`
applies to each `Portfolio` of the path. See [Cross-Validation Prediction](https://skfolio.org/user_guide/model_selection.html.md#cross-validation) for the complete
rules.

When the estimator needs previous weights, the `ending_weights` of the last successful
portfolio become the `previous_weights` of the next rebalancing. They equal its target
weights with `weight_drift=False` and its weights after the final observation with
`weight_drift=True`.

`online_score`, `OnlineGridSearch` and `OnlineRandomizedSearch` accept the same
`portfolio_params` when evaluating a portfolio optimizer. Because they score the
resulting `MultiPeriodPortfolio`, these parameters can change the scores and the
ranking of the parameter sets. When refitting is enabled, `weight_drift` is retained in
`best_estimator_` because prediction requires it. The other parameters are not.

To hold the last allocation instead of producing a failed rebalance, configure
`fallback="previous_weights"`. Other fallback estimators are not available with
`partial_fit`, because they would not have learned from the same sequence of past
observations.

See the example
[Online Evaluation of Portfolio Optimization](https://skfolio.org/auto_examples/online_learning/plot_3_online_portfolio_optimization_evaluation.html.md#sphx-glr-auto-examples-online-learning-plot-3-online-portfolio-optimization-evaluation-py)
for an end-to-end online evaluation of
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk).

# user_guide/optimization.html.md

<a id="optimization"></a>

<a id="id1"></a>

# Optimization

The optimization module implements a set of methods intended for portfolio optimization.
They follow the same API as scikit-learn’s `estimator`: the `fit` method takes `X` as
the assets returns and stores the portfolio weights in its `weights_` attribute.

`X` can be any array-like structure (numpy array, pandas DataFrame, etc.)

All optimization inputs (expected returns, covariance, return scenarios) are expressed
in the periodicity of `X`: with daily returns, the optimizer works with daily moments
and scenarios rather than annualized ones. Parameters that share the unit of expected
returns, such as `transaction_costs` and `management_fees`, must be expressed in the
same periodicity. See [Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention) for the
rationale and the cost conversion rules.

<a id="naive-allocation"></a>

## Naive Allocation

The naive module implements a set of naive allocations commonly used as benchmarks for
comparing different models:

> * [`EqualWeighted`](https://skfolio.org/generated/skfolio.optimization.EqualWeighted.html.md#skfolio.optimization.EqualWeighted)
> * [`InverseVolatility`](https://skfolio.org/generated/skfolio.optimization.InverseVolatility.html.md#skfolio.optimization.InverseVolatility)
> * [`Random`](https://skfolio.org/generated/skfolio.optimization.Random.html.md#skfolio.optimization.Random)

**Example:**

Naive inverse-volatility allocation:

```python
from sklearn.model_selection import train_test_split

from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import InverseVolatility
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = InverseVolatility()
model.fit(X_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.annualized_sharpe_ratio)
```

<a id="mean-risk-optimization"></a>

## Mean-Risk Optimization

The [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) estimator can solve the below 4 objective functions:

> * Minimize Risk:

> $$
> \begin{cases}
> \begin{aligned}
> &\min_{w} & & risk_{i}(w) \\
> &\text{s.t.} & & w^T\mu \ge min\_return \\
> & & & A w \ge b \\
> & & & risk_{j}(w) \le max\_risk_{j} \quad \forall \; j \ne i
> \end{aligned}
> \end{cases}

> $$

> * Maximize Expected Return:

> $$
> \begin{cases}
> \begin{aligned}
> &\max_{w} & & w^T\mu \\
> &\text{s.t.} & & risk_{i}(w) \le max\_risk_{i} \\
> & & & A w \ge b \\
> & & & risk_{j}(w) \le max\_risk_{j} \quad \forall \; j \ne i
> \end{aligned}
> \end{cases}

> $$

> * Maximize Utility:

> $$
> \begin{cases}
> \begin{aligned}
> &\max_{w} & & w^T\mu - \lambda \times risk_{i}(w)\\
> &\text{s.t.} & & risk_{i}(w) \le max\_risk_{i} \\
> & & & w^T\mu \ge min\_return \\
> & & & A w \ge b \\
> & & & risk_{j}(w) \le max\_risk_{j} \quad \forall \; j \ne i
> \end{aligned}
> \end{cases}

> $$

> * Maximize Ratio:

> $$
> \begin{cases}
> \begin{aligned}
> &\max_{w} & & \frac{w^T\mu - r_{f}}{risk_{i}(w)}\\
> &\text{s.t.} & & risk_{i}(w) \le max\_risk_{i} \\
> & & & w^T\mu \ge min\_return \\
> & & & A w \ge b \\
> & & & risk_{j}(w) \le max\_risk_{j} \quad \forall \; j \ne i
> \end{aligned}
> \end{cases}

> $$

With $risk_{i}$ a risk measure among:

> * Variance
> * Semi-Variance
> * Standard-Deviation
> * Semi-Deviation
> * Mean Absolute Deviation
> * First Lower Partial Moment
> * CVaR (Conditional Value at Risk)
> * EVaR (Entropic Value at Risk)
> * Worst Realization (worst return)
> * CDaR (Conditional Drawdown at Risk)
> * Maximum Drawdown
> * Average Drawdown
> * EDaR (Entropic Drawdown at Risk)
> * Ulcer Index
> * Gini Mean Difference

It supports the following parameters:

> * Weight Constraints
> * Budget Constraints
> * Group Constraints
> * Transaction Costs
> * Management Fees
> * L1 and L2 Regularization
> * Turnover Constraint
> * Tracking Error Constraint
> * Uncertainty Set on Expected Returns
> * Uncertainty Set on Covariance
> * Expected Return Constraints
> * Risk Measure Constraints
> * Custom Objective
> * Custom Constraints
> * Prior Estimator

**Example:**

Maximum Sharpe Ratio portfolio:

```python
from sklearn.model_selection import train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    risk_measure=RiskMeasure.VARIANCE,
)
model.fit(X_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.sharpe_ratio)
```

<a id="prior-estimator"></a>

### Prior Estimator

Every portfolio optimization has a parameter named `prior_estimator`.
The [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior) fits a [`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 of the covariance. It represents the investor’s prior beliefs about the
model used to estimate such distribution.

When the prior follows the native NaN-aware convention, compatible optimizers solve the
optimization problem on the investable subset and expand `weights_` back to the full
input universe. See [Missing Data and Changing Universes](https://skfolio.org/user_guide/data_representation.html.md#missing-data) for
details.

The available prior estimators are:

> * [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior)
> * [`BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman)
> * [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel)

**Example:**

Minimum Variance portfolio using a Factor Model:

```python
from sklearn.model_selection import train_test_split

from skfolio.datasets import load_factors_dataset, load_sp500_dataset
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import TimeSeriesFactorModel

prices = load_sp500_dataset()
factor_prices = load_factors_dataset()

X, factors = prices_to_returns(prices, factor_prices)
X_train, X_test, factors_train, factors_test = train_test_split(X, factors, test_size=0.33, shuffle=False)

model = MeanRisk(prior_estimator=TimeSeriesFactorModel())
model.fit(X_train, factors=factors_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.annualized_sharpe_ratio)
```

<a id="combining-prior-estimators"></a>

### Combining Prior Estimators

Prior estimators can be combined together, making it possible to design complex models:

**Example:**

This example is **purposely complex** to demonstrate how multiple estimators can be
combined.

The model below is a Maximum Sharpe Ratio optimization using a Factor Model for the
estimation of the **assets** expected returns and covariance matrix. A Black & Litterman
model is used for the estimation of the **factors** expected returns and covariance matrix,
incorporating the analysts’ views on the factors. Finally, the Black & Litterman prior
expected returns are estimated using an equal-weighted market equilibrium with a risk
aversion of 2 and a denoised prior covariance matrix:

```python
from sklearn.model_selection import train_test_split

from skfolio.datasets import load_factors_dataset, load_sp500_dataset
from skfolio.moments import DenoiseCovariance, EquilibriumMu
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import BlackLitterman, EmpiricalPrior, TimeSeriesFactorModel

prices = load_sp500_dataset()
factor_prices = load_factors_dataset()

X, factors = prices_to_returns(prices, factor_prices)
X_train, X_test, factors_train, factors_test = train_test_split(X, factors, test_size=0.33, shuffle=False)

factor_views = ["MTUM - QUAL == 0.0003 ",
                "SIZE - USMV == 0.0004",
                "VLUE == 0.0006"]

model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    prior_estimator=TimeSeriesFactorModel(
        factor_prior_estimator=BlackLitterman(
            prior_estimator=EmpiricalPrior(
                mu_estimator=EquilibriumMu(risk_aversion=2),
                covariance_estimator=DenoiseCovariance()
            ),
            views=factor_views)
    )
)

model.fit(X_train, factors=factors_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.annualized_sharpe_ratio)
```

<a id="custom-estimator"></a>

### Custom Estimator

It is very common to use a custom implementation for the moments estimators. For
example, you may want to use an in-house estimation for the covariance or a predictive
model for the expected returns.

Below is a simple example of how you would implement a custom covariance estimator.
For more complex cases and estimators, check the [API Reference](https://skfolio.org/api.html.md#api).

```python
import numpy as np

from skfolio.datasets import load_sp500_dataset
from skfolio.moments import BaseCovariance
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior

prices = load_sp500_dataset()
X = prices_to_returns(prices)

class MyCustomCovariance(BaseCovariance):
    def __init__(self, my_param=0):
        super().__init__()
        self.my_param = my_param

    def fit(self, X, y=None):
        X = self._validate_data(X)
        # Your custom implementation goes here
        covariance = np.cov(X.T, ddof=self.my_param)
        self._set_covariance(covariance)
        return self

model = MeanRisk(
    prior_estimator=EmpiricalPrior(covariance_estimator=MyCustomCovariance(my_param=1)),
)
model.fit(X)
```

<a id="worst-case-optimization"></a>

### Worst-Case Optimization

With the `mu_uncertainty_set_estimator` parameter, the expected returns of the assets
are modeled with a [norm-ball uncertainty set](https://skfolio.org/user_guide/uncertainty_set.html.md#uncertainty-set-estimator). This
approach is known as worst-case optimization and falls under the class of robust
optimization. It mitigates the instability that arises from estimation errors of the
expected returns.

**Example:**

Worst-case maximum Mean/CDaR ratio (Conditional Drawdown at Risk) with an ellipsoidal
uncertainty set for the expected returns of the assets:

```python
from sklearn.model_selection import train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns
from skfolio.uncertainty_set import BootstrapMuUncertaintySet

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    risk_measure=RiskMeasure.CDAR,
    mu_uncertainty_set_estimator=BootstrapMuUncertaintySet(confidence_level=0.9),
)
model.fit(X_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.annualized_sharpe_ratio)
print(portfolio.cdar_ratio)
```

Covariance uncertainty is configured with `covariance_uncertainty_set_estimator`.
It is applied to the variance risk measure or a `max_variance` constraint. Generic
estimators use a lifted semidefinite formulation, while
[`OrthogonalCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet) uses a compact
representation in the factor model’s orthogonal space.

<a id="going-further"></a>

### Going Further

You can explore the remaining parameters (constraints, L1 and L2 regularization, costs,
turnover, tracking error, etc.) with the
[Mean-Risk examples](https://skfolio.org/auto_examples/mean_risk/index.html.md#mean-risk-examples) and the [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) API.

<a id="risk-budgeting"></a>

## Risk Budgeting

The [`RiskBudgeting`](https://skfolio.org/generated/skfolio.optimization.RiskBudgeting.html.md#skfolio.optimization.RiskBudgeting) solves the below convex problem:

> $$
> \begin{cases}
> \begin{aligned}
> &\min_{w} & & risk_{i}(w) \\
> &\text{s.t.} & & b^T log(w) \ge c \\
> & & & w^T\mu \ge min\_return \\
> & & & A w \ge b \\
> & & & w \ge0
> \end{aligned}
> \end{cases}

> $$

with $b$ the risk budget vector and $c$ an auxiliary variable of the log
barrier.

And $risk_{i}$ a risk measure among:

> * Variance
> * Semi-Variance
> * Standard-Deviation
> * Semi-Deviation
> * Mean Absolute Deviation
> * First Lower Partial Moment
> * CVaR (Conditional Value at Risk)
> * EVaR (Entropic Value at Risk)
> * Worst Realization (worst return)
> * CDaR (Conditional Drawdown at Risk)
> * Maximum Drawdown
> * Average Drawdown
> * EDaR (Entropic Drawdown at Risk)
> * Ulcer Index
> * Gini Mean Difference
> * First Lower Partial Moment

It supports the following parameters:

> * Weight Constraints
> * Budget Constraints
> * Group Constrains
> * Transaction Costs
> * Management Fees
> * Expected Return Constraints
> * Custom Objective
> * Custom constraints
> * Prior Estimator

Limitations are imposed on certain constraints, such as long-only weights, to ensure the
problem remains convex.

**Example:**

CVaR (Conditional Value at Risk) Risk Parity portfolio:

```python
from sklearn.model_selection import train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import RiskBudgeting
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = RiskBudgeting(risk_measure=RiskMeasure.CVAR)
model.fit(X_train)
print(model.weights_)

portfolio_train = model.predict(X_train)
print(portfolio_train.annualized_sharpe_ratio)
print(portfolio_train.contribution(measure=RiskMeasure.CVAR))

portfolio_test = model.predict(X_test)
print(portfolio_test.annualized_sharpe_ratio)
print(portfolio_test.contribution(measure=RiskMeasure.CVAR))
```

<a id="maximum-diversification"></a>

## Maximum Diversification

The [`MaximumDiversification`](https://skfolio.org/generated/skfolio.optimization.MaximumDiversification.html.md#skfolio.optimization.MaximumDiversification) maximizes the diversification ratio, which is the
ratio of the weighted volatilities over the total volatility.

**Example:**

```python
from sklearn.model_selection import train_test_split

from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MaximumDiversification
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = MaximumDiversification()
model.fit(X_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.diversification)
```

<a id="distributionally-robust-cvar"></a>

## Distributionally Robust CVaR

The [`DistributionallyRobustCVaR`](https://skfolio.org/generated/skfolio.optimization.DistributionallyRobustCVaR.html.md#skfolio.optimization.DistributionallyRobustCVaR) constructs a Wasserstein ball in the space of
multivariate and non-discrete probability distributions centered at the uniform
distribution on the training samples and finds the allocation that minimizes the CVaR
of the worst-case distribution within this Wasserstein ball.
Esfahani and Kuhn proved that for piecewise linear objective functions,
which is the case of CVaR, the distributionally robust optimization problem
over a Wasserstein ball can be reformulated as finite convex programs.

A solver like `Mosek` that can handle a high number of constraints is preferred.

**Example:**

```python
from sklearn.model_selection import train_test_split

from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import DistributionallyRobustCVaR
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X = X["2020":]
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = DistributionallyRobustCVaR(wasserstein_ball_radius=0.01)
model.fit(X_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.cvar)
```

<a id="hierarchical-risk-parity"></a>

## Hierarchical Risk Parity

The [`HierarchicalRiskParity`](https://skfolio.org/generated/skfolio.optimization.HierarchicalRiskParity.html.md#skfolio.optimization.HierarchicalRiskParity) (HRP) is a portfolio optimization method developed
by Marcos Lopez de Prado.

This algorithm uses a distance matrix to compute hierarchical clusters using the
Hierarchical Tree Clustering algorithm then employs seriation to rearrange the assets
in the dendrogram, minimizing the distance between leaves.
in the dendrogram, minimizing the distance between leaves.

The final step is the recursive bisection where each cluster is split between two
sub-clusters by starting with the topmost cluster and traversing in a top-down
manner. For each sub-cluster, we compute the total cluster risk of an inverse-risk
allocation. A weighting factor is then computed from these two sub-cluster risks,
which is used to update the cluster weight.

#### NOTE
The original paper uses the variance as the risk measure and the single-linkage
method for the Hierarchical Tree Clustering algorithm. Here we generalize it to
multiple risk measures and linkage methods.
The default linkage method is set to the Ward
variance minimization algorithm, which is more stable and has better properties
than the single-linkage method.

It supports all [prior estimators](https://skfolio.org/user_guide/prior.html.md#prior) and [risk measures](https://skfolio.org/api.html.md#measures-ref)
as well as weight constraints.

It also supports all [distance estimators](https://skfolio.org/user_guide/distance.html.md#distance) through the
`distance_estimator` parameter. It fits a distance model for the
estimation of the codependence and the distance matrix used to compute the linkage
matrix:

> * [`PearsonDistance`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance)
> * [`KendallDistance`](https://skfolio.org/generated/skfolio.distance.KendallDistance.html.md#skfolio.distance.KendallDistance)
> * [`SpearmanDistance`](https://skfolio.org/generated/skfolio.distance.SpearmanDistance.html.md#skfolio.distance.SpearmanDistance)
> * [`CovarianceDistance`](https://skfolio.org/generated/skfolio.distance.CovarianceDistance.html.md#skfolio.distance.CovarianceDistance)
> * [`DistanceCorrelation`](https://skfolio.org/generated/skfolio.distance.DistanceCorrelation.html.md#skfolio.distance.DistanceCorrelation)
> * [`MutualInformation`](https://skfolio.org/generated/skfolio.distance.MutualInformation.html.md#skfolio.distance.MutualInformation)

**Example:**

Hierarchical Risk Parity with semi (downside) standard-deviation as the risk measure and
mutual information as the distance estimator:

```python
from sklearn.model_selection import train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.distance import MutualInformation
from skfolio.optimization import HierarchicalRiskParity
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = HierarchicalRiskParity(
    risk_measure=RiskMeasure.SEMI_DEVIATION, distance_estimator=MutualInformation()
)
model.fit(X_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.annualized_sharpe_ratio)
print(portfolio.contribution(measure=RiskMeasure.SEMI_DEVIATION))
```

<a id="hierarchical-equal-risk-contribution"></a>

## Hierarchical Equal Risk Contribution

The [`HierarchicalEqualRiskContribution`](https://skfolio.org/generated/skfolio.optimization.HierarchicalEqualRiskContribution.html.md#skfolio.optimization.HierarchicalEqualRiskContribution) (HERC) is a portfolio optimization method
developed by Thomas Raffinot.

This algorithm uses a distance matrix to compute hierarchical clusters using the
Hierarchical Tree Clustering algorithm. It then computes, for each cluster, the total
cluster risk of an inverse-risk allocation.

The final step is the top-down recursive division of the dendrogram, where the assets
weights are updated using a naive risk parity within clusters.

It differs from the Hierarchical Risk Parity by exploiting the dendrogram shape
during the top-down recursive division instead of bisecting it.

#### NOTE
The default linkage method is set to the Ward
variance minimization algorithm, which is more stable and has better properties
than the single-linkage method.

It supports all [prior estimators](https://skfolio.org/user_guide/prior.html.md#prior) and [risk measures](https://skfolio.org/api.html.md#measures-ref)
as well as weight constraints.

It also supports all [distance estimators](https://skfolio.org/user_guide/distance.html.md#distance) through the
`distance_estimator` parameter. It fits a distance model for the
estimation of the codependence and the distance matrix used to compute the linkage
matrix:

> * [`PearsonDistance`](https://skfolio.org/generated/skfolio.distance.PearsonDistance.html.md#skfolio.distance.PearsonDistance)
> * [`KendallDistance`](https://skfolio.org/generated/skfolio.distance.KendallDistance.html.md#skfolio.distance.KendallDistance)
> * [`SpearmanDistance`](https://skfolio.org/generated/skfolio.distance.SpearmanDistance.html.md#skfolio.distance.SpearmanDistance)
> * [`CovarianceDistance`](https://skfolio.org/generated/skfolio.distance.CovarianceDistance.html.md#skfolio.distance.CovarianceDistance)
> * [`DistanceCorrelation`](https://skfolio.org/generated/skfolio.distance.DistanceCorrelation.html.md#skfolio.distance.DistanceCorrelation)
> * [`MutualInformation`](https://skfolio.org/generated/skfolio.distance.MutualInformation.html.md#skfolio.distance.MutualInformation)

**Example:**

Hierarchical Equal Risk Contribution with CVaR (Conditional Value at Risk) as the risk
measure and mutual information as the distance estimator:

```python
from sklearn.model_selection import train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.distance import MutualInformation
from skfolio.optimization import HierarchicalEqualRiskContribution
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = HierarchicalEqualRiskContribution(
    risk_measure=RiskMeasure.CVAR,
    distance_estimator = MutualInformation()
)
model.fit(X_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.annualized_sharpe_ratio)
print(portfolio.contribution(measure=RiskMeasure.CVAR))
```

<a id="nested-clusters-optimization"></a>

## Nested Clusters Optimization

The [`NestedClustersOptimization`](https://skfolio.org/generated/skfolio.optimization.NestedClustersOptimization.html.md#skfolio.optimization.NestedClustersOptimization) (NCO) is a portfolio optimization method
developed by Marcos Lopez de Prado.

It uses a distance matrix to compute clusters using a clustering algorithm (
Hierarchical Tree Clustering, KMeans, etc.). For each cluster, the inner-cluster
weights are computed by fitting the inner-estimator on each cluster using the whole
training data. Then the outer-cluster weights are computed by training the
outer-estimator using out-of-sample estimates of the inner-estimators with
cross-validation. Finally, the final assets weights are the dot-product of the
inner-weights and outer-weights.

#### NOTE
The original paper uses KMeans as the clustering algorithm, minimum Variance for
the inner-estimator and equal-weighted for the outer-estimator. Here we generalize
it to all `sklearn` and `skfolio` clustering algorithms (Hierarchical Tree
Clustering, KMeans, etc.), all portfolio optimizations (Mean-Variance, HRP, etc.)
and risk measures (variance, CVaR, etc.).
To avoid data leakage at the outer-estimator, we use out-of-sample estimates to
fit the outer estimator.

It supports all [distance estimators](https://skfolio.org/user_guide/distance.html.md#distance)
and [clustering estimator](https://skfolio.org/user_guide/cluster.html.md#cluster) (both `skfolio` and `sklearn`)

**Example:**

Nested Clusters Optimization with KMeans as the clustering algorithm, Kendall Distance
as the distance estimator, Minimum Semi-Variance as the inner estimator, and CVaR Risk
Parity as the outer (meta) estimator trained on the out-of-sample estimates from the
KFold cross-validation and run with parallelization:

```python
from sklearn.cluster import KMeans
from sklearn.model_selection import KFold, train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.distance import KendallDistance
from skfolio.optimization import MeanRisk, NestedClustersOptimization, RiskBudgeting
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = NestedClustersOptimization(
    inner_estimator=MeanRisk(risk_measure=RiskMeasure.SEMI_VARIANCE),
    outer_estimator=RiskBudgeting(risk_measure=RiskMeasure.CVAR),
    distance_estimator=KendallDistance(),
    clustering_estimator=KMeans(n_init="auto"),
    cv=KFold(),
    n_jobs=-1,
)
model.fit(X_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.annualized_sharpe_ratio)
print(portfolio.contribution(measure=RiskMeasure.CVAR))
```

The `cv` parameter can also be a combinatorial cross-validation, such as
`CombinatorialPurgedCV`, in which case each cluster’s
out-of-sample outputs are a collection of multiple paths instead of one single path.
The selected out-of-sample path among this collection of paths is chosen according to
the `quantile` and `quantile_measure` parameters.

<a id="stacking-optimization"></a>

## Stacking Optimization

[`StackingOptimization`](https://skfolio.org/generated/skfolio.optimization.StackingOptimization.html.md#skfolio.optimization.StackingOptimization) is an ensemble method that consists of stacking the outputs
of individual portfolio optimizations with a final portfolio optimization.

The final weights are the dot product of the individual optimizations’ weights and the final
optimization’s weights.

Stacking leverages the strengths of each individual portfolio optimization by
using their outputs as inputs to a final portfolio optimization.

To avoid data leakage, out-of-sample estimates are used to fit the outer
optimization.

**Example:**

Stacking Optimization with Minimum Semi-Variance and CVaR Risk Parity
stacked together using Minimum Variance as the final (meta) estimator.

```python
from sklearn.model_selection import KFold, train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk, RiskBudgeting, StackingOptimization
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

estimators = [
    ('model1', MeanRisk(risk_measure=RiskMeasure.SEMI_VARIANCE)),
    ('model2', RiskBudgeting(risk_measure=RiskMeasure.CVAR))
]

model = StackingOptimization(
    estimators=estimators,
    final_estimator=MeanRisk(),
    cv=KFold(),
    n_jobs=-1
)
model.fit(X_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.annualized_sharpe_ratio)
```

The `cv` parameter can also be a combinatorial cross-validation, such as
`CombinatorialPurgedCV`, in which case each out-of-sample outputs are a
collection of multiple paths instead of one single path. The selected out-of-sample path
among this collection of paths is chosen according to the `quantile` and
`quantile_measure` parameters.

<a id="tracking-error-optimization"></a>

<a id="id2"></a>

## Tracking Error Optimization

Tracking error measures the deviation between a portfolio’s performance and a benchmark.
`skfolio` provides three approaches for tracking error optimization:

1. **Return-based tracking error constraint** (via `max_tracking_error`):
   Constrains the tracking error while optimizing another objective (e.g., minimize CVaR).
2. **Weight-based target** (via `target_weights`):
   Minimizes tracking error by finding weights that minimize deviation from a target
   portfolio allocation.
3. **Return-based target** (via [`BenchmarkTracker`](https://skfolio.org/generated/skfolio.optimization.BenchmarkTracker.html.md#skfolio.optimization.BenchmarkTracker)):
   Minimizes tracking error by optimizing on excess returns (portfolio returns
   minus benchmark returns).

**Example 1: Return-based tracking error constraint**

Minimize CVaR while constraining the tracking error to 0.30% vs a benchmark:

```python
from sklearn.model_selection import train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset, load_sp500_index
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
spx_prices = load_sp500_index()

X, y = prices_to_returns(prices, spx_prices)
X_train, X_test, factors_train, factors_test = train_test_split(X, factors, test_size=0.33, shuffle=False)

model = MeanRisk(
    objective_function=ObjectiveFunction.MINIMIZE_RISK,
    risk_measure=RiskMeasure.CVAR,
    max_tracking_error=0.003,  # 0.30% tracking error constraint
)
model.fit(X_train, factors=factors_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.cvar)
```

**Example 2: Weight-based target**

Minimize tracking error vs an equal-weighted target portfolio:

```python
from sklearn.model_selection import train_test_split

import numpy as np
from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()

X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

# Define target portfolio (e.g., equal-weighted)
n_assets = X.shape[1]
target_weights = np.ones(n_assets) / n_assets

model = MeanRisk(
    objective_function=ObjectiveFunction.MINIMIZE_RISK,
    risk_measure=RiskMeasure.STANDARD_DEVIATION,
    target_weights=target_weights,
)
model.fit(X_train)
print(model.weights_)

portfolio = model.predict(X_test)
print(portfolio.annualized_sharpe_ratio)
```

**Example 3: Return-based target**

Minimize tracking error vs a benchmark’s returns:

```python
from sklearn.model_selection import train_test_split

from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset, load_sp500_index
from skfolio.optimization import BenchmarkTracker
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
benchmark_prices = load_sp500_index()

X, y = prices_to_returns(prices, benchmark_prices)
X_train, X_test, factors_train, factors_test = train_test_split(
    X, y["SP500"], test_size=0.33, shuffle=False
)

model = BenchmarkTracker(
    risk_measure=RiskMeasure.STANDARD_DEVIATION,
)
model.fit(X_train, factors=factors_train)
print(model.weights_)

portfolio = model.predict(X_test)
# Compare portfolio returns to benchmark
excess_returns = portfolio.returns - y_test.values
tracking_error = np.std(excess_returns, ddof=1)
print(f"Tracking Error: {tracking_error:0.2%}")
```

<a id="fallbacks"></a>

## Fallbacks

Optimization can sometimes fail during a given rebalancing. For example, a convex
mean-variance problem with strict risk or sector constraints may become infeasible on
specific dates.

All optimization estimators accept a `fallback` parameter that can be either a single
estimator or a list of estimators. When the primary optimization raises during `fit`,
the models in `fallback` are tried in order until one succeeds. The fitted weights and
core fitted attributes are copied back to the original estimator so you can keep a
single reference in your workflow. Fallbacks can also be set to the string
`previous_weights` to reuse the latest available allocation when the primary fit fails.

Each attempt is recorded in `fallback_chain_`, and the successful estimator is available
through `fallback_`.

This mechanism is critical in automated production, where optimization failures
shouldn’t interrupt pipelines and where you need reproducibility and auditability.
It can also be used to loosen optimization constraints gradually.

Example: The primary model is a minimum-variance optimization made intentionally
infeasible (the assets’ minimum weights are set to 10%, which exceeds the feasible
upper bound of 1/n_assets = 5%). As a fallback, we provide a feasible minimum-variance
model with a 2% minimum weight constraint:

```python
model = MeanRisk(
min_weights=0.1,  # intentionally infeasible
fallback=MeanRisk(min_weights=0.02),  # feasible fallback
)
model.fit(X_train)
print(model.weights_)

# Let's retrieve the fitted fallback that produced the final result:
print(model.fallback_)
# Let's display the sequence of attempts and their outcomes:
print(model.fallback_chain_)
# The fallback audit trail is also propagated to the predicted portfolio:
portfolio = model.predict(X_test)
assert portfolio.fallback_chain == model.fallback_chain_
```

When calling `predict`, the selected fallback and the full attempt log are propagated
to the resulting portfolio via `fallback_chain`.

For a step-by-step tutorial and more details, see
[Failure and Fallbacks](https://skfolio.org/auto_examples/mean_risk/plot_17_failure_and_fallbacks.html.md#sphx-glr-auto-examples-mean-risk-plot-17-failure-and-fallbacks-py).

<a id="failure-handling"></a>

## Failure Handling

In research, cross-validation and hyperparameter tuning (e.g., walk-forward, multiple
randomized cross-validation), it’s often useful to let all runs complete while keeping
a full record of failures instead of stopping on the first failed rebalancing.

The behavior on optimization failure is controlled by the `raise_on_failure`
parameter.

- If `raise_on_failure=True` (default): any error raised by the primary estimator is
  re-raised after fallbacks are exhausted. No `weights_` are set, and calling
  `predict` before a successful `fit` raises a `NotFittedError`.
- If `raise_on_failure=False`: errors are not raised. Instead, a warning is
  emitted, `weights_` is set to `None`, and `predict` returns a
  [`FailedPortfolio`](https://skfolio.org/generated/skfolio.portfolio.FailedPortfolio.html.md#skfolio.portfolio.FailedPortfolio) that carries diagnostics.

Diagnostics are exposed via:

- `error_`: the stringified error of the failed fit.
- `fallback_chain_`: a sequence of attempts with outcomes (`"success"` or the
  error message), starting from the primary estimator.

For online workflows based on `partial_fit`, the estimator first updates its stateful
components, such as the prior and moment estimators, then solves the next portfolio.
The `raise_on_failure` policy applies to solver failures at that rebalance. Errors raised
while updating stateful components are still raised because the estimator state may be
incomplete. The only fallback supported by `partial_fit` is
`fallback="previous_weights"`, which reuses the latest valid allocation. Estimator
fallbacks are reserved for regular `fit`, where each fallback can be fitted on the
complete training window.

Example: proceed without raising and retrieve failure diagnostics

```python
from skfolio import RiskMeasure
from skfolio.optimization import MeanRisk, ObjectiveFunction

# Configure an intentionally infeasible problem
model = MeanRisk(
    min_weights=1.0,
    raise_on_failure=False,  # do not raise; collect diagnostics instead
)

model.fit(X_train)  # does not raise; weights_ is None on failure
print(model.error_)          # stringified error message
print(model.fallback_chain_) # attempts and outcomes

ptf = model.predict(X_test)  # returns a FailedPortfolio sentinel
print(type(ptf).__name__)    # "FailedPortfolio"
print(ptf.optimization_error)
print(ptf.fallback_chain)
```

For a complete tutorial illustrating failure handling and fallbacks, see
[Failure and Fallbacks](https://skfolio.org/auto_examples/mean_risk/plot_17_failure_and_fallbacks.html.md#sphx-glr-auto-examples-mean-risk-plot-17-failure-and-fallbacks-py).

# user_guide/population.html.md

<a id="population"></a>

<a id="id1"></a>

# Population

A [`Population`](https://skfolio.org/generated/skfolio.population.Population.html.md#skfolio.population.Population) is a list of portfolios ([`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio)
or [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) or both).
`Population` inherits from the built-in `list` class and extends it by adding new
functionalities to improve portfolio manipulation and analysis.

**Example:**

In this example, we create a Population of 100 random Portfolios:

```python
from skfolio import (
    PerfMeasure,
    Population,
    Portfolio,
    RatioMeasure,
    RiskMeasure,
)
from skfolio.datasets import load_sp500_dataset
from skfolio.preprocessing import prices_to_returns
from skfolio.utils.stats import rand_weights

prices = load_sp500_dataset()
X = prices_to_returns(X=prices)

population = Population([])

n_assets = X.shape[1]
for i in range(100):
    weights = rand_weights(n=n_assets)
    portfolio = Portfolio(X=X, weights=weights, name=str(i))
    population.append(portfolio)
```

Let’s explore some of the methods:

```python
print(population.composition())

print(population.summary())

portfolio = population.quantile(measure=RiskMeasure.VARIANCE, q=0.95)

population.set_portfolio_params(compounded=True)

fronts = population.non_dominated_sort()

population.plot_measures(
    x=RiskMeasure.ANNUALIZED_VARIANCE,
    y=PerfMeasure.ANNUALIZED_MEAN,
    z=RiskMeasure.MAX_DRAWDOWN,
    show_fronts=True,
)

population[:2].plot_cumulative_returns()

population.plot_distribution(
    measure_list=[RatioMeasure.SHARPE_RATIO, RatioMeasure.SORTINO_RATIO]
)

population.plot_composition()
```

A `Population` is returned by the `predict` method of some portfolio optimization that
supports multi-outputs.

For example, fitting [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk) with parameter
`efficient_frontier_size=30` will find the weights of 30 portfolios belonging to the
efficient frontier. Calling the method `predict(X_test)` on that model will return a
`Population` containing these 30 `Portfolio`, predicted on the test set:

```python
from sklearn.model_selection import train_test_split

from skfolio import (
    RiskMeasure,
)
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(X=prices)
X_train, X_test = train_test_split(X, test_size=0.33, shuffle=False)

model = MeanRisk(
    risk_measure=RiskMeasure.VARIANCE,
    efficient_frontier_size=30,
)
model.fit(X_train)
print(model.weights_.shape)

population = model.predict(X_test)
```

# user_guide/portfolio.html.md

<a id="portfolio"></a>

<a id="id1"></a>

# Portfolio

`Portfolio` classes implement a large set of attributes and methods intended for
portfolio analysis. They are returned by the `predict` method of
[portfolio optimizations](https://skfolio.org/user_guide/optimization.html.md#optimization).

They are also data-containers (calling
`np.asarray(portfolio)` returns the portfolio returns) making them compatible
with `sklearn.model_selection` tools.

They use `slots` for improved performance.

<a id="base-portfolio"></a>

## Base Portfolio

[`BasePortfolio`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio) directly takes a portfolio returns array as input and implements
a large set of attributes and methods.

**Example:**

```python
import datetime as dt
from skfolio import BasePortfolio

portfolio = BasePortfolio(
    returns=[0.002, -0.001, 0.0015],
    observations=[dt.date(2022, 1, 1), dt.date(2022, 1, 2), dt.date(2022, 1, 3)],
)
```

<a id="attributes-and-methods"></a>

### Attributes and Methods

More than 40 attributes and methods are available, including all the
[measures](https://skfolio.org/api.html.md#measures-ref) (Mean, Variance, Sharpe Ratio, CVaR, CDaR, Drawdowns,
etc.). The attributes are computed only when requested, then cached in `slots` for
enhanced performance.

Measures are computed on the per-observation return series, in the periodicity of
the returns. The annualized variants (e.g. `annualized_sharpe_ratio`,
`annualized_mean`) scale them for reporting using the `annualization_factor`
parameter (default 252). Optimization inputs are never annualized, only reported
measures are (see [Periodicity Convention](https://skfolio.org/user_guide/data_preparation.html.md#periodicity-convention)).

**Example:**

```python
from skfolio import RatioMeasure

# attributes
portfolio.mean
portfolio.variance
portfolio.sharpe_ratio
portfolio.sortino_ratio
portfolio.cdar
portfolio.max_drawdown
portfolio.cumulative_returns
portfolio.drawdowns
portfolio.returns_df
portfolio.cumulative_returns_df

# methods
portfolio.summary()
portfolio.dominates(other_portfolio)
portfolio.rolling_measure(measure=RatioMeasure.SHARPE_RATIO)

# plots
portfolio.plot_cumulative_returns()
portfolio.plot_rolling_measure(measure=RatioMeasure.SHARPE_RATIO)
```

It is also an array container:

```python
np.asarray(portfolio)
>>> array([ 0.002 , -0.001 ,  0.0015])
```

Finally, portfolios can be compared together using domination:

```python
portfolio == other_portfolio
portfolio >= other_portfolio
portfolio > other_portfolio
```

The measures used in the domination are controlled using `fitness_measures`. The default
is to use the list `[PerfMeasure.MEAN, RiskMeasure.VARIANCE]`.

<a id="id2"></a>

## Portfolio

[`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) inherits from [`BasePortfolio`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio). Under the default
constant-weight convention, portfolio returns are the dot product of the asset weights
and asset returns minus costs:

$$
r_p = R \cdot w^{T} - c^{T} \cdot |w-w_{prev}| - f^{T} \cdot w
$$

with $r_p$ the vector of portfolio returns, $R$ the matrix of asset
returns, $w$ the vector of asset weights, $c$ the vector of asset
transaction costs, $f$ the vector of asset management fees and
$w_{prev}$ the previous asset weights.

By default, each observation is evaluated at the target weights, consistent with
the optimizer’s linear portfolio return definition. This convention evaluates
**allocation skill**, the expected return and risk of the selected target allocation,
independently of subsequent weight drift.

Because the same target weights are applied to every observation, reordering the
observations does not change the resulting distribution of portfolio returns.

Economically, evaluating every observation at the target weights is equivalent to
restoring those weights after each observation. The transaction costs of these
implicit within-window trades are not charged. The transaction-cost term in the
formula above instead applies to the trade from `previous_weights` to the target
weights when the `Portfolio` is created.

With `weight_drift=True`, the portfolio starts at the target weights and holds the
resulting positions throughout the observation window of `X`. Position values change
with asset returns, so portfolio weights evolve with the relative performance of the
assets.

In a long-only portfolio, an asset’s weight increases when its return exceeds the
portfolio return and decreases when its return falls below it. More generally, the
weights applied to later observations depend on earlier asset returns, so the
resulting portfolio return series depends on the order of the observations.

With `weight_drift=True` and `compounded=True`, returns computed from drifted weights
are compounded into a wealth index for evaluating **realized capital growth** and
other path-dependent measures.

Both weight conventions use the same transaction-cost and management-fee formulas.
In a sequential evaluation, transaction costs are computed relative to the previous
target weights with `weight_drift=False`, or the previous period’s ending weights,
including drift, with `weight_drift=True`. Management fees use the target weights
under both settings.

`weight_drift` therefore changes the observation-level portfolio return series,
while `compounded` changes how that series is accumulated. See
[Backtesting and Evaluation](https://skfolio.org/user_guide/backtesting_and_evaluation.html.md#backtesting-and-evaluation) for a detailed discussion of the evaluation
objectives and the choice between `weight_drift=False` and `weight_drift=True`.

**Example:**

```python
from skfolio import Portfolio

X = [
    [0.003, -0.001],
    [-0.001, 0.002],
    [0.0015, 0.004],
]

weights = [0.6, 0.4]

portfolio = Portfolio(X=X, weights=weights)

print(portfolio.returns)
>>> array([0.0014, 0.0002, 0.0025])

drifted_portfolio = Portfolio(X=X, weights=weights, weight_drift=True)
drifted_portfolio.weights_per_observation
drifted_portfolio.ending_weights
```

`X` can be any data-container including numpy array and pandas DataFrame:

```python
import datetime as dt
import pandas as pd

X = pd.DataFrame(
    data=[[0.003, -0.001], [-0.001, 0.002], [0.0015, 0.004]],
    columns=["Asset A", "Asset B"],
    index=[dt.date(2022, 1, 1), dt.date(2022, 1, 2), dt.date(2022, 1, 3)],
)

print(X)
>>>
            Asset A  Asset B
2022-01-01   0.0030   -0.001
2022-01-02  -0.0010    0.002
2022-01-03   0.0015    0.004

weights = [0.6, 0.4]

portfolio = Portfolio(X=X, weights=weights, name="my_portfolio")

print(portfolio.returns)
>>> array([0.0014, 0.0002, 0.0025])
```

<a id="id3"></a>

### Attributes and Methods

[`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) inherits all the attributes and methods from [`BasePortfolio`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio).
It also provides methods for analyzing portfolio weights:

```python
from skfolio import RatioMeasure

portfolio.contribution(measure=RatioMeasure.ANNUALIZED_SHARPE_RATIO)
>>> array([-3.04203502,  3.04203503])

portfolio.composition
>>>
              my_portfolio
asset
Asset A           0.6
Asset B           0.4

portfolio.get_weight("Asset A")
>>> 0.6

# Weight paths and trading diagnostics
portfolio.weights_per_observation
portfolio.ending_weights
portfolio.turnover

# Plots
portfolio.plot_contribution()
portfolio.plot_composition()
```

<a id="multi-period-portfolio"></a>

## Multi Period Portfolio

[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) inherits from [`BasePortfolio`](https://skfolio.org/generated/skfolio.portfolio.BasePortfolio.html.md#skfolio.portfolio.BasePortfolio) and is composed of a
list of [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio). Its return series concatenates the return series of those
portfolios in list order. Its performance and risk measures are computed from that
concatenated series.

A `MultiPeriodPortfolio` is returned by
[`cross_val_predict`](https://skfolio.org/generated/skfolio.model_selection.cross_val_predict.html.md#skfolio.model_selection.cross_val_predict).
Its `turnover` series holds the turnover of each `Portfolio`, and
`ending_weights_dict` maps each `Portfolio` to its weights at the end of its observation
window. With `weight_drift=False`, these are the target weights. With
`weight_drift=True`, they are the held weights after applying the final observation’s
asset returns.

For example, calling `cross_val_predict` with
[`WalkForward`](https://skfolio.org/generated/skfolio.model_selection.WalkForward.html.md#skfolio.model_selection.WalkForward) will return a `MultiPeriodPortfolio`
composed of multiple test `Portfolio`, each corresponding to a train/test fold.

```python
from skfolio import MultiPeriodPortfolio

portfolio = MultiPeriodPortfolio(portfolios=[ptf1, ptf2, ptf3])
```

# user_guide/pre_selection.html.md

<a id="pre-selection"></a>

<a id="pre-selection-transformers"></a>

# Pre-Selection Transformers

A [Pre-Selection transformer](https://skfolio.org/api.html.md#pre-selection-ref) performs a pre-selection on the
initial assets universe.

It follows the same API as scikit-learn’s `estimator`: the `fit_transform` method takes
`X` as the assets returns and returns a new `X` with only the pre-selected assets.

`X` can be any array-like structure (numpy array, pandas DataFrame, etc.)

Pre-selection is one way to handle missing returns before fitting estimators that
require finite inputs. See [Missing Data and Changing Universes](https://skfolio.org/user_guide/data_representation.html.md#missing-data)
for the trade-off between pre-selection, imputation and native NaN-aware estimators.

Available transformers are:
: * [`DropZeroVariance`](https://skfolio.org/generated/skfolio.pre_selection.DropZeroVariance.html.md#skfolio.pre_selection.DropZeroVariance)
  * [`DropCorrelated`](https://skfolio.org/generated/skfolio.pre_selection.DropCorrelated.html.md#skfolio.pre_selection.DropCorrelated)
  * [`SelectComplete`](https://skfolio.org/generated/skfolio.pre_selection.SelectComplete.html.md#skfolio.pre_selection.SelectComplete)
  * [`SelectKExtremes`](https://skfolio.org/generated/skfolio.pre_selection.SelectKExtremes.html.md#skfolio.pre_selection.SelectKExtremes)
  * [`SelectNonDominated`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonDominated.html.md#skfolio.pre_selection.SelectNonDominated)
  * [`SelectNonExpiring`](https://skfolio.org/generated/skfolio.pre_selection.SelectNonExpiring.html.md#skfolio.pre_selection.SelectNonExpiring)

**Example:**

```python
from sklearn import set_config

from skfolio.datasets import load_sp500_dataset
from skfolio.pre_selection import DropCorrelated
from skfolio.preprocessing import prices_to_returns

set_config(transform_output="pandas")

prices = load_sp500_dataset()
X = prices_to_returns(prices)
print(X.shape)

model = DropCorrelated(threshold=0.5)
new_X = model.fit_transform(X)
print(new_X.shape)
```

Pre-Selection transformers are fully compatible with `sklearn.pipeline.Pipeline`:

**Example:**

```python
from sklearn import set_config
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline

from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk
from skfolio.pre_selection import DropCorrelated
from skfolio.preprocessing import prices_to_returns

set_config(transform_output='pandas')

prices = load_sp500_dataset()
X = prices_to_returns(prices)
X_train, X_test = train_test_split(X, shuffle=False, test_size=0.3)

pipe = Pipeline([('pre_selection', DropCorrelated(threshold=0.9)),
                 ('mean_risk', MeanRisk())])
pipe.fit(X_train)

portfolio = pipe.predict(X_test)
print(portfolio.annualized_sharpe_ratio)
```

# user_guide/prior.html.md

<a id="prior"></a>

<a id="prior-estimator"></a>

# Prior Estimator

A Prior Estimator in `skfolio` fits a [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) containing your
pre-optimization inputs ($\mu$, $\Sigma$, returns, sample weight, Cholesky decomposition).

The term “prior” is used in a general optimization sense, not confined to Bayesian
priors. It denotes any **a priori** assumption or estimation method for the return
distribution before optimization, unifying **Frequentist**, **Bayesian** and
**Information-theoretic** approaches into a single cohesive framework:

1. Frequentist:
   : * [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior)
     * [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel)
     * [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData)
2. Bayesian:
   : * [`BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman)
3. Information-theoretic:
   : * [`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling)
     * [`OpinionPooling`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling)

In skfolio’s API, all such methods share the same interface and adhere to scikit-learn’s
estimator API: the `fit` method accepts `X` (the asset returns) and stores the
resulting [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) in its `return_distribution_` attribute.

`X` can be any array-like structure (NumPy array, pandas DataFrame, etc.).

The [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) is a dataclass containing:

> * `mu`: Estimated expected returns of shape (n_assets,)
> * `covariance`: Estimated covariance matrix of shape (n_assets, n_assets)
> * `returns`: (Estimated) asset returns of shape (n_observations, n_assets)
> * `sample_weight` : Sample weight for each observation of shape (n_observations,) (optional)
> * `cholesky` : Lower-triangular Cholesky factor of the covariance (optional)

When native NaN-aware moment estimators are used, a prior can keep the full asset
universe in `return_distribution_` while non-investable assets are represented by NaNs
in $\mu$, $\Sigma$, or both. See
[Missing Data and Changing Universes](https://skfolio.org/user_guide/data_representation.html.md#missing-data) for the full missing-data
and investability convention.

#### NOTE
The posterior of one model can serve as the prior for another. In skfolio,
Prior Estimators can be composed into complex pre-optimization pipelines.
For example, [`BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman) accepts a fitted Prior Estimator that computes
initial expected returns and covariance, applies the analyst’s views to update them,
and then stores the resulting posterior expected returns and covariance in a new
[`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution), which can be passed into another estimator.

<a id="empirical-prior"></a>

## Empirical Prior

The [`EmpiricalPrior`](https://skfolio.org/generated/skfolio.prior.EmpiricalPrior.html.md#skfolio.prior.EmpiricalPrior) estimator estimates the [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) by
fitting its `mu_estimator` and `covariance_estimator` independently.

**Example:**

An `EmpiricalPrior` configured with James–Stein shrinkage to estimate expected returns
and a denoising method to estimate the covariance matrix:

```python
from skfolio.datasets import load_sp500_dataset
from skfolio.moments import DenoiseCovariance, ShrunkMu
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EmpiricalPrior

prices = load_sp500_dataset()
X = prices_to_returns(prices)

model = EmpiricalPrior(
    mu_estimator=ShrunkMu(), covariance_estimator=DenoiseCovariance()
)
model.fit(X)
print(model.return_distribution_)
```

<a id="black-litterman"></a>

## Black & Litterman

The [`BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman) estimator estimates the [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) using
the Black & Litterman model. It takes a Bayesian approach by starting from a prior
estimate of the assets’ expected returns and covariance matrix, then updating them with
the analyst’s views to obtain the posterior estimates.

Tutorials:
: * [Black & Litterman](https://skfolio.org/auto_examples/mean_risk/plot_12_black_and_litterman.html.md#sphx-glr-auto-examples-mean-risk-plot-12-black-and-litterman-py)
  * [Black & Litterman Factor Model](https://skfolio.org/auto_examples/mean_risk/plot_14_black_litterman_factor_model.html.md#sphx-glr-auto-examples-mean-risk-plot-14-black-litterman-factor-model-py)

**Example:**

```python
from skfolio.preprocessing import prices_to_returns
from skfolio.datasets import load_sp500_dataset
from skfolio.prior import BlackLitterman

prices = load_sp500_dataset()
X = prices_to_returns(prices)

analyst_views = [
    "AAPL - BBY == 0.0003",
    "CVX - KO == 0.0004",
    "MSFT == 0.0006",
]

model = BlackLitterman(views=analyst_views)
model.fit(X)
print(model.return_distribution_)
```

<a id="factor-model"></a>

## Factor Model

The [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel) estimator estimates the [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) by fitting
a factor model on asset returns alongside a specified [prior estimator](https://skfolio.org/user_guide/prior.html.md#prior)
for the factor returns.

The purpose of factor models is to impose a structure on financial variables and
their covariance matrix by explaining them through a small number of common factors.
This can help overcome estimation error by reducing the number of parameters,
i.e., the dimensionality of the estimation problem, making portfolio optimization
more robust against noise in the data. Factor models also provide a decomposition of
financial risk into systematic and security-specific components.

The `fit` method takes `X` as the asset
returns and `factors` as the factor returns. Pass factor returns with the `factors` keyword
argument.

Tutorials:
: * [Time-Series Factor Model](https://skfolio.org/auto_examples/mean_risk/plot_13_factor_model.html.md#sphx-glr-auto-examples-mean-risk-plot-13-factor-model-py)
  * [Black & Litterman Factor Model](https://skfolio.org/auto_examples/mean_risk/plot_14_black_litterman_factor_model.html.md#sphx-glr-auto-examples-mean-risk-plot-14-black-litterman-factor-model-py)
  * [Hierarchical Risk Parity - CVaR](https://skfolio.org/auto_examples/clustering/plot_1_hrp_cvar.html.md#sphx-glr-auto-examples-clustering-plot-1-hrp-cvar-py)
  * [Minimize CVaR on Stressed Factors - CVaR](https://skfolio.org/auto_examples/synthetic_data/plot_3_min_CVaR_stressed_factors.html.md#sphx-glr-auto-examples-synthetic-data-plot-3-min-cvar-stressed-factors-py)

**Example:**

```python
from skfolio.datasets import load_factors_dataset, load_sp500_dataset
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import TimeSeriesFactorModel

prices = load_sp500_dataset()
factor_prices = load_factors_dataset()
X, factors = prices_to_returns(prices, factor_prices)

model = TimeSeriesFactorModel()
model.fit(X, factors=factors)
print(model.return_distribution_)
```

The loading matrix (betas) of the factors is estimated using a
`loading_matrix_estimator`. By default, we use the [`LoadingMatrixRegression`](https://skfolio.org/generated/skfolio.prior.LoadingMatrixRegression.html.md#skfolio.prior.LoadingMatrixRegression)
which fits the factors using a `sklearn.linear_model.LassoCV` on each asset
separately.

<a id="synthetic-data"></a>

## Synthetic Data

The [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData) estimator bridges scenario generation and portfolio
optimization. It estimates the [`ReturnDistribution`](https://skfolio.org/generated/skfolio.prior.ReturnDistribution.html.md#skfolio.prior.ReturnDistribution) by fitting a
`distribution_estimator` and sampling new data from it.

The default `distribution_estimator` is a Regular
[`VineCopula`](https://skfolio.org/generated/skfolio.distribution.VineCopula.html.md#skfolio.distribution.VineCopula) estimator. Other common choices are Generative
Adversarial Networks (GANs) or Variational Autoencoders (VAEs).

It is particularly useful when the historical distribution tail dependencies are
sparse and need extrapolation for tail optimizations or when optimizing under
conditional or stressed scenarios.

Tutorials:
: * [Vine Copula](https://skfolio.org/auto_examples/synthetic_data/plot_2_vine_copula.html.md#sphx-glr-auto-examples-synthetic-data-plot-2-vine-copula-py)
  * [Minimize CVaR on Stressed Factors](https://skfolio.org/auto_examples/synthetic_data/plot_3_min_CVaR_stressed_factors.html.md#sphx-glr-auto-examples-synthetic-data-plot-3-min-cvar-stressed-factors-py)
  * [Entropy Pooling](https://skfolio.org/auto_examples/entropy_pooling/plot_1_entropy_pooling.html.md#sphx-glr-auto-examples-entropy-pooling-plot-1-entropy-pooling-py)
  * [Opinion Pooling](https://skfolio.org/auto_examples/entropy_pooling/plot_2_opinion_pooling.html.md#sphx-glr-auto-examples-entropy-pooling-plot-2-opinion-pooling-py)

**Example:**

```python
from skfolio.datasets import load_sp500_dataset, load_factors_dataset
from skfolio.preprocessing import prices_to_returns
from skfolio.distribution import VineCopula
from skfolio.optimization import MeanRisk
from skfolio.prior import TimeSeriesFactorModel, SyntheticData
from skfolio import RiskMeasure

# Load historical prices and convert them to returns
prices = load_sp500_dataset()
X = prices_to_returns(prices, factors)

# Instantiate the SyntheticData model and fit it
model = SyntheticData()
model.fit(X)
print(model.return_distribution_)

# Minimum CVaR optimization on synthetic returns
vine = VineCopula(log_transform=True, n_jobs=-1)
prior = =SyntheticData(distribution_estimator=vine, n_samples=2000)
model = MeanRisk(risk_measure=RiskMeasure.CVAR, prior_estimator=prior)
model.fit(X)
print(model.weights_)

# Stress Test
vine = VineCopula(log_transform=True, central_assets=["BAC"]  n_jobs=-1)
vine.fit(X)
X_stressed = vine.sample(n_samples=10000, conditioning = {"BAC": -0.2})
ptf_stressed = model.predict(X_stressed)
```

<a id="entropy-pooling"></a>

## Entropy Pooling

[`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling), introduced by Attilio Meucci in 2008 as a generalization of the
Black-Litterman framework, is a nonparametric method for adjusting a baseline (“prior”)
probability distribution to incorporate user-defined views by finding the posterior
distribution closest to the prior while satisfying those views.

User-defined views can be **elicited** from domain experts or **derived** from
quantitative analyses.

Grounded in information theory, it updates the distribution in the least-informative
way by minimizing the Kullback-Leibler divergence (relative entropy) under the
specified view constraints.

Tutorials:
: * [Entropy Pooling](https://skfolio.org/auto_examples/entropy_pooling/plot_1_entropy_pooling.html.md#sphx-glr-auto-examples-entropy-pooling-plot-1-entropy-pooling-py)
  * [Opinion Pooling](https://skfolio.org/auto_examples/entropy_pooling/plot_2_opinion_pooling.html.md#sphx-glr-auto-examples-entropy-pooling-plot-2-opinion-pooling-py)

**Example:**

```python
from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EntropyPooling
from skfolio.optimization import HierarchicalRiskParity

prices = load_sp500_dataset()
prices = prices[["AMD", "BAC", "GE", "JNJ", "JPM", "LLY", "PG"]]
X = prices_to_returns(prices)

groups = {
    "AMD": ["Technology", "Growth"],
    "BAC": ["Financials", "Value"],
    "GE": ["Industrials", "Value"],
    "JNJ": ["Healthcare", "Defensive"],
    "JPM": ["Financials", "Income"],
    "LLY": ["Healthcare", "Defensive"],
    "PG": ["Consumer", "Defensive"],
}

entropy_pooling = EntropyPooling(
    mean_views=[
        "JPM == -0.002",
        "PG >= LLY",
        "BAC >= prior(BAC) * 1.2",
        "Financials == 2 * Growth",
    ],
    variance_views=[
        "BAC == prior(BAC) * 4",
    ],
    correlation_views=[
        "(BAC,JPM) == 0.80",
        "(BAC,JNJ) <= prior(BAC,JNJ) * 0.5",
    ],
    skew_views=[
        "BAC == -0.05",
    ],
    cvar_views=[
        "GE == 0.08",
    ],
    cvar_beta=0.90,
    groups=groups,
)

entropy_pooling.fit(X)

print(entropy_pooling.relative_entropy_)
print(entropy_pooling.effective_number_of_scenarios_)
print(entropy_pooling.return_distribution_.sample_weight)

# CVaR Hierarchical Risk Parity optimization on Entropy Pooling
model = HierarchicalRiskParity(
    risk_measure=RiskMeasure.CVAR,
    prior_estimator=entropy_pooling
)
model.fit(X)
print(model.weights_)

# Stress Test the Portfolio
entropy_pooling = EntropyPooling(cvar_views=["AMD == 0.10"])
entropy_pooling.fit(X)

stressed_dist = entropy_pooling.return_distribution_

stressed_ptf = model.predict(stressed_dist)
```

<a id="opinion-pooling"></a>

## Opinion Pooling

[`OpinionPooling`](https://skfolio.org/generated/skfolio.prior.OpinionPooling.html.md#skfolio.prior.OpinionPooling) (also called Belief Aggregation or Risk Aggregation) is a
process in which different probability distributions (opinions), produced by different
experts, are combined to yield a single probability distribution (consensus).

Expert opinions (also called individual prior distributions) can be
**elicited** from domain experts or **derived** from quantitative analyses.

The `OpinionPooling` estimator takes a list of prior estimators, each of which
produces scenario probabilities (`sample_weight`), and pools them into a single
consensus probability .

You can choose between linear (arithmetic) pooling or logarithmic (geometric)
pooling, and optionally apply robust pooling using a Kullback-Leibler divergence
penalty to down-weight experts whose views deviate strongly from the group
consensus.

Tutorials:
: * [Opinion Pooling](https://skfolio.org/auto_examples/entropy_pooling/plot_2_opinion_pooling.html.md#sphx-glr-auto-examples-entropy-pooling-plot-2-opinion-pooling-py)

**Example:**

```python
from skfolio import RiskMeasure
from skfolio.datasets import load_sp500_dataset
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import EntropyPooling, OpinionPooling
from skfolio.optimization import RiskBudgeting

prices = load_sp500_dataset()
X = prices_to_returns(prices)

# We consider two expert opinions, each generated via Entropy Pooling with
# user-defined views.
# We assign probabilities of 40% to Expert 1, 50% to Expert 2, and by default
# the remaining 10% is allocated to the prior distribution:
opinion_1 = EntropyPooling(cvar_views=["AMD == 0.10"])
opinion_2 = EntropyPooling(
    mean_views=["AMD >= BAC", "JPM <= prior(JPM) * 0.8"],
    cvar_views=["GE == 0.12"],
)

opinion_pooling = OpinionPooling(
    estimators=[("opinion_1", opinion_1), ("opinion_2", opinion_2)],
    opinion_probabilities=[0.4, 0.5],
)

opinion_pooling.fit(X)

print(opinion_pooling.return_distribution_.sample_weight)

# CVaR Risk Parity optimization on opinion Pooling
model = RiskBudgeting(
    risk_measure=RiskMeasure.CVAR,
    prior_estimator=opinion_pooling
)
model.fit(X)
print(model.weights_)

# Stress Test the Portfolio
opinion_1 = EntropyPooling(cvar_views=["AMD == 0.05"])
opinion_2 = EntropyPooling(cvar_views=["AMD == 0.10"])
opinion_pooling = OpinionPooling(
    estimators=[("opinion_1", opinion_1), ("opinion_2", opinion_2)],
    opinion_probabilities=[0.6, 0.4],
)
opinion_pooling.fit(X)

stressed_dist = opinion_pooling.return_distribution_

stressed_ptf = model.predict(stressed_dist)
```

<a id="combining-multiple-prior-estimators"></a>

## Combining Multiple Prior Estimators

Prior estimators can be composed to build more sophisticated models. For example,
you can create a Black & Litterman Factor Model by supplying [`BlackLitterman`](https://skfolio.org/generated/skfolio.prior.BlackLitterman.html.md#skfolio.prior.BlackLitterman)
as the prior estimator of the [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel) and impose views on the factors.

**Example:**

Below is a factor model that estimates the **assets’** expected returns and covariance
matrix, where the **factors’** expected returns and covariance are themselves
estimated via a Black & Litterman model that incorporates the analyst’s views on those
**factors**.

```python
from skfolio.datasets import load_factors_dataset, load_sp500_dataset
from skfolio.preprocessing import prices_to_returns
from skfolio.prior import BlackLitterman, TimeSeriesFactorModel

prices = load_sp500_dataset()
factor_prices = load_factors_dataset()
X, factors = prices_to_returns(prices, factor_prices)

views = [
    "MTUM - QUAL == 0.0003",
    "SIZE - USMV == 0.0004",
    "VLUE == 0.0006",
]

model = TimeSeriesFactorModel(
    factor_prior_estimator=BlackLitterman(views=views),
)
model.fit(X, factors=factors)
print(model.return_distribution_)
```

**Example:**

By combining [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData) with [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel) you can generate
synthetic data of your factors then project them to your assets.
This is often used for factor stress testing.

```python
from skfolio.datasets import load_sp500_dataset, load_factors_dataset
from skfolio.preprocessing import prices_to_returns
from skfolio.distribution import VineCopula
from skfolio.optimization import MeanRisk
from skfolio.prior import TimeSeriesFactorModel, SyntheticData
from skfolio import RiskMeasure

# Load historical prices and convert them to returns
prices = load_sp500_dataset()
factors = load_factors_dataset()
X, factors = prices_to_returns(prices, factors)

# Minimum CVaR optimization on Stressed Factors
vine = VineCopula(central_assets=["QUAL"], log_transform=True, n_jobs=-1)
factor_prior = SyntheticData(
    distribution_estimator=vine,
    n_samples=10000,
    sample_args=dict(conditioning={"QUAL": -0.2}),
)
factor_model = TimeSeriesFactorModel(factor_prior_estimator=factor_prior)
model = MeanRisk(risk_measure=RiskMeasure.CVAR, prior_estimator=factor_model)
model.fit(X, factors=factors)
print(model.weights_)

# Stress Test the Portfolio
factor_model.set_params(factor_prior_estimator__sample_args=dict(
    conditioning={"QUAL": -0.5}
))
factor_model.fit(X, factors=factors)
stressed_dist = factor_model.return_distribution_
stressed_ptf = model.predict(stressed_dist)
```

**Example:**

To impose extreme views using Entropy Pooling on a sparse historical distribution,
we must generate synthetic data capable of extrapolating tail dependencies.
This can be achieved by combining [`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling) with [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData):

```python
from skfolio.datasets import load_sp500_dataset
from skfolio.preprocessing import prices_to_returns
from skfolio.distribution import VineCopula
from skfolio.prior import EntropyPooling, SyntheticData

# Load historical prices and convert them to returns
prices = load_sp500_dataset()
X = prices_to_returns(prices)

# Regular Vine Copula and sampling of 100,000 synthetic returns
synth = SyntheticData(
    n_samples=100_000,
    distribution_estimator=VineCopula(log_transform=True, n_jobs=-1, random_state=0)
)

# Entropy Pooling by imposing a CVaR-95% of 10% on Apple
entropy_pooling = EntropyPooling(
    prior_estimator=factor_synth,
    cvar_views=["AAPL == 0.10"],
)

entropy_pooling.fit(X)
```

**Example:**

Instead of applying extreme Entropy Pooling views directly to asset returns, we can
embed it within a time-series factor model.
This allows us to impose views on factor data such as the quality factor “QUAL”.
This can be achieved by combining [`EntropyPooling`](https://skfolio.org/generated/skfolio.prior.EntropyPooling.html.md#skfolio.prior.EntropyPooling) with [`SyntheticData`](https://skfolio.org/generated/skfolio.prior.SyntheticData.html.md#skfolio.prior.SyntheticData)
and with [`TimeSeriesFactorModel`](https://skfolio.org/generated/skfolio.prior.TimeSeriesFactorModel.html.md#skfolio.prior.TimeSeriesFactorModel):

```python
from skfolio.datasets import load_sp500_dataset, load_factors_dataset
from skfolio.preprocessing import prices_to_returns
from skfolio.distribution import VineCopula
from skfolio.optimization import MeanRisk
from skfolio.prior import EntropyPooling, SyntheticData, TimeSeriesFactorModel
from skfolio import RiskMeasure

# Load historical prices and convert them to returns
prices = load_sp500_dataset()
factor_prices = load_factors_dataset()
X, factors = prices_to_returns(prices, factor_prices)

# Regular Vine Copula and sampling of 100,000 synthetic factor returns
factor_synth = SyntheticData(
    n_samples=100_000,
    distribution_estimator=VineCopula(log_transform=True, n_jobs=-1, random_state=0)
)

# Entropy Pooling by imposing a CVaR-95% of 10% on the Quality factor
factor_entropy_pooling = EntropyPooling(
    prior_estimator=factor_synth,
    cvar_views=["QUAL == 0.10"],
)

factor_model = TimeSeriesFactorModel(factor_prior_estimator=factor_entropy_pooling)
factor_model.fit(X, factors=factors)
```

# user_guide/uncertainty_set.html.md

<a id="uncertainty-set-estimator"></a>

<a id="id1"></a>

# Uncertainty Set Estimator

An [uncertainty set estimator](https://skfolio.org/api.html.md#uncertainty-set-ref) builds the region in which a
distribution moment is assumed to lie under estimation error. When one is provided to
[`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk), the objective is evaluated at the least
favorable moment within that region instead of at the point estimate. This is called
worst-case optimization and is a class of robust optimization. It reduces the
instability that arises from the estimation errors of the expected returns and the
covariance matrix.

It follows the same API as scikit-learn’s `estimator`: the `fit` method takes `X` as
the assets returns and stores the fitted set in its `uncertainty_set_` attribute.

`X` can be any array-like structure (numpy array, pandas DataFrame, etc.)

<a id="norm-ball-representation"></a>

## Norm-ball representation

[`UncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.UncertaintySet.html.md#skfolio.uncertainty_set.UncertaintySet) represents deviations of a parameter vector $z$ from its
estimate $\hat{z}$ as $z - \hat{z} = L u$ with
$\lVert u \rVert_p \leq \kappa$:

> $$
> \mathcal{U}=\left\{\hat{z} + L u\,:\,\lVert u \rVert_p \leq \kappa\right\}

> $$

The parameter $z$ is $\mu$ for expected return uncertainty, and
$\text{vec}(\Sigma)$, the vector obtained by stacking the columns of
$\Sigma$, for covariance uncertainty. The set is defined by three fields:

* `radius`, the size $\kappa$ of the normalized ball.
* `norm`, the norm $p$ that selects its shape: $2$ for an ellipsoid,
  $\infty$ for a box and $1$ for a diamond.
* `geometry`, the linear map $L$ that scales and mixes the uncertainty
  directions.

For $p = 2$ and shape matrix $S = L L^{T}$, the set is ellipsoidal:

> $$
> U_{\mu}=\left\{\mu\,|\left(\mu-\hat{\mu}\right)S^{-1}\left(\mu-\hat{\mu}\right)^{T}\leq\kappa^{2}\right\}

> $$

Optimizers use the worst-case deviation over $\mathcal{U}$, which for a linear
exposure vector $e$ is $\kappa \lVert L^{T} e \rVert_q$, with $q$ the
dual norm of $p$. The map $L$ may be low-rank, which keeps this penalty
tractable for covariance uncertainty.

<a id="available-estimators"></a>

## Available estimators

For the expected returns:
: * [`EmpiricalMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalMuUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalMuUncertaintySet)
  * [`BootstrapMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapMuUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapMuUncertaintySet)
  * [`OrthogonalMuUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalMuUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalMuUncertaintySet)

For the covariance:
: * [`EmpiricalCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.EmpiricalCovarianceUncertaintySet)
  * [`BootstrapCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.BootstrapCovarianceUncertaintySet)
  * [`OrthogonalCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet)

The size of the set is controlled by `confidence_level`. The empirical and bootstrap
estimators derive the radius from the quantile of a chi-squared distribution at that
level, so a higher confidence level widens the set and increases the penalty.
[`OrthogonalCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.OrthogonalCovarianceUncertaintySet) is parameterized by `radius` instead.

The `Orthogonal` estimators require the optimizer’s `prior_estimator` to be a factor
model, such as [`CharacteristicsFactorModel`](https://skfolio.org/generated/skfolio.prior.CharacteristicsFactorModel.html.md#skfolio.prior.CharacteristicsFactorModel). The optimizer passes
the fitted return distribution to them. They confine the uncertainty to the subspace
orthogonal to the factor-model loading matrix, which penalizes allocations in directions
that the factor model prices only through idiosyncratic variance. See
[Orthogonal Space Regularization](https://skfolio.org/user_guide/factor_models.html.md#factor-model-orthogonal-space-regularization).

Covariance estimators may store a [`CompactCovarianceUncertaintySet`](https://skfolio.org/generated/skfolio.uncertainty_set.CompactCovarianceUncertaintySet.html.md#skfolio.uncertainty_set.CompactCovarianceUncertaintySet) instead of a
norm ball. It expresses the penalty as a reduced quadratic form that the optimizer adds
directly to the variance term, avoiding the lifted semidefinite formulation required by
a generic set.

**Example:**

```python
from skfolio.datasets import load_sp500_dataset
from skfolio.preprocessing import prices_to_returns
from skfolio.uncertainty_set import EmpiricalMuUncertaintySet

prices = load_sp500_dataset()
X = prices_to_returns(prices)

model = EmpiricalMuUncertaintySet()
model.fit(X)
print(model.uncertainty_set_)
```

<a id="worst-case-optimization"></a>

## Worst-case optimization

Uncertainty set estimators are provided to [`MeanRisk`](https://skfolio.org/generated/skfolio.optimization.MeanRisk.html.md#skfolio.optimization.MeanRisk)
through `mu_uncertainty_set_estimator` and `covariance_uncertainty_set_estimator`. The
optimizer fits them and subtracts the resulting penalty from the portfolio expected
return:

> $$
> w^{T}\hat{\mu} - \kappa\lVert L^{T}w\rVert_{q}

> $$

Covariance uncertainty is applied when `risk_measure=RiskMeasure.VARIANCE` or when
`max_variance` is set.

**Example:**

```python
from skfolio.datasets import load_sp500_dataset
from skfolio.optimization import MeanRisk, ObjectiveFunction
from skfolio.preprocessing import prices_to_returns
from skfolio.uncertainty_set import (
    BootstrapMuUncertaintySet,
    EmpiricalCovarianceUncertaintySet,
)

prices = load_sp500_dataset()
prices = prices["2020":]
X = prices_to_returns(prices)

model = MeanRisk(
    objective_function=ObjectiveFunction.MAXIMIZE_RATIO,
    mu_uncertainty_set_estimator=BootstrapMuUncertaintySet(confidence_level=0.5),
    covariance_uncertainty_set_estimator=EmpiricalCovarianceUncertaintySet(
        confidence_level=0.5
    ),
)
model.fit(X)
print(model.weights_)
```

# user_guide/variance.html.md

<a id="variance-estimator"></a>

<a id="id1"></a>

# Variance Estimator

A [variance estimator](https://skfolio.org/api.html.md#variance-ref) estimates the variance vector of the
assets.

It follows the same API as scikit-learn’s `estimator`: the `fit` method takes `X` as
the assets returns and stores the variances in its `variance_` attribute.

Variance estimators are useful when only marginal volatility is needed, for example
when modelling idiosyncratic risk or working with orthogonalized return series.

`X` can be any array-like structure (numpy array, pandas DataFrame, etc.)

Available estimators are:
: * [`EmpiricalVariance`](https://skfolio.org/generated/skfolio.moments.EmpiricalVariance.html.md#skfolio.moments.EmpiricalVariance)
  * [`EWVariance`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance)
  * [`RegimeAdjustedEWVariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance)

For online learning and streaming workflows, [`EWVariance`](https://skfolio.org/generated/skfolio.moments.EWVariance.html.md#skfolio.moments.EWVariance) and
[`RegimeAdjustedEWVariance`](https://skfolio.org/generated/skfolio.moments.RegimeAdjustedEWVariance.html.md#skfolio.moments.RegimeAdjustedEWVariance) support incremental updates with
`partial_fit`. They also support NaN-aware updates with `active_mask`, which
helps distinguish assets that belong to the universe but have missing returns (e.g.
holidays), from assets outside the universe (e.g. pre-listing or post-delisting
periods).
See [Missing Data and Changing Universes](https://skfolio.org/user_guide/data_representation.html.md#missing-data) for the full convention
on NaNs, universe membership, estimator warmup and investability.

**Example:**

```python
from skfolio.datasets import load_sp500_dataset
from skfolio.moments import EmpiricalVariance
from skfolio.preprocessing import prices_to_returns

prices = load_sp500_dataset()
X = prices_to_returns(prices)

model = EmpiricalVariance()
model.fit(X)
print(model.variance_)
```