mcup 1.0.0__py3-none-any.whl

mcup/__init__.py

@@ -0,0 +1,4 @@
+from .data_generator import DataGenerator as DataGenerator
+from .deming import DemingRegressor as DemingRegressor
+from .weighted import WeightedRegressor as WeightedRegressor
+from .xy_weighted import XYWeightedRegressor as XYWeightedRegressor

mcup/_analytical.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+from numdifftools import Jacobian
+from scipy.optimize import minimize
+
+
+def ols_solve(
+    func: Callable,
+    X: np.ndarray,
+    y: np.ndarray,
+    p0: np.ndarray,
+    optimizer: str,
+) -> tuple[np.ndarray, np.ndarray]:
+    def cost(params: np.ndarray) -> float:
+        r = np.array([y[i] - func(X[i], params) for i in range(len(y))])
+        return float(r @ r)
+
+    result = minimize(cost, p0, method=optimizer)
+    params = result.x
+    n, p = len(y), len(params)
+
+    J = Jacobian(lambda q: np.array([func(X[i], q) for i in range(len(X))]))(params)
+    residuals = np.array([y[i] - func(X[i], params) for i in range(len(y))])
+    sigma2 = float(np.sum(residuals**2)) / max(n - p, 1)
+
+    try:
+        cov = sigma2 * np.linalg.inv(J.T @ J)
+    except np.linalg.LinAlgError:
+        cov = np.full((len(params), len(params)), np.nan)
+
+    return params, cov
+
+
+def analytical_solve(
+    func: Callable,
+    X: np.ndarray,
+    y: np.ndarray,
+    weights: np.ndarray,
+    p0: np.ndarray,
+    optimizer: str,
+) -> tuple[np.ndarray, np.ndarray]:
+    W = np.diag(weights)
+
+    def cost(params: np.ndarray) -> float:
+        r = np.array([y[i] - func(X[i], params) for i in range(len(y))])
+        return float(r @ W @ r)
+
+    result = minimize(cost, p0, method=optimizer)
+    params = result.x
+
+    J = Jacobian(lambda p: np.array([func(X[i], p) for i in range(len(X))]))(params)
+    cov = np.linalg.inv(J.T @ W @ J)
+    return params, cov
+
+
+def deming_analytical_solve(
+    func: Callable,
+    X_obs: np.ndarray,
+    y_obs: np.ndarray,
+    x_err: np.ndarray,
+    y_err: np.ndarray,
+    p0: np.ndarray,
+    optimizer: str,
+) -> tuple[np.ndarray, np.ndarray]:
+    n_beta = len(p0)
+    n = len(y_obs)
+    x_var: np.ndarray = x_err**2  # type: ignore[assignment]
+    y_var: np.ndarray = y_err**2  # type: ignore[assignment]
+    theta0 = np.concatenate([p0, X_obs.ravel()])
+
+    def cost(theta: np.ndarray) -> float:
+        beta = theta[:n_beta]
+        eta = theta[n_beta:].reshape(X_obs.shape)
+        x_term: float = float(np.sum((X_obs - eta) ** 2 / x_var))
+        y_term: float = float(
+            np.sum((y_obs - np.array([func(eta[i], beta) for i in range(n)])) ** 2 / y_var)
+        )
+        return x_term + y_term
+
+    def residuals(theta: np.ndarray) -> np.ndarray:
+        beta = theta[:n_beta]
+        eta = theta[n_beta:].reshape(X_obs.shape)
+        r_x = (X_obs - eta) / x_err
+        r_y = (y_obs - np.array([func(eta[i], beta) for i in range(n)])) / y_err
+        return np.concatenate([r_x.ravel(), r_y.ravel()])  # type: ignore[no-any-return]
+
+    result = minimize(cost, theta0, method=optimizer)
+    theta = result.x
+    beta = theta[:n_beta]
+
+    J = Jacobian(residuals)(theta)
+    try:
+        full_cov = np.linalg.inv(J.T @ J)
+    except np.linalg.LinAlgError:
+        full_cov = np.full((len(theta0), len(theta0)), np.nan)
+
+    cov = full_cov[:n_beta, :n_beta]
+    return beta, cov

