P4: survey hygiene (S-CD.1-3, SCI-08): DOI-aware keys, denominators, coded reporting rates

[mdenolle]

Closes #42. Package P4 of the iteration-3 plan: the survey's citation keys, denominators and reporting rates. Independent of P1 (#52); touches paper/build_survey.py, the generated survey.bib and appendix_table.tex, Appendix C and two sentences elsewhere in the manuscript.

Ledger entries addressed

Entry	What changed
S-CD.1 (key collision)	build_survey.py reuses a references.bib key only when the row DOI matches the entry's DOI (existing_dois, assign_keys). The Piton de la Fournaise study of Obermann et al. (2013, JGR, 10.1002/2013JB010399) had been cited in the appendix as the GJI depth-sensitivity paper (10.1093/gji/ggt043) that shares the key Obermann2013. It is now Obermann2013b with its own entry; the rendered reference list carries both (2013a, 2013b). Regression test: tests/test_build_survey.py
S-CD.1 (counts), SCI-08	Appendix C: 103 rows for 103 publications with one DOI each; seven do not measure dv/v (n/a in the estimator column, named, excluded from the rates); of the 96 that do, 81 ambient noise, 9 earthquake coda only, the rest both. The Results sentence that quoted "103 ambient-noise studies" now quotes the 96 and the split. One noun ("publications") for rows throughout; the table caption defines n/a
S-CD.3	paper/survey_rates.py codes the uncertainty cell of the 75 full-text publications that measure dv/v: 57 state an error, 11 a quality rule only, 7 neither; band 68, window 59, estimator 74 of 75. The keyword rule and the eight hand-coded cells are in the script; counts in paper/data/survey_rates.json and quoted in Appendix C. The 21 abstract-derived rows are excluded from the rates
Search rules	Appendix C states the provenance that literature/README.md documents (six scans in June 2026, 117 rows deduplicated by DOI and checked against Crossref, four DOIs corrected, one row dropped) and the inclusion rule the table applies. Search dates and queries beyond that are not documented anywhere I could find, so they are not stated; #48 asks the author

