AutoValuator 🏎️

An end-to-end machine learning web application that predicts auction sale prices for enthusiast cars listed on Cars & Bids, built on a dataset of 3,000 real auction records.

Live app: autovaluator.streamlit.app

---

Overview

AutoValuator covers the full data science pipeline from cleaning messy scraped data, to training an XGBoost regression model, to deploying it as an interactive Streamlit dashboard.

Model performance:

Metric	Value
R²	0.752
MAE	$7,656
RMSE	$16,315

---

Features

• 🔮 Price Estimator — Input a car's specs and get a predicted auction price with a ±15% confidence band, plus a table of real comparable sold cars
• 📊 Market Dashboard — Live-filtered charts showing price distributions, median price by make, mileage vs price, and body style volume
• 🔍 Deal Scorer — Enter a listing's asking price and get a green/yellow/red verdict on whether it's a good deal vs predicted market value, with a gauge chart
• 🗂️ Data Explorer — Browse, filter, and download the full cleaned auction dataset

---

Project Structure

AutoValuator/
├── data/
│   ├── cars_bids_final_3000.csv   # raw scraped dataset
│   └── cars_bids_clean.csv        # cleaned dataset (generated by notebook)
├── models/
│   ├── model.pkl                  # trained XGBoost model
│   └── encoder.pkl                # fitted OrdinalEncoder
├── images/                        # EDA and evaluation plots
├── AutoValuator.ipynb             # data cleaning, EDA, model training
├── app.py                         # Streamlit web application
├── feature_meta.json              # feature metadata and model metrics
├── requirements.txt
└── README.md

---

Quickstart

1. Clone the repo

git clone https://github.com/keyyril/AutoValuator.git
cd AutoValuator

2. Create and activate a virtual environment

python -m venv .venv

# Windows
.venv\Scripts\activate

# Mac/Linux
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Run the Jupyter notebook

Open AutoValuator.ipynb and run all cells top to bottom. This generates:

• models/model.pkl
• models/encoder.pkl
• feature_meta.json
• data/cars_bids_clean.csv

5. Launch the Streamlit app

streamlit run app.py

Open your browser at http://localhost:8501

---

Notebook Pipeline

Step	Description
1. Imports	Load all libraries
2. Load & Inspect	Read raw CSV, check shape and nulls
3. Data Cleaning	Parse sale price from auction_ended, extract year, clean mileage, normalise categoricals
4. Feature Engineering	Create car_age, is_manual, is_rwd, is_high_mileage, bids_clean
5. EDA	Price distribution, median by make, mileage scatter, correlation heatmap
6. Model Building	OrdinalEncoder + log-transform target + XGBoost (500 trees)
7. Evaluation	MAE, RMSE, R², predicted vs actual plot, residuals, feature importance
8. Save Artifacts	Export model, encoder, metadata, and cleaned CSV

---

Model Details

• Algorithm: XGBoost Regressor
• Target: log1p(sale_price) — log-transformed to handle right-skewed price distribution, reversed with expm1 at prediction time
• Features: make, model, body_style, transmission_clean, drivetrain_clean, seller_type_clean, year, mileage_clean, bids_clean, is_manual, is_rwd, is_private_seller, is_high_mileage
• Encoding: OrdinalEncoder for categoricals (compatible with XGBoost's native handling)
• Split: 80/20 train/test on 1,874 sold auction records

Key hyperparameters:

XGBRegressor(
    n_estimators=500,
    learning_rate=0.05,
    max_depth=6,
    subsample=0.8,
    colsample_bytree=0.8,
)

---

Dataset

• Source: Scraped from Cars & Bids
• Size: 3,000 auction records
• Sold auctions used for training: ~1,874
• Key columns: make, model, year, mileage, transmission, drivetrain, body_style, seller_type, bids, comments, auction_ended, location

---

Tech Stack

Tool	Purpose
Python 3.9	Core language
pandas	Data manipulation
XGBoost	ML model
scikit-learn	Encoding and evaluation metrics
Streamlit 1.28.0	Web application framework
Plotly 5.15.0	Interactive charts
Matplotlib / Seaborn	EDA plots in notebook

---

Known Limitations

• Model struggles with rare high-value exotics (Ferrari, Lamborghini) due to limited training samples — RMSE is 2× MAE as a result
• Predictions assume the car is in average condition — no condition grade input
• Confidence band is a fixed ±15% approximation, not statistically derived from model variance
• Dataset is static — model does not retrain on new auction data automatically