Validating a jig or a coupler can take out the uncertainty two calibrations share (IEC 61094-5 6.7)

[jmrplens]

metrology.verify_jig_or_coupler judged two calibrations of the same microphone as if their uncertainties were independent. When the two share a component, the calibration of the same reference microphone or the same measuring chain, the error of that component moves both sensitivity levels together and cancels in their difference, while the root-sum-square counts it twice. The criterion was then looser than it should be.

The function now takes a keyword-only shared_standard_uncertainty_db, one value or one per frequency of the calibration, with a default of 0 dB. With it the difference is judged against U_Delta = sqrt(U_cal^2 + U_val^2 - 2 (k u_sh)^2), that is k = 2 times the root of u_cal^2 + u_val^2 - 2 u_sh^2: the GUM law of propagation for correlated inputs (JCGM 100:2008 5.2.2, Formula (13)) with the covariance of two levels that each depend on the shared quantity with a sensitivity of 1 (F.1.2.3, Formula (F.2)). The k = 2 comes from IEC 61094-5 7.9 for a comparison and from IEC 61094-2:2009 7.5 for a reciprocity calibration. A negative shared part, one larger than either calibration's standard uncertainty, or one that leaves the difference with no uncertainty at all is refused.

JigCouplerVerification carries the shared part as a keyword-only, read-only field, gives the correlation_coefficient of the two levels (Formula (14)), and its .plot() draws the band two independent calibrations would have, dotted around the narrower one. Two calibrations with the budget of IEC 61094-5 Table D.1 against the same LS2P are judged within 0.101 dB instead of 0.124 dB, and a pair that agrees within the root-sum-square can fail once the shared part is out.

Only a component that enters both levels with the same sign and size can be given. A reciprocity calibration made in the same set of three microphones as the reference's is not such a case: in IEC 61094-2:2009 Formula (7) the pairs that go through the third microphone are in the numerator of one microphone's sensitivity and in the denominator of the other's, so they enter the two levels with opposite signs. That covariance is negative and widens the band beyond the root-sum-square, which this argument does not represent. The docstrings, the guide and its scope notes say so.

The comparison calibration guide has a new section, "Calibrations that share a reference", in English and Spanish and in the docs/ mirror: the jig of A.2 validated against the coupler of A.1 with the reference they share taken out, the figure with both bands, which components two calibrations can share (the reference's calibration, its drift since then, a common chain), and the case above that cannot be given.

Nothing breaks. The default of 0 dB gives the root-sum-square bit for bit, so every existing call returns the verdict it returned before. No migration is needed. The only visible change for an existing caller is the wording of the error raised when the difference of the two calibrations is left with no uncertainty.

How it was verified. The test oracle is worked by hand from IEC 61094-5:2016 Table D.1 (PDF page 22, folio 20): each calibration carries U = 0.0873 dB from its eight rows, the first row (the reference, 0.025 dB) is the shared one, and the difference carries 0.101272 dB against 0.123515 dB for two independent calibrations; a conformance row checks it. A second conformance row reproduces the correlation coefficients JCGM 100:2008 prints in F.1.2.3 Example 2 (PDF page 75, folio 63), about 0.5, 0.990 and 1.000 for comparisons of 100, 10 and 1 x 10^-6 against a standard of relative standard uncertainty 10^-4, to the decimals printed; Formula (F.2) was read on PDF page 74, folio 62. IEC 61094-2:2009 Formula (7) was read on PDF page 14, folio 12, and its 7.5 on PDF page 20, folio 18. Nineteen new tests cover the formula per frequency, the default being the root-sum-square to the last bit, a shared part equal to one uncertainty, the refusals, the shared part staying with its own frequency when the validation leaves out the first, a middle or the last frequency, the zero correlation where a calibration carries no uncertainty, and the plot in both languages.

Jarvis and Watkins (1997), NPL Report CIRA(EXT) 022, was read page by page. It compares jig calibrations of working standard microphones with reciprocity calibrations of the same microphones in Figures 6 and 7 (folio 4), and its text judges the differences in words against the typical repeatability, one standard deviation drawn as a band in Figure 7 (folio 2). It prints no numeric criterion, no worked numbers one could check against, and nothing about what the two calibrations share; its "less than 0.1 dB" on folio 5 reports a result. It is cited in the guide as a source that is not implemented, and no erratum was found in it, in Table D.1 or in GUM Example 2.

The conformance report passes 1893 of 1893 checks. Ruff, ruff format, mypy over src and scripts, bandit, the full test suite, every documentation snippet and the site build with its HTML validation pass.

Summary by CodeRabbit

• New Features

  • Jig and coupler verification now accounts for a standard-uncertainty component shared by both calibrations. Results report the resulting correlation, and plots show the shared-uncertainty band alongside the independent-calibration comparison.
  • Shared uncertainty can be a single value or vary by frequency. It must represent a same-sign, equal-size component and cannot exceed either calibration’s standard uncertainty; unsupported covariance is not represented.

• Documentation

  • Updated conformance reports and related references to reflect 1,893 checks, including two additional checks for correlated calibration comparisons.

[sourcery-ai]

Sorry @jmrplens, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 4 days and 16 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: jmrplens/phonometry/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 1f6f4e0d-87aa-47e8-ac79-fee3d384bb6e

📥 Commits

Reviewing files that changed from the base of the PR and between b3d8562 and be60b6e.

⛔ Files ignored due to path filters (6)

• .github/badges/conformance-summary.svg is excluded by !**/*.svg
• .github/badges/conformance-summary_dark.svg is excluded by !**/*.svg
• .github/images/comparison_jig_validation.svg is excluded by !**/*.svg
• .github/images/comparison_jig_validation_dark.svg is excluded by !**/*.svg
• .github/images/comparison_jig_validation_es.svg is excluded by !**/*.svg
• .github/images/comparison_jig_validation_es_dark.svg is excluded by !**/*.svg

📒 Files selected for processing (7)

• scripts/check_figure_language.py
• scripts/conformance/domains/comparison_calibration.py
• src/phonometry/_plot/metrology.py
• src/phonometry/metrology/comparison_calibration.py
• tests/metrology/test_comparison_diameter_gap_validation.py
• tests/reference_data/__init__.py
• tests/reference_data/comparison_calibration.py

🚧 Files skipped from review as they are similar to previous changes (3)

• src/phonometry/_plot/metrology.py
• scripts/conformance/domains/comparison_calibration.py
• tests/metrology/test_comparison_diameter_gap_validation.py

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

---

📝 Walkthrough

Walkthrough

Jig/coupler verification now accepts shared standard uncertainty and uses it to calculate correlated difference uncertainty. Results expose the shared uncertainty and correlation coefficient. Tests, plots, conformance records, and documentation reflect the new behavior.

Changes

Correlated calibration validation

Layer / File(s)	Summary
Verification API and uncertainty calculation src/phonometry/metrology/comparison_calibration.py, docs/reference/api/index.md, site/src/content/docs/reference/api/metrology/comparison-calibration.md	verify_jig_or_coupler accepts scalar or per-frequency shared uncertainty. Validation rejects unsupported values and calculates the adjusted difference uncertainty and correlation coefficient.
Correlated and independent plot bands src/phonometry/_plot/metrology.py, scripts/figures/metrology.py	Plots show the shared-component band and, when applicable, dotted independent-calibration bounds.
Calculation tests and conformance checks tests/metrology/*, tests/reference_data/*, scripts/conformance/domains/comparison_calibration.py, docs/CONFORMANCE.md, docs/conformance.json	Tests cover calculations, alignment, correlation, verdicts, invalid inputs, and plotting. Two conformance checks cover GUM correlation values and shared-reference difference uncertainty.
Guides and conformance descriptions docs/signals/metrology/*, site/src/content/docs/signals/metrology/*, llms-full.txt, site/public/llms/*, CHANGELOG.md, README*, docs/start/*, site/src/content/docs/*, .zenodo.json	Documentation describes the correlated calculation, supported shared components, and unsupported covariance cases. Reported conformance totals increase from 1,891 to 1,893.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Calibration caller
  participant verify_jig_or_coupler
  participant JigCouplerVerification
  participant plot_jig_coupler_verification
  Calibration caller->>verify_jig_or_coupler: calibration, validation, shared_standard_uncertainty_db
  verify_jig_or_coupler->>JigCouplerVerification: validated shared uncertainty
  JigCouplerVerification-->>Calibration caller: difference uncertainty and correlation coefficient
  Calibration caller->>plot_jig_coupler_verification: verification result
  plot_jig_coupler_verification-->>Calibration caller: shared band and independent bounds

Loading

Merge Risk: ⚪ Minimal · up to be60b

The shared-uncertainty change is mergeable after normal checks. An unusually tiny nonzero uncertainty may be rejected and can be addressed separately.

Security Architecture Review

Security architecture risk: 🔵 Low · up to be60b

The change is confined to calibration calculations and their presentation. Input validation limits the shared component, and inspected consumers do not introduce privileged access or cross-service effects. Broader security and deployment coverage remains incomplete.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — Within inspected consumers, caller authority extends to a numerical verification result and its plotted presentation. No new privileged, tenant, credential, network, or data-store authority was identified. External use of passes as an authoritative compliance decision remains outside the available evidence.

Trust Boundaries and Controls

• observed — Numeric guards reject empty, multidimensional, non-finite, incorrectly sized, or negative shared inputs. The constructor compares the expanded shared component against both calibration uncertainties at nine-decimal precision and requires a positive settled residual uncertainty. These checks constrain magnitude; they do not authenticate calibration provenance or prove that the supplied component is physically shared.
• observed — Result arrays are copied before their writeable flags are cleared, avoiding aliases to caller inputs. The existing read-only helper explicitly permits deliberate re-enabling of writes, so this mechanism is not a security boundary against code executing in the same process.
• observed — The language-checker change exempts one mathematical label from translation reporting, and the routed reference-data change adds numerical test constants. Neither change introduces executable input handling or an authorization exemption.

Resilience and Maintainability Implications

• inferred — The inspected verification transition consists of local normalization, validation, and result construction. Failure raises before a result is returned, with no external commit or cleanup step. Repetition creates separate result arrays rather than modifying shared calibration state; no persistent recovery protocol is introduced.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 84.38% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 32 functions across 8 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: validation can account for uncertainty shared by two calibrations. It is specific and related to the implementation.
Description check	✅ Passed	The description explains the purpose, API changes, formulas, limitations, validation oracles, tests, documentation updates, and reported CI results. It does not reproduce the template headings or chec…

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (14a2802) to head (be60b6e).

Additional details and impacted files

@@                    Coverage Diff                     @@
##           docs/anova-cuadrado-medio     #946   +/-   ##
==========================================================
  Coverage                      96.80%   96.80%           
==========================================================
  Files                            443      443           
  Lines                          87857    87888   +31     
==========================================================
+ Hits                           85050    85081   +31     
  Misses                          2807     2807           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Numerical conformance

1893/1893 checks pass across 111 domains and 523 standards (227 normative designations, 125 further published sources).

_{Used in the tables below is how much of that clause's published tolerance the deviation consumes: 100 % sits exactly on the limit, 5 % uses a twentieth of the allowance, and a dash means the clause states no two-sided tolerance for the quantity, so there is no budget to spend. It is reported and never used to decide a verdict, which is settled at full precision before any rounding.}

New checks (2)

Standard	Quantity	Deviation	Used
IEC 61094-5:2016 6.7; ISO/IEC Guide 98-3 F.1.2.3, Example 2	Correlation of two calibrations against the same standard of 10^-4, for comparisons of 100, 10 and 1 x 10^-6, as printed	0	0 %
IEC 61094-5:2016 6.7, Table D.1; ISO/IEC Guide 98-3 5.2.2	Expanded uncertainty of the difference of two calibrations against the same LS2P, each with the budget of Table D.1	0 dB	0 %

Closest to their published limit (top 5)

The rows with the least room left, so the ones a change is most likely to push over.

Standard	Quantity	Deviation	Used
ISO/TR 17534-3:2015 Table 3	Ground-projected path length dp, m	0.005 m	100 %
DIN 4150-2:1999-06 Annex C, Example 5	KB_FTr with hammer b) in the rest hours, Formula (5)	-0.005	100 %
DIN 4150-2:1999-06 Annex C, Example 8	KB_FTm over the record with the passage maxima alone	-0.0005	100 %
E DIN 4150-2:2023-08 Annex B, Table B.1	KB_FTm,Zug of the metro north by Formula (5)	-0.0005	100 %
Jarvis (1996) NPL CIRA(EXT) 010 Appendix B, folio 26	Volume of the coupler of the example, v = pi r^2 L	-0.00000000005 m³	100 %

---

Tests & coverage: 161316 tests, 0 failures (all green)

Python Version	Tests	Failures	Coverage	Status
macos-latest-3.13	26886	0	96.8%	Passed
macos-latest-3.14	26886	0	96.8%	Passed
ubuntu-latest-3.13	26886	0	96.8%	Passed
ubuntu-latest-3.14	26886	0	96.8%	Passed
windows-latest-3.13	26886	0	96.8%	Passed
windows-latest-3.14	26886	0	96.8%	Passed

_{Full report at this commit: docs/CONFORMANCE.md · docs/conformance.json · full CI artifacts}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud