Add JOSS paper for submission by vahid-ahmadi · Pull Request #264 · PolicyEngine/policyengine.py

vahid-ahmadi · 2026-03-23T12:02:29Z

Summary

Adds paper.md and paper.bib for submission to the Journal of Open Source Software (JOSS)
Paper covers all 6 required JOSS sections: Summary, Statement of Need, State of the Field, Software Design, Research Impact Statement, and AI Usage Disclosure
Cites adoption by 10 Downing Street, HM Treasury (Algorithmic Transparency Record), NIESR UK Living Standards Review 2025, INET Oxford (Seventh Carbon Budget), IEA reports, and House of Lords parliamentary debate
Funded by the Nuffield Foundation

What is JOSS?

JOSS is a peer-reviewed open-access journal for research software. It publishes short papers (750–1,750 words) describing open-source software with research impact. There are no submission fees. The review process happens on GitHub via openjournals/joss-reviews. See the submission guide and paper format for full details.

JOSS requirements checklist

Review suggestions status

From the self-review comment:

Add architecture diagram — architecture.png added with proper Figure 1 reference in text
Fix placeholder ORCIDs — All 4 authors have real ORCIDs
Add a minimal code example — No code snippet yet (QuantEcon-style)
Add comparison table in State of the Field — Feature table vs TAXSIM/UKMOD/OpenFisca
Add reproducibility framing to Statement of Need — Added: "Because existing proprietary models cannot be independently verified..."
Add scope/limitations sentence — Added: "PolicyEngine models static fiscal impacts; it does not model macroeconomic feedback effects or general equilibrium responses"
Condense policy research paragraph — Research Impact still ~60% of body
Add foundational microsimulation references — No Orcutt 1957 or Bourguignon & Spadaro 2006 yet

Additional fixes applied

Replaced fake pe_uk_data / pe_us_data repo citations with real Woodruff & Ghenis (2024) Enhanced CPS working paper
Fixed Claude citation year 2025 → 2026
Fixed broken Atlanta Fed Policy Rules Database URL → GitHub repo
Moved architecture figure after intro paragraph (text-first, then diagram)
Added explicit Figure 1 references in Software Design text
Verified all 27 bib URLs resolve correctly
Synced both HTML previews with paper.md

Steps before submission

After submission

A JOSS editor will open a pre-review issue at joss-reviews
Two reviewers will be assigned; review happens via GitHub issues
Respond to reviewer feedback within 2 weeks, complete changes within 4-6 weeks
Upon acceptance: create a tagged release, deposit to Zenodo for a DOI, update the review thread

Test plan

Verify paper.md renders correctly with JOSS preview tools
Confirm all paper.bib references are valid and resolve correctly

Adds paper.md and paper.bib for submission to the Journal of Open Source Software (JOSS). Paper covers all 6 required JOSS sections and cites adoption by 10 Downing Street, HM Treasury, NIESR, INET Oxford, IEA, and House of Lords parliamentary debate. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rewrites paper.md to describe the policyengine package as a unified multi-country (UK + US) microsimulation framework rather than the UK-only policyengine-uk package. Updates title, summary, statement of need, state of the field, software design, and acknowledgements to reflect the country-agnostic architecture. Adds TAXSIM and US data references to paper.bib. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Adds congressional citation (Young Adult Tax Credit Act, H.R.7547), NBER partnership (TAXSIM emulator MOU), Niskanen Center CTC report, NTA conference presentation, and Georgetown Beeck Center collaboration to the Research Impact section. Adds corresponding BibTeX entries. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Convert all British spellings to American English (organised → organized, programme → program, labour → labor, behavioural → behavioral, modelling → modeling, licence → license, etc.) - Fix Beeck Center citation: was pointing to a 2022 event but labeled as 2024. Replace with correct Better Government Lab collaboration reference (pe_bgl) - Soften Youngman et al. claim: confirmed paper cites PolicyEngine UK data but removed unverifiable direct quote - Remove unused beeck2024rac bib entry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Change country order to "the US and the UK" - Remove "via the Simulation class" from Summary - Remove inline dataset names (Enhanced FRS, CPS) from Summary - Make Statement of Need more specific about access barriers for existing models (UKMOD requires institutional application, TAXSIM covers only taxes not benefits, HMT/IFS/CBO/TPC are fully proprietary) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Update install instructions to match repo docs: pip install policyengine, policyengine[uk], policyengine[us], and uv pip install -e .[dev] for development - Remove backtick code styling from "Simulation class" in Statement of Need - Reorder State of the Field: US models first, then UK models Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Merge "Multi-country" and "Fully open-source" bullets into one - Add specific US program count (over 11) with full list: federal income tax, payroll taxes, state income taxes, SNAP, SSI, Social Security, Medicare, Medicaid, EITC, CTC, and TANF - Remove "Integration with the PolicyEngine web application" bullet Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Merge "Distributional analysis outputs" and "Labor supply dynamics" into single "Economic analysis" bullet - Change "policyengine package" to "policyengine.py package" - Delete "All code examples in the documentation are automatically re-executed" sentence - Remove "built 10ds-microsim on top of" reference, simplify to "used PolicyEngine" Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Academic research: - USC/HHS collaboration on effective marginal tax rates (Unrath) - DeBacker behavioral response modeling (Arnold Ventures) - Beeck Center rules-as-code reports (2023, 2025) Policy research: - DC District Child Tax Credit (first local CTC in US history) - Senator Booker Keep Your Pay Act calculator on Senate website - Reorder US citations before UK in both sections Acknowledgements: - Add US funders: Arnold Ventures, NEO Philanthropy ($200K grant), Gerald Huff Fund for Humanity, NSF POSE program - Keep Nuffield Foundation for UK Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add Atlanta Fed Policy Rules Database MOU for multi-model validation in Institutional partnership section - Add NSF POSE Phase I award (2518372, $299,974) with nsf.gov URL - Update NBER TAXSIM MOU reference to use taxsim.nber.org instead of policyengine.org link - Update Arnold Ventures note to mention congressional district focus - Use external/official URLs for all references where available Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Consistently place US content before UK content in every section: Summary, Statement of Need, Software Design, Research Impact (Government adoption, Congressional/Parliamentary, Academic, Policy research), and Acknowledgements. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…-installable to Python Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove pe_uk_data (no paper exists) and replace pe_us_data with Woodruff & Ghenis 2024 working paper from policyengine-us-data/paper. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vahid-ahmadi · 2026-04-02T11:47:55Z

