skfolio.descriptor.EWDownsideVolatility#

class skfolio.descriptor.EWDownsideVolatility(half_life=40.0, min_acceptable_return=0.0, min_periods=None)[source]#

Exponentially weighted downside return volatility descriptor.

Computes the downside semi-deviation of asset returns using EWMA estimation [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_lifefloat, default=40.0: EWMA half-life in observations.
min_acceptable_returnfloat, default=0.0: Threshold below which returns are considered “downside”. The default of 0.0 defines downside as negative returns (losses).
min_periodsint, 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`(X[, y])	Compute exponentially weighted return volatility.
`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 and return volatility for this batch.
`set_params`(**params)	Set the parameters of this estimator.

See also

EWVolatility: Total (non-downside) variant.
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.

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

[1]

“The cross-section of volatility and expected returns” The Journal of Finance. Ang, A., Hodrick, R. J., Xing, Y., & Zhang, X. (2006).

Examples

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

fit_transform(X, y=None, **fit_params)#

Compute exponentially weighted return volatility.

Parameters:

XAssetPanel: Input panel containing returns.
yNone: Ignored. Present for compatibility with scikit-learn’s API.
**fit_paramsdict: Additional fit parameters. Ignored.

Returns:

volatilityndarray of shape (n_observations, n_assets): EWMA volatility (or downside volatility) 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)#

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:

XAssetPanel: Input panel containing returns.
yNone: Ignored. Present for compatibility with scikit-learn’s API.
**fit_paramsdict: Additional fit parameters. Ignored.

Returns:

volatilityndarray of shape (n_observations, n_assets): EWMA volatility (or downside volatility) 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.