Qubx 0.6.53__tar.gz → 0.6.56__tar.gz

{qubx-0.6.53 → qubx-0.6.56}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Qubx
-Version: 0.6.53
+Version: 0.6.56
 Summary: Qubx - Quantitative Trading Framework
 Author: Dmitry Marienko
 Author-email: dmitry.marienko@xlydian.com

{qubx-0.6.53 → qubx-0.6.56}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "Qubx"
-version = "0.6.53"
+version = "0.6.56"
 description = "Qubx - Quantitative Trading Framework"
 authors = [ "Dmitry Marienko <dmitry.marienko@xlydian.com>", "Yuriy Arabskyy <yuriy.arabskyy@xlydian.com>",]
 readme = "README.md"

{qubx-0.6.53 → qubx-0.6.56}/src/qubx/backtester/management.py

@@ -3,6 +3,7 @@ import zipfile
 from collections import defaultdict
 from pathlib import Path
 
+import numpy as np
 import pandas as pd
 import yaml
 
@@ -230,6 +231,25 @@ class BacktestsResultsManager:
 
             yield info.get("idx", -1)
 
+    def list_variations(self, regex: str = "", detailed=True, sort_by: str | None = "sharpe", ascending=False):
+        """
+        List only variations of a backtest result.
+
+        Args:
+            - regex (str, optional): Regular expression pattern to filter results by strategy name or class. Defaults to "".
+            - sort_by (str, optional): The criterion to sort the results by. Defaults to "sharpe".
+            - ascending (bool, optional): Whether to sort the results in ascending order. Defaults to False.
+            - detailed (bool, optional): Whether to show each variation run. Defaults to True.
+        """
+        return self.list(
+            regex=regex,
+            sort_by=sort_by,
+            ascending=ascending,
+            show_variations=True,
+            show_simulations=False,
+            show_each_variation_run=detailed,
+        )
+
     def list(
         self,
         regex: str = "",
@@ -239,7 +259,9 @@ class BacktestsResultsManager:
         pretty_print=False,
         sort_by: str | None = "sharpe",
         ascending=False,
+        show_simulations=True,
         show_variations=True,
+        show_each_variation_run=True,
     ):
         """List backtesting results with optional filtering and formatting.
 
@@ -248,87 +270,93 @@ class BacktestsResultsManager:
             - with_metrics (bool, optional): Whether to include performance metrics in output. Defaults to True.
             - params (bool, optional): Whether to display strategy parameters. Defaults to False.
             - as_table (bool, optional): Return results as a pandas DataFrame instead of printing. Defaults to False.
+            - sort_by (str, optional): The criterion to sort the results by. Defaults to "sharpe".
+            - ascending (bool, optional): Whether to sort the results in ascending order. Defaults to False.
+            - show_simulations (bool, optional): Whether to show simulation results. Defaults to True.
+            - show_variations (bool, optional): Whether to show variation results. Defaults to True.
+            - show_each_variation_run (bool, optional): Whether to show each variation run. Defaults to True.
 
         Returns:
             - Optional[pd.DataFrame]: If as_table=True, returns a DataFrame containing the results sorted by creation time.
             - Otherwise prints formatted results to console.
         """
         _t_rep = []
-        for n in sorted(self.results.keys()):
-            info = self.results[n]
-            s_cls = info.get("strategy_class", "").split(".")[-1]
+        if show_simulations:
+            for n in sorted(self.results.keys()):
+                info = self.results[n]
+                s_cls = info.get("strategy_class", "").split(".")[-1]
 
-            if regex:
-                if not re.match(regex, n, re.IGNORECASE):
-                    # if not re.match(regex, s_cls, re.IGNORECASE):
-                    continue
+                if regex:
+                    if not re.match(regex, n, re.IGNORECASE):
+                        # if not re.match(regex, s_cls, re.IGNORECASE):
+                        continue
 
