sorted by sum(cum_rank)

.envrc

@@ -0,0 +1 @@
+source /home/oleg/.pyenv/python3.12-venv/bin/activate

.gitignore

@@ -5,8 +5,8 @@ __OLD__/
 .history/
 .cursorindexingignore
 data
-.vscode/
 cvttpy
 # SpecStory explanation file
 .specstory/.what-is-this.md
 results/
+tmp/

.vscode/.env

@@ -0,0 +1 @@
+PYTHONPATH=/home/oleg/develop

.vscode/launch.json

@@ -0,0 +1,133 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+    
+
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "python": "/home/oleg/.pyenv/python3.12-venv/bin/python",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/lib:${workspaceFolder}/.."
+            },
+        },
+        {
+            "name": "-------- VECM --------",
+        },
+        {
+            "name": "CRYPTO VECM BACKTEST (optimized)",
+            "type": "debugpy",
+            "request": "launch",
+            "python": "/home/oleg/.pyenv/python3.12-venv/bin/python",
+            "program": "${workspaceFolder}/research/backtest.py",
+            "args": [
+                "--config=http://cloud16.cvtt.vpn:6789/apps/pairs_trading/backtest",
+                "--instruments=CRYPTO:BNBSPOT:PAIR-ADA-USDT,CRYPTO:BNBSPOT:PAIR-SOL-USDT",
+                "--date_pattern=20250911",
+                "--result_db=${workspaceFolder}/research/results/crypto/%T.vecm-opt.ADA-SOL.20250605.crypto_results.db",            
+            ],
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/..",
+                "CONFIG_SERVICE": "cloud16.cvtt.vpn:6789",
+                "MODEL_CONFIG": "vecm-opt"
+            },
+            "console": "integratedTerminal"
+        },
+        // {
+        //     "name": "EQUITY VECM (rolling)",
+        //     "type": "debugpy",
+        //     "request": "launch",
+        //     "python": "/home/oleg/.pyenv/python3.12-venv/bin/python",
+        //     "program": "${workspaceFolder}/research/backtest.py",
+        //     "args": [
+        //         "--config=${workspaceFolder}/configuration/vecm.cfg",
+        //         "--instruments=COIN:EQUITY:ALPACA,MSTR:EQUITY:ALPACA",
+        //         "--date_pattern=20250605",
+        //         "--result_db=${workspaceFolder}/research/results/equity/%T.vecm.COIN-MSTR.20250605.equity_results.db",            
+        //     ],
+        //     "env": {
+        //         "PYTHONPATH": "${workspaceFolder}/lib"
+        //     },
+        //     "console": "integratedTerminal"
+        // },
+        // {
+        //     "name": "EQUITY-CRYPTO VECM (rolling)",
+        //     "type": "debugpy",
+        //     "request": "launch",
+        //     "python": "/home/oleg/.pyenv/python3.12-venv/bin/python",
+        //     "program": "${workspaceFolder}/research/backtest.py",
+        //     "args": [
+        //         "--config=${workspaceFolder}/configuration/vecm.cfg",
+        //         "--instruments=COIN:EQUITY:ALPACA,BTC-USDT:CRYPTO:BNBSPOT",
+        //         "--date_pattern=20250605",
+        //         "--result_db=${workspaceFolder}/research/results/intermarket/%T.vecm.COIN-BTC.20250601.equity_results.db",            
+        //     ],
+        //     "env": {
+        //         "PYTHONPATH": "${workspaceFolder}/lib"
+        //     },
+        //     "console": "integratedTerminal"
+        // },
+        {
+            "name": "-------- B a t c h e s --------",
+        },
+        {
+            "name": "CRYPTO OLS Batch (rolling)",
+            "type": "debugpy",
+            "request": "launch",
+            "python": "/home/oleg/.pyenv/python3.12-venv/bin/python",
+            "program": "${workspaceFolder}/research/backtest.py",
+            "args": [
+                "--config=${workspaceFolder}/configuration/ols.cfg",
+                "--instruments=ADA-USDT:CRYPTO:BNBSPOT,SOL-USDT:CRYPTO:BNBSPOT",
+                "--date_pattern=2025060*",
+                "--result_db=${workspaceFolder}/research/results/crypto/%T.ols.ADA-SOL.2025060-.crypto_results.db",            
+            ],
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/lib"
+            },
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "CRYPTO VECM Batch (rolling)",
+            "type": "debugpy",
+            "request": "launch",
+            "python": "/home/oleg/.pyenv/python3.12-venv/bin/python",
+            "program": "${workspaceFolder}/research/backtest.py",
+            "args": [
+                "--config=${workspaceFolder}/configuration/vecm.cfg",
+                "--instruments=ADA-USDT:CRYPTO:BNBSPOT,SOL-USDT:CRYPTO:BNBSPOT",
+                "--date_pattern=2025060*",
+                "--result_db=${workspaceFolder}/research/results/crypto/%T.vecm.ADA-SOL.2025060-.crypto_results.db",            
+            ],
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/lib"
+            },
+            "console": "integratedTerminal"
+        },
+        {
+            "name": "-------- Viz Test --------",
+        },
+        {
+            "name": "Viz Test",
+            "type": "debugpy",
+            "request": "launch",
+            "python": "/home/oleg/.pyenv/python3.12-venv/bin/python",
+            "program": "${workspaceFolder}/tests/viz_test.py",
+            "args": [
+                "--config=${workspaceFolder}/configuration/ols.cfg",
+                "--instruments=ADA-USDT:CRYPTO:BNBSPOT,SOL-USDT:CRYPTO:BNBSPOT",
+                "--date_pattern=20250605",
+            ],
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/lib"
+            },
+            "console": "integratedTerminal"
+        }
+    ]
+}

.vscode/pairs_trading.code-workspace

@@ -0,0 +1,10 @@
+{
+    "folders": [
+        {
+            "path": ".."
+        }
+    ],
+    "settings": {
+        "workbench.colorTheme": "Dracula Theme"
+    }
+}

.vscode/settings.json

@@ -0,0 +1,19 @@
+{
+    "python.testing.pytestEnabled": true,
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestArgs": [
+        "unittests"
+    ],
+    "python.testing.cwd": "${workspaceFolder}",
+    "python.testing.autoTestDiscoverOnSaveEnabled": true,
+    "python.testing.pytestPath": "python3",
+    "python.analysis.extraPaths": [
+        "${workspaceFolder}",
+        "${workspaceFolder}/..",
+        "${workspaceFolder}/unittests"
+    ],
+    "python.envFile": "${workspaceFolder}/.env",
+    "python.testing.debugPort": 3000,
+    "python.testing.promptToConfigure": false,
+    "python.defaultInterpreterPath": "/home/oleg/.pyenv/python3.12-venv/bin/python"
+}

PAIRS_TRADING_BACKTEST_USAGE.md

@@ -11,6 +11,7 @@ The enhanced `pt_backtest.py` script now supports multi-day and multi-instrument
 - Support for wildcard patterns in configuration files
 - CLI override for data file specification
 
+
 ### 2. Dynamic Instrument Selection
 - Auto-detection of instruments from database
 - CLI override for instrument specification

README.md

@@ -38,15 +38,12 @@ CONFIG = EQT_CONFIG      # For equity data
 ```
 
 Each configuration dictionary specifies:
-- `security_type`: "CRYPTO" or "EQUITY".
 - `data_directory`: Path to the data files.
 - `datafiles`: A list of database files to process. You can comment/uncomment specific files to include/exclude them from the backtest.
 - `db_table_name`: The name of the table within the SQLite database.
 - `instruments`: A list of symbols to consider for forming trading pairs.
 - `trading_hours`: Defines the session start and end times, crucial for equity markets.
-- `price_column`: The column in the data to be used as the price (e.g., "close").
-- `min_required_points`: Minimum data points needed for statistical calculations.
-- `zero_threshold`: A small value to handle potential division by zero.
+- `stat_model_price`: The column in the data to be used as the price (e.g., "close").
 - `dis-equilibrium_open_trshld`: The threshold (in standard deviations) of the dis-equilibrium for opening a trade.
 - `dis-equilibrium_close_trshld`: The threshold (in standard deviations) of the dis-equilibrium for closing an open trade.
 - `training_minutes`: The length of the rolling window (in minutes) used to train the model (e.g., calculate cointegration, mean, and standard deviation of the dis-equilibrium).

VERSION

@@ -0,0 +1 @@
+0.0.8

apps/pair_selector/pair_selector.py

@@ -0,0 +1,937 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import sqlite3
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence, Set, Tuple, Union
+
+from aiohttp import web
+import numpy as np
+import pandas as pd
+from statsmodels.tsa.stattools import adfuller, coint # type: ignore
+from statsmodels.tsa.vector_ar.vecm import coint_johansen  # type: ignore
+
+
+from cvttpy_tools.app import App
+from cvttpy_tools.base import NamedObject
+from cvttpy_tools.config import Config, CvttAppConfig
+from cvttpy_tools.logger import Log
+from cvttpy_tools.timeutils import NanoPerSec, SecPerHour, current_nanoseconds
+from cvttpy_tools.web.rest_client import RESTSender
+from cvttpy_tools.web.rest_service import RestService
+
+from cvttpy_trading.trading.exchange_config import ExchangeAccounts
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+from cvttpy_trading.trading.mkt_data.md_summary import MdTradesAggregate, MdSummary
+
+from pairs_trading.apps.pair_selector.renderer import HtmlRenderer
+
+
+@dataclass
+class BacktestAggregate:
+    aggr_time_ns_: int
+    num_trades_: Optional[int]
+
+
+@dataclass
+class InstrumentQuality(NamedObject):
+    instrument_: ExchangeInstrument
+    record_count_: int
+    latest_tstamp_: Optional[pd.Timestamp]
+    status_: str
+    reason_: str
+
+
+@dataclass
+class PairStats(NamedObject):
+    pair_name_: str
+    instrument_a_: ExchangeInstrument
+    instrument_b_: ExchangeInstrument
+    pvalue_eg_: Optional[float]
+    pvalue_adf_: Optional[float]
+    pvalue_j_: Optional[float]
+    trace_stat_j_: Optional[float]
+    rank_eg_: int = 0
+    rank_adf_: int = 0
+    rank_j_: int = 0
+    composite_rank_: int = 0
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "exchange_a": self.instrument_a_.exchange_id_,
+            "exchange_b": self.instrument_b_.exchange_id_,
+            "pair_name": self.pair_name_,
+            "instrument_a": self.instrument_a_.instrument_id(),
+            "instrument_b": self.instrument_b_.instrument_id(),
+            "pvalue_eg": self.pvalue_eg_,
+            "pvalue_adf": self.pvalue_adf_,
+            "pvalue_j": self.pvalue_j_,
+            "trace_stat_j": self.trace_stat_j_,
+            "rank_eg": self.rank_eg_,
+            "rank_adf": self.rank_adf_,
+            "rank_j": self.rank_j_,
+            "composite_rank": self.composite_rank_,
+        }
+
+
+def _extract_price_from_fields(
+    price_field: str,
+    inst: ExchangeInstrument,
+    open: Optional[float],
+    high: Optional[float],
+    low: Optional[float],
+    close: Optional[float],
+    vwap: Optional[float],
+) -> float:
+    field_map = {
+        "open": open,
+        "high": high,
+        "low": low,
+        "close": close,
+        "vwap": vwap,
+    }
+    raw = field_map.get(price_field, close)
+    if raw is None:
+        raw = 0.0
+    return inst.get_price(raw)
+
+
+class DataFetcher(NamedObject):
+    sender_: RESTSender
+    interval_sec_: int
+    history_depth_sec_: int
+
+    def __init__(
+        self,
+        base_url: str,
+        interval_sec: int,
+        history_depth_sec: int,
+    ) -> None:
+        self.sender_ = RESTSender(base_url=base_url)
+        self.interval_sec_ = interval_sec
+        self.history_depth_sec_ = history_depth_sec
+
+    def fetch(
+        self, exch_acct: str, inst: ExchangeInstrument
+    ) -> List[MdTradesAggregate]:
+        rqst_data = {
+            "exch_acct": exch_acct,
+            "instrument_id": inst.instrument_id(),
+            "interval_sec": self.interval_sec_,
+            "history_depth_sec": self.history_depth_sec_,
+        }
+        response = self.sender_.send_post(endpoint="md_summary", post_body=rqst_data)
+        if response.status_code not in (200, 201):
+            Log.error(
+                f"{self.fname()}: error {response.status_code} for {inst.details_short()}: {response.text}"
+            )
+            return []
+        mdsums: List[MdSummary] = MdSummary.from_REST_response(response=response)
+        return [
+            mdsum.create_md_trades_aggregate(
+                exch_acct=exch_acct, exch_inst=inst, interval_sec=self.interval_sec_
+            )
+            for mdsum in mdsums
+        ]
+
+
+AggregateLike = Union[MdTradesAggregate, BacktestAggregate]
+
+
+class QualityChecker(NamedObject):
+    interval_sec_: int
+
+    def __init__(self, interval_sec: int) -> None:
+        self.interval_sec_ = interval_sec
+
+    def evaluate(
+        self,
+        inst: ExchangeInstrument,
+        aggr: Sequence[AggregateLike],
+        now_ts: Optional[pd.Timestamp] = None,
+    ) -> InstrumentQuality:
+        if len(aggr) == 0:
+            return InstrumentQuality(
+                instrument_=inst,
+                record_count_=0,
+                latest_tstamp_=None,
+                status_="FAIL",
+                reason_="no records",
+            )
+
+        aggr_sorted = sorted(aggr, key=lambda a: a.aggr_time_ns_)
+
+        latest_ts = pd.to_datetime(aggr_sorted[-1].aggr_time_ns_, unit="ns", utc=True)
+        now_ts = now_ts or pd.Timestamp.utcnow()
+        recency_cutoff = now_ts - pd.Timedelta(seconds=2 * self.interval_sec_)
+        if latest_ts <= recency_cutoff:
+            return InstrumentQuality(
+                instrument_=inst,
+                record_count_=len(aggr_sorted),
+                latest_tstamp_=latest_ts,
+                status_="FAIL",
+                reason_=f"stale: latest {latest_ts} <= cutoff {recency_cutoff}",
+            )
+
+        gaps_ok, reason = self._check_gaps(aggr_sorted)
+        status = "PASS" if gaps_ok else "FAIL"
+        return InstrumentQuality(
+            instrument_=inst,
+            record_count_=len(aggr_sorted),
+            latest_tstamp_=latest_ts,
+            status_=status,
+            reason_=reason,
+        )
+
+    def _check_gaps(self, aggr: Sequence[AggregateLike]) -> Tuple[bool, str]:
+        NUM_TRADES_THRESHOLD = 50
+        if len(aggr) < 2:
+            return True, "ok"
+
+        interval_ns = self.interval_sec_ * NanoPerSec
+        for idx in range(1, len(aggr)):
+            prev = aggr[idx - 1]
+            curr = aggr[idx]
+            delta = curr.aggr_time_ns_ - prev.aggr_time_ns_
+            missing_intervals = int(delta // interval_ns) - 1
+            if missing_intervals <= 0:
+                continue
+
+            prev_nt = prev.num_trades_
+            next_nt = curr.num_trades_
+            estimate = self._approximate_num_trades(prev_nt, next_nt)
+            if estimate > NUM_TRADES_THRESHOLD:
+                return False, (
+                    f"gap of {missing_intervals} interval(s), est num_trades={estimate} > {NUM_TRADES_THRESHOLD}"
+                )
+        return True, "ok"
+
+    @staticmethod
+    def _approximate_num_trades(prev_nt: Optional[int], next_nt: Optional[int]) -> float:
+        if prev_nt is None and next_nt is None:
+            return 0.0
+        if prev_nt is None:
+            return float(next_nt or 0)
+        if next_nt is None:
+            return float(prev_nt)
+        return (prev_nt + next_nt) / 2.0
+
+
+class PairAnalyzer(NamedObject):
+    price_field_: str
+    interval_sec_: int
+
+    def __init__(self, price_field: str, interval_sec: int) -> None:
+        self.price_field_ = price_field
+        self.interval_sec_ = interval_sec
+
+    def analyze(
+        self, series: Dict[ExchangeInstrument, pd.DataFrame]
+    ) -> Dict[str, PairStats]:
+        instruments = list(series.keys())
+        results: Dict[str, PairStats] = {}
+        for i in range(len(instruments)):
+            for j in range(i + 1, len(instruments)):
+                inst_a, inst_b, pair_name = self._normalized_pair(
+                    instruments[i], instruments[j]
+                )
+                df_a = series[inst_a][["tstamp", "price"]].rename(
+                    columns={"price": "price_a"}
+                )
+                df_b = series[inst_b][["tstamp", "price"]].rename(
+                    columns={"price": "price_b"}
+                )
+                merged = pd.merge(df_a, df_b, on="tstamp", how="inner").sort_values(
+                    "tstamp"
+                )
+                # Log.info(f"{self.fname()}: analyzing {pair_name}")
+                stats = self._compute_stats(inst_a, inst_b, pair_name, merged)
+                if stats:
+                    results[pair_name] = stats
+        return self._rank(results)
+
+    def _compute_stats(
+        self,
+        inst_a: ExchangeInstrument,
+        inst_b: ExchangeInstrument,
+        pair_name: str,
+        merged: pd.DataFrame,
+    ) -> Optional[PairStats]:
+        if len(merged) < 2:
+            return None
+        px_a = merged["price_a"].astype(float)
+        px_b = merged["price_b"].astype(float)
+
+        std_a = float(px_a.std())
+        std_b = float(px_b.std())
+        if std_a == 0 or std_b == 0:
+            return None
+
+        z_a = (px_a - float(px_a.mean())) / std_a
+        z_b = (px_b - float(px_b.mean())) / std_b
+
+        p_eg: Optional[float]
+        p_adf: Optional[float]
+        p_j: Optional[float]
+        trace_stat: Optional[float]
+
+        try:
+            p_eg = float(coint(z_a, z_b)[1])
+        except Exception as exc:
+            Log.warning(
+                f"{self.fname()}: EG failed for {inst_a.details_short()}/{inst_b.details_short()}: {exc}"
+            )
+            p_eg = None
+
+        try:
+            spread = z_a - z_b
+            p_adf = float(adfuller(spread, maxlag=1, regression="c")[1])
+        except Exception as exc:
+            Log.warning(
+                f"{self.fname()}: ADF failed for {inst_a.details_short()}/{inst_b.details_short()}: {exc}"
+            )
+            p_adf = None
+
+        try:
+            data = np.column_stack([z_a, z_b])
+            res = coint_johansen(data, det_order=0, k_ar_diff=1)
+            trace_stat = float(res.lr1[0])
+            cv10, cv5, cv1 = res.cvt[0]
+            if trace_stat > cv1:
+                p_j = 0.01
+            elif trace_stat > cv5:
+                p_j = 0.05
+            elif trace_stat > cv10:
+                p_j = 0.10
+            else:
+                p_j = 1.0
+        except Exception as exc:
+            Log.warning(
+                f"{self.fname()}: Johansen failed for {inst_a.details_short()}/{inst_b.details_short()}: {exc}"
+            )
+            p_j = None
+            trace_stat = None
+
+        return PairStats(
+            pair_name_=pair_name,
+            instrument_a_=inst_a,
+            instrument_b_=inst_b,
+            pvalue_eg_=p_eg,
+            pvalue_adf_=p_adf,
+            pvalue_j_=p_j,
+            trace_stat_j_=trace_stat,
+        )
+
+    def _rank(self, results: Dict[str, PairStats]) -> Dict[str, PairStats]:
+        ranked = list(results.values())
+        self._assign_ranks(ranked, key=lambda r: r.pvalue_eg_, attr="rank_eg_")
+        self._assign_ranks(ranked, key=lambda r: r.pvalue_adf_, attr="rank_adf_")
+        self._assign_ranks(ranked, key=lambda r: r.pvalue_j_, attr="rank_j_")
+        for res in ranked:
+            res.composite_rank_ = res.rank_eg_ + res.rank_adf_ # + res.rank_j_
+        ranked.sort(key=lambda r: r.composite_rank_)
+        return {res.pair_name_: res for res in ranked}
+
+    @staticmethod
+    def _normalized_pair(
+        inst_a: ExchangeInstrument, inst_b: ExchangeInstrument
+    ) -> Tuple[ExchangeInstrument, ExchangeInstrument, str]:
+        inst_a_id = PairAnalyzer._pair_label(inst_a.instrument_id())
+        inst_b_id = PairAnalyzer._pair_label(inst_b.instrument_id())
+        if inst_a_id <= inst_b_id:
+            return inst_a, inst_b, f"{inst_a_id}<->{inst_b_id}"
+        return inst_b, inst_a, f"{inst_b_id}<->{inst_a_id}"
+
+    @staticmethod
+    def _pair_label(instrument_id: str) -> str:
+        if instrument_id.startswith("PAIR-"):
+            return instrument_id[len("PAIR-") :]
+        return instrument_id
+
+    @staticmethod
+    def _assign_ranks(results: List[PairStats], key, attr: str) -> None:
+        values = [key(r) for r in results]
+        sorted_vals = sorted([v for v in values if v is not None])
+        for res in results:
+            val = key(res)
+            if val is None:
+                setattr(res, attr, len(sorted_vals) + 1)
+                continue
+            rank = 1 + sum(1 for v in sorted_vals if v < val)
+            setattr(res, attr, rank)
+
+
+class PairSelectionEngine(NamedObject):
+    config_: object
+    instruments_: List[ExchangeInstrument]
+    price_field_: str
+    fetcher_: DataFetcher
+    quality_: QualityChecker
+    analyzer_: PairAnalyzer
+    interval_sec_: int
+    history_depth_sec_: int
+    data_quality_cache_: List[InstrumentQuality]
+    pair_results_cache_: Dict[str, PairStats]
+
+    def __init__(
+        self,
+        config: Config,
+        instruments: List[ExchangeInstrument],
+        price_field: str,
+    ) -> None:
+        self.config_ = config
+        self.instruments_ = instruments
+        self.price_field_ = price_field
+
+        interval_sec = int(config.get_value("interval_sec", 0))
+        history_depth_sec = int(config.get_value("history_depth_hours", 0)) * SecPerHour
+        base_url = config.get_value("cvtt_base_url", None)
+        assert interval_sec > 0, "interval_sec must be > 0"
+        assert history_depth_sec > 0, "history_depth_sec must be > 0"
+        assert base_url, "cvtt_base_url must be set"
+
+        self.fetcher_ = DataFetcher(
+            base_url=base_url,
+            interval_sec=interval_sec,
+            history_depth_sec=history_depth_sec,
+        )
+        self.quality_ = QualityChecker(interval_sec=interval_sec)
+        self.analyzer_ = PairAnalyzer(
+            price_field=price_field, interval_sec=interval_sec
+        )
+
+        self.interval_sec_ = interval_sec
+        self.history_depth_sec_ = history_depth_sec
+
+        self.data_quality_cache_ = []
+        self.pair_results_cache_ = {}
+
+    async def run_once(self) -> None:
+        quality_results: List[InstrumentQuality] = []
+        price_series: Dict[ExchangeInstrument, pd.DataFrame] = {}
+
+        for inst in self.instruments_:
+            exch_acct = inst.user_data_.get("exch_acct") or inst.exchange_id_
+            aggr = self.fetcher_.fetch(exch_acct=exch_acct, inst=inst)
+            q = self.quality_.evaluate(inst, aggr)
+            quality_results.append(q)
+            if q.status_ != "PASS":
+                continue
+            df = self._to_dataframe(aggr, inst)
+            if len(df) > 0:
+                price_series[inst] = df
+        self.data_quality_cache_ = quality_results
+        self.pair_results_cache_ = self.analyzer_.analyze(price_series)
+
+    def _to_dataframe(
+        self, aggr: List[MdTradesAggregate], inst: ExchangeInstrument
+    ) -> pd.DataFrame:
+        rows: List[Dict[str, Any]] = []
+        for item in aggr:
+            rows.append(
+                {
+                    "tstamp": pd.to_datetime(item.aggr_time_ns_, unit="ns", utc=True),
+                    "price": self._extract_price(item, inst),
+                    "num_trades": item.num_trades_,
+                }
+            )
+        df = pd.DataFrame(rows)
+        return df.sort_values("tstamp").reset_index(drop=True)
+
+    def _extract_price(
+        self, aggr: MdTradesAggregate, inst: ExchangeInstrument
+    ) -> float:
+        return _extract_price_from_fields(
+            price_field=self.price_field_,
+            inst=inst,
+            open=aggr.open_,
+            high=aggr.high_,
+            low=aggr.low_,
+            close=aggr.close_,
+            vwap=aggr.vwap_,
+        )
+
+    def sleep_seconds_until_next_cycle(self) -> float:
+        now_ns = current_nanoseconds()
+        interval_ns = self.interval_sec_ * NanoPerSec
+        next_boundary = (now_ns // interval_ns + 1) * interval_ns
+        return max(0.0, (next_boundary - now_ns) / NanoPerSec)
+
+    def quality_dicts(self) -> List[Dict[str, Any]]:
+        res: List[Dict[str, Any]] = []
+        for q in self.data_quality_cache_:
+            res.append(
+                {
+                    "instrument": q.instrument_.instrument_id(),
+                    "record_count": q.record_count_,
+                    "latest_tstamp": (
+                        q.latest_tstamp_.isoformat() if q.latest_tstamp_ else None
+                    ),
+                    "status": q.status_,
+                    "reason": q.reason_,
+                }
+            )
+        return res
+
+    def pair_dicts(self) -> Dict[str, Dict[str, Any]]:
+        return {
+            pair_name: stats.as_dict()
+            for pair_name, stats in self.pair_results_cache_.items()
+        }
+
+
+class PairSelectionBacktest(NamedObject):
+    config_: object
+    instruments_: List[ExchangeInstrument]
+    price_field_: str
+    input_db_: str
+    output_db_: str
+    interval_sec_: int
+    history_depth_hours_: int
+    quality_: QualityChecker
+    analyzer_: PairAnalyzer
+    inst_by_key_: Dict[Tuple[str, str], ExchangeInstrument]
+    inst_by_id_: Dict[str, Optional[ExchangeInstrument]]
+    ambiguous_ids_: Set[str]
+
+    def __init__(
+        self,
+        config: Config,
+        instruments: List[ExchangeInstrument],
+        price_field: str,
+        input_db: str,
+        output_db: str,
+    ) -> None:
+        self.config_ = config
+        self.instruments_ = instruments
+        self.price_field_ = price_field
+        self.input_db_ = input_db
+        self.output_db_ = output_db
+
+        interval_sec = int(config.get_value("interval_sec", 0))
+        if interval_sec <= 0:
+            Log.warning(
+                f"{self.fname()}: interval_sec not set; defaulting to 60 seconds"
+            )
+            interval_sec = 60
+        history_depth_hours = int(config.get_value("history_depth_hours", 0))
+        assert history_depth_hours > 0, "history_depth_hours must be > 0"
+
+        self.interval_sec_ = interval_sec
+        self.history_depth_hours_ = history_depth_hours
+        self.quality_ = QualityChecker(interval_sec=interval_sec)
+        self.analyzer_ = PairAnalyzer(
+            price_field=price_field, interval_sec=interval_sec
+        )
+
+        self.inst_by_key_ = {
+            (inst.exchange_id_, inst.instrument_id()): inst for inst in instruments
+        }
+        self.inst_by_id_ = {}
+        self.ambiguous_ids_ = set()
+        for inst in instruments:
+            inst_id = inst.instrument_id()
+            if inst_id in self.inst_by_id_:
+                existing = self.inst_by_id_[inst_id]
+                if existing is not None and existing.exchange_id_ != inst.exchange_id_:
+                    self.inst_by_id_[inst_id] = None
+                    self.ambiguous_ids_.add(inst_id)
+            elif inst_id not in self.ambiguous_ids_:
+                self.inst_by_id_[inst_id] = inst
+
+        if self.ambiguous_ids_:
+            Log.warning(
+                f"{self.fname()}: ambiguous instrument_id(s) without exchange_id: "
+                f"{sorted(self.ambiguous_ids_)}"
+            )
+
+    def run(self) -> None:
+        df = self._load_input_df()
+        if df.empty:
+            Log.warning(f"{self.fname()}: no rows in md_1min_bars")
+            return
+
+        df = self._filter_instruments(df)
+        if df.empty:
+            Log.warning(f"{self.fname()}: no rows after instrument filtering")
+            return
+
+        conn = self._init_output_db()
+        try:
+            self._run_backtest(df, conn)
+        finally:
+            conn.commit()
+            conn.close()
+
+    def _load_input_df(self) -> pd.DataFrame:
+        if not os.path.exists(self.input_db_):
+            raise FileNotFoundError(f"input_db not found: {self.input_db_}")
+        with sqlite3.connect(self.input_db_) as conn:
+            df = pd.read_sql_query(
+                """
+                SELECT
+                    tstamp,
+                    tstamp_ns,
+                    exchange_id,
+                    instrument_id,
+                    open,
+                    high,
+                    low,
+                    close,
+                    volume,
+                    vwap,
+                    num_trades
+                FROM md_1min_bars
+                """,
+                conn,
+            )
+        if df.empty:
+            return df
+
+        ts_ns = pd.to_datetime(df["tstamp_ns"], unit="ns", utc=True, errors="coerce")
+        ts_txt = pd.to_datetime(df["tstamp"], utc=True, errors="coerce")
+        df["tstamp"] = ts_ns.fillna(ts_txt)
+        df = df.dropna(subset=["tstamp", "instrument_id"]).copy()
+        df["exchange_id"] = df["exchange_id"].fillna("")
+        df["instrument_id"] = df["instrument_id"].astype(str)
+        df["tstamp_ns"] = df["tstamp"].astype("int64")
+        return df.sort_values("tstamp").reset_index(drop=True)
+
+    def _filter_instruments(self, df: pd.DataFrame) -> pd.DataFrame:
+        instrument_ids = {inst.instrument_id() for inst in self.instruments_}
+        df = df[df["instrument_id"].isin(instrument_ids)].copy()
+        if "exchange_id" in df.columns:
+            exchange_ids = {inst.exchange_id_ for inst in self.instruments_}
+            df = df[
+                (df["exchange_id"].isin(exchange_ids)) | (df["exchange_id"] == "")
+            ].copy()
+        return df
+
+    def _init_output_db(self) -> sqlite3.Connection:
+        if os.path.exists(self.output_db_):
+            os.remove(self.output_db_)
+        conn = sqlite3.connect(self.output_db_)
+        conn.execute(
+            """
+            CREATE TABLE pair_selection_history (
+                tstamp TEXT,
+                tstamp_ns INTEGER,
+                pair_name TEXT,
+                exchange_a TEXT,
+                instrument_a TEXT,
+                exchange_b TEXT,
+                instrument_b TEXT,
+                pvalue_eg REAL,
+                pvalue_adf REAL,
+                pvalue_j REAL,
+                trace_stat_j REAL,
+                rank_eg INTEGER,
+                rank_adf INTEGER,
+                rank_j INTEGER,
+                composite_rank REAL
+            )
+            """
+        )
+        conn.execute(
+            """
+            CREATE INDEX idx_pair_selection_history_pair_name
+            ON pair_selection_history (pair_name)
+            """
+        )
+        conn.execute(
+            """
+            CREATE UNIQUE INDEX idx_pair_selection_history_tstamp_pair
+            ON pair_selection_history (tstamp, pair_name)
+            """
+        )
+        conn.commit()
+        return conn
+
+    def _resolve_instrument(
+        self, exchange_id: str, instrument_id: str
+    ) -> Optional[ExchangeInstrument]:
+        if exchange_id:
+            inst = self.inst_by_key_.get((exchange_id, instrument_id))
+            if inst is not None:
+                return inst
+        inst = self.inst_by_id_.get(instrument_id)
+        if inst is None and instrument_id in self.ambiguous_ids_:
+            return None
+        return inst
+
+    def _build_day_series(
+        self, df_day: pd.DataFrame
+    ) -> Dict[ExchangeInstrument, pd.DataFrame]:
+        series: Dict[ExchangeInstrument, pd.DataFrame] = {}
+        group_cols = ["exchange_id", "instrument_id"]
+        for key, group in df_day.groupby(group_cols, dropna=False):
+            exchange_id, instrument_id = key
+            inst = self._resolve_instrument(str(exchange_id or ""), str(instrument_id))
+            if inst is None:
+                continue
+            df_inst = group.copy()
+            df_inst["price"] = [
+                _extract_price_from_fields(
+                    price_field=self.price_field_,
+                    inst=inst,
+                    open=float(row.open), #type: ignore
+                    high=float(row.high), #type: ignore
+                    low=float(row.low), #type: ignore
+                    close=float(row.close), #type: ignore
+                    vwap=float(row.vwap),#type: ignore
+                )
+                for row in df_inst.itertuples(index=False)
+            ]
+            df_inst = df_inst[["tstamp", "tstamp_ns", "price", "num_trades"]]
+            if inst in series:
+                series[inst] = pd.concat([series[inst], df_inst], ignore_index=True)
+            else:
+                series[inst] = df_inst
+        for inst in list(series.keys()):
+            series[inst] = series[inst].sort_values("tstamp").reset_index(drop=True)
+        return series
+
+    def _run_backtest(self, df: pd.DataFrame, conn: sqlite3.Connection) -> None:
+        window_minutes = self.history_depth_hours_ * 60
+        window_td = pd.Timedelta(minutes=window_minutes)
+        step_td = pd.Timedelta(seconds=self.interval_sec_)
+
+        df = df.copy()
+        df["day"] = df["tstamp"].dt.normalize()
+        days = sorted(df["day"].unique())
+        for day in days:
+            day_label = pd.Timestamp(day).date()
+            df_day = df[df["day"] == day]
+            t0 = df_day["tstamp"].min()
+            t_last = df_day["tstamp"].max()
+            if t_last - t0 < window_td:
+                Log.warning(
+                    f"{self.fname()}: skipping {day_label} (insufficient data)"
+                )
+                continue
+
+            day_series = self._build_day_series(df_day)
+            if len(day_series) < 2:
+                Log.warning(
+                    f"{self.fname()}: skipping {day_label} (insufficient instruments)"
+                )
+                continue
+
+            start = t0
+            expected_end = start + window_td
+            while expected_end <= t_last:
+                window_slices: Dict[ExchangeInstrument, pd.DataFrame] = {}
+                ts: Optional[pd.Timestamp] = None
+                for inst, df_inst in day_series.items():
+                    df_win = df_inst[
+                        (df_inst["tstamp"] >= start)
+                        & (df_inst["tstamp"] < expected_end)
+                    ]
+                    if df_win.empty:
+                        continue
+                    window_slices[inst] = df_win
+                    last_ts = df_win["tstamp"].iloc[-1]
+                    if ts is None or last_ts > ts:
+                        ts = last_ts
+
+                if window_slices and ts is not None:
+                    price_series: Dict[ExchangeInstrument, pd.DataFrame] = {}
+                    for inst, df_win in window_slices.items():
+                        aggr = self._to_backtest_aggregates(df_win)
+                        q = self.quality_.evaluate(
+                            inst=inst, aggr=aggr, now_ts=ts
+                        )
+                        if q.status_ != "PASS":
+                            continue
+                        price_series[inst] = df_win[["tstamp", "price"]]
+                    pair_results = self.analyzer_.analyze(price_series)
+                    Log.info(f"{self.fname()}: Saving Results for window ending {ts}")
+                    self._insert_results(conn, ts, pair_results)
+
+                start = start + step_td
+                expected_end = start + window_td
+
+    @staticmethod
+    def _to_backtest_aggregates(df_win: pd.DataFrame) -> List[BacktestAggregate]:
+        aggr: List[BacktestAggregate] = []
+        for tstamp_ns, num_trades in zip(df_win["tstamp_ns"], df_win["num_trades"]):
+            nt = None if pd.isna(num_trades) else int(num_trades)
+            aggr.append(
+                BacktestAggregate(aggr_time_ns_=int(tstamp_ns), num_trades_=nt)
+            )
+        return aggr
+
+    @staticmethod
+    def _insert_results(
+        conn: sqlite3.Connection,
+        ts: pd.Timestamp,
+        pair_results: Dict[str, PairStats],
+    ) -> None:
+        if not pair_results:
+            return
+        iso = ts.isoformat()
+        ns = int(ts.value)
+        rows = []
+        for pair_name in sorted(pair_results.keys()):
+            stats = pair_results[pair_name]
+            rows.append(
+                (
+                    iso,
+                    ns,
+                    pair_name,
+                    stats.instrument_a_.exchange_id_,
+                    stats.instrument_a_.instrument_id(),
+                    stats.instrument_b_.exchange_id_,
+                    stats.instrument_b_.instrument_id(),
+                    stats.pvalue_eg_,
+                    stats.pvalue_adf_,
+                    stats.pvalue_j_,
+                    stats.trace_stat_j_,
+                    stats.rank_eg_,
+                    stats.rank_adf_,
+                    stats.rank_j_,
+                    stats.composite_rank_,
+                )
+            )
+        conn.executemany(
+            """
+            INSERT INTO pair_selection_history (
+                tstamp,
+                tstamp_ns,
+                pair_name,
+                exchange_a,
+                instrument_a,
+                exchange_b,
+                instrument_b,
+                pvalue_eg,
+                pvalue_adf,
+                pvalue_j,
+                trace_stat_j,
+                rank_eg,
+                rank_adf,
+                rank_j,
+                composite_rank
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            rows,
+        )
+        conn.commit()
+
+
+
+class PairSelector(NamedObject):
+    instruments_: List[ExchangeInstrument]
+    engine_: PairSelectionEngine
+    rest_service_: Optional[RestService]
+    backtest_: Optional[PairSelectionBacktest]
+
+    def __init__(self) -> None:
+        App.instance().add_cmdline_arg("--oneshot", action="store_true", default=False)
+        App.instance().add_cmdline_arg("--backtest", action="store_true", default=False)
+        App.instance().add_cmdline_arg("--input_db", default=None)
+        App.instance().add_cmdline_arg("--output_db", default=None)
+        App.instance().add_call(App.Stage.Config, self._on_config())
+        App.instance().add_call(App.Stage.Run, self.run())
+
+    async def _on_config(self) -> None:
+        cfg = CvttAppConfig.instance()
+        self.instruments_ = self._load_instruments(cfg)
+        price_field = cfg.get_value("model/stat_model_price", "close")
+
+        self.backtest_ = None
+        self.rest_service_ = None
+        if App.instance().get_argument("backtest", False):
+            input_db = App.instance().get_argument("input_db", None)
+            output_db = App.instance().get_argument("output_db", None)
+            if not input_db or not output_db:
+                raise ValueError(
+                    "--input_db and --output_db are required when --backtest is set"
+                )
+            self.backtest_ = PairSelectionBacktest(
+                config=cfg,
+                instruments=self.instruments_,
+                price_field=price_field,
+                input_db=input_db,
+                output_db=output_db,
+            )
+            return
+
+        self.engine_ = PairSelectionEngine(
+            config=cfg,
+            instruments=self.instruments_,
+            price_field=price_field,
+        )
+
+        self.rest_service_ = RestService(config_key="/api/REST")
+        self.rest_service_.add_handler("GET", "/data_quality", self._on_data_quality)
+        self.rest_service_.add_handler(
+            "GET", "/pair_selection", self._on_pair_selection
+        )
+
+    def _load_instruments(self, cfg: CvttAppConfig) -> List[ExchangeInstrument]:
+        instruments_cfg = cfg.get_value("instruments", [])
+        instruments: List[ExchangeInstrument] = []
+        assert len(instruments_cfg) >= 2, "at least two instruments required"
+        for item in instruments_cfg:
+            if isinstance(item, str):
+                parts = item.split(":", 1)
+                if len(parts) != 2:
+                    raise ValueError(f"invalid instrument format: {item}")
+                exch_acct, instrument_id = parts
+            elif isinstance(item, dict):
+                exch_acct = item.get("exch_acct", "")
+                instrument_id = item.get("instrument_id", "")
+                if not exch_acct or not instrument_id:
+                    raise ValueError(f"invalid instrument config: {item}")
+            else:
+                raise ValueError(f"unsupported instrument entry: {item}")
+
+            exch_inst = ExchangeAccounts.instance().get_exchange_instrument(
+                exch_acct=exch_acct, instrument_id=instrument_id
+            )
+            assert (
+                exch_inst is not None
+            ), f"no ExchangeInstrument for {exch_acct}:{instrument_id}"
+            exch_inst.user_data_["exch_acct"] = exch_acct
+            instruments.append(exch_inst)
+        return instruments
+
+    async def run(self) -> None:
+        if App.instance().get_argument("backtest", False):
+            if self.backtest_ is None:
+                raise RuntimeError("backtest runner not initialized")
+            self.backtest_.run()
+            return
+        oneshot = App.instance().get_argument("oneshot", False)
+        while True:
+            await self.engine_.run_once()
+            if oneshot:
+                break
+            sleep_for = self.engine_.sleep_seconds_until_next_cycle()
+            await asyncio.sleep(sleep_for)
+
+    async def _on_data_quality(self, request: web.Request) -> web.Response:
+        fmt = request.query.get("format", "html").lower()
+        quality = self.engine_.quality_dicts()
+        if fmt == "json":
+            return web.json_response(quality)
+        return web.Response(
+            text=HtmlRenderer.render_data_quality(quality), content_type="text/html"
+        )
+
+    async def _on_pair_selection(self, request: web.Request) -> web.Response:
+        fmt = request.query.get("format", "html").lower()
+        pairs = self.engine_.pair_dicts()
+        if fmt == "json":
+            return web.json_response(pairs)
+        return web.Response(
+            text=HtmlRenderer.render_pairs(pairs), content_type="text/html"
+        )
+
+
+if __name__ == "__main__":
+    App()
+    CvttAppConfig()
+    PairSelector()
+    App.instance().run()

apps/pair_selector/renderer.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+
+from cvttpy_tools.app import App
+from cvttpy_tools.base import NamedObject
+from cvttpy_tools.config import CvttAppConfig
+
+
+class HtmlRenderer(NamedObject):
+    def __init__(self) -> None:
+        pass
+
+    @staticmethod
+    def render_data_quality(quality: List[Dict[str, Any]]) -> str:
+        rows = "".join(
+            f"<tr>"
+            f"<td>{q.get('instrument','')}</td>"
+            f"<td>{q.get('record_count','')}</td>"
+            f"<td>{q.get('latest_tstamp','')}</td>"
+            f"<td>{q.get('status','')}</td>"
+            f"<td>{q.get('reason','')}</td>"
+            f"</tr>"
+            for q in sorted(quality, key=lambda x: str(x.get("instrument", "")))
+        )
+        return f"""
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset='utf-8'/>
+    <title>Data Quality</title>
+    <style>
+        body {{ font-family: Arial, sans-serif; margin: 20px; }}
+        table {{ border-collapse: collapse; width: 100%; }}
+        th, td {{ border: 1px solid #ccc; padding: 8px; text-align: left; }}
+        th {{ background: #f2f2f2; }}
+    </style>
+</head>
+<body>
+    <h2>Data Quality</h2>
+    <table>
+        <thead>
+            <tr><th>Instrument</th><th>Records</th><th>Latest</th><th>Status</th><th>Reason</th></tr>
+        </thead>
+        <tbody>{rows}</tbody>
+    </table>
+</body>
+</html>
+"""
+
+    @staticmethod
+    def render_pairs(pairs: Dict[str, Dict[str, Any]]) -> str:
+        if not pairs:
+            body = "<p>No pairs available. Check data quality and try again.</p>"
+        else:
+            body_rows = []
+            for pair_name, p in pairs.items():
+                body_rows.append(
+                    "<tr>"
+                    f"<td>{pair_name}</td>"
+                    f"<td data-value='{p.get('rank_eg',0)}'>{p.get('rank_eg','')}</td>"
+                    f"<td data-value='{p.get('rank_adf',0)}'>{p.get('rank_adf','')}</td>"
+                    f"<td data-value='{p.get('rank_j',0)}'>{p.get('rank_j','')}</td>"
+                    f"<td data-value='{p.get('pvalue_eg','')}'>{p.get('pvalue_eg','')}</td>"
+                    f"<td data-value='{p.get('pvalue_adf','')}'>{p.get('pvalue_adf','')}</td>"
+                    f"<td data-value='{p.get('pvalue_j','')}'>{p.get('pvalue_j','')}</td>"
+                    "</tr>"
+                )
+            body = "\n".join(body_rows)
+
+        return f"""
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset='utf-8'/>
+    <title>Pair Selection</title>
+    <style>
+        body {{ font-family: Arial, sans-serif; margin: 20px; }}
+        table {{ border-collapse: collapse; width: 100%; }}
+        th, td {{ border: 1px solid #ccc; padding: 8px; text-align: left; }}
+        th.sortable {{ cursor: pointer; background: #f2f2f2; }}
+    </style>
+</head>
+<body>
+    <h2>Pair Selection</h2>
+    <table id="pairs-table">
+        <thead>
+            <tr>
+                <th>Pair</th>
+                <th class="sortable" data-type="num">Rank-EG</th>
+                <th class="sortable" data-type="num">Rank-ADF</th>
+                <th class="sortable" data-type="num">Rank-J</th>
+                <th>EG p-value</th>
+                <th>ADF p-value</th>
+                <th>Johansen pseudo p</th>
+            </tr>
+        </thead>
+        <tbody>
+            {body}
+        </tbody>
+    </table>
+    <script>
+    (function() {{
+        const table = document.getElementById('pairs-table');
+        if (!table) return;
+        const getValue = (cell) => {{
+            const val = cell.getAttribute('data-value');
+            const num = parseFloat(val);
+            return isNaN(num) ? val : num;
+        }};
+        const toggleSort = (index, isNumeric) => {{
+            const tbody = table.querySelector('tbody');
+            const rows = Array.from(tbody.querySelectorAll('tr'));
+            const th = table.querySelectorAll('th')[index];
+            const dir = th.getAttribute('data-dir') === 'asc' ? 'desc' : 'asc';
+            th.setAttribute('data-dir', dir);
+            rows.sort((a, b) => {{
+                const va = getValue(a.children[index]);
+                const vb = getValue(b.children[index]);
+                if (isNumeric && !isNaN(va) && !isNaN(vb)) {{
+                    return dir === 'asc' ? va - vb : vb - va;
+                }}
+                return dir === 'asc'
+                    ? String(va).localeCompare(String(vb))
+                    : String(vb).localeCompare(String(va));
+            }});
+            tbody.innerHTML = '';
+            rows.forEach(r => tbody.appendChild(r));
+        }};
+        table.querySelectorAll('th.sortable').forEach((th, idx) => {{
+            th.addEventListener('click', () => toggleSort(idx, th.dataset.type === 'num'));
+        }});
+    }})();
+    </script>
+</body>
+</html>
+"""

apps/pair_trader.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Callable, Coroutine, Dict, List
+import aiohttp.web as web
+
+from cvttpy_tools.app import App
+from cvttpy_tools.config import Config
+from cvttpy_tools.base import NamedObject
+from cvttpy_tools.config import CvttAppConfig
+from cvttpy_tools.logger import Log
+from cvttpy_tools.settings.cvtt_types import BookIdT
+from cvttpy_tools.web.rest_service import RestService
+
+# ---
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+from cvttpy_trading.trading.mkt_data.md_summary import MdTradesAggregate
+from cvttpy_trading.trading.exchange_config import ExchangeAccounts
+# ---
+from pairs_trading.lib.live.mkt_data_client import CvttRestMktDataClient
+
+'''
+config http://cloud16.cvtt.vpn/apps/pairs_trading
+'''
+
+HistMdCbT = Callable[[List[MdTradesAggregate]], Coroutine]
+UpdateMdCbT = Callable[[MdTradesAggregate], Coroutine]
+
+class PairTrader(NamedObject):
+    config_: CvttAppConfig
+    instruments_: List[ExchangeInstrument]
+    book_id_: BookIdT
+
+    live_strategy_: "PtLiveStrategy" #type: ignore
+    ti_sender_: "TradingInstructionsSender" #type: ignore
+    pricer_client_: CvttRestMktDataClient
+    rest_service_: RestService
+    
+    latest_history_: Dict[ExchangeInstrument, List[MdTradesAggregate]]
+    
+    def __init__(self) -> None:
+        self.instruments_ = []
+        self.latest_history_ = {}
+        
+        App.instance().add_cmdline_arg(
+            "--instrument_A",
+            type=str,
+            required=True,
+            help=(
+                " Instrument A in pair (e.g., COINBASE_AT:PAIR-BTC-USD)"
+            ),
+        )
+        App.instance().add_cmdline_arg(
+            "--instrument_B",
+            type=str,
+            required=True,
+            help=(
+                " Instrument B in pair (e.g., COINBASE_AT:PAIR-ETH-USD)"
+            ),
+        )
+
+        App.instance().add_cmdline_arg(
+            "--book_id",
+            type=str,
+            required=True,
+            help="Book ID"
+        )
+        App.instance().add_call(App.Stage.Config, self._on_config())
+        App.instance().add_call(App.Stage.Run, self.run())
+        
+    async def _on_config(self) -> None:
+        self.config_ = CvttAppConfig.instance()
+        self.book_id_ = App.instance().get_argument(name="book_id")
+        
+        # ------- PARSE INSTRUMENTS -------
+        instr_list: List[str] = []
+        instr_str = App.instance().get_argument("instrument_A", "")
+        assert instr_str != "", "Missing insrument A" 
+        instr_list.append(instr_str)
+        instr_str = App.instance().get_argument("instrument_B", "")
+        assert instr_str != "", "Missing insrument B" 
+        instr_list.append(instr_str)
+ 
+        for instr in instr_list:
+            instr_parts = instr.split(":")
+            if len(instr_parts) != 2:
+                raise ValueError(f"Invalid pair format: {instr}")   
+            exch_acct = instr_parts[0]
+            instrument_id = instr_parts[1]
+            exch_inst = ExchangeAccounts.instance().get_exchange_instrument(exch_acct=exch_acct, instrument_id=instrument_id)
+            assert exch_inst is not None, f"No ExchangeInstrument for {instr}"
+            exch_inst.user_data_["exch_acct"] = exch_acct
+            self.instruments_.append(exch_inst)
+
+        Log.info(f"{self.fname()} Instruments: {self.instruments_[0].details_short()} <==> {self.instruments_[1].details_short()}")
+        
+        # ------- CREATE STRATEGY -------
+        from pairs_trading.lib.pt_strategy.live.live_strategy import PtLiveStrategy
+        strategy_config = CvttAppConfig.instance() #self.config_.get_subconfig("strategy_config", Config({}))
+        self.live_strategy_ = PtLiveStrategy(
+            config=strategy_config,
+            pairs_trader=self,
+        )
+        Log.info(f"{self.fname()} Strategy created: {self.live_strategy_}")  
+        model_name = self.config_.get_value("model/name", "?model/name?")
+        self.config_.set_value("strategy_id", f"{self.live_strategy_.__class__.__name__}:{model_name}")
+        
+        # # ------- CREATE PRICER CLIENT -------
+        self.pricer_client_ = CvttRestMktDataClient(config=self.config_)
+        Log.info(f"{self.fname()} MD client created: {self.pricer_client_}")  
+        
+        # ------- CREATE TRADER CLIENT -------
+        from pairs_trading.lib.live.ti_sender import TradingInstructionsSender
+        self.ti_sender_ = TradingInstructionsSender(config=self.config_, pairs_trader=self)
+        Log.info(f"{self.fname()} TI sender created: {self.ti_sender_}")
+
+        # # ------- CREATE REST SERVER -------
+        self.rest_service_ = RestService(
+            config_key=f"/api/REST"
+        )
+        
+        # --- Strategy Handlers
+        self.rest_service_.add_handler(
+            method="POST",
+            url="/api/strategy",
+            handler=self._on_api_request,
+        )
+        
+    async def subscribe_md(self) -> None:
+        from functools import partial
+        for exch_inst in self.instruments_:
+            exch_acct = exch_inst.user_data_.get("exch_acct", "?exch_acct?")
+            instrument_id = exch_inst.instrument_id()
+            
+            await self.pricer_client_.add_subscription(
+                exch_acct=exch_acct,
+                instrument_id=instrument_id,
+                interval_sec=self.live_strategy_.interval_sec(),
+                history_depth_sec=self.live_strategy_.history_depth_sec(),
+                callback=partial(self._on_md_summary, exch_inst=exch_inst)
+            )
+
+    async def _on_md_summary(self, history: List[MdTradesAggregate], exch_inst: ExchangeInstrument) -> None:
+        Log.info(f"{self.fname()}: got {exch_inst.details_short()} data")
+        self.latest_history_[exch_inst] = history
+        if len(self.latest_history_) == 2:
+            from itertools import chain
+            all_aggrs = sorted(list(chain.from_iterable(self.latest_history_.values())), key=lambda X: X.aggr_time_ns_)
+
+            await self.live_strategy_.on_mkt_data_hist_snapshot(hist_aggr=all_aggrs)
+            self.latest_history_ = {}
+
+    async def _on_api_request(self, request: web.Request) -> web.Response:
+        # TODO choose pair
+        # TODO confirm chosen pair (after selection is implemented)
+        return web.Response() # TODO  API request handler implementation
+    
+    
+    async def run(self) -> None:
+        Log.info(f"{self.fname()} ...")
+        while True:
+            await asyncio.sleep(0.1)
+        pass
+
+if __name__ == "__main__":
+    App()
+    CvttAppConfig()
+    PairTrader()
+    App.instance().run()

build-dist.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+
+# ---------------- Settings
+
+repo=git@cloud21.cvtt.vpn:/works/git/cvtt2/research/pairs_trading.git
+
+dist_root=/home/cvttdist/software/cvtt2
+dist_user=cvttdist
+dist_host="cloud21.cvtt.vpn"
+dist_ssh_port="22"
+
+dist_locations="cloud21.cvtt.vpn:22 hs01.cvtt.vpn:22"
+version_file="VERSION"
+
+prj=pairs_trading
+brnch=master
+interactive=N
+
+# ---------------- Settings
+
+# ---------------- cmdline
+
+usage() {
+  echo "Usage: $0 [-b <branch (master)> -i (interactive)"
+  exit 1
+}
+
+while getopts "b:i" opt; do
+  case ${opt} in
+    b )
+      brnch=$OPTARG
+      ;;
+    i )
+      interactive=Y
+      ;;
+    \? )
+      echo "Invalid option: -$OPTARG" >&2
+      usage
+      ;;
+    : )
+      echo "Option -$OPTARG requires an argument." >&2
+      usage
+      ;;
+  esac
+done
+# ---------------- cmdline
+
+confirm() {
+    if [ "${interactive}" == "Y" ]; then
+        echo "--------------------------------"
+        echo -n "Press <Enter> to continue" && read
+    fi
+}
+
+
+if [ "${interactive}" == "Y" ]; then
+    echo -n "Enter project [${prj}]: "
+    read project
+    if [ "${project}" == "" ]
+    then
+        project=${prj}
+    fi
+else
+    project=${prj}
+fi
+
+# repo=${git_repo_arr[${project}]}
+if [ -z ${repo} ]; then
+    echo "ERROR: Project repository for ${project} not found"
+    exit -1
+fi
+echo "Project repo: ${repo}"
+
+if [ "${interactive}" == "Y" ]; then
+    echo -n "Enter branch to build release from [${brnch}]: "
+    read branch
+    if [ "${branch}" == "" ]
+    then
+        branch=${brnch}
+    fi
+else
+    branch=${brnch}
+fi
+
+tmp_dir=$(mktemp -d)
+function cleanup {
+    cd ${HOME}
+    rm -rf ${tmp_dir}
+}
+trap cleanup EXIT
+
+
+prj_dir="${tmp_dir}/${prj}"
+
+cmd_arr=()
+Cmd="git clone ${repo} ${prj_dir}"
+cmd_arr+=("${Cmd}")
+
+Cmd="cd ${prj_dir}"
+cmd_arr+=("${Cmd}")
+
+if [ "${interactive}" == "Y" ]; then
+    echo "------------------------------------"
+    echo "The following commands will execute:"
+    echo "------------------------------------"
+    for cmd in "${cmd_arr[@]}"
+    do
+        echo ${cmd}
+    done
+fi
+
+confirm
+
+for cmd in "${cmd_arr[@]}"
+do
+    echo ${cmd} && eval ${cmd}
+done
+
+Cmd="git checkout ${branch}"
+echo ${Cmd} && eval ${Cmd}
+if [ "${?}" != "0" ]; then
+    echo "ERROR: Branch ${branch} is not found"
+    cd ${HOME} && rm -rf ${tmp_dir}
+    exit -1
+fi
+
+
+release_version=$(cat ${version_file} | awk -F',' '{print $1}')
+whats_new=$(cat ${version_file} | awk -F',' '{print $2}')
+
+
+echo "--------------------------------"
+echo "Version file: ${version_file}"
+echo "Release version: ${release_version}"
+
+confirm
+
+version_tag="v${release_version}"
+if [ "$(git tag -l "${version_tag}")" != "" ]; then
+    version_tag="${version_tag}.$(date +%Y%m%d_%H%M)"
+fi
+version_comment="'${version_tag} ${project} ${branch} $(date +%Y-%m-%d)\n${whats_new}'"
+
+cmd_arr=()
+Cmd="git tag -a ${version_tag} -m ${version_comment}"
+cmd_arr+=("${Cmd}")
+
+Cmd="git push origin --tags"
+cmd_arr+=("${Cmd}")
+
+Cmd="rm -rf .git"
+cmd_arr+=("${Cmd}")
+
+SourceLoc=../${project}
+
+dist_path="${dist_root}/${project}/${release_version}"
+
+for dist_loc in ${dist_locations}; do
+    dhp=(${dist_loc//:/ })
+    dist_host=${dhp[0]}
+    dist_port=${dhp[1]}
+    Cmd="rsync -avzh"
+    Cmd="${Cmd} --rsync-path=\"mkdir -p ${dist_path}"
+    Cmd="${Cmd} && rsync\" -e \"ssh -p ${dist_ssh_port}\""
+    Cmd="${Cmd} $SourceLoc ${dist_user}@${dist_host}:${dist_path}/"
+    cmd_arr+=("${Cmd}")
+done
+
+if [ "${interactive}" == "Y" ]; then
+    echo "------------------------------------"
+    echo "The following commands will execute:"
+    echo "------------------------------------"
+    for cmd in "${cmd_arr[@]}"
+    do
+        echo ${cmd}
+    done
+fi
+
+confirm
+
+for cmd in "${cmd_arr[@]}"
+do
+    pwd && echo ${cmd} && eval ${cmd}
+done
+
+echo "$0 Done ${project} ${release_version}"

configuration/__DELETE__/ols-exp.cfg

@@ -0,0 +1,43 @@
+{
+    "market_data_loading": {
+        "CRYPTO": {
+            "data_directory": "./data/crypto",
+            "db_table_name": "md_1min_bars",
+            "instrument_id_pfx": "PAIR-",
+        },
+        "EQUITY": {
+            "data_directory": "./data/equity",
+            "db_table_name": "md_1min_bars",
+            "instrument_id_pfx": "STOCK-",
+        }
+    },
+
+    # ====== Funding ======
+    "funding_per_pair": 2000.0,
+    # ====== Trading Parameters ======
+    "stat_model_price": "close",
+    "execution_price": {
+        "column": "vwap",
+        "shift": 1,
+    },
+    "dis-equilibrium_open_trshld": 2.0,
+    "dis-equilibrium_close_trshld": 0.5,
+    "training_size": 120,
+    "model_class": "pairs_trading.lib.pt_strategy.models.OLSModel",
+    "model_data_policy_class": "pairs_trading.lib.pt_strategy.model_data_policy.ExpandingWindowDataPolicy",
+
+    # ====== Stop Conditions ======
+    "stop_close_conditions": {
+        "profit": 2.0,
+        "loss": -0.5
+    }
+
+    # ====== End of Session Closeout ======
+    "close_outstanding_positions": true,
+    # "close_outstanding_positions": false,
+    "trading_hours": {
+        "timezone": "America/New_York",
+        "begin_session": "7:30:00",
+        "end_session": "18:30:00",
+    }
+}

configuration/__DELETE__/ols-opt.cfg

@@ -0,0 +1,47 @@
+{
+    "market_data_loading": {
+        "CRYPTO": {
+            "data_directory": "./data/crypto",
+            "db_table_name": "md_1min_bars",
+            "instrument_id_pfx": "PAIR-",
+        },
+        "EQUITY": {
+            "data_directory": "./data/equity",
+            "db_table_name": "md_1min_bars",
+            "instrument_id_pfx": "STOCK-",
+        }
+    },
+
+    # ====== Funding ======
+    "funding_per_pair": 2000.0,
+    # ====== Trading Parameters ======
+    "stat_model_price": "close",
+    "execution_price": {
+        "column": "vwap",
+        "shift": 1,
+    },
+    "dis-equilibrium_open_trshld": 1.75,
+    "dis-equilibrium_close_trshld": 0.9,
+    "model_class": "pairs_trading.lib.pt_strategy.models.OLSModel",
+
+    # "model_data_policy_class": "pairs_trading.lib.pt_strategy.model_data_policy.EGOptimizedWndDataPolicy",
+    # "model_data_policy_class": "pairs_trading.lib.pt_strategy.model_data_policy.ADFOptimizedWndDataPolicy",
+    "model_data_policy_class": "pairs_trading.lib.pt_strategy.model_data_policy.JohansenOptdWndDataPolicy",
+    "min_training_size": 60,
+    "max_training_size": 150,
+
+    # ====== Stop Conditions ======
+    "stop_close_conditions": {
+        "profit": 2.0,
+        "loss": -0.5
+    }
+
+    # ====== End of Session Closeout ======
+    "close_outstanding_positions": true,
+    # "close_outstanding_positions": false,
+    "trading_hours": {
+        "timezone": "America/New_York",
+        "begin_session": "7:30:00",
+        "end_session": "18:30:00",
+    }
+}

configuration/__DELETE__/ols.cfg

@@ -0,0 +1,47 @@
+{
+    "market_data_loading": {
+        "CRYPTO": {
+            "data_directory": "./data/crypto",
+            "db_table_name": "md_1min_bars",
+            "instrument_id_pfx": "PAIR-",
+        },
+        "EQUITY": {
+            "data_directory": "./data/equity",
+            "db_table_name": "md_1min_bars",
+            "instrument_id_pfx": "STOCK-",
+        }
+    },
+
+    # ====== Funding ======
+    "funding_per_pair": 2000.0,
+    # ====== Trading Parameters ======
+    "stat_model_price": "close",
+    "execution_price": {
+        "column": "vwap",
+        "shift": 1,
+    },
+    "dis-equilibrium_open_trshld": 1.75,
+    "dis-equilibrium_close_trshld": 0.9,
+    "model_class": "pairs_trading.lib.pt_strategy.models.OLSModel",
+
+    "training_size": 120,
+    "model_data_policy_class": "pairs_trading.lib.pt_strategy.model_data_policy.RollingWindowDataPolicy",
+    # "model_data_policy_class": "pairs_trading.lib.pt_strategy.model_data_policy.OptimizedWindowDataPolicy",
+    # "min_training_size": 60,
+    # "max_training_size": 150,
+
+    # ====== Stop Conditions ======
+    "stop_close_conditions": {
+        "profit": 2.0,
+        "loss": -0.5
+    }
+
+    # ====== End of Session Closeout ======
+    "close_outstanding_positions": true,
+    # "close_outstanding_positions": false,
+    "trading_hours": {
+        "timezone": "America/New_York",
+        "begin_session": "7:30:00",
+        "end_session": "18:30:00",
+    }
+}

configuration/__DELETE__/vecm.cfg

@@ -0,0 +1,48 @@
+{
+    "market_data_loading": {
+        "CRYPTO": {
+    "data_directory": "./data/crypto",
+    "db_table_name": "md_1min_bars",
+    "instrument_id_pfx": "PAIR-",
+        },
+        "EQUITY": {
+            "data_directory": "./data/equity",
+            "db_table_name": "md_1min_bars",
+            "instrument_id_pfx": "STOCK-",
+        }
+    },
+
+    # ====== Funding ======
+    "funding_per_pair": 2000.0,
+  
+    # ====== Trading Parameters ======
+    "stat_model_price": "close", # "vwap"
+    "execution_price": {
+        "column": "vwap",
+        "shift": 1,
+    },
+    "dis-equilibrium_open_trshld": 1.75,
+    "dis-equilibrium_close_trshld": 1.0,
+    "model_class": "pairs_trading.lib.pt_strategy.models.VECMModel",
+
+    "training_size": 120,
+    "model_data_policy_class": "pairs_trading.lib.pt_strategy.model_data_policy.RollingWindowDataPolicy",
+    # "model_data_policy_class": "pairs_trading.lib.pt_strategy.model_data_policy.OptimizedWindowDataPolicy",
+    # "min_training_size": 60,
+    # "max_training_size": 150,
+
+    # ====== Stop Conditions ======
+    "stop_close_conditions": {
+        "profit": 2.0,
+        "loss": -0.5
+    }
+
+    # ====== End of Session Closeout ======
+    "close_outstanding_positions": true,
+    # "close_outstanding_positions": false,
+    "trading_hours": {
+        "timezone": "America/New_York",
+        "begin_session": "7:30:00",
+        "end_session": "18:30:00",
+    }
+}

configuration/backtest.cfg

@@ -0,0 +1,46 @@
+{
+    "refdata": {
+        "assets": @inc=http://@env{CONFIG_SERVICE}/refdata/assets
+        , "instruments": @inc=http://@env{CONFIG_SERVICE}/refdata/instruments
+        , "exchange_instruments": @inc=http://@env{CONFIG_SERVICE}/refdata/exchange_instruments
+        , "dynamic_instrument_exchanges": ["ALPACA"]
+        , "exchanges": @inc=http://@env{CONFIG_SERVICE}/refdata/exchanges
+    }, 
+    "market_data_loading": {
+        "CRYPTO": {
+            "data_directory": "./data/crypto",
+            "db_table_name": "md_1min_bars",
+            "instrument_id_pfx": "PAIR-",
+        },
+        "EQUITY": {
+            "data_directory": "./data/equity",
+            "db_table_name": "md_1min_bars",
+            "instrument_id_pfx": "STOCK-",
+        }
+    },
+    # ====== Funding ======
+    "funding_per_pair": 2000.0,
+
+    # ====== Model =======
+    "model": @inc=http://@env{CONFIG_SERVICE}/apps/common/models/@env{MODEL_CONFIG} 
+
+    # ====== Trading ======= 
+    "execution_price": {
+        "column": "vwap",
+        "shift": 1,
+    },
+    # ====== Stop Conditions ======
+    "stop_close_conditions": {
+        "profit": 2.0,
+        "loss": -0.5
+    }
+
+    # ====== End of Session Closeout ======
+    "close_outstanding_positions": true,
+    # "close_outstanding_positions": false,
+    "trading_hours": {
+        "timezone": "America/New_York",
+        "begin_session": "7:30:00",
+        "end_session": "18:30:00",
+    }
+}

configuration/crypto.cfg

@@ -1,33 +0,0 @@
-{
-    "security_type": "CRYPTO",
-    "data_directory": "./data/crypto",
-    "datafiles": [
-        "2025*.mktdata.ohlcv.db"
-    ],
-    "db_table_name": "md_1min_bars",
-    "exchange_id": "BNBSPOT",
-    "instrument_id_pfx": "PAIR-",
-    # "instruments": [
-    #     "BTC-USDT",
-    #     "BCH-USDT",
-    #     "ETH-USDT",
-    #     "LTC-USDT",
-    #     "XRP-USDT",
-    #     "ADA-USDT",
-    #     "SOL-USDT",
-    #     "DOT-USDT"
-    # ],
-    "trading_hours": {
-        "begin_session": "00:00:00",
-        "end_session": "23:59:00",
-        "timezone": "UTC"
-    },
-    "price_column": "close",
-    "min_required_points": 30,
-    "zero_threshold": 1e-10,
-    "dis-equilibrium_open_trshld": 2.0,
-    "dis-equilibrium_close_trshld": 0.5,
-    "training_minutes": 120,
-    "funding_per_pair": 2000.0,
-    "strategy_class": "strategies.StaticFitStrategy"
-}

configuration/equity.cfg

@@ -1,26 +0,0 @@
-{
-    "security_type": "EQUITY",
-    "data_directory": "./data/equity",
-    "datafiles": [
-        "202506*.mktdata.ohlcv.db",
-    ],
-    "db_table_name": "md_1min_bars",
-    "exchange_id": "ALPACA",
-    "instrument_id_pfx": "STOCK-",
-    "trading_hours": {
-        "begin_session": "9:30:00",
-        "end_session": "16:00:00",
-        "timezone": "America/New_York"
-    },
-    "price_column": "close",
-    "min_required_points": 30,
-    "zero_threshold": 1e-10,
-    "dis-equilibrium_open_trshld": 2.0,
-    "dis-equilibrium_close_trshld": 1.0,
-    "training_minutes": 120,
-    "funding_per_pair": 2000.0,
-    "strategy_class": "strategies.StaticFitStrategy"
-    # "strategy_class": "strategies.SlidingFitStrategy"
-    "exclude_instruments": ["CAN"]
-    
-}

configuration/pair_trader.cfg

@@ -0,0 +1,21 @@
+{
+    "strategy_config": @inc=file:///home/oleg/develop/pairs_trading/configuration/vecm-opt.cfg
+    "pricer_config": {
+        "pricer_url": "ws://localhost:12346/ws",
+        "history_depth_sec": 86400 #"60*60*24",  # use simpleeval
+        "interval_sec": 60
+    },
+    "ti_config": {
+        "cvtt_base_url": "http://localhost:23456"
+        "book_id": "XXXXXXXXX",
+        "strategy_id": "XXXXXXXXX",
+        "ti_endpoint": {
+            "method": "POST",
+            "url": "/trading_instructions"
+        },
+        "health_check_endpoint": {
+            "method": "GET",
+            "url": "/ping"
+        }
+    }
+}

configuration/vecm-opt.cfg

@@ -0,0 +1,56 @@
+{
+    # "refdata": {
+    #     "assets": @inc=http://@env{CONFIG_SERVICE}/refdata/assets
+    #     , "instruments": @inc=http://@env{CONFIG_SERVICE}/refdata/instruments
+    #     , "exchange_instruments": @inc=http://@env{CONFIG_SERVICE}/refdata/exchange_instruments
+    #     , "dynamic_instrument_exchanges": ["ALPACA"]
+    #     , "exchanges": @inc=http://@env{CONFIG_SERVICE}/refdata/exchanges
+    # }, 
+    # "market_data_loading": {
+    #     "CRYPTO": {
+    #         "data_directory": "./data/crypto",
+    #         "db_table_name": "md_1min_bars",
+    #         "instrument_id_pfx": "PAIR-",
+    #     },
+    #     "EQUITY": {
+    #         "data_directory": "./data/equity",
+    #         "db_table_name": "md_1min_bars",
+    #         "instrument_id_pfx": "STOCK-",
+    #     }
+    # },
+
+    # # ====== Funding ======
+    # "funding_per_pair": 2000.0,
+  
+    # ====== Trading Parameters ======
+    "stat_model_price": "close", # "vwap"
+    "execution_price": {
+        "column": "vwap",
+        "shift": 1,
+    },
+    "dis-equilibrium_open_trshld": 1.75,
+    "dis-equilibrium_close_trshld": 1.0,
+
+    "model_class": "pairs_trading.lib.pt_strategy.models.VECMModel",
+
+    # "training_size": 120,
+    # "model_data_policy_class": "pairs_trading.lib.pt_strategy.model_data_policy.RollingWindowDataPolicy",
+    "model_data_policy_class": "pairs_trading.lib.pt_strategy.model_data_policy.ADFOptimizedWndDataPolicy",
+    "min_training_size": 60,
+    "max_training_size": 150,
+
+    # # ====== Stop Conditions ======
+    # "stop_close_conditions": {
+    #     "profit": 2.0,
+    #     "loss": -0.5
+    # }
+
+    # # ====== End of Session Closeout ======
+    # "close_outstanding_positions": true,
+    # # "close_outstanding_positions": false,
+    # "trading_hours": {
+    #     "timezone": "America/New_York",
+    #     "begin_session": "7:30:00",
+    #     "end_session": "18:30:00",
+    # }
+}

lib/live/mkt_data_client.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Dict, Any, List, Optional, Set
+
+import requests
+
+from cvttpy_tools.base import NamedObject
+from cvttpy_tools.logger import Log
+from cvttpy_tools.config import Config
+from cvttpy_tools.timer import Timer
+from cvttpy_tools.timeutils import NanosT, current_seconds
+from cvttpy_tools.settings.cvtt_types import InstrumentIdT, IntervalSecT
+from cvttpy_tools.web.rest_client import RESTSender
+# ---
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+from cvttpy_trading.trading.accounting.exch_account import ExchangeAccountNameT
+from cvttpy_trading.trading.mkt_data.md_summary import MdTradesAggregate, MdSummary, MdSummaryCallbackT
+from cvttpy_trading.trading.exchange_config import ExchangeAccounts
+# ---
+
+
+# class MdSummary(HistMdBar):
+#     def __init__(
+#         self,
+#         ts_ns: int,
+#         open: float,
+#         high: float,
+#         low: float,
+#         close: float,
+#         volume: float,
+#         vwap: float,
+#         num_trades: int,
+#     ):
+#         super().__init__(ts=ts_ns)
+#         self.open_ = open
+#         self.high_ = high
+#         self.low_ = low
+#         self.close_ = close
+#         self.volume_ = volume
+#         self.vwap_ = vwap
+#         self.num_trades_ = num_trades
+
+#     @classmethod
+#     def from_REST_response(cls, response: requests.Response) -> List[MdSummary]:
+#         res: List[MdSummary] = []
+#         jresp = response.json()
+#         hist_data = jresp.get("historical_data", [])
+#         for hd in hist_data:
+#             res.append(
+#                 MdSummary(
+#                     ts_ns=hd["time_ns"],
+#                     open=hd["open"],
+#                     high=hd["high"],
+#                     low=hd["low"],
+#                     close=hd["close"],
+#                     volume=hd["volume"],
+#                     vwap=hd["vwap"],
+#                     num_trades=hd["num_trades"],
+#                 )
+#             )
+#         return res
+
+#     def create_md_trades_aggregate(
+#         self,
+#         exch_acct: ExchangeAccountNameT,
+#         exch_inst: ExchangeInstrument,
+#         interval_sec: IntervalSecT,
+#     ) -> MdTradesAggregate:
+#         res = MdTradesAggregate(
+#             exch_acct=exch_acct,
+#             exch_inst=exch_inst,
+#             interval_ns=interval_sec * NanoPerSec,
+#         )
+#         res.set(mdbar=self)
+#         return res
+
+
+# MdSummaryCallbackT = Callable[[List[MdTradesAggregate]], Coroutine]
+
+
+class MdSummaryCollector(NamedObject):
+    sender_: RESTSender
+    exch_acct_: ExchangeAccountNameT
+    exch_inst_: ExchangeInstrument
+    interval_sec_: IntervalSecT
+    history_depth_sec_: IntervalSecT
+
+    history_: List[MdTradesAggregate]
+
+    callbacks_: List[MdSummaryCallbackT]
+    timer_: Optional[Timer]
+
+    def __init__(
+        self,
+        sender: RESTSender,
+        exch_acct: ExchangeAccountNameT,
+        instrument_id: InstrumentIdT,
+        interval_sec: IntervalSecT,
+        history_depth_sec: IntervalSecT,
+    ) -> None:
+        self.sender_ = sender
+        self.exch_acct_ = exch_acct
+
+        exch_inst = ExchangeAccounts.instance().get_exchange_instrument(
+            exch_acct=exch_acct, instrument_id=instrument_id
+        )
+        assert exch_inst is not None, f"Unable to find Exchange instrument for {exch_acct}/{instrument_id}"
+        self.exch_inst_ = exch_inst
+        self.interval_sec_ = interval_sec
+        self.history_depth_sec_ = history_depth_sec
+
+        self.history_ = []
+        self.callbacks_ = []
+        self.timer_ = None
+
+    def add_callback(self, cb: MdSummaryCallbackT) -> None:
+        self.callbacks_.append(cb)
+
+    def __hash__(self):
+        return hash(
+            (
+                self.exch_acct_,
+                self.exch_inst_.instrument_id(),
+                self.interval_sec_,
+                self.history_depth_sec_,
+            )
+        )
+
+    def rqst_data(self) -> Dict[str, Any]:
+        return {
+            "exch_acct": self.exch_acct_,
+            "instrument_id": self.exch_inst_.instrument_id(),
+            "interval_sec": self.interval_sec_,
+            "history_depth_sec": self.history_depth_sec_,
+        }
+
+    def get_history(self) -> List[MdSummary]:
+        response: requests.Response = self.sender_.send_post(
+            endpoint="md_summary", post_body=self.rqst_data()
+        )
+        if response.status_code not in (200, 201):
+            Log.error(
+                f"{self.fname()}: Received error: {response.status_code} - {response.text}"
+            )
+            return []
+        return MdSummary.from_REST_response(response=response)
+
+    def get_last(self) -> Optional[MdSummary]:
+        Log.info(f"{self.fname()}: for {self.exch_inst_.details_short()}")
+        rqst_data = self.rqst_data()
+        rqst_data["history_depth_sec"] = self.interval_sec_ * 2
+        response: requests.Response = self.sender_.send_post(
+            endpoint="md_summary", post_body=rqst_data
+        )
+        if response.status_code not in (200, 201):
+            Log.error(
+                f"{self.fname()}: Received error: {response.status_code} - {response.text}"
+            )
+            return None
+        res = MdSummary.from_REST_response(response=response)
+        Log.info(f"DEBUG *** {self.exch_inst_.base_asset_id_}: {res[-1].tstamp_}")
+        return None if len(res) == 0 else res[-1]
+
+    def is_empty(self) -> bool:
+        return len(self.history_) == 0
+
+    async def start(self) -> None:
+        if self.timer_:
+            Log.error(f"{self.fname()}: Timer is already started")
+            return
+        mdsum_hist = self.get_history()
+        self.history_ = [
+            mdsum.create_md_trades_aggregate(
+                exch_acct=self.exch_acct_,
+                exch_inst=self.exch_inst_,
+                interval_sec=self.interval_sec_,
+            )
+            for mdsum in mdsum_hist
+        ]
+        await self.run_callbacks()
+        self.set_timer()
+
+    def set_timer(self):
+        if self.timer_:
+            self.timer_.cancel()
+        start_in = self.next_load_time() - current_seconds()
+        self.timer_ = Timer(
+            start_in_sec=start_in,
+            func=self._load_new,
+        )
+        Log.info(f"{self.fname()} Timer for {self.exch_inst_.details_short()} is set to run in {start_in} sec")
+
+    def next_load_time(self) -> NanosT:
+        ALLOW_LAG_SEC = 1
+        curr_sec = int(current_seconds())
+        return (curr_sec - curr_sec % self.interval_sec_) + self.interval_sec_ + ALLOW_LAG_SEC
+
+    async def _load_new(self) -> None:
+
+        last: Optional[MdSummary] = self.get_last()
+        if not last:
+            Log.warning(f"{self.fname()}: did not get last update")
+        elif not self.is_empty() and last.ts_ns_ <= self.history_[-1].aggr_time_ns_:
+            Log.info(
+                f"{self.fname()}: Received {last}. Already Have: {self.history_[-1]}"
+            )
+        else:
+            self.history_.append(last.create_md_trades_aggregate(exch_acct=self.exch_acct_, exch_inst=self.exch_inst_, interval_sec=self.interval_sec_))
+            await self.run_callbacks()
+        self.set_timer()
+
+    async def run_callbacks(self) -> None:
+        [await cb(self.history_) for cb in self.callbacks_]
+
+    def stop(self) -> None:
+        if self.timer_:
+            self.timer_.cancel()
+            self.timer_ = None
+
+
+class CvttRestMktDataClient(NamedObject):
+    config_: Config
+    sender_: RESTSender
+    collectors_: Set[MdSummaryCollector]
+
+    def __init__(self, config: Config) -> None:
+        self.config_ = config
+        base_url = self.config_.get_value("cvtt_base_url", default="")
+        assert base_url
+        self.sender_ = RESTSender(base_url=base_url)
+        self.collectors_ = set()
+
+    async def add_subscription(
+        self,
+        exch_acct: ExchangeAccountNameT,
+        instrument_id: InstrumentIdT,
+        interval_sec: IntervalSecT,
+        history_depth_sec: IntervalSecT,
+        callback: MdSummaryCallbackT,
+    ) -> None:
+        mdsc = MdSummaryCollector(
+            sender=self.sender_,
+            exch_acct=exch_acct,
+            instrument_id=instrument_id,
+            interval_sec=interval_sec,
+            history_depth_sec=history_depth_sec,
+        )
+        mdsc.add_callback(callback)
+        self.collectors_.add(mdsc)
+        await mdsc.start()
+
+
+if __name__ == "__main__":
+    config = Config(json_src={"cvtt_base_url": "http://cvtt-tester-01.cvtt.vpn:23456"})
+    # config = Config(json_src={"cvtt_base_url": "http://dev-server-02.cvtt.vpn:23456"})
+
+    async def _calback(history: List[MdTradesAggregate]) -> None:
+        Log.info(
+            f"MdSummary Hist Length is {len(history)}. Last summary: {history[-1] if  len(history) > 0 else '[]'}"
+        )
+
+    async def __run() -> None:
+        Log.info("Starting...")
+        cvtt_client = CvttRestMktDataClient(config)
+        await cvtt_client.add_subscription(
+            exch_acct="COINBASE_AT",
+            instrument_id="PAIR-BTC-USD",
+            interval_sec=60,
+            history_depth_sec=24 * 3600,
+            callback=_calback,
+        )
+        while True:
+            await asyncio.sleep(5)
+
+    asyncio.run(__run())
+    pass

lib/live/rest_client.py.md

@@ -0,0 +1,60 @@
+```python
+from __future__ import annotations
+
+from typing import Dict
+import time
+
+import requests
+
+from cvttpy_tools.base import NamedObject
+
+class RESTSender(NamedObject):
+    session_: requests.Session
+    base_url_: str
+
+    def __init__(self, base_url: str) -> None:
+        self.base_url_ = base_url
+        self.session_ = requests.Session()
+
+    def is_ready(self) -> bool:
+        """Checks if the server is up and responding"""
+        url = f"{self.base_url_}/ping"
+        try:
+            response = self.session_.get(url)
+            response.raise_for_status()
+            return True
+        except requests.exceptions.RequestException:
+            return False
+
+    def send_post(self, endpoint: str, post_body: Dict) -> requests.Response:
+
+        while not self.is_ready():
+            print("Waiting for FrontGateway to start...")
+            time.sleep(5)
+
+        url = f"{self.base_url_}/{endpoint}"
+        try:
+            return self.session_.request(
+                method="POST",
+                url=url,
+                json=post_body,
+                headers={"Content-Type": "application/json"},
+            )
+        except requests.exceptions.RequestException as excpt:
+            raise ConnectionError(
+                f"Failed to send status={excpt.response.status_code} {excpt.response.text}"  # type: ignore
+            ) from excpt
+
+    def send_get(self, endpoint: str) -> requests.Response:
+        while not self.is_ready():
+            print("Waiting for FrontGateway to start...")
+            time.sleep(5)
+
+        url = f"{self.base_url_}/{endpoint}"
+        try:
+            return self.session_.request(method="GET", url=url)
+        except requests.exceptions.RequestException as excpt:
+            raise ConnectionError(
+                f"Failed to send status={excpt.response.status_code} {excpt.response.text}"  # type: ignore
+            ) from excpt
+```

lib/live/ti_sender.py

@@ -0,0 +1,50 @@
+from enum import Enum
+
+import requests
+
+# import aiohttp
+from cvttpy_tools.base import NamedObject
+from cvttpy_tools.config import Config
+from cvttpy_tools.logger import Log
+from cvttpy_tools.web.rest_client import RESTSender
+# ---
+from cvttpy_trading.trading.trading_instructions import TradingInstructions
+# ---
+from pairs_trading.apps.pair_trader import PairTrader
+
+
+class TradingInstructionsSender(NamedObject):
+    config_: Config
+    sender_: RESTSender
+    pairs_trader_: PairTrader
+
+    class TradingInstType(str, Enum):
+        TARGET_POSITION = "TARGET_POSITION"
+        DIRECT_ORDER = "DIRECT_ORDER"
+        MARKET_MAKING = "MARKET_MAKING"
+        NONE = "NONE"
+
+    def __init__(self, config: Config, pairs_trader: PairTrader) -> None:
+        self.config_ = config
+        base_url = self.config_.get_value("cvtt_base_url", default="")
+        assert base_url
+        self.sender_ = RESTSender(base_url=base_url)
+        self.pairs_trader_ = pairs_trader
+        
+        self.book_id_ = self.pairs_trader_.book_id_
+        assert self.book_id_, "book_id is required"
+        
+        self.strategy_id_ = config.get_value("strategy_id", "")
+        assert self.strategy_id_, "strategy_id is required"
+        
+
+    async def send_trading_instructions(self, ti: TradingInstructions) -> None:
+        Log.info(f"{self.fname()}: sending {ti=}")
+        response: requests.Response = self.sender_.send_post(
+            endpoint="trading_instructions", post_body=ti.to_dict()
+        )
+        if response.status_code not in (200, 201):
+            Log.error(
+                f"{self.fname()}: Received error: {response.status_code} - {response.text}"
+            )
+

lib/pt_strategy/live/live_strategy.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+# ---
+from cvttpy_tools.base import NamedObject
+from cvttpy_tools.app import App
+from cvttpy_tools.config import Config
+from cvttpy_tools.settings.cvtt_types import IntervalSecT
+from cvttpy_tools.timeutils import NanosT, SecPerHour, current_nanoseconds, NanoPerSec, format_nanos_utc
+from cvttpy_tools.logger import Log
+
+# ---
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+from cvttpy_trading.trading.mkt_data.md_summary import MdTradesAggregate
+from cvttpy_trading.trading.trading_instructions import TradingInstructions
+from cvttpy_trading.trading.trading_instructions import TargetPositionSignal
+
+# ---
+from pairs_trading.lib.pt_strategy.model_data_policy import ModelDataPolicy
+from pairs_trading.lib.pt_strategy.pt_model import Prediction
+from pairs_trading.lib.pt_strategy.trading_pair import LiveTradingPair
+from pairs_trading.apps.pair_trader import PairTrader
+from pairs_trading.lib.pt_strategy.pt_market_data import LiveMarketData
+
+
+class PtLiveStrategy(NamedObject):
+    config_: Config
+    instruments_: List[ExchangeInstrument]
+
+    interval_sec_: IntervalSecT
+    history_depth_sec_: IntervalSecT
+    open_threshold_: float
+    close_threshold_: float
+
+    trading_pair_: LiveTradingPair
+    model_data_policy_: ModelDataPolicy
+    pairs_trader_: PairTrader
+
+    # for presentation: history of prediction values and trading signals
+    predictions_df_: pd.DataFrame
+    trading_signals_df_: pd.DataFrame
+    allowed_md_lag_sec_: int
+
+
+    def __init__(
+        self,
+        config: Config,
+        pairs_trader: PairTrader,
+    ):
+        self.config_ = config
+
+        self.pairs_trader_ = pairs_trader
+        self.trading_pair_ = LiveTradingPair(
+            config=config,
+            instruments=self.pairs_trader_.instruments_,
+        )
+        self.model_data_policy_ = ModelDataPolicy.create(
+            self.config_,
+            is_real_time=True,
+            pair=self.trading_pair_,
+        )
+        assert (
+            self.model_data_policy_ is not None
+        ), f"{self.fname()}: Unable to create ModelDataPolicy"
+
+        self.predictions_df_ = pd.DataFrame()
+        self.trading_signals_df_ = pd.DataFrame()
+
+        self.instruments_ = self.pairs_trader_.instruments_
+
+        App.instance().add_call(
+            stage=App.Stage.Config, func=self._on_config(), can_run_now=True
+        )
+
+    async def _on_config(self) -> None:
+        self.interval_sec_ = self.config_.get_value("interval_sec", 0)
+        assert self.interval_sec_ > 0, "interval_sec cannot be 0"
+        self.history_depth_sec_ = (
+            self.config_.get_value("history_depth_hours", 0) * SecPerHour
+        )
+        assert self.history_depth_sec_ > 0, "history_depth_hours cannot be 0"
+
+        self.allowed_md_lag_sec_ = self.config_.get_value("allowed_md_lag_sec", 3)
+
+        self.open_threshold_ = self.config_.get_value(
+            "model/disequilibrium/open_trshld", 0.0
+        )
+        self.close_threshold_ = self.config_.get_value(
+            "model/disequilibrium/close_trshld", 0.0
+        )
+
+        assert (
+            self.open_threshold_ > 0
+        ), "disequilibrium/open_trshld must be greater than 0"
+        assert (
+            self.close_threshold_ > 0
+        ), "disequilibrium/close_trshld must be greater than 0"
+
+        await self.pairs_trader_.subscribe_md()
+
+
+    def __repr__(self) -> str:
+        return f"{self.classname()}: trading_pair={self.trading_pair_}, mdp={self.model_data_policy_.__class__.__name__}, "
+
+    async def on_mkt_data_hist_snapshot(
+        self, hist_aggr: List[MdTradesAggregate]
+    ) -> None:
+        if not self._is_md_actual(hist_aggr=hist_aggr):
+            return
+
+        market_data_df: pd.DataFrame = self._create_md_df(hist_aggr=hist_aggr)
+        if len(market_data_df) == 0:
+            Log.warning(f"{self.fname()} Unable to create market data df")
+            return
+
+        self.trading_pair_.market_data_ = market_data_df
+
+        Log.info(f"{self.fname()}: Running prediction for pair: {self.trading_pair_}")
+        prediction = self.trading_pair_.run(
+            market_data_df, self.model_data_policy_.advance()
+        )
+        self.predictions_df_ = pd.concat(
+            [self.predictions_df_, prediction.to_df()], ignore_index=True
+        )
+
+        trading_instructions: List[TradingInstructions] = (
+            self._create_trading_instructions(
+                prediction=prediction, last_row=market_data_df.iloc[-1]
+            )
+        )
+        if trading_instructions is not None:
+            await self._send_trading_instructions(trading_instructions)
+
+    def _is_md_actual(self, hist_aggr: List[MdTradesAggregate]) -> bool:
+        if len(hist_aggr) == 0:
+            Log.warning(f"{self.fname()} list of aggregates IS EMPTY")
+            return False
+
+        curr_ns = current_nanoseconds()
+        
+        # MAYBE check market data length
+        
+        # at 18:05:01 we should see data for 18:04:00
+        lag_sec = (curr_ns - hist_aggr[-1].aggr_time_ns_) / NanoPerSec - self.interval_sec()
+        if lag_sec > self.allowed_md_lag_sec_:
+            Log.warning(
+                f"{self.fname()} {hist_aggr[-1].exch_inst_.details_short()}"
+                f" Lagging {int(lag_sec)} > {self.allowed_md_lag_sec_} seconds:"
+                f"\n{len(hist_aggr)} records"
+                f"\n{hist_aggr[-1].exch_inst_.base_asset_id_}: {hist_aggr[-1].tstamp()}"
+                f"\n{hist_aggr[-2].exch_inst_.base_asset_id_}: {hist_aggr[-2].tstamp()}"
+            )
+            return False
+        else:
+            Log.info(
+                f"{self.fname()} {hist_aggr[-1].exch_inst_.details_short()}"
+                f" Lag {int(lag_sec)} <= {self.allowed_md_lag_sec_} seconds"
+                f"\n{len(hist_aggr)} records"
+                f"\n{hist_aggr[-1].exch_inst_.base_asset_id_}: {hist_aggr[-1].tstamp()}"
+                f"\n{hist_aggr[-2].exch_inst_.base_asset_id_}: {hist_aggr[-2].tstamp()}"
+            )
+        return True
+
+    def _create_md_df(self, hist_aggr: List[MdTradesAggregate]) -> pd.DataFrame:
+        """
+                          tstamp              time_ns    symbol      open      high       low     close     volume  num_trades        vwap
+        0    2025-09-10 11:30:00  1757503800000000000  ADA-USDT    0.8750    0.8750    0.8743    0.8743  50710.500           0    0.874489
+        1    2025-09-10 11:30:00  1757503800000000000  SOL-USDT  219.9700  219.9800  219.6600  219.7000   2648.582           0  219.787847
+        2    2025-09-10 11:31:00  1757503860000000000  SOL-USDT  219.7000  219.7300  219.6200  219.6200   1134.886           0  219.663460
+        3    2025-09-10 11:31:00  1757503860000000000  ADA-USDT    0.8743    0.8745    0.8741    0.8741  10696.400           0    0.874234
+        4    2025-09-10 11:32:00  1757503920000000000  ADA-USDT    0.8742    0.8742    0.8739    0.8740  18546.900           0    0.874037
+        """
+
+        rows: List[Dict[str, Any]] = []
+
+        for aggr in hist_aggr:
+            exch_inst = aggr.exch_inst_
+
+            rows.append(
+                {
+                    # convert nanoseconds → tz-aware pandas timestamp
+                    "tstamp": pd.to_datetime(aggr.aggr_time_ns_, unit="ns", utc=True),
+                    "time_ns": aggr.aggr_time_ns_,
+                    "symbol": exch_inst.instrument_id().split("-", 1)[1],
+                    "exchange_id": exch_inst.exchange_id_,
+                    "instrument_id": exch_inst.instrument_id(),
+                    "open": exch_inst.get_price(aggr.open_),
+                    "high": exch_inst.get_price(aggr.high_),
+                    "low": exch_inst.get_price(aggr.low_),
+                    "close": exch_inst.get_price(aggr.close_),
+                    "volume": exch_inst.get_quantity(aggr.volume_),
+                    "num_trades": aggr.num_trades_,
+                    "vwap": exch_inst.get_price(aggr.vwap_),
+                }
+            )
+
+        source_md_df = pd.DataFrame(
+            rows,
+            columns=[
+                "tstamp",
+                "time_ns",
+                "symbol",
+                "exchange_id",
+                "instrument_id",
+                "open",
+                "high",
+                "low",
+                "close",
+                "volume",
+                "num_trades",
+                "vwap",
+            ],
+        )
+
+        # automatic sorting
+        source_md_df.sort_values(
+            by=["time_ns", "symbol"],
+            ascending=True,
+            inplace=True,
+            kind="mergesort",  # stable sort
+        )
+
+        source_md_df.reset_index(drop=True, inplace=True)
+
+        pt_mkt_data = LiveMarketData(config=self.config_, instruments=self.instruments_)
+        pt_mkt_data.origin_mkt_data_df_ = source_md_df
+        pt_mkt_data.set_market_data()
+
+        return pt_mkt_data.market_data_df_
+
+    def interval_sec(self) -> IntervalSecT:
+        return self.interval_sec_
+
+    def history_depth_sec(self) -> IntervalSecT:
+        return self.history_depth_sec_
+
+    async def _send_trading_instructions(
+        self, trading_instructions: List[TradingInstructions]
+    ) -> None:
+        for ti in trading_instructions:
+            Log.info(f"{self.fname()} Sending trading instructions {ti}")
+            await self.pairs_trader_.ti_sender_.send_trading_instructions(ti)
+
+    def _create_trading_instructions(
+        self, prediction: Prediction, last_row: pd.Series
+    ) -> List[TradingInstructions]:
+        trd_instructions: List[TradingInstructions] = []
+        pair = self.trading_pair_
+
+        scaled_disequilibrium = prediction.scaled_disequilibrium_
+        abs_scaled_disequilibrium = abs(scaled_disequilibrium)
+
+        if abs_scaled_disequilibrium >= self.open_threshold_:
+            trd_instructions = self._create_open_trade_instructions(
+                pair, row=last_row, prediction=prediction
+            )
+
+        elif abs_scaled_disequilibrium <= self.close_threshold_ or pair.to_stop_close_conditions(predicted_row=last_row):
+            trd_instructions = self._create_close_trade_instructions(
+                pair, row=last_row  # , prediction=prediction
+            )
+
+
+        return trd_instructions
+    
+    def _strength(self, scaled_disequilibrium: float) -> float:
+        # TODO PtLiveStrategy._strength()
+        return 1.0
+
+    def _create_open_trade_instructions(
+        self, pair: LiveTradingPair, row: pd.Series, prediction: Prediction
+    ) -> List[TradingInstructions]:
+        diseqlbrm = prediction.disequilibrium_
+        scaled_disequilibrium = prediction.scaled_disequilibrium_
+        if diseqlbrm > 0:
+            side_a = -1
+            side_b = 1
+        else:
+            side_a = 1
+            side_b = -1
+
+        ti_a: Optional[TradingInstructions] = TradingInstructions(
+            book=self.pairs_trader_.book_id_,
+            strategy_id=self.__class__.__name__,
+            ti_type=TradingInstructions.Type.TARGET_POSITION,
+            issued_ts_ns=current_nanoseconds(),
+            data=TargetPositionSignal(
+                strength=side_a * self._strength(scaled_disequilibrium),
+                exchange_id=pair.get_instrument_a().exchange_id_,
+                base_asset=pair.get_instrument_a().base_asset_id_,
+                quote_asset=pair.get_instrument_a().quote_asset_id_,
+                user_data={}
+            ),
+        )
+        if not ti_a:
+            return []
+        ti_b: Optional[TradingInstructions] = TradingInstructions(
+            book=self.pairs_trader_.book_id_,
+            strategy_id=self.__class__.__name__,
+            ti_type=TradingInstructions.Type.TARGET_POSITION,
+            issued_ts_ns=current_nanoseconds(),
+            data=TargetPositionSignal(
+                strength=side_b * self._strength(scaled_disequilibrium),
+                exchange_id=pair.get_instrument_b().exchange_id_,
+                base_asset=pair.get_instrument_b().base_asset_id_,
+                quote_asset=pair.get_instrument_b().quote_asset_id_,
+                user_data={}
+            ),
+        )
+        if not ti_b:
+            return []
+        return [ti_a, ti_b]
+
+
+    def _create_close_trade_instructions(
+        self, pair: LiveTradingPair, row: pd.Series
+    ) -> List[TradingInstructions]:
+        ti_a: Optional[TradingInstructions] = TradingInstructions(
+            book=self.pairs_trader_.book_id_,
+            strategy_id=self.__class__.__name__,
+            ti_type=TradingInstructions.Type.TARGET_POSITION,
+            issued_ts_ns=current_nanoseconds(),
+            data=TargetPositionSignal(
+                strength=0,
+                exchange_id=pair.get_instrument_a().exchange_id_,
+                base_asset=pair.get_instrument_a().base_asset_id_,
+                quote_asset=pair.get_instrument_a().quote_asset_id_,
+                user_data={}
+            ),
+        )
+        if not ti_a:
+            return []
+        ti_b: Optional[TradingInstructions] = TradingInstructions(
+            book=self.pairs_trader_.book_id_,
+            strategy_id=self.__class__.__name__,
+            ti_type=TradingInstructions.Type.TARGET_POSITION,
+            issued_ts_ns=current_nanoseconds(),
+            data=TargetPositionSignal(
+                strength=0,
+                exchange_id=pair.get_instrument_b().exchange_id_,
+                base_asset=pair.get_instrument_b().base_asset_id_,
+                quote_asset=pair.get_instrument_b().quote_asset_id_,
+                user_data={}
+            ),
+        )
+        if not ti_b:
+            return []
+        return [ti_a, ti_b]

lib/pt_strategy/model_data_policy.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import copy
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, cast
+
+import numpy as np
+import pandas as pd
+
+from cvttpy_tools.config import Config
+
+@dataclass
+class DataWindowParams:
+    training_size_: int
+    training_start_index_: int
+
+
+class ModelDataPolicy(ABC):
+    config_: Config
+    current_data_params_: DataWindowParams
+    count_: int
+    is_real_time_: bool
+
+    def __init__(self, config: Config, *args: Any, **kwargs: Any):
+        self.config_ = config
+        self.current_data_params_ = DataWindowParams(
+            training_size_=config.get_value("model/training_size", 120),
+            training_start_index_=0,
+        )
+        self.count_ = 0
+        self.is_real_time_ = kwargs.get("is_real_time", False)
+
+    @abstractmethod
+    def advance(self, mkt_data_df: Optional[pd.DataFrame] = None) -> DataWindowParams:
+        self.count_ += 1
+        if not self.is_real_time_:
+            print(self.count_, end="\r")
+        return self.current_data_params_
+
+    @staticmethod
+    def create(config: Config, *args: Any, **kwargs: Any) -> ModelDataPolicy:
+        import importlib
+
+        model_data_policy_class_name = config.get_value("model/model_data_policy_class", None)
+        assert model_data_policy_class_name is not None
+        module_name, class_name = model_data_policy_class_name.rsplit(".", 1)
+        module = importlib.import_module(module_name)
+        model_training_data_policy_object = getattr(module, class_name)(
+            config=config, *args, **kwargs
+        )
+        return cast(ModelDataPolicy, model_training_data_policy_object)
+
+
+class RollingWindowDataPolicy(ModelDataPolicy):
+    def __init__(self, config: Config, *args: Any, **kwargs: Any):
+        super().__init__(config, *args, **kwargs)
+        self.count_ = 1
+
+    def advance(self, mkt_data_df: Optional[pd.DataFrame] = None) -> DataWindowParams:
+        super().advance(mkt_data_df)
+        if self.is_real_time_:
+            self.current_data_params_.training_start_index_ = 0
+            if mkt_data_df and len(mkt_data_df) > self.curren_data_params_.training_size_:
+                self.current_data_params_.training_start_index_ = -self.curren_data_params_.training_size_ 
+        else:
+            self.current_data_params_.training_start_index_ += 1
+        return self.current_data_params_
+
+
+class OptimizedWndDataPolicy(ModelDataPolicy, ABC):
+    mkt_data_df_: pd.DataFrame
+    pair_: TradingPair  # type: ignore
+    min_training_size_: int
+    max_training_size_: int
+    end_index_: int
+    prices_a_: np.ndarray
+    prices_b_: np.ndarray
+
+    def __init__(self, config: Config, *args: Any, **kwargs: Any):
+        super().__init__(config, *args, **kwargs)
+        assert (
+            kwargs.get("pair") is not None
+        ), "pair must be provided"
+        assert (config.key_exists("model/max_training_size") and config.key_exists("model/min_training_size")
+            ), "min_training_size and max_training_size must be provided"
+        self.min_training_size_ = cast(int, config.get_value("model/min_training_size"))
+        self.max_training_size_ = cast(int, config.get_value("model/max_training_size"))
+
+        from pairs_trading.lib.pt_strategy.trading_pair import TradingPair
+        self.pair_ = cast(TradingPair, kwargs.get("pair"))        
+        
+        if "mkt_data" in kwargs:
+            self.mkt_data_df_ = cast(pd.DataFrame, kwargs.get("mkt_data"))
+            col_a, col_b = self.pair_.colnames()
+            self.prices_a_ = np.array(self.mkt_data_df_[col_a])
+            self.prices_b_ = np.array(self.mkt_data_df_[col_b])
+        assert self.min_training_size_ < self.max_training_size_
+
+
+    def advance(self, mkt_data_df: Optional[pd.DataFrame] = None) -> DataWindowParams:
+        super().advance(mkt_data_df)
+        if mkt_data_df is not None:
+            self.mkt_data_df_ = mkt_data_df
+
+        if self.is_real_time_:
+            self.end_index_ = len(self.mkt_data_df_) - 1
+        else:
+            self.end_index_ = self.current_data_params_.training_start_index_ + self.max_training_size_
+            if self.end_index_ > len(self.mkt_data_df_) - 1:
+                self.end_index_ = len(self.mkt_data_df_) - 1
+                self.current_data_params_.training_start_index_ = self.end_index_ - self.max_training_size_
+                if self.current_data_params_.training_start_index_ < 0:
+                    self.current_data_params_.training_start_index_ = 0
+
+        col_a, col_b = self.pair_.colnames()
+        self.prices_a_ = np.array(self.mkt_data_df_[col_a])
+        self.prices_b_ = np.array(self.mkt_data_df_[col_b])
+
+        self.current_data_params_ = self.optimize_window_size()
+        return self.current_data_params_
+
+    @abstractmethod
+    def optimize_window_size(self) -> DataWindowParams:
+        ...
+
+class EGOptimizedWndDataPolicy(OptimizedWndDataPolicy):
+    '''
+    # Engle-Granger cointegration test
+    *** VERY SLOW ***
+    '''
+    def __init__(self, config: Config, *args: Any, **kwargs: Any):
+        super().__init__(config, *args, **kwargs)
+
+    def optimize_window_size(self) -> DataWindowParams:
+        # Run Engle-Granger cointegration test
+        last_pvalue = 1.0
+        result = copy.copy(self.current_data_params_)
+        for trn_size in range(self.min_training_size_, self.max_training_size_):
+            if self.end_index_ - trn_size < 0:
+                break
+
+            from statsmodels.tsa.stattools import coint  # type: ignore
+
+            start_index = self.end_index_ - trn_size
+            series_a = self.prices_a_[start_index : self.end_index_]
+            series_b = self.prices_b_[start_index : self.end_index_]
+            eg_pvalue = float(coint(series_a, series_b)[1])
+            if eg_pvalue < last_pvalue:
+                last_pvalue = eg_pvalue
+                result.training_size_ = trn_size
+                result.training_start_index_ = start_index
+
+        # print(
+        #     f"*** DEBUG *** end_index={self.end_index_}, best_trn_size={self.current_data_params_.training_size}, {last_pvalue=}"
+        # )
+        return result
+
+class ADFOptimizedWndDataPolicy(OptimizedWndDataPolicy):
+    # Augmented Dickey-Fuller test
+    def __init__(self, config: Config, *args: Any, **kwargs: Any):
+        super().__init__(config, *args, **kwargs)
+
+    def optimize_window_size(self) -> DataWindowParams:
+        from statsmodels.regression.linear_model import OLS
+        from statsmodels.tools.tools import add_constant
+        from statsmodels.tsa.stattools import adfuller
+
+        last_pvalue = 1.0
+        result = copy.copy(self.current_data_params_)
+        for trn_size in range(self.min_training_size_, self.max_training_size_):
+            if self.end_index_ - trn_size < 0:
+                break
+            start_index = self.end_index_ - trn_size
+            y = self.prices_a_[start_index : self.end_index_]
+            x = self.prices_b_[start_index : self.end_index_]
+
+            # Add constant to x for intercept
+            x_with_const = add_constant(x)
+
+            # OLS regression: y = a + b*x + e
+            model = OLS(y, x_with_const).fit()
+            residuals = y - model.predict(x_with_const)
+
+            # ADF test on residuals
+            try:
+                adf_result = adfuller(residuals, maxlag=1, regression="c")
+                adf_pvalue = float(adf_result[1])
+            except Exception as e:
+                # Handle edge cases with exception (e.g., constant series, etc.)
+                adf_pvalue = 1.0
+
+            if adf_pvalue < last_pvalue:
+                last_pvalue = adf_pvalue
+                result.training_size_ = trn_size
+                result.training_start_index_ = start_index
+
+        # print(
+        #     f"*** DEBUG *** end_index={self.end_index_},"
+        #     f" best_trn_size={self.current_data_params_.training_size},"
+        #     f" {last_pvalue=}"
+        # )
+        return result
+    
+class JohansenOptdWndDataPolicy(OptimizedWndDataPolicy):
+    # Johansen test
+    def __init__(self, config: Config, *args: Any, **kwargs: Any):
+        super().__init__(config, *args, **kwargs)
+
+    def optimize_window_size(self) -> DataWindowParams:
+        from statsmodels.tsa.vector_ar.vecm import coint_johansen
+        import numpy as np
+
+        best_stat = -np.inf
+        best_trn_size = 0
+        best_start_index = -1
+
+        result = copy.copy(self.current_data_params_)
+        for trn_size in range(self.min_training_size_, self.max_training_size_):
+            if self.end_index_ - trn_size < 0:
+                break
+            start_index = self.end_index_ - trn_size
+            series_a = self.prices_a_[start_index:self.end_index_]
+            series_b = self.prices_b_[start_index:self.end_index_]
+
+            # Combine into 2D matrix for Johansen test
+            try:
+                data = np.column_stack([series_a, series_b])
+
+                # Johansen test: det_order=0 (no deterministic trend), k_ar_diff=1 (lag)
+                res = coint_johansen(data, det_order=0, k_ar_diff=1)
+
+                # Trace statistic for cointegration rank 1
+                trace_stat = res.lr1[0]  # test stat for rank=0 vs >=1
+                critical_value = res.cvt[0, 1]  # 5% critical value
+
+                if trace_stat > best_stat:
+                    best_stat = trace_stat
+                    best_trn_size = trn_size
+                    best_start_index = start_index
+            except Exception:
+                continue
+
+        if best_trn_size > 0:
+            result.training_size_ = best_trn_size
+            result.training_start_index_ = best_start_index
+        else:
+            print("*** WARNING: No valid cointegration window found.")
+
+        # print(
+        #     f"*** DEBUG *** end_index={self.end_index_}, best_trn_size={best_trn_size}, trace_stat={best_stat}"
+        # )
+        return result

lib/pt_strategy/models.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+from typing import Optional
+
+import pandas as pd
+import statsmodels.api as sm
+
+
+
+from pairs_trading.lib.pt_strategy.pt_model import PairsTradingModel, Prediction
+from pairs_trading.lib.pt_strategy.trading_pair import TradingPair
+
+
+class OLSModel(PairsTradingModel):
+    model_: Optional[sm.regression.linear_model.RegressionResultsWrapper]
+    pair_predict_result_: Optional[pd.DataFrame]
+    zscore_df_: Optional[pd.DataFrame]
+
+    def predict(self, pair: TradingPair) -> Prediction:
+        self.training_df_ = pair.market_data_.copy()
+
+        zscore_df = self._fit_zscore(pair=pair)
+
+        assert zscore_df is not None
+        # zscore is both disequilibrium and scaled_disequilibrium
+        self.training_df_["dis-equilibrium"] = zscore_df[0]
+        self.training_df_["scaled_dis-equilibrium"] = zscore_df[0]
+
+        assert zscore_df is not None
+        return Prediction(
+            tstamp=pair.market_data_.iloc[-1]["tstamp"],
+            disequilibrium=self.training_df_["dis-equilibrium"].iloc[-1],
+            scaled_disequilibrium=self.training_df_["scaled_dis-equilibrium"].iloc[-1],
+        )
+
+    def _fit_zscore(self, pair: TradingPair) -> pd.DataFrame:
+        assert self.training_df_ is not None
+        symbol_a_px_series = self.training_df_[pair.colnames()].iloc[:, 0]
+        symbol_b_px_series = self.training_df_[pair.colnames()].iloc[:, 1]
+
+        symbol_a_px_series, symbol_b_px_series = symbol_a_px_series.align(
+            symbol_b_px_series, axis=0
+        )
+
+        X = sm.add_constant(symbol_b_px_series)
+        self.model_ = sm.OLS(symbol_a_px_series, X).fit()
+        assert self.model_ is not None
+
+        # alternate way would be to use models residuals (will give identical results)
+        # alpha, beta = self.model_.params
+        # spread = symbol_a_px_series - (alpha + beta * symbol_b_px_series)
+        spread = self.model_.resid
+        return pd.DataFrame((spread - spread.mean()) / spread.std())
+
+
+class VECMModel(PairsTradingModel):
+    def predict(self, pair: TradingPair) -> Prediction:
+        self.training_df_ = pair.market_data_.copy()
+        assert self.training_df_ is not None
+        vecm_fit = self._fit_VECM(pair=pair)
+
+        assert vecm_fit is not None
+        predicted_prices = vecm_fit.predict(steps=1)
+
+        # Convert prediction to a DataFrame for readability
+        predicted_df = pd.DataFrame(
+            predicted_prices, columns=pd.Index(pair.colnames()), dtype=float
+        )
+
+        disequilibrium = (predicted_df[pair.colnames()] @ vecm_fit.beta)[0][0]
+        scaled_disequilibrium = (disequilibrium - self.training_mu_) / self.training_std_
+        return Prediction(
+            tstamp=pair.market_data_.iloc[-1]["tstamp"],
+            disequilibrium=disequilibrium,
+            scaled_disequilibrium=scaled_disequilibrium,
+        )
+        
+    def _fit_VECM(self, pair: TradingPair) -> VECMResults: # type: ignore
+        from statsmodels.tsa.vector_ar.vecm import VECM, VECMResults
+
+        vecm_df = self.training_df_[pair.colnames()].reset_index(drop=True)
+        vecm_model = VECM(vecm_df, coint_rank=1)
+        vecm_fit = vecm_model.fit()
+
+        assert vecm_fit is not None
+
+        # Check if the model converged properly
+        if not hasattr(vecm_fit, "beta") or vecm_fit.beta is None:
+            print(f"{self}: VECM model failed to converge properly")
+
+        diseq_series = self.training_df_[pair.colnames()] @ vecm_fit.beta
+        # print(diseq_series.shape)
+        self.training_mu_ = float(diseq_series[0].mean())
+        self.training_std_ = float(diseq_series[0].std())
+
+        self.training_df_["dis-equilibrium"] = (
+            self.training_df_[pair.colnames()] @ vecm_fit.beta
+        )
+        # Normalize the dis-equilibrium
+        self.training_df_["scaled_dis-equilibrium"] = (
+            diseq_series - self.training_mu_
+        ) / self.training_std_
+
+        return vecm_fit
+

lib/pt_strategy/prediction.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import pandas as pd
+
+
+class Prediction:
+    tstamp_: pd.Timestamp
+    disequilibrium_: float
+    scaled_disequilibrium_: float
+
+    def __init__(self, tstamp: pd.Timestamp, disequilibrium: float, scaled_disequilibrium: float):
+        self.tstamp_ = tstamp
+        self.disequilibrium_ = disequilibrium
+        self.scaled_disequilibrium_ = scaled_disequilibrium
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "tstamp": self.tstamp_,
+            "disequilibrium": self.disequilibrium_,
+            "signed_scaled_disequilibrium": self.scaled_disequilibrium_,
+            "scaled_disequilibrium": abs(self.scaled_disequilibrium_),
+            # "pair": self.pair_,
+        }
+    def to_df(self) -> pd.DataFrame:
+        return pd.DataFrame([self.to_dict()])
+    

lib/pt_strategy/pt_market_data.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+# ---
+from cvttpy_tools.base import NamedObject
+from cvttpy_tools.config import Config
+from cvttpy_tools.settings.cvtt_types import JsonDictT
+
+# ---
+from cvttpy_trading.trading.mkt_data.md_summary import MdTradesAggregate
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+# ---
+from pairs_trading.lib.tools.data_loader import load_market_data
+
+
+class PtMarketData(NamedObject, ABC):
+    config_: Config
+    origin_mkt_data_df_: pd.DataFrame
+    market_data_df_: pd.DataFrame
+    stat_model_price_: str
+    instruments_: List[ExchangeInstrument]
+    symbol_a_: str
+    symbol_b_: str
+
+    def __init__(self, config: Config, instruments: List[ExchangeInstrument]):
+        self.config_ = config
+        self.origin_mkt_data_df_ = pd.DataFrame()
+        self.market_data_df_ = pd.DataFrame()
+        self.stat_model_price_ = self.config_.get_value("model/stat_model_price")
+
+        self.instruments_ = instruments
+        assert len(self.instruments_) > 0, "No instruments found in config"
+        self.symbol_a_ = self.instruments_[0].instrument_id().split("-", 1)[1]
+        self.symbol_b_ = self.instruments_[1].instrument_id().split("-", 1)[1]
+
+    @abstractmethod
+    def md_columns(self) -> List[str]: ...
+
+    @abstractmethod
+    def rename_columns(self, symbol_df: pd.DataFrame) -> pd.DataFrame: ...
+    
+    @abstractmethod
+    def tranform_df_target_colnames(self) -> List[str]: ...
+        
+    def set_market_data(self) -> None:
+        self.market_data_df_ = pd.DataFrame(
+            self._transform_dataframe(self.origin_mkt_data_df_)[
+                ["tstamp"] + self.tranform_df_target_colnames()
+            ]
+        )
+
+        self.market_data_df_ = self.market_data_df_.dropna().reset_index(drop=True)
+        self.market_data_df_["tstamp"] = pd.to_datetime(self.market_data_df_["tstamp"])
+        self.market_data_df_ = self.market_data_df_.sort_values("tstamp")
+
+    def colnames(self) -> List[str]:
+        return [
+            f"{self.stat_model_price_}_{self.symbol_a_}",
+            f"{self.stat_model_price_}_{self.symbol_b_}",
+        ]
+
+    def _transform_dataframe(self, df: pd.DataFrame) -> pd.DataFrame:
+        df_selected: pd.DataFrame = pd.DataFrame(df[self.md_columns()])
+        result_df = (
+            pd.DataFrame(df_selected["tstamp"]).drop_duplicates().reset_index(drop=True)
+        )
+
+        # For each unique symbol, add a corresponding stat_model_price column
+        symbols = df_selected["symbol"].unique()
+
+        for symbol in symbols:
+            # Filter rows for this symbol
+            df_symbol = df_selected[df_selected["symbol"] == symbol].reset_index(
+                drop=True
+            )
+            # Create column name like "close-COIN"
+            temp_df: pd.DataFrame = self.rename_columns(df_symbol)
+            # Join with our result dataframe
+            result_df = pd.merge(result_df, temp_df, on="tstamp", how="left")
+            result_df = result_df.reset_index(
+                drop=True
+            )  # do not dropna() since irrelevant symbol would affect dataset
+
+        return result_df.dropna()
+    
+class ResearchMarketData(PtMarketData):
+    current_index_: int
+    is_execution_price_: bool
+
+    def __init__(self, config: Config, instruments: List[ExchangeInstrument]):
+        super().__init__(config, instruments)
+        self.current_index_ = 0
+        self.is_execution_price_ = self.config_.key_exists("execution_price")
+        if self.is_execution_price_:
+            self.execution_price_column_ = self.config_.get_value("execution_price")["column"]
+            self.execution_price_shift_ = self.config_.get_value("execution_price")["shift"]
+        else:
+            self.execution_price_column_ = None
+            self.execution_price_shift_ = 0
+
+    def has_next(self) -> bool:
+        return self.current_index_ < len(self.market_data_df_)
+
+    def get_next(self) -> pd.Series:
+        result = self.market_data_df_.iloc[self.current_index_]
+        self.current_index_ += 1
+        return result
+
+    def load(self) -> None:
+        datafiles: List[str] = self.config_.get_value("datafiles", [])
+        assert len(datafiles) > 0, "No datafiles found in config"
+
+        extra_minutes: int = self.execution_price_shift_
+
+        for datafile in datafiles:
+            md_df = load_market_data(
+                datafile=datafile,
+                instruments=self.instruments_,
+                db_table_name=self.config_.get_value("market_data_loading")[
+                    self.instruments_[0].user_data_.get("instrument_type", "?instrument_type?")
+                ]["db_table_name"],
+                trading_hours=self.config_.get_value("trading_hours"),
+                extra_minutes=extra_minutes,
+            )
+            self.origin_mkt_data_df_ = pd.concat([self.origin_mkt_data_df_, md_df])
+
+        self.origin_mkt_data_df_ = self.origin_mkt_data_df_.sort_values(by="tstamp")
+        self.origin_mkt_data_df_ = self.origin_mkt_data_df_.dropna().reset_index(
+            drop=True
+        )
+        self.set_market_data()
+        self._set_execution_price_data()
+
+    def _set_execution_price_data(self) -> None:
+        if not self.is_execution_price_:
+            return
+        if not self.config_.key_exists("execution_price"):
+            self.market_data_df_[f"exec_price_{self.symbol_a_}"] = self.market_data_df_[
+                f"{self.stat_model_price_}_{self.symbol_a_}"
+            ]
+            self.market_data_df_[f"exec_price_{self.symbol_b_}"] = self.market_data_df_[
+                f"{self.stat_model_price_}_{self.symbol_b_}"
+            ]
+            return
+        execution_price_column = self.config_.get_value("execution_price")["column"]
+        execution_price_shift = self.config_.get_value("execution_price")["shift"]
+        self.market_data_df_[f"exec_price_{self.symbol_a_}"] = self.market_data_df_[
+            f"{execution_price_column}_{self.symbol_a_}"
+        ].shift(-execution_price_shift)
+        self.market_data_df_[f"exec_price_{self.symbol_b_}"] = self.market_data_df_[
+            f"{execution_price_column}_{self.symbol_b_}"
+        ].shift(-execution_price_shift)
+        self.market_data_df_ = self.market_data_df_.dropna().reset_index(drop=True)
+
+    def md_columns(self) -> List[str]: 
+        # @abstractmethod
+        if self.is_execution_price_:
+            return ["tstamp", "symbol", self.stat_model_price_, self.execution_price_column_]
+        else:
+            return ["tstamp", "symbol", self.stat_model_price_]
+
+    def rename_columns(self, selected_symbol_df: pd.DataFrame) -> pd.DataFrame:  
+        # @abstractmethod
+        symbol = selected_symbol_df.iloc[0]["symbol"]
+        new_price_column = f"{self.stat_model_price_}_{symbol}"
+        if self.is_execution_price_:
+            new_execution_price_column = f"{self.execution_price_column_}_{symbol}"
+
+            # Create temporary dataframe with timestamp and price
+            temp_df = pd.DataFrame(
+                {
+                    "tstamp": selected_symbol_df["tstamp"],
+                    new_price_column: selected_symbol_df[self.stat_model_price_],
+                    new_execution_price_column: selected_symbol_df[self.execution_price_column_],
+                }
+            )
+        else:
+            temp_df = pd.DataFrame(
+                {
+                    "tstamp": selected_symbol_df["tstamp"],
+                    new_price_column: selected_symbol_df[self.stat_model_price_],
+                }
+            )
+        return temp_df
+
+    def tranform_df_target_colnames(self):
+        # @abstractmethod
+        return self.colnames() + self.orig_exec_prices_colnames()
+    
+    def orig_exec_prices_colnames(self) -> List[str]:
+        return [
+            f"{self.execution_price_column_}_{self.symbol_a_}",
+            f"{self.execution_price_column_}_{self.symbol_b_}",
+        ] if self.is_execution_price_ else []
+
+class LiveMarketData(PtMarketData):
+
+    def __init__(self, config: Config, instruments: List[ExchangeInstrument]):
+        super().__init__(config, instruments)
+
+    def md_columns(self) -> List[str]: 
+        # @abstractmethod
+        return ["tstamp", "symbol", self.stat_model_price_]
+
+    def rename_columns(self, selected_symbol_df: pd.DataFrame) -> pd.DataFrame:  
+        # @abstractmethod
+        symbol = selected_symbol_df.iloc[0]["symbol"]
+        new_price_column = f"{self.stat_model_price_}_{symbol}"
+        temp_df = pd.DataFrame(
+            {
+                "tstamp": selected_symbol_df["tstamp"],
+                new_price_column: selected_symbol_df[self.stat_model_price_],
+            }
+        )
+        return temp_df
+
+    def tranform_df_target_colnames(self):
+        # @abstractmethod
+        return self.colnames()

lib/pt_strategy/pt_model.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, cast
+
+# ---
+from cvttpy_tools.config import Config
+# ---
+from pairs_trading.lib.pt_strategy.prediction import Prediction
+from pairs_trading.lib.pt_strategy.trading_pair import TradingPair
+    
+class PairsTradingModel(ABC):
+
+    @abstractmethod
+    def predict(self, pair: TradingPair) -> Prediction: # type: ignore[assignment]
+        ...
+    
+    @staticmethod
+    def create(config: Config) -> PairsTradingModel:
+        import importlib
+        
+        model_class_name = config.get_value("model/model_class", None)
+        assert model_class_name is not None
+        module_name, class_name = model_class_name.rsplit(".", 1)
+        module = importlib.import_module(module_name)
+        model_object = getattr(module, class_name)()
+        return cast(PairsTradingModel, model_object)
+
+        
+

lib/pt_strategy/research_strategy.py

@@ -0,0 +1,305 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+# ---
+from cvttpy_tools.config import Config
+# ---
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+# ---
+from pairs_trading.lib.pt_strategy.model_data_policy import ModelDataPolicy
+from pairs_trading.lib.pt_strategy.pt_market_data import ResearchMarketData
+from pairs_trading.lib.pt_strategy.pt_model import Prediction
+from pairs_trading.lib.pt_strategy.trading_pair import PairState, TradingPair, ResearchTradingPair
+
+class PtResearchStrategy:
+    config_: Config
+    trading_pair_: ResearchTradingPair
+    model_data_policy_: ModelDataPolicy
+    pt_mkt_data_: ResearchMarketData 
+
+    trades_: List[pd.DataFrame]
+    predictions_df_: pd.DataFrame
+
+    def __init__(
+        self,
+        config: Config,
+        instruments: List[ExchangeInstrument]
+    ):
+        from pairs_trading.lib.pt_strategy.model_data_policy import ModelDataPolicy
+        from pairs_trading.lib.pt_strategy.trading_pair import TradingPair
+
+        self.config_ = config
+        self.trades_ = []
+        self.trading_pair_ = ResearchTradingPair(config=config, instruments=instruments)
+        self.predictions_df_ = pd.DataFrame()
+
+        import copy
+
+        # modified config must be passed to PtMarketData
+        config_copy = copy.deepcopy(config)
+        config_copy.set_value("instruments", instruments)
+        self.pt_mkt_data_ = ResearchMarketData(config=config_copy, instruments=instruments)
+        self.pt_mkt_data_.load()
+        self.model_data_policy_ = ModelDataPolicy.create(
+            config_copy, mkt_data=self.pt_mkt_data_.market_data_df_, pair=self.trading_pair_
+        )
+
+    def outstanding_positions(self) -> List[Dict[str, Any]]:
+        return list(self.trading_pair_.user_data_.get("outstanding_positions", []))
+
+    def run(self) -> None:
+        training_minutes = self.config_.get_value("training_minutes", 120)
+        market_data_series: pd.Series
+        market_data_df = pd.DataFrame()
+
+        idx = 0
+        while self.pt_mkt_data_.has_next():
+            market_data_series = self.pt_mkt_data_.get_next()
+            new_row = pd.DataFrame([market_data_series])
+            market_data_df = pd.concat([market_data_df, new_row], ignore_index=True)
+            if idx >= training_minutes:
+                break
+            idx += 1
+
+        assert idx >= training_minutes, "Not enough training data"
+
+        while self.pt_mkt_data_.has_next():
+
+            market_data_series = self.pt_mkt_data_.get_next()
+            new_row = pd.DataFrame([market_data_series])
+            market_data_df = pd.concat([market_data_df, new_row], ignore_index=True)
+
+            prediction = self.trading_pair_.run(
+                market_data_df, self.model_data_policy_.advance(mkt_data_df=market_data_df)
+            )
+            self.predictions_df_ = pd.concat(
+                [self.predictions_df_, prediction.to_df()], ignore_index=True
+            )
+            assert prediction is not None
+
+            trades = self._create_trades(
+                prediction=prediction, last_row=market_data_df.iloc[-1]
+            )
+            if trades is not None:
+                self.trades_.append(trades)
+
+        trades = self._handle_outstanding_positions()
+        if trades is not None:
+            self.trades_.append(trades)
+
+    def _create_trades(
+        self, prediction: Prediction, last_row: pd.Series
+    ) -> Optional[pd.DataFrame]:
+        pair = self.trading_pair_
+        trades = None
+
+        open_threshold = self.config_.get_value("model/disequilibrium/open_trshld")
+        close_threshold = self.config_.get_value("model/disequilibrium/close_trshld")
+        scaled_disequilibrium = prediction.scaled_disequilibrium_
+        abs_scaled_disequilibrium = abs(scaled_disequilibrium)
+
+        if pair.user_data_["state"] in [
+            PairState.INITIAL,
+            PairState.CLOSE,
+            PairState.CLOSE_POSITION,
+            PairState.CLOSE_STOP_LOSS,
+            PairState.CLOSE_STOP_PROFIT,
+        ]:
+            if abs_scaled_disequilibrium >= open_threshold:
+                trades = self._create_open_trades(
+                    pair, row=last_row, prediction=prediction
+                )
+                if trades is not None:
+                    trades["status"] = PairState.OPEN.name
+                    print(f"OPEN TRADES:\n{trades}")
+                    pair.user_data_["state"] = PairState.OPEN
+                    pair.on_open_trades(trades)
+
+        elif pair.user_data_["state"] == PairState.OPEN:
+            if abs_scaled_disequilibrium <= close_threshold:
+                trades = self._create_close_trades(
+                    pair, row=last_row, prediction=prediction
+                )
+                if trades is not None:
+                    trades["status"] = PairState.CLOSE.name
+                    print(f"CLOSE TRADES:\n{trades}")
+                    pair.user_data_["state"] = PairState.CLOSE
+                    pair.on_close_trades(trades)
+            elif pair.to_stop_close_conditions(predicted_row=last_row):
+                trades = self._create_close_trades(pair, row=last_row)
+                if trades is not None:
+                    trades["status"] = pair.user_data_["stop_close_state"].name
+                    print(f"STOP CLOSE TRADES:\n{trades}")
+                    pair.user_data_["state"] = pair.user_data_["stop_close_state"]
+                    pair.on_close_trades(trades)
+
+        return trades
+
+    def _handle_outstanding_positions(self) -> Optional[pd.DataFrame]:
+        trades = None
+        pair = self.trading_pair_
+
+        # Outstanding positions
+        if pair.user_data_["state"] == PairState.OPEN:
+            print(f"{pair}:  *** Position is NOT CLOSED. ***")
+            # outstanding positions
+            if self.config_.get_value("close_outstanding_positions", False):
+                close_position_row = pd.Series(pair.market_data_.iloc[-2])
+                # close_position_row["disequilibrium"] = 0.0
+                # close_position_row["scaled_disequilibrium"] = 0.0
+                # close_position_row["signed_scaled_disequilibrium"] = 0.0
+
+                trades = self._create_close_trades(
+                    pair=pair, row=close_position_row, prediction=None
+                )
+                if trades is not None:
+                    trades["status"] = PairState.CLOSE_POSITION.name
+                    print(f"CLOSE_POSITION TRADES:\n{trades}")
+                    pair.user_data_["state"] = PairState.CLOSE_POSITION
+                    pair.on_close_trades(trades)
+            else:
+                pair.add_outstanding_position(
+                    symbol=pair.symbol_a(),
+                    open_side=pair.user_data_["open_side_a"],
+                    open_px=pair.user_data_["open_px_a"],
+                    open_tstamp=pair.user_data_["open_tstamp"],
+                    last_mkt_data_row=pair.market_data_.iloc[-1],
+                )
+                pair.add_outstanding_position(
+                    symbol=pair.symbol_b(),
+                    open_side=pair.user_data_["open_side_b"],
+                    open_px=pair.user_data_["open_px_b"],
+                    open_tstamp=pair.user_data_["open_tstamp"],
+                    last_mkt_data_row=pair.market_data_.iloc[-1],
+                )
+        return trades
+
+    def _trades_df(self) -> pd.DataFrame:
+        types = {
+            "time": "datetime64[ns]",
+            "action": "string",
+            "symbol": "string",
+            "side": "string",
+            "price": "float64",
+            "disequilibrium": "float64",
+            "scaled_disequilibrium": "float64",
+            "signed_scaled_disequilibrium": "float64",
+            # "pair": "object",
+        }
+        columns = list(types.keys())
+        return pd.DataFrame(columns=columns).astype(types)
+
+    def _create_open_trades(
+        self, pair: ResearchTradingPair, row: pd.Series, prediction: Prediction
+    ) -> Optional[pd.DataFrame]:
+        colname_a, colname_b = pair.exec_prices_colnames()
+
+        tstamp = row["tstamp"]
+        diseqlbrm = prediction.disequilibrium_
+        scaled_disequilibrium = prediction.scaled_disequilibrium_
+        px_a = row[f"{colname_a}"]
+        px_b = row[f"{colname_b}"]
+
+        # creating the trades
+        df = self._trades_df()
+
+        print(f"OPEN_TRADES: {row["tstamp"]} {scaled_disequilibrium=}")
+        if diseqlbrm > 0:
+            side_a = "SELL"
+            side_b = "BUY"
+        else:
+            side_a = "BUY"
+            side_b = "SELL"
+
+        # save closing sides
+        pair.user_data_["open_side_a"] = side_a  # used in oustanding positions
+        pair.user_data_["open_side_b"] = side_b
+        pair.user_data_["open_px_a"] = px_a
+        pair.user_data_["open_px_b"] = px_b
+        pair.user_data_["open_tstamp"] = tstamp
+
+        pair.user_data_["close_side_a"] = side_b  # used for closing trades
+        pair.user_data_["close_side_b"] = side_a
+
+        # create opening trades
+        df.loc[len(df)] = {
+            "time": tstamp,
+            "symbol": pair.symbol_a(),
+            "side": side_a,
+            "action": "OPEN",
+            "price": px_a,
+            "disequilibrium": diseqlbrm,
+            "signed_scaled_disequilibrium": scaled_disequilibrium,
+            "scaled_disequilibrium": abs(scaled_disequilibrium),
+            # "pair": pair,
+        }
+        df.loc[len(df)] = {
+            "time": tstamp,
+            "symbol": pair.symbol_b(),
+            "side": side_b,
+            "action": "OPEN",
+            "price": px_b,
+            "disequilibrium": diseqlbrm,
+            "scaled_disequilibrium": abs(scaled_disequilibrium),
+            "signed_scaled_disequilibrium": scaled_disequilibrium,
+            # "pair": pair,
+        }
+        return df
+
+    def _create_close_trades(
+        self, pair: ResearchTradingPair, row: pd.Series, prediction: Optional[Prediction] = None
+    ) -> Optional[pd.DataFrame]:
+        colname_a, colname_b = pair.exec_prices_colnames()
+
+        tstamp = row["tstamp"]
+        if prediction is not None:
+            diseqlbrm = prediction.disequilibrium_
+            signed_scaled_disequilibrium = prediction.scaled_disequilibrium_
+            scaled_disequilibrium = abs(prediction.scaled_disequilibrium_)
+        else:
+            diseqlbrm = 0.0
+            signed_scaled_disequilibrium = 0.0
+            scaled_disequilibrium = 0.0
+        px_a = row[f"{colname_a}"]
+        px_b = row[f"{colname_b}"]
+
+        # creating the trades
+        df = self._trades_df()
+
+        # create opening trades
+        df.loc[len(df)] = {
+            "time": tstamp,
+            "symbol": pair.symbol_a(),
+            "side": pair.user_data_["close_side_a"],
+            "action": "CLOSE",
+            "price": px_a,
+            "disequilibrium": diseqlbrm,
+            "scaled_disequilibrium": scaled_disequilibrium,
+            "signed_scaled_disequilibrium": signed_scaled_disequilibrium,
+            # "pair": pair,
+        }
+        df.loc[len(df)] = {
+            "time": tstamp,
+            "symbol": pair.symbol_b(),
+            "side": pair.user_data_["close_side_b"],
+            "action": "CLOSE",
+            "price": px_b,
+            "disequilibrium": diseqlbrm,
+            "scaled_disequilibrium": scaled_disequilibrium,
+            "signed_scaled_disequilibrium": signed_scaled_disequilibrium,
+            # "pair": pair,
+        }
+        del pair.user_data_["close_side_a"]
+        del pair.user_data_["close_side_b"]
+
+        del pair.user_data_["open_tstamp"]
+        del pair.user_data_["open_px_a"]
+        del pair.user_data_["open_px_b"]
+        del pair.user_data_["open_side_a"]
+        del pair.user_data_["open_side_b"]
+        return df
+
+    def day_trades(self) -> pd.DataFrame:
+        return pd.concat(self.trades_, ignore_index=True)

lib/pt_strategy/results.py

@@ -0,0 +1,527 @@
+import os
+import sqlite3
+from datetime import date, datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+# ---
+from cvttpy_tools.config import Config
+# ---
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+# ---
+from pairs_trading.lib.pt_strategy.trading_pair import TradingPair
+
+# Recommended replacement adapters and converters for Python 3.12+
+# From: https://docs.python.org/3/library/sqlite3.html#sqlite3-adapter-converter-recipes
+def adapt_date_iso(val: date) -> str:
+    """Adapt datetime.date to ISO 8601 date."""
+    return val.isoformat()
+
+
+def adapt_datetime_iso(val: datetime) -> str:
+    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
+    return val.isoformat()
+
+def convert_date(val: bytes) -> date:
+    """Convert ISO 8601 date to datetime.date object."""
+    return datetime.fromisoformat(val.decode()).date()
+
+def convert_datetime(val: bytes) -> datetime:
+    """Convert ISO 8601 datetime to datetime.datetime object."""
+    return datetime.fromisoformat(val.decode())
+
+
+# Register the adapters and converters
+sqlite3.register_adapter(date, adapt_date_iso)
+sqlite3.register_adapter(datetime, adapt_datetime_iso)
+sqlite3.register_converter("date", convert_date)
+sqlite3.register_converter("datetime", convert_datetime)
+
+
+def create_result_database(db_path: str) -> None:
+    """
+    Create the SQLite database and required tables if they don't exist.
+    """
+    try:
+        # Create directory if it doesn't exist
+        db_dir = os.path.dirname(db_path)
+        if db_dir and not os.path.exists(db_dir):
+            os.makedirs(db_dir, exist_ok=True)
+            print(f"Created directory: {db_dir}")
+
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+
+        # Create the pt_bt_results table for completed trades
+        cursor.execute(
+            """
+            CREATE TABLE IF NOT EXISTS pt_bt_results (
+                date DATE,
+                pair TEXT,
+                symbol TEXT,
+                open_time DATETIME,
+                open_side TEXT,
+                open_price REAL,
+                open_quantity INTEGER,
+                open_disequilibrium REAL,
+                close_time DATETIME,
+                close_side TEXT,
+                close_price REAL,
+                close_quantity INTEGER,
+                close_disequilibrium REAL,
+                symbol_return REAL,
+                pair_return REAL,
+                close_condition TEXT
+            )
+        """
+        )
+        cursor.execute("DELETE FROM pt_bt_results;")
+
+        # Create the outstanding_positions table for open positions
+        cursor.execute(
+            """
+            CREATE TABLE IF NOT EXISTS outstanding_positions (
+                date DATE,
+                pair TEXT,
+                symbol TEXT,
+                position_quantity REAL,
+                last_price REAL,
+                unrealized_return REAL,
+                open_price REAL,
+                open_side TEXT
+            )
+        """
+        )
+        cursor.execute("DELETE FROM outstanding_positions;")
+
+        # Create the config table for storing configuration JSON for reference
+        cursor.execute(
+            """
+            CREATE TABLE IF NOT EXISTS config (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                run_timestamp DATETIME,
+                config_file_path TEXT,
+                config_json TEXT,
+                datafiles TEXT,
+                instruments TEXT
+            )
+        """
+        )
+        cursor.execute("DELETE FROM config;")
+
+        conn.commit()
+        conn.close()
+
+    except Exception as e:
+        print(f"Error creating result database: {str(e)}")
+        raise
+
+
+def store_config_in_database(
+    db_path: str,
+    config_file_path: str,
+    config: Config,
+    datafiles: List[Tuple[str, str]],
+    instruments: List[ExchangeInstrument],
+) -> None:
+    """
+    Store configuration information in the database for reference.
+    """
+    import json
+
+    if db_path.upper() == "NONE":
+        return
+
+    try:
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+
+        # Convert config to JSON string
+        config_json = json.dumps(config.data(), indent=2, default=str)
+
+        # Convert lists to comma-separated strings for storage
+        datafiles_str = ", ".join([f"{datafile}" for _, datafile in datafiles])
+        instruments_str = ", ".join(
+            [
+                inst.details_short()
+                for inst in instruments
+            ]
+        )
+
+        # Insert configuration record
+        cursor.execute(
+            """
+            INSERT INTO config (
+                run_timestamp, config_file_path, config_json, datafiles, instruments
+            ) VALUES (?, ?, ?, ?, ?)
+        """,
+            (
+                datetime.now(),
+                config_file_path,
+                config_json,
+                datafiles_str,
+                instruments_str,
+            ),
+        )
+
+        conn.commit()
+        conn.close()
+
+        print(f"Configuration stored in database")
+
+    except Exception as e:
+        print(f"Error storing configuration in database: {str(e)}")
+        import traceback
+
+        traceback.print_exc()
+
+
+def convert_timestamp(timestamp: Any) -> Optional[datetime]:
+    """Convert pandas Timestamp to Python datetime object for SQLite compatibility."""
+    if timestamp is None:
+        return None
+    if isinstance(timestamp, pd.Timestamp):
+        return timestamp.to_pydatetime()
+    elif isinstance(timestamp, datetime):
+        return timestamp
+    elif isinstance(timestamp, date):
+        return datetime.combine(timestamp, datetime.min.time())
+    elif isinstance(timestamp, str):
+        return datetime.strptime(timestamp, "%Y-%m-%d %H:%M:%S")
+    elif isinstance(timestamp, int):
+        return datetime.fromtimestamp(timestamp)
+    else:
+        raise ValueError(f"Unsupported timestamp type: {type(timestamp)}")
+
+
+
+DayT = str
+TradeT = Dict[str, Any]
+OutstandingPositionT = Dict[str, Any]
+class PairResearchResult:
+    """
+    Class to handle pair research results for a single pair across multiple days.
+    Simplified version of BacktestResult focused on single pair analysis.
+    """
+    trades_: Dict[DayT, pd.DataFrame]
+    outstanding_positions_: Dict[DayT, List[OutstandingPositionT]]
+    symbol_roundtrip_trades_: Dict[str, List[Dict[str, Any]]]
+    config_: Config
+
+    def __init__(self, config: Config) -> None:
+        self.config_ = config
+        self.trades_ = {}
+        self.outstanding_positions_ = {}
+        self.total_realized_pnl = 0.0
+        self.symbol_roundtrip_trades_ = {}
+
+    def add_day_results(self, day: DayT, trades: pd.DataFrame, outstanding_positions: List[Dict[str, Any]]) -> None:
+        assert isinstance(trades, pd.DataFrame)
+        self.trades_[day] = trades
+        self.outstanding_positions_[day] = outstanding_positions
+
+    def outstanding_positions(self) -> List[OutstandingPositionT]:
+        """Get all outstanding positions across all days as a flat list."""
+        res: List[Dict[str, Any]] = []
+        for day in self.outstanding_positions_.keys():
+            res.extend(self.outstanding_positions_[day])
+        return res
+    
+    def calculate_returns(self) -> None:
+        """Calculate and store total returns for the single pair across all days."""
+        self.extract_roundtrip_trades()
+        
+        self.total_realized_pnl = 0.0
+        
+        for day, day_trades in self.symbol_roundtrip_trades_.items():
+            for trade in day_trades:
+                self.total_realized_pnl += trade['symbol_return']
+    
+    def extract_roundtrip_trades(self) -> None: 
+        """
+        Extract round-trip trades by day, grouping open/close pairs for each symbol.
+        Returns a dictionary with day as key and list of completed round-trip trades.
+        """
+        def _symbol_return(trade1_side: str, trade1_px: float, trade2_side: str, trade2_px: float) -> float:
+            if trade1_side == "BUY" and trade2_side == "SELL":
+                return (trade2_px - trade1_px) / trade1_px * 100
+            elif trade1_side == "SELL" and trade2_side == "BUY":
+                return (trade1_px - trade2_px) / trade1_px * 100
+            else:
+                return 0
+        
+        # Process each day separately
+        for day, day_trades in self.trades_.items():
+
+            # Sort trades by timestamp for the day
+            sorted_trades = day_trades #sorted(day_trades, key=lambda x: x["timestamp"] if x["timestamp"] else pd.Timestamp.min)
+            
+            day_roundtrips = []
+            
+            # Process trades in groups of 4 (open A, open B, close A, close B)
+            for idx in range(0, len(sorted_trades), 4):
+                if idx + 3 >= len(sorted_trades):
+                    break
+                    
+                trade_a_1 = sorted_trades.iloc[idx]      # Open A
+                trade_b_1 = sorted_trades.iloc[idx + 1]  # Open B  
+                trade_a_2 = sorted_trades.iloc[idx + 2]  # Close A
+                trade_b_2 = sorted_trades.iloc[idx + 3]  # Close B
+                
+                # Validate trade sequence
+                if not (trade_a_1["action"] == "OPEN" and trade_a_2["action"] == "CLOSE"):
+                    continue
+                if not (trade_b_1["action"] == "OPEN" and trade_b_2["action"] == "CLOSE"):
+                    continue
+                    
+                # Calculate individual symbol returns
+                symbol_a_return = _symbol_return(
+                    trade_a_1["side"], trade_a_1["price"], 
+                    trade_a_2["side"], trade_a_2["price"]
+                )
+                symbol_b_return = _symbol_return(
+                    trade_b_1["side"], trade_b_1["price"], 
+                    trade_b_2["side"], trade_b_2["price"]
+                )
+                
+                pair_return = symbol_a_return + symbol_b_return
+                
+                # Create round-trip records for both symbols
+                funding_per_position = self.config_.get_value("funding_per_pair", 10000) / 2
+                
+                # Symbol A round-trip
+                day_roundtrips.append({
+                    "symbol": trade_a_1["symbol"],
+                    "open_side": trade_a_1["side"],
+                    "open_price": trade_a_1["price"],
+                    "open_time": trade_a_1["time"],
+                    "close_side": trade_a_2["side"],
+                    "close_price": trade_a_2["price"],
+                    "close_time": trade_a_2["time"],
+                    "symbol_return": symbol_a_return,
+                    "pair_return": pair_return,
+                    "shares": funding_per_position / trade_a_1["price"],
+                    "close_condition": trade_a_2.get("status", "UNKNOWN"),
+                    "open_disequilibrium": trade_a_1.get("disequilibrium"),
+                    "close_disequilibrium": trade_a_2.get("disequilibrium"),
+                })
+                
+                # Symbol B round-trip
+                day_roundtrips.append({
+                    "symbol": trade_b_1["symbol"],
+                    "open_side": trade_b_1["side"],
+                    "open_price": trade_b_1["price"],
+                    "open_time": trade_b_1["time"],
+                    "close_side": trade_b_2["side"],
+                    "close_price": trade_b_2["price"],
+                    "close_time": trade_b_2["time"],
+                    "symbol_return": symbol_b_return,
+                    "pair_return": pair_return,
+                    "shares": funding_per_position / trade_b_1["price"],
+                    "close_condition": trade_b_2.get("status", "UNKNOWN"),
+                    "open_disequilibrium": trade_b_1.get("disequilibrium"),
+                    "close_disequilibrium": trade_b_2.get("disequilibrium"),
+                })
+            
+            if day_roundtrips:
+                self.symbol_roundtrip_trades_[day] = day_roundtrips
+                
+    
+    def print_returns_by_day(self) -> None:
+        """
+        Print detailed return information for each day, grouped by day.
+        Shows individual symbol round-trips and daily totals.
+        """
+        
+        print("\n====== PAIR RESEARCH RETURNS BY DAY ======")
+        
+        total_return_all_days = 0.0
+        
+        for day, day_trades in sorted(self.symbol_roundtrip_trades_.items()):
+            
+            print(f"\n--- {day} ---")
+            
+            day_total_return = 0.0
+            pair_returns = []
+            
+            # Group trades by pair (every 2 trades form a pair)
+            for idx in range(0, len(day_trades), 2):
+                if idx + 1 < len(day_trades):
+                    trade_a = day_trades[idx]
+                    trade_b = day_trades[idx + 1]
+                    
+                    # Print individual symbol results
+                    print(f"  {trade_a['open_time'].time()}-{trade_a['close_time'].time()}")
+                    print(f"    {trade_a['symbol']}: {trade_a['open_side']} @ ${trade_a['open_price']:.2f} → "
+                          f"{trade_a['close_side']} @ ${trade_a['close_price']:.2f} | "
+                          f"Return: {trade_a['symbol_return']:+.2f}% | Shares: {trade_a['shares']:.2f}")
+                    
+                    print(f"    {trade_b['symbol']}: {trade_b['open_side']} @ ${trade_b['open_price']:.2f} → "
+                          f"{trade_b['close_side']} @ ${trade_b['close_price']:.2f} | "
+                          f"Return: {trade_b['symbol_return']:+.2f}% | Shares: {trade_b['shares']:.2f}")
+                    
+                    # Show disequilibrium info if available
+                    if trade_a.get('open_disequilibrium') is not None:
+                        print(f"    Disequilibrium: Open: {trade_a['open_disequilibrium']:.4f}, "
+                              f"Close: {trade_a['close_disequilibrium']:.4f}")
+                    
+                    pair_return = trade_a['pair_return']
+                    print(f"    Pair Return: {pair_return:+.2f}% | Close Condition: {trade_a['close_condition']}")
+                    print()
+                    
+                    pair_returns.append(pair_return)
+                    day_total_return += pair_return
+            
+            print(f"  Day Total Return: {day_total_return:+.2f}% ({len(pair_returns)} pairs)")
+            total_return_all_days += day_total_return
+        
+        print(f"\n====== TOTAL RETURN ACROSS ALL DAYS ======")
+        print(f"Total Return: {total_return_all_days:+.2f}%")
+        print(f"Total Days: {len(self.symbol_roundtrip_trades_)}")
+        if len(self.symbol_roundtrip_trades_) > 0:
+            print(f"Average Daily Return: {total_return_all_days / len(self.symbol_roundtrip_trades_):+.2f}%")
+    
+    def get_return_summary(self) -> Dict[str, Any]:
+        """
+        Get a summary of returns across all days.
+        Returns a dictionary with key metrics.
+        """
+        if len(self.symbol_roundtrip_trades_) == 0:
+            return {
+                "total_return": 0.0,
+                "total_days": 0,
+                "total_pairs": 0,
+                "average_daily_return": 0.0,
+                "best_day": None,
+                "worst_day": None,
+                "daily_returns": {}
+            }
+        
+        daily_returns = {}
+        total_return = 0.0
+        total_pairs = 0
+        
+        for day, day_trades in self.symbol_roundtrip_trades_.items():
+            day_return = 0.0
+            day_pairs = len(day_trades) // 2  # Each pair has 2 symbol trades
+            
+            for trade in day_trades:
+                day_return += trade['symbol_return']
+            
+            daily_returns[day] = {
+                "return": day_return,
+                "pairs": day_pairs
+            }
+            total_return += day_return
+            total_pairs += day_pairs
+        
+        best_day = max(daily_returns.items(), key=lambda x: x[1]["return"]) if daily_returns else None
+        worst_day = min(daily_returns.items(), key=lambda x: x[1]["return"]) if daily_returns else None
+        
+        return {
+            "total_return": total_return,
+            "total_days": len(self.symbol_roundtrip_trades_),
+            "total_pairs": total_pairs,
+            "average_daily_return": total_return / len(self.symbol_roundtrip_trades_) if self.symbol_roundtrip_trades_ else 0.0,
+            "best_day": best_day,
+            "worst_day": worst_day,
+            "daily_returns": daily_returns
+        }
+    
+    
+    def print_grand_totals(self) -> None:
+        """Print grand totals for the single pair analysis."""
+        summary = self.get_return_summary()
+        
+        print(f"\n====== PAIR RESEARCH GRAND TOTALS ======")
+        print('---')
+        print(f"Total Return: {summary['total_return']:+.2f}%")
+        print('---')
+        print(f"Total Days Traded: {summary['total_days']}")
+        print(f"Total Open-Close Actions: {summary['total_pairs']}")
+        print(f"Total Trades:  4 * {summary['total_pairs']} = {4 * summary['total_pairs']}")
+        
+        if summary['total_days'] > 0:
+            print(f"Average Daily Return: {summary['average_daily_return']:+.2f}%")
+        
+        if summary['best_day']:
+            best_day, best_data = summary['best_day']
+            print(f"Best Day: {best_day} ({best_data['return']:+.2f}%)")
+        
+        if summary['worst_day']:
+            worst_day, worst_data = summary['worst_day']
+            print(f"Worst Day: {worst_day} ({worst_data['return']:+.2f}%)")
+        
+        # Update the total_realized_pnl for backward compatibility
+        self.total_realized_pnl = summary['total_return']
+    
+    def analyze_pair_performance(self) -> None:
+        """
+        Main method to perform comprehensive pair research analysis.
+        Extracts round-trip trades, calculates returns, groups by day, and prints results.
+        """
+        print(f"\n{'='*60}")
+        print(f"PAIR RESEARCH PERFORMANCE ANALYSIS")
+        print(f"{'='*60}")
+        
+        self.calculate_returns()
+        self.print_returns_by_day()
+        self.print_outstanding_positions()
+        self._print_additional_metrics()
+        self.print_grand_totals()
+    
+    def _print_additional_metrics(self) -> None:
+        """Print additional performance metrics."""
+        summary = self.get_return_summary()
+        
+        if summary['total_days'] == 0:
+            return
+        
+        print(f"\n====== ADDITIONAL METRICS ======")
+        
+        # Calculate win rate
+        winning_days = sum(1 for day_data in summary['daily_returns'].values() if day_data['return'] > 0)
+        win_rate = (winning_days / summary['total_days']) * 100
+        print(f"Winning Days: {winning_days}/{summary['total_days']} ({win_rate:.1f}%)")
+        
+        # Calculate average trade return
+        if summary['total_pairs'] > 0:
+            # Each pair has 2 symbol trades, so total symbol trades = total_pairs * 2
+            total_symbol_trades = summary['total_pairs'] * 2
+            avg_symbol_return = summary['total_return'] / total_symbol_trades
+            print(f"Average Symbol Return: {avg_symbol_return:+.2f}%")
+            
+            avg_pair_return = summary['total_return'] / summary['total_pairs'] / 2  # Divide by 2 since we sum both symbols
+            print(f"Average Pair Return: {avg_pair_return:+.2f}%")
+        
+        # Show daily return distribution
+        daily_returns_list = [data['return'] for data in summary['daily_returns'].values()]
+        if daily_returns_list:
+            print(f"Daily Return Range: {min(daily_returns_list):+.2f}% to {max(daily_returns_list):+.2f}%")
+        
+    
+    def print_outstanding_positions(self) -> None:
+        """Print outstanding positions for the single pair."""
+        all_positions: List[OutstandingPositionT] = self.outstanding_positions()
+        if not all_positions:
+            print("\n====== NO OUTSTANDING POSITIONS ======")
+            return
+            
+        print(f"\n====== OUTSTANDING POSITIONS ======")
+        print(f"{'Symbol':<10} {'Side':<4} {'Shares':<10} {'Open $':<8} {'Current $':<10} {'Value $':<12}")
+        print("-" * 70)
+        
+        total_value = 0.0
+        for pos in all_positions:
+            current_value = pos.get("last_value", 0.0)
+            print(f"{pos['symbol']:<10} {pos['open_side']:<4} {pos['shares']:<10.2f} "
+                  f"{pos['open_px']:<8.2f} {pos['last_px']:<10.2f} {current_value:<12.2f}")
+            total_value += current_value
+        
+        print("-" * 70)
+        print(f"{'TOTAL VALUE':<60} ${total_value:<12.2f}")
+    
+    def get_total_realized_pnl(self) -> float:
+        """Get total realized PnL."""
+        return self.total_realized_pnl
+    

lib/pt_strategy/trading_pair.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List
+
+import pandas as pd
+
+# ---
+from cvttpy_tools.base import NamedObject
+from cvttpy_tools.config import Config
+# ---
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+# ---
+from pairs_trading.lib.pt_strategy.model_data_policy import DataWindowParams
+from pairs_trading.lib.pt_strategy.prediction import Prediction
+
+
+
+class PairState(Enum):
+    INITIAL = 1
+    OPEN = 2
+    CLOSE = 3
+    CLOSE_POSITION = 4
+    CLOSE_STOP_LOSS = 5
+    CLOSE_STOP_PROFIT = 6
+
+
+class TradingPair(NamedObject, ABC):
+    config_: Config
+    model_: Any # "PairsTradingModel"
+    market_data_: pd.DataFrame
+
+    user_data_: Dict[str, Any]
+    stat_model_price_: str
+
+    instruments_: List[ExchangeInstrument]
+
+    def __init__(
+        self,
+        config: Config,
+        instruments: List[ExchangeInstrument],
+    ):
+        from pairs_trading.lib.pt_strategy.pt_model import PairsTradingModel
+
+        self.config_ = config
+        self.model_ = PairsTradingModel.create(config)
+        self.user_data_ = {}
+        self.instruments_ = instruments
+        self.instruments_[0].user_data_["symbol"] = instruments[0].instrument_id().split("-", 1)[1]
+        self.instruments_[1].user_data_["symbol"] = instruments[1].instrument_id().split("-", 1)[1]        
+        self.stat_model_price_ = config.get_value("model/stat_model_price")
+        
+    def run(self, market_data: pd.DataFrame, data_params: DataWindowParams) -> Prediction:  # type: ignore[assignment]
+        self.market_data_ = market_data[
+            data_params.training_start_index_ : data_params.training_start_index_ + data_params.training_size_
+        ]
+        return self.model_.predict(pair=self)
+
+    def colnames(self) -> List[str]:
+        return [
+            f"{self.stat_model_price_}_{self.symbol_a()}",
+            f"{self.stat_model_price_}_{self.symbol_b()}",
+        ]
+    def symbol_a(self) -> str:
+        return self.get_instrument_a().user_data_["symbol"]
+    
+    def symbol_b(self) -> str:
+        return self.get_instrument_b().user_data_["symbol"]
+
+    def get_instrument_a(self) -> ExchangeInstrument:
+        return self.instruments_[0]
+
+    def get_instrument_b(self) -> ExchangeInstrument:
+        return self.instruments_[1]
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}:"
+            f" symbol_a={self.symbol_a()},"
+            f" symbol_b={self.symbol_b()},"
+            f" model={self.model_.__class__.__name__}"
+        )
+    
+class ResearchTradingPair(TradingPair):
+
+    def __init__(
+        self,
+        config: Config,
+        instruments: List[ExchangeInstrument],
+    ):
+        assert len(instruments) == 2, "Trading pair must have exactly 2 instruments"
+        super().__init__(config=config, instruments=instruments)
+
+        self.user_data_ = {
+            "state": PairState.INITIAL,
+        }
+        
+    def is_closed(self) -> bool:
+        return self.user_data_["state"] in [
+            PairState.CLOSE,
+            PairState.CLOSE_POSITION,
+            PairState.CLOSE_STOP_LOSS,
+            PairState.CLOSE_STOP_PROFIT,
+        ]
+
+    def is_open(self) -> bool:
+        return not self.is_closed()
+
+    def exec_prices_colnames(self) -> List[str]:
+        return [
+            f"exec_price_{self.symbol_a()}",
+            f"exec_price_{self.symbol_b()}",
+        ]
+
+    def to_stop_close_conditions(self, predicted_row: pd.Series) -> bool:
+        config = self.config_
+        if (
+            not config.key_exists("stop_close_conditions")
+            or config.get_value("stop_close_conditions") is None
+        ):
+            return False
+        if "profit" in config.get_value("stop_close_conditions"):
+            current_return = self._current_return(predicted_row)
+            #
+            # print(f"time={predicted_row['tstamp']} current_return={current_return}")
+            #
+            if current_return >= config.get_value("stop_close_conditions")["profit"]:
+                print(f"STOP PROFIT: {current_return}")
+                self.user_data_["stop_close_state"] = PairState.CLOSE_STOP_PROFIT
+                return True
+        if "loss" in config.get_value("stop_close_conditions"):
+            if current_return <= config.get_value("stop_close_conditions")["loss"]:
+                print(f"STOP LOSS: {current_return}")
+                self.user_data_["stop_close_state"] = PairState.CLOSE_STOP_LOSS
+                return True
+        return False
+
+    def _current_return(self, predicted_row: pd.Series) -> float:
+        if "open_trades" in self.user_data_:
+            open_trades = self.user_data_["open_trades"]
+            if len(open_trades) == 0:
+                return 0.0
+
+            def _single_instrument_return(symbol: str) -> float:
+                instrument_open_trades = open_trades[open_trades["symbol"] == symbol]
+                instrument_open_price = instrument_open_trades["price"].iloc[0]
+
+                sign = -1 if instrument_open_trades["side"].iloc[0] == "SELL" else 1
+                instrument_price = predicted_row[f"{self.stat_model_price_}_{symbol}"]
+                instrument_return = (
+                    sign
+                    * (instrument_price - instrument_open_price)
+                    / instrument_open_price
+                )
+                return float(instrument_return) * 100.0
+
+            instrument_a_return = _single_instrument_return(self.symbol_a())
+            instrument_b_return = _single_instrument_return(self.symbol_b())
+            return instrument_a_return + instrument_b_return
+        return 0.0
+
+    def on_open_trades(self, trades: pd.DataFrame) -> None:
+        if "close_trades" in self.user_data_:
+            del self.user_data_["close_trades"]
+        self.user_data_["open_trades"] = trades
+
+    def on_close_trades(self, trades: pd.DataFrame) -> None:
+        del self.user_data_["open_trades"]
+        self.user_data_["close_trades"] = trades
+
+    def add_outstanding_position(
+        self,
+        symbol: str,
+        open_side: str,
+        open_px: float,
+        open_tstamp: datetime,
+        last_mkt_data_row: pd.Series,
+    ) -> None:
+        assert symbol in [
+            self.symbol_a(),
+            self.symbol_b(),
+        ], "Symbol must be one of the pair's symbols"
+        assert open_side in ["BUY", "SELL"], "Open side must be either BUY or SELL"
+        assert open_px > 0, "Open price must be greater than 0"
+        assert open_tstamp is not None, "Open timestamp must be provided"
+        assert last_mkt_data_row is not None, "Last market data row must be provided"
+
+        exec_prices_col_a, exec_prices_col_b = self.exec_prices_colnames()
+        if symbol == self.symbol_a():
+            last_px = last_mkt_data_row[exec_prices_col_a]
+        else:
+            last_px = last_mkt_data_row[exec_prices_col_b]
+
+        funding_per_position = self.config_.get_value("funding_per_pair") / 2
+        shares = funding_per_position / open_px
+        if open_side == "SELL":
+            shares = -shares
+
+        if "outstanding_positions" not in self.user_data_:
+            self.user_data_["outstanding_positions"] = []
+
+        self.user_data_["outstanding_positions"].append(
+            {
+                "symbol": symbol,
+                "open_side": open_side,
+                "open_px": open_px,
+                "shares": shares,
+                "open_tstamp": open_tstamp,
+                "last_px": last_px,
+                "last_tstamp": last_mkt_data_row["tstamp"],
+                "last_value": last_px * shares,
+            }
+        )
+
+class LiveTradingPair(TradingPair):
+
+    def __init__(self, config: Config, instruments: List[ExchangeInstrument]):
+        super().__init__(config, instruments)
+
+    def to_stop_close_conditions(self, predicted_row: pd.Series) -> bool:
+        # TODO LiveTradingPair.to_stop_close_conditions()
+        return False
+        
+

lib/tools/config.py

@@ -0,0 +1,17 @@
+import hjson
+from typing import Dict
+from datetime import datetime
+# ---
+from cvttpy_tools.config import Config
+
+
+def load_config(config_path: str) -> Config:
+    return Config(json_src=f"file://{config_path}")
+
+
+def expand_filename(filename: str) -> str:
+    # expand %T
+    res = filename.replace("%T", datetime.now().strftime("%Y%m%d_%H%M%S"))
+    # expand %D
+    return res.replace("%D", datetime.now().strftime("%Y%m%d"))
+

lib/tools/data_loader.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import sqlite3
+from typing import Any, Dict, List, Tuple, cast
+import pandas as pd
+
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+
+def load_sqlite_to_dataframe(db_path:str, query:str) -> pd.DataFrame:
+    df: pd.DataFrame = pd.DataFrame()
+    import os
+    if not os.path.exists(db_path):
+        print(f"WARNING: database file {db_path} does not exist")
+        return df
+
+    try:
+        conn = sqlite3.connect(db_path)
+
+        df = pd.read_sql_query(query, conn)
+        return df
+    except sqlite3.Error as excpt:
+        print(f"SQLite error: {excpt}")
+        raise
+    except Exception as excpt:
+        print(f"Error: {excpt}")
+        raise Exception() from excpt
+    finally:
+        if "conn" in locals():
+            conn.close()
+
+
+def convert_time_to_UTC(value: str, timezone: str, extra_minutes: int = 0) -> str:
+
+    from zoneinfo import ZoneInfo
+    from datetime import datetime, timedelta
+
+    # Parse it to naive datetime object
+    local_dt = datetime.strptime(value, "%Y-%m-%d %H:%M:%S")
+    local_dt = local_dt + timedelta(minutes=extra_minutes)
+
+    zinfo = ZoneInfo(timezone)
+    result: datetime = local_dt.replace(tzinfo=zinfo).astimezone(ZoneInfo("UTC"))
+
+    return result.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def load_market_data(
+    datafile: str,
+    instruments: List[ExchangeInstrument],
+    db_table_name: str,
+    trading_hours: Dict = {},
+    extra_minutes: int = 0,
+) -> pd.DataFrame:
+
+
+    inst_ids = ['"' + exch_inst.instrument_id() + '"' for exch_inst in instruments]
+    instrument_ids = list(set(inst_ids))
+    exchange_ids = list(
+        set(['"' + instrument.exchange_id() + '"' for instrument in instruments])
+    )
+
+    query = "select"
+    query += " tstamp"
+    query += ", tstamp_ns as time_ns"
+
+    query += f", substr(instrument_id, instr(instrument_id, '-') + 1) as symbol"
+    query += ", open"
+    query += ", high"
+    query += ", low"
+    query += ", close"
+    query += ", volume"
+    query += ", num_trades"
+    query += ", vwap"
+
+    query += f" from {db_table_name}"
+    query += f" where exchange_id in ({','.join(exchange_ids)})"
+    query += f" and instrument_id in ({','.join(instrument_ids)})"
+
+    df = load_sqlite_to_dataframe(db_path=datafile, query=query)
+
+    # Trading Hours
+    if len(df) > 0 and len(trading_hours) > 0:
+        date_str = df["tstamp"][0][0:10]
+
+        start_time = convert_time_to_UTC(
+            f"{date_str} {trading_hours['begin_session']}", trading_hours["timezone"]
+        )
+        end_time = convert_time_to_UTC(
+            f"{date_str} {trading_hours['end_session']}", trading_hours["timezone"], extra_minutes=extra_minutes # to get execution price
+        )
+
+        # Perform boolean selection
+        df = df[(df["tstamp"] >= start_time) & (df["tstamp"] <= end_time)]
+        df["tstamp"] = pd.to_datetime(df["tstamp"])
+
+    return cast(pd.DataFrame, df)
+
+
+# def get_available_instruments_from_db(datafile: str, config: Dict) -> List[str]:
+#     """
+#     Auto-detect available instruments from the database by querying distinct instrument_id values.
+#     Returns instruments without the configured prefix.
+#     """
+#     try:
+#         conn = sqlite3.connect(datafile)
+
+#         # Build exclusion list with full instrument_ids
+#         exclude_instruments = config.get("exclude_instruments", [])
+#         prefix = config.get("instrument_id_pfx", "")
+#         exclude_instrument_ids = [f"{prefix}{inst}" for inst in exclude_instruments]
+
+#         # Query to get distinct instrument_ids
+#         query = f"""
+#         SELECT DISTINCT instrument_id
+#         FROM {config['db_table_name']}
+#         WHERE exchange_id = ?
+#         """
+
+#         # Add exclusion clause if there are instruments to exclude
+#         if exclude_instrument_ids:
+#             placeholders = ",".join(["?" for _ in exclude_instrument_ids])
+#             query += f" AND instrument_id NOT IN ({placeholders})"
+#             cursor = conn.execute(
+#                 query, (config["exchange_id"],) + tuple(exclude_instrument_ids)
+#             )
+#         else:
+#             cursor = conn.execute(query, (config["exchange_id"],))
+#         instrument_ids = [row[0] for row in cursor.fetchall()]
+#         conn.close()
+
+#         # Remove the configured prefix to get instrument symbols
+#         instruments = []
+#         for instrument_id in instrument_ids:
+#             if instrument_id.startswith(prefix):
+#                 symbol = instrument_id[len(prefix) :]
+#                 instruments.append(symbol)
+#             else:
+#                 instruments.append(instrument_id)
+
+#         return sorted(instruments)
+
+#     except Exception as e:
+#         print(f"Error auto-detecting instruments from {datafile}: {str(e)}")
+#         return []
+
+
+# if __name__ == "__main__":
+#     df1 = load_sqlite_to_dataframe(sys.argv[1], table_name="md_1min_bars")
+
+#     print(df1)

lib/tools/filetools.py

@@ -0,0 +1,37 @@
+import os
+import glob
+from typing import Dict, List, Tuple
+# ---
+from cvttpy_tools.config import Config
+# ---
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+
+DayT = str
+DataFileNameT = str
+
+def resolve_datafiles(
+    config: Config, date_pattern: str, instruments: List[ExchangeInstrument]
+) -> List[Tuple[DayT, DataFileNameT]]:
+    resolved_files: List[Tuple[DayT, DataFileNameT]] = []
+    for exch_inst in instruments:
+        pattern = date_pattern
+        inst_type = exch_inst.user_data_.get("instrument_type", "?instrument_type?")
+        data_dir = config.get_value(f"market_data_loading/{inst_type}/data_directory")
+        if "*" in pattern or "?" in pattern:
+            # Handle wildcards
+            if not os.path.isabs(pattern):
+                pattern = os.path.join(data_dir, f"{pattern}.mktdata.ohlcv.db")
+            matched_files = glob.glob(pattern)
+            for matched_file in matched_files:
+                import re
+                match = re.search(r"(\d{8})\.mktdata\.ohlcv\.db$", matched_file)
+                assert match is not None
+                day = match.group(1)
+                resolved_files.append((day, matched_file))
+        else:
+            # Handle explicit file path
+            if not os.path.isabs(pattern):
+                pattern = os.path.join(data_dir, f"{pattern}.mktdata.ohlcv.db")
+            resolved_files.append((date_pattern, pattern))
+    return sorted(list(set(resolved_files)))  # Remove duplicates and sort
+

lib/tools/viz/viz_prices.py

@@ -0,0 +1,79 @@
+from pairs_trading.lib.pt_strategy.research_strategy import PtResearchStrategy
+
+
+def visualize_prices(strategy: PtResearchStrategy, trading_date: str) -> None: 
+    # Plot raw price data
+    import matplotlib.pyplot as plt
+    # Set plotting style
+    import seaborn as sns
+
+    pair = strategy.trading_pair_
+    SYMBOL_A = pair.symbol_a()
+    SYMBOL_B = pair.symbol_b()
+    TRD_DATE = f"{trading_date[0:4]}-{trading_date[4:6]}-{trading_date[6:8]}"
+
+    plt.style.use('seaborn-v0_8')
+    sns.set_palette("husl")
+    plt.rcParams['figure.figsize'] = (15, 10)
+
+    # Get column names for the trading pair
+    colname_a, colname_b = pair.colnames()
+    price_data = strategy.pt_mkt_data_.market_data_df_.copy()
+
+    # Create separate subplots for better visibility
+    fig_price, price_axes = plt.subplots(2, 1, figsize=(18, 10))
+
+    # Plot SYMBOL_A
+    price_axes[0].plot(price_data['tstamp'], price_data[colname_a], alpha=0.7, 
+                        label=f'{SYMBOL_A}', linewidth=1, color='blue')
+    price_axes[0].set_title(f'{SYMBOL_A} Price Data ({TRD_DATE})')
+    price_axes[0].set_ylabel(f'{SYMBOL_A} Price')
+    price_axes[0].legend()
+    price_axes[0].grid(True)
+
+    # Plot SYMBOL_B
+    price_axes[1].plot(price_data['tstamp'], price_data[colname_b], alpha=0.7, 
+                        label=f'{SYMBOL_B}', linewidth=1, color='red')
+    price_axes[1].set_title(f'{SYMBOL_B} Price Data ({TRD_DATE})')
+    price_axes[1].set_ylabel(f'{SYMBOL_B} Price')
+    price_axes[1].set_xlabel('Time')
+    price_axes[1].legend()
+    price_axes[1].grid(True)
+
+    plt.tight_layout()
+    plt.show()
+        
+
+    # Plot individual prices
+    fig, axes = plt.subplots(2, 1, figsize=(18, 12))
+
+    # Normalized prices for comparison
+    norm_a = price_data[colname_a] / price_data[colname_a].iloc[0]
+    norm_b = price_data[colname_b] / price_data[colname_b].iloc[0]
+
+    axes[0].plot(price_data['tstamp'], norm_a, label=f'{SYMBOL_A} (normalized)', alpha=0.8, linewidth=1)
+    axes[0].plot(price_data['tstamp'], norm_b, label=f'{SYMBOL_B} (normalized)', alpha=0.8, linewidth=1)
+    axes[0].set_title(f'Normalized Price Comparison (Base = 1.0)  ({TRD_DATE})')
+    axes[0].set_ylabel('Normalized Price')
+    axes[0].legend()
+    axes[0].grid(True)
+
+    # Price ratio
+    price_ratio = price_data[colname_a] / price_data[colname_b]
+    axes[1].plot(price_data['tstamp'], price_ratio, label=f'{SYMBOL_A}/{SYMBOL_B} Ratio', color='green', alpha=0.8, linewidth=1)
+    axes[1].set_title(f'Price Ratio Px({SYMBOL_A})/Px({SYMBOL_B}) ({TRD_DATE})')
+    axes[1].set_ylabel('Ratio')
+    axes[1].set_xlabel('Time')
+    axes[1].legend()
+    axes[1].grid(True)
+
+    plt.tight_layout()
+    plt.show()
+
+    # Print basic statistics
+    print(f"\nPrice Statistics:")
+    print(f"  {SYMBOL_A}: Mean=${price_data[colname_a].mean():.2f}, Std=${price_data[colname_a].std():.2f}")
+    print(f"  {SYMBOL_B}: Mean=${price_data[colname_b].mean():.2f}, Std=${price_data[colname_b].std():.2f}")
+    print(f"  Price Ratio: Mean={price_ratio.mean():.2f}, Std={price_ratio.std():.2f}")
+    print(f"  Correlation: {price_data[colname_a].corr(price_data[colname_b]):.4f}")
+

lib/tools/viz/viz_trades.py

@@ -0,0 +1,502 @@
+from __future__ import annotations
+
+
+from pairs_trading.lib.pt_strategy.results import (PairResearchResult)
+from pairs_trading.lib.pt_strategy.research_strategy import PtResearchStrategy
+
+
+def visualize_trades(strategy: PtResearchStrategy, results: PairResearchResult, trading_date: str) -> None: 
+
+    import pandas as pd
+    import plotly.express as px
+    import plotly.graph_objects as go
+    import plotly.offline as pyo
+    from IPython.display import HTML
+    from plotly.subplots import make_subplots
+
+
+    pair = strategy.trading_pair_
+    trades = results.trades_[trading_date].copy()
+    origin_mkt_data_df = strategy.pt_mkt_data_.origin_mkt_data_df_
+    mkt_data_df = strategy.pt_mkt_data_.market_data_df_
+    TRD_DATE = f"{trading_date[0:4]}-{trading_date[4:6]}-{trading_date[6:8]}"
+    SYMBOL_A = pair.symbol_a()
+    SYMBOL_B = pair.symbol_b()
+
+    
+    print(f"\nCreated trading pair: {pair}")
+    print(f"Market data shape: {pair.market_data_.shape}")
+    print(f"Column names: {pair.colnames()}")
+
+    # Configure plotly for offline mode
+    pyo.init_notebook_mode(connected=True)
+
+    # Strategy-specific interactive visualization
+    assert strategy.config_ is not None
+
+    print("=== SLIDING FIT INTERACTIVE VISUALIZATION ===")
+    print("Note: Rolling Fit strategy visualization with interactive plotly charts")
+    
+
+    # Create consistent timeline - superset of timestamps from both dataframes
+    all_timestamps = sorted(set(mkt_data_df['tstamp']))
+
+
+    # Create a unified timeline dataframe for consistent plotting
+    timeline_df = pd.DataFrame({'tstamp': all_timestamps})
+
+    # Merge with predicted data to get dis-equilibrium values
+    timeline_df = timeline_df.merge(strategy.predictions_df_[['tstamp', 'disequilibrium', 'scaled_disequilibrium', 'signed_scaled_disequilibrium']], 
+                                    on='tstamp', how='left')
+
+    # Get Symbol_A and Symbol_B market data
+    colname_a, colname_b = pair.colnames()
+    symbol_a_data = mkt_data_df[['tstamp', colname_a]].copy()
+    symbol_b_data = mkt_data_df[['tstamp', colname_b]].copy()
+
+    norm_a = symbol_a_data[colname_a] / symbol_a_data[colname_a].iloc[0]
+    norm_b = symbol_b_data[colname_b] / symbol_b_data[colname_b].iloc[0]
+
+    print(f"Using consistent timeline with {len(timeline_df)} timestamps")
+    print(f"Timeline range: {timeline_df['tstamp'].min()} to {timeline_df['tstamp'].max()}")
+
+    # Create subplots with price charts at bottom
+    fig = make_subplots(
+        rows=4, cols=1,
+        row_heights=[0.3, 0.4, 0.15, 0.15],
+        subplot_titles=[
+            f'Dis-equilibrium with Trading Thresholds ({TRD_DATE})',
+            f'Normalized Price Comparison with BUY/SELL Signals - {SYMBOL_A}&{SYMBOL_B} ({TRD_DATE})',
+            f'{SYMBOL_A} Market Data with Trading Signals ({TRD_DATE})',
+            f'{SYMBOL_B} Market Data with Trading Signals ({TRD_DATE})',
+        ],
+        vertical_spacing=0.06,
+        specs=[[{"secondary_y": False}],
+                [{"secondary_y": False}],
+                [{"secondary_y": False}],
+                [{"secondary_y": False}]]
+    )
+
+    # 1. Scaled dis-equilibrium with thresholds - using consistent timeline
+    fig.add_trace(
+        go.Scatter(
+            x=timeline_df['tstamp'],
+            y=timeline_df['scaled_disequilibrium'],
+            name='Absolute Scaled Dis-equilibrium',
+            line=dict(color='green', width=2),
+            opacity=0.8
+        ),
+        row=1, col=1
+    )
+
+    fig.add_trace(
+        go.Scatter(
+            x=timeline_df['tstamp'],
+            y=timeline_df['signed_scaled_disequilibrium'],
+            name='Scaled Dis-equilibrium',
+            line=dict(color='darkmagenta', width=2),
+            opacity=0.8
+        ),
+        row=1, col=1
+    )
+
+    # Add threshold lines to first subplot
+    fig.add_shape(
+        type="line",
+        x0=timeline_df['tstamp'].min(),
+        x1=timeline_df['tstamp'].max(),
+        y0=strategy.config_.get_value('model/disequilibrium/open_trshld'),
+        y1=strategy.config_.get_value('model/disequilibrium/open_trshld'),
+        line=dict(color="purple", width=2, dash="dot"),
+        opacity=0.7,
+        row=1, col=1
+    )
+
+    fig.add_shape(
+        type="line",
+        x0=timeline_df['tstamp'].min(),
+        x1=timeline_df['tstamp'].max(),
+        y0=-strategy.config_.get_value('model/disequilibrium/open_trshld'),
+        y1=-strategy.config_.get_value('model/disequilibrium/open_trshld'),
+        line=dict(color="purple", width=2, dash="dot"),
+        opacity=0.7,
+        row=1, col=1
+    )
+
+    fig.add_shape(
+        type="line",
+        x0=timeline_df['tstamp'].min(),
+        x1=timeline_df['tstamp'].max(),
+        y0=strategy.config_.get_value('model/disequilibrium/close_trshld'),
+        y1=strategy.config_.get_value('model/disequilibrium/close_trshld'),
+        line=dict(color="brown", width=2, dash="dot"),
+        opacity=0.7,
+        row=1, col=1
+    )
+
+    fig.add_shape(
+        type="line",
+        x0=timeline_df['tstamp'].min(),
+        x1=timeline_df['tstamp'].max(),
+        y0=-strategy.config_.get_value('model/disequilibrium/close_trshld'),
+        y1=-strategy.config_.get_value('model/disequilibrium/close_trshld'),
+        line=dict(color="brown", width=2, dash="dot"),
+        opacity=0.7,
+        row=1, col=1
+    )
+
+    fig.add_shape(
+        type="line",
+        x0=timeline_df['tstamp'].min(),
+        x1=timeline_df['tstamp'].max(),
+        y0=0,
+        y1=0,
+        line=dict(color="black", width=1, dash="solid"),
+        opacity=0.5,
+        row=1, col=1
+    )
+
+    # Add normalized price lines
+    fig.add_trace(
+        go.Scatter(
+            x=mkt_data_df['tstamp'],
+            y=norm_a,
+            name=f'{SYMBOL_A} (Normalized)',
+            line=dict(color='blue', width=2),
+            opacity=0.8
+        ),
+        row=2, col=1
+    )
+
+    fig.add_trace(
+        go.Scatter(
+            x=mkt_data_df['tstamp'],
+            y=norm_b,
+            name=f'{SYMBOL_B} (Normalized)',
+            line=dict(color='orange', width=2),
+            opacity=0.8,
+        ),
+        row=2, col=1
+    )
+
+    # Add BUY and SELL signals if available
+    if trades is not None and len(trades) > 0:
+        # Define signal groups to avoid legend repetition
+        signal_groups = {}
+        
+        # Process all trades and group by signal type (ignore OPEN/CLOSE status)
+        for _, trade in trades.iterrows():
+            symbol = trade['symbol']
+            side = trade['side']
+            # status = trade['status']
+            action = trade['action']
+            
+            # Create signal group key (without status to combine OPEN/CLOSE)
+            signal_key = f"{symbol} {side} {action}"
+            
+            # Find normalized price for this trade
+            trade_time = trade['time']
+            if symbol == SYMBOL_A:
+                closest_idx = mkt_data_df['tstamp'].searchsorted(trade_time)
+                if closest_idx < len(norm_a):
+                    norm_price = norm_a.iloc[closest_idx]
+                else:
+                    norm_price = norm_a.iloc[-1]
+            else:  # SYMBOL_B
+                closest_idx = mkt_data_df['tstamp'].searchsorted(trade_time)
+                if closest_idx < len(norm_b):
+                    norm_price = norm_b.iloc[closest_idx]
+                else:
+                    norm_price = norm_b.iloc[-1]
+            
+            # Initialize group if not exists
+            if signal_key not in signal_groups:
+                signal_groups[signal_key] = {
+                    'times': [],
+                    'prices': [],
+                    'actual_prices': [],
+                    'symbol': symbol,
+                    'side': side,
+                    # 'status': status,
+                    'action': trade['action']
+                }
+            
+            # Add to group
+            signal_groups[signal_key]['times'].append(trade_time)
+            signal_groups[signal_key]['prices'].append(norm_price)
+            signal_groups[signal_key]['actual_prices'].append(trade['price'])
+        
+        # Add each signal group as a single trace
+        for signal_key, group_data in signal_groups.items():
+            symbol = group_data['symbol']
+            side = group_data['side']
+            # status = group_data['status']
+            
+            # Determine marker properties (same for all OPEN/CLOSE of same side)
+            is_close: bool = (group_data['action'] == "CLOSE")
+            
+            if 'BUY' in side:
+                marker_color = 'green'
+                marker_symbol = 'triangle-up'
+                marker_size = 14
+            else:  # SELL
+                marker_color = 'red'
+                marker_symbol = 'triangle-down'
+                marker_size = 14
+            
+            # Create hover text for each point in the group
+            hover_texts = []
+            for i, (time, norm_price, actual_price) in enumerate(zip(group_data['times'], 
+                                                                    group_data['prices'], 
+                                                                    group_data['actual_prices'])):
+                # Find the corresponding trade to get the status for hover text
+                trade_info = trades[(trades['time'] == time) & 
+                                    (trades['symbol'] == symbol) & 
+                                    (trades['side'] == side)]
+                if len(trade_info) > 0:
+                    action = trade_info.iloc[0]['action']
+                    hover_texts.append(f'<b>{signal_key} {action}</b><br>' +
+                                    f'Time: {time}<br>' +
+                                    f'Normalized Price: {norm_price:.4f}<br>' +
+                                    f'Actual Price: ${actual_price:.2f}')
+                else:
+                    hover_texts.append(f'<b>{signal_key}</b><br>' +
+                                    f'Time: {time}<br>' +
+                                    f'Normalized Price: {norm_price:.4f}<br>' +
+                                    f'Actual Price: ${actual_price:.2f}')
+            
+            fig.add_trace(
+                go.Scatter(
+                    x=group_data['times'],
+                    y=group_data['prices'],
+                    mode='markers',
+                    name=signal_key,
+                    marker=dict(
+                        color=marker_color,
+                        size=marker_size,
+                        symbol=marker_symbol,
+                        line=dict(width=2, color='black') if is_close else None
+                    ),
+                    showlegend=True,
+                    hovertemplate='%{text}<extra></extra>',
+                    text=hover_texts
+                ),
+                row=2, col=1
+            )
+
+    # -----------------------------                
+        
+        fig.add_trace(
+            go.Scatter(
+                x=symbol_a_data['tstamp'],
+                y=symbol_a_data[colname_a],
+                name=f'{SYMBOL_A} Price',
+                line=dict(color='blue', width=2),
+                opacity=0.8
+            ),
+            row=3, col=1
+        )
+
+        # Filter trades for Symbol_A
+        symbol_a_trades = trades[trades['symbol'] == SYMBOL_A]
+        print(f"\nSymbol_A trades:\n{symbol_a_trades}")
+        
+        if len(symbol_a_trades) > 0:
+            # Separate trades by action and status for different colors
+            buy_open_trades = symbol_a_trades[(symbol_a_trades['side'].str.contains('BUY', na=False)) & 
+                                                (symbol_a_trades['action'].str.contains('OPEN', na=False))]
+            buy_close_trades = symbol_a_trades[(symbol_a_trades['side'].str.contains('BUY', na=False)) & 
+                                                (symbol_a_trades['action'].str.contains('CLOSE', na=False))]
+            
+            sell_open_trades = symbol_a_trades[(symbol_a_trades['side'].str.contains('SELL', na=False)) & 
+                                                (symbol_a_trades['action'].str.contains('OPEN', na=False))]
+            sell_close_trades = symbol_a_trades[(symbol_a_trades['side'].str.contains('SELL', na=False)) & 
+                                                (symbol_a_trades['action'].str.contains('CLOSE', na=False))]
+            
+            # Add BUY OPEN signals
+            if len(buy_open_trades) > 0:
+                fig.add_trace(
+                    go.Scatter(
+                        x=buy_open_trades['time'],
+                        y=buy_open_trades['price'],
+                        mode='markers',
+                        name=f'{SYMBOL_A} BUY OPEN',
+                        marker=dict(color='green', size=12, symbol='triangle-up'),
+                        showlegend=True
+                    ),
+                    row=3, col=1
+                )
+            
+            # Add BUY CLOSE signals
+            if len(buy_close_trades) > 0:
+                fig.add_trace(
+                    go.Scatter(
+                        x=buy_close_trades['time'],
+                        y=buy_close_trades['price'],
+                        mode='markers',
+                        name=f'{SYMBOL_A} BUY CLOSE',
+                        marker=dict(color='green', size=12, symbol='triangle-up'),
+                        line=dict(width=2, color='black'),
+                        showlegend=True
+                    ),
+                    row=3, col=1
+                )
+            
+            # Add SELL OPEN signals
+            if len(sell_open_trades) > 0:
+                fig.add_trace(
+                    go.Scatter(
+                        x=sell_open_trades['time'],
+                        y=sell_open_trades['price'],
+                        mode='markers',
+                        name=f'{SYMBOL_A} SELL OPEN',
+                        marker=dict(color='red', size=12, symbol='triangle-down'),
+                        showlegend=True
+                    ),
+                    row=3, col=1
+                )
+            
+            # Add SELL CLOSE signals
+            if len(sell_close_trades) > 0:
+                fig.add_trace(
+                    go.Scatter(
+                        x=sell_close_trades['time'],
+                        y=sell_close_trades['price'],
+                        mode='markers',
+                        name=f'{SYMBOL_A} SELL CLOSE',
+                        marker=dict(color='red', size=12, symbol='triangle-down'),
+                        line=dict(width=2, color='black'),
+                        showlegend=True
+                    ),
+                    row=3, col=1
+                )
+                    
+            # 4. Symbol_B Market Data with Trading Signals
+        fig.add_trace(
+            go.Scatter(
+                x=symbol_b_data['tstamp'],
+                y=symbol_b_data[colname_b],
+                name=f'{SYMBOL_B} Price',
+                line=dict(color='orange', width=2),
+                opacity=0.8
+            ),
+            row=4, col=1
+        )
+        
+        # Add trading signals for Symbol_B if available
+        symbol_b_trades = trades[trades['symbol'] == SYMBOL_B]
+        print(f"\nSymbol_B trades:\n{symbol_b_trades}")
+        
+        if len(symbol_b_trades) > 0:
+            # Separate trades by action and status for different colors
+            buy_open_trades = symbol_b_trades[(symbol_b_trades['side'].str.contains('BUY', na=False)) & 
+                                                (symbol_b_trades['action'].str.startswith('OPEN', na=False))]
+            buy_close_trades = symbol_b_trades[(symbol_b_trades['side'].str.contains('BUY', na=False)) & 
+                                                (symbol_b_trades['action'].str.startswith('CLOSE', na=False))]
+            
+            sell_open_trades = symbol_b_trades[(symbol_b_trades['side'].str.contains('SELL', na=False)) & 
+                                                (symbol_b_trades['action'].str.contains('OPEN', na=False))]
+            sell_close_trades = symbol_b_trades[(symbol_b_trades['side'].str.contains('SELL', na=False)) & 
+                                                (symbol_b_trades['action'].str.contains('CLOSE', na=False))]
+            
+            # Add BUY OPEN signals
+            if len(buy_open_trades) > 0:
+                fig.add_trace(
+                    go.Scatter(
+                        x=buy_open_trades['time'],
+                        y=buy_open_trades['price'],
+                        mode='markers',
+                        name=f'{SYMBOL_B} BUY OPEN',
+                        marker=dict(color='darkgreen', size=12, symbol='triangle-up'),
+                        showlegend=True
+                    ),
+                    row=4, col=1
+                )
+            
+            # Add BUY CLOSE signals
+            if len(buy_close_trades) > 0:
+                fig.add_trace(
+                    go.Scatter(
+                        x=buy_close_trades['time'],
+                        y=buy_close_trades['price'],
+                        mode='markers',
+                        name=f'{SYMBOL_B} BUY CLOSE',
+                        marker=dict(color='green', size=12, symbol='triangle-up'),
+                        line=dict(width=2, color='black'),
+                        showlegend=True
+                    ),
+                    row=4, col=1
+                )
+            
+            # Add SELL OPEN signals
+            if len(sell_open_trades) > 0:
+                fig.add_trace(
+                    go.Scatter(
+                        x=sell_open_trades['time'],
+                        y=sell_open_trades['price'],
+                        mode='markers',
+                        name=f'{SYMBOL_B} SELL OPEN',
+                        marker=dict(color='red', size=12, symbol='triangle-down'),
+                        showlegend=True
+                    ),
+                    row=4, col=1
+                )
+            
+            # Add SELL CLOSE signals
+            if len(sell_close_trades) > 0:
+                fig.add_trace(
+                    go.Scatter(
+                        x=sell_close_trades['time'],
+                        y=sell_close_trades['price'],
+                        mode='markers',
+                        name=f'{SYMBOL_B} SELL CLOSE',
+                        marker=dict(color='red', size=12, symbol='triangle-down'),
+                        line=dict(width=2, color='black'),
+                        showlegend=True
+                    ),
+                    row=4, col=1
+                )
+    
+        # Update layout
+        fig.update_layout(
+            height=1600,
+            title_text=f"Strategy Analysis - {SYMBOL_A} & {SYMBOL_B} ({TRD_DATE})",
+            showlegend=True,
+            template="plotly_white",
+            plot_bgcolor='lightgray',
+        )
+        
+        # Update y-axis labels
+        fig.update_yaxes(title_text="Scaled Dis-equilibrium", row=1, col=1)
+        fig.update_yaxes(title_text=f"{SYMBOL_A} Price ($)", row=2, col=1)
+        fig.update_yaxes(title_text=f"{SYMBOL_B} Price ($)", row=3, col=1)
+        fig.update_yaxes(title_text="Normalized Price (Base = 1.0)", row=4, col=1)
+        
+        # Update x-axis labels and ensure consistent time range
+        time_range = [timeline_df['tstamp'].min(), timeline_df['tstamp'].max()]
+        fig.update_xaxes(range=time_range, row=1, col=1)
+        fig.update_xaxes(range=time_range, row=2, col=1)
+        fig.update_xaxes(range=time_range, row=3, col=1)
+        fig.update_xaxes(title_text="Time", range=time_range, row=4, col=1)
+        
+        # Display using plotly offline mode
+        # pyo.iplot(fig)
+        fig.show()
+        
+    else:
+        print("No interactive visualization data available - strategy may not have run successfully")
+
+    print(f"\nChart shows:")
+    print(f"- {SYMBOL_A} and {SYMBOL_B} prices normalized to start at 1.0")
+    print(f"- BUY signals shown as green triangles pointing up")
+    print(f"- SELL signals shown as orange triangles pointing down")
+    print(f"- All BUY signals per symbol grouped together, all SELL signals per symbol grouped together")
+    print(f"- Hover over markers to see individual trade details (OPEN/CLOSE status)")
+
+    if trades is not None and len(trades) > 0:
+        print(f"- Total signals displayed: {len(trades)}")
+        print(f"- {SYMBOL_A} signals: {len(trades[trades['symbol'] == SYMBOL_A])}")
+        print(f"- {SYMBOL_B} signals: {len(trades[trades['symbol'] == SYMBOL_B])}")
+    else:
+        print("- No trading signals to display")
+

requirements.txt

@@ -4,6 +4,7 @@ async-timeout>=4.0.2
 attrs>=21.2.0
 beautifulsoup4>=4.10.0
 black>=23.3.0
+flake8>=6.0.0
 certifi>=2020.6.20
 chardet>=4.0.0
 charset-normalizer>=3.1.0
@@ -23,11 +24,14 @@ hjson>=3.0.2
 html5lib>=1.1
 httplib2>=0.20.2
 idna>=3.3
+ipython>=8.18.1
+ipywidgets>=8.1.1
 ifaddr>=0.1.7
 IMDbPY>=2021.4.18
 ipykernel>=6.29.5
 jeepney>=0.7.1
 jsonschema>=3.2.0
+jupyter>=1.0.0
 keyring>=23.5.0
 launchpadlib>=1.10.16
 lazr.restfulclient>=0.14.4
@@ -41,14 +45,18 @@ more-itertools>=8.10.0
 multidict>=6.0.4
 mypy>=0.942
 mypy-extensions>=0.4.3
+nbformat>=5.10.2
 netaddr>=0.8.0
 ######### netifaces>=0.11.0
+numpy>=1.26.4,<2.3.0
 oauthlib>=3.2.0
 packaging>=23.1
+pandas>=2.2.3
 pathspec>=0.11.1
 pexpect>=4.8.0
 Pillow>=9.0.1
 platformdirs>=3.2.0
+plotly>=5.19.0
 protobuf>=3.12.4
 psutil>=5.9.0
 ptyprocess>=0.7.0
@@ -66,9 +74,11 @@ PyYAML>=6.0
 reportlab>=3.6.8
 requests>=2.25.1
 requests-file>=1.5.1
+scipy<1.13.0
 seaborn>=0.13.2
 SecretStorage>=3.3.1
 setproctitle>=1.2.2
+simpleeval>=1.0.3
 six>=1.16.0
 soupsieve>=2.3.1
 ssh-import-id>=5.11
@@ -160,6 +170,7 @@ types-PyYAML>=5.4
 types-redis>=3.5
 types-requests>=2.25
 types-retry>=0.9
+types-seaborn>0.13.2
 types-selenium>=3.141
 types-Send2Trash>=1.8
 types-setuptools>=57.4

research/backtest.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Tuple
+
+# ---
+from cvttpy_tools.app import App
+from cvttpy_tools.base import NamedObject
+from cvttpy_tools.config import CvttAppConfig
+
+# ---
+from cvttpy_trading.trading.instrument import ExchangeInstrument
+from cvttpy_trading.settings.instruments import Instruments
+
+# ---
+from pairs_trading.lib.pt_strategy.results import (
+    PairResearchResult,
+    create_result_database,
+    store_config_in_database,
+)
+from pairs_trading.lib.pt_strategy.research_strategy import PtResearchStrategy
+from pairs_trading.lib.tools.filetools import resolve_datafiles
+
+InstrumentTypeT = str
+
+
+class Runner(NamedObject):
+    def __init__(self):
+        App()
+        CvttAppConfig()
+
+        # App.instance().add_cmdline_arg(
+        #     "--config", type=str, required=True, help="Path to the configuration file."
+        # )
+        App.instance().add_cmdline_arg(
+            "--date_pattern",
+            type=str,
+            required=True,
+            help="Date YYYYMMDD, allows * and ? wildcards",
+        )
+        App.instance().add_cmdline_arg(
+            "--instruments",
+            type=str,
+            required=True,
+            help="Comma-separated list of instrument symbols (e.g., COIN:EQUITY,GBTC:CRYPTO)",
+        )
+        App.instance().add_cmdline_arg(
+            "--result_db",
+            type=str,
+            required=True,
+            help="Path to SQLite database for storing results. Use 'NONE' to disable database output.",
+        )
+
+        App.instance().add_call(stage=App.Stage.Config, func=self._on_config())
+        App.instance().add_call(stage=App.Stage.Run, func=self.run())
+
+    async def _on_config(self) -> None:
+        # Resolve data files (CLI takes priority over config)
+        instruments: List[ExchangeInstrument] = self._get_instruments()
+        datafiles = resolve_datafiles(
+            config=CvttAppConfig.instance(),
+            date_pattern=App.instance().get_argument("date_pattern"),
+            instruments=instruments,
+        )
+
+        days = list(set([day for day, _ in datafiles]))
+        print(f"Found {len(datafiles)} data files to process:")
+        for df in datafiles:
+            print(f"  - {df}")
+
+        # Create result database if needed
+        if App.instance().get_argument("result_db").upper() != "NONE":
+            create_result_database(App.instance().get_argument("result_db"))
+
+        # Initialize a dictionary to store all trade results
+        all_results: Dict[str, Dict[str, Any]] = {}
+        is_config_stored = False
+        # Process each data file
+
+        results = PairResearchResult(config=CvttAppConfig.instance())
+        for day in sorted(days):
+            md_datafiles = [datafile for md_day, datafile in datafiles if md_day == day]
+            if not all([os.path.exists(datafile) for datafile in md_datafiles]):
+                print(f"WARNING: insufficient data files: {md_datafiles}")
+                exit(1)
+            print(f"\n====== Processing {day} ======")
+
+            if not is_config_stored:
+                store_config_in_database(
+                    db_path=App.instance().get_argument("result_db"),
+                    config_file_path=App.instance().get_argument("config"),
+                    config=CvttAppConfig.instance(),
+                    datafiles=datafiles,
+                    instruments=instruments,
+                )
+                is_config_stored = True
+
+            CvttAppConfig.instance().set_value("datafiles", md_datafiles)
+            pt_strategy = PtResearchStrategy(
+                config=CvttAppConfig.instance(),
+                instruments=instruments,
+            )
+            pt_strategy.run()
+            results.add_day_results(
+                day=day,
+                trades=pt_strategy.day_trades(),
+                outstanding_positions=pt_strategy.outstanding_positions(),
+            )
+
+        results.analyze_pair_performance()
+
+    def _get_instruments(self) -> List[ExchangeInstrument]:
+        res: List[ExchangeInstrument] = []
+
+        for inst in App.instance().get_argument("instruments").split(","):
+            instrument_type = inst.split(":")[0]
+            exchange_id = inst.split(":")[1]
+            instrument_id = inst.split(":")[2]
+            exch_inst: ExchangeInstrument = Instruments.instance().get_exch_inst(
+                exch_id=exchange_id, inst_id=instrument_id, src=f"{self.fname()}"
+            )
+            exch_inst.user_data_["instrument_type"] = instrument_type
+            res.append(exch_inst)
+
+        return res
+
+    async def run(self) -> None:
+
+        if App.instance().get_argument("result_db").upper() != "NONE":
+            print(
+                f'\nResults stored in database: {App.instance().get_argument("result_db")}'
+            )
+        else:
+            print("No results to display.")
+
+
+if __name__ == "__main__":
+    Runner()
+    App.instance().run()

research/notebooks/pair_select_hist.ipynb

@@ -0,0 +1,311 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Pair Selection History\n",
+        "\n",
+        "Interactive notebook for exploring pair selection history from a SQLite database.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "**Usage**\n",
+        "- Enter the SQLite `db_path` (file path).\n",
+        "- Click `Load pairs` to populate the dropdown.\n",
+        "- Select a `pair_name`, then click `Plot`.\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "668ebf19",
+      "metadata": {},
+      "source": [
+        "# Settings"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 1,
+      "id": "c78db847",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import sqlite3\n",
+        "from pathlib import Path\n",
+        "\n",
+        "import pandas as pd\n",
+        "import plotly.express as px\n",
+        "import ipywidgets as widgets\n",
+        "from IPython.display import display\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "e7ac6adc",
+      "metadata": {},
+      "source": [
+        "# Data Loading"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "766bcf9f",
+      "metadata": {},
+      "outputs": [
+        {
+          "data": {
+            "application/vnd.jupyter.widget-view+json": {
+              "model_id": "e0b30b1abd1b440b832fdaaa6cce8f76",
+              "version_major": 2,
+              "version_minor": 0
+            },
+            "text/plain": [
+              "VBox(children=(Text(value='', description='pair_db', layout=Layout(width='80%'), placeholder='/path/to/pairs.d…"
+            ]
+          },
+          "metadata": {},
+          "output_type": "display_data"
+        },
+        {
+          "data": {
+            "application/vnd.jupyter.widget-view+json": {
+              "model_id": "15679f9015854d5fa7119210094fbbc8",
+              "version_major": 2,
+              "version_minor": 0
+            },
+            "text/plain": [
+              "Output()"
+            ]
+          },
+          "metadata": {},
+          "output_type": "display_data"
+        }
+      ],
+      "source": [
+        "db_path = widgets.Text(\n",
+        "    value='',\n",
+        "    placeholder='/path/to/pairs.db',\n",
+        "    description='pair_db',\n",
+        "    layout=widgets.Layout(width='80%')\n",
+        ")\n",
+        "\n",
+        "md_db_path = widgets.Text(\n",
+        "    value='',\n",
+        "    placeholder='/path/to/market_data.db',\n",
+        "    description='md_db',\n",
+        "    layout=widgets.Layout(width='80%')\n",
+        ")\n",
+        "\n",
+        "load_button = widgets.Button(description='Load pairs', button_style='info')\n",
+        "plot_button = widgets.Button(description='Plot', button_style='primary')\n",
+        "\n",
+        "pair_name = widgets.Dropdown(\n",
+        "    options=[],\n",
+        "    value=None,\n",
+        "    description='pair_name',\n",
+        "    layout=widgets.Layout(width='80%')\n",
+        ")\n",
+        "\n",
+        "status = widgets.HTML(value='')\n",
+        "output = widgets.Output()\n",
+        "\n",
+        "controls = widgets.VBox([\n",
+        "    db_path,\n",
+        "    md_db_path,\n",
+        "    widgets.HBox([load_button, plot_button]),\n",
+        "    pair_name,\n",
+        "    status,\n",
+        "])\n",
+        "\n",
+        "display(controls, output)\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "a4d47855",
+      "metadata": {},
+      "source": [
+        "# Processing"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "2c710f51",
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "PLOT_WIDTH = 1100\n",
+        "PLOT_HEIGHT = 320\n",
+        "\n",
+        "def _connect(path: str):\n",
+        "    if not path:\n",
+        "        raise ValueError('Please provide db_path.')\n",
+        "    p = Path(path).expanduser().resolve()\n",
+        "    if not p.exists():\n",
+        "        raise FileNotFoundError(f'Database not found: {p}')\n",
+        "    return sqlite3.connect(p)\n",
+        "\n",
+        "\n",
+        "def _parse_tstamp(series: pd.Series) -> pd.Series:\n",
+        "    return pd.to_datetime(series, utc=True, errors='coerce').dt.tz_convert(None)\n",
+        "\n",
+        "\n",
+        "def _style_fig(fig, tmin, tmax):\n",
+        "    fig.update_layout(\n",
+        "        legend=dict(orientation='h', yanchor='bottom', y=1.02, xanchor='left', x=0),\n",
+        "        margin=dict(l=50, r=20, t=60, b=40),\n",
+        "        height=PLOT_HEIGHT,\n",
+        "        width=PLOT_WIDTH,\n",
+        "    )\n",
+        "    fig.update_xaxes(range=[tmin, tmax])\n",
+        "\n",
+        "\n",
+        "def _load_pairs(_=None):\n",
+        "    status.value = ''\n",
+        "    with output:\n",
+        "        output.clear_output()\n",
+        "    try:\n",
+        "        with _connect(db_path.value) as conn:\n",
+        "            rows = conn.execute(\n",
+        "                \"SELECT pair_name \"\n",
+        "                \"FROM pair_selection_history \"\n",
+        "                \"GROUP BY pair_name \"\n",
+        "                \"ORDER BY SUM(composite_rank), pair_name\"\n",
+        "            ).fetchall()\n",
+        "        options = [r[0] for r in rows]\n",
+        "        pair_name.options = options\n",
+        "        pair_name.value = options[0] if options else None\n",
+        "        status.value = f'Loaded {len(options)} pairs.'\n",
+        "    except Exception as exc:\n",
+        "        status.value = f\"<span style='color:#b00'>Error: {exc}</span>\"\n",
+        "\n",
+        "\n",
+        "def _plot(_=None):\n",
+        "    status.value = ''\n",
+        "    with output:\n",
+        "        output.clear_output()\n",
+        "    try:\n",
+        "        if not pair_name.value:\n",
+        "            raise ValueError('Please select a pair_name.')\n",
+        "        if not md_db_path.value:\n",
+        "            raise ValueError('Please provide md_db path.')\n",
+        "        query = (\n",
+        "            'SELECT tstamp, pvalue_eg, pvalue_adf, rank_eg, rank_adf, '\n",
+        "            'exchange_a, instrument_a, exchange_b, instrument_b '\n",
+        "            'FROM pair_selection_history '\n",
+        "            'WHERE pair_name = ? '\n",
+        "            'ORDER BY tstamp'\n",
+        "        )\n",
+        "        with _connect(db_path.value) as conn:\n",
+        "            df = pd.read_sql_query(query, conn, params=(pair_name.value,))\n",
+        "        if df.empty:\n",
+        "            raise ValueError('No data for selected pair_name.')\n",
+        "        df['tstamp'] = _parse_tstamp(df['tstamp'])\n",
+        "        df = df.dropna(subset=['tstamp'])\n",
+        "        if df.empty:\n",
+        "            raise ValueError('No valid timestamps in pair selection data.')\n",
+        "        tmin = df['tstamp'].min()\n",
+        "        tmax = df['tstamp'].max()\n",
+        "\n",
+        "        first_row = df.dropna(subset=['exchange_a', 'instrument_a', 'exchange_b', 'instrument_b']).iloc[0]\n",
+        "        ex_a = first_row['exchange_a']\n",
+        "        id_a = first_row['instrument_a']\n",
+        "        ex_b = first_row['exchange_b']\n",
+        "        id_b = first_row['instrument_b']\n",
+        "\n",
+        "        fig_p = px.line(\n",
+        "            df,\n",
+        "            x='tstamp',\n",
+        "            y=['pvalue_eg', 'pvalue_adf'],\n",
+        "            title=f'P-Values Over Time: {pair_name.value}',\n",
+        "            labels={'value': 'p-value', 'variable': 'metric', 'tstamp': 'timestamp'}\n",
+        "        )\n",
+        "        fig_p.update_layout(legend_title_text='metric')\n",
+        "        _style_fig(fig_p, tmin, tmax)\n",
+        "\n",
+        "                md_query = (\n",
+        "            'SELECT tstamp, close FROM md_1min_bars '\n",
+        "            'WHERE exchange_id = ? AND instrument_id = ? '\n",
+        "            'ORDER BY tstamp'\n",
+        "        )\n",
+        "        with _connect(md_db_path.value) as md_conn:\n",
+        "            md_a = pd.read_sql_query(md_query, md_conn, params=(ex_a, id_a))\n",
+        "            md_b = pd.read_sql_query(md_query, md_conn, params=(ex_b, id_b))\n",
+        "        if md_a.empty or md_b.empty:\n",
+        "            raise ValueError('Market data not found for selected instruments.')\n",
+        "        md_a['tstamp'] = _parse_tstamp(md_a['tstamp'])\n",
+        "        md_b['tstamp'] = _parse_tstamp(md_b['tstamp'])\n",
+        "        md_a = md_a.dropna(subset=['tstamp', 'close'])\n",
+        "        md_b = md_b.dropna(subset=['tstamp', 'close'])\n",
+        "        md_a = md_a[(md_a['tstamp'] >= tmin) & (md_a['tstamp'] <= tmax)]\n",
+        "        md_b = md_b[(md_b['tstamp'] >= tmin) & (md_b['tstamp'] <= tmax)]\n",
+        "        if md_a.empty or md_b.empty:\n",
+        "            raise ValueError('Market data is outside the pair selection time range.')\n",
+        "        md_a = md_a.sort_values('tstamp')\n",
+        "        md_b = md_b.sort_values('tstamp')\n",
+        "        md_a['scaled_close'] = (md_a['close'] - md_a['close'].iloc[0]) / md_a['close'].iloc[0] * 100\n",
+        "        md_b['scaled_close'] = (md_b['close'] - md_b['close'].iloc[0]) / md_b['close'].iloc[0] * 100\n",
+        "\n",
+        "        md_plot = pd.DataFrame({\n",
+        "            'tstamp': md_a['tstamp'],\n",
+        "            f'{ex_a}:{id_a}': md_a['scaled_close'],\n",
+        "        })\n",
+        "        md_plot = md_plot.merge(\n",
+        "            pd.DataFrame({\n",
+        "                'tstamp': md_b['tstamp'],\n",
+        "                f'{ex_b}:{id_b}': md_b['scaled_close'],\n",
+        "            }),\n",
+        "            on='tstamp',\n",
+        "            how='outer'\n",
+        "        ).sort_values('tstamp')\n",
+        "\n",
+        "        fig_m = px.line(\n",
+        "            md_plot,\n",
+        "            x='tstamp',\n",
+        "            y=[f'{ex_a}:{id_a}', f'{ex_b}:{id_b}'],\n",
+        "            title='Scaled Close Price Change (%)',\n",
+        "            labels={'value': 'scaled % change', 'variable': 'instrument', 'tstamp': 'timestamp'}\n",
+        "        )\n",
+        "        fig_m.update_layout(legend_title_text='instrument')\n",
+        "        _style_fig(fig_m, tmin, tmax)\n",
+        "\n",
+        "        with output:\n",
+        "            display(fig_p)\n",
+        "            display(fig_m)\n",
+        "    except Exception as exc:\n",
+        "        status.value = f\"<span style='color:#b00'>Error: {exc}</span>\"\n",
+        "\n",
+        "\n",
+        "load_button.on_click(_load_pairs)\n",
+        "plot_button.on_click(_plot)\n"
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "python3.12-venv",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "codemirror_mode": {
+        "name": "ipython",
+        "version": 3
+      },
+      "file_extension": ".py",
+      "mimetype": "text/x-python",
+      "name": "python",
+      "nbconvert_exporter": "python",
+      "pygments_lexer": "ipython3",
+      "version": "3.12.9"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

scripts/load_crypto_1min.sh

@@ -12,8 +12,18 @@
 # -------------------------------------
 # --- Current month - all files
 # -------------------------------------
+cd $(realpath $(dirname $0))/..
+mkdir -p ./data/crypto
 pushd ./data/crypto
-rsync -ahvv cvtt@hs01.cvtt.vpn:/works/cvtt/md_archive/crypto/sim/*.gz ./
+
+Files=$1
+if [ -z "$Files" ]; then
+    Files="*.gz"
+fi
+
+Cmd="rsync -ahvv cvtt@hs01.cvtt.vpn:/works/cvtt/md_archive/crypto/sim/${Files} ./"
+echo $Cmd
+eval $Cmd
 # -------------------------------------
 
 for srcfname in $(ls *.db.gz); do
@@ -21,8 +31,12 @@ for srcfname in $(ls *.db.gz); do
     tgtfile=${dt}.mktdata.ohlcv.db
     echo "${srcfname} -> ${tgtfile}"
 
-    gunzip -c $srcfname > temp.db
-    rm -f ${tgtfile} && sqlite3 temp.db ".dump md_1min_bars" | sqlite3  ${tgtfile} && rm ${srcfname}
+    Cmd="gunzip -c $srcfname > temp.db"
+    echo $Cmd
+    eval $Cmd
+    Cmd="rm -f ${tgtfile} && sqlite3 temp.db \".dump md_1min_bars\" | sqlite3  ${tgtfile} && rm ${srcfname}"
+    echo $Cmd
+    eval $Cmd
 done
 rm temp.db
-popd
+popd

scripts/load_equity_1min.sh

@@ -12,7 +12,10 @@ if [ -z "${DatePattern}" ]; then
 fi
 FilePattern="${DatePattern}*.alpaca_sim_md.db.gz"
 
+cd $(realpath $(dirname $0))/..
+mkdir -p ./data/equity
 pushd ./data/equity
+
 Cmd="rsync -ahvv cvtt@hs01.cvtt.vpn:/works/cvtt/md_archive/equity/alpaca_md/sim/${FilePattern} ./"
 echo ${Cmd}
 eval ${Cmd}
@@ -23,8 +26,12 @@ for srcfname in $(ls *.db.gz); do
     tgtfile=${dt}.mktdata.ohlcv.db
     echo "${srcfname} -> ${tgtfile}"
 
-    gunzip -c $srcfname > temp.db
-    rm -f ${tgtfile} && sqlite3 temp.db ".dump md_1min_bars" | sqlite3  ${tgtfile} && rm ${srcfname}
+    Cmd="gunzip -c $srcfname > temp.db && rm $srcfname"
+    echo ${Cmd}
+    eval ${Cmd}
+    Cmd="rm -f ${tgtfile} && sqlite3 temp.db '.dump md_1min_bars' | sqlite3  ${tgtfile}"
+    echo ${Cmd}
+    eval ${Cmd}
 done
 rm temp.db
-popd
+popd

src/notebooks/pt_sliding.ipynb

@@ -1,833 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Sliding Fit Strategy Visualization Notebook\n",
-    "\n",
-    "This notebook is specifically designed for the SlidingFitStrategy, which uses a sliding window approach.\n",
-    "It re-trains the model every minute and shows how cointegration, model parameters, and trading signals evolve over time.\n",
-    "You can visualize the dynamic nature of the sliding window and how the relationship between instruments changes."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### \ud83c\udfaf Key Features:\n",
-    "\n",
-    "1. **Interactive Configuration**: \n",
-    "   - Easy switching between CRYPTO and EQUITY configurations\n",
-    "   - Simple parameter adjustment for thresholds and training periods\n",
-    "\n",
-    "2. **Single Pair Focus**: \n",
-    "   - Instead of running multiple pairs, focuses on one pair at a time\n",
-    "   - Allows deep analysis of the relationship between two instruments\n",
-    "\n",
-    "3. **Step-by-Step Visualization**:\n",
-    "   - **Raw price data**: Individual prices, normalized comparison, and price ratios\n",
-    "   - **Training analysis**: Cointegration testing and VECM model fitting\n",
-    "   - **Dis-equilibrium visualization**: Both raw and scaled dis-equilibrium with threshold lines\n",
-    "   - **Strategy execution**: Trading signal generation and visualization\n",
-    "   - **Prediction analysis**: Actual vs predicted prices with trading signals overlaid\n",
-    "\n",
-    "4. **Rich Analytics**:\n",
-    "   - Cointegration status and VECM model details\n",
-    "   - Statistical summaries for all stages\n",
-    "   - Threshold crossing analysis\n",
-    "   - Trading signal breakdown\n",
-    "\n",
-    "5. **Interactive Experimentation**:\n",
-    "   - Easy parameter modification\n",
-    "   - Re-run capabilities for different configurations\n",
-    "   - Support for both StaticFitStrategy and SlidingFitStrategy\n",
-    "\n",
-    "### \ud83d\ude80 How to Use:\n",
-    "\n",
-    "1. **Start Jupyter**:\n",
-    "   ```bash\n",
-    "   cd src/notebooks\n",
-    "   jupyter notebook pairs_trading_visualization.ipynb\n",
-    "   ```\n",
-    "\n",
-    "2. **Customize Your Analysis**:\n",
-    "   - Change `SYMBOL_A` and `SYMBOL_B` to your desired trading pair\n",
-    "   - Switch between `CRYPTO_CONFIG` and `EQT_CONFIG`\n",
-    "   - Choose your strategy (StaticFitStrategy or SlidingFitStrategy)\n",
-    "   - Adjust thresholds and parameters as needed\n",
-    "\n",
-    "3. **Run and Visualize**:\n",
-    "   - Execute cells step by step to see the analysis unfold\n",
-    "   - Rich matplotlib visualizations show relationships and signals\n",
-    "   - Comprehensive summary at the end\n",
-    "\n",
-    "The notebook provides exactly what you requested - a way to visualize the relationship between two instruments and their scaled dis-equilibrium, with all the stages of your pairs trading strategy clearly displayed and analyzed.\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Setup and Imports"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Trading Parameters Configuration\n",
-    "# Specify your configuration file, trading symbols and date here\n",
-    "\n",
-    "# Configuration file selection\n",
-    "CONFIG_FILE = \"equity\"  # Options: \"equity\", \"crypto\", or custom filename (without .cfg extension)\n",
-    "\n",
-    "# Trading pair symbols\n",
-    "SYMBOL_A = \"COIN\"   # Change this to your desired symbol A\n",
-    "SYMBOL_B = \"MSTR\"   # Change this to your desired symbol B\n",
-    "\n",
-    "# Date for data file selection (format: YYYYMMDD)\n",
-    "TRADING_DATE = \"20250605\"  # Change this to your desired date\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import sys\n",
-    "import os\n",
-    "sys.path.append('..')\n",
-    "\n",
-    "import pandas as pd\n",
-    "import numpy as np\n",
-    "import matplotlib.pyplot as plt\n",
-    "import seaborn as sns\n",
-    "from typing import Dict, List, Optional\n",
-    "from IPython.display import clear_output\n",
-    "\n",
-    "# Import our modules\n",
-    "from strategies import SlidingFitStrategy, PairState\n",
-    "from tools.data_loader import load_market_data\n",
-    "from tools.trading_pair import TradingPair\n",
-    "from results import BacktestResult\n",
-    "\n",
-    "# Set plotting style\n",
-    "plt.style.use('seaborn-v0_8')\n",
-    "sns.set_palette(\"husl\")\n",
-    "plt.rcParams['figure.figsize'] = (15, 10)\n",
-    "\n",
-    "print(\"Setup complete!\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Configuration"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Load Configuration from Configuration Files using HJSON\n",
-    "import hjson\n",
-    "import os\n",
-    "\n",
-    "def load_config_from_file(config_type=\"equity\"):\n",
-    "    \"\"\"Load configuration from configuration files using HJSON\"\"\"\n",
-    "    config_file = f\"../../configuration/{config_type}.cfg\"\n",
-    "    \n",
-    "    try:\n",
-    "        with open(config_file, 'r') as f:\n",
-    "            # HJSON handles comments, trailing commas, and other human-friendly features\n",
-    "            config = hjson.load(f)\n",
-    "        \n",
-    "        # Convert relative paths to absolute paths from notebook perspective\n",
-    "        if 'data_directory' in config:\n",
-    "            data_dir = config['data_directory']\n",
-    "            if data_dir.startswith('./'):\n",
-    "                # Convert relative path to absolute path from notebook's perspective\n",
-    "                config['data_directory'] = os.path.abspath(f\"../../{data_dir[2:]}\")\n",
-    "        \n",
-    "        return config\n",
-    "        \n",
-    "    except FileNotFoundError:\n",
-    "        print(f\"Configuration file not found: {config_file}\")\n",
-    "        return None\n",
-    "    except hjson.HjsonDecodeError as e:\n",
-    "        print(f\"HJSON parsing error in {config_file}: {e}\")\n",
-    "        return None\n",
-    "    except Exception as e:\n",
-    "        print(f\"Unexpected error loading config from {config_file}: {e}\")\n",
-    "        return None\n",
-    "\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "print(f\"Trading Parameters:\")\n",
-    "print(f\"  Configuration: {CONFIG_FILE}\")\n",
-    "print(f\"  Symbol A: {SYMBOL_A}\")\n",
-    "print(f\"  Symbol B: {SYMBOL_B}\")\n",
-    "print(f\"  Trading Date: {TRADING_DATE}\")\n",
-    "\n",
-    "# Load the specified configuration\n",
-    "print(f\"\\nLoading {CONFIG_FILE} configuration using HJSON...\")\n",
-    "CONFIG = load_config_from_file(CONFIG_FILE)\n",
-    "\n",
-    "if CONFIG:\n",
-    "    print(f\"\u2713 Successfully loaded {CONFIG['security_type']} configuration\")\n",
-    "    print(f\"  Data directory: {CONFIG['data_directory']}\")\n",
-    "    print(f\"  Database table: {CONFIG['db_table_name']}\")\n",
-    "    print(f\"  Exchange: {CONFIG['exchange_id']}\")\n",
-    "    print(f\"  Training window: {CONFIG['training_minutes']} minutes\")\n",
-    "    print(f\"  Open threshold: {CONFIG['dis-equilibrium_open_trshld']}\")\n",
-    "    print(f\"  Close threshold: {CONFIG['dis-equilibrium_close_trshld']}\")\n",
-    "    \n",
-    "    # Automatically construct data file name based on date and config type\n",
-    "    # if CONFIG['security_type'] == \"CRYPTO\":\n",
-    "    DATA_FILE = f\"{TRADING_DATE}.mktdata.ohlcv.db\"\n",
-    "    # elif CONFIG['security_type'] == \"EQUITY\":\n",
-    "    #     DATA_FILE = f\"{TRADING_DATE}.alpaca_sim_md.db\"\n",
-    "    # else:\n",
-    "    #     DATA_FILE = f\"{TRADING_DATE}.mktdata.db\"  # Default fallback\n",
-    "\n",
-    "    # Update CONFIG with the specific data file and instruments\n",
-    "    CONFIG[\"datafiles\"] = [DATA_FILE]\n",
-    "    CONFIG[\"instruments\"] = [SYMBOL_A, SYMBOL_B]\n",
-    "    \n",
-    "    print(f\"\\nData Configuration:\")\n",
-    "    print(f\"  Data File: {DATA_FILE}\")\n",
-    "    print(f\"  Security Type: {CONFIG['security_type']}\")\n",
-    "    \n",
-    "    # Verify data file exists\n",
-    "    import os\n",
-    "    data_file_path = f\"{CONFIG['data_directory']}/{DATA_FILE}\"\n",
-    "    if os.path.exists(data_file_path):\n",
-    "        print(f\"  \u2713 Data file found: {data_file_path}\")\n",
-    "    else:\n",
-    "        print(f\"  \u26a0 Data file not found: {data_file_path}\")\n",
-    "        print(f\"    Please check if the date and file exist in the data directory\")\n",
-    "        \n",
-    "        # List available files in the data directory\n",
-    "        try:\n",
-    "            data_dir = CONFIG['data_directory']\n",
-    "            if os.path.exists(data_dir):\n",
-    "                available_files = [f for f in os.listdir(data_dir) if f.endswith('.db')]\n",
-    "                print(f\"    Available files in {data_dir}:\")\n",
-    "                for file in sorted(available_files)[:5]:  # Show first 5 files\n",
-    "                    print(f\"      - {file}\")\n",
-    "                if len(available_files) > 5:\n",
-    "                    print(f\"      ... and {len(available_files)-5} more files\")\n",
-    "        except Exception as e:\n",
-    "            print(f\"    Could not list files in data directory: {e}\")\n",
-    "else:\n",
-    "    print(\"\u26a0 Failed to load configuration. Please check the configuration file.\")\n",
-    "    print(\"Available configuration files:\")\n",
-    "    config_dir = \"../../configuration\"\n",
-    "    if os.path.exists(config_dir):\n",
-    "        config_files = [f for f in os.listdir(config_dir) if f.endswith('.cfg')]\n",
-    "        for file in config_files:\n",
-    "            print(f\"  - {file}\")\n",
-    "    else:\n",
-    "        print(f\"  Configuration directory not found: {config_dir}\")\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Select Trading Pair and Initialize Strategy"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Initialize Strategy\n",
-    "# Trading pair and data file are now defined in the previous cell\n",
-    "\n",
-    "# Initialize SlidingFitStrategy\n",
-    "STRATEGY = SlidingFitStrategy()\n",
-    "\n",
-    "print(f\"Strategy Initialization:\")\n",
-    "print(f\"  Selected pair: {SYMBOL_A} & {SYMBOL_B}\")\n",
-    "print(f\"  Data file: {DATA_FILE}\")\n",
-    "print(f\"  Strategy: {type(STRATEGY).__name__}\")\n",
-    "print(f\"\\nStrategy characteristics:\")\n",
-    "print(f\"  - Sliding window training every minute\")\n",
-    "print(f\"  - Dynamic cointegration testing\")\n",
-    "print(f\"  - State-based position management\")\n",
-    "print(f\"  - Continuous model re-training\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Load and Prepare Market Data"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Load market data\n",
-    "datafile_path = f\"{CONFIG['data_directory']}/{DATA_FILE}\"\n",
-    "print(f\"Loading data from: {datafile_path}\")\n",
-    "\n",
-    "market_data_df = load_market_data(datafile_path, config=CONFIG)\n",
-    "\n",
-    "print(f\"Loaded {len(market_data_df)} rows of market data\")\n",
-    "print(f\"Symbols in data: {market_data_df['symbol'].unique()}\")\n",
-    "print(f\"Time range: {market_data_df['tstamp'].min()} to {market_data_df['tstamp'].max()}\")\n",
-    "\n",
-    "# Create trading pair\n",
-    "pair = TradingPair(\n",
-    "    market_data=market_data_df,\n",
-    "    symbol_a=SYMBOL_A,\n",
-    "    symbol_b=SYMBOL_B,\n",
-    "    price_column=CONFIG[\"price_column\"]\n",
-    ")\n",
-    "\n",
-    "print(f\"\\nCreated trading pair: {pair}\")\n",
-    "print(f\"Market data shape: {pair.market_data_.shape}\")\n",
-    "print(f\"Column names: {pair.colnames()}\")\n",
-    "\n",
-    "# Calculate maximum possible iterations for sliding window\n",
-    "training_minutes = CONFIG[\"training_minutes\"]\n",
-    "max_iterations = len(pair.market_data_) - training_minutes\n",
-    "print(f\"\\nSliding window analysis:\")\n",
-    "print(f\"  Training window size: {training_minutes} minutes\")\n",
-    "print(f\"  Maximum iterations: {max_iterations}\")\n",
-    "print(f\"  Total analysis time: ~{max_iterations} minutes\")\n",
-    "\n",
-    "# Display sample data\n",
-    "print(f\"\\nSample data:\")\n",
-    "display(pair.market_data_.head())"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Run SlidingFitStrategy with Real-Time Visualization"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Run the sliding strategy with detailed tracking\n",
-    "print(f\"Running SlidingFitStrategy on {pair}...\")\n",
-    "print(f\"This will process {max_iterations} minutes of data with sliding training windows.\\n\")\n",
-    "\n",
-    "# Initialize tracking variables\n",
-    "iteration_data = []\n",
-    "cointegration_history = []\n",
-    "beta_history = []\n",
-    "alpha_history = []\n",
-    "state_history = []\n",
-    "disequilibrium_history = []\n",
-    "scaled_disequilibrium_history = []\n",
-    "timestamp_history = []\n",
-    "training_mu_history = []\n",
-    "training_std_history = []\n",
-    "\n",
-    "# Initialize the strategy state\n",
-    "pair.user_data_['state'] = PairState.INITIAL\n",
-    "pair.user_data_[\"trades\"] = pd.DataFrame(columns=STRATEGY.TRADES_COLUMNS)\n",
-    "pair.user_data_[\"is_cointegrated\"] = False\n",
-    "\n",
-    "bt_result = BacktestResult(config=CONFIG)\n",
-    "training_minutes = CONFIG[\"training_minutes\"]\n",
-    "open_threshold = CONFIG[\"dis-equilibrium_open_trshld\"]\n",
-    "close_threshold = CONFIG[\"dis-equilibrium_close_trshld\"]\n",
-    "\n",
-    "# Limit iterations for demonstration (change this to max_iterations for full run)\n",
-    "max_demo_iterations = min(200, max_iterations)  # Process first 200 minutes\n",
-    "print(f\"Processing first {max_demo_iterations} iterations for demonstration...\\n\")\n",
-    "\n",
-    "for curr_training_start_idx in range(max_demo_iterations):\n",
-    "    if curr_training_start_idx % 20 == 0:\n",
-    "        print(f\"Processing iteration {curr_training_start_idx}/{max_demo_iterations}...\")\n",
-    "\n",
-    "    # Get datasets for this iteration\n",
-    "    pair.get_datasets(\n",
-    "        training_minutes=training_minutes,\n",
-    "        training_start_index=curr_training_start_idx,\n",
-    "        testing_size=1\n",
-    "    )\n",
-    "\n",
-    "    if len(pair.training_df_) < training_minutes:\n",
-    "        print(f\"Iteration {curr_training_start_idx}: Not enough training data. Stopping.\")\n",
-    "        break\n",
-    "\n",
-    "    # Record timestamp for this iteration\n",
-    "    current_timestamp = pair.testing_df_['tstamp'].iloc[0] if len(pair.testing_df_) > 0 else None\n",
-    "    timestamp_history.append(current_timestamp)\n",
-    "\n",
-    "    # Train and test cointegration\n",
-    "    try:\n",
-    "        is_cointegrated = pair.train_pair()\n",
-    "        cointegration_history.append(is_cointegrated)\n",
-    "\n",
-    "        if is_cointegrated:\n",
-    "            # Record model parameters\n",
-    "            beta_history.append(pair.vecm_fit_.beta.flatten())\n",
-    "            alpha_history.append(pair.vecm_fit_.alpha.flatten())\n",
-    "            training_mu_history.append(pair.training_mu_)\n",
-    "            training_std_history.append(pair.training_std_)\n",
-    "\n",
-    "            # Generate prediction for current minute\n",
-    "            pair.predict()\n",
-    "\n",
-    "            if len(pair.predicted_df_) > 0:\n",
-    "                current_disequilibrium = pair.predicted_df_['disequilibrium'].iloc[0]\n",
-    "                current_scaled_disequilibrium = pair.predicted_df_['scaled_disequilibrium'].iloc[0]\n",
-    "                disequilibrium_history.append(current_disequilibrium)\n",
-    "                scaled_disequilibrium_history.append(current_scaled_disequilibrium)\n",
-    "            else:\n",
-    "                disequilibrium_history.append(np.nan)\n",
-    "                scaled_disequilibrium_history.append(np.nan)\n",
-    "        else:\n",
-    "            # No cointegration\n",
-    "            beta_history.append(None)\n",
-    "            alpha_history.append(None)\n",
-    "            training_mu_history.append(np.nan)\n",
-    "            training_std_history.append(np.nan)\n",
-    "            disequilibrium_history.append(np.nan)\n",
-    "            scaled_disequilibrium_history.append(np.nan)\n",
-    "\n",
-    "    except Exception as e:\n",
-    "        print(f\"Iteration {curr_training_start_idx}: Training failed: {str(e)}\")\n",
-    "        cointegration_history.append(False)\n",
-    "        beta_history.append(None)\n",
-    "        alpha_history.append(None)\n",
-    "        training_mu_history.append(np.nan)\n",
-    "        training_std_history.append(np.nan)\n",
-    "        disequilibrium_history.append(np.nan)\n",
-    "        scaled_disequilibrium_history.append(np.nan)\n",
-    "\n",
-    "    # Record current state\n",
-    "    current_state = pair.user_data_.get('state', PairState.INITIAL)\n",
-    "    state_history.append(current_state)\n",
-    "\n",
-    "print(f\"\\nCompleted {len(cointegration_history)} iterations\")\n",
-    "print(f\"Cointegration rate: {sum(cointegration_history)/len(cointegration_history)*100:.1f}%\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Visualize Sliding Window Results"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Create comprehensive visualization of sliding window results\n",
-    "fig, axes = plt.subplots(6, 1, figsize=(18, 24))\n",
-    "\n",
-    "# Filter valid timestamps\n",
-    "valid_timestamps = [ts for ts in timestamp_history if ts is not None]\n",
-    "n_points = len(valid_timestamps)\n",
-    "\n",
-    "if n_points == 0:\n",
-    "    print(\"No valid data points to visualize\")\n",
-    "else:\n",
-    "    # 1. Cointegration Status Over Time\n",
-    "    cointegration_values = [1 if coint else 0 for coint in cointegration_history[:n_points]]\n",
-    "    axes[0].plot(valid_timestamps, cointegration_values, 'o-', alpha=0.7, markersize=3)\n",
-    "    axes[0].fill_between(valid_timestamps, cointegration_values, alpha=0.3)\n",
-    "    axes[0].set_title('Cointegration Status Over Time (1=Cointegrated, 0=Not Cointegrated)')\n",
-    "    axes[0].set_ylabel('Cointegrated')\n",
-    "    axes[0].set_ylim(-0.1, 1.1)\n",
-    "    axes[0].grid(True)\n",
-    "\n",
-    "    # 2. Beta Coefficients Evolution\n",
-    "    valid_betas = []\n",
-    "    beta_timestamps = []\n",
-    "    for i, beta in enumerate(beta_history[:n_points]):\n",
-    "        if beta is not None and i < len(valid_timestamps):\n",
-    "            valid_betas.append(beta)\n",
-    "            beta_timestamps.append(valid_timestamps[i])\n",
-    "\n",
-    "    if valid_betas:\n",
-    "        beta_array = np.array(valid_betas)\n",
-    "        axes[1].plot(beta_timestamps, beta_array[:, 1], 'o-', alpha=0.7, markersize=2,\n",
-    "                    label='Beta[1]', color='red')\n",
-    "        axes[1].set_title('VECM Beta[1] Coefficient Evolution (Beta[0] = 1.0 by normalization)')\n",
-    "        axes[1].set_ylabel('Beta[1] Value')\n",
-    "        axes[1].legend()\n",
-    "        axes[1].grid(True)\n",
-    "\n",
-    "    # 3. Training Mean and Std Evolution\n",
-    "    valid_mu = [mu for mu in training_mu_history[:n_points] if not np.isnan(mu)]\n",
-    "    valid_std = [std for std in training_std_history[:n_points] if not np.isnan(std)]\n",
-    "    mu_timestamps = [valid_timestamps[i] for i, mu in enumerate(training_mu_history[:n_points]) if not np.isnan(mu)]\n",
-    "\n",
-    "    if valid_mu:\n",
-    "        axes[2].plot(mu_timestamps, valid_mu, 'b-', alpha=0.7, label='Training Mean', linewidth=1)\n",
-    "        ax2_twin = axes[2].twinx()\n",
-    "        ax2_twin.plot(mu_timestamps, valid_std, 'r-', alpha=0.7, label='Training Std', linewidth=1)\n",
-    "        axes[2].set_title('Training Dis-equilibrium Statistics Evolution')\n",
-    "        axes[2].set_ylabel('Mean', color='b')\n",
-    "        ax2_twin.set_ylabel('Std', color='r')\n",
-    "        axes[2].grid(True)\n",
-    "        axes[2].legend(loc='upper left')\n",
-    "        ax2_twin.legend(loc='upper right')\n",
-    "\n",
-    "    # 4. Raw Dis-equilibrium Over Time\n",
-    "    valid_diseq = [diseq for diseq in disequilibrium_history[:n_points] if not np.isnan(diseq)]\n",
-    "    diseq_timestamps = [valid_timestamps[i] for i, diseq in enumerate(disequilibrium_history[:n_points]) if not np.isnan(diseq)]\n",
-    "\n",
-    "    if valid_diseq:\n",
-    "        axes[3].plot(diseq_timestamps, valid_diseq, 'g-', alpha=0.7, linewidth=1)\n",
-    "        # Add rolling mean\n",
-    "        if len(valid_diseq) > 10:\n",
-    "            rolling_mean = pd.Series(valid_diseq).rolling(window=10, min_periods=1).mean()\n",
-    "            axes[3].plot(diseq_timestamps, rolling_mean, 'r-', alpha=0.8, linewidth=2, label='10-period MA')\n",
-    "            axes[3].legend()\n",
-    "        axes[3].set_title('Raw Dis-equilibrium Over Time')\n",
-    "        axes[3].set_ylabel('Dis-equilibrium')\n",
-    "        axes[3].grid(True)\n",
-    "\n",
-    "    # 5. Scaled Dis-equilibrium with Thresholds\n",
-    "    valid_scaled_diseq = [diseq for diseq in scaled_disequilibrium_history[:n_points] if not np.isnan(diseq)]\n",
-    "    scaled_diseq_timestamps = [valid_timestamps[i] for i, diseq in enumerate(scaled_disequilibrium_history[:n_points]) if not np.isnan(diseq)]\n",
-    "\n",
-    "    if valid_scaled_diseq:\n",
-    "        axes[4].plot(scaled_diseq_timestamps, valid_scaled_diseq, 'purple', alpha=0.7, linewidth=1)\n",
-    "        axes[4].axhline(y=open_threshold, color='red', linestyle='--', alpha=0.8,\n",
-    "                       label=f'Open Threshold ({open_threshold})')\n",
-    "        axes[4].axhline(y=close_threshold, color='blue', linestyle='--', alpha=0.8,\n",
-    "                       label=f'Close Threshold ({close_threshold})')\n",
-    "        axes[4].axhline(y=0, color='black', linestyle='-', alpha=0.5, linewidth=0.5)\n",
-    "        axes[4].set_title('Scaled Dis-equilibrium with Trading Thresholds')\n",
-    "        axes[4].set_ylabel('Scaled Dis-equilibrium')\n",
-    "        axes[4].legend()\n",
-    "        axes[4].grid(True)\n",
-    "\n",
-    "    # 6. Price Data with Training Windows\n",
-    "    # Show original price data with indication of training windows\n",
-    "    colname_a, colname_b = pair.colnames()\n",
-    "    price_data = pair.market_data_[:n_points + training_minutes].copy()\n",
-    "\n",
-    "    axes[5].plot(price_data['tstamp'], price_data[colname_a], alpha=0.7, label=f'{SYMBOL_A}', linewidth=1)\n",
-    "    axes[5].plot(price_data['tstamp'], price_data[colname_b], alpha=0.7, label=f'{SYMBOL_B}', linewidth=1)\n",
-    "\n",
-    "    # Highlight training windows\n",
-    "    for i in range(0, min(n_points, 10), max(1, n_points//20)):  # Show every 20th window\n",
-    "        start_idx = i\n",
-    "        end_idx = i + training_minutes\n",
-    "        if end_idx < len(price_data):\n",
-    "            window_data = price_data.iloc[start_idx:end_idx]\n",
-    "            axes[5].axvspan(window_data['tstamp'].iloc[0], window_data['tstamp'].iloc[-1],\n",
-    "                           alpha=0.1, color='gray')\n",
-    "\n",
-    "    axes[5].set_title(f'Price Data with Training Windows (Gray bands show some training windows)')\n",
-    "    axes[5].set_ylabel('Price')\n",
-    "    axes[5].set_xlabel('Time')\n",
-    "    axes[5].legend()\n",
-    "    axes[5].grid(True)\n",
-    "\n",
-    "plt.tight_layout()\n",
-    "plt.show()\n",
-    "\n",
-    "# Print summary statistics\n",
-    "print(f\"\\n\" + \"=\"*80)\n",
-    "print(f\"SLIDING WINDOW ANALYSIS SUMMARY\")\n",
-    "print(f\"=\"*80)\n",
-    "print(f\"Total iterations processed: {n_points}\")\n",
-    "print(f\"Cointegration episodes: {sum(cointegration_history[:n_points])}\")\n",
-    "print(f\"Cointegration rate: {sum(cointegration_history[:n_points])/n_points*100:.1f}%\")\n",
-    "if valid_betas:\n",
-    "    print(f\"Beta coefficient stability: Std = {np.std(beta_array, axis=0)}\")\n",
-    "if valid_scaled_diseq:\n",
-    "    threshold_breaches = sum(1 for x in valid_scaled_diseq if abs(x) > open_threshold)\n",
-    "    print(f\"Open threshold breaches: {threshold_breaches} ({threshold_breaches/len(valid_scaled_diseq)*100:.1f}%)\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Analyze Training Window Evolution"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Detailed analysis of how training windows evolve\n",
-    "print(\"TRAINING WINDOW EVOLUTION ANALYSIS\")\n",
-    "print(\"=\"*50)\n",
-    "\n",
-    "# Analyze cointegration stability\n",
-    "if len(cointegration_history) > 1:\n",
-    "    # Find cointegration change points\n",
-    "    change_points = []\n",
-    "    for i in range(1, len(cointegration_history)):\n",
-    "        if cointegration_history[i] != cointegration_history[i-1]:\n",
-    "            change_points.append((i, cointegration_history[i], valid_timestamps[i] if i < len(valid_timestamps) else None))\n",
-    "\n",
-    "    print(f\"\\nCointegration Change Points:\")\n",
-    "    if change_points:\n",
-    "        for idx, status, timestamp in change_points[:10]:  # Show first 10\n",
-    "            status_str = \"GAINED\" if status else \"LOST\"\n",
-    "            print(f\"  Iteration {idx}: {status_str} cointegration at {timestamp}\")\n",
-    "        if len(change_points) > 10:\n",
-    "            print(f\"  ... and {len(change_points)-10} more changes\")\n",
-    "    else:\n",
-    "        print(f\"  No cointegration changes detected\")\n",
-    "\n",
-    "# Analyze beta stability when cointegrated\n",
-    "if valid_betas and len(valid_betas) > 10:\n",
-    "    beta_df = pd.DataFrame(valid_betas, columns=[f'Beta_{i}' for i in range(len(valid_betas[0]))])\n",
-    "    beta_df['timestamp'] = beta_timestamps\n",
-    "\n",
-    "    print(f\"\\nBeta Coefficient Analysis:\")\n",
-    "    print(f\"  Number of valid beta estimates: {len(valid_betas)}\")\n",
-    "    print(f\"  Beta statistics:\")\n",
-    "    for col in beta_df.columns[:-1]:  # Exclude timestamp\n",
-    "        print(f\"    {col}: Mean={beta_df[col].mean():.4f}, Std={beta_df[col].std():.4f}\")\n",
-    "\n",
-    "    # Check for beta regime changes\n",
-    "    beta_changes = []\n",
-    "    threshold = 0.1  # 10% change threshold\n",
-    "    for i in range(1, len(valid_betas)):\n",
-    "        if np.any(np.abs(np.array(valid_betas[i]) - np.array(valid_betas[i-1])) > threshold):\n",
-    "            beta_changes.append(i)\n",
-    "\n",
-    "    print(f\"  Significant beta changes (>{threshold*100}%): {len(beta_changes)}\")\n",
-    "    if beta_changes:\n",
-    "        print(f\"    Change frequency: {len(beta_changes)/len(valid_betas)*100:.1f}% of cointegrated periods\")\n",
-    "\n",
-    "# Analyze dis-equilibrium characteristics\n",
-    "if valid_scaled_diseq:\n",
-    "    scaled_diseq_series = pd.Series(valid_scaled_diseq)\n",
-    "\n",
-    "    print(f\"\\nDis-equilibrium Analysis:\")\n",
-    "    print(f\"  Mean: {scaled_diseq_series.mean():.4f}\")\n",
-    "    print(f\"  Std: {scaled_diseq_series.std():.4f}\")\n",
-    "    print(f\"  Min: {scaled_diseq_series.min():.4f}\")\n",
-    "    print(f\"  Max: {scaled_diseq_series.max():.4f}\")\n",
-    "\n",
-    "    # Threshold analysis\n",
-    "    open_breaches = sum(1 for x in valid_scaled_diseq if abs(x) >= open_threshold)\n",
-    "    close_opportunities = sum(1 for x in valid_scaled_diseq if abs(x) <= close_threshold)\n",
-    "\n",
-    "    print(f\"  Open threshold breaches: {open_breaches} ({open_breaches/len(valid_scaled_diseq)*100:.1f}%)\")\n",
-    "    print(f\"  Close opportunities: {close_opportunities} ({close_opportunities/len(valid_scaled_diseq)*100:.1f}%)\")\n",
-    "\n",
-    "    # Mean reversion analysis\n",
-    "    zero_crossings = 0\n",
-    "    for i in range(1, len(valid_scaled_diseq)):\n",
-    "        if (valid_scaled_diseq[i-1] * valid_scaled_diseq[i]) < 0:  # Sign change\n",
-    "            zero_crossings += 1\n",
-    "\n",
-    "    print(f\"  Zero crossings (mean reversion events): {zero_crossings}\")\n",
-    "    if zero_crossings > 0:\n",
-    "        print(f\"  Average time between mean reversions: {len(valid_scaled_diseq)/zero_crossings:.1f} minutes\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Run Complete Strategy (Optional)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Optional: Run the complete strategy to generate actual trades\n",
-    "# Warning: This may take several minutes depending on data size\n",
-    "\n",
-    "RUN_COMPLETE_STRATEGY = False  # Set to True to run full strategy\n",
-    "\n",
-    "if RUN_COMPLETE_STRATEGY:\n",
-    "    print(\"Running complete SlidingFitStrategy...\")\n",
-    "    print(\"This may take several minutes...\")\n",
-    "\n",
-    "    # Reset strategy state\n",
-    "    STRATEGY.curr_training_start_idx_ = 0\n",
-    "\n",
-    "    # Create new pair and result objects\n",
-    "    pair_full = TradingPair(\n",
-    "        market_data=market_data_df,\n",
-    "        symbol_a=SYMBOL_A,\n",
-    "        symbol_b=SYMBOL_B,\n",
-    "        price_column=CONFIG[\"price_column\"]\n",
-    "    )\n",
-    "\n",
-    "    bt_result_full = BacktestResult(config=CONFIG)\n",
-    "\n",
-    "    # Run strategy\n",
-    "    pair_trades = STRATEGY.run_pair(config=CONFIG, pair=pair_full, bt_result=bt_result_full)\n",
-    "\n",
-    "    if pair_trades is not None and len(pair_trades) > 0:\n",
-    "        print(f\"\\nGenerated {len(pair_trades)} trading signals:\")\n",
-    "        display(pair_trades)\n",
-    "\n",
-    "        # Analyze trades\n",
-    "        trade_times = pair_trades['time'].unique()\n",
-    "        print(f\"\\nTrade Analysis:\")\n",
-    "        print(f\"  Unique trade times: {len(trade_times)}\")\n",
-    "        print(f\"  Trade frequency: {len(trade_times)/max_iterations*100:.2f}% of total periods\")\n",
-    "\n",
-    "        # Group trades by time\n",
-    "        for trade_time in trade_times[:5]:  # Show first 5 trade times\n",
-    "            trades_at_time = pair_trades[pair_trades['time'] == trade_time]\n",
-    "            print(f\"\\n  Trade at {trade_time}:\")\n",
-    "            for _, trade in trades_at_time.iterrows():\n",
-    "                print(f\"    {trade['action']} {trade['symbol']} @ ${trade['price']:.2f} \"\n",
-    "                      f\"(dis-eq: {trade['scaled_disequilibrium']:.2f})\")\n",
-    "    else:\n",
-    "        print(\"\\nNo trading signals generated\")\n",
-    "        print(\"Possible reasons:\")\n",
-    "        print(\"  - Insufficient cointegration periods\")\n",
-    "        print(\"  - Dis-equilibrium never exceeded thresholds\")\n",
-    "        print(\"  - Strategy-specific conditions not met\")\n",
-    "else:\n",
-    "    print(\"Complete strategy execution is disabled.\")\n",
-    "    print(\"Set RUN_COMPLETE_STRATEGY = True to run the full strategy.\")\n",
-    "    print(\"Note: This may take several minutes depending on your data size.\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Interactive Parameter Analysis"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Interactive analysis for parameter optimization\n",
-    "print(\"PARAMETER SENSITIVITY ANALYSIS\")\n",
-    "print(\"=\"*40)\n",
-    "\n",
-    "print(f\"Current parameters:\")\n",
-    "print(f\"  Training window: {CONFIG['training_minutes']} minutes\")\n",
-    "print(f\"  Open threshold: {CONFIG['dis-equilibrium_open_trshld']}\")\n",
-    "print(f\"  Close threshold: {CONFIG['dis-equilibrium_close_trshld']}\")\n",
-    "\n",
-    "# Recommendations based on observed data\n",
-    "if valid_scaled_diseq:\n",
-    "    diseq_stats = pd.Series(valid_scaled_diseq).describe()\n",
-    "    print(f\"\\nObserved scaled dis-equilibrium statistics:\")\n",
-    "    print(f\"  75th percentile: {diseq_stats['75%']:.2f}\")\n",
-    "    print(f\"  95th percentile: {np.percentile(valid_scaled_diseq, 95):.2f}\")\n",
-    "    print(f\"  99th percentile: {np.percentile(valid_scaled_diseq, 99):.2f}\")\n",
-    "\n",
-    "    # Suggest optimal thresholds\n",
-    "    suggested_open = np.percentile(np.abs(valid_scaled_diseq), 85)\n",
-    "    suggested_close = np.percentile(np.abs(valid_scaled_diseq), 30)\n",
-    "\n",
-    "    print(f\"\\nSuggested threshold optimization:\")\n",
-    "    print(f\"  Suggested open threshold: {suggested_open:.2f} (85th percentile)\")\n",
-    "    print(f\"  Suggested close threshold: {suggested_close:.2f} (30th percentile)\")\n",
-    "\n",
-    "    if suggested_open != open_threshold or suggested_close != close_threshold:\n",
-    "        print(f\"\\nTo test these parameters, modify the CONFIG dictionary:\")\n",
-    "        print(f\"  CONFIG['dis-equilibrium_open_trshld'] = {suggested_open:.2f}\")\n",
-    "        print(f\"  CONFIG['dis-equilibrium_close_trshld'] = {suggested_close:.2f}\")\n",
-    "\n",
-    "# Training window recommendations\n",
-    "if len(cointegration_history) > 0:\n",
-    "    cointegration_rate = sum(cointegration_history)/len(cointegration_history)\n",
-    "    print(f\"\\nTraining window analysis:\")\n",
-    "    print(f\"  Current cointegration rate: {cointegration_rate*100:.1f}%\")\n",
-    "\n",
-    "    if cointegration_rate < 0.3:\n",
-    "        print(f\"  Recommendation: Consider increasing training window (current: {training_minutes})\")\n",
-    "        print(f\"  Suggested: {int(training_minutes * 1.5)} minutes\")\n",
-    "    elif cointegration_rate > 0.8:\n",
-    "        print(f\"  Recommendation: Consider decreasing training window for more responsive model\")\n",
-    "        print(f\"  Suggested: {int(training_minutes * 0.75)} minutes\")\n",
-    "    else:\n",
-    "        print(f\"  Current training window appears appropriate\")\n",
-    "\n",
-    "print(f\"\\nTo re-run analysis with different parameters:\")\n",
-    "print(f\"1. Modify the CONFIG dictionary above\")\n",
-    "print(f\"2. Re-run from the 'Run SlidingFitStrategy' cell\")\n",
-    "print(f\"3. Compare results with current analysis\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Summary and Conclusions\n",
-    "\n",
-    "This notebook demonstrates the SlidingFitStrategy's dynamic approach to pairs trading.\n",
-    "Key insights from the sliding window analysis:\n",
-    "\n",
-    "1. **Cointegration Stability**: How often the pair maintains cointegration\n",
-    "2. **Model Parameter Evolution**: How VECM coefficients change over time\n",
-    "3. **Threshold Effectiveness**: How well current thresholds capture trading opportunities\n",
-    "4. **Mean Reversion Patterns**: Frequency and timing of dis-equilibrium corrections\n",
-    "\n",
-    "The sliding approach allows for:\n",
-    "- **Adaptive modeling**: Responds to changing market conditions\n",
-    "- **Dynamic thresholding**: Can be optimized based on observed patterns\n",
-    "- **Real-time monitoring**: Provides continuous assessment of pair relationships\n",
-    "- **Risk management**: Early detection of cointegration breakdown"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "python3.12-venv",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.12.3"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}

src/notebooks/pt_static.ipynb

@@ -1,710 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "# Pairs Trading Visualization Notebook\n",
-    "\n",
-    "This notebook allows you to visualize pairs trading strategies on individual instrument pairs.\n",
-    "You can examine the relationship between two instruments, their dis-equilibrium, and trading signals."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### \ud83c\udfaf Key Features:\n",
-    "\n",
-    "1. **Interactive Configuration**: \n",
-    "   - Easy switching between CRYPTO and EQUITY configurations\n",
-    "   - Simple parameter adjustment for thresholds and training periods\n",
-    "\n",
-    "2. **Single Pair Focus**: \n",
-    "   - Instead of running multiple pairs, focuses on one pair at a time\n",
-    "   - Allows deep analysis of the relationship between two instruments\n",
-    "\n",
-    "3. **Step-by-Step Visualization**:\n",
-    "   - **Raw price data**: Individual prices, normalized comparison, and price ratios\n",
-    "   - **Training analysis**: Cointegration testing and VECM model fitting\n",
-    "   - **Dis-equilibrium visualization**: Both raw and scaled dis-equilibrium with threshold lines\n",
-    "   - **Strategy execution**: Trading signal generation and visualization\n",
-    "   - **Prediction analysis**: Actual vs predicted prices with trading signals overlaid\n",
-    "\n",
-    "4. **Rich Analytics**:\n",
-    "   - Cointegration status and VECM model details\n",
-    "   - Statistical summaries for all stages\n",
-    "   - Threshold crossing analysis\n",
-    "   - Trading signal breakdown\n",
-    "\n",
-    "5. **Interactive Experimentation**:\n",
-    "   - Easy parameter modification\n",
-    "   - Re-run capabilities for different configurations\n",
-    "   - Support for both StaticFitStrategy and SlidingFitStrategy\n",
-    "\n",
-    "### \ud83d\ude80 How to Use:\n",
-    "\n",
-    "1. **Start Jupyter**:\n",
-    "   ```bash\n",
-    "   cd src/notebooks\n",
-    "   jupyter notebook pairs_trading_visualization.ipynb\n",
-    "   ```\n",
-    "\n",
-    "2. **Customize Your Analysis**:\n",
-    "   - Change `SYMBOL_A` and `SYMBOL_B` to your desired trading pair\n",
-    "   - Switch between `CRYPTO_CONFIG` and `EQT_CONFIG`\n",
-    "   - Only **StaticFitStrategy** is supported. \n",
-    "   - Adjust thresholds and parameters as needed\n",
-    "\n",
-    "3. **Run and Visualize**:\n",
-    "   - Execute cells step by step to see the analysis unfold\n",
-    "   - Rich matplotlib visualizations show relationships and signals\n",
-    "   - Comprehensive summary at the end\n",
-    "\n",
-    "The notebook provides exactly what you requested - a way to visualize the relationship between two instruments and their scaled dis-equilibrium, with all the stages of your pairs trading strategy clearly displayed and analyzed.\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Setup and Imports"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import sys\n",
-    "import os\n",
-    "sys.path.append('..')\n",
-    "\n",
-    "import pandas as pd\n",
-    "import numpy as np\n",
-    "import matplotlib.pyplot as plt\n",
-    "import seaborn as sns\n",
-    "from typing import Dict, List, Optional\n",
-    "\n",
-    "# Import our modules\n",
-    "from strategies import StaticFitStrategy, SlidingFitStrategy\n",
-    "from tools.data_loader import load_market_data\n",
-    "from tools.trading_pair import TradingPair\n",
-    "from results import BacktestResult\n",
-    "\n",
-    "# Set plotting style\n",
-    "plt.style.use('seaborn-v0_8')\n",
-    "sns.set_palette(\"husl\")\n",
-    "plt.rcParams['figure.figsize'] = (12, 8)\n",
-    "\n",
-    "print(\"Setup complete!\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Configuration"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Configuration - Choose between CRYPTO_CONFIG or EQT_CONFIG\n",
-    "\n",
-    "CRYPTO_CONFIG = {\n",
-    "    \"security_type\": \"CRYPTO\",\n",
-    "    \"data_directory\": \"../../data/crypto\",\n",
-    "    \"datafiles\": [\n",
-    "        \"20250519.mktdata.ohlcv.db\",\n",
-    "    ],\n",
-    "    \"db_table_name\": \"bnbspot_ohlcv_1min\",\n",
-    "    \"exchange_id\": \"BNBSPOT\",\n",
-    "    \"instrument_id_pfx\": \"PAIR-\",\n",
-    "    \"instruments\": [\n",
-    "        \"BTC-USDT\",\n",
-    "        \"BCH-USDT\",\n",
-    "        \"ETH-USDT\",\n",
-    "        \"LTC-USDT\",\n",
-    "        \"XRP-USDT\",\n",
-    "        \"ADA-USDT\",\n",
-    "        \"SOL-USDT\",\n",
-    "        \"DOT-USDT\",\n",
-    "    ],\n",
-    "    \"trading_hours\": {\n",
-    "        \"begin_session\": \"00:00:00\",\n",
-    "        \"end_session\": \"23:59:00\",\n",
-    "        \"timezone\": \"UTC\",\n",
-    "    },\n",
-    "    \"price_column\": \"close\",\n",
-    "    \"min_required_points\": 30,\n",
-    "    \"zero_threshold\": 1e-10,\n",
-    "    \"dis-equilibrium_open_trshld\": 2.0,\n",
-    "    \"dis-equilibrium_close_trshld\": 0.5,\n",
-    "    \"training_minutes\": 120,\n",
-    "    \"funding_per_pair\": 2000.0,\n",
-    "}\n",
-    "\n",
-    "EQT_CONFIG = {\n",
-    "    \"security_type\": \"EQUITY\",\n",
-    "    \"data_directory\": \"../../data/equity\",\n",
-    "    \"datafiles\": {\n",
-    "        \"0508\":   \"20250508.alpaca_sim_md.db\",\n",
-    "        \"0509\":   \"20250509.alpaca_sim_md.db\",\n",
-    "        \"0510\":   \"20250510.alpaca_sim_md.db\",\n",
-    "        \"0511\":   \"20250511.alpaca_sim_md.db\",\n",
-    "        \"0512\":   \"20250512.alpaca_sim_md.db\",\n",
-    "        \"0513\":   \"20250513.alpaca_sim_md.db\",\n",
-    "        \"0514\":   \"20250514.alpaca_sim_md.db\",\n",
-    "        \"0515\":   \"20250515.alpaca_sim_md.db\",\n",
-    "        \"0516\":   \"20250516.alpaca_sim_md.db\",\n",
-    "        \"0517\":   \"20250517.alpaca_sim_md.db\",\n",
-    "        \"0518\":   \"20250518.alpaca_sim_md.db\",\n",
-    "        \"0519\":   \"20250519.alpaca_sim_md.db\",\n",
-    "        \"0520\":   \"20250520.alpaca_sim_md.db\",\n",
-    "        \"0521\":   \"20250521.alpaca_sim_md.db\",\n",
-    "        \"0522\":   \"20250522.alpaca_sim_md.db\",\n",
-    "    },\n",
-    "    \"db_table_name\": \"md_1min_bars\",\n",
-    "    \"exchange_id\": \"ALPACA\",\n",
-    "    \"instrument_id_pfx\": \"STOCK-\",\n",
-    "    \"instruments\": [\n",
-    "        \"COIN\",\n",
-    "        \"GBTC\",\n",
-    "        \"HOOD\",\n",
-    "        \"MSTR\",\n",
-    "        \"PYPL\",\n",
-    "    ],\n",
-    "    \"trading_hours\": {\n",
-    "        \"begin_session\": \"9:30:00\",\n",
-    "        \"end_session\": \"16:00:00\",\n",
-    "        \"timezone\": \"America/New_York\",\n",
-    "    },\n",
-    "    \"price_column\": \"close\",\n",
-    "    \"min_required_points\": 30,\n",
-    "    \"zero_threshold\": 1e-10,\n",
-    "    \"dis-equilibrium_open_trshld\": 2.0,\n",
-    "    \"dis-equilibrium_close_trshld\": 1.0, #0.5,\n",
-    "    \"training_minutes\": 120,\n",
-    "    \"funding_per_pair\": 2000.0,\n",
-    "}\n",
-    "\n",
-    "# Choose your configuration\n",
-    "CONFIG = EQT_CONFIG  # Change to CRYPTO_CONFIG if you want to use crypto data\n",
-    "\n",
-    "print(f\"Using {CONFIG['security_type']} configuration\")\n",
-    "print(f\"Available instruments: {CONFIG['instruments']}\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Select Trading Pair and Data File"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Select your trading pair and strategy\n",
-    "SYMBOL_A = \"COIN\"  # Change these to your desired symbols\n",
-    "SYMBOL_B = \"GBTC\"\n",
-    "DATA_FILE = CONFIG[\"datafiles\"][\"0509\"]\n",
-    "\n",
-    "# Choose strategy\n",
-    "STRATEGY = StaticFitStrategy()\n",
-    "\n",
-    "print(f\"Selected pair: {SYMBOL_A} & {SYMBOL_B}\")\n",
-    "print(f\"Data file: {DATA_FILE}\")\n",
-    "print(f\"Strategy: {type(STRATEGY).__name__}\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Load Market Data"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Load market data\n",
-    "datafile_path = f\"{CONFIG['data_directory']}/{DATA_FILE}\"\n",
-    "print(f\"Current working directory: {os.getcwd()}\")\n",
-    "print(f\"Loading data from: {datafile_path}\")\n",
-    "\n",
-    "market_data_df = load_market_data(datafile_path, config=CONFIG)\n",
-    "\n",
-    "print(f\"Loaded {len(market_data_df)} rows of market data\")\n",
-    "print(f\"Symbols in data: {market_data_df['symbol'].unique()}\")\n",
-    "print(f\"Time range: {market_data_df['tstamp'].min()} to {market_data_df['tstamp'].max()}\")\n",
-    "\n",
-    "# Display first few rows\n",
-    "market_data_df.head()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Create Trading Pair and Analyze"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Create trading pair\n",
-    "pair = TradingPair(\n",
-    "    market_data=market_data_df,\n",
-    "    symbol_a=SYMBOL_A,\n",
-    "    symbol_b=SYMBOL_B,\n",
-    "    price_column=CONFIG[\"price_column\"]\n",
-    ")\n",
-    "\n",
-    "print(f\"Created trading pair: {pair}\")\n",
-    "print(f\"Market data shape: {pair.market_data_.shape}\")\n",
-    "print(f\"Column names: {pair.colnames()}\")\n",
-    "\n",
-    "# Display first few rows of pair data\n",
-    "pair.market_data_.head()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Split Data into Training and Testing"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Get training and testing datasets\n",
-    "training_minutes = CONFIG[\"training_minutes\"]\n",
-    "pair.get_datasets(training_minutes=training_minutes)\n",
-    "\n",
-    "print(f\"Training data: {len(pair.training_df_)} rows\")\n",
-    "print(f\"Testing data: {len(pair.testing_df_)} rows\")\n",
-    "print(f\"Training period: {pair.training_df_['tstamp'].iloc[0]} to {pair.training_df_['tstamp'].iloc[-1]}\")\n",
-    "print(f\"Testing period: {pair.testing_df_['tstamp'].iloc[0]} to {pair.testing_df_['tstamp'].iloc[-1]}\")\n",
-    "\n",
-    "# Check for any missing data\n",
-    "print(f\"Training data null values: {pair.training_df_.isnull().sum().sum()}\")\n",
-    "print(f\"Testing data null values: {pair.testing_df_.isnull().sum().sum()}\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Visualize Raw Price Data"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Plot raw price data\n",
-    "fig, axes = plt.subplots(3, 1, figsize=(15, 12))\n",
-    "\n",
-    "# Combined price plot\n",
-    "colname_a, colname_b = pair.colnames()\n",
-    "all_data = pd.concat([pair.training_df_, pair.testing_df_]).reset_index(drop=True)\n",
-    "\n",
-    "# Plot individual prices\n",
-    "axes[0].plot(all_data['tstamp'], all_data[colname_a], label=f'{SYMBOL_A}', alpha=0.8)\n",
-    "axes[0].plot(all_data['tstamp'], all_data[colname_b], label=f'{SYMBOL_B}', alpha=0.8)\n",
-    "axes[0].axvline(x=pair.training_df_['tstamp'].iloc[-1], color='red', linestyle='--', alpha=0.7, label='Train/Test Split')\n",
-    "axes[0].set_title(f'Price Comparison: {SYMBOL_A} vs {SYMBOL_B}')\n",
-    "axes[0].set_ylabel('Price')\n",
-    "axes[0].legend()\n",
-    "axes[0].grid(True)\n",
-    "\n",
-    "# Normalized prices for comparison\n",
-    "norm_a = all_data[colname_a] / all_data[colname_a].iloc[0]\n",
-    "norm_b = all_data[colname_b] / all_data[colname_b].iloc[0]\n",
-    "\n",
-    "axes[1].plot(all_data['tstamp'], norm_a, label=f'{SYMBOL_A} (normalized)', alpha=0.8)\n",
-    "axes[1].plot(all_data['tstamp'], norm_b, label=f'{SYMBOL_B} (normalized)', alpha=0.8)\n",
-    "axes[1].axvline(x=pair.training_df_['tstamp'].iloc[-1], color='red', linestyle='--', alpha=0.7, label='Train/Test Split')\n",
-    "axes[1].set_title('Normalized Price Comparison')\n",
-    "axes[1].set_ylabel('Normalized Price')\n",
-    "axes[1].legend()\n",
-    "axes[1].grid(True)\n",
-    "\n",
-    "# Price ratio\n",
-    "price_ratio = all_data[colname_a] / all_data[colname_b]\n",
-    "axes[2].plot(all_data['tstamp'], price_ratio, label=f'{SYMBOL_A}/{SYMBOL_B} Ratio', color='green', alpha=0.8)\n",
-    "axes[2].axvline(x=pair.training_df_['tstamp'].iloc[-1], color='red', linestyle='--', alpha=0.7, label='Train/Test Split')\n",
-    "axes[2].set_title('Price Ratio')\n",
-    "axes[2].set_ylabel('Ratio')\n",
-    "axes[2].set_xlabel('Time')\n",
-    "axes[2].legend()\n",
-    "axes[2].grid(True)\n",
-    "\n",
-    "plt.tight_layout()\n",
-    "plt.show()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Train the Pair and Check Cointegration"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Train the pair and check cointegration\n",
-    "try:\n",
-    "    is_cointegrated = pair.train_pair()\n",
-    "    print(f\"Pair {pair} cointegration status: {is_cointegrated}\")\n",
-    "\n",
-    "    if is_cointegrated:\n",
-    "        print(f\"VECM Beta coefficients: {pair.vecm_fit_.beta.flatten()}\")\n",
-    "        print(f\"Training dis-equilibrium mean: {pair.training_mu_:.6f}\")\n",
-    "        print(f\"Training dis-equilibrium std: {pair.training_std_:.6f}\")\n",
-    "\n",
-    "        # Display VECM summary\n",
-    "        print(\"\\nVECM Model Summary:\")\n",
-    "        print(pair.vecm_fit_.summary())\n",
-    "    else:\n",
-    "        print(\"Pair is not cointegrated. Cannot proceed with strategy.\")\n",
-    "\n",
-    "except Exception as e:\n",
-    "    print(f\"Training failed: {str(e)}\")\n",
-    "    is_cointegrated = False"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Visualize Training Period Dis-equilibrium"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "if is_cointegrated:\n",
-    "    # fig, axes = plt.subplots(, 1, figsize=(15, 10))\n",
-    "\n",
-    "    # # Raw dis-equilibrium\n",
-    "    # axes[0].plot(pair.training_df_['tstamp'], pair.training_df_['dis-equilibrium'],\n",
-    "    #              color='blue', alpha=0.8, label='Raw Dis-equilibrium')\n",
-    "    # axes[0].axhline(y=pair.training_mu_, color='red', linestyle='--', alpha=0.7, label='Mean')\n",
-    "    # axes[0].axhline(y=pair.training_mu_ + pair.training_std_, color='orange', linestyle='--', alpha=0.5, label='+1 Std')\n",
-    "    # axes[0].axhline(y=pair.training_mu_ - pair.training_std_, color='orange', linestyle='--', alpha=0.5, label='-1 Std')\n",
-    "    # axes[0].set_title('Training Period: Raw Dis-equilibrium')\n",
-    "    # axes[0].set_ylabel('Dis-equilibrium')\n",
-    "    # axes[0].legend()\n",
-    "    # axes[0].grid(True)\n",
-    "\n",
-    "    # Scaled dis-equilibrium\n",
-    "    fig, axes = plt.subplots(1, 1, figsize=(15, 5))\n",
-    "    axes.plot(pair.training_df_['tstamp'], pair.training_df_['scaled_dis-equilibrium'],\n",
-    "                 color='green', alpha=0.8, label='Scaled Dis-equilibrium')\n",
-    "    axes.axhline(y=0, color='red', linestyle='--', alpha=0.7, label='Mean (0)')\n",
-    "    axes.axhline(y=1, color='orange', linestyle='--', alpha=0.5, label='+1 Std')\n",
-    "    axes.axhline(y=-1, color='orange', linestyle='--', alpha=0.5, label='-1 Std')\n",
-    "    axes.axhline(y=CONFIG['dis-equilibrium_open_trshld'], color='purple',\n",
-    "                    linestyle=':', alpha=0.7, label=f\"Open Threshold ({CONFIG['dis-equilibrium_open_trshld']})\")\n",
-    "    axes.axhline(y=CONFIG['dis-equilibrium_close_trshld'], color='brown',\n",
-    "                    linestyle=':', alpha=0.7, label=f\"Close Threshold ({CONFIG['dis-equilibrium_close_trshld']})\")\n",
-    "    axes.set_title('Training Period: Scaled Dis-equilibrium')\n",
-    "    axes.set_ylabel('Scaled Dis-equilibrium')\n",
-    "    axes.set_xlabel('Time')\n",
-    "    axes.legend()\n",
-    "    axes.grid(True)\n",
-    "\n",
-    "    plt.tight_layout()\n",
-    "    plt.show()\n",
-    "\n",
-    "    # Print statistics\n",
-    "    print(f\"Training dis-equilibrium statistics:\")\n",
-    "    print(f\"  Mean: {pair.training_df_['dis-equilibrium'].mean():.6f}\")\n",
-    "    print(f\"  Std: {pair.training_df_['dis-equilibrium'].std():.6f}\")\n",
-    "    print(f\"  Min: {pair.training_df_['dis-equilibrium'].min():.6f}\")\n",
-    "    print(f\"  Max: {pair.training_df_['dis-equilibrium'].max():.6f}\")\n",
-    "\n",
-    "    print(f\"\\nScaled dis-equilibrium statistics:\")\n",
-    "    print(f\"  Mean: {pair.training_df_['scaled_dis-equilibrium'].mean():.6f}\")\n",
-    "    print(f\"  Std: {pair.training_df_['scaled_dis-equilibrium'].std():.6f}\")\n",
-    "    print(f\"  Min: {pair.training_df_['scaled_dis-equilibrium'].min():.6f}\")\n",
-    "    print(f\"  Max: {pair.training_df_['scaled_dis-equilibrium'].max():.6f}\")\n",
-    "else:\n",
-    "    print(\"The pair is not cointegrated\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Generate Predictions and Run Strategy"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "if is_cointegrated:\n",
-    "    try:\n",
-    "        # Generate predictions\n",
-    "        pair.predict()\n",
-    "        print(f\"Generated predictions for {len(pair.predicted_df_)} rows\")\n",
-    "\n",
-    "        # Display prediction data structure\n",
-    "        print(f\"Prediction columns: {list(pair.predicted_df_.columns)}\")\n",
-    "        print(f\"Prediction period: {pair.predicted_df_['tstamp'].iloc[0]} to {pair.predicted_df_['tstamp'].iloc[-1]}\")\n",
-    "\n",
-    "        # Run strategy\n",
-    "        bt_result = BacktestResult(config=CONFIG)\n",
-    "        pair_trades = STRATEGY.run_pair(config=CONFIG, pair=pair, bt_result=bt_result)\n",
-    "\n",
-    "        if pair_trades is not None and len(pair_trades) > 0:\n",
-    "            print(f\"\\nGenerated {len(pair_trades)} trading signals:\")\n",
-    "            print(pair_trades)\n",
-    "        else:\n",
-    "            print(\"\\nNo trading signals generated\")\n",
-    "\n",
-    "    except Exception as e:\n",
-    "        print(f\"Prediction/Strategy failed: {str(e)}\")\n",
-    "        pair_trades = None"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Visualize Predictions and Dis-equilibrium"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "if is_cointegrated and hasattr(pair, 'predicted_df_'):\n",
-    "    fig, axes = plt.subplots(4, 1, figsize=(16, 16))\n",
-    "\n",
-    "    # Actual vs Predicted Prices\n",
-    "    colname_a, colname_b = pair.colnames()\n",
-    "\n",
-    "    axes[0].plot(pair.predicted_df_['tstamp'], pair.predicted_df_[colname_a],\n",
-    "                 label=f'{SYMBOL_A} Actual', alpha=0.8)\n",
-    "    axes[0].plot(pair.predicted_df_['tstamp'], pair.predicted_df_[f'{colname_a}_pred'],\n",
-    "                 label=f'{SYMBOL_A} Predicted', alpha=0.8, linestyle='--')\n",
-    "    axes[0].set_title('Actual vs Predicted Prices - Symbol A')\n",
-    "    axes[0].set_ylabel('Price')\n",
-    "    axes[0].legend()\n",
-    "    axes[0].grid(True)\n",
-    "\n",
-    "    axes[1].plot(pair.predicted_df_['tstamp'], pair.predicted_df_[colname_b],\n",
-    "                 label=f'{SYMBOL_B} Actual', alpha=0.8)\n",
-    "    axes[1].plot(pair.predicted_df_['tstamp'], pair.predicted_df_[f'{colname_b}_pred'],\n",
-    "                 label=f'{SYMBOL_B} Predicted', alpha=0.8, linestyle='--')\n",
-    "    axes[1].set_title('Actual vs Predicted Prices - Symbol B')\n",
-    "    axes[1].set_ylabel('Price')\n",
-    "    axes[1].legend()\n",
-    "    axes[1].grid(True)\n",
-    "\n",
-    "    # Raw dis-equilibrium\n",
-    "    axes[2].plot(pair.predicted_df_['tstamp'], pair.predicted_df_['disequilibrium'],\n",
-    "                 color='blue', alpha=0.8, label='Dis-equilibrium')\n",
-    "    axes[2].axhline(y=pair.training_mu_, color='red', linestyle='--', alpha=0.7, label='Training Mean')\n",
-    "    axes[2].set_title('Testing Period: Raw Dis-equilibrium')\n",
-    "    axes[2].set_ylabel('Dis-equilibrium')\n",
-    "    axes[2].legend()\n",
-    "    axes[2].grid(True)\n",
-    "\n",
-    "    # Scaled dis-equilibrium with trading signals\n",
-    "    axes[3].plot(pair.predicted_df_['tstamp'], pair.predicted_df_['scaled_disequilibrium'],\n",
-    "                 color='green', alpha=0.8, label='Scaled Dis-equilibrium')\n",
-    "\n",
-    "    # Add threshold lines\n",
-    "    axes[3].axhline(y=CONFIG['dis-equilibrium_open_trshld'], color='purple',\n",
-    "                    linestyle=':', alpha=0.7, label=f\"Open Threshold ({CONFIG['dis-equilibrium_open_trshld']})\")\n",
-    "    axes[3].axhline(y=CONFIG['dis-equilibrium_close_trshld'], color='brown',\n",
-    "                    linestyle=':', alpha=0.7, label=f\"Close Threshold ({CONFIG['dis-equilibrium_close_trshld']})\")\n",
-    "\n",
-    "    # Add trading signals if they exist\n",
-    "    if pair_trades is not None and len(pair_trades) > 0:\n",
-    "        for _, trade in pair_trades.iterrows():\n",
-    "            color = 'red' if 'BUY' in trade['action'] else 'blue'\n",
-    "            marker = '^' if 'BUY' in trade['action'] else 'v'\n",
-    "            axes[3].scatter(trade['time'], trade['scaled_disequilibrium'],\n",
-    "                           color=color, marker=marker, s=100, alpha=0.8,\n",
-    "                           label=f\"{trade['action']} {trade['symbol']}\" if _ < 2 else \"\")\n",
-    "\n",
-    "    axes[3].set_title('Testing Period: Scaled Dis-equilibrium with Trading Signals')\n",
-    "    axes[3].set_ylabel('Scaled Dis-equilibrium')\n",
-    "    axes[3].set_xlabel('Time')\n",
-    "    axes[3].legend()\n",
-    "    axes[3].grid(True)\n",
-    "\n",
-    "    plt.tight_layout()\n",
-    "    plt.show()\n",
-    "\n",
-    "    # Print prediction statistics\n",
-    "    print(f\"\\nTesting dis-equilibrium statistics:\")\n",
-    "    print(f\"  Mean: {pair.predicted_df_['disequilibrium'].mean():.6f}\")\n",
-    "    print(f\"  Std: {pair.predicted_df_['disequilibrium'].std():.6f}\")\n",
-    "    print(f\"  Min: {pair.predicted_df_['disequilibrium'].min():.6f}\")\n",
-    "    print(f\"  Max: {pair.predicted_df_['disequilibrium'].max():.6f}\")\n",
-    "\n",
-    "    print(f\"\\nTesting scaled dis-equilibrium statistics:\")\n",
-    "    print(f\"  Mean: {pair.predicted_df_['scaled_disequilibrium'].mean():.6f}\")\n",
-    "    print(f\"  Std: {pair.predicted_df_['scaled_disequilibrium'].std():.6f}\")\n",
-    "    print(f\"  Min: {pair.predicted_df_['scaled_disequilibrium'].min():.6f}\")\n",
-    "    print(f\"  Max: {pair.predicted_df_['scaled_disequilibrium'].max():.6f}\")\n",
-    "\n",
-    "    # Count threshold crossings\n",
-    "    open_crossings = (pair.predicted_df_['scaled_disequilibrium'] >= CONFIG['dis-equilibrium_open_trshld']).sum()\n",
-    "    close_crossings = (pair.predicted_df_['scaled_disequilibrium'] <= CONFIG['dis-equilibrium_close_trshld']).sum()\n",
-    "    print(f\"\\nThreshold crossings:\")\n",
-    "    print(f\"  Open threshold ({CONFIG['dis-equilibrium_open_trshld']}): {open_crossings} times\")\n",
-    "    print(f\"  Close threshold ({CONFIG['dis-equilibrium_close_trshld']}): {close_crossings} times\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Summary and Analysis"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "print(\"=\" * 60)\n",
-    "print(\"PAIRS TRADING ANALYSIS SUMMARY\")\n",
-    "print(\"=\" * 60)\n",
-    "\n",
-    "print(f\"\\nPair: {SYMBOL_A} & {SYMBOL_B}\")\n",
-    "print(f\"Strategy: {type(STRATEGY).__name__}\")\n",
-    "print(f\"Data file: {DATA_FILE}\")\n",
-    "print(f\"Training period: {training_minutes} minutes\")\n",
-    "\n",
-    "print(f\"\\nCointegration Status: {'\u2713 COINTEGRATED' if is_cointegrated else '\u2717 NOT COINTEGRATED'}\")\n",
-    "\n",
-    "if is_cointegrated:\n",
-    "    print(f\"\\nVECM Model:\")\n",
-    "    print(f\"  Beta coefficients: {pair.vecm_fit_.beta.flatten()}\")\n",
-    "    print(f\"  Training mean: {pair.training_mu_:.6f}\")\n",
-    "    print(f\"  Training std: {pair.training_std_:.6f}\")\n",
-    "\n",
-    "    if pair_trades is not None and len(pair_trades) > 0:\n",
-    "        print(f\"\\nTrading Signals: {len(pair_trades)} generated\")\n",
-    "        unique_times = pair_trades['time'].unique()\n",
-    "        print(f\"  Unique trade times: {len(unique_times)}\")\n",
-    "\n",
-    "        # Group by time to see paired trades\n",
-    "        for trade_time in unique_times:\n",
-    "            trades_at_time = pair_trades[pair_trades['time'] == trade_time]\n",
-    "            print(f\"\\n  Trade at {trade_time}:\")\n",
-    "            for _, trade in trades_at_time.iterrows():\n",
-    "                print(f\"    {trade['action']} {trade['symbol']} @ ${trade['price']:.2f} (dis-eq: {trade['scaled_disequilibrium']:.2f})\")\n",
-    "    else:\n",
-    "        print(f\"\\nTrading Signals: None generated\")\n",
-    "        print(\"  Possible reasons:\")\n",
-    "        print(\"    - Dis-equilibrium never exceeded open threshold\")\n",
-    "        print(\"    - Insufficient testing data\")\n",
-    "        print(\"    - Strategy-specific conditions not met\")\n",
-    "\n",
-    "else:\n",
-    "    print(\"\\nCannot proceed with trading strategy - pair is not cointegrated\")\n",
-    "    print(\"Consider:\")\n",
-    "    print(\"  - Trying different symbol pairs\")\n",
-    "    print(\"  - Adjusting training period length\")\n",
-    "    print(\"  - Using different data timeframe\")\n",
-    "\n",
-    "print(\"\\n\" + \"=\" * 60)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Interactive Analysis (Optional)\n",
-    "\n",
-    "You can modify the parameters below and re-run the analysis:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Interactive parameter adjustment\n",
-    "print(\"Current parameters:\")\n",
-    "print(f\"  Open threshold: {CONFIG['dis-equilibrium_open_trshld']}\")\n",
-    "print(f\"  Close threshold: {CONFIG['dis-equilibrium_close_trshld']}\")\n",
-    "print(f\"  Training minutes: {CONFIG['training_minutes']}\")\n",
-    "\n",
-    "# Uncomment and modify these to experiment:\n",
-    "# CONFIG['dis-equilibrium_open_trshld'] = 1.5\n",
-    "# CONFIG['dis-equilibrium_close_trshld'] = 0.3\n",
-    "# CONFIG['training_minutes'] = 180\n",
-    "\n",
-    "print(\"\\nTo re-run with different parameters:\")\n",
-    "print(\"1. Modify the parameters above\")\n",
-    "print(\"2. Re-run from the 'Split Data into Training and Testing' cell\")\n",
-    "print(\"3. Or try different symbol pairs by changing SYMBOL_A and SYMBOL_B\")"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "python3.12-venv",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.12.3"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 4
-}

src/pt_backtest.py

@@ -1,291 +0,0 @@
-import argparse
-import hjson
-import importlib
-import glob
-import os
-import sqlite3
-from datetime import datetime, date
-
-from typing import Any, Dict, List, Optional
-
-import pandas as pd
-
-from tools.data_loader import get_available_instruments_from_db, load_market_data
-from tools.trading_pair import TradingPair
-from results import BacktestResult, create_result_database, store_results_in_database, store_config_in_database
-
-
-def load_config(config_path: str) -> Dict:
-    with open(config_path, "r") as f:
-        config = hjson.load(f)
-    return config
-
-
-# def get_available_instruments_from_db(datafile: str, config: Dict) -> List[str]:
-#     """
-#     Auto-detect available instruments from the database by querying distinct instrument_id values.
-#     Returns instruments without the configured prefix.
-#     """
-#     try:
-#         conn = sqlite3.connect(datafile)
-
-#         # Query to get distinct instrument_ids
-#         query = f"""
-#         SELECT DISTINCT instrument_id 
-#         FROM {config['db_table_name']} 
-#         WHERE exchange_id = ?
-#         """
-
-#         cursor = conn.execute(query, (config["exchange_id"],))
-#         instrument_ids = [row[0] for row in cursor.fetchall()]
-#         conn.close()
-
-#         # Remove the configured prefix to get instrument symbols
-#         prefix = config.get("instrument_id_pfx", "")
-#         instruments = []
-#         for instrument_id in instrument_ids:
-#             if instrument_id.startswith(prefix):
-#                 symbol = instrument_id[len(prefix) :]
-#                 instruments.append(symbol)
-#             else:
-#                 instruments.append(instrument_id)
-
-#         return sorted(instruments)
-
-#     except Exception as e:
-#         print(f"Error auto-detecting instruments from {datafile}: {str(e)}")
-#         return []
-
-
-def resolve_datafiles(config: Dict, cli_datafiles: Optional[str] = None) -> List[str]:
-    """
-    Resolve the list of data files to process.
-    CLI datafiles take priority over config datafiles.
-    Supports wildcards in config but not in CLI.
-    """
-    if cli_datafiles:
-        # CLI override - comma-separated list, no wildcards
-        datafiles = [f.strip() for f in cli_datafiles.split(",")]
-        # Make paths absolute relative to data directory
-        data_dir = config.get("data_directory", "./data")
-        resolved_files = []
-        for df in datafiles:
-            if not os.path.isabs(df):
-                df = os.path.join(data_dir, df)
-            resolved_files.append(df)
-        return resolved_files
-
-    # Use config datafiles with wildcard support
-    config_datafiles = config.get("datafiles", [])
-    data_dir = config.get("data_directory", "./data")
-    resolved_files = []
-
-    for pattern in config_datafiles:
-        if "*" in pattern or "?" in pattern:
-            # Handle wildcards
-            if not os.path.isabs(pattern):
-                pattern = os.path.join(data_dir, pattern)
-            matched_files = glob.glob(pattern)
-            resolved_files.extend(matched_files)
-        else:
-            # Handle explicit file path
-            if not os.path.isabs(pattern):
-                pattern = os.path.join(data_dir, pattern)
-            resolved_files.append(pattern)
-
-    return sorted(list(set(resolved_files)))  # Remove duplicates and sort
-
-
-def run_backtest(
-    config: Dict,
-    datafile: str,
-    price_column: str,
-    strategy,
-    instruments: List[str],
-) -> BacktestResult:
-    """
-    Run backtest for all pairs using the specified instruments.
-    """
-    bt_result: BacktestResult = BacktestResult(config=config)
-
-    def _create_pairs(config: Dict, instruments: List[str]) -> List[TradingPair]:
-        nonlocal datafile
-        all_indexes = range(len(instruments))
-        unique_index_pairs = [(i, j) for i in all_indexes for j in all_indexes if i < j]
-        pairs = []
-
-        # Update config to use the specified instruments
-        config_copy = config.copy()
-        config_copy["instruments"] = instruments
-
-        market_data_df = load_market_data(datafile, config=config_copy)
-
-        for a_index, b_index in unique_index_pairs:
-            pair = TradingPair(
-                market_data=market_data_df,
-                symbol_a=instruments[a_index],
-                symbol_b=instruments[b_index],
-                price_column=price_column,
-            )
-            pairs.append(pair)
-        return pairs
-
-    pairs_trades = []
-    for pair in _create_pairs(config, instruments):
-        single_pair_trades = strategy.run_pair(
-            pair=pair, config=config, bt_result=bt_result
-        )
-        if single_pair_trades is not None and len(single_pair_trades) > 0:
-            pairs_trades.append(single_pair_trades)
-
-    # Check if result_list has any data before concatenating
-    if len(pairs_trades) == 0:
-        print("No trading signals found for any pairs")
-        return bt_result
-
-    result = pd.concat(pairs_trades, ignore_index=True)
-    result["time"] = pd.to_datetime(result["time"])
-    result = result.set_index("time").sort_index()
-
-    bt_result.collect_single_day_results(result)
-    return bt_result
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Run pairs trading backtest.")
-    parser.add_argument(
-        "--config", type=str, required=True, help="Path to the configuration file."
-    )
-    parser.add_argument(
-        "--datafiles",
-        type=str,
-        required=False,
-        help="Comma-separated list of data files (overrides config). No wildcards supported.",
-    )
-    parser.add_argument(
-        "--instruments",
-        type=str,
-        required=False,
-        help="Comma-separated list of instrument symbols (e.g., COIN,GBTC). If not provided, auto-detects from database.",
-    )
-    parser.add_argument(
-        "--result_db",
-        type=str,
-        required=True,
-        help="Path to SQLite database for storing results. Use 'NONE' to disable database output.",
-    )
-
-    args = parser.parse_args()
-
-    config: Dict = load_config(args.config)
-
-    # Dynamically instantiate strategy class
-    strategy_class_name = config.get("strategy_class", "strategies.StaticFitStrategy")
-    module_name, class_name = strategy_class_name.rsplit(".", 1)
-    module = importlib.import_module(module_name)
-    strategy = getattr(module, class_name)()
-
-    # Resolve data files (CLI takes priority over config)
-    datafiles = resolve_datafiles(config, args.datafiles)
-
-    if not datafiles:
-        print("No data files found to process.")
-        return
-
-    print(f"Found {len(datafiles)} data files to process:")
-    for df in datafiles:
-        print(f"  - {df}")
-
-    # Create result database if needed
-    if args.result_db.upper() != "NONE":
-        create_result_database(args.result_db)
-
-    # Initialize a dictionary to store all trade results
-    all_results: Dict[str, Dict[str, Any]] = {}
-    
-    # Store configuration in database for reference
-    if args.result_db.upper() != "NONE":
-        # Get list of all instruments for storage
-        all_instruments = []
-        for datafile in datafiles:
-            if args.instruments:
-                file_instruments = [inst.strip() for inst in args.instruments.split(",")]
-            else:
-                file_instruments = get_available_instruments_from_db(datafile, config)
-            all_instruments.extend(file_instruments)
-        
-        # Remove duplicates while preserving order
-        unique_instruments = list(dict.fromkeys(all_instruments))
-        
-        store_config_in_database(
-            db_path=args.result_db,
-            config_file_path=args.config,
-            config=config,
-            strategy_class=strategy_class_name,
-            datafiles=datafiles,
-            instruments=unique_instruments
-        )
-
-    # Process each data file
-    price_column = config["price_column"]
-
-    for datafile in datafiles:
-        print(f"\n====== Processing {os.path.basename(datafile)} ======")
-
-        # Determine instruments to use
-        if args.instruments:
-            # Use CLI-specified instruments
-            instruments = [inst.strip() for inst in args.instruments.split(",")]
-            print(f"Using CLI-specified instruments: {instruments}")
-        else:
-            # Auto-detect instruments from database
-            instruments = get_available_instruments_from_db(datafile, config)
-            print(f"Auto-detected instruments: {instruments}")
-
-        if not instruments:
-            print(f"No instruments found for {datafile}, skipping...")
-            continue
-
-        # Process data for this file
-        try:
-            strategy.reset()
-            
-            bt_results = run_backtest(
-                config=config,
-                datafile=datafile,
-                price_column=price_column,
-                strategy=strategy,
-                instruments=instruments,
-            )
-
-            # Store results with file name as key
-            filename = os.path.basename(datafile)
-            all_results[filename] = {"trades": bt_results.trades.copy()}
-
-            # Store results in database
-            if args.result_db.upper() != "NONE":
-                store_results_in_database(args.result_db, datafile, bt_results)
-
-            print(f"Successfully processed {filename}")
-
-        except Exception as err:
-            print(f"Error processing {datafile}: {str(err)}")
-            import traceback
-
-            traceback.print_exc()
-
-    # Calculate and print results using a new BacktestResult instance for aggregation
-    if all_results:
-        aggregate_bt_results = BacktestResult(config=config)
-        aggregate_bt_results.calculate_returns(all_results)
-        aggregate_bt_results.print_grand_totals()
-        aggregate_bt_results.print_outstanding_positions()
-
-        if args.result_db.upper() != "NONE":
-            print(f"\nResults stored in database: {args.result_db}")
-    else:
-        print("No results to display.")
-
-
-if __name__ == "__main__":
-    main()

src/results.py

@@ -1,656 +0,0 @@
-from typing import Any, Dict, List
-import pandas as pd
-import sqlite3
-import os
-from datetime import datetime, date
-
-
-# Recommended replacement adapters and converters for Python 3.12+
-# From: https://docs.python.org/3/library/sqlite3.html#sqlite3-adapter-converter-recipes
-def adapt_date_iso(val):
-    """Adapt datetime.date to ISO 8601 date."""
-    return val.isoformat()
-
-def adapt_datetime_iso(val):
-    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
-    return val.isoformat()
-
-def convert_date(val):
-    """Convert ISO 8601 date to datetime.date object."""
-    return datetime.fromisoformat(val.decode()).date()
-
-def convert_datetime(val):
-    """Convert ISO 8601 datetime to datetime.datetime object."""
-    return datetime.fromisoformat(val.decode())
-
-# Register the adapters and converters
-sqlite3.register_adapter(date, adapt_date_iso)
-sqlite3.register_adapter(datetime, adapt_datetime_iso)
-sqlite3.register_converter("date", convert_date)
-sqlite3.register_converter("datetime", convert_datetime)
-
-
-def create_result_database(db_path: str) -> None:
-    """
-    Create the SQLite database and required tables if they don't exist.
-    """
-    try:
-        conn = sqlite3.connect(db_path)
-        cursor = conn.cursor()
-        
-        # Create the pt_bt_results table for completed trades
-        cursor.execute('''
-            CREATE TABLE IF NOT EXISTS pt_bt_results (
-                date DATE,
-                pair TEXT,
-                symbol TEXT,
-                open_time DATETIME,
-                open_side TEXT,
-                open_price REAL,
-                open_quantity INTEGER,
-                open_disequilibrium REAL,
-                close_time DATETIME,
-                close_side TEXT,
-                close_price REAL,
-                close_quantity INTEGER,
-                close_disequilibrium REAL,
-                symbol_return REAL,
-                pair_return REAL
-            )
-        ''')
-        cursor.execute("DELETE FROM pt_bt_results;")
-
-        # Create the outstanding_positions table for open positions
-        cursor.execute('''
-            CREATE TABLE IF NOT EXISTS outstanding_positions (
-                date DATE,
-                pair TEXT,
-                symbol TEXT,
-                position_quantity REAL,
-                last_price REAL,
-                unrealized_return REAL,
-                open_price REAL,
-                open_side TEXT
-            )
-        ''')
-        cursor.execute("DELETE FROM outstanding_positions;")
-        
-        # Create the config table for storing configuration JSON for reference
-        cursor.execute('''
-            CREATE TABLE IF NOT EXISTS config (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                run_timestamp DATETIME,
-                config_file_path TEXT,
-                config_json TEXT,
-                strategy_class TEXT,
-                datafiles TEXT,
-                instruments TEXT
-            )
-        ''')
-        cursor.execute("DELETE FROM config;")
-        
-        conn.commit()
-        conn.close()
-        
-    except Exception as e:
-        print(f"Error creating result database: {str(e)}")
-        raise
-
-
-def store_config_in_database(db_path: str, config_file_path: str, config: Dict, strategy_class: str, datafiles: List[str], instruments: List[str]) -> None:
-    """
-    Store configuration information in the database for reference.
-    """
-    import json
-    
-    if db_path.upper() == "NONE":
-        return
-        
-    try:
-        conn = sqlite3.connect(db_path)
-        cursor = conn.cursor()
-        
-        # Convert config to JSON string
-        config_json = json.dumps(config, indent=2, default=str)
-        
-        # Convert lists to comma-separated strings for storage
-        datafiles_str = ', '.join(datafiles)
-        instruments_str = ', '.join(instruments)
-        
-        # Insert configuration record
-        cursor.execute('''
-            INSERT INTO config (
-                run_timestamp, config_file_path, config_json, strategy_class, datafiles, instruments
-            ) VALUES (?, ?, ?, ?, ?, ?)
-        ''', (
-            datetime.now(),
-            config_file_path,
-            config_json,
-            strategy_class,
-            datafiles_str,
-            instruments_str
-        ))
-        
-        conn.commit()
-        conn.close()
-        
-        print(f"Configuration stored in database")
-        
-    except Exception as e:
-        print(f"Error storing configuration in database: {str(e)}")
-        import traceback
-        traceback.print_exc()
-
-
-def store_results_in_database(db_path: str, datafile: str, bt_result: 'BacktestResult') -> None:
-    """
-    Store backtest results in the SQLite database.
-    """
-    if db_path.upper() == "NONE":
-        return
-    
-    def convert_timestamp(timestamp):
-        """Convert pandas Timestamp to Python datetime object for SQLite compatibility."""
-        if timestamp is None:
-            return None
-        if hasattr(timestamp, 'to_pydatetime'):
-            return timestamp.to_pydatetime()
-        return timestamp
-    
-    try:
-        # Extract date from datafile name (assuming format like 20250528.mktdata.ohlcv.db)
-        filename = os.path.basename(datafile)
-        date_str = filename.split('.')[0]  # Extract date part
-        
-        # Convert to proper date format
-        try:
-            date_obj = datetime.strptime(date_str, '%Y%m%d').date()
-        except ValueError:
-            # If date parsing fails, use current date
-            date_obj = datetime.now().date()
-        
-        conn = sqlite3.connect(db_path)
-        cursor = conn.cursor()
-        
-        # Process each trade from bt_result
-        trades = bt_result.get_trades()
-        
-        for pair_name, symbols in trades.items():
-            # Calculate pair return for this pair
-            pair_return = 0.0
-            pair_trades = []
-            
-            # First pass: collect all trades and calculate returns
-            for symbol, symbol_trades in symbols.items():
-                if len(symbol_trades) == 0:  # No trades for this symbol
-                    print(f"Warning: No trades found for symbol {symbol} in pair {pair_name}")
-                    continue
-                    
-                elif len(symbol_trades) >= 2:  # Completed trades (entry + exit)
-                    # Handle both old and new tuple formats
-                    if len(symbol_trades[0]) == 2:  # Old format: (action, price)
-                        entry_action, entry_price = symbol_trades[0]
-                        exit_action, exit_price = symbol_trades[1]
-                        open_disequilibrium = 0.0  # Fallback for old format
-                        open_scaled_disequilibrium = 0.0
-                        close_disequilibrium = 0.0
-                        close_scaled_disequilibrium = 0.0
-                        open_time = datetime.now()
-                        close_time = datetime.now()
-                    else:  # New format: (action, price, disequilibrium, scaled_disequilibrium, timestamp)
-                        entry_action, entry_price, open_disequilibrium, open_scaled_disequilibrium, open_time = symbol_trades[0]
-                        exit_action, exit_price, close_disequilibrium, close_scaled_disequilibrium, close_time = symbol_trades[1]
-                        
-                        # Handle None values
-                        open_disequilibrium = open_disequilibrium if open_disequilibrium is not None else 0.0
-                        open_scaled_disequilibrium = open_scaled_disequilibrium if open_scaled_disequilibrium is not None else 0.0
-                        close_disequilibrium = close_disequilibrium if close_disequilibrium is not None else 0.0
-                        close_scaled_disequilibrium = close_scaled_disequilibrium if close_scaled_disequilibrium is not None else 0.0
-                        
-                        # Convert pandas Timestamps to Python datetime objects
-                        open_time = convert_timestamp(open_time) or datetime.now()
-                        close_time = convert_timestamp(close_time) or datetime.now()
-                    
-                    # Calculate actual share quantities based on funding per pair
-                    # Split funding equally between the two positions
-                    funding_per_position = bt_result.config["funding_per_pair"] / 2
-                    shares = funding_per_position / entry_price
-                    
-                    # Calculate symbol return
-                    symbol_return = 0.0
-                    if entry_action == "BUY" and exit_action == "SELL":
-                        symbol_return = (exit_price - entry_price) / entry_price * 100
-                    elif entry_action == "SELL" and exit_action == "BUY":
-                        symbol_return = (entry_price - exit_price) / entry_price * 100
-                    
-                    pair_return += symbol_return
-                    
-                    pair_trades.append({
-                        'symbol': symbol,
-                        'entry_action': entry_action,
-                        'entry_price': entry_price,
-                        'exit_action': exit_action,
-                        'exit_price': exit_price,
-                        'symbol_return': symbol_return,
-                        'open_disequilibrium': open_disequilibrium,
-                        'open_scaled_disequilibrium': open_scaled_disequilibrium,
-                        'close_disequilibrium': close_disequilibrium,
-                        'close_scaled_disequilibrium': close_scaled_disequilibrium,
-                        'open_time': open_time,
-                        'close_time': close_time,
-                        'shares': shares,
-                        'is_completed': True
-                    })
-                    
-                # Skip one-sided trades - they will be handled by outstanding_positions table
-                elif len(symbol_trades) == 1:
-                    print(f"Skipping one-sided trade for {symbol} in pair {pair_name} - will be stored in outstanding_positions table")
-                    continue
-                    
-                else:
-                    # This should not happen, but handle unexpected cases
-                    print(f"Warning: Unexpected number of trades ({len(symbol_trades)}) for symbol {symbol} in pair {pair_name}")
-                    continue
-            
-            # Second pass: insert completed trade records into database
-            for trade in pair_trades:
-                # Only store completed trades in pt_bt_results table
-                cursor.execute('''
-                    INSERT INTO pt_bt_results (
-                        date, pair, symbol, open_time, open_side, open_price, 
-                        open_quantity, open_disequilibrium, close_time, close_side, 
-                        close_price, close_quantity, close_disequilibrium, 
-                        symbol_return, pair_return
-                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                ''', (
-                    date_obj,
-                    pair_name,
-                    trade['symbol'],
-                    trade['open_time'],
-                    trade['entry_action'],
-                    trade['entry_price'],
-                    trade['shares'],
-                    trade['open_scaled_disequilibrium'],
-                    trade['close_time'],
-                    trade['exit_action'],
-                    trade['exit_price'],
-                    trade['shares'],
-                    trade['close_scaled_disequilibrium'],
-                    trade['symbol_return'],
-                    pair_return
-                ))
-        
-        # Store outstanding positions in separate table
-        outstanding_positions = bt_result.get_outstanding_positions()
-        for pos in outstanding_positions:
-            # Calculate position quantity (negative for SELL positions)
-            position_qty_a = pos['shares_a'] if pos['side_a'] == 'BUY' else -pos['shares_a']
-            position_qty_b = pos['shares_b'] if pos['side_b'] == 'BUY' else -pos['shares_b']
-            
-            # Calculate unrealized returns
-            # For symbol A: (current_price - open_price) / open_price * 100 * position_direction
-            unrealized_return_a = ((pos['current_px_a'] - pos['open_px_a']) / pos['open_px_a'] * 100) * (1 if pos['side_a'] == 'BUY' else -1)
-            unrealized_return_b = ((pos['current_px_b'] - pos['open_px_b']) / pos['open_px_b'] * 100) * (1 if pos['side_b'] == 'BUY' else -1)
-            
-            # Store outstanding position for symbol A
-            cursor.execute('''
-                INSERT INTO outstanding_positions (
-                    date, pair, symbol, position_quantity, last_price, unrealized_return, open_price, open_side
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-            ''', (
-                date_obj,
-                pos['pair'],
-                pos['symbol_a'],
-                position_qty_a,
-                pos['current_px_a'],
-                unrealized_return_a,
-                pos['open_px_a'],
-                pos['side_a']
-            ))
-            
-            # Store outstanding position for symbol B
-            cursor.execute('''
-                INSERT INTO outstanding_positions (
-                    date, pair, symbol, position_quantity, last_price, unrealized_return, open_price, open_side
-                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-            ''', (
-                date_obj,
-                pos['pair'],
-                pos['symbol_b'],
-                position_qty_b,
-                pos['current_px_b'],
-                unrealized_return_b,
-                pos['open_px_b'],
-                pos['side_b']
-            ))
-        
-        conn.commit()
-        conn.close()
-        
-    except Exception as e:
-        print(f"Error storing results in database: {str(e)}")
-        import traceback
-        traceback.print_exc()
-
-
-class BacktestResult:
-    """
-    Class to handle backtest results, trades tracking, PnL calculations, and reporting.
-    """
-
-    def __init__(self, config: Dict[str, Any]):
-        self.config = config
-        self.trades: Dict[str, Dict[str, Any]] = {}
-        self.total_realized_pnl = 0.0
-        self.outstanding_positions: List[Dict[str, Any]] = []
-
-    def add_trade(self, pair_nm, symbol, action, price, disequilibrium=None, scaled_disequilibrium=None, timestamp=None):
-        """Add a trade to the results tracking."""
-        pair_nm = str(pair_nm)
-
-        if pair_nm not in self.trades:
-            self.trades[pair_nm] = {symbol: []}
-        if symbol not in self.trades[pair_nm]:
-            self.trades[pair_nm][symbol] = []
-        self.trades[pair_nm][symbol].append((action, price, disequilibrium, scaled_disequilibrium, timestamp))
-
-    def add_outstanding_position(self, position: Dict[str, Any]):
-        """Add an outstanding position to tracking."""
-        self.outstanding_positions.append(position)
-
-    def add_realized_pnl(self, realized_pnl: float):
-        """Add realized PnL to the total."""
-        self.total_realized_pnl += realized_pnl
-
-    def get_total_realized_pnl(self) -> float:
-        """Get total realized PnL."""
-        return self.total_realized_pnl
-
-    def get_outstanding_positions(self) -> List[Dict[str, Any]]:
-        """Get all outstanding positions."""
-        return self.outstanding_positions
-
-    def get_trades(self) -> Dict[str, Dict[str, Any]]:
-        """Get all trades."""
-        return self.trades
-
-    def clear_trades(self):
-        """Clear all trades (used when processing new files)."""
-        self.trades.clear()
-
-    def collect_single_day_results(self, result):
-        """Collect and process single day trading results."""
-        if result is None:
-            return
-
-        print("\n --------------  Suggested Trades ")
-        print(result)
-
-        for row in result.itertuples():
-            action = row.action
-            symbol = row.symbol
-            price = row.price
-            disequilibrium = getattr(row, 'disequilibrium', None)
-            scaled_disequilibrium = getattr(row, 'scaled_disequilibrium', None)
-            timestamp = getattr(row, 'time', None)
-            self.add_trade(
-                pair_nm=row.pair, action=action, symbol=symbol, price=price,
-                disequilibrium=disequilibrium, scaled_disequilibrium=scaled_disequilibrium,
-                timestamp=timestamp
-            )
-
-    def print_single_day_results(self):
-        """Print single day results summary."""
-        for pair, symbols in self.trades.items():
-            print(f"\n--- {pair} ---")
-            for symbol, trades in symbols.items():
-                for trade_data in trades:
-                    if len(trade_data) >= 2:
-                        side, price = trade_data[:2]
-                        print(f"{symbol} {side} at ${price}")
-
-    def print_results_summary(self, all_results):
-        """Print summary of all processed files."""
-        print("\n====== Summary of All Processed Files ======")
-        for filename, data in all_results.items():
-            trade_count = sum(
-                len(trades)
-                for symbol_trades in data["trades"].values()
-                for trades in symbol_trades.values()
-            )
-            print(f"{filename}: {trade_count} trades")
-
-    def calculate_returns(self, all_results: Dict):
-        """Calculate and print returns by day and pair."""
-        print("\n====== Returns By Day and Pair ======")
-
-        for filename, data in all_results.items():
-            day_return = 0
-            print(f"\n--- {filename} ---")
-
-            # Process each pair
-            for pair, symbols in data["trades"].items():
-                pair_return = 0
-                pair_trades = []
-
-                # Calculate individual symbol returns in the pair
-                for symbol, trades in symbols.items():
-                    if len(trades) >= 2:  # Need at least entry and exit
-                        # Get entry and exit trades - handle both old and new tuple formats
-                        if len(trades[0]) == 2:  # Old format: (action, price)
-                            entry_action, entry_price = trades[0]
-                            exit_action, exit_price = trades[1]
-                            open_disequilibrium = None
-                            open_scaled_disequilibrium = None
-                            close_disequilibrium = None
-                            close_scaled_disequilibrium = None
-                        else:  # New format: (action, price, disequilibrium, scaled_disequilibrium, timestamp)
-                            entry_action, entry_price = trades[0][:2]
-                            exit_action, exit_price = trades[1][:2]
-                            open_disequilibrium = trades[0][2] if len(trades[0]) > 2 else None
-                            open_scaled_disequilibrium = trades[0][3] if len(trades[0]) > 3 else None
-                            close_disequilibrium = trades[1][2] if len(trades[1]) > 2 else None
-                            close_scaled_disequilibrium = trades[1][3] if len(trades[1]) > 3 else None
-
-                        # Calculate return based on action
-                        symbol_return = 0
-                        if entry_action == "BUY" and exit_action == "SELL":
-                            # Long position
-                            symbol_return = (exit_price - entry_price) / entry_price * 100
-                        elif entry_action == "SELL" and exit_action == "BUY":
-                            # Short position
-                            symbol_return = (entry_price - exit_price) / entry_price * 100
-
-                        pair_trades.append(
-                            (
-                                symbol,
-                                entry_action,
-                                entry_price,
-                                exit_action,
-                                exit_price,
-                                symbol_return,
-                                open_scaled_disequilibrium,
-                                close_scaled_disequilibrium,
-                            )
-                        )
-                        pair_return += symbol_return
-
-                # Print pair returns with disequilibrium information
-                if pair_trades:
-                    print(f"  {pair}:")
-                    for (
-                        symbol,
-                        entry_action,
-                        entry_price,
-                        exit_action,
-                        exit_price,
-                        symbol_return,
-                        open_scaled_disequilibrium,
-                        close_scaled_disequilibrium,
-                    ) in pair_trades:
-                        disequil_info = ""
-                        if open_scaled_disequilibrium is not None and close_scaled_disequilibrium is not None:
-                            disequil_info = f" | Open Dis-eq: {open_scaled_disequilibrium:.2f}, Close Dis-eq: {close_scaled_disequilibrium:.2f}"
-                        
-                        print(
-                            f"    {symbol}: {entry_action} @ ${entry_price:.2f}, {exit_action} @ ${exit_price:.2f}, Return: {symbol_return:.2f}%{disequil_info}"
-                        )
-                    print(f"    Pair Total Return: {pair_return:.2f}%")
-                    day_return += pair_return
-
-            # Print day total return and add to global realized PnL
-            if day_return != 0:
-                print(f"  Day Total Return: {day_return:.2f}%")
-                self.add_realized_pnl(day_return)
-
-    def print_outstanding_positions(self):
-        """Print all outstanding positions with share quantities and current values."""
-        if not self.get_outstanding_positions():
-            print("\n====== NO OUTSTANDING POSITIONS ======")
-            return
-
-        print(f"\n====== OUTSTANDING POSITIONS ======")
-        print(
-            f"{'Pair':<15}"
-            f" {'Symbol':<10}"
-            f" {'Side':<4}"
-            f" {'Shares':<10}"
-            f" {'Open $':<8}"
-            f" {'Current $':<10}"
-            f" {'Value $':<12}"
-            f" {'Disequilibrium':<15}"
-        )
-        print("-" * 100)
-
-        total_value = 0.0
-
-        for pos in self.get_outstanding_positions():
-            # Print position A
-            print(
-                f"{pos['pair']:<15}"
-                f" {pos['symbol_a']:<10}"
-                f" {pos['side_a']:<4}"
-                f" {pos['shares_a']:<10.2f}"
-                f" {pos['open_px_a']:<8.2f}"
-                f" {pos['current_px_a']:<10.2f}"
-                f" {pos['current_value_a']:<12.2f}"
-                f" {'':<15}"
-            )
-
-            # Print position B
-            print(
-                f"{'':<15}"
-                f" {pos['symbol_b']:<10}"
-                f" {pos['side_b']:<4}"
-                f" {pos['shares_b']:<10.2f}"
-                f" {pos['open_px_b']:<8.2f}"
-                f" {pos['current_px_b']:<10.2f}"
-                f" {pos['current_value_b']:<12.2f}"
-            )
-
-            # Print pair totals with disequilibrium info
-            print(
-                f"{'':<15}"
-                f" {'PAIR TOTAL':<10}"
-                f" {'':<4}"
-                f" {'':<10}"
-                f" {'':<8}"
-                f" {'':<10}"
-                f" {pos['total_current_value']:<12.2f}"
-            )
-
-            # Print disequilibrium details
-            print(
-                f"{'':<15}"
-                f" {'DISEQUIL':<10}"
-                f" {'':<4}"
-                f" {'':<10}"
-                f" {'':<8}"
-                f" {'':<10}"
-                f" Raw: {pos['current_disequilibrium']:<6.4f}"
-                f" Scaled: {pos['current_scaled_disequilibrium']:<6.4f}"
-            )
-
-            print("-" * 100)
-
-            total_value += pos["total_current_value"]
-
-        print(f"{'TOTAL OUTSTANDING VALUE':<80} ${total_value:<12.2f}")
-
-    def print_grand_totals(self):
-        """Print grand totals across all pairs."""
-        print(f"\n====== GRAND TOTALS ACROSS ALL PAIRS ======")
-        print(f"Total Realized PnL: {self.get_total_realized_pnl():.2f}%")
-
-    def handle_outstanding_position(self, pair, pair_result_df, last_row_index,
-                                  open_side_a, open_side_b, open_px_a, open_px_b,
-                                  open_tstamp):
-        """
-        Handle calculation and tracking of outstanding positions when no close signal is found.
-
-        Args:
-            pair: TradingPair object
-            pair_result_df: DataFrame with pair results
-            last_row_index: Index of the last row in the data
-            open_side_a, open_side_b: Trading sides for symbols A and B
-            open_px_a, open_px_b: Opening prices for symbols A and B
-            open_tstamp: Opening timestamp
-        """
-        if pair_result_df is None or pair_result_df.empty:
-            return 0, 0, 0
-
-        last_row = pair_result_df.loc[last_row_index]
-        last_tstamp = last_row["tstamp"]
-        colname_a, colname_b = pair.colnames()
-        last_px_a = last_row[colname_a]
-        last_px_b = last_row[colname_b]
-
-        # Calculate share quantities based on funding per pair
-        # Split funding equally between the two positions
-        funding_per_position = self.config["funding_per_pair"] / 2
-        shares_a = funding_per_position / open_px_a
-        shares_b = funding_per_position / open_px_b
-
-        # Calculate current position values (shares * current price)
-        current_value_a = shares_a * last_px_a
-        current_value_b = shares_b * last_px_b
-        total_current_value = current_value_a + current_value_b
-
-        # Get disequilibrium information
-        current_disequilibrium = last_row["disequilibrium"]
-        current_scaled_disequilibrium = last_row["scaled_disequilibrium"]
-
-        # Store outstanding positions
-        self.add_outstanding_position(
-            {
-                "pair": str(pair),
-                "symbol_a": pair.symbol_a_,
-                "symbol_b": pair.symbol_b_,
-                "side_a": open_side_a,
-                "side_b": open_side_b,
-                "shares_a": shares_a,
-                "shares_b": shares_b,
-                "open_px_a": open_px_a,
-                "open_px_b": open_px_b,
-                "current_px_a": last_px_a,
-                "current_px_b": last_px_b,
-                "current_value_a": current_value_a,
-                "current_value_b": current_value_b,
-                "total_current_value": total_current_value,
-                "open_time": open_tstamp,
-                "last_time": last_tstamp,
-                "current_abs_term": current_scaled_disequilibrium,
-                "current_disequilibrium": current_disequilibrium,
-                "current_scaled_disequilibrium": current_scaled_disequilibrium,
-            }
-        )
-
-        # Print position details
-        print(f"{pair}: NO CLOSE SIGNAL FOUND - Position held until end of session")
-        print(f"  Open: {open_tstamp} | Last: {last_tstamp}")
-        print(f"  {pair.symbol_a_}: {open_side_a} {shares_a:.2f} shares @ ${open_px_a:.2f} -> ${last_px_a:.2f} | Value: ${current_value_a:.2f}")
-        print(f"  {pair.symbol_b_}: {open_side_b} {shares_b:.2f} shares @ ${open_px_b:.2f} -> ${last_px_b:.2f} | Value: ${current_value_b:.2f}")
-        print(f"  Total Value: ${total_current_value:.2f}")
-        print(f"  Disequilibrium: {current_disequilibrium:.4f} | Scaled: {current_scaled_disequilibrium:.4f}")
-
-        return current_value_a, current_value_b, total_current_value

src/strategies.py

@@ -1,420 +0,0 @@
-from abc import ABC, abstractmethod
-from enum import Enum
-
-from typing import Dict, Optional, cast
-
-import pandas as pd  # type: ignore[import]
-
-from tools.trading_pair import TradingPair
-from results import BacktestResult
-
-NanoPerMin = 1e9
-
-class PairsTradingStrategy(ABC):
-    TRADES_COLUMNS = [
-        "time",
-        "action",
-        "symbol",
-        "price",
-        "disequilibrium",
-        "scaled_disequilibrium",
-        "pair",
-    ]
-    @abstractmethod
-    def run_pair(self, config: Dict, pair: TradingPair, bt_result: BacktestResult) -> Optional[pd.DataFrame]:
-        ...
-        
-    @abstractmethod
-    def reset(self):
-        ...
-
-class StaticFitStrategy(PairsTradingStrategy):
-
-    def run_pair(self, config: Dict, pair: TradingPair, bt_result: BacktestResult) -> Optional[pd.DataFrame]: # abstractmethod
-        pair.get_datasets(training_minutes=config["training_minutes"])
-        try:
-            is_cointegrated = pair.train_pair()
-            if not is_cointegrated:
-                print(f"{pair} IS NOT COINTEGRATED")
-                return None
-        except Exception as e:
-            print(f"{pair}: Training failed: {str(e)}")
-            return None
-
-        try:
-            pair.predict()
-        except Exception as e:
-            print(f"{pair}: Prediction failed: {str(e)}")
-            return None
-
-        pair_trades = self.create_trading_signals(pair=pair, config=config, result=bt_result)
-
-        return pair_trades
-
-    def create_trading_signals(self, pair: TradingPair, config: Dict, result: BacktestResult) -> pd.DataFrame:
-        beta = pair.vecm_fit_.beta  # type: ignore
-        colname_a, colname_b = pair.colnames()
-
-        predicted_df = pair.predicted_df_
-
-        open_threshold = config["dis-equilibrium_open_trshld"]
-        close_threshold = config["dis-equilibrium_close_trshld"]
-
-        # Iterate through the testing dataset to find the first trading opportunity
-        open_row_index = None
-        for row_idx in range(len(predicted_df)):
-            curr_disequilibrium = predicted_df["scaled_disequilibrium"][row_idx]
-
-            # Check if current row has sufficient disequilibrium (not near-zero)
-            if curr_disequilibrium >= open_threshold:
-                open_row_index = row_idx
-                break
-
-        # If no row with sufficient disequilibrium found, skip this pair
-        if open_row_index is None:
-            print(f"{pair}: Insufficient disequilibrium in testing dataset. Skipping.")
-            return pd.DataFrame()
-
-        # Look for close signal starting from the open position
-        trading_signals_df = (
-            predicted_df["scaled_disequilibrium"][open_row_index:] < close_threshold
-        )
-
-        # Adjust indices to account for the offset from open_row_index
-        close_row_index = None
-        for idx, value in trading_signals_df.items():
-            if value:
-                close_row_index = idx
-                break
-
-        open_row = predicted_df.loc[open_row_index]
-        open_tstamp = open_row["tstamp"]
-        open_disequilibrium = open_row["disequilibrium"]
-        open_scaled_disequilibrium = open_row["scaled_disequilibrium"]
-        open_px_a = open_row[f"{colname_a}"]
-        open_px_b = open_row[f"{colname_b}"]
-
-        abs_beta = abs(beta[1])
-        pred_px_b = predicted_df.loc[open_row_index][f"{colname_b}_pred"]
-        pred_px_a = predicted_df.loc[open_row_index][f"{colname_a}_pred"]
-
-        if pred_px_b * abs_beta - pred_px_a > 0:
-            open_side_a = "BUY"
-            open_side_b = "SELL"
-            close_side_a = "SELL"
-            close_side_b = "BUY"
-        else:
-            open_side_b = "BUY"
-            open_side_a = "SELL"
-            close_side_b = "SELL"
-            close_side_a = "BUY"
-
-        # If no close signal found, print position and unrealized PnL
-        if close_row_index is None:
-
-            last_row_index = len(predicted_df) - 1
-
-            # Use the new method from BacktestResult to handle outstanding positions
-            result.handle_outstanding_position(
-                pair=pair,
-                pair_result_df=predicted_df,
-                last_row_index=last_row_index,
-                open_side_a=open_side_a,
-                open_side_b=open_side_b,
-                open_px_a=open_px_a,
-                open_px_b=open_px_b,
-                open_tstamp=open_tstamp,
-            )
-
-            # Return only open trades (no close trades)
-            trd_signal_tuples = [
-                (
-                    open_tstamp,
-                    open_side_a,
-                    pair.symbol_a_,
-                    open_px_a,
-                    open_disequilibrium,
-                    open_scaled_disequilibrium,
-                    pair,
-                ),
-                (
-                    open_tstamp,
-                    open_side_b,
-                    pair.symbol_b_,
-                    open_px_b,
-                    open_disequilibrium,
-                    open_scaled_disequilibrium,
-                    pair,
-                ),
-            ]
-        else:
-            # Close signal found - create complete trade
-            close_row = predicted_df.loc[close_row_index]
-            close_tstamp = close_row["tstamp"]
-            close_disequilibrium = close_row["disequilibrium"]
-            close_scaled_disequilibrium = close_row["scaled_disequilibrium"]
-            close_px_a = close_row[f"{colname_a}"]
-            close_px_b = close_row[f"{colname_b}"]
-
-            print(f"{pair}: Close signal found at index {close_row_index}")
-
-            trd_signal_tuples = [
-                (
-                    open_tstamp,
-                    open_side_a,
-                    pair.symbol_a_,
-                    open_px_a,
-                    open_disequilibrium,
-                    open_scaled_disequilibrium,
-                    pair,
-                ),
-                (
-                    open_tstamp,
-                    open_side_b,
-                    pair.symbol_b_,
-                    open_px_b,
-                    open_disequilibrium,
-                    open_scaled_disequilibrium,
-                    pair,
-                ),
-                (
-                    close_tstamp,
-                    close_side_a,
-                    pair.symbol_a_,
-                    close_px_a,
-                    close_disequilibrium,
-                    close_scaled_disequilibrium,
-                    pair,
-                ),
-                (
-                    close_tstamp,
-                    close_side_b,
-                    pair.symbol_b_,
-                    close_px_b,
-                    close_disequilibrium,
-                    close_scaled_disequilibrium,
-                    pair,
-                ),
-            ]
-
-        # Add tuples to data frame
-        return pd.DataFrame(
-            trd_signal_tuples,
-            columns=self.TRADES_COLUMNS,  # type: ignore
-        )
-    
-    def reset(self):
-        pass
-
-class PairState(Enum):
-    INITIAL = 1
-    OPEN = 2
-    CLOSED = 3
-
-class SlidingFitStrategy(PairsTradingStrategy):
-    def __init__(self):
-        super().__init__()
-        self.curr_training_start_idx_ = 0
-
-    def run_pair(self, config: Dict, pair: TradingPair, bt_result: BacktestResult) -> Optional[pd.DataFrame]:
-        print(f"***{pair}*** STARTING....")
-
-        pair.user_data_['state'] = PairState.INITIAL
-        pair.user_data_["trades"] = pd.DataFrame(columns=self.TRADES_COLUMNS)  # type: ignore
-        pair.user_data_["is_cointegrated"] = False
-
-        open_threshold = config["dis-equilibrium_open_trshld"]
-        close_threshold = config["dis-equilibrium_open_trshld"]
-
-        training_minutes = config["training_minutes"]
-        while True:
-            print(self.curr_training_start_idx_, end='\r')
-            pair.get_datasets(
-                training_minutes=training_minutes,
-                training_start_index=self.curr_training_start_idx_,
-                testing_size=1
-            )
-
-            if len(pair.training_df_) < training_minutes:  # type: ignore
-                print(f"{pair}:  {self.curr_training_start_idx_} Not enough training data. Completing the job.")
-                if pair.user_data_["state"] == PairState.OPEN:
-                    print(f"{pair}:  {self.curr_training_start_idx_} Position is not closed.")
-                    # outstanding positions
-                    # last_row_index = self.curr_training_start_idx_ + training_minutes
-
-                    bt_result.handle_outstanding_position(
-                        pair=pair,
-                        pair_result_df=pair.predicted_df_,
-                        last_row_index=0,
-                        open_side_a=pair.user_data_["open_side_a"],
-                        open_side_b=pair.user_data_["open_side_b"],
-                        open_px_a=pair.user_data_["open_px_a"],
-                        open_px_b=pair.user_data_["open_px_b"],
-                        open_tstamp=pair.user_data_["open_tstamp"],
-                    )
-                break
-
-            try:
-                is_cointegrated = pair.train_pair()
-            except Exception as e:
-                raise RuntimeError(f"{pair}: Training failed: {str(e)}") from e
-
-            if pair.user_data_["is_cointegrated"] != is_cointegrated:
-                    pair.user_data_["is_cointegrated"] = is_cointegrated
-                    if not is_cointegrated:
-                        if pair.user_data_["state"] == PairState.OPEN:
-                            print(f"{pair}  {self.curr_training_start_idx_} LOST COINTEGRATION. Consider closing positions...")
-                        else:
-                            print(f"{pair} {self.curr_training_start_idx_} IS NOT COINTEGRATED. Moving on")
-                    else:
-                        print('*' * 80)
-                        print(f"Pair {pair} ({self.curr_training_start_idx_}) IS COINTEGRATED")
-                        print('*' * 80)
-            if not is_cointegrated:
-                self.curr_training_start_idx_ += 1
-                continue
-
-            try:
-                pair.predict()
-            except Exception as e:
-                raise RuntimeError(f"{pair}: Prediction failed: {str(e)}") from e
-
-            if pair.user_data_["state"] == PairState.INITIAL:
-
-                open_trades = self._get_open_trades(pair, open_threshold=open_threshold)
-                if open_trades is not None:
-                    pair.user_data_["trades"] = open_trades
-                    pair.user_data_["state"] = PairState.OPEN
-            elif pair.user_data_["state"] == PairState.OPEN:
-                close_trades = self._get_close_trades(pair, close_threshold=close_threshold)
-                if close_trades is not None:
-                    pair.user_data_["trades"] = pd.concat([pair.user_data_["trades"], close_trades], ignore_index=True)
-                    pair.user_data_["state"] = PairState.CLOSED
-                    break
-
-            self.curr_training_start_idx_ += 1
-
-        print(f"***{pair}*** FINISHED ... {len(pair.user_data_['trades'])}")
-        return pair.user_data_["trades"]
-
-    def _get_open_trades(self, pair: TradingPair, open_threshold: float) -> Optional[pd.DataFrame]:
-        colname_a, colname_b = pair.colnames()
-
-        predicted_df = pair.predicted_df_
-        
-        # Check if we have any data to work with
-        if len(predicted_df) == 0:
-            return None
-
-        open_row = predicted_df.iloc[0]
-        open_tstamp = open_row["tstamp"]
-        open_disequilibrium = open_row["disequilibrium"]
-        open_scaled_disequilibrium = open_row["scaled_disequilibrium"]
-        open_px_a = open_row[f"{colname_a}"]
-        open_px_b = open_row[f"{colname_b}"]
-
-        if open_scaled_disequilibrium < open_threshold:
-            return None
-
-        # creating the trades
-        if open_disequilibrium > 0:
-            open_side_a = "SELL"
-            open_side_b = "BUY"
-            close_side_a = "BUY"
-            close_side_b = "SELL"
-        else:
-            open_side_a = "BUY"
-            open_side_b = "SELL"
-            close_side_a = "SELL"
-            close_side_b = "BUY"
-
-        # save closing sides
-        pair.user_data_["open_side_a"] = open_side_a
-        pair.user_data_["open_side_b"] = open_side_b
-        pair.user_data_["open_px_a"] = open_px_a
-        pair.user_data_["open_px_b"] = open_px_b
-
-        pair.user_data_["open_tstamp"] = open_tstamp
-
-        pair.user_data_["close_side_a"] = close_side_a
-        pair.user_data_["close_side_b"] = close_side_b
-
-
-        # create opening trades
-        trd_signal_tuples = [
-            (
-                open_tstamp,
-                open_side_a,
-                pair.symbol_a_,
-                open_px_a,
-                open_disequilibrium,
-                open_scaled_disequilibrium,
-                pair,
-            ),
-            (
-                open_tstamp,
-                open_side_b,
-                pair.symbol_b_,
-                open_px_b,
-                open_disequilibrium,
-                open_scaled_disequilibrium,
-                pair,
-            ),
-        ]
-        return pd.DataFrame(
-            trd_signal_tuples,
-            columns=self.TRADES_COLUMNS,  # type: ignore
-        )
-
-    def _get_close_trades(self, pair: TradingPair, close_threshold: float) -> Optional[pd.DataFrame]:
-        colname_a, colname_b = pair.colnames()
-
-        # Check if we have any data to work with
-        if len(pair.predicted_df_) == 0:
-            return None
-
-        close_row = pair.predicted_df_.iloc[0]
-        close_tstamp = close_row["tstamp"]
-        close_disequilibrium = close_row["disequilibrium"]
-        close_scaled_disequilibrium = close_row["scaled_disequilibrium"]
-        close_px_a = close_row[f"{colname_a}"]
-        close_px_b = close_row[f"{colname_b}"]
-
-        close_side_a = pair.user_data_["close_side_a"]
-        close_side_b = pair.user_data_["close_side_b"]
-
-        if close_scaled_disequilibrium > close_threshold:
-            return None
-
-        trd_signal_tuples = [
-            (
-                close_tstamp,
-                close_side_a,
-                pair.symbol_a_,
-                close_px_a,
-                close_disequilibrium,
-                close_scaled_disequilibrium,
-                pair,
-            ),
-            (
-                close_tstamp,
-                close_side_b,
-                pair.symbol_b_,
-                close_px_b,
-                close_disequilibrium,
-                close_scaled_disequilibrium,
-                pair,
-            ),
-        ]
-
-        # Add tuples to data frame
-        return pd.DataFrame(
-            trd_signal_tuples,
-            columns=self.TRADES_COLUMNS,  # type: ignore
-        )
-
-    def reset(self):
-        self.curr_training_start_idx_ = 0
-
-
-

src/tools/data_loader.py

@@ -1,138 +0,0 @@
-import sqlite3
-from typing import Dict, List, cast
-import pandas as pd
-
-
-
-def load_sqlite_to_dataframe(db_path, query):
-    try:
-        conn = sqlite3.connect(db_path)
-
-        df = pd.read_sql_query(query, conn)
-        return df
-    except sqlite3.Error as excpt:
-        print(f"SQLite error: {excpt}")
-        raise
-    except Exception as excpt:
-        print(f"Error: {excpt}")
-        raise Exception() from excpt
-    finally:
-        if "conn" in locals():
-            conn.close()
-
-
-def convert_time_to_UTC(value: str, timezone: str) -> str:
-
-    from zoneinfo import ZoneInfo
-    from datetime import datetime
-
-    # Parse it to naive datetime object
-    local_dt = datetime.strptime(value, "%Y-%m-%d %H:%M:%S")
-
-    zinfo = ZoneInfo(timezone)
-    result: datetime = local_dt.replace(tzinfo=zinfo).astimezone(ZoneInfo("UTC"))
-
-    return result.strftime("%Y-%m-%d %H:%M:%S")
-
-
-def load_market_data(datafile: str, config: Dict) -> pd.DataFrame:
-    from tools.data_loader import load_sqlite_to_dataframe
-
-    instrument_ids = [
-        '"' + config["instrument_id_pfx"] + instrument + '"'
-        for instrument in config["instruments"]
-    ]
-    security_type = config["security_type"]
-    exchange_id = config["exchange_id"]
-
-    query = "select"
-    if security_type == "CRYPTO":
-        query += " strftime('%Y-%m-%d %H:%M:%S', tstamp_ns/1000000000, 'unixepoch') as tstamp"
-        query += ", tstamp as time_ns"
-    else:
-        query += " tstamp"
-        query += ", tstamp_ns as time_ns"
-
-    query += f", substr(instrument_id, {len(config['instrument_id_pfx']) + 1}) as symbol"
-    query += ", open"
-    query += ", high"
-    query += ", low"
-    query += ", close"
-    query += ", volume"
-    query += ", num_trades"
-    query += ", vwap"
-
-    query += f" from {config['db_table_name']}"
-    query += f" where exchange_id ='{exchange_id}'"
-    query += f" and instrument_id in ({','.join(instrument_ids)})"
-
-    df = load_sqlite_to_dataframe(db_path=datafile, query=query)
-
-    # Trading Hours
-    date_str = df["tstamp"][0][0:10]
-    trading_hours = config["trading_hours"]
-
-    start_time = convert_time_to_UTC(
-        f"{date_str} {trading_hours['begin_session']}", trading_hours["timezone"]
-    )
-    end_time = convert_time_to_UTC(
-        f"{date_str} {trading_hours['end_session']}", trading_hours["timezone"]
-    )
-
-    # Perform boolean selection
-    df = df[(df["tstamp"] >= start_time) & (df["tstamp"] <= end_time)]
-    df["tstamp"] = pd.to_datetime(df["tstamp"])
-
-    return cast(pd.DataFrame, df)
-
-
-def get_available_instruments_from_db(datafile: str, config: Dict) -> List[str]:
-    """
-    Auto-detect available instruments from the database by querying distinct instrument_id values.
-    Returns instruments without the configured prefix.
-    """
-    try:
-        conn = sqlite3.connect(datafile)
-
-        # Build exclusion list with full instrument_ids
-        exclude_instruments = config.get("exclude_instruments", [])
-        prefix = config.get("instrument_id_pfx", "")
-        exclude_instrument_ids = [f"{prefix}{inst}" for inst in exclude_instruments]
-        
-        # Query to get distinct instrument_ids
-        query = f"""
-        SELECT DISTINCT instrument_id 
-        FROM {config['db_table_name']} 
-        WHERE exchange_id = ?
-        """
-        
-        # Add exclusion clause if there are instruments to exclude
-        if exclude_instrument_ids:
-            placeholders = ','.join(['?' for _ in exclude_instrument_ids])
-            query += f" AND instrument_id NOT IN ({placeholders})"
-            cursor = conn.execute(query, (config["exchange_id"],) + tuple(exclude_instrument_ids))
-        else:
-            cursor = conn.execute(query, (config["exchange_id"],))
-        instrument_ids = [row[0] for row in cursor.fetchall()]
-        conn.close()
-
-        # Remove the configured prefix to get instrument symbols
-        instruments = []
-        for instrument_id in instrument_ids:
-            if instrument_id.startswith(prefix):
-                symbol = instrument_id[len(prefix) :]
-                instruments.append(symbol)
-            else:
-                instruments.append(instrument_id)
-
-        return sorted(instruments)
-
-    except Exception as e:
-        print(f"Error auto-detecting instruments from {datafile}: {str(e)}")
-        return []
-
-
-# if __name__ == "__main__":
-#     df1 = load_sqlite_to_dataframe(sys.argv[1], table_name="md_1min_bars")
-
-#     print(df1)

src/tools/trading_pair.py

@@ -1,170 +0,0 @@
-
-from typing import Any, Dict, List, Optional
-import pandas as pd  #type:ignore
-from statsmodels.tsa.vector_ar.vecm import VECM #type:ignore
-
-class TradingPair:
-    market_data_: pd.DataFrame
-    symbol_a_: str
-    symbol_b_: str
-    price_column_: str
-
-    training_mu_: Optional[float]
-    training_std_: Optional[float]
-
-    training_df_: Optional[pd.DataFrame]
-    testing_df_: Optional[pd.DataFrame]
-
-    vecm_fit_: Optional[VECM]
-
-    user_data_: Dict[str, Any]
-
-    def __init__(self, market_data: pd.DataFrame, symbol_a: str, symbol_b: str, price_column: str):
-        self.symbol_a_ = symbol_a
-        self.symbol_b_ = symbol_b
-        self.price_column_ = price_column
-        self.market_data_ = self._transform_dataframe(market_data)[["tstamp"] + self.colnames()]
-
-        self.training_mu_ = None
-        self.training_std_ = None
-        self.training_df_ = None
-        self.testing_df_ = None
-        self.vecm_fit_ = None
-
-        self.user_data_ = {}
-
-    def _transform_dataframe(self, df: pd.DataFrame):
-        # Select only the columns we need
-        df_selected = df[["tstamp", "symbol", self.price_column_]]
-
-        # Start with unique timestamps
-        result_df: pd.DataFrame = pd.DataFrame(df_selected["tstamp"]).drop_duplicates().reset_index(drop=True)
-
-        # For each unique symbol, add a corresponding close price column
-
-        symbols = df_selected["symbol"].unique()
-        for symbol in symbols:
-            # Filter rows for this symbol
-            df_symbol = df_selected[df_selected["symbol"] == symbol].reset_index(drop=True)
-
-            # Create column name like "close-COIN"
-            new_price_column = f"{self.price_column_}_{symbol}"
-
-            # Create temporary dataframe with timestamp and price
-            temp_df = pd.DataFrame({
-                "tstamp": df_symbol["tstamp"],
-                new_price_column: df_symbol[self.price_column_]
-            })
-
-            # Join with our result dataframe
-            result_df = pd.merge(result_df, temp_df, on="tstamp", how="left")
-            result_df = result_df.reset_index(drop=True) # do not dropna() since irrelevant symbol would affect dataset
-
-        return result_df
-    def get_datasets(self, training_minutes: int, training_start_index: int = 0, testing_size: Optional[int] = None) -> None:
-
-        testing_start_index = training_start_index + training_minutes
-        self.training_df_ = self.market_data_.iloc[training_start_index:testing_start_index, :].copy()
-        self.training_df_ = self.training_df_.dropna().reset_index(drop=True)
-
-        testing_start_index = training_start_index + training_minutes
-        if testing_size is None:
-            self.testing_df_ = self.market_data_.iloc[testing_start_index:, :].copy()
-        else:
-            self.testing_df_ = self.market_data_.iloc[testing_start_index:testing_start_index + testing_size, :].copy()
-        self.testing_df_ = self.testing_df_.dropna().reset_index(drop=True)
-
-    def colnames(self) -> List[str]:
-        return [f"{self.price_column_}_{self.symbol_a_}", f"{self.price_column_}_{self.symbol_b_}"]
-
-    def fit_VECM(self):
-        vecm_df = self.training_df_[self.colnames()].reset_index(drop=True)
-        vecm_model = VECM(vecm_df, coint_rank=1)
-        vecm_fit = vecm_model.fit()
-
-        # URGENT check beta and alpha
-
-        # Check if the model converged properly
-        if not hasattr(vecm_fit, "beta") or vecm_fit.beta is None:
-            print(f"{self}: VECM model failed to converge properly")
-
-        self.vecm_fit_ = vecm_fit
-        # print(f"{self}: beta={self.vecm_fit_.beta} alpha={self.vecm_fit_.alpha}"  )
-        # print(f"{self}: {self.vecm_fit_.summary()}")
-        pass
-
-    def check_cointegration_johansen(self):
-        from statsmodels.tsa.vector_ar.vecm import coint_johansen
-        df = self.training_df_[self.colnames()].reset_index(drop=True)
-        result = coint_johansen(df, det_order=0, k_ar_diff=1)
-        print(f"{self}: lr1={result.lr1[0]} cvt={result.cvt[0, 1]}.")
-        is_cointegrated = result.lr1[0] > result.cvt[0, 1]
-
-        return is_cointegrated
-
-
-    def check_cointegration(self):
-        from statsmodels.tsa.stattools import coint
-        col1, col2 = self.colnames()
-        series1 = self.training_df_[col1].reset_index(drop=True)
-        series2 = self.training_df_[col2].reset_index(drop=True)
-
-        # Run Engle-Granger cointegration test
-        pvalue = coint(series1, series2)[1]
-        # Define cointegration if p-value < 0.05 (i.e., reject null of no cointegration)
-        is_cointegrated = pvalue < 0.05
-        print(f"{self}: is_cointegrated={is_cointegrated} pvalue={pvalue}")
-        return is_cointegrated
-
-
-    def train_pair(self) -> bool:
-        is_cointegrated = self.check_cointegration()
-        if not is_cointegrated:
-            return False
-            pass
-
-        # print('*' * 80 + '\n' + f"**************** {self} IS COINTEGRATED ****************\n" + '*' * 80)
-        self.fit_VECM()
-        assert self.training_df_ is not None and self.vecm_fit_ is not None
-        diseq_series = self.training_df_[self.colnames()] @ self.vecm_fit_.beta
-        self.training_mu_ = diseq_series.mean().iloc[0]
-        self.training_std_ = diseq_series.std().iloc[0]
-
-        self.training_df_["dis-equilibrium"] = self.training_df_[self.colnames()] @ self.vecm_fit_.beta
-        # Normalize the dis-equilibrium
-        self.training_df_["scaled_dis-equilibrium"] = (
-            diseq_series - self.training_mu_
-        ) / self.training_std_
-
-        return True
-
-    def predict(self) -> None:
-        assert self.testing_df_ is not None
-        assert self.vecm_fit_ is not None
-        predicted_prices = self.vecm_fit_.predict(steps=len(self.testing_df_))
-
-        # Convert prediction to a DataFrame for readability
-        # predicted_df =
-
-        self.predicted_df_ = pd.merge(
-            self.testing_df_.reset_index(drop=True),
-            pd.DataFrame(predicted_prices, columns=self.colnames()),
-            left_index=True,
-            right_index=True,
-            suffixes=("", "_pred"),
-        ).dropna()
-
-        self.predicted_df_["disequilibrium"] = self.predicted_df_[self.colnames()] @ self.vecm_fit_.beta
-
-        self.predicted_df_["scaled_disequilibrium"] = (
-            abs(self.predicted_df_["disequilibrium"] - self.training_mu_) / self.training_std_
-        )
-
-        # Reset index to ensure proper indexing
-        self.predicted_df_ = self.predicted_df_.reset_index()
-        return self.predicted_df_
-
-
-    def __repr__(self) ->str:
-        return f"{self.symbol_a_} & {self.symbol_b_}"
-

src/utils/db_inspector.py

@@ -1,169 +0,0 @@
-#!/usr/bin/env python3
-"""
-Database inspector utility for pairs trading results database.
-Provides functionality to view all tables and their contents.
-"""
-
-import sqlite3
-import sys
-import json
-import os
-from typing import List, Dict, Any
-
-def list_tables(db_path: str) -> List[str]:
-    """List all tables in the database."""
-    conn = sqlite3.connect(db_path)
-    cursor = conn.cursor()
-    
-    cursor.execute("""
-        SELECT name FROM sqlite_master 
-        WHERE type='table' 
-        ORDER BY name
-    """)
-    
-    tables = [row[0] for row in cursor.fetchall()]
-    conn.close()
-    return tables
-
-def view_table_schema(db_path: str, table_name: str):
-    """View the schema of a specific table."""
-    conn = sqlite3.connect(db_path)
-    cursor = conn.cursor()
-    
-    cursor.execute(f"PRAGMA table_info({table_name})")
-    columns = cursor.fetchall()
-    
-    print(f"\nTable: {table_name}")
-    print("-" * 50)
-    print("Column Name".ljust(20) + "Type".ljust(15) + "Not Null".ljust(10) + "Default")
-    print("-" * 50)
-    
-    for col in columns:
-        cid, name, type_, not_null, default_value, pk = col
-        print(f"{name}".ljust(20) + f"{type_}".ljust(15) + f"{bool(not_null)}".ljust(10) + f"{default_value or ''}")
-    
-    conn.close()
-
-def view_config_table(db_path: str, limit: int = 10):
-    """View entries from the config table."""
-    conn = sqlite3.connect(db_path)
-    cursor = conn.cursor()
-    
-    cursor.execute(f"""
-        SELECT id, run_timestamp, config_file_path, strategy_class, 
-               datafiles, instruments, config_json
-        FROM config 
-        ORDER BY run_timestamp DESC
-        LIMIT {limit}
-    """)
-    
-    rows = cursor.fetchall()
-    
-    if not rows:
-        print("No configuration entries found.")
-        return
-    
-    print(f"\nMost recent {len(rows)} configuration entries:")
-    print("=" * 80)
-    
-    for row in rows:
-        id, run_timestamp, config_file_path, strategy_class, datafiles, instruments, config_json = row
-        
-        print(f"ID: {id} | {run_timestamp}")
-        print(f"Config: {config_file_path} | Strategy: {strategy_class}")
-        print(f"Files: {datafiles}")
-        print(f"Instruments: {instruments}")
-        print("-" * 80)
-    
-    conn.close()
-
-def view_results_summary(db_path: str):
-    """View summary of trading results."""
-    conn = sqlite3.connect(db_path)
-    cursor = conn.cursor()
-    
-    # Get results summary
-    cursor.execute("""
-        SELECT date, COUNT(*) as trade_count, 
-               ROUND(SUM(symbol_return), 2) as total_return
-        FROM pt_bt_results 
-        GROUP BY date 
-        ORDER BY date DESC
-    """)
-    
-    results = cursor.fetchall()
-    
-    if not results:
-        print("No trading results found.")
-        return
-    
-    print(f"\nTrading Results Summary:")
-    print("-" * 50)
-    print("Date".ljust(15) + "Trades".ljust(10) + "Total Return %")
-    print("-" * 50)
-    
-    for date, trade_count, total_return in results:
-        print(f"{date}".ljust(15) + f"{trade_count}".ljust(10) + f"{total_return}")
-    
-    # Get outstanding positions summary
-    cursor.execute("""
-        SELECT COUNT(*) as position_count,
-               ROUND(SUM(unrealized_return), 2) as total_unrealized
-        FROM outstanding_positions
-    """)
-    
-    outstanding = cursor.fetchone()
-    if outstanding and outstanding[0] > 0:
-        print(f"\nOutstanding Positions: {outstanding[0]} positions")
-        print(f"Total Unrealized Return: {outstanding[1]}%")
-    
-    conn.close()
-
-def main():
-    if len(sys.argv) < 2:
-        print("Usage: python db_inspector.py <database_path> [command]")
-        print("Commands:")
-        print("  tables     - List all tables")
-        print("  schema     - Show schema for all tables")
-        print("  config     - View configuration entries")
-        print("  results    - View trading results summary")
-        print("  all        - Show everything (default)")
-        print("\nExample: python db_inspector.py results/equity.db config")
-        sys.exit(1)
-    
-    db_path = sys.argv[1]
-    command = sys.argv[2] if len(sys.argv) > 2 else "all"
-    
-    if not os.path.exists(db_path):
-        print(f"Database file not found: {db_path}")
-        sys.exit(1)
-    
-    try:
-        if command in ["tables", "all"]:
-            tables = list_tables(db_path)
-            print(f"Tables in database: {', '.join(tables)}")
-        
-        if command in ["schema", "all"]:
-            tables = list_tables(db_path)
-            for table in tables:
-                view_table_schema(db_path, table)
-        
-        if command in ["config", "all"]:
-            if "config" in list_tables(db_path):
-                view_config_table(db_path)
-            else:
-                print("Config table not found.")
-        
-        if command in ["results", "all"]:
-            if "pt_bt_results" in list_tables(db_path):
-                view_results_summary(db_path)
-            else:
-                print("Results table not found.")
-                
-    except Exception as e:
-        print(f"Error inspecting database: {str(e)}")
-        import traceback
-        traceback.print_exc()
-
-if __name__ == "__main__":
-    main()