skfolio.descriptor.EWAmihudIlliquidity#

class skfolio.descriptor.EWAmihudIlliquidity(half_life=63.0, min_periods=None)[source]#

Exponentially weighted Amihud illiquidity descriptor.

Computes an EWMA of the per-observation Amihud illiquidity ratio:

\[ \begin{aligned} \text{ILLIQ\_raw}(t) &= \frac{|r(t)|} {\text{adj\_close}(t) \times \text{adj\_volume}(t)} \\[0.75em] \text{ILLIQ}(t) &= \lambda \cdot \text{ILLIQ}(t-1) + (1 - \lambda) \cdot \text{ILLIQ\_raw}(t) \end{aligned} \]

where \(\lambda = \exp(-\ln(2) / \text{half\_life})\) is the EWMA decay factor and the denominator is the dollar trading volume (traded amount).

The Amihud illiquidity ratio is a proxy for price impact, defined as the absolute return per unit of dollar volume traded. Higher values imply larger price moves for a given dollar amount traded, reflecting lower liquidity. Higher illiquidity is often associated with higher expected returns, commonly interpreted as an illiquidity premium for bearing higher trading costs and exit risk [1].

EWMA smoothing is preferred over a fixed rolling average because the raw ratio is very noisy (it can spike when volume is low or returns are large). EWMA dampens transient spikes gradually, producing more stable factor exposures.

Parameters:

half_lifefloat, default=63.0

EWMA half-life in observations. Controls how fast old illiquidity values decay. With daily data, common choices are:

half_life=21: ~1 month
half_life=63: ~3 months (default)
half_life=252: ~1 year

min_periodsint, optional

Minimum number of valid illiquidity observations 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 illiquidity 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.
illiquidity_ndarray of shape (n_assets,): Last EWMA-smoothed Amihud illiquidity value for each asset.

Methods

`fit_transform`(X[, y])	Compute exponentially weighted Amihud illiquidity.
`get_metadata_routing`()	Get metadata routing of this object.
`get_params`([deep])	Get parameters for this estimator.
`partial_fit_transform`(X[, y])	Update state and return smoothed illiquidity for this batch.
`set_params`(**params)	Set the parameters of this estimator.

See also

EWShareTurnover: EWMA share turnover (volume-based liquidity).

Notes

Dollar trading volume (traded_amount) is computed internally as adj_close * adj_volume. Both fields must use the same split-adjustment basis.

NaNs are allowed as missing observations. Non-missing returns values must be finite. Non-missing adj_close values must be finite and strictly positive. Non-missing adj_volume values must be finite and non-negative.

The EWMA state is updated only for valid observations. Zero adj_volume means the stock did not trade, so the per-observation ratio is undefined: the EWMA state is held and the valid-observation count is not incremented. NaN in returns, adj_close or adj_volume is handled the same way.

The active_mask property of the AssetPanel distinguishes holidays from delistings.

References

[1]

“Illiquidity and stock returns: cross-section and time-series effects” Journal of Financial Markets. Amihud, Y. (2002).

Examples

>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWAmihudIlliquidity
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 3-month effective window (default)
>>> descriptor = EWAmihudIlliquidity()
>>> illiq = descriptor.fit_transform(X)
>>>
>>> # 1-month effective window
>>> descriptor = EWAmihudIlliquidity(half_life=21)
>>> illiq_1m = descriptor.fit_transform(X)

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

Compute exponentially weighted Amihud illiquidity.

Parameters:

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

Returns:

illiquidityndarray of shape (n_observations, n_assets): EWMA-smoothed Amihud illiquidity 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 state and return smoothed illiquidity 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", "adj_close", and "adj_volume".
yNone: Ignored. Present for compatibility with scikit-learn’s API.
**fit_paramsdict: Additional fit parameters. Ignored.

Returns:

illiquidityndarray of shape (n_observations, n_assets): EWMA-smoothed Amihud illiquidity 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.