progress

lib/cvtt/mkt_data.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+
+import argparse
+from ast import Sub
+import asyncio
+from functools import partial
+import json
+import logging
+import uuid
+from dataclasses import dataclass
+from typing import Callable, Coroutine, Dict, List, Optional
+
+from numpy.strings import str_len
+import websockets
+from websockets.asyncio.client import ClientConnection
+
+MessageTypeT = str
+SubscriptionIdT = str
+MessageT = Dict
+UrlT = str
+CallbackT = Callable[[MessageTypeT, SubscriptionIdT, MessageT], Coroutine[None, str, None]]
+
+@dataclass
+class CvttPricesSubscription:
+    id_: str
+    exchange_config_name_: str
+    instrument_id_: str
+    interval_sec_: int
+    history_depth_sec_: int
+    is_subscribed_: bool
+    is_historical_: bool
+    callback_: CallbackT
+
+    def __init__(
+        self,
+        exchange_config_name: str,
+        instrument_id: str,
+        interval_sec: int,
+        history_depth_sec: int,
+        callback: CallbackT,
+    ):
+        self.exchange_config_name_ = exchange_config_name
+        self.instrument_id_ = instrument_id
+        self.interval_sec_ = interval_sec
+        self.history_depth_sec_ = history_depth_sec
+        self.callback_ = callback
+        self.id_ = str(uuid.uuid4())
+        self.is_subscribed_ = False
+        self.is_historical_ = history_depth_sec > 0
+
+
+class CvttPricerWebSockClient:
+    # Class members with type hints
+    ws_url_: UrlT
+    websocket_: Optional[ClientConnection]
+    subscriptions_: Dict[SubscriptionIdT, CvttPricesSubscription]
+    is_connected_: bool
+    logger_: logging.Logger
+
+    def __init__(self, url: str):
+        self.ws_url_ = url
+        self.websocket_ = None
+        self.is_connected_ = False
+        self.subscriptions_ = {}
+        self.logger_ = logging.getLogger(__name__)
+        logging.basicConfig(level=logging.INFO)
+
+    async def subscribe(
+        self, subscription: CvttPricesSubscription
+    ) -> str:  # returns subscription id
+
+        if not self.is_connected_:
+            try:
+                self.logger_.info(f"Connecting to {self.ws_url_}")
+                self.websocket_ = await websockets.connect(self.ws_url_)
+                self.is_connected_ = True
+            except Exception as e:
+                self.logger_.error(f"Unable to connect to {self.ws_url_}: {str(e)}")
+                raise e
+
+        subscr_msg = {
+            "type": "subscr",
+            "id": subscription.id_,
+            "subscr_type": "MD_AGGREGATE",
+            "exchange_config_name": subscription.exchange_config_name_,
+            "instrument_id": subscription.instrument_id_,
+            "interval_sec": subscription.interval_sec_,
+        }
+        if subscription.is_historical_:
+            subscr_msg["history_depth_sec"] = subscription.history_depth_sec_
+
+        assert self.websocket_ is not None
+        await self.websocket_.send(json.dumps(subscr_msg))
+
+        response = await self.websocket_.recv()
+        response_data = json.loads(response)
+        if not await self.handle_subscription_response(subscription, response_data):
+            await self.websocket_.close()
+            self.is_connected_ = False
+            raise Exception(f"Subscription failed: {str(response)}")
+
+        self.subscriptions_[subscription.id_] = subscription
+        return subscription.id_
+
+    async def handle_subscription_response(
+        self, subscription: CvttPricesSubscription, response: dict
+    ) -> bool:
+        if response.get("type") != "subscr" or response.get("id") != subscription.id_:
+            return False
+
+        if response.get("status") == "success":
+            self.logger_.info(f"Subscription successful: {json.dumps(response)}")
+            return True
+        elif response.get("status") == "error":
+            self.logger_.error(f"Subscription failed: {response.get('reason')}")
+            return False
+        return False
+
+    async def run(self) -> None:
+        assert self.websocket_
+        try:
+            while self.is_connected_:
+                try:
+                    message = await self.websocket_.recv()
+                    message_str = (
+                        message.decode("utf-8")
+                        if isinstance(message, bytes)
+                        else message
+                    )
+                    await self.process_message(json.loads(message_str))
+                except websockets.ConnectionClosed:
+                    self.logger_.warning("Connection closed")
+                    self.is_connected_ = False
+                    break
+        except Exception as e:
+            self.logger_.error(f"Error occurred: {str(e)}")
+            self.is_connected_ = False
+            await asyncio.sleep(5)  # Wait before reconnecting
+
+    async def process_message(self, message: Dict) -> None:
+        message_type = message.get("type")
+        if message_type in ["md_aggregate", "historical_md_aggregate"]:
+            subscription_id = message.get("subscr_id")
+            if subscription_id not in self.subscriptions_:
+                self.logger_.warning(f"Unknown subscription id: {subscription_id}")
+                return
+
+            subscription = self.subscriptions_[subscription_id]
+            await subscription.callback_(message_type, subscription_id, message)
+        else:
+            self.logger_.warning(f"Unknown message type: {message.get('type')}")
+
+
+async def main() -> None:
+    async def on_message(message_type: MessageTypeT, subscr_id: SubscriptionIdT, message: Dict, instrument_id: str) -> None:
+        print(f"{message_type=} {subscr_id=} {instrument_id}")
+        if message_type == "md_aggregate":
+            aggr = message.get("md_aggregate", [])
+            print(f"[{aggr['tstmp'][:19]}] *** RLTM ***  {message}")
+        elif message_type == "historical_md_aggregate":
+            for aggr in message.get("historical_data", []):
+                print(f"[{aggr['tstmp'][:19]}] *** HIST *** {aggr}")
+        else:
+            print(f"Unknown message type: {message_type}")
+        
+    pricer_client = CvttPricerWebSockClient(
+        "ws://localhost:12346/ws"
+    )
+    await pricer_client.subscribe(CvttPricesSubscription(
+        exchange_config_name="COINBASE_AT",
+        instrument_id="PAIR-BTC-USD",
+        interval_sec=60,
+        history_depth_sec=60*60*24,
+        callback=partial(on_message, instrument_id="PAIR-BTC-USD")
+    ))
+    await pricer_client.subscribe(CvttPricesSubscription(
+        exchange_config_name="COINBASE_AT",
+        instrument_id="PAIR-ETH-USD",
+        interval_sec=60,
+        history_depth_sec=60*60*24,
+        callback=partial(on_message, instrument_id="PAIR-ETH-USD")
+    ))
+
+    await pricer_client.run() 
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lib/pt_trading/fit_methods.py