-            name = info.get("name", "")
-            smbs = ", ".join(info.get("symbols", list()))
-            start = pd.Timestamp(info.get("start", "")).round("1s")
-            stop = pd.Timestamp(info.get("stop", "")).round("1s")
-            dscr = info.get("description", "")
-            created = pd.Timestamp(info.get("creation_time", "")).round("1s")
-            metrics = info.get("performance", {})
-            author = info.get("author", "")
-            _s = f"{yellow(str(info.get('idx')))} - {red(name)} ::: {magenta(created)} by {cyan(author)}"
-
-            _one_line_dscr = ""
-            if dscr:
-                dscr = dscr.split("\n")
-                for _d in dscr:
-                    _s += f"\n\t{magenta('# ' + _d)}"
-                    _one_line_dscr += "\u25cf " + _d + "\n"
-
-            _s += f"\n\tstrategy: {green(s_cls)}"
-            _s += f"\n\tinterval: {blue(start)} - {blue(stop)}"
-            _s += f"\n\tcapital: {blue(info.get('capital', ''))} {info.get('base_currency', '')} ({info.get('commissions', '')})"
-            _s += f"\n\tinstruments: {blue(smbs)}"
-            if params:
-                formats = ["{" + f":<{i}" + "}" for i in [50]]
-                _p = pd.DataFrame.from_dict(info.get("parameters", {}), orient="index")
-                for i in _p.to_string(
-                    max_colwidth=30,
-                    header=False,
-                    formatters=[(lambda x: cyan(fmt.format(str(x)))) for fmt in formats],
-                    justify="left",
-                ).split("\n"):
-                    _s += f"\n\t  |  {yellow(i)}"
-
-            if not as_table:
-                print(_s)
+                name = info.get("name", "")
+                smbs = ", ".join(info.get("symbols", list()))
+                start = pd.Timestamp(info.get("start", "")).round("1s")
+                stop = pd.Timestamp(info.get("stop", "")).round("1s")
+                dscr = info.get("description", "")
+                created = pd.Timestamp(info.get("creation_time", "")).round("1s")
+                metrics = info.get("performance", {})
+                author = info.get("author", "")
+                _s = f"{yellow(str(info.get('idx')))} - {red(name)} ::: {magenta(created)} by {cyan(author)}"
+
+                _one_line_dscr = ""
+                if dscr:
+                    dscr = dscr.split("\n")
+                    for _d in dscr:
+                        _s += f"\n\t{magenta('# ' + _d)}"
+                        _one_line_dscr += "\u25cf " + _d + "\n"
+
+                _s += f"\n\tstrategy: {green(s_cls)}"
+                _s += f"\n\tinterval: {blue(start)} - {blue(stop)}"
+                _s += f"\n\tcapital: {blue(info.get('capital', ''))} {info.get('base_currency', '')} ({info.get('commissions', '')})"
+                _s += f"\n\tinstruments: {blue(smbs)}"
+                if params:
+                    formats = ["{" + f":<{i}" + "}" for i in [50]]
+                    _p = pd.DataFrame.from_dict(info.get("parameters", {}), orient="index")
+                    for i in _p.to_string(
+                        max_colwidth=30,
+                        header=False,
+                        formatters=[(lambda x: cyan(fmt.format(str(x)))) for fmt in formats],
+                        justify="left",
+                    ).split("\n"):
+                        _s += f"\n\t  |  {yellow(i)}"
 
-            if with_metrics:
-                _m_repr = (
-                    pd.DataFrame.from_dict(metrics, orient="index")
-                    .T[["gain", "cagr", "sharpe", "qr", "max_dd_pct", "mdd_usd", "fees", "execs"]]
-                    .astype(float)
-                )
-                _m_repr = _m_repr.round(3).to_string(index=False)
-                _h, _v = _m_repr.split("\n")
                 if not as_table:
