quantlib-st 1.8.0__py3-none-any.whl

quantlib_st/cli/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["main"]
+
+from quantlib_st.cli.main import main

quantlib_st/cli/__main__.py

@@ -0,0 +1,5 @@
+from quantlib_st.cli.main import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

quantlib_st/cli/corr_cmd.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from io import StringIO
+
+
+def add_corr_subcommand(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "corr",
+        help="Compute correlations over time from CSV piped on stdin (outputs JSON).",
+    )
+
+    parser.add_argument(
+        "--frequency",
+        default="D",
+        help="Resample frequency before correlation (default: D). Use W if you want weekly.",
+    )
+    parser.add_argument(
+        "--date-method",
+        default="in_sample",
+        choices=["expanding", "rolling", "in_sample"],
+        help="How to choose the fit window over time (default: in_sample)",
+    )
+    parser.add_argument(
+        "--rollyears",
+        type=int,
+        default=20,
+        help="Rolling years (used only if --date-method rolling; default: 20)",
+    )
+    parser.add_argument(
+        "--interval-frequency",
+        default="12M",
+        help="How often to emit a new correlation matrix (default: 12M)",
+    )
+
+    parser.add_argument(
+        "--using-exponent",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Use EWMA correlation (default: true)",
+    )
+    parser.add_argument(
+        "--ew-lookback",
+        type=int,
+        default=250,
+        help="EWMA span/lookback (default: 250)",
+    )
+    parser.add_argument(
+        "--min-periods",
+        type=int,
+        default=20,
+        help="Minimum observations before correlations appear (default: 20)",
+    )
+
+    parser.add_argument(
+        "--floor-at-zero",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Floor negative correlations at 0 (default: true)",
+    )
+    parser.add_argument(
+        "--clip",
+        type=float,
+        default=None,
+        help="Optional absolute clip value for correlations (e.g. 0.9)",
+    )
+    parser.add_argument(
+        "--shrinkage",
+        type=float,
+        default=0.0,
+        help="Optional shrinkage-to-average in [0,1] (default: 0)",
+    )
+
+    parser.add_argument(
+        "--forward-fill-price-index",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Forward fill the synthetic price index before resampling (default: true)",
+    )
+    parser.add_argument(
+        "--is-price-series",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="If true, treat input as prices. If false (default), treat as returns.",
+    )
+
+    parser.add_argument(
+        "--index-col",
+        type=int,
+        default=0,
+        help="Which CSV column is the datetime index (default: 0)",
+    )
+
+    parser.set_defaults(_handler=run_corr)
+
+
+def run_corr(args: argparse.Namespace) -> int:
+    import pandas as pd
+    from quantlib_st.correlation.correlation_over_time import (
+        correlation_over_time,
+        correlation_list_to_jsonable,
+    )
+
+    csv_text = sys.stdin.read()
+    if not csv_text.strip():
+        print(json.dumps({"error": "no input on stdin"}), file=sys.stderr)
+        return 2
+
+    try:
+        df = pd.read_csv(StringIO(csv_text), index_col=args.index_col, parse_dates=True)
+    except Exception as e:
+        print(json.dumps({"error": f"failed to parse CSV: {e}"}), file=sys.stderr)
+        return 2
+
+    df = df.sort_index()
+
+    corr_list = correlation_over_time(
+        df,
+        frequency=args.frequency,
+        forward_fill_price_index=args.forward_fill_price_index,
+        is_price_series=args.is_price_series,
+        date_method=args.date_method,
+        rollyears=args.rollyears,
+        interval_frequency=args.interval_frequency,
+        using_exponent=args.using_exponent,
+        ew_lookback=args.ew_lookback,
+        min_periods=args.min_periods,
+        floor_at_zero=args.floor_at_zero,
+        clip=args.clip,
+        shrinkage=args.shrinkage,
+    )
+
+    out = correlation_list_to_jsonable(corr_list)
+    sys.stdout.write(json.dumps(out))
+    sys.stdout.write("\n")
+    return 0

quantlib_st/cli/costs_cmd.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from io import StringIO
+
+
+def add_costs_subcommand(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "costs",
+        help="Calculate SR costs for an instrument from price CSV piped on stdin or provided via file.",
+    )
+
+    parser.add_argument(
+        "--instrument",
+        required=True,
+        help="Instrument code (e.g., ES, GC).",
+    )
+    parser.add_argument(
+        "--config",
+        help="Path to JSON file containing instrument cost configuration.",
+    )
+    parser.add_argument(
+        "--use-ibkr",
+        action="store_true",
+        help="Use IBKR API for cost data (currently a stub).",
+    )
+    parser.add_argument(
+        "--vol",
+        type=float,
+        help="Override annualized volatility (as a decimal, e.g., 0.15 for 15%%).",
+    )
+    parser.add_argument(
+        "--price",
+        type=float,
+        help="Override current price (otherwise uses the last price in the CSV).",
+    )
+
+    parser.set_defaults(_handler=handle_costs)
+
+
+def handle_costs(args: argparse.Namespace) -> int:
+    import pandas as pd
+    from quantlib_st.costs.data_source import (
+        ConfigFileCostDataSource,
+        IBKRCostDataSource,
+    )
+    from quantlib_st.costs.calculator import (
+        calculate_sr_cost,
+        calculate_annualized_volatility,
+        calculate_recent_average_price,
+        calculate_cost_percentage_terms,
+    )
+
+    # 1. Get Cost Config
+    if args.use_ibkr:
+        data_source = IBKRCostDataSource()
+    elif args.config:
+        data_source = ConfigFileCostDataSource(args.config)
+    else:
+        print("Error: Must provide either --config or --use-ibkr", file=sys.stderr)
+        return 1
+
+    try:
+        cost_config = data_source.get_cost_config(args.instrument)
+    except Exception as e:
+        print(f"Error fetching cost config: {e}", file=sys.stderr)
+        return 1
+
+    # 2. Get Price Data
+    if not sys.stdin.isatty():
+        # Read from stdin
+        input_data = sys.stdin.read()
+        df = pd.read_csv(StringIO(input_data), index_col=0, parse_dates=True)
+    else:
+        # If no stdin, we need at least --price and --vol if we want to calculate anything
+        df = pd.DataFrame()
+
+    if df.empty and (args.price is None or args.vol is None):
+        print(
+            "Error: Must pipe price CSV to stdin or provide both --price and --vol overrides.",
+            file=sys.stderr,
+        )
+        return 1
+
+    # 3. Determine Price and Volatility
+    if args.price is not None:
+        average_price = float(args.price)
+    else:
+        # Use average price over the last year (256 days)
+        average_price = calculate_recent_average_price(df.iloc[:, 0])
+
+    if args.vol is not None:
+        # If user provides --vol, we assume it's annualized volatility in price units
+        ann_stdev_price_units = float(args.vol)
+    else:
+        # Calculate annualized volatility in price units (average over last year)
+        ann_stdev_price_units = float(calculate_annualized_volatility(df.iloc[:, 0]))
+
+    # 4. Calculate Costs
+    sr_cost = float(
+        calculate_sr_cost(
+            cost_config,
+            price=average_price,
+            ann_stdev_price_units=ann_stdev_price_units,
+        )
+    )
+
+    pct_cost = float(
+        calculate_cost_percentage_terms(
+            cost_config,
+            blocks_traded=1.0,
+            price=average_price,
+        )
+    )
+
+    # 5. Output Results
+    result = {
+        "instrument": args.instrument,
+        "average_price": round(average_price, 4),
+        "ann_stdev_price_units": round(ann_stdev_price_units, 4),
+        "sr_cost": round(sr_cost, 5),
+        "percentage_cost": round(pct_cost, 6),
+    }
+
+    print(json.dumps(result, indent=2))
+    return 0

