twinfit 0.0.1__tar.gz

twinfit-0.0.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,54 @@
+# 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/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "twinfit"
+version = "0.0.1"
+description = "Bias correction of a fit through a simulator of the data (indirect inference)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Michelangelo Dondi" }]
+requires-python = ">=3.9"
+dependencies = ["numpy>=1.21", "scipy>=1.7"]
+keywords = ["indirect inference", "bias correction", "simulation", "fitting", "systematic errors"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

twinfit-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

twinfit-0.0.1/src/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-0.0.1/src/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/src/twinfit.egg-info/PKG-INFO

@@ -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/src/twinfit.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/twinfit/__init__.py
+src/twinfit/indirect.py
+src/twinfit.egg-info/PKG-INFO
+src/twinfit.egg-info/SOURCES.txt
+src/twinfit.egg-info/dependency_links.txt
+src/twinfit.egg-info/requires.txt
+src/twinfit.egg-info/top_level.txt
+tests/test_indirect.py

twinfit-0.0.1/src/twinfit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

twinfit-0.0.1/src/twinfit.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy>=1.21
+scipy>=1.7
+
+[test]
+pytest

twinfit-0.0.1/src/twinfit.egg-info/top_level.txt

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

twinfit-0.0.1/tests/test_indirect.py

@@ -0,0 +1,73 @@
+"""Checks of the two corrections on a case where the answer is known in closed form.
+
+The maximum likelihood estimate of a Gaussian variance from n draws, the mean of the squared deviations, has mean (n - 1)/n times the
+variance. With the simulator sqrt(theta) z the mean fit of the simulations is theta times a constant c fixed by the draws, so the
+solved correction is exactly estimate / c and the plug-in one exactly estimate (2 - c), and c itself sits near (n - 1)/n.
+"""
+import numpy as np
+import pytest
+
+from twinfit import plugin_correction, solved_correction
+
+N = 10
+
+
+def simulate_var(theta, rng):
+    return np.sqrt(theta[0]) * rng.standard_normal(N)
+
+
+def fit_var(x):
+    return np.var(x)
+
+
+def constant_c(n_sim, seed):
+    seeds = np.random.SeedSequence(seed).spawn(n_sim)
+    return np.mean([np.var(np.random.default_rng(s).standard_normal(N)) for s in seeds])
+
+
+def test_solved_is_exact_for_a_scale_family():
+    est, n_sim, seed = 1.7, 400, 3
+    c = constant_c(n_sim, seed)
+    out = solved_correction(est, simulate_var, fit_var, n_sim=n_sim, seed=seed)
+    assert out.converged
+    assert out.estimate[0] == pytest.approx(est / c, rel=1e-9)
+    assert out.jacobian[0, 0] == pytest.approx(c, rel=1e-5)
+
+
+def test_plugin_is_exact_algebra():
+    est, n_sim, seed = 1.7, 400, 3
+    c = constant_c(n_sim, seed)
+    out = plugin_correction(est, simulate_var, fit_var, n_sim=n_sim, seed=seed)
+    assert out.estimate[0] == pytest.approx(est * (2 - c), rel=1e-12)
+
+
+def test_the_constant_is_the_textbook_bias():
+    n_sim = 4000
+    c = constant_c(n_sim, 11)
+    sd = np.sqrt(2 * (N - 1)) / N / np.sqrt(n_sim)      # sd of the mean of var(z) over n_sim draws
+    assert abs(c - (N - 1) / N) < 3 * sd
+
+
+def test_vector_parameters_and_delta_covariance():
+    def simulate(theta, rng):
+        return theta[0] + np.sqrt(theta[1]) * rng.standard_normal(N)
+
+    def fit(x):
+        return np.array([np.mean(x), np.var(x)])
+
+    out = solved_correction([0.3, 2.0], simulate, fit, n_sim=300, seed=5)
+    seeds = np.random.SeedSequence(5).spawn(300)
+    zs = [np.random.default_rng(s).standard_normal(N) for s in seeds]
+    m, c = np.mean([z.mean() for z in zs]), np.mean([z.var() for z in zs])
+    assert out.converged
+    # mean fit: (mu + sqrt(v) m, v c), solved for (0.3, 2.0)
+    v = 2.0 / c
+    assert out.estimate[1] == pytest.approx(v, rel=1e-8)
+    assert out.estimate[0] == pytest.approx(0.3 - np.sqrt(v) * m, rel=1e-8, abs=1e-10)
+    cov = out.delta_covariance(np.diag([0.1, 0.2]))
+    assert cov.shape == (2, 2) and np.all(np.linalg.eigvalsh(cov) > 0)
+
+
+def test_shape_mismatch_is_refused():
+    with pytest.raises(ValueError):
+        plugin_correction([1.0, 2.0], simulate_var, fit_var, n_sim=3)