# Tutorial: Testing a 5-Day Reversal Alpha

Generated: 2026-06-12T18:30:56

This document is a teaching walkthrough for someone who is new to this research
framework and only lightly familiar with quant research. We will use one
concrete experiment, a 5-day reversal alpha on the full downloaded Chinese
A-share universe, to learn how the framework defines an alpha, stores it, tests
it, turns it into a portfolio, and explains the gap between a research result
and simulated trading PnL.

The important point is not the timestamp; it is the research method.

## The Research Question

A quant research project starts with a hypothesis:

> If a stock fell a lot over the last few trading days, it may rebound soon; if
> it rose a lot, it may cool off soon.

This is called **short-horizon reversal**. It is a simple idea: recent losers
are candidates to buy, and recent winners are candidates to sell or underweight.
In this repo, the tested version looks back 5 trading days.

The central research question is:

> Does this 5-day reversal rule create useful portfolio returns after the
> framework applies realistic storage, portfolio construction, execution
> constraints, and trading costs?

The answer from this run is nuanced:

- The naive built-in version is positive under the tradable
  next-open-to-next-open research convention (**41.40%**),
  but its stored weights still show that raw z-score weighting is too sensitive
  to A-share outliers.
- A rank-weighted version on a liquid, non-ST, tradable universe has a positive
  costless research result: **209.58%**
  at Sharpe **1.44**.
- The daily-traded implementation is still not tradable after costs because
  turnover is too high.

That is a normal research outcome. Good research is not just asking "did the
backtest go up?" It is asking **which layer explains the result**: signal,
weighting, universe, construction, execution, or cost.

## How This Framework Defines An Alpha

In many quant textbooks, an alpha is described as a **prediction** of future
returns. This framework uses a stricter and more practical convention:

> An alpha is a signed cross-sectional position weight.

That sentence is the key to the whole repo.

- **Signed** means positive values are long exposure and negative values are
  short exposure.
- **Cross-sectional** means the alpha compares stocks to other stocks on the
  same date.
- **Position weight** means the output is already an instruction about what the
  portfolio wants to own. It is not merely a score to correlate with future
  returns.

The stored alpha file always has this schema:

| column | meaning |
| --- | --- |
| `symbol_id` | Stock identifier such as `sh600000` or `sz000001`. |
| `date` | The signal date. The alpha is formed using information known by this date's close. |
| `alpha_name` | A label for this particular run, such as `reversal_5d_all`. |
| `weight` | Signed desired exposure. Positive means long; negative means short. |

Because the framework treats alphas as position weights, it evaluates them with
portfolio metrics: return, Sharpe, turnover, drawdown, and hit rate. It does
**not** use IC/IR, because IC/IR would treat the alpha as a return predictor.

## The Pipeline In One Picture

Every phase reads parquet files and writes parquet files. That makes the system
easy to inspect and rerun one layer at a time.

```text
daily bars
   -> alpha weights
   -> combined weights
   -> portfolio targets and integer positions
   -> simulated fills and PnL
   -> evaluation metrics
```

For this experiment, the important phases are:

| phase | command family | what it teaches you |
| --- | --- | --- |
| Data | `cli.py data download` | What market data is available. |
| Alpha compute | `cli.py alpha compute` | How a raw research idea becomes stored weights. |
| Alpha eval | `cli.py alpha eval` | How close-formed weights perform over the tradable next-open-to-next-open interval. |
| Combo | `cli.py combo combine` | How one or more alphas become one combined book. |
| Portfolio build | `cli.py portfolio build` | How weights become target values and integer shares. |
| Portfolio simulate | `cli.py portfolio simulate` | How the integer book trades at next open with constraints and costs. |
| Portfolio eval | `cli.py portfolio eval` | How the continuous target portfolio behaves over the same costless open-to-open research interval. |

In a real research workflow, you should learn to pause after every phase and
inspect the parquet output. Most mistakes are easier to find at the interface
between two phases than at the final PnL line.

## Step 1: Define The Raw Reversal Signal

The built-in 5-day reversal alpha is implemented as:

```python
signal = -close.pct_change(5, fill_method=None)
```

For stock `i` on date `t`, this is approximately:

```text
signal[i, t] = -(close[i, t] / close[i, t-5] - 1)
```

So:

- If a stock rose by 10% over the last 5 trading days, the raw signal is `-10%`.
  It becomes a candidate short or underweight.
- If a stock fell by 10% over the last 5 trading days, the raw signal is `+10%`.
  It becomes a candidate long or overweight.

