Economic
Economic data utilities: BLS QCEW downloads and economic indicators.
Economic data utilities.
Currently: - bls.qcew: BLS Quarterly Census of Employment and Wages downloader/parser. - irs.soi: IRS Statistics of Income by ZIP code.
Future: - bls.api: keyed-API client for incremental loads. - bea: BEA Regional Economic Accounts.
Submodules
BLS (Bureau of Labor Statistics) data utilities.
- class siege_utilities.economic.bls.QCEWFiles[source]
Bases:
objectThin wrapper around BLS QCEW open-data files.
Network-only on the first download for a (year) tuple; cached on disk thereafter. parse() filters by (state_fips, quarter, naics_depth) without re-hitting the network.
Example
files = QCEWFiles() df = files.load(year=2024, quarter=3, state_fips=”06”, naics_depth=2)
- parse(csv_path, *, year, quarter, state_fips=None, naics_depth=2)[source]
Parse a downloaded QCEW CSV into a normalized DataFrame.
- Filters:
quarter: the BLS qtr column matches; 1-4.
state_fips: if given, area_fips startswith state_fips.
naics_depth: keep only rows where industry_code length matches (NAICS 2-digit = sector level by default).
Returns columns: area_fips, own_code, industry_code, agglvl_code, qtrly_estabs, month1/2/3_emplvl, total_qtrly_wages, avg_wkly_wage, year, qtr.
BLS Quarterly Census of Employment and Wages — open data downloader + parser.
BLS publishes QCEW open data files (no API key needed) at data.bls.gov. Each quarter ships as a CSV inside a zip. This module downloads, unzips, caches, and parses into a DataFrame normalized to the shape downstream warehouses (e.g., socialwarehouse) consume.
Lift origin: this module was first written in socialwarehouse and graduated to siege_utilities per the SU-first rule (SU#533). Downstream consumers should from siege_utilities.economic.bls import QCEWFiles.
Phase 1 scope: files-only path (no BLS API key required). Phase 2 will add an APIClient that uses the keyed BLS API for incremental loads.
- class siege_utilities.economic.bls.qcew.QCEWFiles[source]
Bases:
objectThin wrapper around BLS QCEW open-data files.
Network-only on the first download for a (year) tuple; cached on disk thereafter. parse() filters by (state_fips, quarter, naics_depth) without re-hitting the network.
Example
files = QCEWFiles() df = files.load(year=2024, quarter=3, state_fips=”06”, naics_depth=2)
- parse(csv_path, *, year, quarter, state_fips=None, naics_depth=2)[source]
Parse a downloaded QCEW CSV into a normalized DataFrame.
- Filters:
quarter: the BLS qtr column matches; 1-4.
state_fips: if given, area_fips startswith state_fips.
naics_depth: keep only rows where industry_code length matches (NAICS 2-digit = sector level by default).
Returns columns: area_fips, own_code, industry_code, agglvl_code, qtrly_estabs, month1/2/3_emplvl, total_qtrly_wages, avg_wkly_wage, year, qtr.