[SwiftyProjects]

Summary

Two years after v1.0.0, a full modernization of TRACES ahead of a v2.0.0 release: the analysis moves from notebook cells into a tested traces_ts package, several v1 calculation bugs are fixed, and the default significance tests now account for autocorrelation. Results differ from v1; AnalysisConfig.classic() / traces analyze --classic give v1-style statistics.

What changed

Environment

• pyproject.toml + uv.lock; works with uv sync or pip install -e . in any venv (verified by installing the built wheel in a plain pip venv)
• environment.yml is conda-forge only and just installs the package
• Python 3.11-3.14; tested on NumPy 2.5, pandas 3.0, SciPy 1.18, matplotlib 3.11
• Distribution traces-ts, import traces_ts (traces is already taken on PyPI)

v1 bugs fixed

• CCF optimal lag ignored max_lag (v1 reported lags of 11-12 with max_lag=10)
• CCF and time-delayed correlations used opposite lag signs; now positive lag = series_1 leads
• CCF was not normalized (values were r x (n-1), e.g. 50.9); CCF(0) now equals Pearson r
• Hard-coded Time column; first column is now the time column as documented
• No missing-value handling despite docs; explicit raise / drop / interpolate
• (count, method) legend labels in the method-performance plot

Statistics (on by default)

• Autocorrelation-adjusted p-values via effective sample size (Pyper & Peterman, 1998)
• Benjamini-Hochberg FDR correction across pairs
• Double AR pre-whitening + residual-based Bonferroni band for lead/lag detection (order-independent)
• New none relationship type; documented evidence_score replaces the old confidence score

Features

• traces analyze CLI: CSV, Excel (results/summary/config sheets), Markdown report, figures
• CSV input, configurable time column, date parsing, detrending (none / linear / difference)
• New per-pair CCF and rolling-correlation plots; relationship matrix covers all series
• Notebook rewritten as a thin six-step walkthrough with a classic-vs-v2 comparison

Quality

• 58 pytest tests, including statistical calibration checks
• GitHub Actions: ruff, tests on Linux (3.11-3.14), Windows and macOS, lowest supported dependency versions, notebook execution, CLI smoke test, build
• README, guides and formulae rewritten; CHANGELOG with migration table; CITATION.cff
• Example outputs are generated from real runs by scripts/generate_examples.py (the old hand-written step*.txt outputs did not match the code)

Why the statistics changed

Simulated independent series, n = 52, alpha = 0.05 (1,000 pairs each):

Series type	naive p	v2 p	naive lag detection	v2 lag detection
White noise	6.3%	5.6%	1.7%	1.4%
AR(1), phi = 0.95	55.7%	6.2%	43.2%	1.5%
Random walk	66.8%	14.4%	33.2%	1.5%
Smoothed noise	51.4%	6.0%	49.8%	7.6%

A true 3-step lead is detected 84-93% of the time with the correct sign 98% of the time.

Sample dataset A1 (relationship-type counts):

Type	classic (v1-style)	v2 default
linear	4	4
lagged	7	0
complex	33	5
none	1	36

Reviewer notes

• Breaking change: result columns are snake_case (series_1, relationship_type, evidence_score, ccf_peak_lag, ...); see the migration table in CHANGELOG.md
• Random walks and strong deterministic trends still inflate adjusted p-values (~14-15%); reports flag high-persistence series and recommend detrend="difference". Documented under Limitations in docs/Formulae.md
• The CI workflow has not run on GitHub before this PR; watch the first run
• After merge: tag v2.0.0 and publish a GitHub release from the CHANGELOG

Test plan

• uv run pytest (58 passed)
• uv run pytest --nbmake notebooks
• uv run ruff check . and uv run ruff format --check .
• Lowest direct dependencies on Python 3.11 (58 passed)
• uv build, wheel installed in a plain pip venv, traces analyze on dataset B1
• GitHub Actions CI green

🤖 Generated with Claude Code