Add JOSS paper for submission

[vahid-ahmadi]

Summary

• Adds paper.md and paper.bib for submission to the Journal of Open Source Software
• Adds CITATION.cff, CODE_OF_CONDUCT.md and .github/workflows/draft-pdf.yml, none of which the repository had
• Paper is ~1,110 words, inside JOSS's 750–1,750 range

Follows PolicyEngine/policyengine.py#264, which was accepted and published.

This is a different paper from paper/

paper/main.tex is a 39-page empirical study — SCF-to-CPS wealth imputation, an SSI policy simulation, cross-dataset benchmarking. JOSS wants a short software paper and will desk-reject a research article, so this is a new, software-focused paper.md that cites the working paper as the validation study rather than replacing it.

The framing leads on the finding that justifies the package existing: benchmarking across seven domains shows no method dominates — QRF wins on nonlinear relationships, matching better preserves marginals, OLS stays competitive when relationships are near-linear. If performance is dataset-specific, the useful contribution is a harness that measures it, which is a stronger claim than "five imputation methods".

JOSS requirements

• Public repository with browsable source
• Issue tracker readable without registration
• Public development history > 6 months — since February 2025, 474 commits, five contributors
• paper.md with Summary, Statement of Need, State of the Field, Software Design, Research Impact Statement, Acknowledgements, AI Usage Disclosure, References
• Word count 927, within 750–1,750
• paper.bib — 13 entries, all cited, no orphans, all DOIs resolve
• AI usage disclosure
• Funding acknowledgement
• CITATION.cff, validated against schema 1.2.0
• CODE_OF_CONDUCT.md
• Draft PDF workflow
• OSI-approved licence — the repository has none. See microimpute has no licence, so all rights are reserved #197
• ORCID for every author — María's is 0009-0007-4946-2248, verified against the ORCID registry
• Author list and order confirmed by all named authors

Blockers before submitting

Must fix — correctness

A pre-submission audit of the models turned up a set of silent correctness bugs. A reviewer will run these methods, and they produce plausible wrong numbers rather than errors. A second round of review, with every finding independently reproduced by an adversarial verifier before filing, added #207-#213.

• Normalization preprocessing re-fits on the receiver, erasing the level difference between datasets #202 — normalization preprocessing re-fits on the receiver, erasing the level difference between datasets. Imputed mean 29.83 against a true 90.05 in the reproduction
• Zero-inflated quantiles ignore the zero mass and are non-monotone #203 — zero-inflated quantiles ignore the zero mass; 87% of rows have non-monotone quantiles. Zero-inflated targets are the motivating case for this package
• Default QRF grows trees to purity, giving miscalibrated quantiles and inert sample weights #205 — default QRF grows trees to purity, so nominal 10th/90th percentiles cover 30%/70%, and sample weights become inert
• Model API and robustness defects found in a pre-submission audit #206 — model API and robustness defects: QuantReg.fit only fits the median, Matching returns identical values for every quantile, intercepts dropped on constant predictors, weights dropped in two places, train_size and random_state inert
• Test suite fails with 8 errors on a clean checkout without rpy2 #204 — the test suite fails with 8 errors on a clean checkout without rpy2
• Per-variable QRF models share one seed, making jointly imputed variables comonotonic #207 — every per-variable QRF model is seeded identically, so variables imputed together come out rank-comonotonic. This is on the default path, and policyengine-uk-data hits it: ten wealth variables and eleven consumption variables are each imputed in one bare predict() call. Components with ~0 true conditional correlation reproduce at 0.71 Spearman
• Log loss is computed from class labels, and integer counts are silently switched to classification #209 — log loss is computed from class labels via fabricated 0.99/0.01 probabilities, so it is an affine function of accuracy rather than a proper score, and it disagrees with cross_validate_model on the same model and data (2.14 against 0.79, truth 0.69). Integer targets with fewer than ten levels are also silently switched to classification
• Matching silently substitutes the training mean on failure, and that score is fed to Optuna #210 — Matching hyperparameter tuning substitutes the training mean on any exception, with no log or counter, and feeds that score to Optuna. A parameter set under which matching always fails can be selected as best and reported as the winning method
• OLS random quantile sampling draws only ten residual values, shared across calls and variables #208 — OLS random quantile sampling draws ten residual values regardless of row count, shared across calls and variables. Lower priority: the path is opt-in and autoimpute never reaches it

