Installation Guide

AirPulse Installation Guide

Prerequisites

Before you begin, make sure you have the following installed on your computer:

• Python 3.10 or higher (download from python.org if you do not have it)
• pip package manager (comes with Python by default)
• A code editor like VS Code, PyCharm, or Sublime Text
• A modern web browser (Chrome, Firefox, or Edge)
• Internet connection (required for the live dashboard mode; manual prediction works offline)

Step 1 - Extract the Project

After downloading, extract the ZIP file to any location on your computer. You should see a folder named "AQI Prediction" containing these files and folders:

AQI Prediction/
  app.py
  requirements.txt
  AQI_Prediction.ipynb
  aqi_model.pkl
  scaler.pkl
  feature_names.pkl
  eda_plots.png
  model_evaluation.png
  dataset/
    city_day.csv
    city_hour.csv
    station_day.csv
    station_hour.csv
    stations.csv
  templates/
    index.html
    predict.html
    about.html
  static/
    css/
      style.css
    js/
      app.js
      predict.js
  

Step 2 - Open Terminal in the Project Folder

Open your terminal (Command Prompt on Windows, Terminal on macOS/Linux) and navigate to the project folder:

cd path/to/AQI Prediction

On Windows, if the path has spaces, wrap it in quotes:

cd "C:\Users\YourName\Downloads\AQI Prediction"

Step 3 - Create a Virtual Environment

It is recommended to use a virtual environment so that the project dependencies do not interfere with other Python projects on your system.

python -m venv venv

Activate the virtual environment:

On macOS or Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

After activation, you should see (venv) at the beginning of your terminal prompt.

Step 4 - Install Dependencies

Install all required Python packages using the provided requirements.txt file:

pip install -r requirements.txt

This will install the following packages: Flask, XGBoost, scikit-learn, pandas, NumPy, joblib, and requests. The installation may take 2-5 minutes depending on your internet speed.

Step 5 - Verify Model Files

Check that these three files exist in the project root folder:

• aqi_model.pkl (approximately 2.1 MB) - the trained XGBoost model
• scaler.pkl (approximately 1.3 KB) - the fitted StandardScaler
• feature_names.pkl - the ordered list of 14 feature names

These files are already included in the download. If they are missing for any reason, you can regenerate them by running the Jupyter notebook:

pip install jupyter
jupyter notebook AQI_Prediction.ipynb

Once the notebook opens in your browser, go to Kernel and click "Restart and Run All". Wait for all 10 cells to finish executing. The .pkl files will be saved to the project root.

Step 6 - Start the Flask Server

Run the main application file:

python app.py

You should see output similar to this:

 * Running on http://127.0.0.1:5001
 * [startup] Model loaded. Features: ['PM2.5', 'PM10', ...]
  

The server is now running. Do not close this terminal window while using the application.

Step 7 - Open in Browser

Open your web browser and go to the following URLs:

Page	URL	Description
Live Dashboard	http://127.0.0.1:5001/	Real-time AQI monitoring with city selector and ML prediction
Manual Prediction	http://127.0.0.1:5001/predict	Enter custom pollutant values and get a next-day AQI forecast
About	http://127.0.0.1:5001/about	Full project documentation, dataset details, and model info

Step 8 - Test the Application

On the dashboard page, select a city from the dropdown (for example, Delhi or Mumbai). The page will fetch live pollutant readings from the WAQI API and display the current AQI in the animated gauge. Below the pollutant breakdown cards, you will see the ML-predicted AQI for tomorrow with health recommendations.

On the manual prediction page, adjust the pollutant sliders or type values directly into the number inputs. Click the "Predict AQI" button to see the result card animate into view with the forecasted AQI value, category, and health advice.

Optional - Change the Default City

Open app.py in your code editor. Near the top of the file, find this line:

DEFAULT_CITY = "Bangalore"

Change "Bangalore" to any supported city name (for example, "Delhi" or "Mumbai"). Save the file and restart the server.

Optional - Use Your Own WAQI API Token

The project comes with a pre-configured API token. If you want to use your own, sign up at aqicn.org/data-platform/token/ and replace the token in app.py:

WAQI_TOKEN = "your_token_here"

Troubleshooting

Port 5001 already in use: Another application is using port 5001. On macOS/Linux, run "lsof -i :5001" to find the process, then "kill -9 PID" to stop it. On Windows, use "netstat -ano | findstr :5001" and then "taskkill /PID PID_NUMBER /F".

ModuleNotFoundError: Make sure your virtual environment is activated (you should see (venv) in your terminal). Then run "pip install -r requirements.txt" again.

WAQI API not responding: Check your internet connection. If the API is temporarily down, the manual prediction page will still work since it does not depend on the external API.

Sliders not syncing with number inputs: Do a hard browser refresh with Ctrl+Shift+R (Windows) or Cmd+Shift+R (macOS) to clear the JavaScript cache.