czsc 信号函数实战:bar_end_V221211 大周期 K 线闭合判定全解析
czsc 信号函数实战:bar_end_V221211 大周期 K 线闭合判定全解析
本篇技术指南围绕 czsc 缠论量化工具中的
bar_end_V221211信号函数展开,讲解它如何以基础周期(如 15 分钟)K 线为输入,判断目标大周期(如 60 分钟)K 线是否已经闭合,以及闭合前已累计多少根同周期 K 线。读完本文,你将掌握该信号的参数模板、命名规则、判定逻辑与 Rust 源码实现细节,并了解它在 A 股分钟数据下的边界行为,可直接用于信号组合与策略构建。
一、信号概览:模块归属与命名规范
bar_end_V221211 是 czsc 信号体系中 kline(K 线)类别的信号,实现在 crates/czsc-signals/src/bar.rs 中,与 bar_single_V230506、bar_zdt_V230331、bar_triple_V230506、bar_vol_grow_V221112 等一批裸 K 线/量价信号同处一个模块。它的用途非常聚焦:判断大周期 K 线是否闭合。
从信号命名可以看出 czsc 的约定:
bar:作用于 K 线(bar)级别;end:表达"结束/闭合"语义;V221211:版本号,表示该信号逻辑定型于 2022-12-11,后续迭代会以新的版本号命名(例如模块内bar_operate_span_V221111、bar_time_V230327等均为不同版本演进)。
该信号在 crates/czsc-signals/src/registry.rs 的信号注册表中登记("bar_end_V221211"),意味着它可以被信号调度与组合系统统一识别、加载和回放。
二、参数模板与信号命名解析
bar_end_V221211 的参数模板为:
{freq}_{freq1}结束_BS辅助221211
其中:
freq:当前分析使用的基础周期,来自CZSC对象(例如15分钟),由信号框架自动注入,无需手动配置;freq1:目标分钟周期,即要判断"是否闭合"的大周期,默认60分钟;结束:模板中固定的中文关键词段;BS辅助221211:辅助标识段,BS为买卖(Buy/Sell)辅助语义,221211为版本号。
信号输出为 czsc 标准的 7 段格式(由 make_signal7 统一构造):
{周期}_{因子}_{辅助}_{值1}_{值2}_{值3}_{评分}
bar_end_V221211 只占用值 1(v1)字段,值 2、值 3 固定为 任意,评分为 0。对应关系为:
| 段位 | 取值 | 说明 |
|---|---|---|
| 周期 | 15分钟 等 |
基础周期 freq |
| 因子 | 60分钟结束 |
{freq1}结束 |
| 辅助 | BS辅助221211 |
版本标识 |
| 值1 | 闭合 / 未闭{i} |
闭合状态判定结果 |
| 值2 | 任意 |
固定 |
| 值3 | 任意 |
固定 |
| 评分 | 0 |
固定 |
三、信号逻辑:三步判定大周期 K 线是否闭合
原文档给出了完整的判定流程,共三步:
- 计算结束时间:以当前基础周期
freq与目标分钟周期freq1,计算当前 K 线对应的"结束时间"c1_dt; - 统计连续数量:从最新 K 线向前(时间倒序)统计同属该结束时间的连续 K 线数量
i; - 判定状态:若
end_time == last_dt,即最新一根 K 线的自身时间恰好等于该大周期的结束时间,则判定为闭合;否则判定为未闭{i},其中{i}就是第 2 步统计到的连续同周期 K 线数量。
结合 crates/czsc-signals/src/bar.rs 的 Rust 实现,可以看到更具体的执行细节:
let freq1 = params.str("freq1", "60分钟");
let k1 = c.freq.to_string();
let k2 = format!("{freq1}结束");
let k3 = "BS辅助221211";
if !freq1.contains("分钟") || c.bars_raw.is_empty() {
return make_kline_signal_v1(&k1, &k2, &k3, "其他");
}
let last_dt = c.bars_raw.last().map(|x| x.dt).unwrap();
let Some(c1_dt) = minute_freq_end_time(last_dt, freq1) else {
return vec![];
};
let mut i = 0usize;
for bar in c.bars_raw.iter().rev() {
let Some(edt) = minute_freq_end_time(bar.dt, freq1) else {
break;
};
if edt != c1_dt {
break;
}
i += 1;
}
let v1 = if c1_dt == last_dt {
"闭合".to_string()
} else {
format!("未闭{i}")
};
make_kline_signal_v1(&k1, &k2, &k3, &v1)
3.1 两个前置守卫
实现开头的两处判断决定了信号的降级行为:
freq1不是分钟周期或数据为空:freq1字符串中不含分钟字样,或bars_raw为空时,直接输出其他(make_kline_signal_v1会将值 1 置为其他)。这保证了模板约束——freq1必须是分钟级别周期。- 结束时间计算失败:
minute_freq_end_time返回None时,函数返回空向量vec![],即该时刻不产生任何信号。从源码结构看,这一分支主要面向 30/60 分钟周期在非标准交易时点(详见下文第四节)的情况。
3.2 未闭计数的统计口径
i 的统计方式是核心语义:从最新一根 K 线开始,按时间倒序(iter().rev())逐根计算其对应的结束时间,只要与当前大周期结束时间 c1_dt 一致就继续累加,遇到不一致或计算失败即中断。因此 未闭{i} 中的 i 表示:在当前未闭合的大周期 K 线内,已经落入了 i 根基础周期 K 线。
例如 15分钟_60分钟结束_BS辅助221211_未闭2_任意_任意_0 表示:当前 60 分钟 K 线尚未到收盘时间点,但已经积累了 2 根 15 分钟 K 线(即该 60 分钟区间已走过约 30 分钟)。
3.3 闭合的判定标准
闭合 的判定条件是 c1_dt == last_dt,即最新一根基础周期 K 线的自身时间戳恰好等于该大周期的结束时间点。这等价于"最新 K 线正好收在大周期收盘边界上",例如 60 分钟周期下最新 15 分钟 K 线恰好收在 10:30、11:30、14:00 或 15:00。
四、分钟周期结束时间的计算原理
判定是否闭合的核心依赖工具函数 minute_freq_end_time。它先通过 parse_minute_freq 把 60分钟 解析为分钟数 60,随后分两条路径计算:
4.1 A 股特殊时点映射(30 分钟与 60 分钟)
代码注释明确说明,该函数与 Python 版 freq_end_time(..., market="A股") 对齐——A 股分钟数据在 09:30、13:30 等边界点不是简单的整除向上取整,因此对 30 分钟、60 分钟两种周期内置了映射表:
| 目标周期 | 输入时间(HH:MM) | 映射结束时间 |
|---|---|---|
| 30分钟 | 09:30、10:00 | 10:00 |
| 30分钟 | 10:30 | 10:30 |
| 30分钟 | 11:00 | 11:00 |
| 30分钟 | 11:30 | 11:30 |
| 30分钟 | 13:30 | 13:30 |
| 30分钟 | 14:00 | 14:00 |
| 30分钟 | 14:30 | 14:30 |
| 30分钟 | 15:00 | 15:00 |
| 60分钟 | 09:30、10:00、10:30 | 10:30 |
| 60分钟 | 11:00、11:30 | 11:30 |
| 60分钟 | 13:30、14:00 | 14:00 |
| 60分钟 | 14:30、15:00 | 15:00 |
不在映射表中的时间点(如 10:15 计算 60 分钟结束时间)返回 None——这正是 bar_end_v221211 中"返回空向量"分支的触发场景。从源码结构可以推断,A 股每个 60 分钟交易时段由 4 根 15 分钟 K 线组成(09:30–10:30、10:30–11:30、13:30–14:00、14:00–15:00),而 30 分钟时段为 2 根 15 分钟 K 线(09:30–10:00、10:00–10:30……),映射表正是对这一交易结构的显式编码。
4.2 通用分钟周期计算
对非 30/60 分钟的其他分钟周期(如 5分钟、15分钟、120分钟),走通用公式:
end_hm = hm % m == 0 ? hm : (hm / m + 1) * m
即:若当前时刻恰好是整段边界,结束时间就是自身;否则向上取整到下一个整段边界;若结果达到或超过 24:00(end_hm >= 24*60),则减去 24 小时并顺延到次日。这保证跨日场景下结束时间仍落在正确的自然日上。
五、参数说明与配置方式
bar_end_V221211 仅有一个可配置参数:
| 参数 | 含义 | 默认值 | 约束 |
|---|---|---|---|
freq1 |
目标分钟周期(大周期) | 60分钟 |
字符串必须包含 分钟,否则信号降级为 其他 |
freq1 通过 ParamView 读取(params.str("freq1", "60分钟")),ParamView 是 czsc 信号框架统一的参数视图,参数可从信号模板字符串或外部配置注入。基础周期 freq 不开放配置,直接取自 CZSC 对象的 freq 字段。
实际使用中常见组合:
15分钟基础周期 +60分钟目标周期:用于日内的 60 分钟级别 K 线闭合判断;5分钟基础周期 +30分钟目标周期:更细粒度地捕捉 30 分钟收盘时点。
六、信号列表示例
以下两个示例摘自原文档,均为合法的 7 段信号:
Signal('15分钟_60分钟结束_BS辅助221211_闭合_任意_任意_0')
Signal('15分钟_60分钟结束_BS辅助221211_未闭2_任意_任意_0')
第一个表示最新 15 分钟 K 线恰好收在 60 分钟结束点(10:30/11:30/14:00/15:00 之一),60 分钟 K 线闭合;第二个表示 60 分钟 K 线尚未闭合,但已累计 2 根 15 分钟 K 线。
七、与 Python 版本的对齐说明
原文档特别强调:闭合/未闭计数语义与 Python bar_end_V221211 保持一致。这是 czsc 双语言(Python 参考实现 + Rust 原生实现)架构下的关键约定——Rust 侧的 minute_freq_end_time 在 utils/sig.rs 中明确标注了与 Python freq_end_time(..., market="A股") 的口径对齐,包括 30/60 分钟映射表与通用整除取整两种路径;计数逻辑(倒序遍历、遇到异周期即断)也与 Python 行为逐行对应。因此同一份参数模板与数据在 Python 与 Rust 两侧会得到完全一致的信号值,这为跨语言回测与结果复现提供了保证。
八、使用注意事项
- 数据量要求:
bar_end_V221211对 K 线数量本身没有硬性下限,只要bars_raw非空即可计算,但未闭{i}的计数准确性依赖完整的基础周期数据序列;若数据缺失导致同周期 K 线不连续,计数会提前中断。 - 仅支持分钟级
freq1:freq1必须是分钟周期字符串,若传入日线等非分钟周期,信号会降级为其他。 - 非标准时点无信号:当
freq1为 30/60 分钟且最新 K 线时间不在映射表覆盖范围内时,返回空向量(不产生信号),这在信号聚合时表现为该时刻没有bar_end_V221211输出,属预期行为。 - 典型应用场景:该信号适合作为时间过滤/择时辅助——在
闭合出现时触发大周期级别的交易确认,在未闭{i}阶段用于仓位管理或避免在大周期未收盘时提前行动。
九、快速参考
| 项目 | 内容 |
|---|---|
| 信号名 | bar_end_V221211 |
| 模块 | crates/czsc-signals/src/bar.rs |
| 类别 | kline |
| 参数模板 | {freq}_{freq1}结束_BS辅助221211 |
| 参数 | freq1(默认 60分钟) |
| 输出值 | 闭合 / 未闭{i} / 其他(空数据或非法参数时) |
| 版本标识 | V221211(2022-12-11 定型) |
参考文档:.claude/skills/signal-functions/references/signals/bar_end_V221211.md,信号注册见 crates/czsc-signals/src/registry.rs。