Must fix — compliance

• microimpute has no licence, so all rights are reserved #197 — no LICENSE file, no licence in packaging metadata. This is the first item on the JOSS checklist, and it also means the five downstream repositories currently depend on all-rights-reserved code
• Read the package version from installed metadata #200 — __version__ reported 1.1.2 while the package was 3.1.1 (PR open)
• Wheel ships subpackages as package data, sweeping in stale __pycache__ and working-tree junk #211 — the wheel declares only the top-level package, so subpackages ship as package data via a **/* glob that also sweeps in stale __pycache__ (501 KB of build-host bytecode in a test build). pyproject.toml also lists two of the four authors, omitting the paper's corresponding author, and carries no license, classifiers or [project.urls]
• Create a GitHub Release from a tag and archive to Zenodo for a DOI — there are six tags but zero releases
• Expand .github/CONTRIBUTING.md beyond its current 12 lines to cover dev setup, running tests, reporting issues, and where to seek support

Should fix — reviewers will raise these

• Three competing docs configs, and no installation page or API reference #198 — three competing docs configs, no installation page in the docs, no API reference
• Python version matrix does not cover the declared supported range #199 — the Python matrix does not cover the declared >=3.12,<3.15 range; 3.13 never runs on PRs, 3.14 never on main, and the full suite effectively runs on one version
• Add a usage code example to the README — the API section is prose only
• Resolve or close draft PR Make microimpute.Imputer the canonical regime-gated sequential imputer #196, which questions which class is the canonical imputer; an open question about the central API undercuts the documentation a reviewer is asked to assess
• Add CI to prevent breaking changes in policyengine-us-data #134 / PR Add downstream CI to prevent breaking policyengine-us-data #135 — downstream CI against policyengine-us-data, open since October
• Sequential imputation runs out of memory with many variables #96 — sequential imputation runs out of memory with many variables, a known limit in a headline feature
• "Normalized" mutual information divides nats by bits and drifts with sample size #212 — compute_predictor_correlations documents a normalized mutual information matrix, but divides MI in nats by an entropy in bits whose continuous-column value is log2(n_distinct). Two identical variables score 0.55 rather than 1.0, and the value drifts with sample size
• Pre-submission cleanup: API exports, validation, CI gaps, vacuous tests, dead code, stale docs #213 — grouped cleanup: ZeroInflatedImputer is undocumented and unexported although the paper describes it; autoimpute() cannot reach four Imputer.fit parameters; validation.py has no test file; MDN tests are gated out of CI by a changed-filename grep; five tests cannot fail or assert nothing; dead config; and four stale docstrings, including a compare_distributions example that is wrong on both printed values

Worth considering

• Move microimputation-dashboard/ to its own repository — a Next.js app roughly doubles the review surface for something that is not the Python package
• Add a README in paper/ clarifying that the manuscript is an unpublished working paper distinct from this submission

An honest note on impact

Every dependent is inside the PolicyEngine organisation: policyengine-uk-data, uk-trade-shock-study, uk-public-services-imputation, nics-exemption-inactive-employees, imputation-paper. There is no identifiable external user, and the repository has 0 stars. JOSS does not require external adoption but reviewers weigh it. The strongest honest framing is production dependency — a microsimulation data pipeline depends on this — rather than community uptake, and that is how the paper puts it.

Authorship to confirm

Currently María (corresponding), Max, Nikhil, Vahid — by commit share that is 354 / 101 / 45 / small. @baogorek contributed 15 commits and is acknowledged rather than listed; worth confirming that is right with him.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
microimpute-dashboard	Ready	Preview	Sep 16, 2026 11:28am UTC