policyengine-household-wizard 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -0
- package/dist/draft-BI_Gnew1.cjs +1 -0
- package/dist/draft-DF6lMn4k.js +88 -0
- package/dist/index.cjs +1 -1
- package/dist/index.js +34 -33
- package/dist/us-household/samples/index.d.ts +38 -0
- package/dist/us-household/samples/index.d.ts.map +1 -0
- package/dist/us-household-samples.cjs +1 -0
- package/dist/us-household-samples.d.ts +1 -0
- package/dist/us-household-samples.js +61 -0
- package/dist/us-household.cjs +1 -1
- package/dist/us-household.js +239 -313
- package/package.json +6 -1
- package/src/us-household/samples/catalog.json +1 -0
- package/src/us-household/samples/index.ts +124 -0
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import { createPerson } from '../draft';
|
|
2
|
+
import type { USHouseholdDraft, USMaritalStatus, USPersonDraft } from '../types';
|
|
3
|
+
import catalog from './catalog.json';
|
|
4
|
+
|
|
5
|
+
export interface DrawUsSampleHouseholdOptions {
|
|
6
|
+
/** Omit to draw across states. State codes use two uppercase letters. */
|
|
7
|
+
stateCode?: string;
|
|
8
|
+
/** Skip copies of the previous profile in its state when another profile is available. */
|
|
9
|
+
excludeId?: string;
|
|
10
|
+
/** Returns a number from zero inclusive to one exclusive. */
|
|
11
|
+
random?: () => number;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export interface UsSampleHousehold {
|
|
15
|
+
/** A catalog slot local to this release, suitable for excludeId. */
|
|
16
|
+
id: string;
|
|
17
|
+
stateCode: string;
|
|
18
|
+
draft: USHouseholdDraft;
|
|
19
|
+
provenance: {
|
|
20
|
+
dataset: string;
|
|
21
|
+
buildId: string;
|
|
22
|
+
year: number;
|
|
23
|
+
url: string;
|
|
24
|
+
sha256: string;
|
|
25
|
+
policyengineVersion: string;
|
|
26
|
+
policyengineUsVersion: string;
|
|
27
|
+
sourceHouseholds: number;
|
|
28
|
+
eligibleHouseholds: number;
|
|
29
|
+
totalWeight: number;
|
|
30
|
+
eligibleWeight: number;
|
|
31
|
+
drawsPerState: number;
|
|
32
|
+
seed: number;
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
interface SampleProfile {
|
|
37
|
+
maritalStatus: USMaritalStatus;
|
|
38
|
+
people: Pick<
|
|
39
|
+
USPersonDraft,
|
|
40
|
+
'kind' | 'age' | 'isFullTimeStudent' | 'isDisabled' | 'employmentIncome' |
|
|
41
|
+
'selfEmploymentIncome' | 'socialSecurityIncome' | 'privatePensionIncome'
|
|
42
|
+
>[];
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
interface StateSamples {
|
|
46
|
+
populationWeight: number;
|
|
47
|
+
households: SampleProfile[];
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function profileKey(stateCode: string, profile: SampleProfile): string {
|
|
51
|
+
// The same person fields can arrive in a different key order. The order of
|
|
52
|
+
// the people themselves matters: the head and spouse occupy distinct rows.
|
|
53
|
+
const members = profile.people.map((person) =>
|
|
54
|
+
Object.entries(person).sort(([left], [right]) => left.localeCompare(right)),
|
|
55
|
+
);
|
|
56
|
+
return JSON.stringify([stateCode, profile.maritalStatus, members]);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// The generator has already drawn household slots in proportion to source
|
|
60
|
+
// weights within each state. Divide the state's eligible-household weight
|
|
61
|
+
// evenly among its slots so national draws also respect state population.
|
|
62
|
+
const states = catalog.states as Record<string, StateSamples>;
|
|
63
|
+
const slots = Object.entries(states).flatMap(([stateCode, state]) =>
|
|
64
|
+
state.households.map((household, index) => ({
|
|
65
|
+
id: `${stateCode}-${index}`,
|
|
66
|
+
stateCode,
|
|
67
|
+
weight: state.populationWeight / state.households.length,
|
|
68
|
+
profile: household,
|
|
69
|
+
profileKey: profileKey(stateCode, household),
|
|
70
|
+
})),
|
|
71
|
+
);
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Draw an editable household from the calibrated populace_us_2024 dataset in its source year.
|
|
75
|
+
* ZIP, county and other facts outside the projection stay unset.
|
|
76
|
+
*/
|
|
77
|
+
export function drawUsSampleHousehold({
|
|
78
|
+
stateCode,
|
|
79
|
+
excludeId,
|
|
80
|
+
random = Math.random,
|
|
81
|
+
}: DrawUsSampleHouseholdOptions = {}): UsSampleHousehold {
|
|
82
|
+
const matching = stateCode === undefined ? slots : slots.filter((slot) => slot.stateCode === stateCode);
|
|
83
|
+
if (!matching.length) {
|
|
84
|
+
throw new RangeError(`No sample households for state "${stateCode}".`);
|
|
85
|
+
}
|
|
86
|
+
const previous = excludeId === undefined ? undefined : matching.find((slot) => slot.id === excludeId);
|
|
87
|
+
const alternatives = previous
|
|
88
|
+
? matching.filter((slot) => slot.profileKey !== previous.profileKey)
|
|
89
|
+
: matching;
|
|
90
|
+
const pool = alternatives.length > 0 ? alternatives : matching;
|
|
91
|
+
|
|
92
|
+
const unit = random();
|
|
93
|
+
if (!Number.isFinite(unit) || unit < 0 || unit >= 1) {
|
|
94
|
+
throw new RangeError('The random draw must be at least zero and less than one.');
|
|
95
|
+
}
|
|
96
|
+
let remaining = unit * pool.reduce((sum, slot) => sum + slot.weight, 0);
|
|
97
|
+
const selected = pool.find((slot) => {
|
|
98
|
+
remaining -= slot.weight;
|
|
99
|
+
return remaining < 0;
|
|
100
|
+
}) ?? pool[pool.length - 1]; // rounding at the upper end of the last slot
|
|
101
|
+
return sampleFromSlot(selected);
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Reopen a sample from this catalog release, or return undefined for an unknown ID. */
|
|
105
|
+
export function getUsSampleHousehold(id: string): UsSampleHousehold | undefined {
|
|
106
|
+
const selected = slots.find((slot) => slot.id === id);
|
|
107
|
+
return selected && sampleFromSlot(selected);
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
function sampleFromSlot(selected: (typeof slots)[number]): UsSampleHousehold {
|
|
111
|
+
const people: USPersonDraft[] = [];
|
|
112
|
+
for (const person of selected.profile.people) {
|
|
113
|
+
people.push(createPerson(person.kind, people, person));
|
|
114
|
+
}
|
|
115
|
+
return {
|
|
116
|
+
id: selected.id,
|
|
117
|
+
stateCode: selected.stateCode,
|
|
118
|
+
provenance: { ...catalog.provenance },
|
|
119
|
+
draft: {
|
|
120
|
+
year: catalog.provenance.year, state: selected.stateCode, county: null, zip: null,
|
|
121
|
+
maritalStatus: selected.profile.maritalStatus, people,
|
|
122
|
+
},
|
|
123
|
+
};
|
|
124
|
+
}
|