@MaxGhenis Your ORCID is still the placeholder 0000-0000-0000-0000 in paper.md (line 12). Could you update it with your real ORCID? You can register for free at https://orcid.org/register if you don't have one yet.

Update caption to match actual diagram content and add explicit Figure 1 references in the Software Design text, following JOSS conventions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Replace pe_us_data/pe_uk_data citations with woodruff2024enhanced_cps - Update architecture figure caption and add Figure 1 text references - Remove pe_uk_data reference entry Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Update claude2025 -> claude2026 (Anthropic 2026) - Move architecture figure after intro paragraph in Software Design - Rewrite "At runtime" paragraph to better reference Figure 1 inputs - Replace broken Atlanta Fed URL with stable GitHub repo link Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Move figure after intro paragraph in Software Design - Update Claude citation year to 2026 - Replace broken Atlanta Fed URL with GitHub repo - Update "At runtime" paragraph to match paper.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add US reform code example in Software Design (QuantEcon-style) - Add Orcutt 1957 and Bourguignon & Spadaro 2006 to State of the Field - Word count: 1,665 / 1,750 JOSS limit Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…mar edits - Reorder authors: Max, Vahid, Nikhil, Pavel - Update date to 7 April 2026 - Restore UKMOD access sentence in Statement of Need - Add US models (TAXSIM, CBO, TPC) to State of the Field - Replace em dashes with commas throughout - Fix behavioral response description (income/substitution/capital gains elasticities) - Remove OpenFisca mention from Software Design first sentence - Move Better Government Lab from Government adoption to Academic research - Remove UKMOD acknowledgement - Update figure: center text in boxes, equalize arrow lengths, new output labels - Trim architecture.png whitespace - Update figure caption to match new output labels - Fix Youngman citation rendering - Add parametric/structural reform language to Statement of Need - Delete "+ operator" reference - Update macroeconomic limitation sentence - Fix missing blank line before AI Usage Disclosure Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ations - Replace promotional language (essential→standard, unified→common, harmonized→shared, Government adoption→Government use) - Convert passive voice throughout (was supported by→funders funded, were used to assist→authors used, maintained by X→which X maintains) - Fix Atlanta Fed framing: PE runs comparisons under MOU, not Fed validating PE - Add missing citations: No 10 Innovation Fellowship (Woodruff), JEC immigration calculator, Rep. Tlaib End Child Poverty Act - Remove McGarvey quote (just cite the bill) and move Booker/Keep Your Pay to congressional section - Remove "first local child tax credit in US history" (DC policy claim, not PE) - Add tested code example showing baseline-vs-reform workflow - Split dense State of the Field paragraph into two - Fix table dimensions: Country coverage, Python package (pip install), Shared reform and output API across countries - Spell out Current Population Survey (CPS) on first use - Fix architecture caption: three input concepts, dynamics in country packages - Fix SVG: Behavioural→Behavioral (American spelling), labour supply elasticities→in country packages - Remove 3 unused bib entries (ghenis2026no10, ukmod_access, pe_nber_mou) - Remove defensive counterfactual paragraph and "foundational" evaluative adjective Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add DOIs: taxsim (10.2307/3325474), youngman2026carbon (10.48550/arXiv.2602.15607) - Pin policyengine_py version to 3.4.0 in bib entry - Add expected output comment to paper code example - Mention paper_repro_uk.py reproduction script in paper - Regenerate architecture.png from updated SVG (sync Behavioral spelling and "in country packages" label) - Add CITATION.cff for machine-readable citation metadata Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Note code example results are California-specific - Fix bib key sutherland2014euromod → sutherland2013euromod to match actual publication year (2013) - Add abstract field to CITATION.cff - Add sentence describing Dynamic class and behavioral response pipeline in Software Design section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Add CODE_OF_CONDUCT.md (Contributor Covenant v2.0) — JOSS requires community governance documentation - Fix OpenFisca table entry: OpenFisca IS pip-installable (openfisca-france, openfisca-core on PyPI), change No → Yes - Fix figure/text mismatch: paper said "Figure 1 illustrates this architecture" (implying 4-layer stack) but the figure shows a runtime workflow — reword to match - Fix paper_repro_uk.py docstring: was incorrectly claiming it uses "the same reform shown in paper.md" (paper shows US reform, script uses UK reform) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…example - Fix UKMOD: mark as pip-installable via euromod Python connector (consistent with euromod_download_2026 bib note) - Fix OpenFisca country coverage: "France, Tunisia, and other jurisdictions" (was understating the ecosystem) - Fix OpenFisca reform API: "Shared core, country-specific parameters" (openfisca-core provides shared Reform class) - Fix UKMOD country coverage: "UK and EU member states" - Fix code example: 2026 standard deduction is $16,100 under OBBBA, doubled = $32,200 (was $30,950, a stale value) - Fix code example output: $42,634 (was $42,484) - Fix HM Treasury ATRS framing: "registered... as an algorithmic tool their team evaluates" (ATRS is mandatory disclosure, not endorsement) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

