[PULL REQUEST] Households by Workers

[GregorSchroeder]

Describe this pull request. What changes are being made?

This pull request adds to the household characteristics module, households by number of workers.

Validation and testing

Production database [run_id]=225. Checked that household size constraints were not violated at the MGRA level and checked the 18+ population soft constraint was also respected. See SQL code below.

DECLARE @run_id INTEGER = 225;

-- Check soft constraint of persons aged 18+
WITH [Household Size] AS (
	SELECT
		[year],
		[mgra],
		SUM(
			CASE
				WHEN [metric] = 'Household Workers - 1' THEN [value]
				WHEN [metric] = 'Household Workers - 2' THEN [value]*2
				WHEN [metric] = 'Household Workers - 3+' THEN [value]*3
				ELSE 0
			END
		) AS [min_workers]
	FROM [outputs].[hh_characteristics]
	WHERE [run_id] = @run_id AND [metric] LIKE 'Household Workers%'
	GROUP BY [year], [mgra]
),
[Population Aged 18+] AS (
    SELECT
        [year],
        [mgra],
        SUM([value]) AS [persons_18plus]
    FROM [outputs].[ase]
    WHERE
        [run_id] = @run_id
        AND [age_group] NOT IN (
            'Under 5',
            '5 to 9',
            '10 to 14',
            '15 to 17'
        )
    GROUP BY [year], [mgra]
)
SELECT
	[Household Size].[year],
	[Household Size].[mgra],
	[Household Size].[min_workers],
	ISNULL([Population Aged 18+].[persons_18plus], 0) AS [persons_18plus]
FROM [Household Size]
LEFT OUTER JOIN [Population Aged 18+]
	ON [Household Size].[year] = [Population Aged 18+].[year]
	AND [Household Size].[mgra] = [Population Aged 18+].[mgra]
WHERE [min_workers] > ISNULL([Population Aged 18+].[persons_18plus], 0);

-- Check hard constraint of household size is not violated
WITH [Household Size] AS (
	SELECT
		[year],
		[mgra],
		SUM(CASE WHEN [metric] != 'Household Size - 1' THEN [value] ELSE 0 END) AS [2+ size],  -- 2+ household size
		SUM(CASE WHEN [metric] NOT IN ('Household Size - 1','Household Size - 2') THEN [value] ELSE 0 END) AS [3+ size]  -- 3+ household size
	FROM [outputs].[hh_characteristics]
	WHERE [run_id] = @run_id AND [metric] LIKE 'Household Size%'
	GROUP BY [year], [mgra]
),
[Household Workers] AS (
	SELECT
		[year],
		[mgra],
		SUM(CASE WHEN [metric] = 'Household Workers - 2' THEN [value] ELSE 0 END) AS [2 workers],
		SUM(CASE WHEN [metric] = 'Household Workers - 3+' THEN [value] ELSE 0 END) AS [3+ workers]
	FROM [outputs].[hh_characteristics]
	WHERE [run_id] = @run_id AND [metric] LIKE 'Household Workers%'
	GROUP BY [year], [mgra]
)
SELECT
	[Household Size].[year],
	[Household Size].[mgra],
	[Household Size].[2+ size],
	[Household Size].[3+ size],
	[Household Workers].[2 workers],
	[Household Workers].[3+ workers]
FROM [Household Size]
INNER JOIN [Household Workers]
	ON [Household Size].[year] = [Household Workers].[year]
	AND [Household Size].[mgra] = [Household Workers].[mgra]
WHERE
	[Household Size].[2+ size] < [Household Workers].[2 workers]
	OR [Household Size].[3+ size] < [Household Workers].[3+ workers]

What issues does this pull request address?

closes #247

Additional context

This is being done in service of SANDAG/Cohort-Component-Model#140.

As part of this review, once the first review of the methodology is approved, we can add a section to the Wiki either as a part of this PR or a subsequent.

[Copilot]

Pull request overview

Adds “households by number of workers (0,1,2,3+)” as a new output within the Household Characteristics module, sourcing tract-level distributions from ACS B08202 and applying MGRA-level controls/adjustments.

Changes:

• Adds ACS tract control SQL for households by worker count (with regional fallback for missing tract distributions).
• Adds MGRA control SQL inputs used by the worker characteristic (18+ population proxy and collapsed household size controls).
• Extends the Python household-characteristics pipeline to compute, validate, and insert “Household Workers - *” outputs, plus supporting constants/validation counts.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
sql/hh_characteristics/get_tract_controls_hh_by_workers.sql	New ACS B08202-based tract distribution controls for worker categories (0–3+).
sql/hh_characteristics/get_mgra_controls_hh_by_workers_hhs.sql	New SQL to fetch/collapse households-by-size outputs into (1,2,3+) controls for the workers step.
sql/hh_characteristics/get_mgra_controls_hh_by_workers_18plus.sql	New SQL to fetch MGRA 18+ population control totals (proxy constraint).
sql/hh_characteristics/get_mgra_controls_hh_by_size.sql	Comment/docstring tweak to reflect correct parameters.
python/utils.py	Adds HOUSEHOLD_WORKERS constant and fixes connection-string formatting.
python/tests.py	Updates expected distinct counts to include household_workers.
python/hh_characteristics.py	Adds the end-to-end “households by workers” computation, validation, and insertion to DB/debug outputs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Eric-Liu-SANDAG]

I think just add wiki stuff to this PR, did some basic sanity checks on the data, looks okay

[Eric-Liu-SANDAG]

Can you re-run with the new 18+ to test if the more restricted household population only still works?

[Eric-Liu-SANDAG]

Completed run in [run_id]=229, since Gregor is at ESRI conference

[Eric-Liu-SANDAG]

Can you also add your worker validation scripts to the file reporting\reporting.py?