Notice the timing. The signal uses prices through date `t`. It must not use the
return from `t` to `t+1`, because that is the future. The costless alpha
evaluator tests the weight formed on date `t` over the tradable interval from
`open[t+1]` to `open[t+2]`; the later execution simulator is the separate layer
that trades the constructed integer book at the next open.

## Step 2: Turn A Signal Into Cross-Sectional Weights

By default, `BaseAlpha.to_weights()` does a cross-sectional z-score each date:

```text
weight[i, t] = (signal[i, t] - mean_signal[t]) / std_signal[t]
```

This means the framework asks:

> On this date, which stocks have stronger reversal scores than the rest of the
> market, and by how much?

That is useful, but it has a weakness. If a few stocks have extreme trailing
returns because they are newly listed, suspended, illiquid, or limit-constrained,
z-scoring can put a very large amount of relative exposure into exactly those
names.

That is visible in the naive full-universe run. Stored weights reached about
`-52` standard deviations. The
result is positive under the open-to-open convention, but it is much weaker and
less robust than the rank-weighted versions:

| run | weighting | research cumulative return | research Sharpe | research turnover/year |
| --- | --- | --- | --- | --- |
| naive z-score, full universe | z-score | 41.40% | 0.4514 | 160x |

The lesson is not "reversal is solved." The lesson is:

> The same raw signal can become a fragile portfolio if the weighting method
> reacts badly to outliers.

## Step 3: Make The Weighting More Robust

The repo also has a rank-weighted version, `reversal_rank`. It uses the same raw
5-day reversal signal, but converts the cross-section to ranks instead of
z-scores:

```python
ranks = signal.rank(axis=1)
weights = ranks.subtract(ranks.mean(axis=1), axis=0)
```

Rank weighting keeps the ordering of stocks but removes the importance of the
exact outlier magnitude. A stock can be "the worst recent loser" or "the best
recent winner," but it cannot become dozens of standard deviations important
just because its raw percentage move is unusual.

The full-universe rank version was much less pathological, but still not a
clean signal:

| run | weighting | research cumulative return | research Sharpe | research turnover/year |
| --- | --- | --- | --- | --- |
| rank, full universe | rank | 73.44% | 0.8860 | 143x |

That tells us the weighting fix helped, but the universe still contains many
names that are poor candidates for a daily reversal strategy.

## Step 4: Define The Investable Universe

An alpha should be tested on stocks that could plausibly be traded. The liquid
run applies a per-date mask before weights are created. A stock must be:

- seasoned, with at least 60 observed closes;
- currently tradable, using `tradestatus == 1`;
- not ST, using `isST == 0`;
- inside the top 1000 names by trailing 20-day average traded amount.

This mask is applied to the signal, not to the price history used to compute the
5-day return. That distinction matters. We still compute `pct_change(5)` on the
full contiguous price history, then decide which names are eligible to hold on
each signal date.

The liquid rank result is the cleanest research result:

| run | weighting | universe | research cumulative return | research Sharpe | hit rate |
| --- | --- | --- | --- | --- | --- |
| rank, liquid subset | rank | top 1000 liquid, tradable, non-ST | 209.58% | 1.4422 | 55.68% |

This is the first point where a researcher can say:

> There appears to be a real 5-day reversal effect in a cleaner A-share
> universe, before trading costs.

That last phrase, **before trading costs**, is essential.

![Research equity](assets/reversal_5d_research_equity.png)

## Step 5: Check That The Alpha File Is Sane

Before trusting any metric, inspect the stored alpha artifact. The run checked:

- The columns match `ALPHA_COLUMNS`.
- There are no null weights.
- There are no non-finite weights.
- There are no duplicate `(symbol_id, date)` rows.
- The daily cross-sectional mean is approximately zero.
- A one-alpha combo is an exact identity transform.

| run | schema ok | null w | non-finite w | dup keys | max \|daily mean\| | weight range | combo identity Δ |
| --- | --- | --- | --- | --- | --- | --- | --- |
| naive z-score (full) | True | 0 | 0 | 0 | 3.32e-16 | [-52.2, 19.2] | 0.00e+00 |
| rank (full) | True | 0 | 0 | 0 | 0.00e+00 | [-2603.0, 2603.0] | 0.00e+00 |
| rank (liquid subset) | True | 0 | 0 | 0 | 0.00e+00 | [-498.5, 498.5] | 0.00e+00 |

The rank ranges look numerically large because rank weights scale with the
number of names. That is fine: later evaluation divides by gross exposure, and
portfolio construction normalizes by `sum(abs(weight))`. The important
difference is that rank weights are bounded by cross-sectional rank, not by the
raw size of an abnormal stock move.

