skfolio.descriptor.RollingMomentum#

class skfolio.descriptor.RollingMomentum(window=252, skip=21, exponentiate=False)[source]#

Fixed-window momentum descriptor.

Computes the sum of log returns over a trailing window with an optional skip period to exclude the most recent observations:

The skip period separates medium-term momentum from short-term reversal. The classic “12-1” momentum signal uses a skip of approximately one month [1].

\[ \begin{aligned} x(k) &= \log(1 + r(k)) \\[0.75em] S(t) &= \sum_{k=t-\text{skip}-\text{window}+1}^{t-\text{skip}} x(k) \\[0.75em] \text{momentum}(t) &= \begin{cases} \exp(S(t)) - 1 & \text{if } \texttt{exponentiate=True} \\ S(t) & \text{otherwise} \end{cases} \end{aligned} \]

The window uses the \(\text{window}\) observations ending at \(t - \text{skip}\). Output is NaN until the asset has a full active lookback window.

By default, the descriptor is returned in log-return space. Log cumulative returns are more symmetric than simple cumulative returns, which makes them better suited to cross-sectional standardization. Because the logarithm is monotonic, log-space and simple cumulative returns produce the same cross-sectional rankings when returns are finite and greater than -1.

Parameters:

windowint, default=252: Number of observations in the lookback window.
skipint, default=21: Number of most recent observations excluded from the window. The last observation included is at \(t - \text{skip}\). Classic 12-1 momentum uses a skip of about one month (21 daily obs). Set to 0 for no skip.
exponentiatebool, default=False: If True, output is \(\exp(S(t)) - 1\) (return units). If False, output is \(S(t)\) (log space). Cross-sectional ranking is unchanged and only the scale differs.

Attributes:

n_assets_int: Number of assets seen during fitting.
asset_names_ndarray of shape (n_assets,): Asset names seen during fitting.
momentum_ndarray of shape (n_assets,): Last rolling momentum value for each asset.

Methods

`fit_transform`(X[, y])	Compute the rolling log-return descriptor from a clean state.
`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 compute the rolling log-return descriptor.
`set_params`(**params)	Set the parameters of this estimator.

See also

EWMomentum: Exponentially weighted momentum.

Notes

Two code paths are used depending on context:

Batch (first call with sufficient data): vectorized cumsum over the full panel. Time \(O(T \cdot n)\), space \(O(T \cdot n)\).
Online (subsequent calls or streaming): ring buffer of size \(L = \text{skip} + \text{window}\) with a running sum. Per observation: one subtract (value leaving the window), one add (value entering), one write. Time \(O(n)\) per step, space \(O(L \cdot n)\), zero allocation.

After a batch computation, the ring buffer state is populated for subsequent online calls.

NaNs are allowed as missing observations. Non-missing returns values must be finite and greater than -1, so \(\log(1 + r)\) is finite. Active assets with NaN returns (e.g. holidays) contribute 0 to the sum. Inactive asset outputs are set to NaN.

References

[1]

“Returns to buying winners and selling losers: Implications for stock market efficiency” The Journal of Finance. Jegadeesh, N., & Titman, S. (1993).

Examples

>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import RollingMomentum
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 12-1 momentum
>>> descriptor = RollingMomentum(window=252, skip=21)
>>> momentum = descriptor.fit_transform(X)
>>>
>>> # Log-space output
>>> descriptor = RollingMomentum(window=252, skip=21, exponentiate=False)
>>> momentum_log = descriptor.fit_transform(X)

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

Compute the rolling log-return descriptor 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:

descriptorndarray of shape (n_observations, n_assets): Rolling log-return descriptor 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 state and compute the rolling log-return descriptor.

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:

descriptorndarray of shape (n_observations, n_assets): Rolling log-return descriptor 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.