quantlib_st/cli/main.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import argparse
+import importlib.metadata
+
+from quantlib_st.cli.corr_cmd import add_corr_subcommand
+from quantlib_st.cli.costs_cmd import add_costs_subcommand
+
+
+def get_version() -> str:
+    """Get the version of quantlib-st package."""
+    try:
+        return importlib.metadata.version("quantlib-st")
+    except importlib.metadata.PackageNotFoundError:
+        return "unknown"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="quantlib",
+        description="quantlib CLI (corr is the first subcommand; more will be added).",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"%(prog)s {get_version()}",
+    )
+
+    subparsers = parser.add_subparsers(dest="subcommand", required=True)
+
+    add_corr_subcommand(subparsers)
+    add_costs_subcommand(subparsers)
+
+    args = parser.parse_args(argv)
+
+    # Dispatch
+    if args.subcommand == "corr":
+        return args._handler(args)
+    elif args.subcommand == "costs":
+        return args._handler(args)
+
+    parser.error(f"Unknown subcommand: {args.subcommand}")
+    return 2

quantlib_st/config/configdata.py

@@ -0,0 +1,329 @@
+"""
+Configuration is used to control the behaviour of a system
+
+Config can be passed as a dict, a filename from which a YAML spec is read in
+and then parsed
+
+There are no set elements for configurations, although typically they will
+contain:
+
+parameters - a dict of values which override those in system.defaults
+trading_rules - a specification of the trading rules for a system
+
+"""
+
+from pathlib import Path
+from typing import Optional, Union, Any
+
+import os
+import yaml
+
+from quantlib_st.core.exceptions import missingData
+from quantlib_st.core.fileutils import resolve_path_and_filename_for_package
+from quantlib_st.config.defaults import get_system_defaults_dict
+from quantlib_st.config.fill_config_dict_with_defaults import (
+    fill_config_dict_with_defaults,
+)
+from quantlib_st.config.private_config import (
+    get_private_config_as_dict,
+    PRIVATE_CONFIG_FILE,
+)
+from quantlib_st.config.private_directory import (
+    get_full_path_for_private_config,
+    PRIVATE_CONFIG_DIR_ENV_VAR,
+)
+from quantlib_st.logging.logger import *
+
+
+RESERVED_NAMES = [
+    "log",
+    "_elements",
+    "elements",
+    "_default_filename",
+    "_private_filename",
+]
+
+
+class Config(object):
+    # Common configuration attributes (type hints for IDE)
+    trading_rules: Any
+    forecast_scalar_estimate: Any
+    forecast_scalar_fixed: Any
+    instruments: Any
+    parameters: Any
+    base_currency: Any
+
+    def __init__(
+        self,
+        config_object: Optional[Union[str, dict, list]] = None,
+        default_filename=None,
+        private_filename=None,
+    ):
+        """
+        Config objects control the behaviour of systems
+
+        :param config_object: Either:
+                        a string (which points to a YAML filename)
+                        or a dict (which may nest many things)
+                        or a list of strings or dicts or configs (build config from
+                        multiple elements, latter elements will overwrite
+                        earlier ones)
+
+        :type config_object: str or dict
+
+        :returns: new Config object
+
+        >>> Config(dict(parameters=dict(p1=3, p2=4.6), another_thing=[]))
+        Config with elements: another_thing, parameters
+
+        >>> Config("systems.provided.example.exampleconfig.yaml")
+        Config with elements: base_currency, ... trading_rules
+
+        >>> Config(["systems.provided.example.exampleconfig.yaml", dict(parameters=dict(p1=3, p2=4.6), another_thing=[])])
+        Config with elements: another_thing, ... parameters, ...trading_rules
+
+        """
+
+        # this will normally be overridden by the base system
+        self.log = get_logger(
+            "config", {TYPE_LOG_LABEL: "config", STAGE_LOG_LABEL: "config"}
+        )
+
+        self._default_filename = default_filename
+        self._private_filename = private_filename
+
+        if config_object is None:
+            config_object = dict()
+
+        self._init_config(config_object)
+
+    @property
+    def elements(self) -> list:
+        elements = getattr(self, "_elements", [])
+
+        return elements
+
+    def add_elements(self, new_elements: list):
+        _ = [self.add_single_element(element_name) for element_name in new_elements]
+
+    def remove_element(self, element: str):
+        current_elements = self.elements
+        current_elements.remove(element)
+        self._elements = current_elements
+
+    def add_single_element(self, element_name):
+        if element_name not in RESERVED_NAMES:
+            elements = self.elements
+            if element_name not in elements:
+                elements.append(element_name)
+                self._elements = elements
+
+    def __getattr__(self, name: str) -> Any:
+        # This allows Pylance to know that Config can have dynamic attributes
+        # and prevents "unknown attribute" errors.
+        # We only get here if the attribute isn't already defined in __dict__
+        raise AttributeError(
+            f"'{type(self).__name__}' object has no attribute '{name}'"
+        )
+
+    def get_element(self, element_name):
+        try:
+            result = getattr(self, element_name)
+        except AttributeError:
+            raise missingData("Missing config element %s" % element_name)
+        return result
+
+    def get_element_or_default(self, element_name, default):
+        result = getattr(self, element_name, default)
+        return result
+
+    def get_element_or_arg_not_supplied(self, element_name):
+        return self.get_element_or_default(element_name, None)
+
+    def __repr__(self):
+        elements = self.elements
+        elements.sort()
+        return "Config with elements: %s" % ", ".join(self.elements)
+
+    def _init_config(self, config_object):
+        if isinstance(config_object, list):
+            # multiple configs, already a list
+            config_list = config_object
+        else:
+            config_list = [config_object]
+
+        self._create_config_from_list(config_list)
+
+    def _create_config_from_list(self, config_object):
+        for config_item in config_object:
+            self._create_config_from_item(config_item)
+
+    def _create_config_from_item(self, config_item):
+        if isinstance(config_item, dict):
+            # its a dict
+            self._create_config_from_dict(config_item)
+
+        elif isinstance(config_item, str) or isinstance(config_item, Path):
+            # must be a file YAML'able, from which we load the
+            filename = resolve_path_and_filename_for_package(os.fspath(config_item))
+            with open(filename) as file_to_parse:
+                dict_to_parse = yaml.load(file_to_parse, Loader=yaml.FullLoader)
+
+            self._create_config_from_dict(dict_to_parse)
+
+        elif isinstance(config_item, Config):
+            self._create_config_from_dict(config_item.as_dict())
+        else:
+            error_msg = (
+                "Can only create a config with a nested dict or the "
+                "string of a 'yamable' filename, or a list "
+                "comprising these things"
+            )
+            self.log.critical(error_msg)
+
+    def _create_config_from_dict(self, config_object):
+        """
+        Take a dictionary object and turn it into self
+
+        When we've close self will be an object where the attributes are
+
+        So if config_object=dict(a=2, b=2)
+        Then this object will become self.a=2, self.b=2
+        """
+        base_config = config_object.get("base_config")
+        if base_config is not None:
+            self._create_config_from_item(base_config)
+
+        attr_names = list(config_object.keys())
+        [setattr(self, keyname, config_object[keyname]) for keyname in config_object]
+
+        self.add_elements(attr_names)
+
+    def system_init(self, base_system):
+        """
+        This is run when added to a base system
+
+        :param base_system
+        :return: nothing
+        """
+
+        # fill with defaults
+        self.fill_with_defaults()
+
+    def __delattr__(self, element_name: str):
+        """
+        Remove element_name from config
+
+        >>> config=Config(dict(parameters=dict(p1=3, p2=4.6), another_thing=[]))
+        >>> del(config.another_thing)
+        >>> config
+        Config with elements: parameters
+        >>>
+        """
+        # to avoid recursion, we must first avoid recursion
+        super().__delattr__(element_name)
+
+        self.remove_element(element_name)
+
+    def __setattr__(self, element_name: str, value):
+        """
+        Add / replace element_name in config
+
+        >>> config=Config(dict(parameters=dict(p1=3, p2=4.6), another_thing=[]))
+        >>> config.another_thing="test"
+        >>> config.another_thing
+        'test'
+        >>> config.yet_another_thing="more testing"
+        >>> config
+        Config with elements: another_thing, parameters, yet_another_thing
+        >>>
+        """
+        # to avoid recursion, we must first avoid recursion
+        super().__setattr__(element_name, value)
+        self.add_single_element(element_name)
+
+    def fill_with_defaults(self):
+        """
+        Fills with defaults - private stuff first, then defaults
+        """
+        # self.log.debug("Adding config defaults")
+
+        self_as_dict = self.as_dict()
+        defaults_dict = self.default_config_dict
+        private_dict = self.private_config_dict
+
+        ## order is - self (backtest filename), private, defaults
+        new_dict_with_private = fill_config_dict_with_defaults(
+            self_as_dict, private_dict
+        )
+        new_dict_with_defaults = fill_config_dict_with_defaults(
+            new_dict_with_private, defaults_dict
+        )
+
+        self._create_config_from_dict(new_dict_with_defaults)
+
+    @property
+    def default_config_dict(self) -> dict:
+        default_filename = self.default_config_filename
+        default_dict = get_system_defaults_dict(filename=default_filename)
+
+        return default_dict
+
+    @property
+    def default_config_filename(self) -> Optional[str]:
+        default_filename = getattr(self, "_default_filename", None)
+
+        return default_filename
+
+    @property
+    def private_config_dict(self) -> dict:
+        private_filename = self.private_config_filename
+        private_dict = get_private_config_as_dict(private_filename)
+
+        return private_dict
+
+    @property
+    def private_config_filename(self):
+        private_filename = getattr(self, "_private_filename", None)
+
+        return private_filename
+
+    def as_dict(self):
+        element_names = sorted(getattr(self, "_elements", []))
+        self_as_dict = {}
+        for element in element_names:
+            self_as_dict[element] = getattr(self, element, "")
+
+        return self_as_dict
+
+    def save(self, filename):
+        config_to_save = self.as_dict()
+        with open(filename, "w") as file:
+            yaml.dump(config_to_save, file)
+
+    @classmethod
+    def default_config(cls):
+        if hasattr(cls, "evaluated"):
+            return cls.evaluated
+
+        if os.getenv(PRIVATE_CONFIG_DIR_ENV_VAR):
+            config = Config(
+                private_filename=get_full_path_for_private_config(PRIVATE_CONFIG_FILE)
+            )
+        else:
+            config = Config()
+        config.fill_with_defaults()
+
+        cls.evaluated = config
+        return cls.evaluated
+
+    @classmethod
+    def reset(cls):
+        if hasattr(cls, "evaluated"):
+            delattr(cls, "evaluated")
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

quantlib_st/config/defaults.py

@@ -0,0 +1,36 @@
+"""
+All default parameters that might be used in a system are stored here
+
+Order of preferences is - passed in command line to calculation method,
+                          stored in system config object
+                          found in defaults
+
+"""
+
+from typing import Optional
+
+import yaml
+
+from quantlib_st.core.fileutils import resolve_path_and_filename_for_package
+
+DEFAULT_FILENAME = "config.defaults.yaml"
+
+
+def get_system_defaults_dict(filename: Optional[str] = None) -> dict:
+    """
+    >>> get_system_defaults_dict()['average_absolute_forecast']
+    10.0
+    """
+    if filename is None:
+        filename = DEFAULT_FILENAME
+    default_file = resolve_path_and_filename_for_package(filename)
+    with open(default_file) as file_to_parse:
+        default_dict = yaml.load(file_to_parse, Loader=yaml.FullLoader)
+
+    return default_dict
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()