quantile_returns

Defined in fynance.metrics

quantile_returns(factor, fwd, n_quantiles=5)

Equal-count quantile-portfolio returns of a factor.

On each bar the assets valid in both factor and fwd (finite on both sides) are sorted by factor value and split into n_quantiles equal-count buckets — ties are broken by rank order (a stable sort), bucket 0 holding the lowest factor values and bucket n_quantiles - 1 the highest. Each bucket’s return is the equal-weighted mean of its assets’ forward returns. Bars with fewer than n_quantiles valid assets yield a row of np.nan (and zero counts).

Alignment. factor[t] is the score known at bar t and fwd[t] the return realized after t (built by the caller, e.g. via fynance.features.horizon_returns), so a positive top-minus-bottom spread means high-factor assets out-earned low-factor assets.

Parameters:

factornp.ndarray[dtype, ndim=2]

Factor panel (T, N) — the per-bar cross-sectional score.

fwdnp.ndarray[dtype, ndim=2]

Forward-return panel (T, N) aligned with factor.

n_quantilesint, optional

Number of equal-count buckets Q (default 5), a positive integer of at least 2.

Returns:

QuantileResult

The per-bar bucket returns, long-short spread, bucket counts and n_quantiles.

See also

fynance.metrics.information_coefficient, ic_summary

Examples

A two-bar, four-asset panel split into two buckets; the factor ranking is ascending on the first bar and descending on the second:

>>> import numpy as np
>>> factor = np.array([[1., 2., 3., 4.], [4., 3., 2., 1.]])
>>> fwd = np.array([[1., 2., 3., 4.], [1., 2., 3., 4.]])
>>> res = quantile_returns(factor, fwd, n_quantiles=2)
>>> res.quantile_returns
array([[1.5, 3.5],
       [3.5, 1.5]])
>>> res.spread
array([ 2., -2.])
>>> res.counts
array([[2, 2],
       [2, 2]])