-                    print("\t " + red(_h))
-                    print("\t " + cyan(_v))
-
-            if not as_table:
-                print()
-            else:
-                metrics = {
-                    m: round(v, 3)
-                    for m, v in metrics.items()
-                    if m in ["gain", "cagr", "sharpe", "qr", "max_dd_pct", "mdd_usd", "fees", "execs"]
-                }
-                _t_rep.append(
-                    {"Index": info.get("idx", ""), "Strategy": name}
-                    | metrics
-                    | {
-                        "start": start,
-                        "stop": stop,
-                        "Created": created,
-                        "Author": author,
-                        "Description": _one_line_dscr,
-                    },
-                )
+                    print(_s)
+
+                if with_metrics:
+                    _m_repr = (
+                        pd.DataFrame.from_dict(metrics, orient="index")
+                        .T[["gain", "cagr", "sharpe", "qr", "max_dd_pct", "mdd_usd", "fees", "execs"]]
+                        .astype(float)
+                    )
+                    _m_repr = _m_repr.round(3).to_string(index=False)
+                    _h, _v = _m_repr.split("\n")
+                    if not as_table:
+                        print("\t " + red(_h))
+                        print("\t " + cyan(_v))
+
+                if not as_table:
+                    print()
+                else:
+                    metrics = {
+                        m: round(v, 3)
+                        for m, v in metrics.items()
+                        if m in ["gain", "cagr", "sharpe", "qr", "max_dd_pct", "mdd_usd", "fees", "execs"]
+                    }
+                    _t_rep.append(
+                        {"Index": info.get("idx", ""), "Strategy": name}
+                        | metrics
+                        | {
+                            "start": start,
+                            "stop": stop,
+                            "Created": created,
+                            "Author": author,
+                            "Description": _one_line_dscr,
+                        },
+                    )
 
         # - variations (only if not as_table for the time being)
         if not as_table and show_variations:
@@ -358,11 +386,12 @@ class BacktestsResultsManager:
                 _m_repr = _m_repr.to_string(index=True)
 
                 print(_s)
-                for _i, _l in enumerate(_m_repr.split("\n")):
-                    if _i == 0:
-                        print("\t " + red(_l))
-                    else:
-                        print("\t " + blue(_l))
+                if show_each_variation_run:
+                    for _i, _l in enumerate(_m_repr.split("\n")):
+                        if _i == 0:
+                            print("\t " + red(_l))
+                        else:
+                            print("\t " + blue(_l))
 
         if as_table:
             _df = pd.DataFrame.from_records(_t_rep, index="Index")
@@ -376,3 +405,105 @@ class BacktestsResultsManager:
                     .replace("<td>", '<td align="left" valign="top">')
                 )
             return _df
