Kaggle F1 Pit Stops Prediction - Solution Pipeline

This repository contains a complete, production-quality, end-to-end Machine Learning pipeline for the Kaggle Playground Series (Season 6 Episode 5) competition: Predicting F1 Pit Stops.

The objective is to predict the probability that a driver will make a pit stop on the next lap (PitNextLap) using the ROC-AUC evaluation metric.

---

Project Structure

project/
│
├── data/                      # Contains raw CSV data files (train, test, sample_submission)
├── notebooks/
│   ├── eda.py                 # Exploratory Data Analysis script
│   ├── adversarial_validation.py # Adversarial validation check
│   └── kaggle_pipeline.py     # Self-contained pipeline for copy-pasting to Kaggle
│
├── src/
│   ├── __init__.py
│   ├── config.py              # Configuration of features, parameters, and paths
│   ├── utils.py               # Seeding, logging, and memory reduction utilities
│   ├── features.py            # Feature engineering pipeline
│   ├── models.py              # Wrapper classes for LightGBM, XGBoost, CatBoost
│   ├── train.py               # Cross-validation training loop and OOF generation
│   ├── inference.py           # Test inference pipeline
│   └── ensemble.py            # Blending and ensembling pipeline
│
├── outputs/                   # OOF predictions, trained fold models, importance summaries
├── submissions/               # Holds final submission.csv
│
├── requirements.txt           # Package dependencies
├── compile_notebook.py        # Pipeline compiler to generate kaggle_pipeline.py
└── README.md                  # This documentation file

---

Implementation Details

1. Feature Engineering (src/features.py)

Features are engineered at multiple levels:

• Raw Transformations: Sin/cos cyclical transformations for LapNumber and RaceProgress to capture cyclical patterns. Approximations of remaining laps.
• Group Sequences: Sorting the dataset by (Year, Race, Driver, LapNumber) allows us to generate continuous sequence features:
  • Lags of 1 and 2 laps for numerical features (e.g. TyreLife, Stint, Position, LapTime (s)).
  • First-order differences (e.g. change in position, change in tyre life).
  • Rolling statistics (mean & standard deviation) over 3 and 5 laps (properly shifted to prevent leakage).
  • Stint wear profiling (laps run on current stint).
• Group Aggregations: Packing dynamics per race and lap (e.g. pack pace, standard deviation of pack, count of other drivers pitting on the same lap to capture safety cars/accidents).
• Target Encoding: Performed fold-by-fold during cross-validation to completely prevent leakage.

2. Modeling & CV (src/models.py, src/train.py)

• We train three gradient boosted decision tree frameworks: LightGBM, XGBoost, and CatBoost.
• Cross-Validation: 5-Fold Stratified K-Fold.
• Seed Averaging: Every model is trained across 3 different seeds to stabilize and reduce predictions variance.
• Out-of-Fold Predictions: Saved for ensembling.

3. Ensembling (src/ensemble.py)

The pipeline runs and compares three ensembling methods:

• Rank Averaging: Averaging percentile ranks of predictions to prevent calibration scale mismatch.
• Optimized Weighted Blending: Using SLSQP optimization to find weights that maximize OOF ROC-AUC.
• Stacking: Training a Ridge Regression meta-model on the OOF predictions of the base models.

---

How to Run the Pipeline

Local Run

1. Install requirements:

   pip install -r requirements.txt

2. Run Exploratory Data Analysis:

   python notebooks/eda.py

3. Run Adversarial Validation:

   python notebooks/adversarial_validation.py

4. Train base models & generate OOFs:

   python src/train.py

5. Blend models & generate final submission:

   python src/ensemble.py

   The final submission will be saved in submissions/submission.csv.

---

Running on Kaggle (Unified Pipeline)

To run the entire pipeline on a free Kaggle Notebook CPU/GPU instance in a single run:

1. Generate the unified script:

   python compile_notebook.py

   This will read the modular files from src/ and output a single, self-contained file notebooks/kaggle_pipeline.py.

2. Copy and Run on Kaggle:

   • Copy the entire contents of notebooks/kaggle_pipeline.py.
   • Paste it into a Python script or a single cell of a Jupyter Notebook on Kaggle.
   • Upload the competition datasets (train.csv, test.csv, sample_submission.csv) to your Kaggle workspace directory.
   • Run the cell. It will perform cross-validation, train all fold models, run ensembling, and output submission.csv in your output directory.