fix(joss): clean review follow-ups

Author: brycewang-stanford

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to StatsPAI will be documented in this file.
 
 ## [Unreleased]
 
+### Fixed
+
+- Cleaned up JOSS review follow-ups: removed two uncited duplicate BibTeX
+  entries that caused editorialbot DOI suggestions, aligned the AKM
+  shift-share citation key / DOI metadata, and refreshed v1.15.6 wording in
+  reviewer-facing docs and README release callouts.
+- `tools/audit_citations.py` now treats transient HTTP/socket/SSL timeouts as
+  unresolved citation lookups instead of leaking Python tracebacks.
+
 ## [1.15.6] — 2026-05-24
 
 ### Changed — Co-authorship, JOSS submission readiness

README.md

@@ -126,13 +126,12 @@ StatsPAI's focus is **causal inference** — and on this axis we aim to be the m
 
 **StatsPAI at a glance**: 1,018 registered functions in the live agent registry · 80 submodules · ~249k LOC (core) + ~86k LOC (tests). All four numbers are reproducible from the canonical generator (`python scripts/registry_stats.py`); the per-module table in [`docs/stats.md`](docs/stats.md) is regenerated from the same script. For the full coverage matrix (23 method families) and cross-ecosystem line-count comparison, see [`docs/stats.md`](docs/stats.md).
 
-**📦 v1.15.5 (2026-05-21) — Agent-card coverage ratchet**
+**📦 v1.15.6 (2026-05-24) — JOSS readiness and citation metadata**
 
-StatsPAI now ships a CI-ratcheted agent-card coverage audit, generated
-baseline cards for the 1,018-function registry, and inherited agent-card
-metadata for canonical estimator variants. This release is registry /
-metadata infrastructure: estimator numerical paths are unchanged. Full
-notes in [`CHANGELOG.md`](CHANGELOG.md) under `[1.15.5]`.
+StatsPAI now ships updated co-author and citation metadata, a JOSS reviewer
+guide, a validation dossier, and paper/reference fixes for the 1,018-function
+registry. Estimator numerical paths are unchanged. Full notes in
+[`CHANGELOG.md`](CHANGELOG.md) under `[1.15.6]`.
 
 ---
 

README_CN.md

@@ -48,13 +48,12 @@ StatsPAI 聚焦**因果推断**——在这条主线上，我们的目标是成
 
 **StatsPAI 一句话概览**：live agent registry 中有 1,018 个注册函数 · 80 个子模块 · ~249k 行核心代码 + ~86k 行测试。这四个数字都可以由唯一的生成器 (`python scripts/registry_stats.py`) 现场复算；[`docs/stats.md`](docs/stats.md) 中的按模块拆分表也由同一个脚本回写。完整覆盖矩阵（23 个方法家族）以及跨生态行数对比，详见 [`docs/stats.md`](docs/stats.md)。
 
-**📦 v1.15.5（2026-05-21）— Agent-card 覆盖率 ratchet**
+**📦 v1.15.6（2026-05-24）— JOSS 准备与引用元数据**
 
-StatsPAI 现在带有 CI ratchet 的 agent-card 覆盖率审计、面向
-1,018 个注册函数的自动 baseline cards，以及 canonical 估计器变体的
-继承式 agent-card 元数据。本版本是 registry / metadata 基础设施更新：
+StatsPAI 现在带有更新后的共同作者与引用元数据、JOSS reviewer guide、
+validation dossier，以及面向 1,018 个注册函数的论文 / reference 修复。
 估计器数值路径不变。完整发布说明见 [`CHANGELOG.md`](CHANGELOG.md)
-`[1.15.5]`。
+`[1.15.6]`。
 
 ---
 

docs/index.md

@@ -11,9 +11,9 @@ mixed-effects, modern ML causal inference, the full three-school
 modules (bridging theorems, fairness, surrogates, PCMCI, TMLE survival,
 etc.), and publication-ready output in Word / Excel / LaTeX / HTML.
 
-> **Current release: v1.15.5 (2026-05-21)** — Agent-card coverage
-> ratchet, generated baseline cards, inherited estimator-family metadata,
-> and refreshed 1,018-function registry statistics. See the
+> **Current release: v1.15.6 (2026-05-24)** — JOSS readiness update:
+> co-author and citation metadata, reviewer guide, validation dossier,
+> and paper/reference fixes for the 1,018-function registry. See the
 > [changelog](changelog.md) for detail.
 
 ```python

docs/joss_validation_dossier.md

@@ -9,14 +9,14 @@ research software. It is intentionally factual and reproducible.
 - Package archive: <https://doi.org/10.5281/zenodo.19933900>
 - PyPI: <https://pypi.org/project/StatsPAI/>
 - License: MIT, with a plain-text `LICENSE` file in the repository.
-- Current release at the time of this dossier: `1.15.5`, released on
-  2026-05-21.
+- Current release at the time of this dossier: `1.15.6`, released on
+  2026-05-24.
 - Public GitHub repository creation date: 2025-07-26.
 
 ## Software Scope
 
 StatsPAI exposes a unified Python interface for causal inference and applied
-econometrics. As of release `1.15.5`, the registry reports 1,018 public
+econometrics. As of release `1.15.6`, the registry reports 1,018 public
 functions across 80 submodules:
 
 ```bash