mcup/_mc.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+import numpy as np
+from scipy.optimize import minimize
+
+from ._utils import welford_finalize, welford_update
+
+
+def mc_solve(
+    cost_fn_builder: Callable,
+    X: np.ndarray,
+    y: np.ndarray,
+    x_err: Optional[np.ndarray],
+    y_err: np.ndarray,
+    p0: np.ndarray,
+    n_iter: int,
+    rtol: Optional[float],
+    atol: Optional[float],
+    optimizer: str,
+    extract_params: Optional[Callable] = None,
+    p0_fn: Optional[Callable] = None,
+) -> tuple[np.ndarray, np.ndarray, int]:
+    def _default_extract(theta: np.ndarray) -> np.ndarray:
+        return theta
+
+    def _default_p0_fn(x_s: np.ndarray, y_s: np.ndarray) -> np.ndarray:
+        return p0
+
+    _extract: Callable = extract_params if extract_params is not None else _default_extract
+    _p0_fn: Callable = p0_fn if p0_fn is not None else _default_p0_fn
+
+    n_tracked = len(_extract(p0))
+    n, mean, cov_agg = 0, np.zeros(n_tracked), np.zeros((n_tracked, n_tracked))
+    current_est = _extract(p0).copy()
+
+    def _step(x_s: np.ndarray, y_s: np.ndarray) -> None:
+        nonlocal n, mean, cov_agg, current_est
+        cost = cost_fn_builder(x_s, y_s, current_est)
+        result = minimize(cost, _p0_fn(x_s, y_s), method=optimizer)
+        if result.success:
+            tracked = _extract(result.x)
+            n, mean, cov_agg = welford_update(n, mean, cov_agg, tracked)
+            current_est = mean.copy()
+
+    x_noise_shape = X.shape
+    y_noise_shape = y.shape
+
+    if rtol is not None and atol is not None:
+        mean_prev = np.full(n_tracked, np.inf)
+        std_prev = np.full(n_tracked, np.inf)
+        max_iter = n_iter if n_iter is not None else 100_000
+        for _ in range(max_iter):
+            if x_err is not None:
+                x_s = X + np.random.normal(0, 1, x_noise_shape) * x_err
+            else:
+                x_s = X.copy()
+            y_s = y + np.random.normal(0, 1, y_noise_shape) * y_err
+            _step(x_s, y_s)
+            if n > 1:
+                std = np.sqrt(np.diag(welford_finalize(n, cov_agg)))
+                if np.allclose(mean, mean_prev, rtol=rtol, atol=atol) and np.allclose(
+                    std, std_prev, rtol=rtol, atol=atol
+                ):
+                    break
+                mean_prev, std_prev = mean.copy(), std.copy()
+    else:
+        for _ in range(n_iter):
+            if x_err is not None:
+                x_s = X + np.random.normal(0, 1, x_noise_shape) * x_err
+            else:
+                x_s = X.copy()
+            y_s = y + np.random.normal(0, 1, y_noise_shape) * y_err
+            _step(x_s, y_s)
+
+    return mean, welford_finalize(n, cov_agg), n

mcup/_utils.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import contextlib
+from typing import Generator, Optional
+
+import numpy as np
+
+
+@contextlib.contextmanager
+def local_numpy_seed(seed: Optional[int]) -> Generator[None, None, None]:
+    if seed is not None:
+        state = np.random.get_state()
+        np.random.seed(seed)
+    try:
+        yield
+    finally:
+        if seed is not None:
+            np.random.set_state(state)
+
+
+def welford_update(
+    n: int,
+    mean: np.ndarray,
+    cov_agg: np.ndarray,
+    x: np.ndarray,
+) -> tuple[int, np.ndarray, np.ndarray]:
+    n = n + 1
+    delta = x - mean
+    mean = mean + delta / n
+    cov_agg = cov_agg + np.outer(delta, x - mean)
+    return n, mean, cov_agg
+
+
+def welford_finalize(n: int, cov_agg: np.ndarray) -> np.ndarray:
+    if n < 2:
+        return np.full_like(cov_agg, np.nan)  # type: ignore[no-any-return]
+    return cov_agg / (n - 1)  # type: ignore[no-any-return]

mcup/base.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple, Union
+
+import numpy as np
+
+
+class BaseRegressor:
+    def __init__(
+        self,
+        func: Callable,
+        method: str = "mc",
+        n_iter: int = 10_000,
+        rtol: Optional[float] = None,
+        atol: Optional[float] = None,
+        optimizer: str = "Nelder-Mead",
+    ) -> None:
+        self.func = func
+        self.method = method
+        self.n_iter = n_iter
+        self.rtol = rtol
+        self.atol = atol
+        self.optimizer = optimizer
+
+    def get_params(self, deep: bool = True) -> Dict[str, Any]:
+        return {
+            "func": self.func,
+            "method": self.method,
+            "n_iter": self.n_iter,
+            "rtol": self.rtol,
+            "atol": self.atol,
+            "optimizer": self.optimizer,
+        }
+
+    def set_params(self, **params: Any) -> BaseRegressor:
+        for k, v in params.items():
+            setattr(self, k, v)
+        return self
+
+    def _check_is_fitted(self) -> None:
+        if not hasattr(self, "params_"):
+            raise ValueError("Estimator is not fitted. Call fit() first.")
+
+    def _validate_inputs(
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        y_err: np.ndarray,
+        x_err: Optional[np.ndarray] = None,
+    ) -> Union[
+        Tuple[np.ndarray, np.ndarray, np.ndarray],
+        Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray],
+    ]:
+        X = np.asarray(X, dtype=float)
+        y = np.asarray(y, dtype=float)
+        y_err = np.asarray(y_err, dtype=float)
+        if X.shape[0] != y.shape[0]:
+            raise ValueError("X and y must have the same number of samples.")
+        if y_err.shape != y.shape:
+            raise ValueError("y_err must have the same shape as y.")
+        if x_err is not None:
+            x_err = np.asarray(x_err, dtype=float)
+            if x_err.shape != X.shape:
+                raise ValueError("x_err must have the same shape as X.")
+            return X, y, y_err, x_err
+        return X, y, y_err
+
+    def fit(self, X: np.ndarray, y: np.ndarray, **kwargs: Any) -> "BaseRegressor":
+        raise NotImplementedError

