horizon_returns

Defined in fynance.features.horizon

horizon_returns(prices, h, *, overlapping=False)[source]

Forward return over a fixed horizon h, strictly causal.

The label at time t is the simple return realized over the next h steps, \(prices_{t+h} / prices_t - 1\). It looks forward (the label at t is only known at t + h), so it is a prediction target, not a feature — never feed it back into the model as an input at time t.

By default the labels are non-overlapping: one sample every h steps (t = 0, h, 2h, ...), so no two labels share any underlying price move. This matters for Information Coefficient estimation — overlapping H-bar labels are autocorrelated by construction and inflate the apparent IC. Set overlapping=True to get one label per bar (t = 0, 1, 2, ...) when that autocorrelation is acceptable.

Parameters:
pricesnp.ndarray[dtype, ndim=1 or 2]

Time-series of prices indexed by time on the first axis. For a 2-D (T, N) panel each column is an independent series.

hint

Forward horizon in number of steps, must be a positive integer.

overlappingbool, optional

If False (default), keep one label every h steps (non-overlapping). If True, keep one label per bar (overlapping).

Returns:
np.ndarray[np.float64, ndim=1 or 2]

Forward horizon returns. A 1-D input of length T yields a 1-D output; a 2-D (T, N) input yields a (K, N) output where K is the number of retained labels.

See also

fynance.metrics.information_coefficient

Notes

With \(T\) observations and horizon \(h\), the forward return is

\[r^{(h)}_t = \frac{prices_{t+h}}{prices_t} - 1\]

defined for \(t + h < T\). The non-overlapping output keeps \(t \in \{0, h, 2h, \dots\}\) and has length \(\lfloor (T - 1) / h \rfloor\); the overlapping output keeps every \(t \in \{0, 1, \dots\}\) and has length \(T - h\).

References

Examples

Non-overlapping 2-step forward returns (one label every 2 bars):

>>> import numpy as np
>>> prices = np.array([100., 110., 121., 133.1, 146.41, 161.051])
>>> horizon_returns(prices, 2)
array([0.21, 0.21])

Overlapping labels keep one per bar:

>>> horizon_returns(prices, 2, overlapping=True)
array([0.21, 0.21, 0.21, 0.21])