@@ -100,4 +100,3 @@ python -m twine check dist/*
 
 For a shorter package-level check, use the reviewer guide in
 `docs/joss_reviewer_guide.md`.
-

paper.bib

@@ -3192,16 +3192,6 @@ @misc{did_misclassified2025
   doi={10.48550/arXiv.2507.20415}
 }
 
-@article{adao2019shift,
-  title={Shift-Share Designs: Theory and Inference},
-  author={Ad{\\~a}o, Rodrigo and Koles{\\'a}r, Michal and Morales, Eduardo},
-  journal={Quarterly Journal of Economics},
-  volume={134},
-  number={4},
-  pages={1949--2010},
-  year={2019}
-}
-
 @article{santanna2020doubly,
   title={Doubly Robust Difference-in-Differences Estimators},
   author={Sant'Anna, Pedro H.C. and Zhao, Jun},
@@ -4278,13 +4268,6 @@ @article{runge2020discovering
   doi={10.48550/arXiv.2003.03685}
 }
 
-@article{schwab2014ltmle,
-  title={{ltmle}: Longitudinal Targeted Maximum Likelihood Estimation},
-  author={Schwab, Joshua and Lendle, Samuel and Petersen, Maya and van der Laan, Mark J.},
-  journal={R package and accompanying working paper},
-  year={2014}
-}
-
 @inproceedings{tran2023inferring,
   title={Inferring the Long-Term Causal Effects of Long-Term Treatments from Short-Term Experiments},
   author={Tran, Allen and Bibaut, Aur{\'e}lien and Kallus, Nathan},

src/statspai/bartik/adao_correction.py

@@ -436,14 +436,15 @@ def shift_share_se(
 
 # Register citation
 CausalResult._CITATIONS["adao_correction"] = (
-    "@article{adao2019shift,\n"
+    "@article{ado2019shift,\n"
     "  title={Shift-Share Designs: Theory and Inference},\n"
     "  author={Ad{\\~a}o, Rodrigo and Koles{\\'a}r, Michal and "
     "Morales, Eduardo},\n"
     "  journal={Quarterly Journal of Economics},\n"
     "  volume={134},\n"
     "  number={4},\n"
     "  pages={1949--2010},\n"
-    "  year={2019}\n"
+    "  year={2019},\n"
+    "  doi={10.1093/qje/qjz025}\n"
     "}"
 )

tests/test_audit_citations.py

@@ -130,6 +130,31 @@ def test_doi_regex_stops_at_sentence_period():
     assert m.group("id") == "10.1234/xyz"
 
 
+# ---------------------------------------------------------------------------
+# Network failures — must degrade to unresolved, not traceback
+# ---------------------------------------------------------------------------
+
+
+def test_verify_crossref_timeout_is_soft_failure(monkeypatch, capsys):
+    def boom(*args, **kwargs):
+        raise TimeoutError("read operation timed out")
+
+    monkeypatch.setattr(ac, "_http_get", boom)
+
+    assert ac.verify_crossref(["10.1234/example"]) == {}
+    assert "TimeoutError" in capsys.readouterr().err
+
+
+def test_verify_arxiv_timeout_is_soft_failure(monkeypatch, capsys):
+    def boom(*args, **kwargs):
+        raise TimeoutError("read operation timed out")
+
+    monkeypatch.setattr(ac, "_http_get", boom)
+
+    assert ac.verify_arxiv(["2408.12345"]) == {}
+    assert "TimeoutError" in capsys.readouterr().err
+
+
 # ---------------------------------------------------------------------------
 # Name helpers
 # ---------------------------------------------------------------------------
@@ -373,8 +398,7 @@ def test_cli_runs_without_crash_on_empty_tree(tmp_path):
       not a crash).
     * ``2`` — soft failure (rate limit, network) — acceptable.
 
-    Any other exit (including a traceback in ``stderr``) is a real
-    failure.
+    Any other exit, and any traceback in ``stderr``, is a real failure.
     """
     (tmp_path / "src").mkdir()
     (tmp_path / "docs").mkdir()
@@ -387,25 +411,9 @@ def test_cli_runs_without_crash_on_empty_tree(tmp_path):
         capture_output=True, text=True, check=False,
         cwd=tmp_path,
     )
-    # Traceback is acceptable IFF it terminates in a known transient
-    # network failure (the auditor calls arXiv / Crossref / DataCite
-    # live and a cold CI runner can hit HTTP 429 or socket-level
-    # timeouts even on a no-citation tree, because REPO_ROOT scanning
-    # still picks up the real repo's src/ and docs/ before the empty
-    # tmp_path overrides reach it). A traceback whose tail names
-    # something other than these classes is a real auditor crash.
-    _known_transient_errors = (
-        "TimeoutError",        "socket.timeout",
-        "URLError",            "RemoteDisconnected",
-        "ConnectionResetError", "ConnectionAbortedError",
-        "HTTPError: 429",      "HTTPError: 503",
-        "HTTPError: 504",      "ssl.SSLError",
+    assert "Traceback" not in result.stderr, (
+        f"auditor crashed with traceback:\n{result.stderr}"
     )
-    if "Traceback" in result.stderr:
-        assert any(err in result.stderr for err in _known_transient_errors), (
-            f"auditor crashed with traceback (not a known transient "
-            f"network error):\n{result.stderr}"
-        )
     assert result.returncode in (0, 1, 2), (
         f"unexpected exit {result.returncode}: {result.stderr}"
     )

tools/audit_citations.py

@@ -34,9 +34,11 @@
 
 import argparse
 import hashlib
+import http.client
 import html
 import json
 import re
+import socket
 import ssl
 import sys
 import time
@@ -67,6 +69,14 @@
 DEFAULT_ROOTS = ("src", "docs")
 DEFAULT_OUT = REPO_ROOT / "audit_report.md"
 USER_AGENT = "statspai-citation-audit/1.0 (mailto:brycew6m@stanford.edu)"
+_TRANSIENT_NETWORK_ERRORS = (
+    urllib.error.URLError,
+    TimeoutError,
+    socket.timeout,
+    ConnectionError,
+    http.client.HTTPException,
+    ssl.SSLError,
+)
 
 ARXIV_RE = re.compile(
     r"""
@@ -437,8 +447,8 @@ def verify_arxiv(ids: list[str], refresh: bool = False) -> dict[str, PaperMeta]:
         )
         try:
             xml_bytes = _http_get(url, refresh=refresh, sleep=3.0)
-        except urllib.error.URLError as e:
-            print(f"[arxiv] HTTP error {e!r} for chunk starting {chunk[0]}",
+        except _TRANSIENT_NETWORK_ERRORS as e:
+            print(f"[arxiv] HTTP/network error {e!r} for chunk starting {chunk[0]}",
                   file=sys.stderr)
             continue
         root = ET.fromstring(xml_bytes)
@@ -491,8 +501,8 @@ def verify_nber(ids: list[str], refresh: bool = False) -> dict[str, PaperMeta]:
             html_text = _http_get(url, refresh=refresh, sleep=1.0).decode(
                 "utf-8", errors="replace"
             )
-        except urllib.error.URLError as e:
-            print(f"[nber] HTTP error {e!r} for w{wp}", file=sys.stderr)
+        except _TRANSIENT_NETWORK_ERRORS as e:
+            print(f"[nber] HTTP/network error {e!r} for w{wp}", file=sys.stderr)
             continue
         authors: list[str] = []
         title = ""
@@ -530,8 +540,8 @@ def _verify_datacite_one(doi: str, refresh: bool = False) -> Optional[PaperMeta]
     url = f"https://api.datacite.org/dois/{urllib.parse.quote(doi, safe='')}"
     try:
         raw = _http_get(url, refresh=refresh, sleep=0.5)
-    except urllib.error.URLError as e:
-        print(f"[datacite] HTTP error {e!r} for {doi}", file=sys.stderr)
+    except _TRANSIENT_NETWORK_ERRORS as e:
+        print(f"[datacite] HTTP/network error {e!r} for {doi}", file=sys.stderr)
         return None
     try:
         obj = json.loads(raw)
@@ -570,8 +580,8 @@ def verify_crossref(dois: list[str], refresh: bool = False) -> dict[str, PaperMe
                 crossref_404 = True
             else:
                 continue
-        except urllib.error.URLError as e:
-            print(f"[crossref] HTTP error {e!r} for {doi}", file=sys.stderr)
+        except _TRANSIENT_NETWORK_ERRORS as e:
+            print(f"[crossref] HTTP/network error {e!r} for {doi}", file=sys.stderr)
             continue
         if crossref_404:
             # Fall through to DataCite — Zenodo / Figshare / Dryad