Data Preparation

---
name: data-preparation
description: "Prepare causalml datasets, encodings, propensity scores, matching
  samples, and balance checks."
disable-model-invocation: true
metadata:
  disco-role: operating
license: NOASSERTION
---

# data-preparation

Use this operating sub-skill when the task is about preparing data for CausalML workflows before causal estimation, tree modeling, deep modeling, validation, or decision optimization.

## Route here for

- Generating CausalML synthetic datasets for binary treatment simulations or uplift-classification examples.
- Building feature matrices with the bundled rare-category label and one-hot encoders.
- Estimating binary propensity scores with elastic-net logistic regression or gradient-boosted propensity models.
- Performing nearest-neighbor propensity-score matching with optional calipers, replacement, ratios, and exact group strata.
- Running matched-sample balance checks with standardized mean differences.
- Producing matched CSV files with the bundled `scripts/match_csv.py` helper.

## Route elsewhere

- Meta-learners, TMLE, IV/DRIV, ATE/ITE/CATE estimation, or serialization: use `../causal-estimation/`.
- Causal trees, causal forests, uplift trees, or tree visualization: use `../tree-models/`.
- Neural DragonNet or CEVAE models: use `../deep-models/`.
- Uplift metrics, validation, sensitivity analysis, feature selection, or treatment optimization: use `../analysis-and-decision/`.

## Operating map

| User goal | Primary runtime artifact |
| --- | --- |
| Generate synthetic regression or uplift-classification data | `references/workflows.md#synthetic-data-workflows` |
| Convert mixed pandas columns into a numeric model matrix | `references/workflows.md#feature-matrix-and-encoding-workflows` |
| Estimate clipped binary propensity scores | `references/workflows.md#propensity-score-workflows` |
| Match treated and control units, including group-stratified matching | `references/workflows.md#nearest-neighbor-matching-workflows` |
| Check pre/post balance with standardized mean differences | `references/workflows.md#balance-table-workflow` |
| Prepare CSV data for matching from the shell | `scripts/match_csv.py` |
| Confirm accepted column shapes and labels | `references/data-contracts.md` |
| Diagnose common data-preparation failures | `references/troubleshooting.md` |

## Default safety checks

Before fitting or matching, confirm these items:

1. Treatment is binary `0/1` for propensity and matching APIs.
2. Treatment, outcome, observed propensity, true effects, and post-treatment variables are excluded from feature columns unless the user explicitly asks for an audit.
3. Matching score columns are numeric and do not contain missing values.
4. `NearestNeighborMatch(replace=False)` receives exactly one score column; use `replace=True` for multi-column nearest-neighbor matching.
5. Balance tables use numeric covariates; encode categorical variables or audit them separately.
6. Synthetic examples generated by `synthetic_data()` draw from NumPy global randomness, so set `np.random.seed(...)` before calling if reproducibility matters.

## Bundled helper

Run the CSV helper with:

```bash
python sub-skills/data-preparation/scripts/match_csv.py \
  --input input.csv \
  --output matched.csv \
  --treatment-column treatment \
  --feature-columns age tenure spend_segment \
  --matching-covariates age tenure \
  --score-column propensity \
  --caliper 0.2 \
  --ratio 1 \
  --random-state 42
```

The helper imports installed CausalML APIs, writes a matched CSV, and prints balance tables before and after matching when the requested balance covariates support them.