@@ -0,0 +1,419 @@
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Dict, Optional, cast
+
+import pandas as pd  # type: ignore[import]
+
+from pt_trading.results import BacktestResult
+from pt_trading.trading_pair import TradingPair
+
+NanoPerMin = 1e9
+
+class PairsTradingFitMethod(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 StaticFit(PairsTradingFitMethod):
+
+    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) -> None:
+        pass
+
+class PairState(Enum):
+    INITIAL = 1
+    OPEN = 2
+    CLOSED = 3
+
+class SlidingFit(PairsTradingFitMethod):
+    def __init__(self) -> None:
+        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:
+                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
+
+
+

lib/pt_trading/results.py

@@ -0,0 +1,777 @@
+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,
+                fit_method_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,
+    fit_method_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, fit_method_class, datafiles, instruments
+            ) VALUES (?, ?, ?, ?, ?, ?)
+        """,
+            (
+                datetime.now(),
+                config_file_path,
+                config_json,
+                fit_method_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

lib/pt_trading/trading_pair.py

@@ -0,0 +1,208 @@
+from typing import Any, Dict, List, Optional
+import pandas as pd  # type:ignore
+from statsmodels.tsa.vector_ar.vecm import VECM, VECMResults  # type:ignore
+
+
+class TradingPair:
+    market_data_: pd.DataFrame
+    symbol_a_: str
+    symbol_b_: str
+    price_column_: str
+
+    training_mu_: float
+    training_std_: float
+
+    training_df_: pd.DataFrame
+    testing_df_: pd.DataFrame
+
+    vecm_fit_: VECMResults
+
+    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_ = pd.DataFrame(
+            self._transform_dataframe(market_data)[["tstamp"] + self.colnames()]
+        )
+
+ 
+        self.user_data_ = {}
+
+    def _transform_dataframe(self, df: pd.DataFrame) -> pd.DataFrame:
+        # Select only the columns we need
+        df_selected: pd.DataFrame = pd.DataFrame(
+            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()
+        assert self.training_df_ is not None
+        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()
+        assert self.testing_df_ is not None
+        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):
+        assert self.training_df_ is not None
+        vecm_df = self.training_df_[self.colnames()].reset_index(drop=True)
+        vecm_model = VECM(vecm_df, coint_rank=1)
+        vecm_fit = vecm_model.fit()
+
+        assert vecm_fit is not None
+
+        # 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):
+        assert self.training_df_ is not None
+        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]}? {result.lr1[0] > result.cvt[0, 1]}"
+        )
+        is_cointegrated = result.lr1[0] > result.cvt[0, 1]
+
+        return is_cointegrated
+
+    def check_cointegration_engle_granger(self):
+        from statsmodels.tsa.stattools import coint
+
+        col1, col2 = self.colnames()
+        assert self.training_df_ is not None
+        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_johansen = self.check_cointegration_johansen()
+        is_cointegrated_engle_granger = self.check_cointegration_engle_granger()
+        if not is_cointegrated_johansen and not is_cointegrated_engle_granger:
+            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
+        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_[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) -> pd.DataFrame:
+        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=pd.Index(self.colnames()), dtype=float
+            ),
+            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_}"

lib/tools/config.py

@@ -0,0 +1,17 @@
+import hjson
+from typing import Dict
+from datetime import datetime
+
+
+def load_config(config_path: str) -> Dict:
+    with open(config_path, "r") as f:
+        config = hjson.load(f)
+    return dict(config)
+
+
+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,138 @@
+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)

lib/utils/db_inspector.py

@@ -0,0 +1,169 @@
+#!/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) -> None:
+    """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) -> None:
+    """View entries from the config table."""
+    conn = sqlite3.connect(db_path)
+    cursor = conn.cursor()
+    
+    cursor.execute(f"""
+        SELECT id, run_timestamp, config_file_path, fit_method_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, fit_method_class, datafiles, instruments, config_json = row
+        
+        print(f"ID: {id} | {run_timestamp}")
+        print(f"Config: {config_file_path} | Strategy: {fit_method_class}")
+        print(f"Files: {datafiles}")
+        print(f"Instruments: {instruments}")
+        print("-" * 80)
+    
+    conn.close()
+
+def view_results_summary(db_path: str) -> None:
+    """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() -> None:
+    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()