chinese-equity-quant/docs/reversal_5d_all_universe_pipeline_report.md

Tutorial: Testing a 5-Day Reversal Alpha

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.

This generated version was refreshed at 2026-06-12T22:52:56. 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.

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:

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

For stock i on date t, this is approximately:

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.

The code lives in pipeline/alpha/library/reversal.py:

class ReversalAlpha(BaseAlpha):
    name = "reversal"

    def __init__(self, lookback: int = 5):
        self.lookback = lookback

    def signal(self, close: pd.DataFrame) -> pd.DataFrame:
        return -close.pct_change(self.lookback, fill_method=None)

The alpha class only defines the raw signal. The base class then turns that signal into weights.

Step 2: Turn A Signal Into Cross-Sectional Weights

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

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:

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.

When reading this chart, focus on the shape and relative behavior:

• The naive z-score line shows why outlier-sensitive weighting is fragile.
• The rank full-universe line shows that robust weighting helps, but the full universe still contains noisy and hard-to-trade names.
• The liquid rank line shows the signal-level edge before execution costs.

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.

This is a good habit: when a backtest looks strange, plot the weights before debugging the PnL. A broken or concentrated weight distribution often explains the result.

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:

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:

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:

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

The integer book is not exact because small target positions can be rounded away. The liquid subset has lower tracking error because it spreads the book over fewer and more tradable names.

When you research a new alpha, ask two separate questions:

• Does the continuous target portfolio match the alpha? It should.
• Does the integer tradable portfolio still resemble the target? It may not, especially for small books or very broad universes.

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:

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.

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: Reproduce The Experiment

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

# 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.

Appendix: Phase Timings From This Rerun

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

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.