+
+    def variation_plot(self, variation_idx: int, criterion: str = "sharpe", ascending: bool = False, n=3, h=600):
+        """
+        Plot a variation of a backtest result.
+
+        Args:
+            - variation_idx (int): The index of the variation to plot.
+            - criterion (str): The criterion to plot (e.g. "sharpe", "mdd_usd", "max_dd_pct", etc.).
+            - ascending (bool): Whether to sort the results in ascending order.
+            - n (int): The number of decimal places to display.
+            - h (int): The height of the plot.
+
+        Returns:
+            plotly.graph_objects.Figure: The plot of the variation.
+        """
+        import plotly.express as px
+        from itertools import cycle
+        from qubx.utils.misc import string_shortener
+
+        _vars = self.variations.get(variation_idx)
+        if not _vars:
+            raise ValueError(f"No variations found for index {variation_idx} !")
+
+        variations = _vars.get("variations", [])
+        name = _vars.get("name", "") or ""
+
+        _r, _p = {}, {}
+        for i, v in enumerate(variations):
+            _p[i] = v["parameters"]
+        _pp = pd.DataFrame.from_records(_p).T
+        # - changed parameters
+        _cp = []
+        for c in _pp.columns:
+            if len(_pp[c].astype(str).unique()) > 1:
+                _cp.append(c)
+
+        # - if nothing was actually changed in parameters, raise an error
+        if not _cp:
+            raise ValueError(f"No variable parameters found for simulation {name} !")
+
+        _ms = max([len(string_shortener(x)) for x in _cp]) + 3
+        _h = "".join([string_shortener(x).center(_ms) for x in _cp])
+
+        _sel = lambda ds, _cp: "".join(
+            [
+                f"<span style='color:{c}'> {str(ds[k]).center(_ms)}</span>"
+                for k, c in zip(_cp, cycle(px.colors.qualitative.Plotly))
+                if k in k in ds
+            ]
+        )
+        for i, v in enumerate(variations):
+            _r[i] = {"name": v["name"], **v["performance"], "parameters": _sel(v["parameters"], _cp)}
+
+        t1 = pd.DataFrame.from_records(_r).T
+        if criterion not in t1.columns:
+            raise ValueError(f"Criterion {criterion} not found in results: possible values are {t1.columns}")
+        t2 = t1.sort_values(criterion, ascending=ascending)
+
+        data = pd.Series([np.nan, *t2[criterion].to_list()], index=[_h, *t2["parameters"].to_list()])
+
+        figure = (
+            px.bar(data, orientation="h")
+            .update_layout(
+                title=dict(
+                    text=f"{name} | <span style='color:orange'>{criterion.capitalize()}</span>",
+                ),
+                xaxis=dict(tickfont=dict(family="monospace", size=10, color="#ff4000")),
+                yaxis=dict(
+                    tickfont=dict(family="monospace", size=10, color="#40a000"),
+                    dtick=1,
+                ),
+            )
+            .update_layout(
+                height=h,
+                hovermode="x unified",
+                showlegend=False,
+                hoverdistance=1,
+                yaxis={"hoverformat": f".{n}f"},
+                dragmode="zoom",
+                newshape=dict(line_color="red", line_width=1.0),
+                modebar_add=["drawline", "drawopenpath", "drawrect", "eraseshape"],
+                hoverlabel=dict(align="auto", bgcolor="rgba(10, 10, 10, 0.5)"),
+            )
+            .update_xaxes(
+                showspikes=True,
+                spikemode="across",
+                spikesnap="cursor",
+                spikecolor="#306020",
+                spikethickness=1,
+                spikedash="dot",
+                title=criterion,
+            )
+            .update_yaxes(
+                spikesnap="cursor",
+                spikecolor="#306020",
+                tickformat=f".{n}f",
+                spikethickness=1,
+                title="Parameters",
+                autorange="reversed",
+            )
+        )
+        return figure

{qubx-0.6.53 → qubx-0.6.56}/src/qubx/backtester/runner.py

@@ -439,7 +439,7 @@ class SimulationRunner:
         if isinstance(commissions, (str, type(None))):
             commissions = {e: commissions for e in exchanges}
         for exchange in exchanges:
