facebookresearch/balance 0.16.0

0.16.0 (2026-02-09)

on GitHub

New Features

• Outcome weight impact diagnostics
  • Added paired outcome-weight impact tests (y*w0 vs y*w1) with confidence intervals.
  • Exposed in BalanceDFOutcomes, Sample.diagnostics(), and the CLI via
    --weights_impact_on_outcome_method.
• Pandas 3 support
  • Updated compatibility and tests for pandas 3.x
• Categorical distribution metrics without one-hot encoding
  • KLD/EMD/CVMD/KS on BalanceDF.covars() now operate on raw categorical variables
    (with NA indicators) instead of one-hot encoded columns.
• Misc
  • Raw-covariate adjustment for custom models
    • Sample.adjust() now supports fitting models on raw covariates (without a model matrix)
      for IPW via use_model_matrix=False. String, object, and boolean columns are converted
      to pandas Categorical dtype, allowing sklearn estimators with native categorical
      support (e.g., HistGradientBoostingClassifier with categorical_features="from_dtype")
      to handle them correctly. Requires scikit-learn >= 1.4 when categorical columns are
      present.
  • Validate weights include positive values
    • Added a guard in weight diagnostics to error when all weights are zero.
  • Support configurable ID column candidates
    • Sample.from_frame() and guess_id_column() now accept candidate ID column names
      when auto-detecting the ID column.
  • Formula support for BalanceDF model matrices
    • BalanceDF.model_matrix() now accepts a formula argument to build
      custom model matrices without precomputing them manually.

Bug Fixes

• Removed deprecated setup build
  • Replaced deprecated setup.py with pyproject.toml build in CI to avoid build failure.
• Hardened ID column candidate validation
  • guess_id_column() now ignores duplicate candidate names and validates that candidates are non-empty strings.
• Hardened pandas 3 compatibility paths
  • Updated string/NA handling and discrete checks for pandas 3 dtypes, and refreshed tests to accept string-backed dtypes.

Packaging & Tests

• Pandas 3.x compatibility
  • Expanded the pandas dependency range to allow pandas 3.x releases.
• Direct util imports in tests
  • Refactored util test modules to import helpers directly from their modules instead of via balance_util.

Breaking Changes

• Require positive weights for weight diagnostics that normalize or aggregate
  • design_effect, nonparametric_skew, prop_above_and_below, and
    weighted_median_breakdown_point now raise a ValueError when all weights
    are zero.
  • Migration: ensure your weights include at least one positive value
    before calling these diagnostics, or catch the ValueError if all-zero
    weights are possible in your workflow.

Contributors

@neuralsorcerer, @talgalili (with code/methodological review by @talsarig)

Full Changelog: 0.15.0...0.16.0