quantlib-st 0.1.0__tar.gz

quantlib_st-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: quantlib-st
+Version: 0.1.0
+Summary: quantlib-st - a quantitative finance library and cli for systematic trading
+Requires-Python: >=3.12
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: numpy>=2.4.0
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

quantlib_st-0.1.0/README.md

@@ -0,0 +1,25 @@
+# quantlib
+
+Minimal, self-contained CLI tools and library for quantitative finance.
+
+## Subcommands
+
+- **[corr](correlation/README.md)**: Compute correlation matrices over time from returns.
+- **[costs](costs/README.md)**: Calculate Sharpe Ratio (SR) costs for instruments based on spread and fees.
+
+## Install (editable - for developers)
+
+From the repo root:
+
+- `cd quantlib`
+- `python -m pip install install -e .`
+
+This installs the `quantlib` command.
+
+## Build a single binary with PyInstaller
+
+From `quantlib/`:
+
+- `make build`
+
+Binary will be at `dist/quantlib`.

quantlib_st-0.1.0/cli/__init__.py

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

quantlib_st-0.1.0/cli/__main__.py

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

quantlib_st-0.1.0/cli/corr_cmd.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from io import StringIO
+
+import pandas as pd
+
+from correlation.correlation_over_time import (
+    correlation_over_time_for_returns,
+    correlation_list_to_jsonable,
+)
+
+
+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(
+        "--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:
+    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_for_returns(
+        df,
+        frequency=args.frequency,
+        forward_fill_price_index=args.forward_fill_price_index,
+        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-0.1.0/cli/costs_cmd.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import pandas as pd
+from io import StringIO
+
+from costs.data_source import ConfigFileCostDataSource, IBKRCostDataSource
+from costs.calculator import (
+    calculate_sr_cost,
+    calculate_annualized_volatility,
+    calculate_recent_average_price,
+    calculate_cost_percentage_terms,
+)
+
+
+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:
+    # 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-0.1.0/cli/main.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import argparse
+
+from cli.corr_cmd import add_corr_subcommand
+from cli.costs_cmd import add_costs_subcommand
+
+
+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).",
+    )
+
+    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-0.1.0/correlation/correlation_over_time.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+
+import pandas as pd
+
+from .fitting_dates import generate_fitting_dates, listOfFittingDates
+from .exponential_correlation import (
+    CorrelationEstimate,
+    ExponentialCorrelationResults,
+    create_boring_corr_matrix,
+    modify_correlation,
+)
+
+
+@dataclass
+class CorrelationList:
+    corr_list: list[CorrelationEstimate]
+    column_names: list[str]
+    fit_dates: listOfFittingDates
+
+
+def correlation_over_time_for_returns(
+    returns_for_correlation: pd.DataFrame,
+    frequency: str = "D",
+    forward_fill_price_index: bool = True,
+    **kwargs,
+) -> CorrelationList:
+    # Build a synthetic price index from returns, resample, then diff.
+    # For daily frequency, this is essentially a no-op aside from losing the first row.
+    index_prices_for_correlation = returns_for_correlation.cumsum()
+    if forward_fill_price_index:
+        index_prices_for_correlation = index_prices_for_correlation.ffill()
+
+    index_prices_for_correlation = index_prices_for_correlation.resample(frequency).last()
+    returns_for_correlation = index_prices_for_correlation.diff()
+
+    return correlation_over_time(returns_for_correlation, **kwargs)
+
+
+def correlation_over_time(
+    data_for_correlation: pd.DataFrame,
+    date_method: str = "in_sample",
+    rollyears: int = 20,
+    interval_frequency: str = "12M",
+    using_exponent: bool = True,
+    ew_lookback: int = 250,
+    min_periods: int = 20,
+    no_data_offdiag: float = 0.99,
+    floor_at_zero: bool = True,
+    clip: float | None = None,
+    shrinkage: float = 0.0,
+) -> CorrelationList:
+    column_names = list(data_for_correlation.columns)
+
+    fit_dates = generate_fitting_dates(
+        data_for_correlation,
+        date_method=date_method,
+        rollyears=rollyears,
+        interval_frequency=interval_frequency,
+    )
+
+    corr_list: list[CorrelationEstimate] = []
+
+    if using_exponent:
+        results = ExponentialCorrelationResults(
+            data_for_correlation, ew_lookback=ew_lookback, min_periods=min_periods
+        )
+
+        for fit_period in fit_dates:
+            if getattr(fit_period, "no_data", False):
+                corr_list.append(
+                    create_boring_corr_matrix(
+                        len(column_names), column_names, offdiag=no_data_offdiag
+                    )
+                )
+                continue
+
+            corr = results.last_valid_cor_matrix_for_date(fit_period.fit_end)
+            if pd.isna(corr.values).all():
+                corr = create_boring_corr_matrix(
+                    len(column_names), column_names, offdiag=no_data_offdiag
+                )
+
+            corr = modify_correlation(
+                corr,
+                floor_at_zero=floor_at_zero,
+                clip_value=clip,
+                shrinkage=shrinkage,
+            )
+            corr_list.append(corr)
+
+    else:
+        for fit_period in fit_dates:
+            if getattr(fit_period, "no_data", False):
+                corr_list.append(
+                    create_boring_corr_matrix(
+                        len(column_names), column_names, offdiag=no_data_offdiag
+                    )
+                )
+                continue
+
+            sub = data_for_correlation.loc[fit_period.fit_start : fit_period.fit_end]
+            corr_pd = sub.corr()
+            corr = CorrelationEstimate(values=corr_pd.values, columns=column_names)
+            corr = modify_correlation(
+                corr,
+                floor_at_zero=floor_at_zero,
+                clip_value=clip,
+                shrinkage=shrinkage,
+            )
+            corr_list.append(corr)
+
+    return CorrelationList(corr_list=corr_list, column_names=column_names, fit_dates=fit_dates)
+
+
+def correlation_list_to_jsonable(corr_list: CorrelationList) -> dict:
+    periods = []
+    for fit_period, corr in zip(corr_list.fit_dates, corr_list.corr_list):
+        periods.append(
+            {
+                "fit_start": _dt_to_iso(fit_period.fit_start),
+                "fit_end": _dt_to_iso(fit_period.fit_end),
+                "period_start": _dt_to_iso(fit_period.period_start),
+                "period_end": _dt_to_iso(fit_period.period_end),
+                "no_data": bool(getattr(fit_period, "no_data", False)),
+                "correlation": corr.as_dict(),
+            }
+        )
+
+    return {
+        "columns": list(corr_list.column_names),
+        "periods": periods,
+    }
+
+
+def _dt_to_iso(dt: datetime.datetime) -> str:
+    if isinstance(dt, pd.Timestamp):
+        dt = dt.to_pydatetime()
+    if dt.tzinfo is not None:
+        return dt.isoformat()
+    return dt.replace(tzinfo=datetime.timezone.utc).isoformat()

