feat: add self-heating EIV fit

Add York errors-in-variables regression for multi-observation self-heating fits when both resistance and measurement-current standard uncertainties are supplied.

Propagate current uncertainty into the squared-current coordinate, support optional within-observation current/resistance error correlation, and retain York weights, iteration evidence, chi-square diagnostics, and fitted-parameter covariance.

Keep finite-range self-heating coefficient evaluation unavailable for EIV fits until direct current-coordinate uncertainty in dissipated power can be propagated without understating uncertainty.

Author: GregRR

docs/DESIGN.md

@@ -1062,13 +1062,31 @@ parameter covariance. The public uncertainty result records which covariance mod
 was used; its ``residual_variance_ohms_squared`` is present only for the residual-
 scatter ordinary-least-squares path.
 
-Neither covariance path is described as propagation of measurement-current
-uncertainty. If uncertainty in current is material, the independent coordinate has
-measurement error and fixed-coordinate least squares is not an adequate model.
-Correlated repeated readings and other common-mode effects likewise require an
-explicit covariance-aware or errors-in-variables treatment rather than being
-inferred from residual scatter or from the supplied marginal resistance
-uncertainties.
+When measurement-current standard uncertainties are supplied together with
+resistance standard uncertainties for every observation, the 3+ observation fitter
+uses York errors-in-variables regression rather than fixed-coordinate least
+squares. The measured current magnitude is the supplied independent quantity, while
+the fitted coordinate is ``I²``; current uncertainty is therefore propagated to the
+fit coordinate by the first-order relation ``u(I²) = 2 I u(I)``. This is an explicit
+local linearization of the coordinate transformation, not a claim that squared
+current is normally distributed for arbitrarily large relative current uncertainty.
+
+The York path also accepts an optional correlation coefficient for the current and
+resistance errors of each observation. Since all accepted measurement currents are
+positive, the first-order transformation from ``I`` to ``I²`` has positive
+derivative and preserves that within-observation correlation coefficient. Omitting
+the coefficients records zero within-observation correlation. York weights depend
+on the fitted slope and both coordinate uncertainties, so the solver iterates to a
+converged slope. Its chi-square uses the final combined coordinate-error model, and
+its fitted intercept/slope covariance is obtained from the York adjusted
+coordinates and supplied absolute uncertainties without residual rescaling.
+
+This errors-in-variables path still treats separate observations as statistically
+independent. Shared current-source calibration, bridge calibration, environmental
+drift, or other common-mode effects can create cross-observation covariance that a
+per-observation correlation coefficient does not represent. Such covariance must be
+supplied through a separate generalized covariance model rather than inferred from
+replicate scatter, instrument identity, or marginal standard uncertainties.
 
 The 3+ observation fit can also be interpreted through one explicitly supplied
 RTD model without changing the resistance-domain fit. The result converts the
@@ -1081,8 +1099,9 @@ self-heating coefficient or dissipation constant.
 
 The retained intercept/slope covariance can be propagated through the same model
 into the fitted zero-power temperature and fitted temperature rises. It may come
-from residual-scatter ordinary least squares or from supplied absolute resistance
-standard uncertainties in the weighted fit. At each
+from residual-scatter ordinary least squares, supplied absolute resistance standard
+uncertainties in the weighted fit, or the supplied two-coordinate uncertainty model
+in the York errors-in-variables fit. At each
 sampled ``x = I²``, the fitted resistance sensitivity to ``(R0, k)`` is ``(1, x)``.
 The temperature sensitivity vector is therefore the local ``dT/dR`` multiplied by
 ``(1, x)``, while the temperature-rise vector subtracts the corresponding
@@ -1168,8 +1187,9 @@ future statistically justified API concern.
 
 The self-heating layer still does not automatically alter an RTD model or a
 general uncertainty budget. Remaining 0.8.0 regression work is limited to
-errors-in-variables handling when measurement-current uncertainty is material and
-correlated-observation treatment where a defensible covariance model exists.
+cross-observation covariance treatment where a defensible covariance model exists,
+plus any experiment-specific residual acceptance criteria that can be stated without
+inventing universal thresholds.
 
 #### Portable model-definition format decision
 

docs/REFERENCES.md

@@ -303,6 +303,18 @@ variance are available. `rtd-sensor` keeps this response-uncertainty case separa
 from measurement-current uncertainty in the independent coordinate, which requires
 an errors-in-variables treatment.
 
+York, D., Evensen, N. M., López Martínez, M., & De Basabe Delgado, J.
+(2004). Unified equations for the slope, intercept, and standard errors of the
+best straight line. *American Journal of Physics, 72*(3), 367–375.
+https://doi.org/10.1119/1.1632486
+
+**Project use:** Implementation basis for the 3+ observation self-heating
+errors-in-variables fit when measurement-current uncertainty is material. York's
+straight-line formulation supports observation-specific uncertainty in both
+coordinates and correlation between the coordinate errors of each observation.
+`rtd-sensor` applies it to `(I², R)` after first-order propagation
+`u(I²) = 2 I u(I)` and does not infer covariance between separate observations.
+
 Bureau International des Poids et Mesures, Consultative Committee for
 Thermometry. (2021). *Guide to the realization of the ITS-90: Platinum
 resistance thermometry*.

