twinfit 0.0.1__py3-none-any.whl

twinfit/__init__.py

@@ -0,0 +1,8 @@
+"""twinfit: bias correction of a fit through a simulator of the data.
+
+The first release provides the plug-in and the solved (indirect inference) corrections, see ``twinfit.indirect``.
+"""
+from .indirect import Correction, plugin_correction, solved_correction
+
+__all__ = ["Correction", "plugin_correction", "solved_correction", "__version__"]
+__version__ = "0.0.1"

twinfit/indirect.py

@@ -0,0 +1,125 @@
+"""Bias correction of a fit through a simulator of the data.
+
+A fit maps a record to an estimate. When the estimate is biased, because the record is short, the fitted model is approximate or the
+errors are not those the fit assumes, a simulator of the record that is right where the fit is wrong can measure that bias. Two
+corrections are provided, both for a user's fit and a user's simulator.
+
+``plugin_correction``
+    One step. The bias is measured by simulating at the estimate and fitting the simulations, and it is subtracted.
+
+``solved_correction``
+    Indirect inference with the fit as its auxiliary statistic (Gourieroux, Monfort and Renault 1993). The parameters are found at
+    which the mean fit of the simulations equals the fit of the data. The same random draws are used at every trial (common random
+    numbers), so the equation is smooth in the parameters whenever the fit is.
+
+The simulator is a callable ``simulate(theta, rng)`` returning one record, where ``rng`` is a ``numpy.random.Generator``. A
+deterministic simulator, one that ignores ``rng``, gives the binding function itself and needs only ``n_sim=1``. The fit is a
+callable ``fit(record)`` returning the estimate, a scalar or a one-dimensional array of the same length as ``theta``.
+
+With ``n_sim`` simulations the solved estimate carries, besides the sampling error of the data, a simulation error that inflates
+its variance by about ``1 + 1/n_sim`` when the simulator draws errors of the data's law (Gourieroux, Monfort and Renault 1993).
+
+Reference: C. Gourieroux, A. Monfort and E. Renault (1993), Indirect inference, Journal of Applied Econometrics 8, S85-S118,
+doi:10.1002/jae.3950080507.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy import optimize
+
+__all__ = ["Correction", "plugin_correction", "solved_correction"]
+
+
+@dataclass
+class Correction:
+    """The result of a correction.
+
+    estimate: the corrected parameters.
+    raw: the estimate that was corrected.
+    bias: the mean fit of the simulations minus the parameters they were simulated at, evaluated at the corrected estimate for the
+        solved form and at the raw estimate for the plug-in form.
+    jacobian: the derivative of the mean fit of the simulations with respect to the parameters at the corrected estimate (solved
+        form only, otherwise None). It carries a covariance of the raw estimate to the corrected one, see ``delta_covariance``.
+    converged: whether the solver met its tolerance (always True for the plug-in form).
+    n_sim: the number of simulations.
+    message: the solver's message.
+    """
+
+    estimate: np.ndarray
+    raw: np.ndarray
+    bias: np.ndarray
+    jacobian: np.ndarray | None = None
+    converged: bool = True
+    n_sim: int = 0
+    message: str = field(default="")
+
+    def delta_covariance(self, raw_covariance):
+        """The covariance of the corrected estimate from that of the raw one, through the delta method: J^-1 C J^-T."""
+        if self.jacobian is None:
+            raise ValueError("delta_covariance needs the solved form's jacobian")
+        c = np.atleast_2d(np.asarray(raw_covariance, float))
+        jinv = np.linalg.inv(self.jacobian)
+        return jinv @ c @ jinv.T
+
+
+def _seeds(seed, n_sim):
+    if n_sim < 1:
+        raise ValueError("n_sim must be at least 1")
+    return np.random.SeedSequence(seed).spawn(n_sim)
+
+
+def _mean_fit(theta, simulate, fit, seeds):
+    values = [np.atleast_1d(np.asarray(fit(simulate(theta, np.random.default_rng(s))), float)) for s in seeds]
+    out = np.mean(values, axis=0)
+    if out.shape != np.shape(theta):
+        raise ValueError(f"the fit returned shape {out.shape} for parameters of shape {np.shape(theta)}")
+    return out
+
+
+def _as_parameters(estimate):
+    theta = np.atleast_1d(np.asarray(estimate, float)).copy()
+    if theta.ndim != 1:
+        raise ValueError("the estimate must be a scalar or a one-dimensional array")
+    return theta
+
+
+def plugin_correction(estimate, simulate, fit, n_sim=200, seed=0):
+    """Subtract the bias measured at the estimate: theta_hat - (mean fit of simulations at theta_hat - theta_hat)."""
+    raw = _as_parameters(estimate)
+    bias = _mean_fit(raw, simulate, fit, _seeds(seed, n_sim)) - raw
+    return Correction(estimate=raw - bias, raw=raw, bias=bias, n_sim=n_sim, message="plug-in")
+
+
+def _jacobian(theta, simulate, fit, seeds, rel_step):
+    k = theta.size
+    jac = np.empty((k, k))
+    for j in range(k):
+        h = rel_step * max(1.0, abs(theta[j]))
+        up, down = theta.copy(), theta.copy()
+        up[j] += h
+        down[j] -= h
+        jac[:, j] = (_mean_fit(up, simulate, fit, seeds) - _mean_fit(down, simulate, fit, seeds)) / (2 * h)
+    return jac
+
+
+def solved_correction(estimate, simulate, fit, n_sim=200, seed=0, x0=None, tol=1e-10, rel_step=1e-6, maxfev=2000):
+    """Solve mean fit of simulations at theta = estimate for theta, with common random numbers.
+
+    The search starts at ``x0`` when given and otherwise at the plug-in correction, which is exact when the bias does not depend on
+    the parameters.
+    """
+    raw = _as_parameters(estimate)
+    seeds = _seeds(seed, n_sim)
+    start = _as_parameters(x0) if x0 is not None else raw - (_mean_fit(raw, simulate, fit, seeds) - raw)
+
+    def equation(theta):
+        return _mean_fit(theta, simulate, fit, seeds) - raw
+
+    sol = optimize.root(equation, start, method="hybr", tol=tol, options={"maxfev": maxfev})
+    theta = np.asarray(sol.x, float)
+    jac = _jacobian(theta, simulate, fit, seeds, rel_step)
+    bias = _mean_fit(theta, simulate, fit, seeds) - theta
+    return Correction(estimate=theta, raw=raw, bias=bias, jacobian=jac, converged=bool(sol.success), n_sim=n_sim,
+                      message=str(sol.message))

twinfit-0.0.1.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: twinfit
+Version: 0.0.1
+Summary: Bias correction of a fit through a simulator of the data (indirect inference)
+Author: Michelangelo Dondi
+License-Expression: MIT
+Keywords: indirect inference,bias correction,simulation,fitting,systematic errors
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: scipy>=1.7
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# twinfit
+
+Bias correction of a fit through a simulator of the data.
+
+A fit maps a record to an estimate. When the estimate is biased, because the record is short, the fitted model is approximate or
+the errors are not those the fit assumes, a simulator that is right where the fit is wrong can measure the bias. twinfit applies the
+same fit to simulated records and corrects the estimate in one of two ways.
+
+- `plugin_correction` measures the bias by simulating at the estimate, and subtracts it.
+- `solved_correction` finds the parameters at which the mean fit of the simulations equals the fit of the data. This is indirect
+  inference with the fit as its auxiliary statistic (Gourieroux, Monfort and Renault 1993). The same random draws are used at every
+  trial, so the equation is smooth whenever the fit is.
+
+## Install
+
+```bash
+pip install twinfit
+```
+
+## Example
+
+The maximum likelihood estimate of a Gaussian variance from ten draws is biased low by a factor 9/10. The solved correction removes
+that bias in expectation. A single record keeps its sampling error, so one corrected estimate can still sit far from the truth.
+
+```python
+import numpy as np
+from twinfit import solved_correction
+
+def simulate(theta, rng):          # one record at the parameters theta
+    return np.sqrt(theta[0]) * rng.standard_normal(10)
+
+def fit(record):                   # the fit to correct
+    return np.var(record)
+
+record = simulate([2.0], np.random.default_rng(1))
+out = solved_correction(fit(record), simulate, fit, n_sim=400)
+print(out.estimate, out.converged)
+```
+
+The result also carries the derivative of the mean fit with respect to the parameters, so that
+`out.delta_covariance(C)` carries a covariance `C` of the raw estimate to the corrected one.
+
+## Status
+
+Version 0.0.1 is the first release. Further tools are in preparation.
+
+## Reference
+
+C. Gourieroux, A. Monfort and E. Renault (1993). Indirect inference. *Journal of Applied Econometrics* 8, S85-S118.
+doi:10.1002/jae.3950080507
+
+## Licence
+
+MIT.

twinfit-0.0.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+twinfit/__init__.py,sha256=6jfhWHYAOupfRBIZI3yQRYffUjyUSKki2hAUxYA0tmM,365
+twinfit/indirect.py,sha256=bg-TOA-37dXDzcwmATBWD1duiyEFcoG7ztQUhRaeJyY,5787
+twinfit-0.0.1.dist-info/licenses/LICENSE,sha256=I_TdB-aoWaTP4wtJ2fQ3gxEfCdiaAFczigeRA2OVz7s,1075
+twinfit-0.0.1.dist-info/METADATA,sha256=QVQZNFeRb2mcMQvN4fauPijdHv_pk0C7VNGT4WaANaA,2812
+twinfit-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+twinfit-0.0.1.dist-info/top_level.txt,sha256=qNvGOE9vh4UGR8BxLrIRjMKIvovl_U7y-5JlhOftQfA,8
+twinfit-0.0.1.dist-info/RECORD,,

twinfit-0.0.1.dist-info/WHEEL

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

twinfit-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michelangelo Dondi
+
+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.

twinfit-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+twinfit