vizflow 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

vizflow/__init__.py

@@ -5,4 +5,8 @@ Usage:
     import vizflow as vf
 """
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
+
+from .config import Config
+from .market import CN, CRYPTO, Market, Session
+from .ops import aggregate, bin, parse_time

vizflow/config.py

@@ -0,0 +1,73 @@
+"""Configuration classes for VizFlow."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Config:
+    """Central configuration for a pipeline run.
+
+    Attributes:
+        input_dir: Directory containing input files
+        output_dir: Directory for output files
+        input_pattern: Pattern for input files, e.g. "{date}.feather"
+        market: Market identifier, e.g. "CN", "crypto"
+        columns: Mapping from semantic names to actual column names
+        binwidths: Mapping from column names to bin widths
+        horizons: List of forward return horizons in seconds
+        time_cutoff: Optional time cutoff (e.g. 143000000 for 14:30:00)
+    """
+
+    input_dir: Path
+    output_dir: Path
+    input_pattern: str = "{date}.feather"
+    market: str = "CN"
+    columns: dict[str, str] = field(default_factory=dict)
+    binwidths: dict[str, float] = field(default_factory=dict)
+    group_by: list[str] = field(default_factory=list)
+    horizons: list[int] = field(default_factory=list)
+    time_cutoff: int | None = None
+
+    def __post_init__(self):
+        """Convert paths to Path objects if needed."""
+        if isinstance(self.input_dir, str):
+            self.input_dir = Path(self.input_dir)
+        if isinstance(self.output_dir, str):
+            self.output_dir = Path(self.output_dir)
+
+    def col(self, semantic: str) -> str:
+        """Get actual column name from semantic name.
+
+        Args:
+            semantic: Semantic column name (e.g. "timestamp", "price")
+
+        Returns:
+            Actual column name, or the semantic name if no mapping exists
+        """
+        return self.columns.get(semantic, semantic)
+
+    def get_input_path(self, date: str) -> Path:
+        """Get input file path for a date.
+
+        Args:
+            date: Date string, e.g. "20241001"
+
+        Returns:
+            Full path to input file
+        """
+        return self.input_dir / self.input_pattern.format(date=date)
+
+    def get_output_path(self, date: str, suffix: str = ".parquet") -> Path:
+        """Get output file path for a date.
+
+        Args:
+            date: Date string, e.g. "20241001"
+            suffix: File suffix, default ".parquet"
+
+        Returns:
+            Full path to output file
+        """
+        return self.output_dir / f"{date}{suffix}"

vizflow/market.py

@@ -0,0 +1,94 @@
+"""Market session definitions and time handling."""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class Session:
+    """A trading session.
+
+    Attributes:
+        start: Start time as "HH:MM"
+        end: End time as "HH:MM"
+    """
+
+    start: str  # "HH:MM"
+    end: str  # "HH:MM"
+
+
+@dataclass
+class Market:
+    """Market definition with trading sessions.
+
+    Attributes:
+        name: Market identifier (e.g. "CN", "crypto")
+        sessions: List of trading sessions
+    """
+
+    name: str
+    sessions: list[Session]
+
+    def elapsed_seconds(self, time: datetime) -> int:
+        """Convert wall-clock time to continuous trading seconds.
+
+        For CN market:
+          Morning:   elapsed = (hour - 9) * 3600 + (minute - 30) * 60 + second
+          Afternoon: elapsed = 7200 + (hour - 13) * 3600 + minute * 60 + second
+
+        Examples (CN):
+          09:30:00 → 0
+          11:29:59 → 7199
+          13:00:00 → 7200
+          15:00:00 → 14400
+
+        Args:
+            time: datetime object
+
+        Returns:
+            Elapsed trading seconds from market open
+        """
+        h, m, s = time.hour, time.minute, time.second
+
+        if self.name == "CN":
+            # Morning session: 09:30 - 11:30
+            if 9 <= h < 11 or (h == 11 and m < 30) or (h == 9 and m >= 30):
+                if h == 9 and m >= 30:
+                    return (m - 30) * 60 + s
+                elif h == 10:
+                    return 30 * 60 + m * 60 + s
+                elif h == 11 and m < 30:
+                    return 90 * 60 + m * 60 + s
+            # Afternoon session: 13:00 - 15:00
+            elif 13 <= h < 15 or (h == 15 and m == 0 and s == 0):
+                return 7200 + (h - 13) * 3600 + m * 60 + s
+
+        elif self.name == "crypto":
+            # 24/7: simple seconds since midnight
+            return h * 3600 + m * 60 + s
+
+        elif self.name == "KR":
+            # Korea: 09:00 - 15:30
+            if 9 <= h < 15 or (h == 15 and m <= 30):
+                return (h - 9) * 3600 + m * 60 + s
+
+        raise ValueError(f"Time {time} is outside trading hours for market {self.name}")
+
+
+# === Presets ===
+
+CN = Market(
+    name="CN",
+    sessions=[
+        Session(start="09:30", end="11:30"),  # Morning (2 hours)
+        Session(start="13:00", end="15:00"),  # Afternoon (2 hours)
+    ],
+)
+# Total: 4 hours = 14,400 seconds
+
+CRYPTO = Market(
+    name="crypto",
+    sessions=[
+        Session(start="00:00", end="24:00"),
+    ],
+)

vizflow/ops.py

