BreatheEasy: Live AQI Analysis & Forecasting Dashboard

A multi-page, real-time Air Quality Index monitoring dashboard with a self-correcting forecast model and a live performance hub, built with Python and Dash.

---

Overview

BreatheEasy is a full-stack air quality analysis and forecasting dashboard. It provides a clean, intuitive web interface for major Indian cities to:

• Analyze historical Air Quality Index (AQI) trends.
• Display real-time AQI and weather information.
• Generate an intelligent, 3-day AQI forecast that self-corrects based on live data.
• Translate complex air quality data into clear, understandable health risks based on the official CPCB (Central Pollution Control Board) standard.
• Monitor the application's own system health via a live performance hub.

This repository contains the complete source code for the project, including a Dash-based multi-page frontend and a robust Python backend for data processing, API integration, and machine learning.

Dashboard Preview

The application features a fully responsive, dual-theme interface that adapts to your system preferences.

Light Theme	Dark Theme

Core Features

• Interactive Main Dashboard: A user-friendly interface to view current AQI, pollutant risks, historical trends, and educational information. Features a seamless dual-theme (light/dark) experience.
• Intelligent 3-Day Forecast: A sophisticated "Exponential Residual Decay" calibration model that uses raw LightGBM predictions and calibrates them against live, real-time AQI data. The initial forecast error (residual) is decayed exponentially over the 3-day window using a dynamic decay rate ($\gamma$) based on the magnitude of the live error, preserving the weather-driven forecast trend while correcting for absolute scale errors.
• Live Performance Hub: A real-time monitoring page (/performance) that displays live system metrics (CPU, Memory, Network I/O) via time-series graphs, tracks application process details, and provides a view of the live application logs.
• Persistent Background Data Collection: A background process collects system metrics continuously from the moment the app starts, ensuring a complete history is available whenever the performance hub is viewed.
• Dynamic UI Components: The dashboard features custom-built SVG gauges and responsive layouts that adapt to different screen sizes.

Our Contributors

A massive thank you to the talented team that brought BreatheEasy to life. Their dedication and collaboration were instrumental to this project's success.

Chirag P Patil

Kimaya Anand

Arnav Vaidya

How It Works

The application is architected with a clear separation between the backend data processes and the frontend presentation layers.

1. Model Training & Data Pipeline:

   • The src/modeling/train.py script trains a LightGBM model for each target city on the daily feature dataset. It incorporates optimized, city-specific tuned hyperparameters for Bangalore, Chennai, Kolkata, and Mumbai.
   • The trained models are saved as .pkl files in the /models directory, along with their out-of-sample validation scores and feature importances.
   • The automated data and model rebuilding pipeline is managed by scripts/rebuild_data_and_models.py.

2. Application Startup (Backend):

   • When python app.py is run, the main Dash application starts.
   • A hidden dcc.Interval in app.py immediately begins a background task, continuously collecting system metrics (CPU, RAM, Network) and storing them in a central shared_data.py file.

3. User Interaction (Frontend):

   • A user navigates to the main dashboard (/). Selecting a city triggers callbacks in pages/dashboard.py.
   • Forecasting: The predictor.py module is called. It loads the pre-trained LightGBM model, fetches a weather forecast, generates a raw AQI prediction, and then applies the "Exponential Residual Decay" calibration logic by comparing it to the live AQI anchor and decaying the initial residual over future days.
   • Real-time Data: The application fetches current AQI, pollutant levels, and weather from external APIs.
   • The UI is dynamically updated with the forecast, gauges, and health advisories.

4. Performance Monitoring:

   • A user navigates to the performance hub (/performance).
   • Callbacks in pages/performance.py read from the continuously updated data stores in shared_data.py to render the live graphs and scorecards, providing a real-time view of the application's health.

---

Technology Stack

Frontend

• Framework: Dash, Plotly
• UI Components: Dash Core Components, Dash HTML Components, Dash Bootstrap Components
• Custom Visualization: dash-svg for the dynamic AQI gauge.
• Styling: Custom CSS for a dual-theme (light/dark) responsive layout.

Backend & Data Science

• Language: Python 3.10+
• Machine Learning: LightGBM, Scikit-learn
• Data Manipulation: Pandas, NumPy
• System Monitoring: psutil
• API Interaction: requests

Development & Tooling

• Configuration: PyYAML for config.yaml, python-dotenv for API keys.
• Testing: pytest
• Environment: Jupyter Notebooks for initial data exploration.

Project Structure