mcup/data_generator.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, Union
+
+import numpy as np
+
+from ._utils import local_numpy_seed
+
+
+class DataGenerator:
+    """Generates synthetic x/y data with optional noise for testing estimators.
+
+    Parameters:
+        fun: Function for generating y data.
+        data_len: Length of the data.
+        boundaries: 1D ``[a, b]`` or 2D ``[[a_1, b_1], ...]`` array defining x intervals.
+        seed: Optional seed for the noise generator.
+        dtype: NumPy dtype for generated arrays. Default ``np.float64``.
+        params: Optional parameter array passed as second argument to ``fun``.
+    """
+
+    def __init__(
+        self,
+        fun: Callable,
+        data_len: int,
+        boundaries: Union[list, np.ndarray],
+        seed: Optional[int] = None,
+        dtype: Any = np.float64,
+        params: Optional[np.ndarray] = None,
+    ) -> None:
+        if not callable(fun):
+            raise TypeError("Argument fun has to be callable.")
+
+        if not isinstance(data_len, int):
+            raise TypeError("Argument data_len has to be integer.")
+
+        if not isinstance(boundaries, (list, np.ndarray)):
+            raise TypeError("Argument data_len has to be list or np.ndarray")
+
+        b: np.ndarray = np.array(boundaries) if isinstance(boundaries, list) else boundaries
+
+        if b.ndim != 2 and b.ndim != 1:
+            raise TypeError(
+                "Argument boundaries has to have exactly dimensionality of two or one."
+            )
+
+        if b.ndim == 2 and b.shape[0] == 1:
+            b = b[0]
+
+        if b.ndim == 2:
+            self.x_dim = b.shape[0]
+            if b.shape[1] != 2:
+                raise TypeError(
+                    "Argument boundaries has to have defined all intervals "
+                    "with exactly two numbers."
+                )
+
+            for dim_i in range(self.x_dim):
+                if b[dim_i][0] >= b[dim_i][1]:
+                    raise TypeError("Invalid interval in argument boundaries.")
+
+            self.x = np.linspace(
+                b[:, 0],
+                b[:, 1],
+                data_len,
+                dtype=dtype,
+                endpoint=True,
+            )
+
+        elif b.ndim == 1:
+            if b.shape[0] != 2:
+                raise TypeError(
+                    "Argument boundaries has to have interval with exactly two numbers."
+                )
+
+            self.x_dim = 1
+            if b[0] > b[1]:
+                raise TypeError("Invalid interval in argument boundaries.")
+
+            self.x = np.linspace(
+                b[0],
+                b[1],
+                data_len,
+                dtype=dtype,
+                endpoint=True,
+            )
+
+        self.data_len = data_len
+        self.seed = seed
+        self.y = np.zeros((data_len), dtype=dtype)
+        for i in range(self.data_len):
+            if params is None:
+                self.y[i] = fun(self.x[i])
+            else:
+                self.y[i] = fun(self.x[i], params)
+
+    def __add_noise(
+        self,
+        data: np.ndarray,
+        const_err: Optional[float] = None,
+        stat_error: Optional[float] = None,
+    ) -> np.ndarray:
+        assert const_err is not None or stat_error is not None
+
+        if stat_error is None:
+            assert const_err is not None
+            data_ret: np.ndarray = data + np.random.normal(loc=0.0, scale=const_err)
+        elif const_err is None:
+            data_ret = np.multiply(data, np.random.normal(loc=1.0, scale=stat_error))
+        else:
+            data_ret = np.multiply(
+                data, np.random.normal(loc=1.0, scale=stat_error)
+            ) + np.random.normal(loc=0.0, scale=const_err)
+
+        return data_ret
+
+    def add_noise_x(
+        self,
+        const_err: Optional[float] = None,
+        stat_error: Optional[float] = None,
+    ) -> np.ndarray:
+        with local_numpy_seed(self.seed):
+            return self.__add_noise(self.x, const_err=const_err, stat_error=stat_error)
+
+    def add_noise_y(
+        self,
+        const_err: Optional[float] = None,
+        stat_error: Optional[float] = None,
+    ) -> np.ndarray:
+        with local_numpy_seed(self.seed):
+            return self.__add_noise(self.y, const_err=const_err, stat_error=stat_error)