docs/ROADMAP.md

@@ -153,6 +153,12 @@ Implemented in the current 0.8.0 development checkpoint:
   retained normalized weights, chi-square/reduced-chi-square diagnostics, and
   parameter covariance determined directly from those supplied uncertainties rather
   than rescaled by residual scatter;
+- York errors-in-variables regression for 3+ observation fits when every observation
+  has both measurement-current and resistance standard uncertainty, including
+  first-order propagation of current uncertainty into the `I²` coordinate, optional
+  within-observation current/resistance error correlation, chi-square diagnostics,
+  and parameter covariance from the supplied coordinate-uncertainty model without
+  residual rescaling;
 - model-based interpretation of the 3+ observation fit into zero-power, observed,
   and fitted temperatures together with observed/fitted `I²R` powers; and
 - first-order propagation of the full fitted intercept/slope covariance into the
@@ -173,10 +179,9 @@ Implemented in the current 0.8.0 development checkpoint:
 
 Remaining 0.8.0 scope includes:
 
-- errors-in-variables extensions to larger-observation fitting where measurement-
-  current uncertainty is material, plus any defensible correlated-observation
-  treatment and experiment-specific residual acceptance criteria that can be stated
-  without inventing universal thresholds.
+- cross-observation covariance treatment where a defensible model exists, plus any
+  experiment-specific residual acceptance criteria that can be stated without
+  inventing universal thresholds.
 
 The package will analyze supplied current/resistance observations. It will not
 control excitation current, ADCs, bridges, MAX31865 devices, or other acquisition

learn/api/self-heating.md

