<a id="skfolio-descriptor-reversal"></a>

# skfolio.descriptor.Reversal

<a id="skfolio.descriptor.Reversal"></a>

### *class* skfolio.descriptor.Reversal(window=21)

Fixed-window short-term reversal descriptor.

Computes the negated cumulative log return over a trailing window:

$$
\text{reversal}(t) = -\sum_{k=t-w+1}^{t} \log(1 + r_k)
$$

where $w$ is the `window` size and $r_k$ is the asset return at
observation $k$. High values indicate recent poor performance (reversal
candidates).

Short-term reversal captures mean reversion in returns driven by temporary price
pressure, liquidity provision and microstructure effects [[1]](#r3e64ad5733a4-1) [[2]](#r3e64ad5733a4-2).

The output is NaN until an asset has a full active lookback window. Active assets
with missing returns contribute zero to the log-return sum. Non-missing `returns`
values must be finite and greater than `-1`.

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:**
  **window** *int, default=21*
  : Number of trailing observations for the cumulative return.
    Common choices for daily data:
    - `window=1`: 1-day reversal
    - `window=5`: 1-week reversal
    - `window=21`: 1-month reversal (default)
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

  **asset_names_** *ndarray of shape (n_assets,)*
  : Asset names seen during fitting.

  **reversal_** *ndarray of shape (n_assets,)*
  : Last short-term reversal value for each asset.

### Methods

| [`fit_transform`](#skfolio.descriptor.Reversal.fit_transform)(X[, y])         | Compute the rolling log-return descriptor from a clean state.   |
|--------------------------------------------------------------------------------|-----------------------------------------------------------------|
| [`get_metadata_routing`](#skfolio.descriptor.Reversal.get_metadata_routing)()        | Get metadata routing of this object.                            |
| [`get_params`](#skfolio.descriptor.Reversal.get_params)([deep])            | Get parameters for this estimator.                              |
| [`partial_fit_transform`](#skfolio.descriptor.Reversal.partial_fit_transform)(X[, y]) | Update state and compute the rolling log-return descriptor.     |
| [`set_params`](#skfolio.descriptor.Reversal.set_params)(\*\*params)        | Set the parameters of this estimator.                           |

#### SEE ALSO
[`EWMomentum`](https://skfolio.org/generated/skfolio.descriptor.EWMomentum.html.md#skfolio.descriptor.EWMomentum)
: Exponentially weighted momentum (medium/long-term).

[`RollingMomentum`](https://skfolio.org/generated/skfolio.descriptor.RollingMomentum.html.md#skfolio.descriptor.RollingMomentum)
: Fixed-window momentum with optional skip.

### 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 $w$ (the window)
  with a running sum. Per observation: one subtract (value leaving the window), one
  add (current value), one write. Time $O(n)$ per step, space
  $O(w \cdot n)$, zero allocation.

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

### References

* <a id='r3e64ad5733a4-1'>**[1]**</a> “Evidence of predictable behavior of security returns” The Journal of Finance. Jegadeesh, N. (1990).
* <a id='r3e64ad5733a4-2'>**[2]**</a> “Fads, martingales, and market efficiency” The Quarterly Journal of Economics. Lehmann, B. N. (1990).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import Reversal
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> # 1-month reversal (default)
>>> descriptor = Reversal()
>>> reversal = descriptor.fit_transform(X)
>>>
>>> # 1-day reversal
>>> descriptor = Reversal(window=1)
>>> reversal_1d = descriptor.fit_transform(X)
>>>
>>> # 1-week reversal
>>> descriptor = Reversal(window=5)
>>> reversal_5d = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.Reversal.fit_transform"></a>

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

Compute the rolling log-return descriptor from a clean state.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **descriptor** *ndarray of shape (n_observations, n_assets)*
  : Rolling log-return descriptor for each observation and asset.

<a id="skfolio.descriptor.Reversal.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.Reversal.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.Reversal.partial_fit_transform"></a>

#### 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:**
  **X** *AssetPanel*
  : Input panel containing `returns`.

  **y** *None*
  : Ignored. Present for compatibility with scikit-learn’s API.

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **descriptor** *ndarray of shape (n_observations, n_assets)*
  : Rolling log-return descriptor for each observation and asset.

<a id="skfolio.descriptor.Reversal.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.