akquant 0.1.0__cp39-abi3-win_amd64.whl

akquant/backtest.py

@@ -0,0 +1,414 @@
+import pandas as pd
+from typing import Union, List, Optional, Type, Callable, Dict, Any
+from .akquant import Engine, ExecutionMode, Instrument, AssetType, DataFeed, Bar
+from .strategy import Strategy
+from .data import DataLoader
+from .log import get_logger, register_logger
+from .utils import prepare_dataframe, df_to_arrays
+
+
+class FunctionalStrategy(Strategy):
+    """
+    内部策略包装器，用于支持函数式 API (Zipline 风格)
+    """
+
+    def __init__(
+        self, initialize: Callable, on_bar: Callable, context: Dict[str, Any] = None
+    ):
+        super().__init__()
+        self._initialize = initialize
+        self._on_bar_func = on_bar
+        self._context = context or {}
+
+        # 将 context 注入到 self 中，模拟 Zipline 的 context 对象
+        # 用户可以通过 self.xxx 访问 context 属性
+        for k, v in self._context.items():
+            setattr(self, k, v)
+
+        # 调用初始化函数
+        if self._initialize:
+            self._initialize(self)
+
+    def on_bar(self, bar: Bar):
+        if self._on_bar_func:
+            self._on_bar_func(self, bar)
+
+
+def run_backtest(
+    data: Union[pd.DataFrame, List[Bar]],
+    strategy: Union[Type[Strategy], Strategy, Callable[[Any, Bar], None]],
+    symbol: str = "BENCHMARK",
+    cash: float = 1_000_000.0,
+    commission: float = 0.0003,
+    stamp_tax: float = 0.0005,
+    transfer_fee: float = 0.00001,
+    min_commission: float = 5.0,
+    execution_mode: Union[ExecutionMode, str] = ExecutionMode.NextOpen,
+    timezone: str = "Asia/Shanghai",
+    initialize: Optional[Callable[[Any], None]] = None,
+    context: Optional[Dict[str, Any]] = None,
+    history_depth: int = 0,
+    lot_size: Union[int, Dict[str, int], None] = None,
+    show_progress: bool = True,
+    **kwargs,
+) -> Any:
+    """
+    简化版回测入口函数
+
+    :param data: 回测数据，可以是 Pandas DataFrame 或 Bar 列表
+    :param strategy: 策略类、策略实例或 on_bar 回调函数
+    :param symbol: 标的代码
+    :param cash: 初始资金
+    :param commission: 佣金率
+    :param stamp_tax: 印花税率 (仅卖出)
+    :param transfer_fee: 过户费率
+    :param min_commission: 最低佣金
+    :param execution_mode: 执行模式 (ExecutionMode.NextOpen 或 "next_open")
+    :param timezone: 时区名称
+    :param initialize: 初始化回调函数 (仅当 strategy 为函数时使用)
+    :param context: 初始上下文数据 (仅当 strategy 为函数时使用)
+    :param history_depth: 自动维护历史数据的长度 (0 表示禁用)
+    :param lot_size: 最小交易单位。如果是 int，则应用于所有标的；如果是 Dict[str, int]，则按代码匹配；如果不传(None)，默认为 1。
+    :param show_progress: 是否显示进度条 (默认 True)
+    :return: 回测结果 Result 对象
+    """
+
+    # 1. 确保日志已初始化
+    # 如果用户没有配置过日志，这里会提供一个默认配置
+    logger = get_logger()
+    if not logger.handlers:
+        register_logger(console=True, level="INFO")
+        logger = get_logger()
+
+    # 2. 准备数据
+    feed = DataFeed()
+    symbols = []
+
+    # Normalize symbol to list
+    if isinstance(symbol, str):
+        symbols = [symbol]
+    elif isinstance(symbol, list):
+        symbols = symbol
+    else:
+        # If symbol not provided, try to infer from Dict keys or use default
+        symbols = ["BENCHMARK"]
+
+    if isinstance(data, pd.DataFrame):
+        # Single DataFrame -> Single Symbol (use first symbol)
+        target_symbol = symbols[0] if symbols else "BENCHMARK"
+        df = prepare_dataframe(data)
+        # Fast Path: Avoid creating Bar objects in Python
+        arrays = df_to_arrays(df, symbol=target_symbol)
+        feed.add_arrays(*arrays)
+        feed.sort()
+        
+        if target_symbol not in symbols:
+            symbols = [target_symbol]
+
+    elif isinstance(data, dict):
+        # Dict[str, DataFrame] -> Multi Symbol
+        symbols = list(data.keys())
+        for sym, df in data.items():
+            df_prep = prepare_dataframe(df)
+            # Fast Path
+            arrays = df_to_arrays(df_prep, symbol=sym)
+            feed.add_arrays(*arrays)
+        feed.sort()
+
+    elif isinstance(data, list):
+        # List[Bar]
+        if data:
+            data.sort(key=lambda b: b.timestamp)
+            feed.add_bars(data)
+    else:
+        raise ValueError("data must be a DataFrame, Dict[str, DataFrame], or List[Bar]")
+
+    # 3. 设置引擎
+    engine = Engine()
+    engine.set_timezone_name(timezone)
+    engine.set_cash(cash)
+
+    # ... (ExecutionMode logic)
+    if isinstance(execution_mode, str):
+        mode_map = {
+            "next_open": ExecutionMode.NextOpen,
+            "current_close": ExecutionMode.CurrentClose,
+        }
+        mode = mode_map.get(execution_mode.lower())
+        if not mode:
+            logger.warning(
+                f"Unknown execution mode '{execution_mode}', defaulting to NextOpen"
+            )
+            mode = ExecutionMode.NextOpen
+        engine.set_execution_mode(mode)
+    else:
+        engine.set_execution_mode(execution_mode)
+
+    engine.set_t_plus_one(False)  # 默认 T+0，可配置
+    engine.set_force_session_continuous(True)
+    engine.set_stock_fee_rules(commission, stamp_tax, transfer_fee, min_commission)
+
+    # Configure other asset fees if provided
+    if "fund_commission" in kwargs:
+        engine.set_fund_fee_rules(
+            kwargs["fund_commission"],
+            kwargs.get("fund_transfer_fee", 0.0),
+            kwargs.get("fund_min_commission", 0.0),
+        )
+
+    if "option_commission" in kwargs:
+        engine.set_option_fee_rules(kwargs["option_commission"])
+
+    # 4. 添加标的
+    multiplier = kwargs.get("multiplier", 1.0)
+    margin_ratio = kwargs.get("margin_ratio", 1.0)
+    tick_size = kwargs.get("tick_size", 0.01)
+    asset_type = kwargs.get("asset_type", AssetType.Stock)
+
+    # Option specific fields
+    option_type = kwargs.get("option_type", None)
+    strike_price = kwargs.get("strike_price", None)
+    expiry_date = kwargs.get("expiry_date", None)
+    # lot_size is handled separately via argument
+
+    for sym in symbols:
+        # Determine lot_size for this symbol
+        current_lot_size = None
+        if isinstance(lot_size, int):
+            current_lot_size = lot_size
+        elif isinstance(lot_size, dict):
+            current_lot_size = lot_size.get(sym)
+
+        instr = Instrument(
+            sym,
+            asset_type,
+            multiplier,
+            margin_ratio,
+            tick_size,
+            option_type,
+            strike_price,
+            expiry_date,
+            current_lot_size,
+        )
+        engine.add_instrument(instr)
+
+    # 5. 添加数据
+    engine.add_data(feed)
+
+    # ... (Rest is same)
+
+    # 6. 准备策略实例
+    strategy_instance = None
+
+    if isinstance(strategy, type) and issubclass(strategy, Strategy):
+        # 如果是策略类，实例化它
+        # 尝试传递 kwargs 给构造函数，如果失败则无参数构造
+        try:
+            strategy_instance = strategy(**kwargs)
+        except TypeError:
+            strategy_instance = strategy()
+    elif isinstance(strategy, Strategy):
+        # 如果已经是实例
+        strategy_instance = strategy
+    elif callable(strategy):
+        # 如果是函数，假设是 on_bar 回调 (Zipline 风格)
+        # 需要配合 initialize 使用
+        strategy_instance = FunctionalStrategy(initialize, strategy, context)
+    else:
+        raise ValueError("Invalid strategy type")
+
+    # 7. 运行回测
+    logger.info("Running backtest via run_backtest()...")
+
+    # 注入 context 到策略实例
+    if context and hasattr(strategy_instance, "_context"):
+        # 如果是 FunctionalStrategy
+        # 已经在 __init__ 中注入了
+        pass
+    elif context and strategy_instance:
+        # 如果是普通 Strategy，尝试注入属性
+        for k, v in context.items():
+            setattr(strategy_instance, k, v)
+
+    # 设置自动历史数据维护
+    if history_depth > 0:
+        strategy_instance.set_history_depth(history_depth)
+
+    engine.run(strategy_instance, show_progress)
+
+    return engine.get_results()
+
+
+def plot_result(
+    result: Any, show: bool = True, filename: str = None, benchmark: pd.Series = None
+):
+    """
+    绘制回测结果 (权益曲线、回撤、日收益率)
+
+    :param result: BacktestResult 对象
+    :param show: 是否调用 plt.show()
+    :param filename: 保存图片的文件名
+    :param benchmark: 基准收益率序列 (可选, Series with DatetimeIndex)
+    """
+    try:
+        import matplotlib.pyplot as plt
+        import matplotlib.dates as mdates
+        from matplotlib.gridspec import GridSpec
+        from datetime import datetime
+        import numpy as np
+    except ImportError:
+        print(
+            "Error: matplotlib is required for plotting. Please install it via 'pip install matplotlib'."
+        )
+        return
+
+    # Extract data
+    equity_curve = result.equity_curve  # List[Tuple[int, float]]
+
+    if not equity_curve:
+        print("No equity curve data to plot.")
+        return
+
+    # Check if timestamp is in nanoseconds (e.g. > 1e11)
+    # 1e11 seconds is roughly year 5138, so valid seconds are < 1e11
+    # 1e18 nanoseconds is roughly year 2001
+    first_ts = equity_curve[0][0]
+    scale = 1.0
+    if first_ts > 1e11:
+        scale = 1e-9
+
+    times = [datetime.fromtimestamp(t * scale) for t, _ in equity_curve]
+    equity = [e for _, e in equity_curve]
+
+    # Convert to DataFrame for easier calculation
+    df = pd.DataFrame({"equity": equity}, index=times)
+    df.index.name = "Date"
+    df["returns"] = df["equity"].pct_change().fillna(0)
+
+    # Calculate Drawdown
+    rolling_max = df["equity"].cummax()
+    drawdown = (df["equity"] - rolling_max) / rolling_max
+
+    # Create figure with GridSpec
+    fig = plt.figure(figsize=(14, 10))
+    # 3 rows: Equity (3), Drawdown (1), Daily Returns (1)
+    gs = GridSpec(3, 1, height_ratios=[3, 1, 1], hspace=0.05)
+
+    # 1. Equity Curve
+    ax1 = fig.add_subplot(gs[0])
+    ax1.plot(df.index, df["equity"], label="Strategy", color="#1f77b4", linewidth=1.5)
+
+    if benchmark is not None:
+        # Align benchmark to strategy dates
+        try:
+            # Ensure benchmark has DatetimeIndex
+            if not isinstance(benchmark.index, pd.DatetimeIndex):
+                benchmark.index = pd.to_datetime(benchmark.index)
+
+            # Reindex benchmark to match strategy dates (forward fill for missing days if any, but strict alignment preferred)
+            # Normalize dates to start of day for alignment if needed, but here we assume close match
+            # For simplicity, we just plot what overlaps
+
+            # Calculate cumulative return of benchmark
+            bench_cum = (1 + benchmark).cumprod()
+
+            # Rebase benchmark to match initial strategy equity
+            initial_equity = df["equity"].iloc[0]
+            if not bench_cum.empty:
+                # Align start
+                # Find the closest date in benchmark to start date
+                start_date = df.index[0]
+                if start_date in bench_cum.index:
+                    base_val = bench_cum.loc[start_date]
+                else:
+                    # Fallback: use first available
+                    base_val = bench_cum.iloc[0]
+
+                bench_scaled = (bench_cum / base_val) * initial_equity
+
+                # Filter to strategy range
+                bench_plot = bench_scaled[df.index[0] : df.index[-1]]
+                ax1.plot(
+                    bench_plot.index,
+                    bench_plot,
+                    label="Benchmark",
+                    color="gray",
+                    linestyle="--",
+                    alpha=0.7,
+                )
+        except Exception as e:
+            print(f"Warning: Failed to plot benchmark: {e}")
+
+    ax1.set_title("Strategy Performance Analysis", fontsize=14, fontweight="bold")
+    ax1.set_ylabel("Equity", fontsize=10)
+    ax1.grid(True, linestyle="--", alpha=0.3)
+    ax1.legend(loc="upper left", frameon=True, fancybox=True, framealpha=0.8)
+
+    # Add Metrics Text Box
+    metrics = result.metrics
+    trade_metrics = result.trade_metrics
+
+    metrics_text = [
+        f"Total Return: {metrics.total_return_pct:>8.2f}%",
+        f"Annualized:   {metrics.annualized_return:>8.2%}",
+        f"Sharpe Ratio: {metrics.sharpe_ratio:>8.2f}",
+        f"Max Drawdown: {metrics.max_drawdown_pct:>8.2f}%",
+        f"Win Rate:     {metrics.win_rate:>8.2%}",
+    ]
+
+    if hasattr(trade_metrics, "total_closed_trades"):
+        metrics_text.append(f"Trades:       {trade_metrics.total_closed_trades:>8d}")
+
+    text_str = "\n".join(metrics_text)
+
+    props = dict(boxstyle="round", facecolor="white", alpha=0.8, edgecolor="lightgray")
+    ax1.text(
+        0.02,
+        0.05,
+        text_str,
+        transform=ax1.transAxes,
+        fontsize=9,
+        verticalalignment="bottom",
+        fontfamily="monospace",
+        bbox=props,
+    )
+
+    # 2. Drawdown
+    ax2 = fig.add_subplot(gs[1], sharex=ax1)
+    ax2.fill_between(
+        df.index, drawdown, 0, color="#d62728", alpha=0.3, label="Drawdown"
+    )
+    ax2.plot(df.index, drawdown, color="#d62728", linewidth=0.8, alpha=0.8)
+    ax2.set_ylabel("Drawdown", fontsize=10)
+    ax2.grid(True, linestyle="--", alpha=0.3)
+    # ax2.legend(loc='lower right', fontsize=8)
+
+    # 3. Daily Returns
+    ax3 = fig.add_subplot(gs[2], sharex=ax1)
+    ax3.bar(
+        df.index,
+        df["returns"],
+        color="gray",
+        alpha=0.5,
+        label="Daily Returns",
+        width=1.0 if len(df) < 100 else 0.8,
+    )
+    # Highlight extreme returns? No, keep simple.
+    ax3.set_ylabel("Returns", fontsize=10)
+    ax3.grid(True, linestyle="--", alpha=0.3)
+
+    # Format X axis
+    ax3.xaxis.set_major_formatter(mdates.DateFormatter("%Y-%m-%d"))
+    plt.setp(ax1.get_xticklabels(), visible=False)
+    plt.setp(ax2.get_xticklabels(), visible=False)
+    plt.xticks(rotation=0)
+
+    # Adjust margins
+    plt.subplots_adjust(top=0.95, bottom=0.05, left=0.08, right=0.95)
+
+    if filename:
+        plt.savefig(filename, dpi=100, bbox_inches="tight")
+        print(f"Plot saved to {filename}")
+
+    if show:
+        plt.show()

akquant/config.py

@@ -0,0 +1,36 @@
+from typing import Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class StrategyConfig:
+    """
+    Global configuration for strategies and backtesting.
+    Inspired by PyBroker's configuration system.
+    """
+
+    # Capital Management
+    initial_cash: float = 100000.0
+
+    # Fees & Commission
+    fee_mode: str = "per_order"  # 'per_order', 'per_share', 'percent'
+    fee_amount: float = 0.0  # Fixed amount or percentage
+
+    # Execution
+    enable_fractional_shares: bool = False
+    round_fill_price: bool = True
+
+    # Position Sizing Constraints
+    max_long_positions: Optional[int] = None
+    max_short_positions: Optional[int] = None
+
+    # Bootstrap Metrics
+    bootstrap_samples: int = 1000
+    bootstrap_sample_size: Optional[int] = None
+
+    # Other
+    exit_on_last_bar: bool = True
+
+
+# Global instance
+strategy_config = StrategyConfig()

akquant/data.py

@@ -0,0 +1,122 @@
+import pandas as pd
+import hashlib
+from typing import Optional, List
+from pathlib import Path
+import logging
+
+try:
+    import akshare as ak
+except ImportError:
+    ak = None
+
+from .utils import load_akshare_bar
+from .akquant import Bar
+
+logger = logging.getLogger(__name__)
+
+
+class DataLoader:
+    """
+    Data Loader with caching capabilities, inspired by PyBroker.
+    """
+
+    def __init__(self, cache_dir: Optional[str] = None):
+        """
+        Initialize DataLoader.
+
+        Args:
+            cache_dir (str, optional): Directory to store cache files.
+                                     Defaults to ~/.akquant/cache.
+        """
+        if cache_dir:
+            self.cache_dir = Path(cache_dir)
+        else:
+            self.cache_dir = Path.home() / ".akquant" / "cache"
+
+        try:
+            if not self.cache_dir.exists():
+                self.cache_dir.mkdir(parents=True, exist_ok=True)
+        except PermissionError:
+            logger.warning(
+                f"Permission denied for {self.cache_dir}, falling back to local .akquant_cache"
+            )
+            self.cache_dir = Path.cwd() / ".akquant_cache"
+            if not self.cache_dir.exists():
+                self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _get_cache_path(self, key: str) -> Path:
+        """Generate cache file path based on a unique key."""
+        # Use a hash of the key to avoid filesystem issues with long/invalid filenames
+        hashed_key = hashlib.md5(key.encode("utf-8")).hexdigest()
+        return self.cache_dir / f"{hashed_key}.pkl"
+
+    def load_akshare(
+        self,
+        symbol: str,
+        start_date: str,
+        end_date: str,
+        adjust: str = "qfq",
+        period: str = "daily",
+        use_cache: bool = True,
+    ) -> pd.DataFrame:
+        """
+        Load A-share history data from AKShare with caching.
+
+        Args:
+            symbol (str): Stock symbol (e.g., "600000").
+            start_date (str): Start date (YYYYMMDD).
+            end_date (str): End date (YYYYMMDD).
+            adjust (str): Adjustment factor ("qfq", "hfq", ""). Default "qfq".
+            period (str): Period ("daily", "weekly", "monthly"). Default "daily".
+            use_cache (bool): Whether to use cache. Default True.
+
+        Returns:
+            pd.DataFrame: Historical data.
+        """
+        if ak is None:
+            raise ImportError(
+                "akshare is not installed. Please run `pip install akshare`."
+            )
+
+        cache_key = f"akshare_stock_zh_a_hist_{symbol}_{start_date}_{end_date}_{adjust}_{period}"
+        cache_path = self._get_cache_path(cache_key)
+
+        if use_cache and cache_path.exists():
+            logger.info(f"Loading cached data for {symbol} from {cache_path}")
+            try:
+                df = pd.read_pickle(cache_path)
+                return df
+            except Exception as e:
+                logger.warning(f"Failed to load cache: {e}. Reloading from source.")
+
+        logger.info(f"Fetching data for {symbol} from AKShare...")
+        try:
+            df = ak.stock_zh_a_hist(
+                symbol=symbol,
+                period=period,
+                start_date=start_date,
+                end_date=end_date,
+                adjust=adjust,
+            )
+
+            # Basic validation
+            if df.empty:
+                logger.warning(f"No data found for {symbol}")
+                return df
+
+            # Cache the result
+            if use_cache:
+                df.to_pickle(cache_path)
+                logger.info(f"Data cached to {cache_path}")
+
+            return df
+        except Exception as e:
+            logger.error(f"Error fetching data from AKShare: {e}")
+            raise
+
+    def df_to_bars(self, df: pd.DataFrame, symbol: Optional[str] = None) -> List[Bar]:
+        """
+        Convert DataFrame to list of Bar objects.
+        Wrapper around utils.load_akshare_bar.
+        """
+        return load_akshare_bar(df, symbol)

