Kairovia Weather Prediction System

Real-time weather forecasting using ensemble machine learning models for prediction markets
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Model Architecture
5. Features
6. Roadmap
7. Contributing
8. License
9. Contact
10. Acknowledgments

About The Project

Kairovia is a sophisticated weather prediction system designed for real-time forecasting applications, particularly prediction markets. The system leverages an ensemble of machine learning models to predict daily high temperatures with high accuracy using historical weather data from NOAA stations.

Key Features

• Ensemble Learning: Combines LightGBM gradient boosting and heteroscedastic neural networks for robust predictions
• Advanced Feature Engineering: Extracts 200+ temporal and geospatial features including FFTs, lag variables, and rolling statistics
• Uncertainty Quantification: Neural network model provides both point predictions and uncertainty estimates
• Real-time Data Pipeline: Automated data fetching from NOAA weather stations via Meteostat API
• Production-Ready: Trained models and scalers are saved for deployment in inference pipelines

The system processes hourly weather observations (temperature, dewpoint, pressure, wind direction, wind speed, precipitation) and predicts the maximum daily temperature, making it suitable for applications requiring accurate short-term weather forecasts.

(back to top)

Built With

• 
• 
• 
• 
• 
• 
• 

(back to top)

Getting Started

This section will guide you through setting up the project locally.

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Installation

1. Clone the repository

   git clone https://github.com/github_username/kairovia.git
   cd kairovia

2. Install required packages

   pip install numpy pandas scikit-learn lightgbm tensorflow matplotlib joblib meteostat python-dateutil

3. Download weather data

   python download.py

   This will fetch historical weather data from the Austin Bergstrom International Airport (KAUS) station and save it to data.csv.

4. (Optional) Find alternative weather stations

   python find_stations.py

   Use this script to discover weather stations near specific coordinates if you want to use data from a different location.

(back to top)

Usage

Training the Model

To train the ensemble model on your weather data:

python model.py

This script will:

1. Load and preprocess the weather data from data.csv
2. Engineer temporal and geospatial features
3. Train a LightGBM model with quantile regression
4. Train a heteroscedastic neural network
5. Create an ensemble prediction combining both models
6. Evaluate performance and generate visualization plots
7. Save trained models (hetero_nn.keras, lgb_model.txt) and scalers (scaler_X.joblib, scaler_y.joblib)

Model Configuration

Key parameters can be adjusted in model.py:

• INPUT_HOURS: Number of hours of historical data to use (default: 12)
• SPLIT_DATE: Date to split train/test sets (default: None, uses 80/20 split)
• LGB_PARAMS: LightGBM hyperparameters
• EPOCHS: Number of training epochs for neural network
• BATCH_SIZE: Training batch size

Output

The script generates:

• Performance metrics (MAE, MSE) for each model component
• Error distribution plots and analysis
• Saved model files for inference deployment

(back to top)

Model Architecture

The system uses a two-model ensemble approach:

1. LightGBM Gradient Boosting

• Point prediction model for baseline forecasts
• Quantile regression models (10th, 50th, 90th percentiles) for uncertainty bounds
• Handles non-linear relationships and feature interactions efficiently

2. Heteroscedastic Neural Network

• Deep learning model that predicts both mean (μ) and variance (σ²)
• Architecture: 256 → 128 dense layers with batch normalization and dropout
• Uses negative log-likelihood loss for heteroscedastic regression
• Provides uncertainty estimates alongside point predictions

Ensemble Strategy

• Final prediction: 50% LightGBM + 50% Neural Network mean prediction
• Quantile predictions combine LightGBM quantiles with neural network uncertainty

(back to top)

Features

Feature Engineering

The system extracts comprehensive features from raw weather observations:

Temporal Features:

• Cyclical encoding of hour and day-of-year (sine/cosine transformations)
• Rolling statistics (24-hour rolling means)
• Lag variables from previous days
• Linear trend detection in temperature sequences

Derived Meteorological Features:

• Relative humidity calculated from temperature and dewpoint
• Pressure normalization and interpolation
• Wind vector components

Statistical Features:

• Previous day statistics (max, min, mean temperature)
• Rolling window aggregations
• Temporal patterns and trends

All features are standardized using scikit-learn's StandardScaler before model training.

(back to top)

Roadmap

• Add support for multi-location predictions
• Extend to multi-day ahead forecasts
• Implement automated retraining pipeline
• Add model monitoring and drift detection

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

PraneethO - potthi [at] berkeley [dot] edu

Project Link: https://github.com/PraneethO/kairovia

(back to top)

Acknowledgments

• Meteostat - Weather data API and historical climate data
• NOAA - National Oceanic and Atmospheric Administration for weather station data
• LightGBM - Gradient boosting framework
• TensorFlow - Deep learning framework

(back to top)