Add JOSS paper for submission

[vahid-ahmadi]

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

• OSI-approved open-source license (AGPL-3.0)
• Public repository with browsable source code
• Issue tracker readable without registration
• Public development history > 6 months
• Demonstrated research impact (government, academic, policy citations)
• Good open-source practices (CI, tests, docs, PRs, tagged releases)
• Iterative development over time
• paper.md with all 6 required sections
• paper.bib with BibTeX references
• AI Usage Disclosure
• Funding acknowledgement (Nuffield Foundation)
• ORCID IDs for all authors

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

• Complete the full name of all authors in paper.md
• ORCID IDs — All authors have real ORCIDs:
  • Max Ghenis — 0000-0002-1335-8277
  • Nikhil Woodruff — 0009-0009-5004-4910
  • Pavel Makarchuk — 0009-0003-4869-7409
  • Vahid Ahmadi — 0009-0004-1093-6272
• All co-authors confirm agreement to be listed
• Review and approve paper text
• Merge this PR to main
• Submit at https://joss.theoj.org/papers/new with the repo URL
• Disclose conflicts of interest on the submission form (e.g., all authors employed by PolicyEngine)
• Note related publications on the submission form (NIESR report, No 10 Innovation Fellows work, IEA reports)

After submission

1. A JOSS editor will open a pre-review issue at joss-reviews
2. Two reviewers will be assigned; review happens via GitHub issues
3. Respond to reviewer feedback within 2 weeks, complete changes within 4-6 weeks
4. 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

[vahid-ahmadi]

JOSS Paper Review: Comparison with Top Economics/Microsimulation JOSS Papers

I reviewed the most notable JOSS papers in economics and microsimulation — including AgentPy (39 citations, most-cited in the space), QuantEcon.py (9 pages, Nobel laureate co-author), neworder (dynamic microsimulation), BoARIO (indirect economic cost modeling), MEDUSA (distributional policy impacts), openmpp (R microsimulation), Economiccomplexity (9 citations), and BCEA (cost-effectiveness analysis).

Key finding: PolicyEngine would be the first JOSS paper for an open-source tax-benefit microsimulation model. Neither Tax-Calculator, OpenFisca, OG-Core, nor any PSL tool has a JOSS paper. The Research Impact section is unmatched by anything in comparable papers.

---

Suggested Improvements

1. Add an Architecture Diagram (inspired by AgentPy — 39 citations)

AgentPy's clean figure showing Agents → Environments → Models → Experiments → Output is likely a factor in its high citation count. The Software Design section describes 5 component groups in prose — a figure showing Dataset + Policy → Simulation → Output classes with the country-package delegation would make this immediately graspable. JOSS explicitly encourages figures.

2. Add a Code Example (inspired by QuantEcon.py)

QuantEcon's paper is mostly working code snippets. This paper has zero code. Even a short example would make it more concrete:

from policyengine import Simulation

sim = Simulation(country="us", reform={...})
sim.calculate("household_net_income")

3. Sharpen Competitive Differentiation (inspired by neworder & BCEA)

The neworder microsimulation paper does a systematic dimension-by-dimension comparison against MODGEN and LIAM2. Consider adding a comparison table:

Feature	PolicyEngine	TAXSIM	UKMOD	OpenFisca
Open source	✅	Partial	❌	✅
Multi-country	US+UK	US only	UK only	FR (+ forks)
Tax + benefits	Both	Tax only	Both	Both
Web interface	✅	❌	❌	Partial

4. Frame Around Reproducibility (inspired by Economiccomplexity — 9 citations)

Economiccomplexity's strongest move is framing open-source software as a scientific imperative for reproducibility. The Statement of Need focuses on access barriers, which is good — but adding a sentence about reproducibility of policy analysis (CBO/TPC results can't be independently verified) would resonate with JOSS reviewers who care deeply about open science.

5. Consider Trimming the Research Impact Section

This is the paper's strongest section — no other JOSS paper comes close. But it's ~60% of the body. JOSS papers typically run 3–5 pages. The government adoption and congressional citation paragraphs are the strongest; the policy research paragraph could potentially be condensed.

6. Fix Placeholder ORCIDs

Three authors have 0000-0000-0000-0000 as their ORCID. These need real ORCIDs or should be removed — JOSS reviewers will flag this immediately.

7. Engage More with Microsimulation Literature (inspired by BoARIO — 21 references)

BoARIO demonstrates deep engagement with its field's academic literature. Consider citing foundational microsimulation methodology papers (Orcutt 1957, Bourguignon & Spadaro 2006 survey) to position PolicyEngine within the academic tradition, not just against current tools.

8. State What PolicyEngine Does NOT Do (inspired by BCEA)

BCEA's "do one thing well" philosophy is effective. A brief scope statement (e.g., "PolicyEngine does not model macroeconomic feedback effects or general equilibrium") would help reviewers understand the design boundary.

---

Priority Summary

Priority	Action	Effort
🔴 High	Add architecture diagram	Medium
🔴 High	Fix placeholder ORCIDs	Low
🔴 High	Add a minimal code example	Low
🟡 Medium	Add comparison table in State of the Field	Low
🟡 Medium	Add reproducibility framing to Statement of Need	Low
🟡 Medium	Add scope/limitations sentence	Low
🟢 Lower	Condense policy research paragraph	Low
🟢 Lower	Add foundational microsimulation references	Low

[vahid-ahmadi]

@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.