skfolio.descriptor.EWShareTurnover#

class skfolio.descriptor.EWShareTurnover(half_life=21.0, min_periods=None)[source]#

Exponentially weighted share turnover descriptor.

Computes an EWMA of per-observation share turnover:

\[ \begin{aligned} \text{turnover\_raw}(t) &= \frac{\text{adj\_volume}(t)} {\text{adj\_shares\_outstanding}(t)} \\[0.75em] \text{turnover}(t) &= \lambda \cdot \text{turnover}(t-1) + (1 - \lambda) \cdot \text{turnover\_raw}(t) \end{aligned} \]

where \(\lambda = \exp(-\ln(2) / \text{half\_life})\) is the EWMA decay factor.

Share turnover measures trading intensity as the fraction of shares outstanding that changes hands over each observation period. Lower turnover indicates weaker trading activity and lower liquidity, making trades more likely to incur price impact. Low-turnover stocks are often associated with higher expected returns, commonly interpreted as an illiquidity premium [1].

EWMA smoothing is preferred over a fixed rolling average because turnover can spike around earnings, index rebalances or news events. EWMA dampens these spikes gradually, producing more stable factor exposures.

Parameters:

half_lifefloat, default=21.0

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

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

min_periodsint, optional

Minimum number of valid turnover 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 turnover 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.
turnover_ndarray of shape (n_assets,): Last EWMA-smoothed share turnover value for each asset.

Methods

`fit_transform`(X[, y])	Compute exponentially weighted share turnover.
`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 turnover for this batch.
`set_params`(**params)	Set the parameters of this estimator.

See also

EWAmihudIlliquidity: EWMA price-impact illiquidity measure.

Notes

adj_shares_outstanding is common shares outstanding. Both adj_volume and adj_shares_outstanding must use the same split-adjustment basis.

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

The EWMA state is updated only for valid observations. NaN in adj_volume or adj_shares_outstanding holds the EWMA state and does not increment the valid-observation count. Zero adj_volume is valid and produces zero turnover.

The active_mask property of the AssetPanel distinguishes holidays from delistings.

References

[1]

“Liquidity and stock returns: an alternative test” Journal of Financial Markets. Datar, V. T., Naik, N. Y., & Radcliffe, R. (1998).

Examples

>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import EWShareTurnover
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 1-month effective window (default)
>>> descriptor = EWShareTurnover()
>>> turnover = descriptor.fit_transform(X)
>>>
>>> # 3-month effective window
>>> descriptor = EWShareTurnover(half_life=63)
>>> turnover_3m = descriptor.fit_transform(X)

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

Compute exponentially weighted share turnover.

Parameters:

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

Returns:

turnoverndarray of shape (n_observations, n_assets): EWMA-smoothed share turnover 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 turnover 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 "adj_volume" and "adj_shares_outstanding".
yNone: Ignored. Present for compatibility with scikit-learn’s API.
**fit_paramsdict: Additional fit parameters. Ignored.

Returns:

turnoverndarray of shape (n_observations, n_assets): EWMA-smoothed share turnover 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.