mcup/deming.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+import numpy as np
+
+from ._analytical import deming_analytical_solve
+from ._mc import mc_solve
+from .base import BaseRegressor
+
+
+class DemingRegressor(BaseRegressor):
+    """Regression estimator using Deming (total least squares) joint optimisation.
+
+    Optimises jointly over model parameters and latent true x values, giving an
+    exact treatment of both x and y measurement errors. Slower than
+    ``XYWeightedRegressor`` but more accurate when x errors are large or the
+    model is strongly nonlinear.
+
+    Supports two solvers selected via the ``method`` argument:
+
+    - ``"analytical"`` — joint optimisation with ``(J^T W J)^{-1}`` covariance.
+    - ``"mc"`` — Monte Carlo sampling with Welford online covariance
+      (default, robust for nonlinear models).
+
+    Parameters:
+        func: Model function with signature ``func(x, params) -> float``.
+        method: Solver to use, either ``"analytical"`` or ``"mc"``. Default ``"mc"``.
+        n_iter: Maximum number of Monte Carlo iterations. Default ``10_000``.
+        rtol: Relative tolerance for MC convergence stopping. Default ``None`` (disabled).
+        atol: Absolute tolerance for MC convergence stopping. Default ``None`` (disabled).
+        optimizer: SciPy optimizer name used for parameter fitting. Default ``"BFGS"``.
+
+    Attributes:
+        params_: Fitted parameter array.
+        params_std_: Standard deviations of fitted parameters.
+        covariance_: Full parameter covariance matrix.
+        n_iter_: Actual number of MC iterations run (MC method only).
+    """
+
+    def __init__(
+        self,
+        func: Callable,
+        method: str = "mc",
+        n_iter: int = 10_000,
+        rtol: Optional[float] = None,
+        atol: Optional[float] = None,
+        optimizer: str = "BFGS",
+    ) -> None:
+        super().__init__(
+            func,
+            method=method,
+            n_iter=n_iter,
+            rtol=rtol,
+            atol=atol,
+            optimizer=optimizer,
+        )
+
+    def fit(  # type: ignore[override]
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        x_err: np.ndarray,
+        y_err: np.ndarray,
+        p0: np.ndarray,
+    ) -> "DemingRegressor":
+        X, y, y_err, x_err = self._validate_inputs(X, y, y_err, x_err)  # type: ignore[misc]
+        p0 = np.asarray(p0, dtype=float)
+        n_beta = len(p0)
+        n_data = len(y)
+
+        if self.method == "analytical":
+            params, cov = deming_analytical_solve(
+                self.func, X, y, x_err, y_err, p0, self.optimizer
+            )
+            self.params_ = params
+            self.covariance_ = cov
+            self.params_std_ = np.sqrt(np.diag(cov))
+        else:
+            x_var: np.ndarray = x_err**2  # type: ignore[assignment]
+            y_var: np.ndarray = y_err**2  # type: ignore[assignment]
+
+            def cost_fn_builder(
+                x_s: np.ndarray, y_s: np.ndarray, params_est: np.ndarray
+            ) -> object:
+                def cost(theta: np.ndarray) -> float:
+                    beta = theta[:n_beta]
+                    eta = theta[n_beta:].reshape(X.shape)
+                    x_term: float = float(np.sum((x_s - eta) ** 2 / x_var))
+                    y_term: float = float(
+                        np.sum(
+                            (y_s - np.array([self.func(eta[i], beta) for i in range(n_data)])) ** 2
+                            / y_var
+                        )
+                    )
+                    return x_term + y_term
+
+                return cost
+
+            def extract_params(theta: np.ndarray) -> np.ndarray:
+                return theta[:n_beta]
+
+            def p0_fn(x_s: np.ndarray, y_s: np.ndarray) -> np.ndarray:
+                return np.concatenate([p0, x_s.ravel()])  # type: ignore[no-any-return]
+
+            theta0 = np.concatenate([p0, X.ravel()])
+
+            mean, cov, n = mc_solve(
+                cost_fn_builder,
+                X,
+                y,
+                x_err,
+                y_err,
+                theta0,
+                self.n_iter,
+                self.rtol,
+                self.atol,
+                self.optimizer,
+                extract_params=extract_params,
+                p0_fn=p0_fn,
+            )
+            self.params_ = mean
+            self.covariance_ = cov
+            self.params_std_ = np.sqrt(np.diag(cov))
+            self.n_iter_ = n
+
+        return self

