feat: add slogan SVG to README

Author: quantbai

README.md

@@ -1,9 +1,13 @@
-# ⚡Elvers
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/quantbai/elvers/main/assets/elvers.svg" alt="Elvers" width="500">
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![Polars](https://img.shields.io/badge/Polars-1.37.1-green.svg)](https://pola.rs/)
 
+</div>
+
 High-performance multi-factor quantitative framework built on Polars.
 
 Named after **ELVES**, the atmospheric lightning phenomenon that occurs at extreme speed.

assets/elvers.svg

@@ -21,10 +21,10 @@
     ts_zscore, ts_corr, ts_covariance, ts_product,
     ts_arg_max, ts_arg_min, ts_decay_linear, ts_av_diff, ts_scale,
     ts_quantile, ts_cv, ts_autocorr,
-    ts_count_nans,
+    ts_count_nans, ts_backfill,
 
     rank, zscore, mean, median,
-    scale, normalize, quantile, spread, signal,
+    scale, normalize, quantile, signal,
 
     log, ln, sqrt, sign, power, signed_power,
     inverse, s_log_1p, maximum, minimum, where,
@@ -47,10 +47,10 @@
     "ts_zscore", "ts_corr", "ts_covariance", "ts_product",
     "ts_arg_max", "ts_arg_min", "ts_decay_linear", "ts_av_diff", "ts_scale",
     "ts_quantile", "ts_cv", "ts_autocorr",
-    "ts_count_nans",
+    "ts_count_nans", "ts_backfill",
 
     "rank", "zscore", "mean", "median",
-    "scale", "normalize", "quantile", "spread", "signal",
+    "scale", "normalize", "quantile", "signal",
 
     "log", "ln", "sqrt", "sign", "power", "signed_power",
     "inverse", "s_log_1p", "maximum", "minimum", "where",

elvers/__init__.py

@@ -12,7 +12,8 @@ def load(source: Union[str, Path, pl.LazyFrame, pl.DataFrame], balance: bool = T
     """Load data and return a managed Panel object."""
     lf = _read_source(source)
 
-    if "timestamp" not in lf.columns or "symbol" not in lf.columns:
+    schema = lf.collect_schema()
+    if "timestamp" not in schema.names() or "symbol" not in schema.names():
         raise ValueError("Source must contain 'timestamp' and 'symbol' columns.")
 
     if balance:

elvers/io/loader.py

@@ -79,7 +79,7 @@ def balance_panel(lf: pl.LazyFrame) -> Tuple[pl.LazyFrame, PanelInfo]:
     if start_date is None or end_date is None:
         raise ValueError("Data must have 'timestamp' column with valid dates.")
 
-    ts_type = lf.schema["timestamp"]
+    ts_type = lf.collect_schema()["timestamp"]
 
     skeleton = (
         pl.datetime_range(start=start_date, end=end_date, interval="1d", eager=True)
@@ -99,7 +99,7 @@ def balance_panel(lf: pl.LazyFrame) -> Tuple[pl.LazyFrame, PanelInfo]:
     n_days = (end_date - start_date).days + 1
     n_rows = len(symbols) * n_days
 
-    original_cols = [c for c in lf.columns if c not in ("timestamp", "symbol")]
+    original_cols = [c for c in lf.collect_schema().names() if c not in ("timestamp", "symbol")]
     null_counts_row = balanced_lf.select([
         pl.col(c).null_count() for c in original_cols
     ]).collect().row(0)

elvers/io/panel.py

@@ -27,6 +27,7 @@
     ts_cv,
     ts_autocorr,
     ts_count_nans,
+    ts_backfill,
 )
 
 from .cross_sectional import (
@@ -37,7 +38,6 @@
     scale,
     normalize,
     quantile,
-    spread,
     signal,
 )
 
@@ -73,10 +73,10 @@
     "ts_zscore", "ts_corr", "ts_covariance", "ts_product",
     "ts_arg_max", "ts_arg_min", "ts_decay_linear", "ts_av_diff", "ts_scale",
     "ts_quantile", "ts_cv", "ts_autocorr",
-    "ts_count_nans",
+    "ts_count_nans", "ts_backfill",
 
     "rank", "zscore", "mean", "median",
-    "scale", "normalize", "quantile", "spread", "signal",
+    "scale", "normalize", "quantile", "signal",
 
     "log", "ln", "sqrt", "sign", "power", "signed_power",
     "inverse", "s_log_1p", "maximum", "minimum", "where",

elvers/ops/__init__.py

@@ -76,15 +76,6 @@ def quantile(f: Factor, driver: str = "gaussian", sigma: float = 1.0) -> Factor:
     )
 
 
-def spread(f: Factor, pct: float = 0.5) -> Factor:
-    """Simple long/short: top pct% gets +0.5, bottom pct% gets -0.5."""
-    rank_expr = f.expr.rank(method="average") / f.expr.count()
-    long_short = pl.when(rank_expr >= (1 - pct)).then(0.5).when(rank_expr <= pct).then(-0.5).otherwise(0.0)
-    return Factor(
-        long_short.over("timestamp"),
-        f"spread({f.name},{pct})"
-    )
-
 
 def signal(f: Factor) -> Factor:
     """Convert to trading weights (long +0.5, short -0.5, net zero)."""

elvers/ops/cross_sectional.py

@@ -72,18 +72,38 @@ def ts_median(f: Factor, window: int) -> Factor:
 
 
 def ts_rank(f: Factor, window: int, constant: float = 0) -> Factor:
-    """Percentile rank of current value within rolling window (WQ-style)."""
-    rank_expr = f.expr.rolling_rank(window_size=window, min_samples=window) / (window + 1) + constant
+    """Percentile rank of current value within rolling window."""
+    def rank_window(s):
+        if s.is_nan().any() or s.n_unique() == 1:
+            return None
+        vals = s.to_numpy()
+        sorted_idx = vals.argsort()
+        rank_array = sorted_idx.argsort() + 1
+        return float(rank_array[-1]) / len(vals)
+    
+    rank_expr = f.expr.rolling_map(rank_window, window_size=window, min_periods=window)
     return Factor(
-        rank_expr.over("symbol"),
+        rank_expr.over("symbol") + constant,
         f"ts_rank({f.name},{window})"
     )
 
 
 def ts_skewness(f: Factor, window: int) -> Factor:
-    """Rolling skewness over N periods."""
+    """Rolling skewness over N periods (sample skewness with bias correction)."""
+    n = window
+    mean_expr = f.expr.rolling_mean(window_size=window, min_periods=window)
+    diff = f.expr - mean_expr
+    
+    sum_cube = (diff ** 3).rolling_sum(window_size=window, min_periods=window)
+    sum_sq = (diff ** 2).rolling_sum(window_size=window, min_periods=window)
+    
+    numerator = sum_cube * n
+    denominator = (sum_sq ** 1.5) * ((n - 1) * (n - 2))
+    
+    skew_expr = numerator / denominator
+    
     return Factor(
-        f.expr.rolling_skew(window_size=window).over("symbol"),
+        skew_expr.over("symbol"),
         f"ts_skewness({f.name},{window})"
     )
 
@@ -198,14 +218,9 @@ def ts_cv(f: Factor, window: int) -> Factor:
 def ts_autocorr(a: Factor, window: int, lag: int = 1) -> Factor:
     """Rolling autocorrelation with specified lag."""
     lagged = a.expr.shift(lag)
-    # Manual rolling corr between a and lagged version
-    cov_expr = (a.expr * lagged).rolling_mean(window_size=window, min_periods=window) - \
-               a.expr.rolling_mean(window_size=window, min_periods=window) * \
-               lagged.rolling_mean(window_size=window, min_periods=window)
-    std_a = a.expr.rolling_std(window_size=window, min_periods=window)
-    std_lag = lagged.rolling_std(window_size=window, min_periods=window)
-    return Factor(
-        (cov_expr / (std_a * std_lag)).over("symbol"),
+    corr_expr = pl.rolling_corr(a.expr, lagged, window_size=window, min_periods=window, ddof=1)
+    return Factor(
+        corr_expr.over("symbol"),
         f"ts_autocorr({a.name},{window},{lag})"
     )
 
@@ -216,3 +231,31 @@ def ts_count_nans(f: Factor, window: int) -> Factor:
         f.expr.is_null().cast(pl.Int32).rolling_sum(window_size=window, min_periods=1).over("symbol"),
         f"ts_count_nans({f.name},{window})"
     )
+
+
+def ts_backfill(f: Factor, window: int, k: int = 1) -> Factor:
+    """Backfill NaN with k-th most recent non-NaN in window.
+    
+    Parameters
+    ----------
+    f : Factor
+        Input factor
+    window : int
+        Maximum lookback window for filling
+    k : int, default 1
+        Which recent non-NaN to use (1=most recent)
+    
+    Returns
+    -------
+    Factor
+        Factor with NaN backfilled
+    """
+    if k == 1:
+        filled_expr = f.expr.forward_fill(limit=window).over("symbol")
+    else:
+        filled_expr = f.expr.shift(k - 1).forward_fill(limit=window).over("symbol")
+    
+    return Factor(
+        filled_expr,
+        f"ts_backfill({f.name},{window},{k})"
+    )