Report full formulas for unit metadata overrides

[houjun]

Related Issues / Pull Requests

Closes #275. Follow-up to #258.

Description

Overriding detected units previously treated Celsius-to-Kelvin as a 274.15× scale difference, and the initial offset fix reported only a zero point for Celsius-to-Fahrenheit. The shared audit now reports the complete formula, such as °F = °C × 1.8 + 32, for any supported Pint scale/offset conversion regardless of the variable name or physical dimension. Multiplicative conversions also show their direction explicitly, such as g/m³ = kg/m³ × 1000.

The slope comes from Pint's definitions, avoiding cancellation when an offset is large relative to the scale. Rounded coefficients use ≈; reverse Fahrenheit-to-Celsius reports °C ≈ °F × 0.555556 - 17.7778. Logarithmic/unknown converters, unsupported conversions, and numerically unrepresentable coefficients report that the formula is unavailable instead of claiming a scale or affine relationship.

Dataset values and detected observations remain unchanged. Scale mismatches retain their numeric conversion_factor; offset mismatches and the new generic conversion kind use null. Existing version-1 sidecars remain importable, with unchanged fields and version. Consumers validating against a cached schema must refresh it for the added offset and conversion enum values. Dimension and classification mismatches retain their behavior. The web, CLI, and library share this reporting path.

What changes are proposed in this pull request?

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality not to work as expected; for instance, examples in this repository must be updated too)
• This change requires a documentation update

Checklist:

• My code modifies existing public API, or introduces new public API, and I updated or wrote documentation
• I have commented my code
• My code requires documentation updates, and I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Validation

• Full suite on Python 3.13.15 / Pint 0.25.3: 1350 passed, 118 skipped, 219 subtests passed, with four existing pandas deprecation warnings.
• Core, headless/CLI, and web regression tests on minimum supported Pint 0.24.4: 148 passed.
• Confirmed 23 formula/nonlinear regression cases fail against the previous PR head.
• Repository-wide Flake8 and changed-test lint: passed.
• Pre-commit hooks on all six changed files: passed.
• Sphinx HTML build with warnings treated as errors: passed.
• Wheel and source distribution build, offline lock check, and git diff --check: passed.

Coverage includes both directions of Celsius/Kelvin and Celsius/Fahrenheit; pressure, speed, density, time, length, and dimensionless scaling; non-temperature offset definitions; small slopes with large offsets; rounding and scientific notation; logarithmic units and their aliases; unavailable conversions and numerical range limits; schema validation, legacy/new sidecar round trips, preserved source values/observations, CLI output, and the web route.

[Copilot]

Copilot review overview

🟢 Approval recommended

The bounded fix matches the stated requirements, includes focused regression coverage, and has no unresolved findings.

Review effort: Balanced
Findings: None

What changed in this PR

Fixes temperature override reporting in the shared unit audit without changing dataset values.

Changes:

• Reports different temperature zero points as offset mismatches with reference values.
• Updates the schema and documentation while preserving existing sidecar imports.
• Adds core, CLI, and web regression coverage.

File	Description
tests/​unit/​test_variable_unit_validation.py	Tests offset reporting, scale behavior, and sidecar compatibility.
tests/​unit/​test_variable_unit_interfaces.py	Tests CLI temperature override output.
tests/​integration/​test_inspector_metrics.py	Tests offset reporting through the web route.
docs/​source/​variable_unit_validation.rst	Documents offset mismatches and schema compatibility.
docs/​source/​_static/​variable-unit-metadata.schema.json	Allows the offset mismatch kind.
aidrin/​structured_data_metrics/​variable_unit_validation.py	Detects temperature offsets using explicit Pint quantities.

---

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