Not done here, by design: verification of the seven identical-cell row pairs and the Snieder2002 row (#48), and the Yuan et al. (2021) regime (#47).

Verification

• python paper/build_survey.py: 85 new entries, 18 reused; 103 catalogued.
• pytest tests/test_build_survey.py: 4 passed. Pre-commit hooks pass.
• PDF rebuilt with the survey regeneration: 84 pages; ?? 0, ,% 0; both Obermann 2013 papers in the reference list.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The updated manuscript text contains internal inconsistencies in the signal-source split and some LaTeX-quoting corruption that should be corrected before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR implements “P4 survey hygiene” updates to the literature-survey toolchain and manuscript, focusing on DOI-aware citation key reuse, clarified denominators, and coded/verified reporting-rate counts for Appendix C.

Changes:

• Updated paper/build_survey.py to reuse references.bib keys only when DOIs match, and added a regression test for key assignment.
• Added a scripted extraction of survey denominators and verified reporting rates (paper/survey_rates.py), committing its JSON output for Appendix C.
• Regenerated survey artifacts (paper/survey.bib, paper/appendix_table.tex) and updated manuscript text to reflect revised survey counts and wording.

File summaries

File	Description
tests/test_build_survey.py	New tests covering DOI-aware key reuse and disambiguation behavior.
review/REVISION_PLAN_ITER3.md	Adds a dated log entry recording P4 execution status.
paper/survey.bib	Adds a distinct Obermann2013b BibTeX entry to resolve the collision.
paper/survey_rates.py	New script to compute denominators and verified reporting rates from the survey CSV.
paper/data/survey_rates.json	Committed computed counts used by Appendix C prose.
paper/build_survey.py	Implements DOI-aware key reuse (existing_dois, assign_keys) and updates table caption wording.
paper/appendix_table.tex	Regenerated appendix longtable caption and updated the Obermann citation key.
paper/manuscript_marine.tex	Updates manuscript prose for survey denominators/rates and terminology.
paper/manuscript_marine.qmd	Mirrors manuscript prose updates in the Quarto source.

Review details

Suppressed comments (2)

paper/manuscript_marine.tex:2138

• The signal-source breakdown here is inconsistent with the definitions just above. Since 7 publications are explicitly excluded as not measuring dv/v (including 4 tagged "Ambient noise" and 1 tagged "Both"), the 96 measuring publications split as 77 Ambient noise / 9 Earthquake coda / 10 Both. Also, the LaTeX quoting around n/a'' is currently malformed (n/a','').

publications rely on. Seven of the 103 do not themselves measure
\dvv~(theory, depth kernels, deconvolution interferometry, spectral
methods) and are marked ``n/a'\,' in the estimator column; the counts
below exclude them. Of the 96 that measure \dvv, 81 use ambient noise
alone, 9 use earthquake coda alone and the rest both (the

paper/manuscript_marine.qmd:1754

• The measuring-publication signal-source breakdown is off here. Given the 7 explicitly excluded non-measuring rows (including multiple tagged as Ambient noise/Both), the 96 measuring publications split as 77 Ambient noise / 9 Earthquake coda / 10 Both (not 81 / 9 / rest).

rely on. Seven of the 103 do not themselves measure \dvv\ (theory,
depth kernels, deconvolution interferometry, spectral methods) and are marked
``n/a'' in the estimator column; the counts below exclude them. Of the 96
that measure \dvv, 81 use ambient noise alone, 9 use earthquake coda alone
and the rest both (the machine-readable table records this per row);

• Files reviewed: 9/9 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The generated survey table still uses “Study” as the column header despite the PR’s stated switch to “publications”, leaving inconsistent terminology in Appendix C that should be corrected before approval.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

paper/build_survey.py:206

• This docstring says the base key is assigned to “whichever of them the narrative already cites”, but when neither paper is in references.bib the implementation assigns the base key to the first row encountered (CSV order). Consider rewording to match the actual behavior (and keep the special case where an existing references.bib key with matching DOI keeps the base key).

This issue also appears on line 284 of the same file.

paper/build_survey.py:288

• The generated appendix table still labels the first column/header as “Study”, but the caption and manuscript now use “publications” as the consistent noun (per SCI-08 / S-CD.*). To keep terminology consistent within the same table, rename the header to “Publication” (and keep the rest unchanged).

    head = (
        "\\textbf{Study} & "
        + " & ".join(f"\\textbf{{{h}}}" for _, h, _ in COLS)
        + r" \\"
    )

• Files reviewed: 9/9 changed files
• Comments generated: 0 new
• Review effort level: Lite

[mdenolle]

Manuscript text in this PR no longer names scripts, modules, command lines or file paths (the paper is about the method, not the software); the package name and the repository URL remain in Data availability. The pre-existing mentions in the base text are removed in #52, so #52 should merge first; #53 and #54 strip only what they had added.

[Copilot]

🟡 Changes recommended

The newly generated survey rates output currently labels/counts distinct_dois inconsistently with the recorded non-DOI row, so the committed numbers should be regenerated/fixed for internal consistency.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

paper/data/survey_rates.json:5

• distinct_dois should reflect the count of actual DOI identifiers only; since this file already records one non-DOI row in rows_without_doi, the DOI count should be 102 (and will update automatically when regenerating via paper/survey_rates.py).
  paper/survey_rates.py:121
• distinct_dois currently counts every doi_url value, including non-DOI identifiers (e.g. the ADS record row). That makes the field name misleading and inconsistent with rows_without_doi; consider counting only values that look like DOIs (contain "10.").

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Lite

[mdenolle]

The two suppressed comments on the survey-rates export are addressed in bd17cc2: distinct_identifiers is 103 and distinct_dois is 102 (the ADS-identified conference abstract is listed in rows_without_doi); the generated survey.bib and appendix table are unchanged.

[Copilot]

🟡 Changes recommended

assign_keys() currently generates incorrect disambiguation suffixes for third-or-later collisions (e.g., ...bc), which can produce invalid/unexpected citation keys.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

paper/build_survey.py:228

• Key disambiguation appends letters instead of incrementing the existing suffix (e.g., a third collision would produce Wang2017bc rather than Wang2017c). This breaks the intended ...b, ...c, ...d sequence and can generate invalid/unexpected citation keys when more than two distinct papers share a base key.
  tests/test_build_survey.py:18
• spec_from_file_location() can return None; the fixture currently calls module_from_spec(spec) before asserting that spec is non-None, which would raise a less clear error if the path is wrong.

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Lite

[mdenolle]

The two suppressed comments are also addressed in 6ad4096: the disambiguation now replaces a trailing suffix letter (Key2013, Key2013b, Key2013c; test extended with a third distinct paper), and the test fixture asserts the spec before building the module.

[Copilot]

🟢 Approval recommended

The changes satisfy the stated acceptance criteria and the only remaining feedback is a minor maintainability nit with a self-contained fix.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

paper/build_survey.py:246

• bib_authors(rec) is computed twice when building the author field, which is redundant and makes the expression harder to read/maintain. Compute it once and then decide whether to latexify or fall back to authors_from_label.

• Files reviewed: 9/9 changed files
• Comments generated: 0 new
• Review effort level: Lite

[mdenolle]

The remaining nit is addressed in cc3e2ed: the author string is computed once; the generated files are unchanged.

[Copilot]

🟢 Approval recommended

The changes align with the stated acceptance criteria (DOI-aware disambiguation with a test, consistent denominators/splits, and reproducible rate counts) and no new correctness issues were found in the modified regions.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 0 new
• Review effort level: Lite