logistic-regression
Fits a binary logistic regression with statsmodels, produces a LogisticRegressionReport validating against the pack schema, renders a standalone HTML report.
When to use
- Target has exactly two distinct values (0/1, yes/no, true/false, two category names)
- User asks for logistic regression, "model a binary outcome", "predict yes/no"
- pre-analysis identified the target as
binary
- User wants odds ratios or predicted probabilities, not just coefficient signs
Quick start
python .agents/skills/logistic-regression/scripts/fit.py \
--data path/to/data.csv \
--target churned \
--positive-class yes \
--features tenure,monthly_charges,contract_type \
--output results/
Outputs results/report.json (LogisticRegressionReport) and results/report.html.
Arguments
| Flag |
Default |
Description |
--data |
required |
CSV or Parquet path |
--target |
required |
Binary target column (exactly 2 unique values) |
--positive-class |
auto |
Which value to treat as 1 (default: 1 if 0/1 numeric, else alphabetically last) |
--features |
required |
Comma-separated columns, or all |
--output |
required |
Output directory |
--robust-se |
off |
HC0–HC3 robust standard errors |
--threshold |
0.5 |
Classification decision threshold |
--dataset-name |
"" |
Label shown in report header |
Outputs
out/
├── report.json # LogisticRegressionReport (Pydantic schema)
└── report.html # Self-contained HTML with Plotly charts
Report sections
- Fit summary — AUC, Brier score, McFadden pseudo-R², AIC/BIC, positive rate
- Marginal effects — AME forest plot + table (the primary interpretation surface)
- Coefficients — log-odds table + odds ratio forest plot (log scale)
- Classification performance — confusion matrix, accuracy, balanced accuracy, F1
- ROC curve — AUC annotated
- Calibration — reliability diagram with Brier score
- Interpretation — AME-based plain-English facts per feature
- Flags & recommendations
Interpreting the output
Lead with marginal effects (AME), not raw log-odds. AME tells you the average change in predicted probability per unit increase in each feature — the quantity humans find most interpretable.
- AUC 0.5 = random, 0.7 = OK, 0.8 = good, 0.9+ = strong
- Brier score 0.25 = baseline for balanced classes (lower is better)
CLASS_IMBALANCE flag: accuracy is misleading; prefer balanced accuracy and AUC
Chaining
After fit, run diagnostics for assumption checks adapted to logistic models (log-odds linearity, leverage analysis). Or run model-comparison alongside an OLS fit on the same binary target.
References
references/odds_ratio_interpretation.mdreferences/marginal_effects.mdreferences/class_imbalance.mdreferences/threshold_choice.md
1---2name: logistic-regression3description: logistic-regression4---5# logistic-regression67Fits a binary logistic regression with `statsmodels`, produces a `LogisticRegressionReport` validating against the pack schema, renders a standalone HTML report.89## When to use1011- Target has exactly two distinct values (0/1, yes/no, true/false, two category names)12- User asks for logistic regression, "model a binary outcome", "predict yes/no"13- pre-analysis identified the target as `binary`14- User wants odds ratios or predicted probabilities, not just coefficient signs1516## Quick start1718```bash19python .agents/skills/logistic-regression/scripts/fit.py \20 --data path/to/data.csv \21 --target churned \22 --positive-class yes \23 --features tenure,monthly_charges,contract_type \24 --output results/25```2627Outputs `results/report.json` (LogisticRegressionReport) and `results/report.html`.2829## Arguments3031| Flag | Default | Description |32|------|---------|-------------|33| `--data` | required | CSV or Parquet path |34| `--target` | required | Binary target column (exactly 2 unique values) |35| `--positive-class` | auto | Which value to treat as 1 (default: `1` if 0/1 numeric, else alphabetically last) |36| `--features` | required | Comma-separated columns, or `all` |37| `--output` | required | Output directory |38| `--robust-se` | off | `HC0`–`HC3` robust standard errors |39| `--threshold` | `0.5` | Classification decision threshold |40| `--dataset-name` | `""` | Label shown in report header |4142## Outputs4344```45out/46├── report.json # LogisticRegressionReport (Pydantic schema)47└── report.html # Self-contained HTML with Plotly charts48```4950### Report sections51521. **Fit summary** — AUC, Brier score, McFadden pseudo-R², AIC/BIC, positive rate532. **Marginal effects** — AME forest plot + table (the primary interpretation surface)543. **Coefficients** — log-odds table + odds ratio forest plot (log scale)554. **Classification performance** — confusion matrix, accuracy, balanced accuracy, F1565. **ROC curve** — AUC annotated576. **Calibration** — reliability diagram with Brier score587. **Interpretation** — AME-based plain-English facts per feature598. **Flags & recommendations**6061## Interpreting the output6263Lead with **marginal effects** (AME), not raw log-odds. AME tells you the average change in predicted probability per unit increase in each feature — the quantity humans find most interpretable.6465- AUC 0.5 = random, 0.7 = OK, 0.8 = good, 0.9+ = strong66- Brier score 0.25 = baseline for balanced classes (lower is better)67- `CLASS_IMBALANCE` flag: accuracy is misleading; prefer balanced accuracy and AUC6869## Chaining7071After fit, run `diagnostics` for assumption checks adapted to logistic models (log-odds linearity, leverage analysis). Or run `model-comparison` alongside an OLS fit on the same binary target.7273## References7475- `references/odds_ratio_interpretation.md`76- `references/marginal_effects.md`77- `references/class_imbalance.md`78- `references/threshold_choice.md`
WindcleaverDev