aponyx 0.1.0__py3-none-any.whl

aponyx/data/providers/file.py

@@ -0,0 +1,86 @@
+"""
+File-based data provider for Parquet and CSV files.
+
+Handles local file loading with automatic format detection.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from ...persistence.parquet_io import load_parquet
+
+logger = logging.getLogger(__name__)
+
+
+def fetch_from_file(
+    file_path: str | Path,
+    instrument: str,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    **params: Any,
+) -> pd.DataFrame:
+    """
+    Fetch data from local Parquet or CSV file.
+
+    Parameters
+    ----------
+    file_path : str or Path
+        Path to data file.
+    instrument : str
+        Instrument identifier (for logging).
+    start_date : str or None
+        Optional start date filter (ISO format).
+    end_date : str or None
+        Optional end date filter (ISO format).
+    **params : Any
+        Additional parameters (unused for file provider).
+
+    Returns
+    -------
+    pd.DataFrame
+        Raw data loaded from file (validation happens in fetch layer).
+
+    Raises
+    ------
+    ValueError
+        If file format is not supported.
+    FileNotFoundError
+        If file does not exist.
+
+    Notes
+    -----
+    - Automatically detects Parquet vs CSV from file extension
+    - Date filtering applied after loading (files assumed small enough)
+    - Does not perform schema validation (handled by fetch layer)
+    """
+    file_path = Path(file_path)
+    logger.info("Fetching %s from file: %s", instrument, file_path)
+
+    if not file_path.exists():
+        raise FileNotFoundError(f"Data file not found: {file_path}")
+
+    # Load based on file type
+    if file_path.suffix == ".parquet":
+        df = load_parquet(file_path)
+    elif file_path.suffix == ".csv":
+        df = pd.read_csv(file_path)
+    else:
+        raise ValueError(f"Unsupported file format: {file_path.suffix}")
+
+    # Apply date filtering if requested
+    if isinstance(df.index, pd.DatetimeIndex):
+        if start_date is not None:
+            start = pd.Timestamp(start_date)
+            df = df[df.index >= start]
+            logger.debug("Filtered to start_date >= %s: %d rows", start_date, len(df))
+
+        if end_date is not None:
+            end = pd.Timestamp(end_date)
+            df = df[df.index <= end]
+            logger.debug("Filtered to end_date <= %s: %d rows", end_date, len(df))
+
+    logger.info("Loaded %d rows from file", len(df))
+    return df

aponyx/data/sample_data.py

@@ -0,0 +1,359 @@
+"""
+Synthetic data generation for testing and demonstrations.
+
+Generates realistic market data for CDX, VIX, and ETF instruments
+with configurable volatility, correlation, and trend parameters.
+"""
+
+import logging
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from ..persistence.parquet_io import save_parquet
+from .sources import FileSource
+
+logger = logging.getLogger(__name__)
+
+
+def generate_cdx_sample(
+    start_date: str = "2024-01-01",
+    periods: int = 252,
+    index_name: str = "CDX_IG",
+    tenor: str = "5Y",
+    base_spread: float = 100.0,
+    volatility: float = 5.0,
+    seed: int = 42,
+) -> pd.DataFrame:
+    """
+    Generate synthetic CDX spread data.
+
+    Parameters
+    ----------
+    start_date : str, default "2024-01-01"
+        Start date for time series.
+    periods : int, default 252
+        Number of daily observations (trading days).
+    index_name : str, default "CDX_IG"
+        Index identifier (CDX_IG, CDX_HY, CDX_XO).
+    tenor : str, default "5Y"
+        Tenor string (5Y, 10Y).
+    base_spread : float, default 100.0
+        Starting spread level in basis points.
+    volatility : float, default 5.0
+        Daily spread volatility in basis points.
+    seed : int, default 42
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    pd.DataFrame
+        CDX data with columns: date, spread, index, tenor, series
+
+    Notes
+    -----
+    - Uses geometric Brownian motion with mean reversion
+    - Spreads constrained to positive values
+    - Realistic credit market dynamics
+    """
+    logger.info(
+        "Generating CDX sample: index=%s, tenor=%s, periods=%d",
+        index_name,
+        tenor,
+        periods,
+    )
+
+    rng = np.random.default_rng(seed)
+    dates = pd.date_range(start_date, periods=periods, freq="D")
+
+    # Mean-reverting spread dynamics
+    spread = [base_spread]
+    mean_reversion_speed = 0.1
+    mean_level = base_spread
+
+    for _ in range(periods - 1):
+        drift = mean_reversion_speed * (mean_level - spread[-1])
+        shock = rng.normal(0, volatility)
+        new_spread = max(1.0, spread[-1] + drift + shock)
+        spread.append(new_spread)
+
+    df = pd.DataFrame(
+        {
+            "date": dates,
+            "spread": spread,
+            "index": [f"{index_name}_{tenor}"] * periods,
+            "tenor": [tenor] * periods,
+            "series": [42] * periods,
+        }
+    )
+
+    logger.debug("Generated CDX sample: mean_spread=%.2f", df["spread"].mean())
+    return df
+
+
+def generate_vix_sample(
+    start_date: str = "2024-01-01",
+    periods: int = 252,
+    base_vix: float = 15.0,
+    volatility: float = 2.0,
+    seed: int = 42,
+) -> pd.DataFrame:
+    """
+    Generate synthetic VIX volatility data.
+
+    Parameters
+    ----------
+    start_date : str, default "2024-01-01"
+        Start date for time series.
+    periods : int, default 252
+        Number of daily observations.
+    base_vix : float, default 15.0
+        Starting VIX level.
+    volatility : float, default 2.0
+        Volatility of volatility (vol of vol).
+    seed : int, default 42
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    pd.DataFrame
+        VIX data with columns: date, close
+
+    Notes
+    -----
+    - Uses mean-reverting process with occasional spikes
+    - VIX constrained to positive values
+    """
+    logger.info("Generating VIX sample: periods=%d", periods)
+
+    rng = np.random.default_rng(seed)
+    dates = pd.date_range(start_date, periods=periods, freq="D")
+
+    # Mean-reverting VIX with spike potential
+    vix_close = [base_vix]
+    mean_reversion_speed = 0.15
+    mean_level = base_vix
+
+    for i in range(periods - 1):
+        # Occasional spike (5% probability)
+        if rng.random() < 0.05:
+            spike = rng.uniform(5, 15)
+        else:
+            spike = 0
+
+        drift = mean_reversion_speed * (mean_level - vix_close[-1])
+        shock = rng.normal(0, volatility)
+        new_vix = max(8.0, vix_close[-1] + drift + shock + spike)
+        vix_close.append(new_vix)
+
+    df = pd.DataFrame(
+        {
+            "date": dates,
+            "close": vix_close,
+        }
+    )
+
+    logger.debug("Generated VIX sample: mean=%.2f", df["close"].mean())
+    return df
+
+
+def generate_etf_sample(
+    start_date: str = "2024-01-01",
+    periods: int = 252,
+    ticker: str = "HYG",
+    base_price: float = 80.0,
+    volatility: float = 0.5,
+    seed: int = 42,
+) -> pd.DataFrame:
+    """
+    Generate synthetic credit ETF price data.
+
+    Parameters
+    ----------
+    start_date : str, default "2024-01-01"
+        Start date for time series.
+    periods : int, default 252
+        Number of daily observations.
+    ticker : str, default "HYG"
+        ETF ticker symbol (HYG, LQD).
+    base_price : float, default 80.0
+        Starting price.
+    volatility : float, default 0.5
+        Daily price volatility.
+    seed : int, default 42
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    pd.DataFrame
+        ETF data with columns: date, close, ticker
+
+    Notes
+    -----
+    - Uses geometric Brownian motion
+    - Prices constrained to positive values
+    """
+    logger.info("Generating ETF sample: ticker=%s, periods=%d", ticker, periods)
+
+    rng = np.random.default_rng(seed)
+    dates = pd.date_range(start_date, periods=periods, freq="D")
+
+    # Geometric Brownian motion for prices
+    returns = rng.normal(0.0001, volatility / base_price, periods)
+    price = base_price * np.exp(np.cumsum(returns))
+
+    df = pd.DataFrame(
+        {
+            "date": dates,
+            "close": price,
+            "ticker": [ticker] * periods,
+        }
+    )
+
+    logger.debug("Generated ETF sample: mean_price=%.2f", df["close"].mean())
+    return df
+
+
+def generate_full_sample_dataset(
+    output_dir: str = "data/raw",
+    start_date: str = "2023-01-01",
+    periods: int = 252,
+    seed: int = 42,
+) -> dict[str, str]:
+    """
+    Generate complete sample dataset for testing.
+
+    Parameters
+    ----------
+    output_dir : str, default "data/raw"
+        Directory to save Parquet files.
+    start_date : str, default "2023-01-01"
+        Start date for all time series.
+    periods : int, default 252
+        Number of daily observations.
+    seed : int, default 42
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    dict[str, str]
+        Dictionary mapping data type to file path.
+
+    Notes
+    -----
+    Generates and saves:
+    - CDX IG 5Y spreads
+    - CDX HY 5Y spreads
+    - VIX volatility
+    - HYG and LQD ETF prices
+    """
+    from pathlib import Path
+
+    logger.info("Generating full sample dataset: output_dir=%s", output_dir)
+
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    # Generate CDX data (multiple indices)
+    cdx_ig = generate_cdx_sample(
+        start_date=start_date,
+        periods=periods,
+        index_name="CDX_IG",
+        tenor="5Y",
+        base_spread=70.0,
+        volatility=3.0,
+        seed=seed,
+    )
+
+    cdx_hy = generate_cdx_sample(
+        start_date=start_date,
+        periods=periods,
+        index_name="CDX_HY",
+        tenor="5Y",
+        base_spread=350.0,
+        volatility=15.0,
+        seed=seed + 1,
+    )
+
+    cdx_all = pd.concat([cdx_ig, cdx_hy], ignore_index=True)
+    cdx_path = output_path / "cdx_spreads.parquet"
+    save_parquet(cdx_all, cdx_path)
+
+    # Generate VIX data
+    vix = generate_vix_sample(
+        start_date=start_date, periods=periods, base_vix=16.0, seed=seed + 2
+    )
+    vix_path = output_path / "vix.parquet"
+    save_parquet(vix, vix_path)
+
+    # Generate ETF data (multiple tickers)
+    hyg = generate_etf_sample(
+        start_date=start_date,
+        periods=periods,
+        ticker="HYG",
+        base_price=75.0,
+        volatility=0.6,
+        seed=seed + 3,
+    )
+
+    lqd = generate_etf_sample(
+        start_date=start_date,
+        periods=periods,
+        ticker="LQD",
+        base_price=110.0,
+        volatility=0.4,
+        seed=seed + 4,
+    )
+
+    etf_all = pd.concat([hyg, lqd], ignore_index=True)
+    etf_path = output_path / "etf_prices.parquet"
+    save_parquet(etf_all, etf_path)
+
+    file_paths = {
+        "cdx": str(cdx_path),
+        "vix": str(vix_path),
+        "etf": str(etf_path),
+    }
+
+    logger.info("Sample dataset generated: %s", file_paths)
+    return file_paths
+
+
+def generate_full_sample_sources(
+    output_dir: str = "data/raw",
+    start_date: str = "2023-01-01",
+    periods: int = 252,
+    seed: int = 42,
+) -> dict[str, FileSource]:
+    """
+    Generate complete sample dataset and return FileSource configs.
+
+    Parameters
+    ----------
+    output_dir : str, default "data/raw"
+        Directory to save Parquet files.
+    start_date : str, default "2023-01-01"
+        Start date for all time series.
+    periods : int, default 252
+        Number of daily observations.
+    seed : int, default 42
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    dict[str, FileSource]
+        Dictionary mapping data type to FileSource configuration.
+
+    Notes
+    -----
+    Convenience wrapper around generate_full_sample_dataset that returns
+    FileSource objects ready to use with fetch functions.
+    """
+    file_paths = generate_full_sample_dataset(output_dir, start_date, periods, seed)
+
+    return {
+        "cdx": FileSource(Path(file_paths["cdx"])),
+        "vix": FileSource(Path(file_paths["vix"])),
+        "etf": FileSource(Path(file_paths["etf"])),
+    }

aponyx/data/schemas.py

@@ -0,0 +1,65 @@
+"""
+Data schemas and validation rules for market data.
+
+Defines expected column names, types, and constraints for each data source.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class CDXSchema:
+    """Schema for CDX index data."""
+
+    date_col: str = "date"
+    spread_col: str = "spread"
+    index_col: str = "index"  # e.g., "CDX_IG_5Y"
+    tenor_col: str = "tenor"  # e.g., "5Y", "10Y"
+    series_col: str = "series"  # CDX series number
+
+    required_cols: tuple[str, ...] = ("date", "spread", "index")
+    optional_cols: tuple[str, ...] = ("tenor", "series")
+
+    # Validation constraints
+    min_spread: float = 0.0  # Spreads in basis points
+    max_spread: float = 10000.0  # 100% spread cap
+
+
+@dataclass(frozen=True)
+class VIXSchema:
+    """Schema for VIX volatility index data."""
+
+    date_col: str = "date"
+    close_col: str = "close"
+
+    required_cols: tuple[str, ...] = ("date", "close")
+    optional_cols: tuple[str, ...] = ()
+
+    # Validation constraints
+    min_vix: float = 0.0
+    max_vix: float = 200.0  # Extreme stress cap
+
+
+@dataclass(frozen=True)
+class ETFSchema:
+    """Schema for credit ETF data (HYG, LQD)."""
+
+    date_col: str = "date"
+    close_col: str = "close"
+    ticker_col: str = "ticker"
+
+    required_cols: tuple[str, ...] = ("date", "close", "ticker")
+    optional_cols: tuple[str, ...] = ()
+
+    # Validation constraints
+    min_price: float = 0.0
+    max_price: float = 10000.0  # Sanity check
+
+
+# Schema registry for runtime lookup
+SCHEMAS: dict[str, Any] = {
+    "cdx": CDXSchema(),
+    "vix": VIXSchema(),
+    "etf": ETFSchema(),
+}

aponyx/data/sources.py

@@ -0,0 +1,135 @@
+"""
+Data source configuration for pluggable data providers.
+
+Defines source types (file, Bloomberg, API) and factory for provider resolution.
+"""
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, Any
+
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class FileSource:
+    """
+    File-based data source (Parquet or CSV).
+
+    Attributes
+    ----------
+    path : Path
+        Path to the data file.
+    """
+
+    path: Path
+
+    def __post_init__(self) -> None:
+        """Convert path to Path object if string provided."""
+        if isinstance(self.path, str):
+            object.__setattr__(self, "path", Path(self.path))
+
+
+@dataclass(frozen=True)
+class BloombergSource:
+    """
+    Bloomberg Terminal data source.
+
+    Notes
+    -----
+    Requires active Bloomberg Terminal session.
+    Connection is handled automatically by xbbg wrapper.
+    """
+
+    pass
+
+
+@dataclass(frozen=True)
+class APISource:
+    """
+    Generic REST API data source.
+
+    Attributes
+    ----------
+    endpoint : str
+        API endpoint URL.
+    params : dict[str, Any]
+        Additional request parameters.
+    """
+
+    endpoint: str
+    params: dict[str, Any] | None = None
+
+
+# Union type for all data sources
+DataSource = FileSource | BloombergSource | APISource
+
+
+class DataProvider(Protocol):
+    """
+    Protocol for data provider implementations.
+
+    All providers must implement fetch method with standardized signature.
+    """
+
+    def fetch(
+        self,
+        instrument: str,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        **params: Any,
+    ) -> pd.DataFrame:
+        """
+        Fetch data for specified instrument and date range.
+
+        Parameters
+        ----------
+        instrument : str
+            Instrument identifier (e.g., 'CDX.NA.IG.5Y', 'VIX', 'HYG').
+        start_date : str or None
+            Start date in ISO format (YYYY-MM-DD).
+        end_date : str or None
+            End date in ISO format (YYYY-MM-DD).
+        **params : Any
+            Provider-specific parameters.
+
+        Returns
+        -------
+        pd.DataFrame
+            Data with DatetimeIndex.
+        """
+        ...
+
+
+def resolve_provider(source: DataSource) -> str:
+    """
+    Resolve data source to provider type identifier.
+
+    Parameters
+    ----------
+    source : DataSource
+        Data source configuration.
+
+    Returns
+    -------
+    str
+        Provider type: 'file', 'bloomberg', or 'api'.
+
+    Examples
+    --------
+    >>> resolve_provider(FileSource("data.parquet"))
+    'file'
+    >>> resolve_provider(BloombergSource())
+    'bloomberg'
+    """
+    if isinstance(source, FileSource):
+        return "file"
+    elif isinstance(source, BloombergSource):
+        return "bloomberg"
+    elif isinstance(source, APISource):
+        return "api"
+    else:
+        raise ValueError(f"Unknown source type: {type(source)}")