Enhance SSN undocumented type imputation

[vahid-ahmadi]

Fixes #246

Implement ASEC Undocumented Algorithm (paper)

Algorithm Logic: Process of Elimination

1. Start: Assume all foreign-born non-citizens might be undocumented (code 0)
2. Remove: People with evidence of legal status → move to code 3 ("OTHER_NON_CITIZEN")
3. Result: Those remaining in code 0 have no clear indicators of legal status → likely undocumented

Target Implementation

Modify the existing add_ssn_card_type() function to apply these conditions before the random refinement step, ensuring that people meeting any of these conditions are assigned to code 3 ("OTHER_NON_CITIZEN") rather than potentially remaining as code 0 ("NONE"/undocumented).

The 14 Conditions

Condition 1: Pre-1982 Arrivals

• Logic: Remove those who arrived before 1982 (eligible for IRCA amnesty)
• Variable: PEINUSYR codes 1-7 (Before 1950 through 1980-1981)

Condition 2: Eligible Naturalized Citizens

• Logic: Remove naturalized citizens who meet time/age requirements
• Variables: PRCITSHP == 4, A_AGE >= 18, PEINUSYR (for years in US), A_MARITL, A_SPOUSE

Condition 3: Medicare Recipients

• Logic: Remove those with Medicare coverage
• Variable: MCARE == 1

Condition 4: Federal Retirement Benefits

• Logic: Remove those receiving federal government pensions
• Variables: PEN_SC1 == 3 OR PEN_SC2 == 3 (Federal government pension)

Condition 5: Social Security Disability

• Logic: Remove those receiving SS disability benefits
• Variables: RESNSS1 == 2 OR RESNSS2 == 2 (disabled adult or child)

Condition 6: Indian Health Service Coverage

• Logic: Remove those with IHS coverage
• Variable: IHSFLG == 1

Condition 7: Medicaid Recipients (State-specific adjustments needed)

• Logic: Remove Medicaid recipients (with state policy exceptions)
• Variables: CAID == 1, GESTFIPS (for state-specific rules)

Condition 8: CHAMPVA Recipients

• Logic: Remove those with CHAMPVA coverage
• Variable: CHAMPVA == 1

Condition 9: Military Health Insurance

• Logic: Remove those with TRICARE/military coverage
• Variable: MIL == 1

Condition 10: Government Employees

• Logic: Remove government workers and military personnel
• Variables: PEIO1COW codes 1-3 (federal/state/local gov) OR A_MJOCC == 11 (military)

Condition 11: Social Security Recipients

• Logic: Remove those receiving Social Security payments
• Variable: SS_YN == 1

Condition 12: Housing Assistance (State-specific adjustments needed)

• Logic: Remove housing assistance recipients (with mixed-status family exceptions)
• Variables: Household-level HPUBLIC == 1 OR HLORENT == 1, GESTFIPS

Condition 13: Veterans/Military Personnel

• Logic: Remove veterans and active military
• Variables: PEAFEVER == 1 OR A_MJOCC == 11

Condition 14: SSI Recipients

• Logic: Remove those receiving SSI for themselves (not on behalf of children)
• Variables: SSI_YN == 1, RESNSSI1/RESNSSI2 (to verify recipient)

Additional Steps

Family Correlation Adjustment (80%)

• Logic: Ensure 80% correlation between parent and child code 0 status
• Process: For parent-child pairs with mismatched code 0 status, align them 80% of the time
• Scope: Only applies to people with codes 0 or 3

Random Refinement (30%)

• Logic: Apply random assignment to the remaining code 0 non-citizens
• Process: 30% assigned to code 3, 70% remain as code 0 (likely undocumented)
• Purpose: Accounts for uncertainty in identifying undocumented status