![Weight distributions](assets/reversal_5d_weight_distributions.png)

## Step 6: Understand The Alpha Evaluation Formula

The costless alpha evaluator now asks:

> If we compute alpha weights after close on date `t`, trade them at `open[t+1]`,
> and hold them until `open[t+2]`, what return would we earn before costs?

This is still a **research-layer approximation**, not the trading simulator. At
this stage the framework has only an alpha weight file. It has not yet rounded
shares, checked limits, clipped trades, or paid costs. The purpose is to answer
a clean signal question: "Do these close-formed weights line up with returns
over the interval we could actually own after next-open execution?"

The daily research return is:

```text
R[t] = sum_i(weight[i, t] * (open[i, t+2] / open[i, t+1] - 1)) / sum_i(abs(weight[i, t]))
```

This has three important consequences:

- The alpha is normalized by its gross exposure, so the scale of raw weights
  does not by itself create a higher return.
- The new signal does not receive credit for the overnight gap from `close[t]`
  to `open[t+1]`, because it cannot be traded until `open[t+1]`.
- The final two signal dates are dropped from performance metrics because they
  do not have a complete next-open-to-next-open holding interval.

Turnover is still measured from the weights:

```text
turnover[t] = sum_i(abs(weight[i, t] - weight[i, t-1])) / sum_i(abs(weight[i, t-1]))
```

The annualized turnover numbers are a warning. Even a positive signal can be
hard to monetize if it asks the portfolio to trade too much every day.

## Step 7: Build A Portfolio From The Alpha

The alpha file is still an abstract research book. `portfolio build` turns it
into target exposures and integer shares.

The main normalization is:

```text
target_weight[i, t] = weight[i, t] / sum_i(abs(weight[i, t]))
target_value[i, t] = booksize * target_weight[i, t]
target_shares[i, t] = target_value[i, t] / construction_price[i, t]
```

Then the framework creates an integer A-share book using lot rules and repair
logic. This is where a research portfolio starts to become a tradable portfolio.

The continuous target portfolio matched the stored alpha almost exactly:

| run | target_value identity max\|Δ\| | alpha→target max\|Δ\| | research corr(alpha,portfolio) | mean integer gross | mean L1 tracking |
| --- | --- | --- | --- | --- | --- |
| naive z-score (full) | 0.0000 | 0.00e+00 | 1.000000 | 9,138,331 | 2,542,655 |
| rank (full) | 0.0000 | 0.00e+00 | 1.000000 | 8,984,098 | 2,678,278 |
| rank (liquid subset) | 0.0000 | 0.00e+00 | 1.000000 | 9,810,256 | 862,303 |

![Portfolio tracking](assets/reversal_5d_portfolio_tracking.png)

## Step 8: Simulate Execution And Costs

Research returns are not the same as tradable PnL. The simulator executes the
integer `position_shares` at the next available open and applies constraints:

- suspension;
- price limit;
- volume cap;
- proportional trading cost.

The cost model is:

```text
cost = abs(traded_shares * open) * (cost_bps + slippage_bps) / 10000
```

For this run, cost is 5 bps commission plus 5 bps slippage. Slippage is treated
as cash cost, not as an additional execution price adjustment.

The execution results explain the final research conclusion:

| run | corr(alpha, exec net) | PnL before cost | total cost | net PnL | mean daily turnover |
| --- | --- | --- | --- | --- | --- |
| naive z-score (full) | 0.8956 | 1,838,974 | 13,032,720 | -11,193,746 | 0.5711 |
| rank (full) | 0.9126 | 5,052,067 | 11,713,451 | -6,661,383 | 0.5133 |
| rank (liquid subset) | 0.8884 | 11,017,842 | 12,733,803 | -1,715,960 | 0.5715 |

For the liquid rank run, simulated PnL before cost is about
11,017,842, but total
cost is about 12,733,803. That is why
the final net PnL is weak or negative.

This is not a contradiction. It is exactly what a research pipeline should show:

> The signal can exist in the costless layer, but the daily implementation can
> still trade too much to keep the edge.

![Execution vs research](assets/reversal_5d_exec_vs_research.png)

## Step 9: Read The Headline Metrics Like A Researcher

The complete summary is:

| run | weighting | research cum | research Sharpe | research turn/yr | exec before cost | exec net | exec net Sharpe |
| --- | --- | --- | --- | --- | --- | --- | --- |
| naive z-score (full) | z-score | 41.40% | 0.4514 | 160× | 18.39% | -111.94% | -1.4508 |
| rank (full) | rank | 73.44% | 0.8860 | 143× | 50.52% | -66.61% | -1.1839 |
| rank (liquid subset) | rank | 209.58% | 1.4422 | 148× | 110.18% | -17.16% | -0.2226 |

