Ranking Functions

How assets are scored and selected for portfolio construction.

Momentum Ranking

Ranks assets by price momentum — the difference between the current price and the price t periods ago. Higher momentum = higher rank.

Formula

Score(i) = P(i, today) - P(i, today - t)

Assets with the largest positive price change over t periods are ranked highest. The simulator handles the sorting (descending).

Parameters

Name	Type	Default	Description
`prices`	`DataFrame`	`—`	DataFrame of historical prices (datetime index, symbol columns)
`t`	`int`	`10`	Lookback period in trading days

How It Works

Computes simple price difference over the lookback window for each asset. Returns a Series of momentum values. The TPS simulator sorts descending to select top assets.

Live Demo — 10 Stocks Ranked

Sample data: 252 trading days, seeded random walk

Rank	Symbol	Name	Score	Selected
#1	TSLA	Tesla Inc.	22.7286	Top 5
#2	MSFT	Microsoft Corp.	9.1736	Top 5
#3	GOOGL	Alphabet Inc.	4.1126	Top 5
#4	META	Meta Platforms Inc.	2.0901	Top 5
#5	NVDA	NVIDIA Corp.	0.8989	Top 5
#6	JPM	JPMorgan Chase & Co.	-0.1532	Excluded
#7	AMZN	Amazon.com Inc.	-2.0967	Excluded
#8	AAPL	Apple Inc.	-2.1140	Excluded
#9	JNJ	Johnson & Johnson	-2.1368	Excluded
#10	V	Visa Inc.	-5.6223	Excluded

When to Use

Use when you believe recent winners will continue to outperform. Standard in cross-sectional momentum strategies.

Code Example

from tradepilot.ranking import momentum_ranking

scores = momentum_ranking(prices, t=10)
# Returns pd.Series with momentum scores per asset
# Simulator selects top N by descending score

Random Ranking

Assigns random scores to each asset — useful for testing, benchmarking, and Monte Carlo simulations.

Formula

Score(i) = random()  ∈ [0, 1)

Each asset gets a uniform random value. Optional seed parameter for reproducibility.

Parameters

Name	Type	Default	Description
`prices`	`DataFrame`	`—`	DataFrame of historical prices (only used for column names)
`seed`	`int \| None`	`None`	Random seed for reproducibility

How It Works

Uses numpy random to generate a random score for each asset column. With a fixed seed, produces reproducible rankings for testing.

Live Demo — 10 Stocks Ranked

Sample data: 252 trading days, seeded random walk

Rank	Symbol	Name	Score	Selected
#1	META	Meta Platforms Inc.	0.9759	Top 5
#2	GOOGL	Alphabet Inc.	0.7354	Top 5
#3	V	Visa Inc.	0.5304	Top 5
#4	MSFT	Microsoft Corp.	0.5246	Top 5
#5	JPM	JPMorgan Chase & Co.	0.5123	Top 5
#6	TSLA	Tesla Inc.	0.3762	Excluded
#7	AMZN	Amazon.com Inc.	0.2633	Excluded
#8	JNJ	Johnson & Johnson	0.2571	Excluded
#9	NVDA	NVIDIA Corp.	0.1963	Excluded
#10	AAPL	Apple Inc.	0.0003	Excluded

When to Use

Use as a baseline benchmark to verify that your real strategy outperforms random selection. Essential for statistical significance testing.

Code Example

from tradepilot.ranking import random_ranking

scores = random_ranking(prices, seed=42)
# Returns pd.Series with random scores [0, 1)
# Use seed for reproducible results

VaR Ranking

Ranks assets by historic Value at Risk — lower VaR means lower risk. Selects the safest assets first.

Formula

Score(i) = VaR_historic(i, t, level)

VaR is the loss threshold such that only `level`% of returns fall below it. Lower VaR = less risky = ranked first.

Parameters

Name	Type	Default	Description
`prices`	`DataFrame`	`—`	DataFrame of historical prices
`t`	`int`	`100`	Number of past periods to consider (0 = all)
`level`	`int`	`5`	Percentile level for VaR calculation

How It Works

Converts prices to returns, then computes the historic VaR at the given percentile for each asset. Assets with lower VaR (less risk) are preferred. The simulator sorts ascending to select lowest-risk assets.

Live Demo — 10 Stocks Ranked

Sample data: 252 trading days, seeded random walk

Rank	Symbol	Name	Score	Selected
#1	V	Visa Inc.	0.0140	Top 5
#2	JPM	JPMorgan Chase & Co.	0.0141	Top 5
#3	META	Meta Platforms Inc.	0.0156	Top 5
#4	GOOGL	Alphabet Inc.	0.0179	Top 5
#5	JNJ	Johnson & Johnson	0.0180	Top 5
#6	NVDA	NVIDIA Corp.	0.0184	Excluded
#7	AAPL	Apple Inc.	0.0186	Excluded
#8	MSFT	Microsoft Corp.	0.0192	Excluded
#9	AMZN	Amazon.com Inc.	0.0200	Excluded
#10	TSLA	Tesla Inc.	0.0353	Excluded

When to Use

Use for risk-averse portfolio construction. Prioritizes capital preservation by selecting assets with the smallest tail risk.

Code Example

from tradepilot.ranking import var_ranking

scores = var_ranking(prices, t=100, level=5)
# Returns pd.Series with VaR values per asset
# Lower VaR = less risky = ranked first