quantlib_st-0.1.0/correlation/exponential_correlation.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass
+class CorrelationEstimate:
+    values: np.ndarray
+    columns: list[str]
+
+    def as_dict(self) -> dict:
+        return {
+            "columns": list(self.columns),
+            "values": self.values.tolist(),
+        }
+
+    def floor_at_zero(self) -> "CorrelationEstimate":
+        values = self.values.copy()
+        values[values < 0.0] = 0.0
+        np.fill_diagonal(values, 1.0)
+        return CorrelationEstimate(values=values, columns=self.columns)
+
+    def clip(self, clip_value: float | None) -> "CorrelationEstimate":
+        if clip_value is None:
+            return self
+        clip_value = abs(float(clip_value))
+        values = self.values.copy()
+        values[values < -clip_value] = -clip_value
+        values[values > clip_value] = clip_value
+        np.fill_diagonal(values, 1.0)
+        return CorrelationEstimate(values=values, columns=self.columns)
+
+    def shrink_to_average(self, shrinkage: float) -> "CorrelationEstimate":
+        shrinkage = float(shrinkage)
+        if shrinkage <= 0.0:
+            return self
+        if shrinkage >= 1.0:
+            shrinkage = 1.0
+
+        values = self.values.copy()
+        vals = values.copy()
+        np.fill_diagonal(vals, np.nan)
+        avg = np.nanmean(vals)
+        if np.isnan(avg):
+            return self
+
+        prior = np.full_like(values, avg, dtype=float)
+        np.fill_diagonal(prior, 1.0)
+        shrunk = shrinkage * prior + (1.0 - shrinkage) * values
+        np.fill_diagonal(shrunk, 1.0)
+        return CorrelationEstimate(values=shrunk, columns=self.columns)
+
+
+def modify_correlation(
+    corr: CorrelationEstimate,
+    *,
+    floor_at_zero: bool = True,
+    shrinkage: float = 0.0,
+    clip_value: float | None = None,
+) -> CorrelationEstimate:
+    if floor_at_zero:
+        corr = corr.floor_at_zero()
+    corr = corr.clip(clip_value)
+    if shrinkage and shrinkage > 0.0:
+        corr = corr.shrink_to_average(shrinkage)
+    return corr
+
+
+def create_boring_corr_matrix(
+    size: int, columns: list[str], offdiag: float = 0.99
+) -> CorrelationEstimate:
+    values = np.full((size, size), offdiag, dtype=float)
+    np.fill_diagonal(values, 1.0)
+    return CorrelationEstimate(values=values, columns=columns)
+
+
+class ExponentialCorrelationResults:
+    def __init__(
+        self, data_for_correlation: pd.DataFrame, ew_lookback: int = 250, min_periods: int = 20
+    ):
+        self._columns = list(data_for_correlation.columns)
+        self._raw_correlations = data_for_correlation.ewm(
+            span=ew_lookback, min_periods=min_periods, ignore_na=True
+        ).corr(pairwise=True)
+
+    @property
+    def raw_correlations(self) -> pd.DataFrame:
+        return self._raw_correlations
+
+    @property
+    def columns(self) -> list[str]:
+        return self._columns
+
+    def last_valid_cor_matrix_for_date(self, date_point: datetime.datetime) -> CorrelationEstimate:
+        return last_valid_cor_matrix_for_date(self.raw_correlations, self.columns, date_point)
+
+
+def last_valid_cor_matrix_for_date(
+    raw_correlations: pd.DataFrame, columns: list[str], date_point: datetime.datetime
+) -> CorrelationEstimate:
+    size_of_matrix = len(columns)
+    subset = raw_correlations[raw_correlations.index.get_level_values(0) < date_point]
+
+    if subset.shape[0] < size_of_matrix:
+        return CorrelationEstimate(
+            values=np.full((size_of_matrix, size_of_matrix), np.nan),
+            columns=columns,
+        )
+
+    corr_matrix_values = subset.tail(size_of_matrix).values
+    return CorrelationEstimate(values=corr_matrix_values, columns=columns)

quantlib_st-0.1.0/correlation/fitting_dates.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+from typing import List
+
+import pandas as pd
+
+
+IN_SAMPLE = "in_sample"
+ROLLING = "rolling"
+EXPANDING = "expanding"
+
+POSSIBLE_DATE_METHODS = [IN_SAMPLE, ROLLING, EXPANDING]
+
+
+@dataclass
+class fitDates:
+    fit_start: datetime.datetime
+    fit_end: datetime.datetime
+    period_start: datetime.datetime
+    period_end: datetime.datetime
+    no_data: bool = False
+
+
+class listOfFittingDates(list):
+    def list_of_starting_periods(self) -> list:
+        return [period.period_start for period in self]
+
+    def index_of_most_recent_period_before_relevant_date(
+        self, relevant_date: datetime.datetime
+    ):
+        index = []
+        list_of_start_periods = self.list_of_starting_periods()
+        if relevant_date < list_of_start_periods[0]:
+            raise Exception(f"Date {relevant_date} is before first fitting date")
+
+        for index, start_date in enumerate(list_of_start_periods):
+            if relevant_date < start_date:
+                return index - 1
+
+        return index
+
+
+def generate_fitting_dates(
+    data: pd.DataFrame,
+    date_method: str,
+    rollyears: int = 20,
+    interval_frequency: str = "12M",
+) -> listOfFittingDates:
+    if date_method not in POSSIBLE_DATE_METHODS:
+        raise ValueError(
+            f"Unknown date_method={date_method}; expected one of {POSSIBLE_DATE_METHODS}"
+        )
+
+    start_date = data.index[0]
+    end_date = data.index[-1]
+
+    if date_method == IN_SAMPLE:
+        return listOfFittingDates(
+            [fitDates(start_date, end_date, start_date, end_date, no_data=False)]
+        )
+
+    boundaries = _list_of_starting_dates_per_period(
+        start_date, end_date, interval_frequency=interval_frequency
+    )
+
+    # Short history: fall back to a single in-sample period.
+    if len(boundaries) < 2:
+        return listOfFittingDates(
+            [fitDates(start_date, end_date, start_date, end_date, no_data=False)]
+        )
+
+    periods: List[fitDates] = []
+    for period_index in range(len(boundaries))[1:-1]:
+        period_start = boundaries[period_index]
+        period_end = boundaries[period_index + 1]
+
+        if date_method == EXPANDING:
+            fit_start = start_date
+        elif date_method == ROLLING:
+            yearidx_to_use = max(0, period_index - rollyears)
+            fit_start = boundaries[yearidx_to_use]
+        else:
+            raise ValueError(f"Unknown date_method={date_method}")
+
+        fit_end = period_start
+        periods.append(fitDates(fit_start, fit_end, period_start, period_end, no_data=False))
+
+    if date_method in [ROLLING, EXPANDING] and len(boundaries) >= 2:
+        periods = [
+            fitDates(
+                start_date,
+                start_date,
+                start_date,
+                boundaries[1],
+                no_data=True,
+            )
+        ] + periods
+
+    return listOfFittingDates(periods)
+
+
+def _list_of_starting_dates_per_period(
+    start_date: datetime.datetime,
+    end_date: datetime.datetime,
+    interval_frequency: str = "12M",
+):
+    if interval_frequency == "W":
+        use_interval_frequency = "7D"
+    elif interval_frequency == "M":
+        use_interval_frequency = "30D"
+    elif interval_frequency in ["12M", "Y"]:
+        use_interval_frequency = "365D"
+    else:
+        use_interval_frequency = interval_frequency
+
+    results = list(pd.date_range(end_date, start_date, freq="-" + use_interval_frequency))
+    results.reverse()
+    return results

quantlib_st-0.1.0/costs/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

quantlib_st-0.1.0/costs/calculator.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from costs.config import InstrumentCostConfig
+
+
+def calculate_annualized_volatility(
+    prices: pd.Series, days_per_year: int = 256, vol_lookback: int = 35
+) -> float:
+    """
+    Calculate annualized volatility from a price series.
+    Matches the logic in pysystemtrade:
+    1. Calculate absolute price changes.
+    2. Calculate EWMA volatility (span=35).
+    3. Take the mean of that volatility over the last year (256 days).
+    4. Annualize it by multiplying by sqrt(256).
+    """
+    daily_returns = prices.diff().dropna()
+
+    # EWMA volatility of absolute returns
+    daily_vol = daily_returns.ewm(span=vol_lookback, adjust=True, min_periods=10).std()
+
+    # Average over the last year (256 business days)
+    recent_daily_vol = daily_vol.tail(days_per_year).mean()
+
+    # Annualize
+    return float(recent_daily_vol * np.sqrt(days_per_year))
+
+
+def calculate_recent_average_price(
+    prices: pd.Series, days_per_year: int = 256
+) -> float:
+    """
+    Calculate the average price over the last year (256 business days).
+    Matches _recent_average_price in pysystemtrade.
+    """
+    return float(prices.tail(days_per_year).mean())
+
+
+def calculate_sr_cost(
+    cost_config: InstrumentCostConfig,
+    price: float,
+    ann_stdev_price_units: float,
+    blocks_traded: float = 1.0,
+) -> float:
+    """
+    Calculates the expected reduction in Sharpe Ratio due to costs.
+    Ported from pysystemtrade sysobjects.instruments.instrumentCosts.calculate_sr_cost
+    """
+    cost_instrument_currency = calculate_cost_instrument_currency(
+        cost_config, blocks_traded=blocks_traded, price=price
+    )
+
+    # Annualized stdev in instrument currency (price units * point size)
+    ann_stdev_instrument_currency = ann_stdev_price_units * cost_config.point_size
+
+    if ann_stdev_instrument_currency == 0:
+        return 0.0
+
+    return cost_instrument_currency / ann_stdev_instrument_currency
+
+
+def calculate_cost_instrument_currency(
+    cost_config: InstrumentCostConfig,
+    blocks_traded: float,
+    price: float,
+    include_slippage: bool = True,
+) -> float:
+    """
+    Ported from pysystemtrade sysobjects.instruments.instrumentCosts.calculate_cost_instrument_currency
+    """
+    value_per_block = price * cost_config.point_size
+
+    if include_slippage:
+        slippage = (
+            abs(blocks_traded) * cost_config.price_slippage * cost_config.point_size
+        )
+    else:
+        slippage = 0.0
+
+    commission = calculate_total_commission(
+        cost_config, blocks_traded=blocks_traded, value_per_block=value_per_block
+    )
+
+    return slippage + commission
+
+
+def calculate_total_commission(
+    cost_config: InstrumentCostConfig, blocks_traded: float, value_per_block: float
+) -> float:
+    """
+    Ported from pysystemtrade sysobjects.instruments.instrumentCosts.calculate_total_commission
+    """
+    per_trade_commission = cost_config.per_trade_commission
+    per_block_commission = abs(blocks_traded) * cost_config.per_block_commission
+    percentage_commission = (
+        cost_config.percentage_commission * abs(blocks_traded) * value_per_block
+    )
+
+    return max([per_block_commission, per_trade_commission, percentage_commission])
+
+
+def calculate_cost_percentage_terms(
+    cost_config: InstrumentCostConfig, blocks_traded: float, price: float
+) -> float:
+    """
+    Ported from pysystemtrade sysobjects.instruments.instrumentCosts.calculate_cost_percentage_terms
+    """
+    cost_in_currency = calculate_cost_instrument_currency(
+        cost_config, blocks_traded=blocks_traded, price=price
+    )
+    total_value = abs(blocks_traded) * price * cost_config.point_size
+
+    if total_value == 0:
+        return 0.0
+
+    return cost_in_currency / total_value

quantlib_st-0.1.0/costs/config.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class InstrumentCostConfig:
+    instrument_code: str
+    point_size: float
+    price_slippage: float  # Half spread in price units
+    per_block_commission: float = 0.0
+    percentage_commission: float = 0.0
+    per_trade_commission: float = 0.0
+
+    @classmethod
+    def from_dict(cls, data: dict) -> InstrumentCostConfig:
+        return cls(
+            instrument_code=data["instrument_code"],
+            point_size=data["point_size"],
+            price_slippage=data["price_slippage"],
+            per_block_commission=data.get("per_block_commission", 0.0),
+            percentage_commission=data.get("percentage_commission", 0.0),
+            per_trade_commission=data.get("per_trade_commission", 0.0),
+        )

quantlib_st-0.1.0/costs/data_source.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from costs.config import InstrumentCostConfig
+
+
+class CostDataSource(ABC):
+    @abstractmethod
+    def get_cost_config(self, instrument_code: str) -> InstrumentCostConfig:
+        pass
+
+
+class ConfigFileCostDataSource(CostDataSource):
+    def __init__(self, config_path: str):
+        with open(config_path, "r") as f:
+            self.config_data = json.load(f)
+
+    def get_cost_config(self, instrument_code: str) -> InstrumentCostConfig:
+        # Assuming the config file is a list of instrument configs or a dict keyed by code
+        if isinstance(self.config_data, list):
+            for item in self.config_data:
+                if item["instrument_code"] == instrument_code:
+                    return InstrumentCostConfig.from_dict(item)
+        elif isinstance(self.config_data, dict):
+            if instrument_code in self.config_data:
+                return InstrumentCostConfig.from_dict(self.config_data[instrument_code])
+            elif (
+                "instrument_code" in self.config_data
+                and self.config_data["instrument_code"] == instrument_code
+            ):
+                return InstrumentCostConfig.from_dict(self.config_data)
+
+        raise ValueError(f"No cost config found for instrument: {instrument_code}")
+
+
+class IBKRCostDataSource(CostDataSource):
+    """
+    Stub for future IBKR API integration.
+    """
+
+    def get_cost_config(self, instrument_code: str) -> InstrumentCostConfig:
+        # TODO: Implement IBKR API calls to fetch real-time/historical spreads and commissions
+        raise NotImplementedError(
+            "IBKR API integration not yet implemented. Please use --config for now."
+        )

quantlib_st-0.1.0/quantlib_st.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: quantlib-st
+Version: 0.1.0
+Summary: quantlib-st - a quantitative finance library and cli for systematic trading
+Requires-Python: >=3.12
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: numpy>=2.4.0
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

quantlib_st-0.1.0/quantlib_st.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+README.md
+setup.py
+cli/__init__.py
+cli/__main__.py
+cli/corr_cmd.py
+cli/costs_cmd.py
+cli/main.py
+correlation/__init__.py
+correlation/correlation_over_time.py
+correlation/exponential_correlation.py
+correlation/fitting_dates.py
+costs/__init__.py
+costs/calculator.py
+costs/config.py
+costs/data_source.py
+quantlib_st.egg-info/PKG-INFO
+quantlib_st.egg-info/SOURCES.txt
+quantlib_st.egg-info/dependency_links.txt
+quantlib_st.egg-info/entry_points.txt
+quantlib_st.egg-info/requires.txt
+quantlib_st.egg-info/top_level.txt
+tests/__init__.py
+tests/correlation/__init__.py
+tests/correlation/test_correlation.py
+tests/correlation/test_fitting_dates.py

quantlib_st-0.1.0/quantlib_st.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

quantlib_st-0.1.0/quantlib_st.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+quantlib- = cli.main:main

quantlib_st-0.1.0/quantlib_st.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pandas>=2.3.3
+numpy>=2.4.0

quantlib_st-0.1.0/quantlib_st.egg-info/top_level.txt

@@ -0,0 +1,4 @@
+cli
+correlation
+costs
+tests

quantlib_st-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

quantlib_st-0.1.0/setup.py

@@ -0,0 +1,19 @@
+from setuptools import setup, find_packages
+
+
+setup(
+    name="quantlib-st",
+    version="0.1.0",
+    description="quantlib-st - a quantitative finance library and cli for systematic trading",
+    packages=find_packages(),
+    python_requires=">=3.12",
+    install_requires=[
+        "pandas>=2.3.3",
+        "numpy>=2.4.0",
+    ],
+    entry_points={
+        "console_scripts": [
+            "quantlib-=cli.main:main",
+        ]
+    },
+)

quantlib_st-0.1.0/tests/correlation/test_correlation.py

@@ -0,0 +1,75 @@
+import datetime
+import numpy as np
+import pandas as pd
+
+from correlation.exponential_correlation import (
+    ExponentialCorrelationResults,
+    CorrelationEstimate,
+)
+
+
+def test_exponential_correlation_results_structure():
+    # Create dummy returns for 3 instruments over 5 days
+    dates = pd.date_range("2023-01-01", periods=5)
+    data = pd.DataFrame(np.random.randn(5, 3), index=dates, columns=["A", "B", "C"])
+
+    # Initialize with a small lookback for testing
+    results = ExponentialCorrelationResults(data, ew_lookback=5, min_periods=2)
+
+    # 1. Understanding _raw_correlations
+    # When we call .corr(pairwise=True) on an EWM object, pandas returns a MultiIndex DataFrame.
+    # Level 0: Date
+    # Level 1: Instrument name
+    raw = results.raw_correlations
+
+    assert isinstance(raw, pd.DataFrame)
+    # For 5 days and 3 instruments, we expect 5 * 3 = 15 rows
+    assert len(raw) == 15
+    # The columns should match the instrument names
+    assert list(raw.columns) == ["A", "B", "C"]
+
+    # Check the first date's matrix (it should be NaN if min_periods=2)
+    first_date = dates[0]
+    matrix_at_t0 = raw.loc[first_date]
+    assert matrix_at_t0.isna().all().all()
+
+    # Check the third date's matrix (should have values)
+    third_date = dates[2]
+    matrix_at_t2 = raw.loc[third_date]
+    assert not matrix_at_t2.isna().any().any()
+    assert matrix_at_t2.loc["A", "A"] == 1.0  # Diagonal is always 1.0
+
+
+def test_last_valid_cor_matrix_for_date():
+    dates = pd.date_range("2023-01-01", periods=10)
+    data = pd.DataFrame(np.random.randn(10, 2), index=dates, columns=["X", "Y"])
+
+    results = ExponentialCorrelationResults(data, ew_lookback=5, min_periods=2)
+
+    # Test retrieving matrix for a specific point in time
+    # If we ask for 2023-01-05, it should give us the matrix from the last available date BEFORE 2023-01-05
+    target_date = datetime.datetime(2023, 1, 5)
+    estimate = results.last_valid_cor_matrix_for_date(target_date)
+
+    assert isinstance(estimate, CorrelationEstimate)
+    assert estimate.columns == ["X", "Y"]
+    assert estimate.values.shape == (2, 2)
+
+    # The values should match the raw correlation at 2023-01-04
+    expected_values = np.asarray(
+        results.raw_correlations.loc[pd.Timestamp("2023-01-04")].values
+    )
+    np.testing.assert_array_almost_equal(estimate.values, expected_values)
+
+
+def test_last_valid_cor_matrix_no_data():
+    # Test what happens if we ask for a date before any data exists
+    dates = pd.date_range("2023-01-10", periods=5)
+    data = pd.DataFrame(np.random.randn(5, 2), index=dates, columns=["X", "Y"])
+    results = ExponentialCorrelationResults(data)
+
+    early_date = datetime.datetime(2023, 1, 1)
+    estimate = results.last_valid_cor_matrix_for_date(early_date)
+
+    # Should return a matrix of NaNs
+    assert np.isnan(estimate.values).all()

quantlib_st-0.1.0/tests/correlation/test_fitting_dates.py

@@ -0,0 +1,54 @@
+import pandas as pd
+
+from correlation.fitting_dates import (
+    generate_fitting_dates,
+    IN_SAMPLE,
+    EXPANDING,
+    ROLLING,
+)
+
+
+def _make_df(start: str, end: str, freq: str = "M") -> pd.DataFrame:
+    idx = pd.date_range(start, end, freq=freq)
+    return pd.DataFrame(index=idx, data={"x": 0})
+
+
+def test_in_sample_returns_single_period():
+    df = _make_df("2020-01-01", "2022-12-31")
+    periods = generate_fitting_dates(df, date_method=IN_SAMPLE)
+
+    assert len(periods) == 1
+    p = periods[0]
+    assert p.fit_start == df.index[0]
+    assert p.fit_end == df.index[-1]
+    assert p.period_start == df.index[0]
+    assert p.period_end == df.index[-1]
+    assert p.no_data is False
+
+
+def test_expanding_uses_initial_start_for_estimation():
+    df = _make_df("2018-01-01", "2022-12-31")
+    periods = generate_fitting_dates(
+        df, date_method=EXPANDING, interval_frequency="12M"
+    )
+
+    # There should be at least one real (non-no-data) period
+    non_empty = [p for p in periods if not p.no_data]
+    assert len(non_empty) >= 1
+
+    # For expanding, all real periods should use the original start as fit_start
+    assert all(p.fit_start == df.index[0] for p in non_empty)
+
+
+def test_rolling_moves_fit_start_forward():
+    df = _make_df("2018-01-01", "2022-12-31")
+    # use a small rollyears so the fit_start should advance away from the original start
+    periods = generate_fitting_dates(
+        df, date_method=ROLLING, rollyears=1, interval_frequency="12M"
+    )
+
+    non_empty = [p for p in periods if not p.no_data]
+    assert len(non_empty) >= 2
+
+    # At least one period should have a fit_start later than the original data start
+    assert any(p.fit_start > df.index[0] for p in non_empty)