back-trader-python 1.4.0__py3-none-any.whl

backtrader/utils/fractal.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python
+"""Fractal Indicator Module - Fractal pattern detection.
+
+This module provides the Fractal indicator for identifying fractal
+patterns in price data. Fractals are reversal patterns that indicate
+potential trend changes.
+
+Classes:
+    Fractal: Identifies bullish and bearish fractal patterns.
+
+References:
+    http://www.investopedia.com/articles/trading/06/fractals.asp
+
+Example:
+    >>> from backtrader.utils.fractal import Fractal
+    >>> class MyStrategy(bt.Strategy):
+    ...     def __init__(self):
+    ...         self.fractal = Fractal(self.data)
+    ...     def next(self):
+    ...         if self.fractal.fractal_bullish[0] > 0:
+    ...             self.buy()
+"""
+
+from ..indicators import PeriodN
+
+__all__ = ["Fractal"]
+
+
+class Fractal(PeriodN):
+    """Fractal pattern indicator.
+
+    Identifies bullish and bearish fractal patterns which indicate
+    potential reversal points in price trends.
+
+    A bearish fractal occurs when there's a pattern with the highest
+    high in the middle and two lower highs on each side.
+
+    A bullish fractal occurs when there's a pattern with the lowest
+    low in the middle and two higher lows on each side.
+
+    Params:
+        period: Number of bars to check (default: 5).
+        bardist: Distance to max/min in percentage (default: 0.015).
+        shift_to_potential_fractal: Index of potential fractal (default: 2).
+
+    Lines:
+        fractal_bearish: Bearish fractal levels.
+        fractal_bullish: Bullish fractal levels.
+    """
+
+    lines = ("fractal_bearish", "fractal_bullish")
+
+    plotinfo = {"subplot": False, "plotlinelabels": False, "plot": True}
+
+    plotlines = {
+        "fractal_bearish": {
+            "marker": "^",
+            "markersize": 4.0,
+            "color": "lightblue",
+            "fillstyle": "full",
+            "ls": "",
+        },
+        "fractal_bullish": {
+            "marker": "v",
+            "markersize": 4.0,
+            "color": "lightblue",
+            "fillstyle": "full",
+            "ls": "",
+        },
+    }
+    params = (
+        ("period", 5),
+        ("bardist", 0.015),  # distance to max/min in absolute perc
+        ("shift_to_potential_fractal", 2),
+    )
+
+    def next(self):
+        """Calculate fractal patterns for the current bar.
+
+        Identifies bearish fractals (highest high in middle with two lower
+        highs on sides) and bullish fractals (lowest low in middle with two
+        higher lows on sides).
+        """
+        # A bearish turning point occurs when there is a pattern with the
+        # highest high in the middle and two lower highs on each side. [Ref 1]
+
+        last_five_highs = self.data.high.get(size=self.p.period)
+        max_val = max(last_five_highs)
+        max_idx = last_five_highs.index(max_val)
+
+        if max_idx == self.p.shift_to_potential_fractal:
+            self.lines.fractal_bearish[-2] = max_val * (1 + self.p.bardist)
+
+        # A bullish turning point occurs when there is a pattern with the
+        # lowest low in the middle and two higher lowers on each side. [Ref 1]
+        last_five_lows = self.data.low.get(size=self.p.period)
+        min_val = min(last_five_lows)
+        min_idx = last_five_lows.index(min_val)
+
+        if min_idx == self.p.shift_to_potential_fractal:
+            self.l.fractal_bullish[-2] = min_val * (1 - self.p.bardist)

backtrader/utils/get_metrics.py