-            _exchange_to_tcc[exchange] = lookup.fees.find(exchange.lower(), commissions.get(exchange))
+            _exchange_to_tcc[exchange] = lookup.find_fees(exchange.lower(), commissions.get(exchange))
         return _exchange_to_tcc
 
     def _construct_account_processor(

{qubx-0.6.53 → qubx-0.6.56}/src/qubx/core/basics.py

@@ -1,3 +1,4 @@
+import re
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import StrEnum
@@ -176,6 +177,14 @@ class MarketType(StrEnum):
 
 @dataclass
 class Instrument:
+    """
+    Instrument class.
+
+     - 2025-06-11: Important change for FUTURE type: now instrument's symbol contains delivery date in format YYYYMMDD.
+        So now for let's say september's BTCUSDT future, symbol would be BTCUSD.20250914
+        and full id is `BINANCE.UM:FUTURE:BTCUSD.20250914`
+    """
+
     symbol: str
     asset_type: AssetType
     market_type: MarketType
@@ -192,8 +201,10 @@ class Instrument:
     maint_margin: float = 0.0  # maintenance margin
     liquidation_fee: float = 0.0  # liquidation fee
     contract_size: float = 1.0  # contract size
-    onboard_date: datetime | None = None
-    delivery_date: datetime | None = None
+    onboard_date: datetime | None = None  # date when instrument was listed on the exchange
+    delivery_date: datetime | None = None  # date when instrument is delivered
+    delist_date: datetime | None = None  # date when instrument is delisted
+    inverse: bool = False  # if true, then the future is inverse
 
     @property
     def price_precision(self):
@@ -437,9 +448,6 @@ class AssetBalance:
         return self
 
 
-MARKET_TYPE = Literal["SPOT", "MARGIN", "SWAP", "FUTURES", "OPTION"]
-
-
 class Position:
     instrument: Instrument  # instrument for this position
     quantity: float = 0.0  # quantity positive for long and negative for short
@@ -878,3 +886,101 @@ class RestoredState:
     balances: dict[str, AssetBalance]
     instrument_to_target_positions: dict[Instrument, list[TargetPosition]]
     positions: dict[Instrument, Position]
+
+
+class InstrumentsLookup:
+    def get_lookup(self) -> dict[str, Instrument]: ...
+
+    def find(
+        self,
+        exchange: str,
+        base: str,
+        quote: str,
+        settle: str | None = None,
+        market_type: MarketType | None = None,
+    ) -> Instrument | None:
+        for i in self.get_lookup().values():
+            if (
+                i.exchange == exchange
+                and ((i.base == base and i.quote == quote) or (i.base == quote and i.quote == base))
+                and (market_type is None or i.market_type == market_type)
+            ):
+                if settle is not None and i.settle is not None:
+                    if i.settle == settle:
+                        return i
+                else:
+                    return i
+        return None
+
+    def find_symbol(self, exchange: str, symbol: str, market_type: MarketType | None = None) -> Instrument | None:
+        for i in self.get_lookup().values():
+            if (
+                (i.exchange == exchange)
+                and (i.symbol == symbol)
+                and (market_type is None or i.market_type == market_type)
+            ):
+                return i
+
+        return None
+
+    def find_instruments(
+        self,
+        exchange: str,
+        quote: str | None = None,
+        market_type: MarketType | None = None,
+        as_of: str | pd.Timestamp | None = None,
+    ) -> list[Instrument]:
+        """
+        Find instruments by exchange, quote, market type and as of date.
+        If as_of is not None, then only instruments that are not delisted after as_of date will be returned.
+        - exchange: str - exchange name
+        - quote: str | None - quote currency
+        - market_type: MarketType | None - market type
+        - as_of is a string in format YYYY-MM-DD or pd.Timestamp or None
+        """
+        _limit_time = pd.Timestamp(as_of) if as_of else None
+        return [
+            i
+            for i in self.get_lookup().values()
+            if i.exchange == exchange
+            and (quote is None or i.quote == quote)
+            and (market_type is None or i.market_type == market_type)
+            and (
+                _limit_time is None
+                or (i.delist_date is None)
+                or (pd.Timestamp(i.delist_date).tz_localize(None) >= _limit_time)
+            )
+        ]
+
+    def find_aux_instrument_for(
+        self, instrument: Instrument, base_currency: str, market_type: MarketType | None = None
+    ) -> Instrument | None:
+        """
+        Tries to find aux instrument (for conversions to funded currency)
+        for example:
+            ETHBTC -> BTCUSDT for base_currency USDT
+            EURGBP -> GBPUSD for base_currency USD
+            ...
+        """
+        if market_type is None:
+            market_type = instrument.market_type
+        base_currency = base_currency.upper()
+        if instrument.quote != base_currency:
+            return self.find(instrument.exchange, instrument.quote, base_currency, market_type=market_type)
+        return None
+
+    def __getitem__(self, spath: str) -> list[Instrument]:
+        """
+        Helper method for finding instruments by pattern.
+        It's convenient to use in research mode.
+        """
+        res = []
+        c = re.compile(spath)
+        for k, v in self.get_lookup().items():
+            if re.match(c, k):
+                res.append(v)
+        return res
+
+
+class FeesLookup:
+    def find_fees(self, exchange: str, spec: str | None) -> TransactionCostsCalculator: ...

{qubx-0.6.53 → qubx-0.6.56}/src/qubx/core/helpers.py

@@ -6,15 +6,15 @@ import time
 from collections import defaultdict, deque
 from inspect import isbuiltin, isclass, isfunction, ismethod, ismethoddescriptor
 from threading import Thread
-from typing import Any, Callable, Dict, List
+from typing import Any, Callable
 
 import numpy as np
 import pandas as pd
 from croniter import croniter
 
 from qubx import logger
-from qubx.core.basics import SW, CtrlChannel, DataType, Instrument, Timestamped
-from qubx.core.series import OHLCV, Bar, OrderBook, Quote, Trade
+from qubx.core.basics import SW, CtrlChannel, DataType, Instrument, Timestamped, dt_64
+from qubx.core.series import OHLCV, Bar, OrderBook, Quote, Trade, time_as_nsec
 from qubx.utils.time import convert_seconds_to_str, convert_tf_str_td64, interval_to_cron
 
 
@@ -26,9 +26,9 @@ class CachedMarketDataHolder:
     default_timeframe: np.timedelta64
     _last_bar: dict[Instrument, Bar | None]
     _ohlcvs: dict[Instrument, dict[np.timedelta64, OHLCV]]
-    _updates: dict[Instrument, Any]
+    _updates: dict[Instrument, Bar | Quote | Trade]
 
-    _instr_to_sub_to_buffer: Dict[Instrument, Dict[str, deque]]
+    _instr_to_sub_to_buffer: dict[Instrument, dict[str, deque]]
 
     def __init__(self, default_timeframe: str | None = None, max_buffer_size: int = 10_000) -> None:
         self._ohlcvs = dict()
@@ -93,7 +93,7 @@ class CachedMarketDataHolder:
 
         return self._ohlcvs[instrument][tf]
 
-    def get_data(self, instrument: Instrument, event_type: str) -> List[Any]:
+    def get_data(self, instrument: Instrument, event_type: str) -> list[Any]:
         return list(self._instr_to_sub_to_buffer[instrument][event_type])
 
     def update(
@@ -126,7 +126,7 @@ class CachedMarketDataHolder:
                 pass
 
     @SW.watch("CachedMarketDataHolder")
-    def update_by_bars(self, instrument: Instrument, timeframe: str | np.timedelta64, bars: List[Bar]) -> OHLCV:
+    def update_by_bars(self, instrument: Instrument, timeframe: str | np.timedelta64, bars: list[Bar]) -> OHLCV:
         """
         Update or create OHLCV series with the provided historical bars.
 
@@ -203,6 +203,17 @@ class CachedMarketDataHolder:
                     continue
                 ser.update(trade.time, trade.price, total_vol, bought_vol)
 
+    def finalize_all_ohlc(self, time: dt_64):
+        """
+        Finalize all OHLCV series at the given time.
+        FIXME: (2025-06-17) This is part of urgent live fix and must be removed in future !!!.
+        """
+        for instrument in self._ohlcvs.keys():
+            # - use most recent update
+            if (_u := self._updates.get(instrument)) is not None:
+                _px = extract_price(_u)
+                self.update_by_bar(instrument, Bar(time_as_nsec(time), _px, _px, _px, _px, 0, 0))
+
 
 SPEC_REGEX = re.compile(
     r"((?P<type>[A-Za-z]+)(\.?(?P<timeframe>[0-9A-Za-z]+))?\ *:)?"