Weighting

Overview

Weighting has two mutually exclusive options:

flowchart TD
  A["Weighting"] --> B["Compute Weights\nDerive new weights from controls"]
  A --> C["Existing Weights\nAttach pre-computed weights"]

• Compute Weights computes new weights from PUMS controls and survey seed data.
• Existing Weights attaches weights that were already computed elsewhere.

Only the compute weights option needs the full weighting pipeline machinery such as PUMS fetching, crosswalk construction, incidence preparation, control aggregation, balancing, diagnostics, and control validation. The existing weights option is much lighter: it joins external weight files onto canonical tables and can optionally derive missing downstream weights through the survey hierarchy.

Choose an Option

Option	Use when	Key inputs	Main output
Compute Weights	You need to create expansion weights from controls	PUMS, geography, control definitions, survey tables	New household weights propagated to all tables
Existing Weights	You already have weight files from another system or prior run	Weight CSVs keyed to canonical IDs	Existing weights attached and optionally propagated

processing.weighting

Survey weighting module.

This module provides two pipeline options for attaching expansion weights to survey tables:

1. add_existing_weights -- load pre-computed weights from CSV files and join them to tables, optionally deriving missing weights by propagating values through the survey hierarchy.
2. compute_weights -- compute weights from scratch using PUMS / ACS microdata as population controls via maximum-entropy balancing.

The compute_weights step orchestrates the full pipeline — see compute_weights.py for the detailed step-by-step description.

Weight hierarchy

Every weight is written once per profile, suffixed with its name (hh_weight_<profile>, person_weight_<profile>, ...):

hh_weight
  └─ person_weight        (household's weight, shared among its usable persons)
      └─ day_weight        (split: a person's usable days sum to their weight)
          └─ unlinked_trip_weight  (day's weight, shared within the day)
              ├─ linked_trip_weight   (mean agg via linked_trip_id)
              │   └─ joint_trip_weight (SUM agg via joint_trip_id)
              └─ tour_weight          (mean agg via tour_id)
                  └─ joint_tour_weight (SUM agg via joint_tour_id)

Module structure

weighting/
├── existing_weights.py       # attach pre-computed weights
├── existing/                 # its settings and redistribution onto usable records
├── compute_weights.py        # single @step() entry point for full weighting pipeline
├── core/                     # WeightingPipeline, the hierarchy, propagation, settings
├── controls/                 # control variable definitions & registry
├── data_prep/                # PUMS I/O, control totals, survey seed, geography
├── balancing/                # balancer, base weights, importance, merges
├── diagnostics/              # interactive HTML report (Plotly + Jinja2)
└── validation/               # post-balancing sanity checks