@@ -72,6 +72,8 @@ fit_zero_power_resistance(
     observations: Iterable[SelfHeatingObservation],
     *,
     resistance_standard_uncertainties_ohms: Iterable[float] | None = None,
+    measurement_current_standard_uncertainties_a: Iterable[float] | None = None,
+    current_resistance_error_correlations: Iterable[float] | None = None,
     context: SelfHeatingExperimentContext | None = None,
 ) -> ZeroPowerResistanceFitResult
 ```
@@ -91,9 +93,17 @@ The default multi-observation path uses **unweighted ordinary least squares** in
 resistance. If every observation has an absolute resistance standard uncertainty,
 pass those values with `resistance_standard_uncertainties_ohms`; the same function
 then uses inverse-variance weighted least squares with weights proportional to
-`1/u²`. The `I²` coordinate remains fixed/exact in both cases, so this is not an
-errors-in-variables treatment for uncertain measurement current. Optional
-``context`` is retained as non-behavioral provenance and does not alter the fit.
+`1/u²`. The `I²` coordinate remains fixed/exact in those two modes.
+
+If every observation also has a measurement-current standard uncertainty, pass it
+with `measurement_current_standard_uncertainties_a`. The fit then uses York
+errors-in-variables regression in `(I², R)` coordinates. Current uncertainty is
+propagated to the squared-current coordinate with the first-order relation
+`u(I²) = 2 I u(I)`. Optional `current_resistance_error_correlations` supply one
+within-observation correlation coefficient per current/resistance pair; omitted
+coefficients are recorded as zero. The York path does not infer covariance between
+separate observations. Optional ``context`` remains non-behavioral provenance and
+does not alter any fit.
 
 ```python
 weighted_fit = self_heating.fit_zero_power_resistance(
@@ -106,10 +116,25 @@ print(weighted_fit.evidence.chi_squared)
 print(weighted_fit.evidence.reduced_chi_squared)
 ```
 
-The uncertainties must be finite, positive, and match the observation count. They
-are treated as absolute independent resistance-domain standard uncertainties and
-are never inferred from replicate scatter. `rtd-sensor` does not define a universal
-acceptable reduced-chi-square threshold.
+The uncertainty sequences must be finite, positive, and match the observation
+count. Errors-in-variables fitting requires both current and resistance standard
+uncertainties. Correlation coefficients must lie from `-1` through `1`. These values
+are supplied measurement evidence; `rtd-sensor` does not infer them from replicate
+scatter or shared instrumentation and does not define a universal acceptable
+reduced-chi-square threshold.
+
+```python
+eiv_fit = self_heating.fit_zero_power_resistance(
+    observations,
+    resistance_standard_uncertainties_ohms=(0.002, 0.002, 0.005, 0.005),
+    measurement_current_standard_uncertainties_a=(2e-7, 2e-7, 5e-7, 5e-7),
+    current_resistance_error_correlations=(0.0, 0.0, 0.2, 0.2),
+)
+
+print(eiv_fit.evidence.current_squared_standard_uncertainties_a2)
+print(eiv_fit.evidence.errors_in_variables_effective_weights)
+print(eiv_fit.evidence.chi_squared)
+```
 
 ## `assess_zero_power_extrapolation`
 
@@ -230,13 +255,19 @@ residual_standard_deviation_ohms: float
 fitted_resistances_ohms: tuple[float, ...]
 context: SelfHeatingExperimentContext | None
 resistance_standard_uncertainties_ohms: tuple[float, ...] | None
+measurement_current_standard_uncertainties_a: tuple[float, ...] | None
+current_resistance_error_correlations: tuple[float, ...] | None
+current_squared_standard_uncertainties_a2: tuple[float, ...] | None
 effective_weights: tuple[float, ...] | None
+errors_in_variables_effective_weights: tuple[float, ...] | None
+errors_in_variables_iteration_count: int | None
 chi_squared: float | None
 reduced_chi_squared: float | None
 weighted_rms_residual_ohms: float | None
 method: (
     "ordinary_least_squares_resistance_vs_current_squared"
     | "inverse_variance_weighted_least_squares_resistance_vs_current_squared"
+    | "york_errors_in_variables_resistance_vs_current_squared"
 )
 ```
 
@@ -262,13 +293,14 @@ Estimates fitted-parameter covariance using the statistical model retained by th
 fit. For an unweighted fit, the calculation uses residual variance
 `SSE / residual_degrees_of_freedom` and ordinary-least-squares covariance. For an
 inverse-variance weighted fit, covariance comes directly from the supplied absolute
-resistance standard uncertainties and is not rescaled by residual scatter or
-reduced chi-square. Measurement-current-squared coordinates remain fixed/exact in
-both cases.
+resistance standard uncertainties. For a York errors-in-variables fit, covariance
+comes from the York adjusted coordinates and the supplied current/resistance
+coordinate uncertainty model. Neither absolute-uncertainty path is rescaled by
+residual scatter or reduced chi-square.
 
-Measurement-current uncertainty and correlated observation errors still require a
-different or larger statistical model. Fitted RTD-model covariance also remains
-separate.
+The York path can represent correlation between current and resistance errors
+within each observation. Correlation between separate observations still requires a
+larger covariance model. Fitted RTD-model covariance also remains separate.
 
 ## `ZeroPowerResistanceFitUncertaintyResult`
 
@@ -355,19 +387,23 @@ propagate_zero_power_fit_temperature_uncertainty(
 
 Propagates the full retained covariance of the fitted zero-power resistance and
 ``dR/d(I²)`` slope through the supplied RTD model. The covariance may come from
-residual-scatter OLS or from supplied absolute resistance uncertainties in the
-weighted fit. The result reports fit-covariance uncertainty for the zero-power
-temperature, each fitted temperature, and each fitted temperature rise.
+residual-scatter OLS, supplied absolute resistance uncertainties in the weighted
+fit, or a York errors-in-variables coordinate-uncertainty model. The result reports
+fit-parameter-covariance uncertainty for the zero-power temperature, each fitted
+temperature, and each fitted temperature rise.
 
 At sampled ``x = I²``, fitted resistance depends on the retained parameters as
 ``R0 + k*x``. The fitted-temperature sensitivity vector is the local ``dT/dR``
 times ``(1, x)``. Temperature-rise sensitivities subtract the zero-power
 temperature sensitivity first, preserving the shared fitted intercept and the
 intercept/slope covariance.
 
-This is first-order/local propagation. The RTD model is treated as fixed and no
-measurement-current uncertainty, additional resistance uncertainty, model-parameter
-covariance, or correlated experiment effects are inserted automatically.
+This is first-order/local propagation. For a York fit, measurement-current
+uncertainty has already influenced the fitted-parameter covariance, but no separate
+direct uncertainty term is added for the nominal sampled current coordinate used to
+report each fitted point. The RTD model is treated as fixed and no additional
+resistance uncertainty, model-parameter covariance, or cross-observation correlated
+experiment effects are inserted automatically.
 
 ## `ZeroPowerResistanceFitTemperatureUncertaintyResult`
 
@@ -419,6 +455,14 @@ The two-current correction path is intentionally not accepted here. Its two poin
 exactly determine the resistance line, so the named context-bound characterization
 remains on the larger-observation path with residual diagnostics and fit covariance.
 
+The current coefficient calculation also rejects York errors-in-variables fits.
+When measurement-current uncertainty is material, fitted ``I²R`` power depends
+directly on an uncertain current coordinate; propagating only the fitted intercept/
+slope covariance would omit that dependence. The EIV fit can still be used for the
+zero-power extrapolation and its temperature interpretation, but coefficient
+characterization remains on the fixed-current OLS/WLS paths until that downstream
+uncertainty model is defined.
+
 ## `SelfHeatingCoefficientResult`
 
 **Introduced in:** rtd-sensor 0.8.0