API Reference

Leximin calibration of survey weights.

calibrate() takes a data frame and targets for each variable and returns weights whose misses are shared out as evenly as possible across the margins: the largest relative miss is as small as the weight bounds allow, then the next largest, and so on. Among weights with those misses, it moves each respondent as little and as evenly as possible. calibrate_replicates() does the same for replicate weights, for standard errors.

fairlex.calibrate(data, targets, *, base_weight=None, total=None, shares=False, importance=None, bounds=(0.1, 10.0), slack=0.0)[source]

Calibrate survey weights to categorical targets from a data frame.

Misses are compared relative to each target, and both the misses and the weight changes are made leximin-optimal (see fairlex.calibration.leximin_weights()).

Parameters:

  • data (DataFrame) – One row per respondent.

  • targets (Mapping[str, Mapping[object, float]]) – {variable: {level: target}}. Every level present in the data must have a target. With shares=False the values are population totals, and different variables may disagree about the overall size: that disagreement is what gets shared out. With shares=True each variable’s values are proportions that sum to 1, multiplied by total. Targets must be non-negative.

  • base_weight (str | None) – Column holding the base (design) weights. If omitted, every respondent starts at total / n.

  • total (float | None) – Population size. Added as its own margin when given. Required with shares=True, and when base_weight is omitted and the variables’ targets imply different population sizes.

  • shares (bool) – Treat each variable’s targets as proportions. Use it when your sources agree on proportions but not on the population size; the disagreement about size then disappears before calibration.

  • importance (Mapping[str, float] | None) – {variable: factor}. A factor of 2 makes misses on that variable’s margins count twice as much. Defaults to 1.

  • bounds (tuple[float, float]) – (lower, upper) bounds on each weight relative to its base weight, as in R survey, icarus and svy.

  • slack (float) – Extra relative miss every margin may take on top of its leximin level, in exchange for smaller weight changes.

Returns:

A CalibrationReport; print it for a summary.

Raises:

ValueError – If the targets and data do not match (see above), if total is needed but missing, or if importance names an unknown variable or a non-positive factor.

Return type:

CalibrationReport

fairlex.calibrate_replicates(data, targets, replicate_weights, **options)[source]

Calibrate every set of replicate base weights to the same targets.

This is how calibrated weights get standard errors: generate replicate base weights with your survey package (bootstrap, jackknife, BRR, e.g. svy’s create_bs_wgts or R survey::as.svrepdesign), calibrate each replicate exactly as the full sample was, and let the survey package combine the replicate estimates. Replicate weights of zero, as in a bootstrap draw that leaves a respondent out, stay zero.

Parameters:
Returns:

Calibrated replicate weights, one column per replicate, indexed like data.

Raises:

ValueError – If options includes base_weight, which the replicate columns replace.

Return type:

DataFrame

class fairlex.CalibrationReport(weights, margins, binding, epsilon, t, ess, deff, status, message)[source]

What calibrate() returns.

Variables:

  • weights (pandas.Series) – Calibrated weights, indexed like the input data frame.

  • margins (pandas.DataFrame) – One row per margin: variable, level, target, before and after (weighted totals), miss and miss_pct (miss as a percentage of the target).

  • binding (list[tuple[str, object, str]]) – The margins at the worst scaled miss, when that miss is above zero, as (variable, level, reason). reason is "weight bounds" when every member already sits at the bound that would help, so the target is out of reach on its own, and "conflicting targets" otherwise: meeting it better would push another margin further off.

  • epsilon (float) – Largest scaled miss: the largest relative miss times its variable’s importance.

  • t (float | None) – Largest relative weight change.

  • ess (float) – Kish effective sample size of the calibrated weights.

  • deff (float) – Kish design effect of the calibrated weights.

  • status (int) – Solver status (0 is success).

  • message (str) – Solver message.

Parameters: