V0.9.64 更新一批代码 (#224)

* 0.9.64 start coding

* 0.9.64 新增两个 streamlit 组件

* Add show_returns_contribution Streamlit component for strategy returns analysis

* 优化 show_returns_contribution 组件，增加图表标题和说明

* 0.9.64 新增两个组件

* 优化图表布局，修复函数名拼写错误，更新示例代码以展示因子值可视化

* Refactor seasonal effect component to quarterly effect and update example for improved outsample comparison

* update

* Add cumulative returns visualization and new trading time function; refactor trade price calculation

* Add Streamlit example for incremental line chart updates with random data

* 优化季度效果展示函数，更新统计信息的显示方式，调整图表布局以提升可读性

* 更新代码注释，优化函数参数类型，移除过时函数，增加新函数以获取分钟线数据

* 标记函数subtract_fee为过时，建议使用rs_czsc.WeightBacktest替代以支持扣费

* 更新README.md，突出项目贡献部分的链接，调整Python版本要求为3.8及以上，并新增使用案例部分以提供更多参考资料。

* 移除过时的cal_trade_price函数，并在相关模块中重新导入以保持功能完整性

* 修正测试任务中的路径，更新pytest命令以指向正确的测试目录；移除过时的bar_cross_ps_V221112函数；调整测试数据构造方式以提高可读性和准确性。

* 修正测试文件中的权重计算，将权重值从整数更改为浮点数；更新交易价格计算测试，调整相关断言以匹配新计算结果。

Author: zengbin93

.github/workflows/pythonpackage.yml

@@ -5,7 +5,7 @@ name: Python package
 
 on:
   push:
-    branches: [ master, 'V0.9.63' ]
+    branches: [ master, 'V0.9.64' ]
   pull_request:
     branches: [ master ]
 

.vscode/settings.json

@@ -17,5 +17,5 @@
         "120"
     ],
     "typescript.locale": "zh-CN",
-    "python.analysis.typeCheckingMode": "basic",
+    "python.analysis.typeCheckingMode": "basic"
 }

.vscode/tasks.json

@@ -0,0 +1,38 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "运行所有测试",
+            "type": "shell",
+            "command": "python -m pytest test -v",
+            "group": {
+                "kind": "test",
+                "isDefault": true
+            },
+            "presentation": {
+                "reveal": "always",
+                "panel": "new"
+            }
+        },
+        {
+            "label": "运行当前测试文件",
+            "type": "shell",
+            "command": "python -m pytest ${file} -v",
+            "group": "test",
+            "presentation": {
+                "reveal": "always",
+                "panel": "new"
+            }
+        },
+        {
+            "label": "运行带覆盖率报告的测试",
+            "type": "shell",
+            "command": "python -m pytest test -v --cov=czsc --cov-report=html",
+            "group": "test",
+            "presentation": {
+                "reveal": "always",
+                "panel": "new"
+            }
+        }
+    ]
+} 

README.md

@@ -37,17 +37,17 @@
 
 ## 项目贡献
 