mcup/weighted.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import numpy as np
+
+from ._analytical import analytical_solve
+from ._mc import mc_solve
+from .base import BaseRegressor
+
+
+class WeightedRegressor(BaseRegressor):
+    """Regression estimator for data where only y has measurement errors.
+
+    Minimises the weighted chi-squared objective ``Σ (y - f(x))² / σ_y²``.
+    Supports two solvers selected via the ``method`` argument:
+
+    - ``"analytical"`` — weighted least squares with ``(J^T W J)^{-1}`` covariance (fast).
+    - ``"mc"`` — Monte Carlo sampling with Welford online covariance (robust for nonlinear models).
+
+    Parameters:
+        func: Model function with signature ``func(x, params) -> float``.
+        method: Solver to use, either ``"analytical"`` or ``"mc"``. Default ``"mc"``.
+        n_iter: Maximum number of Monte Carlo iterations. Default ``10_000``.
+        rtol: Relative tolerance for MC convergence stopping. Default ``None`` (disabled).
+        atol: Absolute tolerance for MC convergence stopping. Default ``None`` (disabled).
+        optimizer: SciPy optimizer name used for parameter fitting. Default ``"Nelder-Mead"``.
+
+    Attributes:
+        params_: Fitted parameter array.
+        params_std_: Standard deviations of fitted parameters.
+        covariance_: Full parameter covariance matrix.
+        n_iter_: Actual number of MC iterations run (MC method only).
+    """
+
+    def fit(  # type: ignore[override]
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        y_err: np.ndarray,
+        p0: np.ndarray,
+    ) -> "WeightedRegressor":
+        X, y, y_err = self._validate_inputs(X, y, y_err)  # type: ignore[misc]
+        p0 = np.asarray(p0, dtype=float)
+        self._y_err_fit_ = y_err
+
+        weights = 1.0 / (y_err**2)
+
+        if self.method == "analytical":
+            params, cov = analytical_solve(self.func, X, y, weights, p0, self.optimizer)
+            self.params_ = params
+            self.covariance_ = cov
+            self.params_std_ = np.sqrt(np.diag(cov))
+        else:
+
+            def cost_fn_builder(
+                x_s: np.ndarray, y_s: np.ndarray, params_est: np.ndarray
+            ) -> object:
+                w = 1.0 / (y_err**2)
+
+                def cost(params: np.ndarray) -> float:
+                    r = np.array([y_s[i] - self.func(x_s[i], params) for i in range(len(y_s))])
+                    return float(np.dot(r**2, w))
+
+                return cost
+
+            mean, cov, n = mc_solve(
+                cost_fn_builder,
+                X,
+                y,
+                None,
+                y_err,
+                p0,
+                self.n_iter,
+                self.rtol,
+                self.atol,
+                self.optimizer,
+            )
+            self.params_ = mean
+            self.covariance_ = cov
+            self.params_std_ = np.sqrt(np.diag(cov))
+            self.n_iter_ = n
+
+        return self

mcup/xy_weighted.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+from numdifftools import Gradient
+
+from ._analytical import analytical_solve
+from ._mc import mc_solve
+from .base import BaseRegressor
+
+
+def _combined_weights(
+    func: Callable,
+    X: np.ndarray,
+    params: np.ndarray,
+    x_err: np.ndarray,
+    y_err: np.ndarray,
+) -> np.ndarray:
+    var: np.ndarray = y_err**2  # type: ignore[assignment]
+    for i in range(len(X)):
+        xi = np.atleast_1d(X[i])
+        df_dx = Gradient(lambda x: func(x, params))(xi)
+        xe = np.atleast_1d(x_err[i])
+        var[i] += float(np.dot(df_dx.ravel() ** 2, xe.ravel() ** 2))
+    return 1.0 / var  # type: ignore[no-any-return]
+
+
+class XYWeightedRegressor(BaseRegressor):
+    """Regression estimator for data where both x and y have measurement errors.
+
+    Uses iteratively reweighted least squares (IRLS) to combine x and y variances
+    via error propagation: ``σ_combined² = σ_y² + (∂f/∂x)² σ_x²``. Faster than
+    ``DemingRegressor`` and well-suited to mildly nonlinear models.
+
+    Supports two solvers selected via the ``method`` argument:
+
+    - ``"analytical"`` — IRLS with ``(J^T W J)^{-1}`` covariance (fast).
+    - ``"mc"`` — Monte Carlo sampling with Welford online covariance (robust for nonlinear models).
+
+    Parameters:
+        func: Model function with signature ``func(x, params) -> float``.
+        method: Solver to use, either ``"analytical"`` or ``"mc"``. Default ``"mc"``.
+        n_iter: Maximum number of Monte Carlo iterations. Default ``10_000``.
+        rtol: Relative tolerance for MC convergence stopping. Default ``None`` (disabled).
+        atol: Absolute tolerance for MC convergence stopping. Default ``None`` (disabled).
+        optimizer: SciPy optimizer name used for parameter fitting. Default ``"Nelder-Mead"``.
+
+    Attributes:
+        params_: Fitted parameter array.
+        params_std_: Standard deviations of fitted parameters.
+        covariance_: Full parameter covariance matrix.
+        n_iter_: Actual number of MC iterations run (MC method only).
+    """
+
+    def fit(  # type: ignore[override]
+        self,
+        X: np.ndarray,
+        y: np.ndarray,
+        x_err: np.ndarray,
+        y_err: np.ndarray,
+        p0: np.ndarray,
+        n_irls: int = 10,
+    ) -> "XYWeightedRegressor":
+        X, y, y_err, x_err = self._validate_inputs(X, y, y_err, x_err)  # type: ignore[misc]
+        p0 = np.asarray(p0, dtype=float)
+
+        if self.method == "analytical":
+            params = p0.copy()
+            for _ in range(n_irls):
+                weights = _combined_weights(self.func, X, params, x_err, y_err)
+                params, cov = analytical_solve(self.func, X, y, weights, params, self.optimizer)
+            self.params_ = params
+            self.covariance_ = cov
+            self.params_std_ = np.sqrt(np.diag(cov))
+        else:
+
+            def cost_fn_builder(
+                x_s: np.ndarray, y_s: np.ndarray, params_est: np.ndarray
+            ) -> object:
+                weights = _combined_weights(self.func, x_s, params_est, x_err, y_err)
+
+                def cost(params: np.ndarray) -> float:
+                    r = np.array([y_s[i] - self.func(x_s[i], params) for i in range(len(y_s))])
+                    return float(np.dot(r**2, weights))
+
+                return cost
+
+            mean, cov, n = mc_solve(
+                cost_fn_builder,
+                X,
+                y,
+                x_err,
+                y_err,
+                p0,
+                self.n_iter,
+                self.rtol,
+                self.atol,
+                self.optimizer,
+            )
+            self.params_ = mean
+            self.covariance_ = cov
+            self.params_std_ = np.sqrt(np.diag(cov))
+            self.n_iter_ = n
+
+        return self

