model-air-quality

name	model-air-quality
description	Use when a user has a CSV of air quality measurements and wants to visualize trends, patterns, or create a short-term forecast.

Model and Analyze Air Quality Data

Time-series analysis and visualization for pollutant concentrations. Generate wind-dependent polar plots, calendar heatmaps, time-of-day patterns, and optional forecasts.

When to use

• User has a CSV of historical pollutant data and wants to identify patterns (hour-of-day, day-of-week, seasonal)
• User has wind and pollution data and wants to understand directional dependence
• User wants to visualize daily/weekly/monthly pollution cycles
• User is exploring a dataset before deciding on further statistical analysis
• User needs a simple forecast (ARIMA or Prophet baseline)

Inputs to gather

• CSV file path: Must contain datetime column (ISO 8601, e.g., 2026-04-20T14:30:00Z) and one or more pollutant columns (e.g., PM2.5, O3, NO2, value)
• Optional meteorological columns: wind_speed, wind_dir (degrees, 0–360), temp, humidity
• Desired analysis: time-variation, polar-plot, calendar-plot, forecast — or list what the user wants to explore (e.g., "show me hour-of-day patterns and any weekly cycle")
• Output path: Directory or file prefix for PNG plots and CSV summaries (defaults to current working directory)

Procedure

1. Load CSV; validate that datetime column exists and is parseable; stop with helpful error if not.

2. Parse datetime to UTC; warn if any rows are missing or non-numeric pollutant values (offer to drop or interpolate).

3. Based on user's requested analysis, execute one or more of:

   Time Variation:

   • Compute mean pollutant concentration by hour-of-day, day-of-week, and month-of-year.
   • Calculate 95% confidence bands (standard error * 1.96) around each mean.
   • Generate three subplot PNG panels (hour, day, month) with error bands.
   • Inspired by openair's timeVariation().

   Polar Plot:

   • Requires wind_speed and wind_dir columns; stop with guidance if missing.
   • Bin wind direction (16 or 8 bins, e.g., N, NE, E, SE, S, SW, W, NW) and wind speed (e.g., 0–2, 2–5, 5–10, >10 m/s).
   • Compute mean pollutant concentration in each bin.
   • Generate polar contour/scatter plot (matplotlib polar projection or similar).
   • Inspired by openair's polarPlot().

   Calendar Plot:

   • Aggregate to daily mean per pollutant.
   • Generate heatmap grid (rows = weeks, columns = days; months separated).
   • Color intensity represents concentration; missing days appear gray.
   • PNG output showing full date range.

   Simple Forecast:

   • Check if user has statsmodels (ARIMA) or prophet installed; print install hint if missing.
   • Fit ARIMA(1, 1, 1) or Prophet with default settings to the last 60 days of data.
   • Forecast 7–14 days ahead.
   • Return CSV with date, pollutant, forecast, lower_ci, upper_ci (95% CI).
   • Caveat: "This is a baseline forecast; for operational air quality prediction, consult specialized models."

4. Write outputs:

   • PNGs: {output_path}/{analysis_type}_{pollutant}.png
   • CSVs: {output_path}/{analysis_type}_{pollutant}.csv (summary stats, forecast, etc.)

5. Print summary of outputs generated and their file locations.

Output / side effects

• PNG files written to user-specified directory (or cwd if not specified).
• CSV summaries (daily means, hourly aggregates, forecast values, bin statistics).
• Console report: number of rows processed, date range covered, any gaps in data, which columns were used.

Example filenames:

time-variation_PM2.5.png
polar-plot_PM2.5.png
calendar-plot_PM2.5.png
forecast_PM2.5.csv

Safety / constraints

• If required libraries are missing (pandas, matplotlib, numpy), print install command and stop gracefully.
• If the CSV has <7 days of data, warn that time-variation and forecast results may be unreliable.
• Do not automatically smooth or gap-fill data; ask the user if interpolation is desired.
• For forecasts, include a disclaimer: "This is a simple baseline and does not account for weather patterns, traffic, or external events. Use for exploration only; do not rely for public health guidance."
• Offer to point users to the openair R package for advanced analysis: https://github.com/davidcarslaw/openair