@@ -0,0 +1,108 @@
+"""Core operations for data transformation."""
+
+from __future__ import annotations
+
+import polars as pl
+
+from .market import Market
+
+
+def parse_time(
+    df: pl.LazyFrame,
+    market: Market,
+    timestamp_col: str = "timestamp",
+) -> pl.LazyFrame:
+    """Add elapsed_seconds column based on market sessions.
+
+    Args:
+        df: Input LazyFrame
+        market: Market definition (only CN supported)
+        timestamp_col: Column with integer timestamp (H/HHMMSSMMM format)
+            e.g., 93012145 = 09:30:12.145, 142058425 = 14:20:58.425
+
+    Returns:
+        LazyFrame with elapsed_seconds column (float, includes milliseconds)
+        e.g., 09:30:12.145 → 12.145 (12 seconds + 145ms into trading)
+
+    Raises:
+        NotImplementedError: If market is not CN
+    """
+    if market.name != "CN":
+        raise NotImplementedError(f"Market {market.name} not supported yet")
+
+    col = pl.col(timestamp_col)
+
+    # Parse H/HHMMSSMMM → hour, minute, second, millisecond
+    h = col // 10000000  # 93012145 // 10000000 = 9
+    m = (col // 100000) % 100  # 93012145 // 100000 = 930, 930 % 100 = 30
+    s = (col // 1000) % 100  # 93012145 // 1000 = 93012, 93012 % 100 = 12
+    ms = col % 1000  # 93012145 % 1000 = 145
+
+    # CN market: calculate elapsed seconds from market open
+    # Morning: 09:30-11:30 (2 hours = 7200 seconds)
+    # Afternoon: 13:00-15:00 (2 hours = 7200 seconds)
+    base_seconds = (
+        pl.when((h == 9) & (m >= 30))
+        .then((m - 30) * 60 + s)  # 09:30-09:59
+        .when(h == 10)
+        .then(30 * 60 + m * 60 + s)  # 10:00-10:59
+        .when((h == 11) & (m < 30))
+        .then(90 * 60 + m * 60 + s)  # 11:00-11:29
+        .when((h >= 13) & (h < 15))
+        .then(7200 + (h - 13) * 3600 + m * 60 + s)  # 13:00-14:59
+        .when((h == 15) & (m == 0) & (s == 0))
+        .then(14400)  # 15:00:00 exactly
+        .otherwise(None)  # Outside trading hours
+    )
+
+    # Include milliseconds as fractional part
+    elapsed = base_seconds.cast(pl.Float64) + ms.cast(pl.Float64) / 1000.0
+
+    return df.with_columns(elapsed.alias("elapsed_seconds"))
+
+
+def bin(df: pl.LazyFrame, widths: dict[str, float]) -> pl.LazyFrame:
+    """Add bin columns for specified columns.
+
+    Args:
+        df: Input LazyFrame
+        widths: Column name to bin width mapping
+
+    Returns:
+        LazyFrame with {col}_bin columns added
+
+    Formula:
+        bin_value = round(raw_value / binwidth)
+        actual_value = bin_value * binwidth  # To recover
+    """
+    exprs = [
+        (pl.col(col) / width).round().cast(pl.Int64).alias(f"{col}_bin")
+        for col, width in widths.items()
+    ]
+    return df.with_columns(exprs)
+
+
+def aggregate(
+    df: pl.LazyFrame,
+    group_by: list[str],
+    metrics: dict[str, pl.Expr],
+) -> pl.LazyFrame:
+    """Aggregate data with custom metrics.
+
+    Args:
+        df: Input LazyFrame
+        group_by: Columns to group by
+        metrics: Name to Polars expression mapping
+
+    Returns:
+        Aggregated LazyFrame
+
+    Example:
+        metrics = {
+            "count": pl.len(),
+            "total_qty": pl.col("quantity").sum(),
+            "vwap": pl.col("notional").sum() / pl.col("quantity").sum(),
+        }
+    """
+    agg_exprs = [expr.alias(name) for name, expr in metrics.items()]
+    return df.group_by(group_by).agg(agg_exprs)

{vizflow-0.1.0.dist-info → vizflow-0.3.0.dist-info}/METADATA

@@ -1,9 +1,6 @@
 Metadata-Version: 2.4
 Name: vizflow
-Version: 0.1.0
-Project-URL: Homepage, https://github.com/vizflow/vizflow
-Project-URL: Documentation, https://github.com/vizflow/vizflow
-Project-URL: Repository, https://github.com/vizflow/vizflow
+Version: 0.3.0
 Requires-Python: >=3.9
 Requires-Dist: polars>=0.20.0
 Provides-Extra: dev

vizflow-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+vizflow/__init__.py,sha256=_2uMkH3E9eiPvkbE8-2Rmq4J5zjXxZcgqcSa3wnDI5E,244
+vizflow/config.py,sha256=1bc4maiFzeTVVMAcHyeJku4f5KcU-LlWGFpcHhjXylg,2356
+vizflow/market.py,sha256=MtNz_nnZxC66Aq-i2PXEwaFCTknijFWYZUUv6798k2s,2493
+vizflow/ops.py,sha256=-C-e_WYJCdfl8DHkSvufyE_tMkruq6AI2MBoCwt2Hqo,3304
+vizflow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vizflow-0.3.0.dist-info/METADATA,sha256=hixuCfcNqckSK81T-vosviHJoCPS60Ju6brL-tHWwdg,388
+vizflow-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+vizflow-0.3.0.dist-info/RECORD,,

vizflow-0.1.0.dist-info/RECORD

@@ -1,5 +0,0 @@
-vizflow/__init__.py,sha256=TMwTRqV4GoUUvrZQ-IrDTEZP77noJFKptpfWyMGZbmA,124
-vizflow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-vizflow-0.1.0.dist-info/METADATA,sha256=DRwpVGhhmQM06_bnpBHcYDbHxJXsy4VR4Ldmlm06kJ8,569
-vizflow-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-vizflow-0.1.0.dist-info/RECORD,,