mcup-1.0.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: mcup
+Version: 1.0.0
+Summary: Monte Carlo Uncertainty Propagation for regression with measurement errors
+Author-email: Daniel Herman <daniel.herman@protonmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/detrin/MCUP
+Keywords: physics,statistics,error,uncertainty,propagation,regression
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.8.0
+Requires-Dist: numdifftools>=0.9.39
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Requires-Dist: build>=0.10; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.4; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.20; extra == "docs"
+Dynamic: license-file
+
+# MCUP
+
+MCUP (Monte Carlo Uncertainty Propagation) is a Python library for regression with measurement errors. It provides three sklearn-like estimators that correctly propagate x and y measurement uncertainties into parameter confidence intervals.
+
+[![PyPI pyversions](https://img.shields.io/pypi/pyversions/mcup.svg)](https://pypi.org/project/mcup/) [![PyPI version](https://img.shields.io/pypi/v/mcup.svg)](https://pypi.org/project/mcup/) [![CI](https://github.com/detrin/MCUP/actions/workflows/package-main.yml/badge.svg)](https://github.com/detrin/MCUP/actions/workflows/package-main.yml) [![codecov](https://codecov.io/gh/detrin/MCUP/branch/master/graph/badge.svg?token=Dx6elQkztR)](https://codecov.io/gh/detrin/MCUP)
+
+## Install
+
+```bash
+uv add mcup
+```
+
+Or with pip:
+
+```bash
+pip install mcup
+```
+
+## Quick start
+
+The core idea: you have data where measurement noise is not uniform, or x itself is measured. MCUP gives you honest parameter uncertainties in both cases.
+
+**Case 1 — only y has errors (heteroscedastic noise)**
+
+A photodetector where noise grows with signal: points at high intensity are less reliable. OLS doesn't know that and gives overconfident slope uncertainty. `WeightedRegressor` down-weights noisy points and produces calibrated intervals.
+
+```python
+import numpy as np
+from mcup import WeightedRegressor
+
+rng = np.random.default_rng(42)
+x = np.linspace(1, 10, 30)
+y_err = 0.1 * x                  # noise grows with x
+y = 2.0 * x + 1.0 + rng.normal(0, y_err)
+
+def line(x, p):
+    return p[0] + p[1] * x
+
+# Uniform weights (wrong — ignores that high-x points are noisier)
+ols = WeightedRegressor(line, method="analytical")
+ols.fit(x, y, y_err=np.ones_like(x), p0=[0.0, 1.0])
+
+# Correct weights from measurement errors
+wls = WeightedRegressor(line, method="analytical")
+wls.fit(x, y, y_err=y_err, p0=[0.0, 1.0])
+
+print(f"OLS:      slope = {ols.params_[1]:.3f} ± {ols.params_std_[1]:.4f}  ← overconfident")
+print(f"Weighted: slope = {wls.params_[1]:.3f} ± {wls.params_std_[1]:.4f}  ← calibrated")
+# true slope = 2.0
+```
+
+**Case 2 — both x and y have errors**
+
+A spring balance where both extension (x) and force (y) are measured with error. Ignoring x-errors causes attenuation bias (slope pulled toward zero) and intervals that are far too narrow. `XYWeightedRegressor` propagates both error sources.
+
+```python
+from mcup import XYWeightedRegressor
+
+rng = np.random.default_rng(0)
+x_true = np.linspace(0.1, 2.0, 25)
+x_err, y_err = 0.05 * np.ones(25), 0.15 * np.ones(25)
+x_obs = x_true + rng.normal(0, x_err)
+y = 8.0 * x_true + rng.normal(0, y_err)   # true spring constant k=8
+
+# Ignoring x-errors (wrong)
+bad = WeightedRegressor(line, method="analytical")
+bad.fit(x_obs, y, y_err=y_err, p0=[0.0, 1.0])
+
+# Propagating both errors (correct)
+est = XYWeightedRegressor(line, method="analytical")
+est.fit(x_obs, y, x_err=x_err, y_err=y_err, p0=[0.0, 1.0])
+
+print(f"Ignoring x-err: k = {bad.params_[1]:.3f} ± {bad.params_std_[1]:.3f}  ← biased low, too narrow")
+print(f"XYWeighted:     k = {est.params_[1]:.3f} ± {est.params_std_[1]:.3f}  ← unbiased, calibrated")
+# true k = 8.0
+```
+
+## Why MCUP
+
+Standard least squares (OLS) assumes all observations are equally reliable. Real experiments break this in two common ways:
+
+- **Heteroscedastic y-errors** — measurement noise varies across the range. OLS overweights noisy points, biasing the fit and producing overconfident uncertainties.
+- **Errors in x** — when the independent variable is itself measured (time, concentration, displacement), ignoring those errors causes attenuation bias: slopes are pulled toward zero, and uncertainty intervals shrink below their true size.
+
+**Why not just use the covariance matrix from the optimizer?**
+
+When measurement errors are large, the standard approach of reading off `sqrt(diag(cov))` from the fit residuals underestimates the true parameter uncertainty. The covariance matrix tells you how well the optimizer converged — it does not propagate the uncertainty that came *in* with your data. MCUP propagates measurement noise directly through the model so that `params_std_` reflects both fit quality and input uncertainty. For a worked example comparing both approaches, see this [Kaggle notebook on measurement error in regression](https://www.kaggle.com/code/jetakow/measurement-error-in-regression).
+
+MCUP fixes both problems. The figure below illustrates the effect for a linear calibration with heteroscedastic y-errors:
+
+![Comparison of OLS vs WeightedRegressor](docs/assets/comparison_linear.png)
+
+*Left: OLS (red) fits the same data differently from weighted regression (blue) because it treats all points equally regardless of σ_y. Right: over 500 simulated experiments, OLS coverage deviates from the nominal 68.3% — WeightedRegressor stays calibrated.*
+
+## Estimators
+
+| Estimator | Use when | Error model |
+|-----------|----------|-------------|
+| `WeightedRegressor` | Only y has measurement errors | `Σ (y − f(x))² / σ_y²` |
+| `XYWeightedRegressor` | Both x and y have errors (nonlinear) | Combined variance via error propagation (IRLS) |
+| `DemingRegressor` | Both x and y have errors (linear only) | Joint optimisation over parameters + latent true x |
+
+Each estimator supports:
+- `method="analytical"` — weighted LS + `(J^T W J)^{-1}` covariance (fast, exact for well-posed problems)
+- `method="mc"` — Monte Carlo with Welford covariance (robust cross-check for nonlinear models)
+
+## Benchmark summary
+
+Validated across 13 physical scenarios (200 independent parameter configurations each). The analytical solver achieves well-calibrated 1σ uncertainty intervals on all scenarios:
+
+| Scenario | Estimator | Bias | RMSE | Coverage |
+|----------|-----------|------|------|----------|
+| Linear calibration (homo) | WeightedRegressor | +0.3% | 12.8% | ✓ 68% |
+| Linear calibration (hetero) | WeightedRegressor | +0.5% | 7.2% | ✓ 71% |
+| Radioactive decay | WeightedRegressor | −0.0% | 2.6% | ✓ 64% |
+| Power law (diffusion) | WeightedRegressor | +0.0% | 4.6% | ✓ 68% |
+| Gaussian spectral peak | WeightedRegressor | −0.1% | 1.7% | ✓ 66% |
+| Damped oscillator | WeightedRegressor | −0.4% | 7.2% | ✓ 67% |
+| Exp decay + timing errors | **XYWeightedRegressor** | −1.2% | 5.0% | ✓ 64% |
+| Hooke's law (x+y errors) | **XYWeightedRegressor** | −1.0% | 54% | ✓ 75% |
+| Beer-Lambert (x+y errors) | **XYWeightedRegressor** | +46% | 220% | ✓ 68% |
+| Method comparison | **DemingRegressor** | +14% | 111% | ✓ 64% |
+| Isotope ratio MS | **DemingRegressor** | +3.2% | 420% | ✓ 72% |
+| Small sample (n=8) | WeightedRegressor | −2.7% | 29% | ✓ 69% |
+| Low SNR | WeightedRegressor | −1.9% | 136% | ✓ 67% |
+
+Bias and RMSE are relative to the true parameter values. Large RMSE on near-zero intercepts (Beer-Lambert baseline, isotope intercept) reflects small absolute values — the coverage column is the reliable calibration metric.
+
+### OLS baseline: when ignoring measurement errors breaks uncertainty estimation
+
+Plain OLS (no error weighting) estimates parameter uncertainty from fit residuals alone — `σ² = SSR/(n−p)`. This works when noise is truly uniform. When noise varies across the range, OLS produces miscalibrated intervals even though the parameter estimates themselves may look reasonable.
+
+| Scenario | OLS coverage | WeightedRegressor coverage | What goes wrong |
+|----------|:------------:|:--------------------------:|-----------------|
+| S1 Linear (homo σ_y=0.5) | ✓ 68%/70% | ✓ 68%/70% | — OLS works; noise is uniform |
+| S2 Linear (hetero σ_y=0.1+0.1·x) | ~ 86%/72% | ✓ 71%/72% | Intervals too wide; pooled σ² inflated by noisy high-x points |
+| S3 Radioactive decay (Poisson √A) | ✗ 32%/42% | ✓ 64%/68% | Badly overconfident; large early-time counts dominate residuals |
+| S4 Power law (8% relative noise) | ✓ 66%/66% | ✓ 68%/69% | — OLS approximately ok here |
+| S5 Gaussian peak (Poisson counts) | ✗ 39%/54% | ✓ 66%/70% | Overconfident; amplitude and center poorly constrained |
+| S6 Damped oscillator (uniform σ_y) | ✓ 64%/71% | ✓ 67%/72% | — OLS works; noise is uniform |
+
+**The pattern:** OLS coverage is correct only when σ_y is constant across the range (S1, S6). As soon as noise scales with signal — Poisson counting (S3, S5) or percentage-of-reading errors (S2, S4) — the pooled residual variance is a poor proxy for per-point noise, and uncertainty intervals become unreliable. The parameter estimates themselves are often similar; it is the *uncertainty* that OLS gets wrong.
+
+### Using the wrong estimator when x has errors
+
+| Scenario | Wrong estimator | Coverage | Correct estimator | Coverage |
+|----------|-----------------|:--------:|-------------------|:--------:|
+| Exp decay + timing errors | WeightedRegressor | ✗ 30% | XYWeightedRegressor | ✓ 64% |
+| Beer-Lambert | WeightedRegressor | ✗ 7% | XYWeightedRegressor | ✓ 68% |
+| Method comparison | WeightedRegressor (OLS) | ✗ 32% | DemingRegressor | ✓ 66% |
+
+See [DEVELOPING.md](DEVELOPING.md) for contributing, running tests, and building docs.

mcup-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+mcup/__init__.py,sha256=t0sRZV6lqTWcHhwgk_wQFJLvN1A-Ie9flcGNiYcIalg,243
+mcup/_analytical.py,sha256=4VM9OR4jmAq8L4fU8nVww_OG-jUhFG4x-YFZ2ka8BmM,2988
+mcup/_mc.py,sha256=arnon-1EfPQu_azOOdrcL34QC7Bbu69xgrOS9wzmvrc,2682
+mcup/_utils.py,sha256=-bWB0lpfWGwRYIRzDXoObBa-sE04aqK3Iy6To1B2h1w,911
+mcup/base.py,sha256=IUsUOMco-ea9pr1ISJGX6AnFPD7--Wn3JyKu-C2mraw,2169
+mcup/data_generator.py,sha256=t7IeOvf4O4BToQOqNyDOwUsRfPK3zdWuzvqV-iTjNso,4263
+mcup/deming.py,sha256=PK_YvleMkbBttEUWK85s34zTyBujUALRUxj6WfrWUFI,4453
+mcup/weighted.py,sha256=PX6_lJ3SOtcwsa8FStLZPubdbZdjAH0TuUeturrowqI,2906
+mcup/xy_weighted.py,sha256=19JY54jfbnN9LbdlaoflbO9HRVqFjhzgJTiui3gDqfY,3818
+mcup-1.0.0.dist-info/licenses/LICENSE,sha256=wLrB04kUc06V33Ar3mfP3WMWcaYX-bR9auKlgASm7NA,1070
+mcup-1.0.0.dist-info/METADATA,sha256=uqX8kGl53yYm_JWD-mNNtr9z6ZnnZ93q8GNqlQH-Y3I,10380
+mcup-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mcup-1.0.0.dist-info/top_level.txt,sha256=wQnyw3YFlhcrK_VFkXApZiELVpKQ4DLsnzAXD-A8E28,5
+mcup-1.0.0.dist-info/RECORD,,

mcup-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcup-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Daniel Herman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcup-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcup