---
license: mit
language:
- en
tags:
- tabular-regression
- scikit-learn
- random-forest
- house-prices
- california-housing
- real-estate
- regression
library_name: scikit-learn
metrics:
- rmse
- r2
datasets:
- california-housing
pipeline_tag: tabular-regression
---

# California House Price Prediction Model 🏠

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![scikit-learn](https://img.shields.io/badge/scikit--learn-1.3+-orange.svg)](https://scikit-learn.org/)

A machine learning model for predicting California house prices based on various features like location, age, size, and proximity to the ocean. This model uses a **Random Forest Regressor** trained on the California Housing dataset and achieves strong predictive performance.

## 📊 Model Overview

- **Model Type**: Random Forest Regressor (scikit-learn)
- **Task**: Regression (Predict median house value)
- **Training Data**: California Housing dataset (20,640 instances)
- **Performance**: Final RMSE on test set: ~$47,000-49,000
- **Features**: 8 numerical features + 1 categorical feature (ocean_proximity)
- **Target**: Median house value in California districts (in USD)

## 🎯 Use Cases

- Real estate price estimation
- Housing market analysis
- Property valuation for California regions
- Educational demonstrations of regression modeling

## 📥 Installation

### Clone the repository

```bash
git clone https://huggingface.co/nitish-niraj/house-price-prediction
cd house-price-prediction
```

### Install dependencies

```bash
pip install -r requirements.txt
```

## 🚀 Quick Start

### Using the Python API

```python
from inference import load_model

# Load the model
predictor = load_model()

# Prepare input data
house_data = {
    'longitude': -122.23,
    'latitude': 37.88,
    'housing_median_age': 41.0,
    'total_rooms': 880.0,
    'total_bedrooms': 129.0,
    'population': 322.0,
    'households': 126.0,
    'median_income': 8.3252,
    'ocean_proximity': 'NEAR BAY'
}

# Make prediction
predicted_price = predictor.predict(house_data)
print(f"Predicted house price: ${predicted_price[0]:,.2f}")
```

### Using the convenience function

```python
from inference import HousePricePredictor

predictor = HousePricePredictor()
predictor.load()

# Predict single house price
price = predictor.predict_single(
    longitude=-122.23,
    latitude=37.88,
    housing_median_age=41.0,
    total_rooms=880.0,
    total_bedrooms=129.0,
    population=322.0,
    households=126.0,
    median_income=8.3252,
    ocean_proximity='NEAR BAY'
)
print(f"Predicted price: ${price:,.2f}")
```

### Batch predictions

```python
import pandas as pd
from inference import load_model

predictor = load_model()

# Prepare multiple houses
houses_df = pd.DataFrame([
    {'longitude': -122.23, 'latitude': 37.88, 'housing_median_age': 41.0,
     'total_rooms': 880.0, 'total_bedrooms': 129.0, 'population': 322.0,
     'households': 126.0, 'median_income': 8.3252, 'ocean_proximity': 'NEAR BAY'},
    {'longitude': -122.22, 'latitude': 37.86, 'housing_median_age': 21.0,
     'total_rooms': 7099.0, 'total_bedrooms': 1106.0, 'population': 2401.0,
     'households': 1138.0, 'median_income': 8.3014, 'ocean_proximity': 'NEAR BAY'},
])

# Predict all at once
predictions = predictor.predict(houses_df)
for i, price in enumerate(predictions):
    print(f"House {i+1}: ${price:,.2f}")
```

## 📋 Input Features

The model requires the following features for prediction:

| Feature | Type | Description | Example |
|---------|------|-------------|---------|
| `longitude` | float | Longitude coordinate of the house | -122.23 |
| `latitude` | float | Latitude coordinate of the house | 37.88 |
| `housing_median_age` | float | Median age of houses in the district | 41.0 |
| `total_rooms` | float | Total number of rooms in the district | 880.0 |
| `total_bedrooms` | float | Total number of bedrooms in the district | 129.0 |
| `population` | float | Total population in the district | 322.0 |
| `households` | float | Total number of households in the district | 126.0 |
| `median_income` | float | Median income (in tens of thousands USD) | 8.3252 |
| `ocean_proximity` | string | Proximity to ocean | One of: `<1H OCEAN`, `INLAND`, `NEAR OCEAN`, `NEAR BAY`, `ISLAND` |

## 🎨 Gradio Demo

A Gradio web interface is included in the notebook for interactive predictions:

```python
# Run the Gradio demo (from the notebook)
import gradio as gr
# See housepriceprediction.ipynb for the full demo code
```

## 📈 Model Training Details

### Training Process

1. **Data Preprocessing**:
   - Handled missing values using median imputation
   - Created stratified train-test split (80-20) based on income categories
   - Feature engineering: Added derived features (rooms_per_household, etc.)
   - Standardized numerical features using StandardScaler
   - One-hot encoded categorical feature (ocean_proximity)

2. **Model Selection**:
   - Compared Linear Regression, Decision Tree, and Random Forest
   - Random Forest showed best performance

3. **Hyperparameter Tuning**:
   - Used GridSearchCV with 5-fold cross-validation
   - Optimized parameters: `n_estimators`, `max_features`, `bootstrap`
   - Best parameters: `{'max_features': 8, 'n_estimators': 30}`

4. **Evaluation**:
   - Primary metric: RMSE (Root Mean Squared Error)
   - Cross-validation RMSE: ~$49,000
   - Final test set RMSE: ~$47,000-49,000

### Feature Importance

Top features contributing to predictions (from the trained model):

1. Median Income
2. Longitude
3. Latitude
4. Housing Median Age
5. Ocean Proximity

## 📦 Model Files

- `house_price_model.joblib` (80+ MB) - Trained Random Forest model
- `preprocessing_pipeline.joblib` (2+ KB) - Data preprocessing pipeline
- `inference.py` - Python inference API
- `housepriceprediction.ipynb` - Training notebook with Gradio demo

## 🔧 Requirements

- Python 3.8+
- scikit-learn >= 1.3.0
- pandas >= 2.0.0
- numpy >= 1.24.0
- joblib >= 1.3.0
- gradio >= 4.0.0 (optional, for demo)

See `requirements.txt` for complete dependencies.

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Feel free to:

- Report bugs
- Suggest new features
- Submit pull requests

## 📚 References

- Dataset: [California Housing Dataset](https://www.kaggle.com/datasets/camnugent/california-housing-prices)
- Inspired by: *Hands-On Machine Learning with Scikit-Learn and TensorFlow* by Aurélien Géron

## 👤 Author

nitish-niraj

- GitHub: [@nitish-niraj](https://github.com/nitish-niraj)
- Hugging Face: [@nitish-niraj](https://huggingface.co/nitish-niraj)

## 🌟 Acknowledgments

- California Housing dataset from the 1990 U.S. Census
- scikit-learn community for excellent ML tools
- Hugging Face for model hosting platform

---

**Note**: This model is trained on 1990 census data and is intended for educational and demonstration purposes. For real-world applications, consider using more recent data and additional features.