Add income, tenure, fix occupants

[lixiliu]

Pull Request Description

• Update PUMS tsvs from 2017 5-yrs to 2019 5-yrs,
• Add new tvs: Income, Income RECS2015, Federal Poverty Level, Tenure, and PUMA Metro Status (a few of them are explained in detail below.)
• In ACS, Income, Tenure, Occupants, and Heating Fuel are reported for Occupied units only. Instead of making these tsvs with Option=None for Vacant Units, we have decided to attribute these distributions to all units regardless of Vacancy Status. This will help facilitate future work, such as modeling seasonally vacant units when occupants, income, and tenure tags do play a part. It's important to keep this caveat in mind when:

1. comparing these tsv distributions with other data sources,
2. segmenting the buildstock.csv or ResStock results,
3. using the distributions to conduct analyses such as the population-based building projection for C2C.

• Update dependencies and fix encoding error in Occupants.tsv
• Included sampling_prob calc fix from https://github.com/NREL/resstock-estimation/pull/203

PUMS tsv dependency tree (includes all ResStock geography resolutions, color represents hierarchy level)

Companion ResStock-Estimation PR: https://github.com/NREL/resstock-estimation/pull/186

• PUMA Metro Status: derived from ACS IPUMS METRO codes, this tsv indicates "whether the household resided within a metropolitan area and, for households in metropolitan areas, whether the household resided within or outside of a central/principal city." (ACS IPUMS codebook). Each PUMA has a unique METRO status in ACS and therefore has a unique PUMA Metro Status. IPUMS derives METRO codes for samples not directly identified based on available geographic information and whether the associated county group or PUMA lies wholly or only partially within metropolitan areas or principal cities. PUMA Metro Status has the following options:

In metro area, principal city : A PUMA is within the largest city in a Metro or Micropolitan Area (N=304)
In metro area, not/partially in principal city : A PUMA is within a Metro or Micropolitan Area but not within or is only partially within the Area's largest city (N=1560)
Not/partially in metro area : A PUMA is not within or is only partially within a Metro or Micropolitan Area (N=472)

• Federal Poverty Level: A normalization of income based on the Federal Poverty Line (annually determined, location, and household size-specific). This tsv is calculated using annual household income in 2019USD (continuous, not binned) from the 2019-5yrs PUMS data and 2019 Federal Poverty Lines for contiguous US, where the FPL threshold for 1-occupant household is $12490 and $4420 for every additional person in the household.
• Tenure: Tenure terms are typically Renter-Occupied, Owner-Occupied, and None for Vacant units. However, since the distribution applies regardless of Vacancy Status, Tenure has the options: [Owner and Renter].

Checklist

Not all may apply:

• Tests (and test files) have been updated
• Documentation has been updated
• Changelog has been updated
• openstudio tasks.rb update_measures has been run
• No unexpected regression test changes on CI (checked comparison artifacts)

[vtnate]

I am not at all qualified to comment on the technicalities of this change, but I was able to use this occupants.tsv file to calculate USA national population with only a 1.2% error from census data. This seems like a great improvement over the former occupants.tsv.

[joseph-robertson]

So... what ultimately was the fix here for when Occupants=0? I thought we were going to be testing this fix: NREL/OpenStudio-HPXML#1057.

@afontani @lixiliu

[lixiliu]

So... what ultimately was the fix here for when Occupants=0? I thought we were going to be testing this fix: NREL/OpenStudio-HPXML#1057.

@afontani @lixiliu

@joseph-robertson - we ended up removing Occupants=None as an option from the tsv and options_lookup here. We still need Occupants=0 as a valid measure for internal transparency, particularly if the number of Occupants affects internal gain regardless of the occupant schedule. When the Occupants=0 fix is ready, we are thinking of adding that to Vacancy Status=Vacant in options_lookup to enforce Occupants=0 there. That way, we ensure there is no internal gain and Vacant units corresponds to Occupants=0 in the OS/HPXML models, which, to my knowledge, a lot of people use/reference when we publish them.