vahid-ahmadi requested review from MaxGhenis, nikhilwoodruff and nwoodruff-co March 23, 2026 12:03

vahid-ahmadi mentioned this pull request Mar 23, 2026

Add JOSS paper for submission PolicyEngine/policyengine-uk#1532

Closed

24 tasks

vahid-ahmadi requested a review from PavelMakarchuk March 23, 2026 12:05

vahid-ahmadi and others added 3 commits March 23, 2026 12:07

Add Pavel Makarchuk as author in JOSS paper

7fb0128

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vahid-ahmadi removed request for MaxGhenis, PavelMakarchuk, nikhilwoodruff and nwoodruff-co March 23, 2026 12:21

vahid-ahmadi marked this pull request as draft March 23, 2026 12:21

vahid-ahmadi self-assigned this Mar 23, 2026

vahid-ahmadi and others added 15 commits March 23, 2026 12:27

Reorder authors: Pavel Makarchuk before Vahid Ahmadi

f893bd3

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove all code-style backtick formatting from prose text

3dafc7e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove 'Multi-Country' from paper title

51db607

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove 'Open-Source' from paper title

0964bd5

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove dev install command from Statement of Need

ba4c107

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix double parentheses in AI disclosure, remove test scaffolding, pip…

190ebdc

…-installable to Python Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove pip install commands from Statement of Need

d70aa4d

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace fake data repo citations with real Enhanced CPS paper

e02e911

Remove pe_uk_data (no paper exists) and replace pe_us_data with Woodruff & Ghenis 2024 working paper from policyengine-us-data/paper. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vahid-ahmadi and others added 6 commits April 2, 2026 12:51

Add proper figure reference for architecture diagram in paper

915e553

Update caption to match actual diagram content and add explicit Figure 1 references in the Software Design text, following JOSS conventions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Populate Max Ghenis ORCID

b88f067

vahid-ahmadi requested review from MaxGhenis April 2, 2026 12:39

vahid-ahmadi and others added 4 commits April 2, 2026 13:40

Update paper date to 2 April 2026

e1e397d

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove 'and drafting of this paper' from AI disclosure

7e2f556

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Shorten architecture figure caption

b5d0810

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vahid-ahmadi marked this pull request as ready for review April 7, 2026 09:57

MaxGhenis and others added 15 commits April 7, 2026 07:29

Remove non-runnable paper example

e62c46d

Clarify policyengine.py JOSS positioning

0f075dc

Tighten JOSS reviewer documentation

01a317d

Tighten JOSS reviewer path and scope

bc48c4e

Add model references and package naming

134c861

Add JOSS draft PDF compilation workflow

c16c837

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

date

76f057d

Refine state of field references

1b008c0

Soften comparative paper tone

9c943f0

Merge remote-tracking branch 'origin/main' into joss-paper

b99f2be

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add JOSS paper for submission#264

Add JOSS paper for submission#264
vahid-ahmadi wants to merge 53 commits intomainfrom
joss-paper

vahid-ahmadi commented Mar 23, 2026 •

edited

Loading

Uh oh!

vahid-ahmadi commented Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

vahid-ahmadi commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What is JOSS?

JOSS requirements checklist

Review suggestions status

Additional fixes applied

Steps before submission

After submission

Test plan

Uh oh!

vahid-ahmadi commented Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vahid-ahmadi commented Mar 23, 2026 •

edited

Loading