<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`](#skfolio.descriptor.EWMacroSensitivity.fit_transform)(X[, y, reference_returns])         | Compute exponentially weighted macro sensitivities.              |
|---------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| [`get_metadata_routing`](#skfolio.descriptor.EWMacroSensitivity.get_metadata_routing)()                           | Return metadata routing for the external reference series.       |
| [`get_params`](#skfolio.descriptor.EWMacroSensitivity.get_params)([deep])                               | Get parameters for this estimator.                               |
| [`partial_fit_transform`](#skfolio.descriptor.EWMacroSensitivity.partial_fit_transform)(X[, y, reference_returns]) | Update EWMA state and return macro sensitivities for this batch. |
| [`set_params`](#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.