<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`](#skfolio.descriptor.EWResidualDownsideVolatility.fit_transform)(X[, y])         | Compute exponentially weighted CAPM residual volatility.         |
|--------------------------------------------------------------------------------|------------------------------------------------------------------|
| [`get_metadata_routing`](#skfolio.descriptor.EWResidualDownsideVolatility.get_metadata_routing)()        | Get metadata routing of this object.                             |
| [`get_params`](#skfolio.descriptor.EWResidualDownsideVolatility.get_params)([deep])            | Get parameters for this estimator.                               |
| [`partial_fit_transform`](#skfolio.descriptor.EWResidualDownsideVolatility.partial_fit_transform)(X[, y]) | Update EWMA state and return residual volatility for this batch. |
| [`set_params`](#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.