Hard-Minor GAN

Boundary-focused generative augmentation for imbalanced customer-churn prediction

Zihan Shen · Xingrui Zhao · Jingyou Yan

Outstanding Data Mining Course Project · Fall Semester, Academic Year 2025–2026

Overview · Method · Results · Quick Start · Reproducibility · Attribution

Overview

Customer-churn data are strongly imbalanced, but minority samples do not contribute equally to a classifier. Hard-Minor GAN targets the positive cases that a baseline classifier finds uncertain, learns their continuous distribution in a compact LASSO-PCA space, and uses the generated samples to refine downstream churn prediction.

Method overview. The first three panels are conceptual; the recall values in the final panel are reported course-project results.

The design addresses three practical issues in imbalanced tabular learning:

Challenge	Design choice	Intended effect
Minority heterogeneity	Select uncertain positive cases near the current decision boundary	Focus generation on the classification bottleneck
Noisy, correlated continuous variables	Apply LASSO selection followed by PCA	Give the GAN a smaller, decorrelated feature space
Mixed continuous and discrete fields	Generate continuous PCA features and reuse complete valid discrete rows	Avoid invalid categorical combinations

Method

1. Training-only representation learning

The dataset is split before fitting missing-value statistics, scaling, one-hot encoding, LASSO, or PCA. LASSO removes weak continuous variables, and PCA retains 95% cumulative explained variance by default.

2. Hard-Minor selection

A boundary classifier scores minority-class training samples. The default selected set is

$$ \mathcal{D}_{\mathrm{hard}} = {x_i \in \mathcal{D}_{\mathrm{minor}} \mid 0.2 < P(y=1 \mid x_i) < 0.6}. $$

The interval is configurable with --hard-low and --hard-high. A deterministic fallback prevents very small selected sets from breaking GAN training.

3. Targeted generation

An MLP generator learns the continuous PCA representation of the selected subset. Generated values are clipped to the Hard-Minor mean ±2.5 standard deviations in PCA space. Complete encoded discrete rows are sampled from selected observations and joined with the generated continuous features.

4. Downstream evaluation

The augmented training set is evaluated with XGBoost. Logistic regression, random forest, LightGBM, SMOTE, and ADASYN are available as comparison paths. The release records AUC, F1, precision, recall, training traces, and feature-importance outputs.

Results

The following three plots are the original figures from the course report. They summarize the private-data experiment and are presented as reported results; the public synthetic test suite does not reproduce these values.

Feature importance

Figure 1. Top 15 features associated with customer-churn prediction in the report experiment.

Adversarial training

Figure 2. Generator and discriminator training and validation loss across 1,400 epochs.

Model comparison

Figure 3. Reported AUC, F1, and recall across the evaluated classifiers and sampling strategies.

On the held-out split reported in the course paper, Hard-Minor GAN reached 0.781 AUC, 0.351 F1, and 0.464 recall. Its recall was higher than the reported XGBoost baseline (0.454) and XGBoost with SMOTE (0.408), while plain XGBoost retained the best AUC, F1, and precision. The result should therefore be read as a recall-oriented trade-off rather than a universal improvement across every metric.

Implementation Map

Component	Repository entry point
Preprocessing and LASSO-PCA transforms	load_and_preprocess_data, lasso_feature_selection, pca_feature_enhancement
Boundary subset construction	select_hard_minority
Generator, discriminator, and training loop	GAN
Mixed-type sample reconstruction	sample_discrete_features
End-to-end experiment and outputs	run_experiment

Quick Start

Install

git clone https://github.com/Ailta666508/Hard-Minor-GAN.git
cd Hard-Minor-GAN
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

Python 3.10–3.12 is supported. XGBoost and LightGBM require an OpenMP runtime; on macOS with Homebrew, install it with brew install libomp.

Prepare data

The project uses a private commercial-bank dataset with 33 continuous variables, eight encoded discrete variables, and the binary target churn. No customer record, trained model, or private-data derivative is included. Place an authorized UTF-8 CSV outside version control, for example at data/churn.csv; see data/README.md for the schema.

Run the report configuration

hard-minor-gan \
  --data data/churn.csv \
  --output-dir results \
  --gan-epochs 1400 \
  --target-ratio 0.23

For a short environment check:

hard-minor-gan \
  --data data/churn.csv \
  --output-dir results/smoke \
  --gan-epochs 5 \
  --n-estimators 10 \
  --baseline-models logistic xgb \
  --skip-oversampling \
  --no-gpu

The run writes model metrics, feature importance, GAN history, comparison plots, and a machine-readable summary to the selected output directory.

Reproducibility

python -m pytest -q
python scripts/verify_release.py

The synthetic suite checks training-only preprocessing, LASSO/PCA artifacts, boundary selection, generation-count arithmetic, valid discrete-row sampling, threshold evaluation, GAN training and generation, and a short end-to-end pipeline. The validated environment and scope are recorded in docs/VALIDATION.md.

The private banking dataset is required to reproduce the course-report figures and metrics. Without it, the repository validates implementation behavior rather than the reported empirical results.

Limitations

• Boundary membership depends on classifier calibration and the selected probability interval.
• GAN training remains sensitive to sample count and hyperparameters.
• Statistical clipping limits extreme PCA values but does not guarantee business validity.
• The reported experiment is based on one private banking dataset; broader external validation is still needed.
• Feature importance is associative, and PCA back-projection is approximate.

Project Attribution

The course report was written by Zihan Shen (沈子涵), Xingrui Zhao (赵星睿), and Jingyou Yan (严璟悠). All original project code was written solely by Zihan Shen, who also maintains this public repository. The report PDF is not redistributed because its title page contains student identifiers; the three research figures above are included without customer-level data.

No repository-wide open-source license is granted. Contact the project rights holders before reuse, particularly for work involving financial data. Further release details are documented in docs/CODE_SCOPE.md.

Note: This project was initially developed locally without a commit-by-commit version history. This repository publishes the curated release; subsequent updates are tracked here.