skfolio.descriptor.EWMarketBeta#

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)[source]#

Exponentially weighted market beta descriptor.

Measures each asset’s sensitivity to the market portfolio using exponentially weighted covariance and variance estimates [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_lifefloat, 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_periodint, 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_periodsint, 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_groupstr, 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\]

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.

Missing category codes are excluded from shrinkage. If None (default), no shrinkage is applied.

min_group_sizeint, 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_boundstuple 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.

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.

epsfloat, 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`(X[, y])	Compute exponentially weighted market betas.
`get_metadata_routing`()	Get metadata routing of this object.
`get_params`([deep])	Get parameters for this estimator.
`partial_fit_transform`(X[, y])	Update EWMA state on X and return betas for this batch.
`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 distinguishes holidays from delistings.

Market returns are computed from the estimation universe (estimation_mask of 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

[1]

“Capital asset prices: A theory of market equilibrium under conditions of risk”. The Journal of Finance. Sharpe, W. F. (1964).

fit_transform(X, y=None, **fit_params)[source]#

Compute exponentially weighted market betas.

Parameters:

XAssetPanel: Input panel containing returns and market_cap, and when shrinkage_group is set, that group characteristic.
yNone: Ignored. Present for compatibility with scikit-learn’s API.
**fit_paramsdict: Additional fit parameters. Ignored.

Returns:

betasndarray of shape (n_observations, n_assets): Market beta for each observation and asset.

get_metadata_routing()#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)#

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

partial_fit_transform(X, y=None, **fit_params)[source]#

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:

XAssetPanel: Input panel containing at least "returns" and "market_cap". If shrinkage is enabled, it must also contain the field specified by shrinkage_group.
yNone: Ignored. Present for compatibility with scikit-learn’s API.
**fit_paramsdict: Additional fit parameters. Ignored.

Returns:

betasndarray of shape (n_observations, n_assets): Market beta for each observation and asset.

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:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.