predict — Number-generation strategies¶
Strategies are pure-injection: declared via the needs_history / method / aliases class attributes and auto-registered by the base __init_subclass__; the load_predict_numbers factory resolves them and injects history data.
For entertainment only — no predictive power
Lottery draws are independent random events; every strategy has exactly the same expected value as the random baseline.
predict ¶
选号策略集（娱乐与教学用途）。
仅供娱乐，不构成任何预测力
彩票开奖为独立随机事件，以下任何策略都不具备真实预测力，任何一注号码的
中奖概率与随机选号完全相同。本模块仅提供统计选号参考与教学示例；
random 为基线策略，任何策略都应先与它对比（可用 lotterycn.backtest
复现实验）。请理性购彩。
策略来源（社区彩票圈/股票分析框架的平移，均无真实预测力）： 随机基线 random 走势图派 frequency（冷热）、omission（遗漏回补）、tail（尾数）、trend（和值均线通道） 形态派 filter（奇偶/大小/质合/012路/三区比/AC值/连号/杀号 可组合缩水） 序列派 markov（一阶）、markov2（二阶，稀疏性教学）、repeat（重号/邻号/斜连号） 统计派 deviation（卡方偏离度） 集成派 ensemble（多策略投票）
设计约定：策略类是"纯注入"的——构造器不做任何网络 IO，历史数据由
load_predict_numbers 工厂统一解析并注入（子类通过 needs_history
声明是否依赖历史，通过 aliases 声明别名，两者均由基类自动注册）。
需要历史数据的子类调用 self._require_history()。
Classes¶
BasePredictor ¶
策略基类（纯注入，构造器零 IO，torch Layer 风格）。
子类声明三个类属性，注册由基类 __init_subclass__ 自动完成：
needs_history — 是否依赖历史数据（工厂据此决定是否联网拉取并注入）；
method — 输出 DataFrame 的 method 列标签，同时作为注册键；
aliases — 别名 → 策略参数覆盖（可选）。
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lottery_name
|
str
|
str, must in NUMBER_POOLS. |
'ssq'
|
history
|
Optional[DataFrame]
|
pandas.DataFrame, 历史开奖数据；由工厂注入或调用方显式传入。 不依赖历史的子类（needs_history = False）可为 None。 |
None
|
RandomPredictor ¶
Bases: BasePredictor
基线策略：均匀随机（等价 load_random_data）。
FrequencyPredictor ¶
FrequencyPredictor(lottery_name: str = 'ssq', history: Optional[DataFrame] = None, recent_n: Optional[int] = None, mode: str = 'hot', explore_ratio: float = 0.5)
Bases: BasePredictor
冷热号策略（动量）：按近 N 期出现频率取号。
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
recent_n
|
Optional[int]
|
int, 滑动窗口期数，None 表示全历史。 |
None
|
mode
|
str
|
str, 'hot' 取高频头部，'cold' 取低频头部。 |
'hot'
|
explore_ratio
|
float
|
float, 0~1。0 为确定性取头部 k 个；越大越随机。 |
0.5
|
OmissionPredictor ¶
OmissionPredictor(lottery_name: str = 'ssq', history: Optional[DataFrame] = None, recent_n: Optional[int] = None, explore_ratio: float = 0.5)
Bases: BasePredictor
遗漏回补策略（均值回归）：按"当前遗漏 / 平均遗漏"的偏移度取号。
直觉：某号码当前连续未出期数远超其历史平均遗漏时，社区称之为"遗漏 回补"。数学真相：独立开奖下这仍是均匀抽样的另一种表达，不改变概率。
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
recent_n
|
Optional[int]
|
int, 计算平均遗漏的窗口期数，None 表示全历史。 |
None
|
DeviationPredictor ¶
DeviationPredictor(lottery_name: str = 'ssq', history: Optional[DataFrame] = None, recent_n: Optional[int] = None, side: str = 'hot', explore_ratio: float = 0.5)
Bases: BasePredictor
卡方偏离度策略：按 (实际频次 - 期望频次)² / 期望频次 取号。
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
recent_n
|
Optional[int]
|
int, 窗口期数，None 表示全历史。 |
None
|
side
|
str
|
str, 'hot' 取正偏离头部（实际多于期望），'cold' 取负偏离头部。 |
'hot'
|
RepeatNeighborPredictor ¶
RepeatNeighborPredictor(lottery_name: str = 'ssq', history: Optional[DataFrame] = None, repeat_weight: float = 2.0, neighbor_weight: float = 1.0, jump_weight: float = 1.0, explore_ratio: float = 0.5)
Bases: BasePredictor
重号/邻号/斜连号策略：按与最近两期号码的邻近关系打分。
score(n) = repeat_weight·[n ∈ 上期] + neighbor_weight·[n 与上期某号相差 1] + jump_weight·[n 与上上期某号相差 1]（斜连号）。
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
repeat_weight
|
float
|
float, 重号权重。 |
2.0
|
neighbor_weight
|
float
|
float, 邻号权重。 |
1.0
|
jump_weight
|
float
|
float, 斜连号（上上期 ±1）权重。 |
1.0
|
TrendPredictor ¶
TrendPredictor(lottery_name: str = 'ssq', history: Optional[DataFrame] = None, window: int = 10, k_sigma: float = 1.0, max_trials: int = 10000)
Bases: BasePredictor
和值均线通道策略（股票均线框架平移）：按和值的 MA ± k·σ 生成和值带。
随机候选的和值落入带内才保留。数学真相：和值序列无趋势， 带只是历史分布的描述。
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
window
|
int
|
int, 均线与波动率计算的窗口期数。 |
10
|
k_sigma
|
float
|
float, 通道宽度系数（MA ± k·σ）。 |
1.0
|
max_trials
|
int
|
int, 最大尝试次数。 |
10000
|
TailPredictor ¶
TailPredictor(lottery_name: str = 'ssq', history: Optional[DataFrame] = None, recent_n: Optional[int] = None, mode: str = 'hot', explore_ratio: float = 0.5, tail_count: Optional[int] = None)
Bases: BasePredictor
尾数策略：先按尾数（号码 % 10）频率选尾集合，再在选中尾内取号。
仅作用于红球/前区；蓝球按普通频率取号。数字型彩种每位 0-9， 尾即号码本身，策略退化为号码级频率。
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tail_count
|
Optional[int]
|
int, 选用的尾数个数；None 时按号码池与注数自动推导。 |
None
|
MarkovPredictor ¶
Bases: BasePredictor
一阶马尔可夫策略：按 P(本期出现 | 上期出现/未出现) 的转移概率采样。
教学要点：对独立开奖，转移概率收敛到边际频率，本策略退化为频率法， 用于直观验证"历史模式无预测力"。
Markov2Predictor ¶
Bases: BasePredictor
二阶马尔可夫策略：状态为上两期的出现/未出现组合（4 态）。
教学要点：样本在高阶状态下迅速稀疏，Laplace 平滑后大量状态退化为 均匀分布——直观展示"历史模式越复杂，越接近随机"。
FilterPredictor ¶
FilterPredictor(lottery_name: str = 'ssq', history: Optional[DataFrame] = None, sum_range=None, odd_range=None, prime_range=None, zone_ratio=None, mod3_range=None, ac_range=None, consecutive_range=None, exclude_numbers=None, max_trials: int = 10000)
Bases: BasePredictor
形态缩水策略：批量随机候选，按多组形态约束过滤。
注意：过滤只改变选号的分布形态，不改变任何一注的中奖概率。
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sum_range
|
tuple, 红球和值区间 (lo, hi)，None 不过滤。 |
None
|
|
odd_range
|
tuple, 红球奇数个数区间 (lo, hi)，None 不过滤。 |
None
|
|
prime_range
|
tuple, 红球质数个数区间 (lo, hi)，None 不过滤。 |
None
|
|
zone_ratio
|
tuple, 三区比（红球按号码池三等分的分布），精确匹配，如 (2, 2, 2)。 |
None
|
|
mod3_range
|
tuple, 012 路分布（号码 % 3 的计数），精确匹配，如 (1, 3, 2)。 |
None
|
|
ac_range
|
tuple, AC 值区间 (lo, hi)，None 不过滤。 |
None
|
|
consecutive_range
|
tuple, 连号对数区间 (lo, hi)，None 不过滤。 |
None
|
|
exclude_numbers
|
iterable, 杀号集合（命中的候选直接淘汰）。 |
None
|
|
max_trials
|
int
|
int, 最大尝试次数，防止过滤条件过严导致死循环。 |
10000
|
EnsemblePredictor ¶
EnsemblePredictor(lottery_name: str = 'ssq', history: Optional[DataFrame] = None, members: tuple = ('frequency', 'omission', 'repeat'), votes_min: int = 1)
Bases: BasePredictor
集成投票策略：多个子策略各出 top-k，按号码得票数取前 k。
集成不改变期望——各子策略无预测力，投票亦然；提供它是为了 把"多策略共振"这一社区习惯变成可复现的实验。
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
members
|
tuple
|
tuple, 子策略 method 名（不能含 'ensemble'，避免递归）。 |
('frequency', 'omission', 'repeat')
|
votes_min
|
int
|
int, 入选号码的最少得票数；不足 k 个时按票数补齐。 |
1
|
Functions:¶
load_predict_numbers ¶
load_predict_numbers(lottery_name: str = 'ssq', method: str = 'random', amount: int = 1, history: Optional[DataFrame] = None, **kwargs) -> DataFrame
Generate numbers with a strategy. Output mirrors load_random_data
(plus a method column).
⚠️ Entertainment only — every strategy has exactly the same expected value
as the random baseline (verify with lotterycn.backtest).
中文说明
按指定策略生成选号。可用策略：random 基线 / frequency 冷热（别名
hot/cold）/ omission 遗漏回补（chase）/ deviation 卡方偏离（chisq）/
repeat 重邻斜 / trend 和值均线 / tail 尾数 / markov / markov2 /
filter 形态缩水（和值/奇偶/质合/三区/012路/AC值/连号/杀号）/
ensemble 多策略投票。history= 注入 DataFrame 可完全离线；
否则按需拉取（支持 if_cached）。
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lottery_name
|
str
|
str, must in ('ssq', 'qlc', 'kl8', '3d', 'dlt', 'pls', 'plw', 'qxc'). |
'ssq'
|
method
|
str
|
str, 'random' | 'frequency'（别名 'hot'/'cold'）| 'omission'（'chase'） | 'deviation'（'chisq'）| 'repeat' | 'trend' | 'tail' | 'markov' | 'markov2' | 'filter' | 'ensemble'. |
'random'
|
amount
|
int
|
int, 生成注数，default 1. |
1
|
history
|
Optional[DataFrame]
|
pandas.DataFrame, 显式注入历史数据（离线使用）；为 None 且策略 需要历史时按 **kwargs 中的数据获取参数联网拉取。 |
None
|
**kwargs
|
两类参数—— 策略参数：recent_n / mode / explore_ratio（frequency/omission/deviation/tail）， repeat_weight / neighbor_weight / jump_weight（repeat）， window / k_sigma（trend），members / votes_min（ensemble）， sum_range / odd_range / prime_range / zone_ratio / mod3_range / ac_range / consecutive_range / exclude_numbers / max_trials（filter）； 数据获取参数（仅拉取时生效）：if_cached / timeout / proxies / max_retries 等。 |
{}
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame |