driftdep 0.1.0__tar.gz

driftdep-0.1.0/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip3 --version)",
+      "Read(//Users/vivekchaudhary/.local/bin/**)",
+      "Read(//opt/homebrew/bin/**)",
+      "Read(//Users/vivekchaudhary/.cargo/bin/**)",
+      "Read(//usr/local/bin/**)",
+      "Read(//opt/homebrew/**)",
+      "Bash(curl -LsSf https://astral.sh/uv/install.sh)",
+      "Bash(sh)",
+      "Bash(~/.local/bin/uv *)"
+    ]
+  }
+}

driftdep-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

driftdep-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,88 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Verify wheel contents (research/ must be absent)
+        run: |
+          pip install twine
+          twine check dist/*
+          python - <<'EOF'
+          import zipfile, sys, pathlib
+          wheels = list(pathlib.Path("dist").glob("*.whl"))
+          assert wheels, "No wheel found in dist/"
+          for whl in wheels:
+              with zipfile.ZipFile(whl) as z:
+                  names = z.namelist()
+                  bad = [n for n in names if n.startswith("research/")]
+                  if bad:
+                      print(f"ERROR: research/ found in wheel: {bad}", file=sys.stderr)
+                      sys.exit(1)
+          print("Wheel contents OK — research/ is absent.")
+          EOF
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/driftdep
+    permissions:
+      id-token: write   # OIDC trusted publishing
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/driftdep
+    permissions:
+      id-token: write   # OIDC trusted publishing
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

driftdep-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+env/
+venv/
+.uv/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# Research outputs (large, reproducible from manifest.yaml seeds)
+research/results/*
+!research/results/.gitkeep
+research/data/raw/
+research/data/external/
+research/data/cache/
+
+# Simulation artefacts
+*.pkl
+*.parquet
+*.feather
+*.h5
+*.hdf5
+
+# Figures (generated by make figures / make reproduce)
+*.pdf
+*.png
+*.svg
+
+# Raw data (download scripts in research/data/ provided instead)
+*.csv
+
+# Package / distribution
+*.whl
+*.tar.gz
+MANIFEST
+
+# Mount point (local only)
+mnt/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+CLAUDE.md

driftdep-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vivek Chaudhary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

driftdep-0.1.0/Makefile

@@ -0,0 +1,67 @@
+.PHONY: test test-fast lint typecheck reproduce figures data clean build
+
+# ── development ────────────────────────────────────────────────────────────────
+
+test:
+	uv run pytest
+
+test-fast:
+	uv run pytest -m "not slow"
+
+lint:
+	uv run ruff check . && uv run ruff format --check .
+
+typecheck:
+	uv run mypy src/driftdep
+
+build:
+	uv build
+
+# ── paper reproduction ─────────────────────────────────────────────────────────
+# Regenerates every figure and table from seeds; outputs land in research/results/.
+# Figures are deterministic (no timestamps) so diffs are clean.
+
+reproduce:
+	@echo "=== Logging library versions ==="
+	uv run python -c "\
+import sys, importlib, csv, pathlib; \
+libs = ['numpy','scipy','statsmodels','arch','dcor','pandas','matplotlib','joblib']; \
+rows = []; \
+[rows.append({'package': l, 'version': getattr(importlib.import_module(l), '__version__', '?')}) for l in libs]; \
+path = pathlib.Path('research/results/environment.txt'); \
+path.write_text('\n'.join(f\"{r['package']}=={r['version']}\" for r in rows) + '\n'); \
+print('Versions logged to', path)"
+	@echo "=== Experiments ==="
+	uv run python -m research.experiments.size screen
+	uv run python -m research.experiments.size full
+	uv run python -m research.experiments.power screen
+	uv run python -m research.experiments.power multi
+	uv run python -m research.experiments.streaming screen
+	uv run python -m research.experiments.compute_cost
+	uv run python -m research.experiments.realdata
+	@echo "=== Figures and tables ==="
+	$(MAKE) figures
+
+figures:
+	uv run python -m research.analysis.fig1_false_alarm
+	uv run python -m research.analysis.fig2_ks_null
+	uv run python -m research.analysis.fig3_ess_indicator
+	uv run python -m research.analysis.fig4_size_after_correction
+	uv run python -m research.analysis.fig5_power
+	uv run python -m research.analysis.fig6_arl
+	uv run python -m research.analysis.table1_size
+	uv run python -m research.analysis.table2_realdata
+
+# ── data download (separate from reproduce; requires internet) ─────────────────
+
+data:
+	uv run python -m research.data.download_fred
+	uv run python -m research.data.download_uci
+	uv run python -m research.data.download_m4
+
+# ── housekeeping ───────────────────────────────────────────────────────────────
+
+clean:
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true
+	rm -rf dist/ build/ src/*.egg-info/

driftdep-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: driftdep
+Version: 0.1.0
+Summary: Dependence-robust two-sample drift tests for serially correlated feature streams
+Author-email: Vivek Chaudhary <vivekch2018@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: MLOps,drift detection,monitoring,serial dependence,two-sample test
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: research
+Requires-Dist: arch>=6.0; extra == 'research'
+Requires-Dist: dcor>=0.6; extra == 'research'
+Requires-Dist: joblib>=1.3; extra == 'research'
+Requires-Dist: matplotlib>=3.7; extra == 'research'
+Requires-Dist: pandas>=2.0; extra == 'research'
+Requires-Dist: statsmodels>=0.14; extra == 'research'
+Description-Content-Type: text/markdown
+
+# driftdep
+
+**Your drift monitor is lying to you.**
+If your feature windows are autocorrelated — and they almost always are —
+standard two-sample tests (KS, CvM, AD, MMD) over-reject by 2–10× at realistic
+dependencies.  A single AR(1) coefficient of ρ=0.7 inflates the KS false-alarm
+rate from 5% to 35%.  Long-memory processes (ARFIMA) push it even higher.
+
+`driftdep` is a drop-in, dependence-robust replacement that corrects for serial
+dependence via ESS-adjusted block permutation by default.
+
+```python
+# Before — unreliable under serial dependence
+from scipy.stats import ks_2samp
+stat, p = ks_2samp(x_ref, x_new)   # p-value too small when data is autocorrelated
+
+# After — calibrated by default
+from driftdep import ks_2samp
+stat, p = ks_2samp(x_ref, x_new)   # same call, same unpacking, correct p-value
+```
+
+## Install
+
+```bash
+pip install driftdep
+```
+
+Requires Python ≥ 3.10, numpy ≥ 1.24, scipy ≥ 1.10 only.
+Heavy research dependencies (arch, statsmodels, dcor) are optional:
+
+```bash
+pip install "driftdep[research]"   # for all corrections and download scripts
+```
+
+## Quick start
+
+```python
+import numpy as np
+import driftdep
+
+rng = np.random.default_rng(0)
+x_ref = rng.standard_normal(500)
+x_new = rng.standard_normal(500)   # same distribution; should not alarm
+
+stat, p = driftdep.ks_2samp(x_ref, x_new)
+# p ≈ 0.6 — no false alarm (correct even if the series is autocorrelated)
+
+# Full result with diagnostics
+result = driftdep.drift_test(x_ref, x_new, statistic="ks")
+print(result.pvalue)        # dependence-corrected p-value
+print(result.n_eff)         # effective sample size estimate
+print(result.block_length)  # block length used by block permutation
+```
+
+## API
+
+```python
+driftdep.drift_test(
+    x, y, *,
+    statistic="ks",           # "ks", "cvm", "ad", "energy", "mmd",
+                              # "wasserstein", "psi", "js"
+    correction="block_perm",  # default engine; see table below
+    block_length=None,        # None → auto (Politis–White 2004)
+    ess_adjust=True,          # compute and report indicator-transform ESS
+    n_resamples=999,          # permutation resamples
+    alpha=0.05,
+    rng=None,                 # numpy Generator, int seed, or None
+) -> DriftResult
+```
+
+`DriftResult` unpacks as `(statistic, pvalue)` for drop-in compatibility and
+also exposes `.pvalue`, `.n_eff`, `.block_length`, `.correction`.
+
+### Available corrections
+
+| `correction=`   | Description                                         | Extra deps     |
+|-----------------|-----------------------------------------------------|----------------|
+| `block_perm`    | Block permutation, Politis–White block length       | —              |
+| `ess_adjust`    | ESS-adjusted analytic null (cheapest; KS/CvM/AD)   | —              |
+| `naive`         | i.i.d. null — baseline / reference only            | —              |
+| `thinning`      | Keep every k-th obs to approximate independence     | —              |
+| `dep_wild`      | Dependent wild bootstrap (Shao 2010)                | —              |
+| `mbb`           | Moving block bootstrap (Künsch 1989)                | `[research]`   |
+| `cbb`           | Circular block bootstrap                            | `[research]`   |
+| `stationary`    | Stationary bootstrap (Politis–Romano 1994)          | `[research]`   |
+| `prewhiten`     | **Cautionary only** — changes the hypothesis        | `[research]`   |
+
+## Method
+
+`driftdep` benchmarks and operationalizes dependence corrections for two-sample
+distributional drift tests.  The core insight: when observations within a
+monitoring window are autocorrelated, the i.i.d. null distribution of KS, CvM,
+and related statistics is stochastically dominated, causing severe over-rejection.
+
+The recommended default — ESS-adjusted block permutation — permutes contiguous
+blocks of length *b* (preserving within-block dependence) and selects *b*
+automatically via Politis–White (2004).  Empirical size recovers to ≈ α across
+AR(1), ARFIMA, and GARCH dependence structures.  Size-adjusted power is within
+5–7 percentage points of the uncalibrated naive test at moderate effect sizes.
+
+All corrections already exist in the literature; this package operationalizes
+them in a unified interface with a validated default.
+
+## Reproduce paper results
+
+```bash
+git clone https://github.com/vivekch2018/driftdep
+cd driftdep
+pip install -e ".[research]"
+make data        # download public datasets (requires internet)
+make reproduce   # regenerate all figures and tables from seeds
+```
+
+## Citation
+
+```bibtex
+@misc{chaudhary2025driftdep,
+  author  = {Chaudhary, Vivek},
+  title   = {Two-Sample Drift Tests Break Under Serial Dependence:
+             A Benchmark and Deployable Correction},
+  year    = {2025},
+  note    = {Preprint},
+  url     = {https://github.com/vivekch2018/driftdep},
+}
+```
+
+## License
+
+MIT

driftdep-0.1.0/README.md

@@ -0,0 +1,129 @@
+# driftdep
+
+**Your drift monitor is lying to you.**
+If your feature windows are autocorrelated — and they almost always are —
+standard two-sample tests (KS, CvM, AD, MMD) over-reject by 2–10× at realistic
+dependencies.  A single AR(1) coefficient of ρ=0.7 inflates the KS false-alarm
+rate from 5% to 35%.  Long-memory processes (ARFIMA) push it even higher.
+
+`driftdep` is a drop-in, dependence-robust replacement that corrects for serial
+dependence via ESS-adjusted block permutation by default.
+
+```python
+# Before — unreliable under serial dependence
+from scipy.stats import ks_2samp
+stat, p = ks_2samp(x_ref, x_new)   # p-value too small when data is autocorrelated
+
+# After — calibrated by default
+from driftdep import ks_2samp
+stat, p = ks_2samp(x_ref, x_new)   # same call, same unpacking, correct p-value
+```
+
+## Install
+
+```bash
+pip install driftdep
+```
+
+Requires Python ≥ 3.10, numpy ≥ 1.24, scipy ≥ 1.10 only.
+Heavy research dependencies (arch, statsmodels, dcor) are optional:
+
+```bash
+pip install "driftdep[research]"   # for all corrections and download scripts
+```
+
+## Quick start
+
+```python
+import numpy as np
+import driftdep
+
+rng = np.random.default_rng(0)
+x_ref = rng.standard_normal(500)
+x_new = rng.standard_normal(500)   # same distribution; should not alarm
+
+stat, p = driftdep.ks_2samp(x_ref, x_new)
+# p ≈ 0.6 — no false alarm (correct even if the series is autocorrelated)
+
+# Full result with diagnostics
+result = driftdep.drift_test(x_ref, x_new, statistic="ks")
+print(result.pvalue)        # dependence-corrected p-value
+print(result.n_eff)         # effective sample size estimate
+print(result.block_length)  # block length used by block permutation
+```
+
+## API
+
+```python
+driftdep.drift_test(
+    x, y, *,
+    statistic="ks",           # "ks", "cvm", "ad", "energy", "mmd",
+                              # "wasserstein", "psi", "js"
+    correction="block_perm",  # default engine; see table below
+    block_length=None,        # None → auto (Politis–White 2004)
+    ess_adjust=True,          # compute and report indicator-transform ESS
+    n_resamples=999,          # permutation resamples
+    alpha=0.05,
+    rng=None,                 # numpy Generator, int seed, or None
+) -> DriftResult
+```
+
+`DriftResult` unpacks as `(statistic, pvalue)` for drop-in compatibility and
+also exposes `.pvalue`, `.n_eff`, `.block_length`, `.correction`.
+
+### Available corrections
+
+| `correction=`   | Description                                         | Extra deps     |
+|-----------------|-----------------------------------------------------|----------------|
+| `block_perm`    | Block permutation, Politis–White block length       | —              |
+| `ess_adjust`    | ESS-adjusted analytic null (cheapest; KS/CvM/AD)   | —              |
+| `naive`         | i.i.d. null — baseline / reference only            | —              |
+| `thinning`      | Keep every k-th obs to approximate independence     | —              |
+| `dep_wild`      | Dependent wild bootstrap (Shao 2010)                | —              |
+| `mbb`           | Moving block bootstrap (Künsch 1989)                | `[research]`   |
+| `cbb`           | Circular block bootstrap                            | `[research]`   |
+| `stationary`    | Stationary bootstrap (Politis–Romano 1994)          | `[research]`   |
+| `prewhiten`     | **Cautionary only** — changes the hypothesis        | `[research]`   |
+
+## Method
+
+`driftdep` benchmarks and operationalizes dependence corrections for two-sample
+distributional drift tests.  The core insight: when observations within a
+monitoring window are autocorrelated, the i.i.d. null distribution of KS, CvM,
+and related statistics is stochastically dominated, causing severe over-rejection.
+
+The recommended default — ESS-adjusted block permutation — permutes contiguous
+blocks of length *b* (preserving within-block dependence) and selects *b*
+automatically via Politis–White (2004).  Empirical size recovers to ≈ α across
+AR(1), ARFIMA, and GARCH dependence structures.  Size-adjusted power is within
+5–7 percentage points of the uncalibrated naive test at moderate effect sizes.
+
+All corrections already exist in the literature; this package operationalizes
+them in a unified interface with a validated default.
+
+## Reproduce paper results
+
+```bash
+git clone https://github.com/vivekch2018/driftdep
+cd driftdep
+pip install -e ".[research]"
+make data        # download public datasets (requires internet)
+make reproduce   # regenerate all figures and tables from seeds
+```
+
+## Citation
+
+```bibtex
+@misc{chaudhary2025driftdep,
+  author  = {Chaudhary, Vivek},
+  title   = {Two-Sample Drift Tests Break Under Serial Dependence:
+             A Benchmark and Deployable Correction},
+  year    = {2025},
+  note    = {Preprint},
+  url     = {https://github.com/vivekch2018/driftdep},
+}
+```
+
+## License
+
+MIT

driftdep-0.1.0/manifest.yaml

@@ -0,0 +1,99 @@
+# manifest.yaml — factor grid and root seed for driftdep paper experiments.
+# All results are fully reproducible from this file.
+# See CLAUDE.md §7 for the reproducibility contract.
+# See the paper plan §8 for the scientific design rationale.
+
+root_seed: 20250101
+
+# ── experimental design ────────────────────────────────────────────────────────
+# Strategy: screening design first (vary one factor family at a time around the
+# baseline cell), then focused full-factorial on the interesting region.
+# This avoids the millions-of-cells full cross-product while covering the space.
+
+screening:
+  description: >
+    Vary one factor family at a time around the baseline cell to identify
+    where size inflation is largest. Used to select the focused-factorial region.
+  baseline:
+    test: ks
+    correction: naive
+    dgp: ar1
+    rho: 0.5
+    n: 500
+    marginal: gaussian
+    alpha: 0.05
+    n_reps: 1000
+
+focused_factorial:
+  description: >
+    Full factorial on the region identified by screening. This is the source
+    of Table 1, Figs 1, 4, 5, 6 in the paper.
+  tests:
+    - ks
+    - cvm
+    - ad
+    - energy
+    - mmd_rbf
+    - wass
+    - psi
+    - js
+  corrections:
+    - naive
+    - block_perm
+    - mbb
+    - cbb
+    - stationary
+    - dep_wild
+    - ess_adjust
+    - thinning
+    - prewhiten
+  dgps:
+    - ar1
+    - arma11
+    - ar2cyclic
+    - arfima0d0
+    - garch11
+    - seasonal_ar
+    - heavy_tail_ar1
+  rho_grid: [0.0, 0.3, 0.5, 0.7, 0.9, -0.3]
+  arfima_d_grid: [0.1, 0.2, 0.4]
+  n_grid: [100, 250, 500, 1000, 2000]
+  marginals:
+    - gaussian
+    - student_t4
+    - lognormal
+    - bimodal
+  alpha: 0.05
+  alpha_appendix: [0.01, 0.10]
+  n_reps_size: 10000   # tight CIs around 0.05 require many reps
+  n_reps_power: 5000
+
+# ── block length selection ─────────────────────────────────────────────────────
+block_length:
+  methods:
+    - politis_white_auto   # arch.bootstrap.optimal_block_length (PW 2004)
+    - fixed_n13            # b = floor(n^(1/3)); simple rule
+
+# ── streaming experiment ───────────────────────────────────────────────────────
+streaming:
+  window_sizes: [100, 250, 500]
+  alpha_grid: [0.01, 0.05, 0.10]
+  n_reps_arl: 5000
+  drift_types:
+    - location_shift
+    - scale_change
+    - shape_change
+
+# ── power alternatives ─────────────────────────────────────────────────────────
+# All reported at size-adjusted power with matched dependence.
+power_alternatives:
+  - type: location_shift
+    delta_sd_units: [0.2, 0.5, 1.0, 2.0]
+  - type: scale_change
+    variance_multiplier: [1.5, 2.0, 4.0]
+  - type: shape_change
+    description: skewness/kurtosis shift at matched mean & variance
+  - type: partial_contamination
+    contamination_fraction: [0.1, 0.2, 0.5]
+  - type: gradual_drift
+    description: linear interpolation of marginal across window