akquant/indicator.py

@@ -0,0 +1,56 @@
+from typing import Callable, Dict
+import pandas as pd
+
+
+class Indicator:
+    """
+    Helper class for defining and calculating indicators.
+    Inspired by PyBroker's indicator system.
+    """
+
+    def __init__(self, name: str, fn: Callable, **kwargs):
+        self.name = name
+        self.fn = fn
+        self.kwargs = kwargs
+        self._data: Dict[str, pd.Series] = {}  # symbol -> series
+
+    def __call__(self, df: pd.DataFrame, symbol: str) -> pd.Series:
+        """Calculate indicator on a DataFrame"""
+        if symbol in self._data:
+            return self._data[symbol]
+
+        # Assume fn takes a series/df and returns a series
+        # If kwargs contains column names, extract them
+        # This is a simplified version of PyBroker's powerful DSL
+        try:
+            result = self.fn(df, **self.kwargs)
+        except Exception:
+            # Try passing column if specified in kwargs
+            # e.g. rolling_mean(df['close'], window=5)
+            # This part is tricky to generalize without a full DSL,
+            # so we start simple: user passes a lambda or function that takes df
+            result = self.fn(df)
+
+        self._data[symbol] = result
+        return result
+
+
+class IndicatorSet:
+    """
+    Collection of indicators for easy management.
+    """
+
+    def __init__(self):
+        self._indicators: Dict[str, Indicator] = {}
+
+    def add(self, name: str, fn: Callable, **kwargs):
+        self._indicators[name] = Indicator(name, fn, **kwargs)
+
+    def get(self, name: str) -> Indicator:
+        return self._indicators[name]
+
+    def calculate_all(self, df: pd.DataFrame, symbol: str) -> Dict[str, pd.Series]:
+        results = {}
+        for name, ind in self._indicators.items():
+            results[name] = ind(df, symbol)
+        return results