skfolio.descriptor.EWMacroSensitivity#

class skfolio.descriptor.EWMacroSensitivity(half_life=60.0, aggregation_period=1, min_periods=None, eps=1e-12)[source]#

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_lifefloat, default=60.0: EWMA half-life in units of aggregated periods.
aggregation_periodint, default=1: Number of consecutive observations to aggregate before updating EWMA statistics.
min_periodsint, 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.
epsfloat, 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`(X[, y, reference_returns])	Compute exponentially weighted macro sensitivities.
`get_metadata_routing`()	Return metadata routing for the external reference series.
`get_params`([deep])	Get parameters for this estimator.
`partial_fit_transform`(X[, y, reference_returns])	Update EWMA state and return macro sensitivities for this batch.
`set_params`(**params)	Set the parameters of this estimator.

See also

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

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

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

Compute exponentially weighted macro sensitivities.

Parameters:

XAssetPanel: Input panel containing returns and market_cap.
yNone: Ignored. Present for compatibility with scikit-learn’s API.
reference_returnsarray-like of shape (n_observations,): External reference return series aligned with X (e.g., macro factor).
**fit_paramsdict: Additional fit parameters. Ignored.

Returns:

sensitivitiesndarray of shape (n_observations, n_assets): Partial beta to the reference series for each observation and asset.

get_metadata_routing()[source]#: Return metadata routing for the external reference series.

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, reference_returns=None, **fit_params)[source]#

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:

XAssetPanel: Input panel containing "returns" and "market_cap".
yNone: Ignored. Present for compatibility with scikit-learn’s API.
reference_returnsarray-like of shape (n_observations,): External macro reference returns, e.g. FX basket returns.
**fit_paramsdict: Additional fit parameters. Ignored.

Returns:

sensitivitiesndarray of shape (n_observations, n_assets): Partial beta to the reference series 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.