Document scale-lookup boundary conventions: right=True needs a -.inf first threshold - #85
Merged
hua7450 merged 1 commit intoSep 1, 2026
Conversation
single_amount lookups are lower-bound inclusive by default, so a source table printed as closed integer bands must be keyed by its wording: band starts with the default calc, or band tops with calc(..., right=True). The right=True form requires a -.inf first threshold, because a value exactly equal to the first threshold otherwise falls below the scale and returns 0. Adds the convention table, the first-threshold trap table, a right=True checklist, the round-before-lookup rule, and a CI-verified example to references/parameters.md; cross-reference bullets in variables.md and tests.md; and routing/trigger updates in SKILL.md. Replaces the 0.0001 threshold-shift guidance for "above X" with right=True + -.inf. Closes PolicyEngine#83 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents how to key
single_amountbracket parameters when the source table prints closed integer bands, and theright=Truetrap that bit NY IT-214 (policyengine-us #9313).Closes #83
What changed
references/parameters.md— new "Scale-lookup boundary conventions" subsection: the convention table (band starts + default calc vs. band tops +right=True), the first-threshold trap table, aright=Truechecklist, the round-half-up-before-lookup rule, and a CI-verified<!-- verify -->example.references/variables.md— gotcha bullet:right=Trueat every call site, floor/round before the lookup.references/tests.md— coverage bullet: test at exactly $0 and exactly at a band top for everysingle_amountlookup.SKILL.md— routing row and trigger words.Design decision
The convention is fixed by the source wording (statute / form / manual): band starts printed → band-start keys; "over X but not over Y" → band-top keys with
right=Trueand-.inf. The issue's original "pick one convention per program" rule was dropped: tables keyed faithfully to their own wording already agree at every boundary.This also replaces the previous
0.0001threshold-shift guidance for "above X" withright=True+-.inf, which is exact and needs no epsilon. The old pattern is mentioned as legacy so readers recognize it in existing code.Evidence (policyengine-core 3.30,
SingleAmountTaxScale.calc)Probe incomes
[-100, 0, 3000, 3001], bands "$0–3,000 → 375; 3,001+ → 330":[0, 3001][0, 375, 375, 330][-inf, 3000]right=True[375, 375, 375, 330][0, 3000]right=True[0, 0, 375, 330]← exactly $0 zeroed[0, 3000][0, 375, 330, 330]← the IT-214 bugMarginalRateTaxScale.calc(..., right=True)raisesTypeError, so the checklist notesright=exists only onsingle_amount/marginal_amountscales.np.round(3000.5) == 3000(half-to-even) vsnp.floor(3000.5 + 0.5) == 3001(half-up).Follow-up (policyengine-us, not in this PR)
A sweep of the 97
calc(..., right=True)call sites in policyengine-us found 48 whose parameter has a first threshold ≥ 0. Confirmed misfires at an input of exactly 0: CO CDCC match (0 instead of 0.5), HI CDCC rate (0 instead of 0.25), OH exemption credit ($0 instead of $20); CT personal credit rate returns 0 at exactly $15,000. Worth a separate policyengine-us issue.Test plan
uv run pytest --ignore=tests/test_skill_examples.py— 152 passed<!-- verify -->block executed against the installed core — passesskill-examplesjob🤖 Generated with Claude Code