Implement DFM Omnibus Test for Treatment Effect Heterogeneity

[Copilot]

This PR implements the Ding, Feller, Miratrix (2018) omnibus test for systematic treatment effect heterogeneity as a post-estimation method for the Feols class.

Overview

The DFM test evaluates whether treatment effects vary systematically across observable characteristics by testing the joint significance of treatment-covariate interactions. This is a widely used diagnostic in econometrics for detecting effect heterogeneity.

Key Features

New dfm_test() Method

• Automatic treatment detection: Recognizes common treatment variable patterns (treatment, treat, policy, intervention, etc.)
• Flexible specification: Allows manual specification of treatment and interaction variables
• Multiple treatments: Supports testing heterogeneity across multiple treatment variables
• Distribution options: Supports both chi-squared and F test distributions

Usage Example

import pyfixest as pf
import numpy as np
import pandas as pd

# Generate data with heterogeneous treatment effects
np.random.seed(42)
n = 1000
age = np.random.uniform(20, 60, n)
treatment = np.random.binomial(1, 0.5, n)
# Treatment effect varies with age
outcome = 20000 + 500 * age + treatment * (1000 + 50 * (age - 40)) + np.random.normal(0, 5000, n)

data = pd.DataFrame({'outcome': outcome, 'treatment': treatment, 'age': age})

# Fit base model
fit = pf.feols('outcome ~ treatment + age', data=data)

# Test for heterogeneity (auto-detects treatment variable)
result = fit.dfm_test()
print(f"Test statistic: {result['statistic']:.3f}")
print(f"P-value: {result['pvalue']:.6f}")

# Manual specification
result = fit.dfm_test(treatment_vars='treatment', interaction_vars=['age'])

Implementation Details

• Mathematical correctness: Results verified against manual interaction term testing
• Integration: Uses existing wald_test infrastructure for reliability
• Error handling: Graceful handling of multicollinearity with fixed effects
• Robustness: Comprehensive test suite covering edge cases and validation scenarios

Documentation

• Added examples to the quickstart guide
• Comprehensive docstring with methodology explanation and references
• Clear usage examples demonstrating both automatic and manual specification

Testing

The implementation includes extensive tests covering:

• Basic functionality and parameter validation
• Treatment variable auto-detection
• Multiple treatment scenarios
• Error handling for invalid inputs
• Fixed effects compatibility
• Mathematical verification against manual computation

This implementation provides researchers with a practical tool to test for systematic treatment effect heterogeneity following established econometric methodology.

Fixes #989.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

@apoorvalal 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.