@@ -0,0 +1,101 @@
+# pyright: reportAny=false, reportExplicitAny=false
+"""Standard-metric extraction helpers for Cerebro backtests.
+
+Exposes :data:`STANDARD_METRIC_FIELDS` (the canonical key list),
+:func:`get_backtest_metrics` (which collects the raw values from a
+completed run) and :func:`write_metrics` (which serialises the
+result as JSON). An alias
+:data:`extract_backtest_metrics` is also provided for callers that
+prefer the longer name.
+"""
+
+from __future__ import absolute_import, annotations, division, print_function, unicode_literals
+
+import json
+from pathlib import Path
+from typing import Any
+
+STANDARD_METRIC_FIELDS = (
+    "bar_num",
+    "buy_count",
+    "sell_count",
+    "win_count",
+    "loss_count",
+    "trade_num",
+    "final_value",
+    "sharpe_ratio",
+    "annual_return",
+    "max_drawdown",
+    "return_rate",
+)
+
+
+def get_backtest_metrics(cerebro: Any, config: dict[str, Any]) -> dict[str, Any]:
+    """Extract raw standard metrics from a completed Cerebro backtest.
+
+    Pulls the strategy instance from ``cerebro.runstrats[0][0]`` and
+    reads the ``sharpe``, ``returns``, ``drawdown`` and ``trades``
+    analyzers plus the broker's final portfolio value. The returned
+    dict contains exactly the keys listed in
+    :data:`STANDARD_METRIC_FIELDS` and is the raw payload consumed by
+    downstream normalisation or reporting layers.
+
+    Args:
+        cerebro: A Cerebro instance whose first run strategy has
+            already produced the four expected analyzers
+            (``sharpe``, ``returns``, ``drawdown``, ``trades``).
+        config: Configuration dict. Only ``config["backtest"]
+            ["initial_cash"]`` is read, used as the baseline for
+            ``return_rate``.
+
+    Returns:
+        dict: Mapping of standard metric name -> value (floats for
+        percentages and counts, broker value for ``final_value``).
+    """
+
+    strat = cerebro.runstrats[0][0]
+    initial_cash = float(config["backtest"]["initial_cash"])
+    final_value = float(cerebro.broker.getvalue())
+
+    sharpe = strat.analyzers.sharpe.get_analysis()
+    returns = strat.analyzers.returns.get_analysis()
+    drawdown = strat.analyzers.drawdown.get_analysis()
+    trades = strat.analyzers.trades.get_analysis()
+
+    return {
+        "bar_num": strat.bar_num,
+        "buy_count": trades.get("long", {}).get("total"),
+        "sell_count": trades.get("short", {}).get("total"),
+        "win_count": trades.get("won", {}).get("total"),
+        "loss_count": trades.get("lost", {}).get("total"),
+        "trade_num": trades.get("total", {}).get("total"),
+        "final_value": final_value,
+        "sharpe_ratio": sharpe["sharperatio"],
+        "annual_return": returns["rnorm"],
+        "max_drawdown": drawdown["max"]["drawdown"],
+        "return_rate": (final_value / initial_cash - 1.0) * 100.0,
+    }
+
+
+def write_metrics(metrics: dict[str, Any], base_dir: str, filename: str = "py_result.json") -> Path:
+    """Serialize ``metrics`` as JSON inside ``base_dir``.
+
+    Args:
+        metrics: Mapping of metric name -> JSON-serialisable value.
+            Typically the output of :func:`get_backtest_metrics`.
+        base_dir: Directory where the JSON file will be written.
+            Created implicitly by :class:`pathlib.Path` (the
+            underlying ``open`` will fail if it does not exist).
+        filename: JSON file name. Defaults to ``"py_result.json"``.
+
+    Returns:
+        Path: The absolute (or relative) path to the written file.
+    """
+    output_path = Path(base_dir) / filename
+    with output_path.open("w", encoding="utf-8") as handle:
+        json.dump(metrics, handle, ensure_ascii=False, indent=2)
+    return output_path
+
+
+extract_backtest_metrics = get_backtest_metrics
+extract_metrics = get_backtest_metrics

backtrader/utils/load_data.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Shared data-loading helpers for functional tests and examples."""
+
+from __future__ import absolute_import, division, print_function, unicode_literals
+
+from functools import lru_cache
+from pathlib import Path
+
+_BASE_COLUMNS = ["open", "high", "low", "close", "volume", "openinterest"]
+_AUGMENT_COLUMNS = ("tick_volume", "real_volume", "spread")
+
+
+def resolve_repo_paths(node, repo=None, placeholder="{repo}"):
+    """Resolve repo placeholders inside nested config data."""
+    if repo is None:
+        return node
+
+    repo_text = str(repo)
+
+    if isinstance(node, dict):
+        return {
+            key: resolve_repo_paths(value, repo=repo_text, placeholder=placeholder)
+            for key, value in node.items()
+        }
+
+    if isinstance(node, list):
+        return [
+            resolve_repo_paths(value, repo=repo_text, placeholder=placeholder) for value in node
+        ]
+
+    if isinstance(node, tuple):
+        return tuple(
+            resolve_repo_paths(value, repo=repo_text, placeholder=placeholder) for value in node
+        )
+
+    if isinstance(node, str):
+        return node.replace(placeholder, repo_text)
+
+    return node
+
+
+def load_config(config, repo=None, placeholder="{repo}"):
+    """Return a deep-copied inline config with repo placeholders resolved."""
+    import copy
+
+    return resolve_repo_paths(
+        copy.deepcopy(config),
+        repo=repo,
+        placeholder=placeholder,
+    )
+
+
+def _first_non_empty_line(filepath):
+    with open(filepath, "r", encoding="utf-8", errors="ignore") as handle:
+        for line in handle:
+            line = line.strip()
+            if line:
+                return line.strip('"')
+
+    raise ValueError("MT5 CSV file is empty: %s" % filepath)
+
+
+def _read_cleaned_mt5_csv(filepath, sep):
+    import io
+
+    import pandas as pd
+
+    with open(filepath, "r", encoding="utf-8", errors="ignore") as handle:
+        lines = [line.strip().strip('"') for line in handle if line.strip()]
+
+    if not lines:
+        raise ValueError("MT5 CSV file is empty: %s" % filepath)
+
+    return pd.read_csv(io.StringIO("\n".join(lines)), sep=sep)
+
+
+def _needs_cleaned_read(df):
+    if "time" in df.columns:
+        return False
+    return "<DATE>" not in df.columns or "<TIME>" not in df.columns
+
+
+def _read_mt5_csv(filepath, bar_shift_minutes=0):
+    """Read MT5 data and keep standard plus known raw columns."""
+    return _read_mt5_csv_cached(*_mt5_cache_args(filepath, bar_shift_minutes))
+
+
+def _mt5_cache_args(filepath, bar_shift_minutes):
+    path = Path(filepath)
+    stat = path.stat()
+    return (
+        str(path),
+        stat.st_mtime_ns,
+        stat.st_size,
+        int(bar_shift_minutes or 0),
+    )
+
+
+def _datetime_cache_key(value):
+    if value is None:
+        return None
+    if hasattr(value, "isoformat"):
+        return value.isoformat()
+    return str(value)
+
+
+@lru_cache(maxsize=64)
+def _read_mt5_csv_cached(filepath, mtime_ns, size, bar_shift_minutes):
+    """Read MT5 data once per file version and timestamp shift."""
+    import pandas as pd
+
+    sep = "\t" if "\t" in _first_non_empty_line(filepath) else ","
+    df = pd.read_csv(filepath, sep=sep, encoding="utf-8", encoding_errors="ignore")
+    if _needs_cleaned_read(df):
+        df = _read_cleaned_mt5_csv(filepath, sep)
+
+    if "time" in df.columns:
+        parsed = pd.to_datetime(df["time"], errors="coerce", utc=True).dt.tz_convert(None)
+    else:
+        dt_text = df["<DATE>"].astype(str) + " " + df["<TIME>"].astype(str)
+        parsed = pd.to_datetime(dt_text, format="%Y.%m.%d %H:%M", errors="coerce")
+        if parsed.isna().any():
+            parsed = pd.to_datetime(
+                dt_text,
+                format="%Y.%m.%d %H:%M:%S",
+                errors="coerce",
+            )
+        if parsed.isna().any():
+            parsed = pd.to_datetime(dt_text, errors="coerce")
+
+    if bar_shift_minutes:
+        parsed = parsed + pd.to_timedelta(int(bar_shift_minutes), unit="m")
+
+    df["datetime"] = parsed
+    df = df.rename(
+        columns={
+            "<OPEN>": "open",
+            "<HIGH>": "high",
+            "<LOW>": "low",
+            "<CLOSE>": "close",
+            "<TICKVOL>": "tick_volume",
+            "<VOL>": "real_volume",
+            "<SPREAD>": "spread",
+        }
+    )
+
+    if "volume" not in df.columns:
+        if "tick_volume" in df.columns:
+            df["volume"] = df["tick_volume"]
+        elif "real_volume" in df.columns:
+            df["volume"] = df["real_volume"]
+        else:
+            df["volume"] = 0
+    if "openinterest" not in df.columns:
+        df["openinterest"] = df["real_volume"] if "real_volume" in df.columns else 0
+
+    columns = ["datetime"] + _BASE_COLUMNS
+    columns.extend(column for column in _AUGMENT_COLUMNS if column in df.columns)
+
+    return df[columns].dropna(subset=["datetime"]).set_index("datetime").sort_index()
+
+
+@lru_cache(maxsize=64)
+def _slice_mt5_csv_cached(filepath, mtime_ns, size, bar_shift_minutes, fromdate, todate):
+    """Return a cached OHLCV slice for repeated functional-test date windows."""
+    import pandas as pd
+
+    df = _read_mt5_csv_cached(filepath, mtime_ns, size, bar_shift_minutes)
+    start = 0
+    stop = len(df)
+    if fromdate is not None:
+        start = df.index.searchsorted(pd.Timestamp(fromdate), side="left")
+    if todate is not None:
+        stop = df.index.searchsorted(pd.Timestamp(todate), side="right")
+    return df.iloc[start:stop].loc[:, _BASE_COLUMNS]
+
+
+def load_mt5_csv(filepath, fromdate=None, todate=None, bar_shift_minutes=0):
+    """Load MT5 CSV data into a normalized OHLCV DataFrame."""
+    df = _slice_mt5_csv_cached(
+        *_mt5_cache_args(filepath, bar_shift_minutes),
+        _datetime_cache_key(fromdate),
+        _datetime_cache_key(todate),
+    )
+    return df.copy()
+
+
+def augment_mt5_csv_columns(frame, filepath, columns, bar_shift_minutes=0):
+    """Add selected raw MT5 columns to a DataFrame returned by ``load_mt5_csv``."""
+    columns = tuple(columns)
+    if not columns:
+        return frame.copy()
+
+    unsupported = [column for column in columns if column not in _AUGMENT_COLUMNS]
+    if unsupported:
+        raise ValueError("Unsupported MT5 augment column: %s" % unsupported[0])
+
+    raw = _read_mt5_csv(filepath, bar_shift_minutes=bar_shift_minutes)
+    result = frame.copy()
+    available = [column for column in columns if column in raw.columns]
+    if available:
+        result.loc[:, available] = raw.loc[:, available].reindex(result.index).fillna(0)
+
+    for column in columns:
+        if column not in raw.columns:
+            result[column] = 0
+
+    return result