-* [择时策略研究框架](https://s0cqcxuy3p.feishu.cn/wiki/wikcnhizrtIOQakwVcZLMKJNaib)
+* **[择时策略研究框架](https://s0cqcxuy3p.feishu.cn/wiki/wikcnhizrtIOQakwVcZLMKJNaib)**
 * 缠论的 `分型、笔` 的自动识别，详见 `czsc/analyze.py`
 * 定义并实现 `信号-因子-事件-交易` 量化交易逻辑体系，因子是信号的线性组合，事件是因子的同类合并，详见 `czsc/objects.py`
 * 定义并实现了若干信号函数，详见 `czsc/signals`
 * 缠论多级别联立决策分析交易，详见 `CzscTrader`
-* [Streamlit 量化研究组件库](https://s0cqcxuy3p.feishu.cn/wiki/AATuw5vN7iN9XbkVPuwcE186n9f)
+* **[Streamlit 量化研究组件库](https://s0cqcxuy3p.feishu.cn/wiki/AATuw5vN7iN9XbkVPuwcE186n9f)**
 
 
 ## 安装使用
 
-**注意:** python 版本必须大于等于 3.7
+**注意:** python 版本必须大于等于 3.8
 
 直接从github安装：
 ```
@@ -64,6 +64,13 @@ pip install git+https://github.com/waditu/[email protected] -U
 pip install czsc -U -i https://pypi.python.org/simple
 ```
 
+## 使用案例
+
+1. [使用 tqsdk 进行期货交易](https://s0cqcxuy3p.feishu.cn/wiki/wikcn41lQIAJ1f8v41Dj5eAmrub)
+2. [CTA择时：缠论30分钟笔非多即空](https://s0cqcxuy3p.feishu.cn/wiki/YPlewoj70ikwxakPnOucTP8lnYg)
+3. [使用CTA研究UI页面进行策略研究](https://s0cqcxuy3p.feishu.cn/wiki/JWe3wo1VNiglO9kE999cGy8innh)
+
+
 ## 使用前必看
 
 * 目前的开发还在高频次的迭代中，对于已经在使用某个版本的用户，请谨慎更新，版本兼容性实在是太差，主要是因为当前还有太多考虑不完善的地方，我为此感到抱歉；

czsc/__init__.py

@@ -85,7 +85,6 @@
     x_round,
     import_by_name,
     create_grid_params,
-    cal_trade_price,
     update_bbars,
     update_tbars,
     update_nxb,
@@ -170,6 +169,12 @@
     show_df_describe,
     show_date_effect,
     show_weight_distribution,
+    show_normality_check,
+    show_outsample_by_dailys,
+    show_returns_contribution,
+    show_symbols_bench,
+    show_quarterly_effect,
+    show_cumulative_returns,
 )
 
 from czsc.utils.bi_info import (
@@ -223,13 +228,14 @@
     dif_long_bear,
     tsf_type,
     limit_leverage,
+    cal_trade_price,
 )
 
 
-__version__ = "0.9.63"
+__version__ = "0.9.64"
 __author__ = "zengbin93"
 __email__ = "[email protected]"
-__date__ = "20250101"
+__date__ = "20250224"
 
 
 def welcome():

czsc/connectors/cooperation.py

@@ -145,25 +145,6 @@ def get_raw_bars(symbol, freq, sdt, edt, fq="前复权", **kwargs):
     sdt = pd.to_datetime(sdt).strftime("%Y%m%d")
     edt = pd.to_datetime(edt).strftime("%Y%m%d")
 
-    if "SH" in symbol or "SZ" in symbol:
-        fq_map = {"前复权": "qfq", "后复权": "hfq", "不复权": None}
-        adj = fq_map.get(fq, None)
-
-        code, asset = symbol.split("#")
-
-        if freq.value.endswith("分钟"):
-            df = dc.pro_bar(code=code, sdt=sdt, edt=edt, freq="min", adj=adj, asset=asset[0].lower(), v=2, ttl=ttl)
-            df = df[~df["dt"].str.endswith("09:30:00")].reset_index(drop=True)
-            df.rename(columns={"code": "symbol"}, inplace=True)
-            df["dt"] = pd.to_datetime(df["dt"])
-            return czsc.resample_bars(df, target_freq=freq, raw_bars=raw_bars, base_freq="1分钟")
-
-        else:
-            df = dc.pro_bar(code=code, sdt=sdt, edt=edt, freq="day", adj=adj, asset=asset[0].lower(), v=2, ttl=ttl)
-            df.rename(columns={"code": "symbol"}, inplace=True)
-            df["dt"] = pd.to_datetime(df["dt"])
-            return czsc.resample_bars(df, target_freq=freq, raw_bars=raw_bars)
-
     if symbol.endswith("9001"):
         # https://s0cqcxuy3p.feishu.cn/wiki/WLGQwJLWQiWPCZkPV7Xc3L1engg
         if fq == "前复权":
@@ -203,6 +184,25 @@ def get_raw_bars(symbol, freq, sdt, edt, fq="前复权", **kwargs):
         df["dt"] = pd.to_datetime(df["dt"])
         return czsc.resample_bars(df, target_freq=freq, raw_bars=raw_bars)
 
+    if "SH" in symbol or "SZ" in symbol:
+        fq_map = {"前复权": "qfq", "后复权": "hfq", "不复权": None}
+        adj = fq_map.get(fq, None)
+
+        code, asset = symbol.split("#")
+
+        if freq.value.endswith("分钟"):
+            df = dc.pro_bar(code=code, sdt=sdt, edt=edt, freq="min", adj=adj, asset=asset[0].lower(), v=2, ttl=ttl)
+            df = df[~df["dt"].str.endswith("09:30:00")].reset_index(drop=True)
+            df.rename(columns={"code": "symbol"}, inplace=True)
+            df["dt"] = pd.to_datetime(df["dt"])
+            return czsc.resample_bars(df, target_freq=freq, raw_bars=raw_bars, base_freq="1分钟")
+
+        else:
+            df = dc.pro_bar(code=code, sdt=sdt, edt=edt, freq="day", adj=adj, asset=asset[0].lower(), v=2, ttl=ttl)
+            df.rename(columns={"code": "symbol"}, inplace=True)
+            df["dt"] = pd.to_datetime(df["dt"])
+            return czsc.resample_bars(df, target_freq=freq, raw_bars=raw_bars)
+
     raise ValueError(f"symbol {symbol} 无法识别，获取数据失败！")
 
 

czsc/connectors/qmt_connector.py

@@ -372,6 +372,16 @@ def is_trade_time(dt: datetime = datetime.now()):
         return True
 
 
+def is_stock_trade_time(dt: datetime = datetime.now()):
+    """判断指定时间是否是股票交易时间"""
+    hm = dt.strftime("%H:%M")
+    if "09:30" <= hm < "11:30":
+        return True
+    if "13:00" <= hm < "15:00":
+        return True
+    return False
+
+
 def is_trade_day(dt: datetime = datetime.now()):
     """判断指定日期是否是交易日"""
     date = dt.strftime("%Y%m%d")

czsc/connectors/ts_connector.py

@@ -77,8 +77,8 @@ def get_daily_basic(sdt="20100101", edt="20240101"):
 
     https://s0cqcxuy3p.feishu.cn/wiki/W5UYwk0qwiHWlxk2ngDcjxQKncg
     """
-    sdt = pd.to_datetime(sdt).strftime("%Y%m%d")
-    edt = pd.to_datetime(edt).strftime("%Y%m%d")
+    sdt = pd.to_datetime(sdt)
+    edt = pd.to_datetime(edt)
 
     dates = czsc.get_trading_dates(sdt, edt)
     rows = []
@@ -129,6 +129,109 @@ def moneyflow_hsgt(start_date, end_date):
     return df
 
 
+def pro_bar_minutes(ts_code, sdt, edt, freq="60min", asset="E", adj=None):
+    """获取分钟线
+
+    https://tushare.pro/document/2?doc_id=109
+
+    :param ts_code: 标的代码
+    :param sdt: 开始时间，精确到分钟
+    :param edt: 结束时间，精确到分钟
+    :param freq: 分钟周期，可选值 1min, 5min, 15min, 30min, 60min
+    :param asset: 资产类别：E股票 I沪深指数 C数字货币 FT期货 FD基金 O期权 CB可转债（v1.2.39），默认E
+    :param adj: 复权类型，None不复权，qfq:前复权，hfq:后复权
+    :param raw_bar: 是否返回 RawBar 对象列表
+    :return:
+    """
+    import tushare as ts
+    from datetime import timedelta
+    pro = dc
+
+    dt_fmt = "%Y%m%d"
+
+    sdt = pd.to_datetime(sdt).strftime(dt_fmt)
+    edt = pd.to_datetime(edt).strftime(dt_fmt)
+
+    klines = []
+    end_dt = pd.to_datetime(edt)
+    dt1 = pd.to_datetime(sdt)
+    delta = timedelta(days=20 * int(freq.replace("min", "")))
+    dt2 = dt1 + delta
+    while dt1 < end_dt:
+        df = ts.pro_bar(
+            ts_code=ts_code,
+            asset=asset,
+            freq=freq,
+            start_date=dt1.strftime(dt_fmt),
+            end_date=dt2.strftime(dt_fmt),
+        )
+        klines.append(df)
+        dt1 = dt2
+        dt2 = dt1 + delta
+        print(f"pro_bar_minutes: {ts_code} - {asset} - {freq} - {dt1} - {dt2} - {len(df)}")
+
+    df_klines = pd.concat(klines, ignore_index=True)
+    kline = df_klines.drop_duplicates("trade_time").sort_values("trade_time", ascending=True, ignore_index=True)
+    kline["trade_time"] = pd.to_datetime(kline["trade_time"], format=dt_fmt)
+    kline["dt"] = kline["trade_time"]
+    float_cols = ["open", "close", "high", "low", "vol", "amount"]
+    kline[float_cols] = kline[float_cols].astype("float32")
+    kline["avg_price"] = kline["amount"] / kline["vol"]
+
+    # 删除9:30的K线
+    kline["keep"] = kline["trade_time"].apply(lambda x: 0 if x.hour == 9 and x.minute == 30 else 1)
+    kline = kline[kline["keep"] == 1]
+    
+    # 删除没有成交量的K线
+    kline = kline[kline["vol"] > 0]
+    kline.drop(["keep"], axis=1, inplace=True)
+
+    start_date = pd.to_datetime(sdt)
+    end_date = pd.to_datetime(edt)
+    kline = kline[(kline["trade_time"] >= start_date) & (kline["trade_time"] <= end_date)]
+    kline = kline.reset_index(drop=True)
+    kline["trade_date"] = kline.trade_time.apply(lambda x: x.strftime(dt_fmt))
+
+    if asset == "E":
+        # https://tushare.pro/document/2?doc_id=28
+        factor = pro.adj_factor(ts_code=ts_code, start_date=sdt, end_date=edt)
+    elif asset == "FD":
+        # https://tushare.pro/document/2?doc_id=199
+        factor = pro.fund_adj(ts_code=ts_code, start_date=sdt, end_date=edt)
+    else:
+        factor = pd.DataFrame()
+
+    if len(factor) > 0:
+        # 处理复权因子缺失的情况：前值填充
+        df1 = pd.DataFrame({"trade_date": kline["trade_date"].unique().tolist()})
+        factor = df1.merge(factor, on=["trade_date"], how="left").ffill().bfill()
+        factor = factor.sort_values("trade_date", ignore_index=True)
+
+    print(f"pro_bar_minutes: {ts_code} - {asset} - 复权因子长度 = {len(factor)}")
+
+    # 复权行情说明：https://tushare.pro/document/2?doc_id=146
+    if len(factor) > 0 and adj and adj == "qfq":
+        # 前复权	= 当日收盘价 × 当日复权因子 / 最新复权因子
+        latest_factor = factor.iloc[-1]["adj_factor"]
+        adj_map = {row["trade_date"]: row["adj_factor"] for _, row in factor.iterrows()}
+        for col in ["open", "close", "high", "low"]:
+            kline[col] = kline.apply(lambda x: x[col] * adj_map[x["trade_date"]] / latest_factor, axis=1)
+
+    if len(factor) > 0 and adj and adj == "hfq":
+        # 后复权	= 当日收盘价 × 当日复权因子
+        adj_map = {row["trade_date"]: row["adj_factor"] for _, row in factor.iterrows()}
+        for col in ["open", "close", "high", "low"]:
+            kline[col] = kline.apply(lambda x: x[col] * adj_map[x["trade_date"]], axis=1)   
+
+    if sdt:
+        kline = kline[kline["trade_time"] >= pd.to_datetime(sdt)]
+    if edt:
+        kline = kline[kline["trade_time"] <= pd.to_datetime(edt)]
+
+    kline = kline.reset_index(drop=True)
+    return kline
+
+
 def get_symbols(step="all"):
     """获取标的代码"""
     stocks = dc.stock_basic(exchange="", list_status="L", fields="ts_code,symbol,name,area,industry,list_date")

czsc/eda.py

@@ -86,7 +86,7 @@ def remove_beta_effects(df, **kwargs):
 def cross_sectional_strategy(df, factor, weight="weight", long=0.3, short=0.3, **kwargs):
     """根据截面因子值构建多空组合
 
-    :param df: pd.DataFrame, 包含因子列的数据, 必须包含 dt, symbol, factor 列
+    :param df: pd.DataFrame, 包含多个品种的因子数据, 必须包含 dt, symbol, factor 列
     :param factor: str, 因子列名称
     :param weight: str, 权重列名称，默认为 weight
     :param long: float, 多头持仓比例/数量，默认为 0.3, 取值范围为 [0, n_symbols], 0~1 表示比例，大于等于1表示数量
@@ -600,3 +600,68 @@ def limit_leverage(df: pd.DataFrame, leverage: float = 1.0, **kwargs):
 
     return df
 
+
+def cal_trade_price(df: pd.DataFrame, digits=None, **kwargs):
+    """计算给定品种基础周期K线数据的交易价格表
+
+    :param df: 基础周期K线数据，一般是1分钟周期的K线，支持多个品种
+    :param digits: 保留小数位数，默认值为None，用每个品种的 close 列的小数位数
+    :param kwargs:
+
+        - windows: 计算TWAP和VWAP的窗口列表，默认值为(5, 10, 15, 20, 30, 60)
+        - copy: 是否复制数据，默认值为True
+
+    :return: 交易价格表，包含多个品种的交易价格
+    """
+    assert "symbol" in df.columns, "数据中必须包含 symbol 列"
+    for col in ["dt", "open", "close", "vol"]:
+        assert col in df.columns, f"数据中必须包含 {col} 列"
+
+    if kwargs.get("copy", True):
+        df = df.copy()
+
+    # 获取所有唯一的品种
+    symbols = df["symbol"].unique().tolist()
+    
+    # 为每个品种分别计算交易价格
+    dfs = []
+    for symbol in symbols:
+        df_symbol = df[df["symbol"] == symbol].copy()
+        df_symbol = df_symbol.sort_values("dt").reset_index(drop=True)
+        
+        # 如果没有指定digits，则使用该品种的close列的小数位数
+        symbol_digits = digits
+        if symbol_digits is None:
+            symbol_digits = df_symbol["close"].astype(str).str.split(".").str[1].str.len().max()
+
+        # 下根K线开盘、收盘
+        df_symbol["TP_CLOSE"] = df_symbol["close"]
+        df_symbol["TP_NEXT_OPEN"] = df_symbol["open"].shift(-1)
+        df_symbol["TP_NEXT_CLOSE"] = df_symbol["close"].shift(-1)
+        price_cols = ["TP_CLOSE", "TP_NEXT_OPEN", "TP_NEXT_CLOSE"]
+
+        # TWAP / VWAP 价格
+        df_symbol["vol_close_prod"] = df_symbol["vol"] * df_symbol["close"]
+        for t in kwargs.get("windows", (5, 10, 15, 20, 30, 60)):
+            
+            df_symbol[f"TP_TWAP{t}"] = df_symbol["close"].rolling(t).mean().shift(-t)
+
+            df_symbol[f"sum_vol_{t}"] = df_symbol["vol"].rolling(t).sum()
+            df_symbol[f"sum_vcp_{t}"] = df_symbol["vol_close_prod"].rolling(t).sum()
+            df_symbol[f"TP_VWAP{t}"] = (df_symbol[f"sum_vcp_{t}"] / df_symbol[f"sum_vol_{t}"]).shift(-t)
+            
+            price_cols.extend([f"TP_TWAP{t}", f"TP_VWAP{t}"])
+            df_symbol.drop(columns=[f"sum_vol_{t}", f"sum_vcp_{t}"], inplace=True)
+
+        df_symbol.drop(columns=["vol_close_prod"], inplace=True)
+
+        # 用当前K线的收盘价填充交易价中的 nan 值
+        for price_col in price_cols:
+            df_symbol[price_col] = df_symbol[price_col].fillna(df_symbol["close"])
+
+        df_symbol[price_cols] = df_symbol[price_cols].round(symbol_digits)
+        dfs.append(df_symbol)
+
+    # 合并所有品种的交易价格数据
+    dfk = pd.concat(dfs, ignore_index=True)
+    return dfk