The repository is organized into a modular structure that separates concerns, making it clean and maintainable.

├── app.py                      # Main Dash app entry point handles background tasks
├── shared_data.py              # Central data store for performance hub
├── requirements.txt            # Python package dependencies
├── config/
│   └── config.yaml             # Central configuration for the application
├── assets/                     # CSS, images, logos, and favicon
│   ├── performance_style.css   # Stylesheet for the performance hub
│   └── style.css               # Stylesheet for the main dashboard
├── data/                       # Datasets used for training and analysis
│   └── Post-Processing/
│       └── CSV_Files/
│           └── Master_Daily_Features.csv
├── models/                     # Trained LightGBM models and performance artifacts
│   ├── Bangalore_lgbm_daily_model.pkl
│   ├── Chennai_lgbm_daily_model.pkl
│   ├── Kolkata_lgbm_daily_model.pkl
│   ├── Mumbai_lgbm_daily_model.pkl
│   └── ... (and feature_importance/validation_score files)
├── pages/                      # Multi-page app layouts and callbacks
│   ├── dashboard.py
│   └── performance.py
├── src/                        # Core backend source code
│   ├── analysis/               # Historical data analysis functions
│   ├── api_integration/        # External API clients
│   ├── health_rules/           # AQI scales and interpretation logic
│   └── modeling/
│       ├── predictor.py        # Generates final, calibrated forecasts
│       └── train.py            # Trains the LightGBM models
├── notebook/                   # Jupyter notebooks for exploration and development
├── scripts/                    # Helper scripts for data processing tasks
└── tests/                      # Automated tests for the backend

Setup and Usage

Follow these steps to set up and run the BreatheEasy dashboard on your local machine.

1. Prerequisites

• Python 3.10 or newer.
• git installed on your system.

2. Clone the Repository

git clone https://github.com/cp099/BreatheEasy
cd BreatheEasy

3. Set Up a Virtual Environment

It is strongly recommended to use a virtual environment to manage project dependencies.

# On macOS/Linux
python3 -m venv venv
source venv/bin/activate

# On Windows
python -m venv venv
.\venv\Scripts\activate

4. Install Dependencies

Install all required Python packages from the requirements.txt file.

pip install -r requirements.txt

5. Configure API Keys

The application requires API keys from two services to fetch live, real-time data.

1. Create the .env file: In the root directory of the project, create a new file named .env.
2. Get API Keys:
   • WeatherAPI: Sign up for a free key at weatherapi.com
   • AQICN: Get a free token from the World Air Quality Index Project.
3. Add Keys to .env: Open the .env file and add your keys in the following format:

   WEATHERAPI_API_KEY="YOUR_ACTUAL_WEATHERAPI_KEY_HERE"
   AQICN_API_TOKEN="YOUR_ACTUAL_AQICN_TOKEN_HERE"
   

Security Note: The .gitignore file is already configured to prevent your .env file from being committed to Git.

6. Run the Application

With the setup complete, you can now run the Dash application directly.

python app.py

The application will start, and you can access the dashboard by navigating to the following URLs in your web browser:

• Main Dashboard: http://127.0.0.1:8050/
• Performance Hub: http://127.0.0.1:8050/performance

---

(Optional) Retraining the Models & Updating Data

The project features a unified data rebuilding and model retraining pipeline. If you wish to refresh the historical datasets with the latest weather and air quality observations and retrain the forecasting models:

1. Run the Unified Rebuild Script: Run the following helper script from the project's root directory. It automatically downloads clean hourly historical weather and air quality data from Open-Meteo from October 2022 to the present, computes daily CPCB AQI, constructs lagged features, and retrains all daily LightGBM models using their tuned city-specific hyperparameters:

   python scripts/rebuild_data_and_models.py

2. Verify Performance: Confirm that all new models are successfully generated in the /models directory and check the updated validation score files.

Contributing

Contributions to the BreatheEasy project are welcome! If you have suggestions for improvements or find any issues, please feel free to:

1. Open an Issue: Describe the bug or feature proposal in detail.
2. Fork the Repository: Create your own copy of the project on GitHub.
3. Create a Feature Branch: (git checkout -b feature/AmazingFeature)
4. Commit Your Changes: (git commit -m 'Add some AmazingFeature')
5. Push to the Branch: (git push origin feature/AmazingFeature)
6. Open a Pull Request: Create a PR back to the main repository with a clear description of your changes.

License

This project is distributed under the Apache License, Version 2.0. See the LICENSE and NOTICE files for more information.