*Research = costless, no-look-ahead weights over the next-open-to-next-open
holding interval. Execution = next-open fills on the discretized integer book
under suspension / price-limit / volume-cap constraints, 5 bps commission + 5
bps slippage.*

Here is the interpretation:

- **Naive z-score full universe**: positive under open-to-open research, but a
  less reliable test of the reversal idea because the weighting scheme lets
  outliers dominate parts of the book.
- **Rank full universe**: a better test of the same idea, but still noisy
  because the universe includes too many problematic names.
- **Rank liquid subset**: the best signal-level test; it finds the cleanest
  costless reversal effect.
- **Execution net**: daily rebalancing remains heavily constrained by cost.

A beginner might look only at the final net PnL and say "the alpha failed." A
researcher should be more precise:

> The raw 5-day reversal idea has signal value in a liquid universe, but the
> current daily trading rule has too much turnover for the assumed cost model.

## Step 10: Time Consumption By Phase

| phase | rank full (s) | rank liquid (s) |
| --- | --- | --- |
| alpha compute | 94.1 | 107.8 |
| alpha eval | 93.3 | 96.9 |
| combo combine | 21.6 | 21.7 |
| portfolio build | 537.6 | 236.7 |
| portfolio eval | 95.1 | 88.3 |
| portfolio simulate | 139.6 | 139.1 |
| total | 981.3 | 690.5 |

![Phase timings](assets/reversal_5d_phase_timings.png)

`portfolio build` usually dominates because it iterates per signal date and
repairs a multi-thousand-name integer book under lot rules. The liquid run is
faster because it carries fewer non-zero names per date.

## Step 11: Reproduce The Experiment

These commands reproduce the important artifacts, assuming the full daily-bar
dataset already exists at `data/daily_bars/all`.

```bash
# Naive z-score baseline: built-in reversal alpha, full universe.
uv run python cli.py alpha compute --data-path data/daily_bars/all \
    --alpha-name reversal_5d_all --alpha-type reversal --lookback 5 \
    --output-dir alphas

# Rank-weighted full and liquid runs.
bash scripts/run_reversal_rank_e2e.sh

# Regenerate figures, diagnostics, and this tutorial report.
uv run python scripts/generate_reversal_5d_report.py
```

If you are learning the framework, do not run the whole pipeline blindly. Run
one phase, inspect the output parquet, then continue.

## How To Research Your Own Alpha

Use this checklist for a new idea.

1. State the hypothesis in plain language.
   Example: "Stocks with poor 5-day returns may rebound over the next day."

2. Write the raw signal.
   Implement `signal(close) -> wide DataFrame` in an alpha class. Higher values
   should mean stronger long preference.

3. Choose the weighting method.
   The default z-score is useful, but it can be fragile. Consider rank weights,
   caps, neutralization, or liquidity-aware filters if outliers dominate.

4. Define the investable universe before trusting results.
   Make sure the strategy is not depending on suspended, ST, newly listed, or
   illiquid names.

5. Evaluate the alpha as a portfolio, not as a prediction.
   Check cumulative return, Sharpe, drawdown, hit rate, and turnover over the
   next-open-to-next-open holding interval. Do not add IC/IR unless the
   framework's alpha convention changes.

6. Build the portfolio and inspect tracking.
   Confirm that target weights match the alpha, then check whether integer
   shares still track the target book.

7. Simulate execution with costs.
   The final research question is not only "is there a signal?" It is "is there
   enough signal left after realistic trading?"

8. Diagnose the failure layer.
   If results are bad, identify whether the problem is the raw signal, weighting,
   universe, construction, execution constraints, turnover, or cost.

For this 5-day reversal study, the diagnosis is clear: **the signal-level result
is most promising after robust weighting and a liquid universe filter, but the
current implementation needs turnover control before it can be considered
tradable.**

## Next Research Directions

The natural next experiments are:

- Add turnover control: no-trade bands, slower rebalancing, or weight smoothing.
- Sweep the lookback window: compare 3-day, 5-day, 10-day, and 20-day reversal.
- Sweep liquidity filters: top 500, top 1000, top 1500 by traded amount.
- Add position caps so no single name can dominate after normalization.
- Compare rank weighting with volatility-scaled reversal.

The most important habit is to keep the layers separate. A good alpha research
workflow does not stop at a single performance number; it explains how the idea
travels from hypothesis, to signal, to weights, to portfolio, to executable PnL.