iotlabkit 1.0.0__py3-none-any.whl

iotlabkit/templates/program_14.py

@@ -0,0 +1,287 @@
+"""Template generator for Program 14: Kochi Hourly Air Quality & Health Index Analysis."""
+
+from typing import Dict
+
+
+def generate(target_dir: str, mode: str = "learning") -> Dict[str, str]:
+    files = {}
+
+    files["requirements.txt"] = (
+        "requests>=2.28.0\n"
+        "pandas>=1.5.0\n"
+        "matplotlib>=3.6.0\n"
+        "streamlit>=1.25.0\n"
+    )
+
+    files[".env.example"] = (
+        "# Kochi Air Quality Coordinates\n"
+        "LATITUDE=9.93\n"
+        "LONGITUDE=76.27\n"
+        "PAST_DAYS=7\n"
+    )
+
+    files[".gitignore"] = (
+        ".env\n"
+        "__pycache__/\n"
+        "*.py[cod]\n"
+        "output/*.png\n"
+    )
+
+    # fetch_air_quality.py
+    if mode == "learning":
+        fetch_doc = (
+            '"""Kochi Air Quality Data Ingestion - Program 14.\n\n'
+            "Retrieves genuine hourly air-quality observations from Open-Meteo Air Quality API\n"
+            "for Kochi (9.93°N, 76.27°E), collecting PM10, PM2.5, and US AQI indices.\n"
+            '"""\n'
+        )
+    else:
+        fetch_doc = '"""Air Quality Ingestion - Program 14 (Exam Mode)."""\n'
+
+    files["fetch_air_quality.py"] = fetch_doc + (
+        "import argparse\n"
+        "import os\n"
+        "import sys\n"
+        "import pandas as pd\n"
+        "import requests\n\n"
+        "DEFAULT_LAT = 9.93\n"
+        "DEFAULT_LON = 76.27\n"
+        "OUTPUT_CSV = os.path.join(os.path.dirname(__file__), 'data', 'air_quality_kochi.csv')\n\n"
+        "def fetch_air_quality(lat: float, lon: float, past_days: int = 7) -> pd.DataFrame:\n"
+        "    url = 'https://air-quality-api.open-meteo.com/v1/air-quality'\n"
+        "    params = {\n"
+        "        'latitude': lat,\n"
+        "        'longitude': lon,\n"
+        "        'hourly': 'pm10,pm2_5,us_aqi',\n"
+        "        'past_days': past_days,\n"
+        "        'forecast_days': 1,\n"
+        "        'timezone': 'auto'\n"
+        "    }\n"
+        "    print(f\"Retrieving hourly air quality observations from Open-Meteo (Lat: {lat}, Lon: {lon})...\")\n"
+        "    resp = requests.get(url, params=params, timeout=12)\n"
+        "    if resp.status_code != 200:\n"
+        "        raise RuntimeError(f\"Open-Meteo Air Quality API error ({resp.status_code}): {resp.text}\")\n\n"
+        "    data = resp.json()\n"
+        "    hourly = data.get('hourly', {})\n"
+        "    df = pd.DataFrame({\n"
+        "        'time': hourly.get('time', []),\n"
+        "        'pm10': hourly.get('pm10', []),\n"
+        "        'pm2_5': hourly.get('pm2_5', []),\n"
+        "        'us_aqi': hourly.get('us_aqi', [])\n"
+        "    })\n"
+        "    return df\n\n"
+        "def main():\n"
+        "    parser = argparse.ArgumentParser(description='Fetch Kochi air quality data')\n"
+        "    parser.add_argument('--lat', type=float, default=DEFAULT_LAT, help='Latitude')\n"
+        "    parser.add_argument('--lon', type=float, default=DEFAULT_LON, help='Longitude')\n"
+        "    parser.add_argument('--days', type=int, default=7, help='Past days')\n"
+        "    args = parser.parse_args()\n\n"
+        "    os.makedirs(os.path.dirname(OUTPUT_CSV), exist_ok=True)\n"
+        "    try:\n"
+        "        df = fetch_air_quality(args.lat, args.lon, args.days)\n"
+        "        df.to_csv(OUTPUT_CSV, index=False)\n"
+        "        print(f\"✓ Saved {len(df)} air-quality observations to {OUTPUT_CSV}\")\n"
+        "        print(\"Now run `python analyzer.py` to calculate particulate statistics and health index trends.\")\n"
+        "    except Exception as err:\n"
+        "        print(f\"✗ Error fetching air quality: {err}\")\n"
+        "        sys.exit(1)\n\n"
+        "if __name__ == '__main__':\n"
+        "    main()\n"
+    )
+
+    # analyzer.py
+    if mode == "learning":
+        ana_doc = (
+            '"""Air Quality Time-Series & Statistical Health Index Analyzer.\n\n'
+            "Evaluates PM10 and PM2.5 concentrations, computes EPA AQI health category buckets,\n"
+            "distinguishes missing observations from calculated statistics, and plots trends.\n"
+            '"""\n'
+        )
+    else:
+        ana_doc = '"""Air Quality Analyzer - Program 14 (Exam Mode)."""\n'
+
+    files["analyzer.py"] = ana_doc + (
+        "import os\n"
+        "import sys\n"
+        "import pandas as pd\n"
+        "try:\n"
+        "    import matplotlib.pyplot as plt\n"
+        "    HAS_MATPLOTLIB = True\n"
+        "except ImportError:\n"
+        "    HAS_MATPLOTLIB = False\n\n"
+        "CSV_PATH = os.path.join(os.path.dirname(__file__), 'data', 'air_quality_kochi.csv')\n"
+        "OUTPUT_DIR = os.path.join(os.path.dirname(__file__), 'output')\n\n"
+        "def categorize_us_aqi(aqi: float) -> str:\n"
+        "    if pd.isna(aqi):\n"
+        "        return 'Missing Observation'\n"
+        "    if aqi <= 50:\n"
+        "        return 'Good (0-50)'\n"
+        "    elif aqi <= 100:\n"
+        "        return 'Moderate (51-100)'\n"
+        "    elif aqi <= 150:\n"
+        "        return 'Unhealthy for Sensitive Groups (101-150)'\n"
+        "    elif aqi <= 200:\n"
+        "        return 'Unhealthy (151-200)'\n"
+        "    elif aqi <= 300:\n"
+        "        return 'Very Unhealthy (201-300)'\n"
+        "    else:\n"
+        "        return 'Hazardous (>300)'\n\n"
+        "def main():\n"
+        "    if not os.path.exists(CSV_PATH) or os.path.getsize(CSV_PATH) == 0:\n"
+        "        print(f\"✗ Error: Dataset file '{CSV_PATH}' is missing.\")\n"
+        "        print(\"  Run `python fetch_air_quality.py` first to retrieve live API observations.\")\n"
+        "        sys.exit(1)\n\n"
+        "    df = pd.read_csv(CSV_PATH)\n"
+        "    os.makedirs(OUTPUT_DIR, exist_ok=True)\n\n"
+        "    # Data Audit: Clearly distinguish raw observations, missing values, and calculated statistics\n"
+        "    total_rows = len(df)\n"
+        "    missing_pm25 = df['pm2_5'].isna().sum()\n"
+        "    missing_pm10 = df['pm10'].isna().sum()\n"
+        "    missing_aqi = df['us_aqi'].isna().sum()\n\n"
+        "    print('=' * 70)\n"
+        "    print('💨 Kochi Air Quality Statistical & Health Analysis')\n"
+        "    print('=' * 70)\n"
+        "    print(f\"Total Hourly Records    : {total_rows}\")\n"
+        "    print(f\"Missing Observations    : PM2.5: {missing_pm25}, PM10: {missing_pm10}, US AQI: {missing_aqi}\")\n"
+        "    print('-' * 70)\n"
+        "    print('Calculated Statistics (Excluding missing observations):')\n"
+        "    print(f\"  PM2.5 (μg/m³)         : Mean = {df['pm2_5'].mean():.2f}, Median = {df['pm2_5'].median():.2f}, Peak = {df['pm2_5'].max():.1f}, Std = {df['pm2_5'].std():.2f}\")\n"
+        "    print(f\"  PM10  (μg/m³)         : Mean = {df['pm10'].mean():.2f}, Median = {df['pm10'].median():.2f}, Peak = {df['pm10'].max():.1f}, Std = {df['pm10'].std():.2f}\")\n"
+        "    print(f\"  US AQI (Index)        : Mean = {df['us_aqi'].mean():.1f}, Peak = {df['us_aqi'].max():.0f}, Min = {df['us_aqi'].min():.0f}\")\n\n"
+        "    df['aqi_category'] = df['us_aqi'].apply(categorize_us_aqi)\n"
+        "    category_counts = df['aqi_category'].value_counts()\n"
+        "    print('\\nUS EPA AQI Health Category Breakdown:')\n"
+        "    for cat, cnt in category_counts.items():\n"
+        "        pct = round(cnt / total_rows * 100, 1)\n"
+        "        print(f\"  - {cat:<36}: {cnt:>3} hours ({pct:>4}%)\")\n"
+        "    print('=' * 70 + '\\n')\n\n"
+        "    if HAS_MATPLOTLIB:\n"
+        "        # Chart 1: Time Series Trend of PM2.5 and PM10 with WHO Air Quality Guidelines\n"
+        "        plt.figure(figsize=(11, 5))\n"
+        "        plt.plot(df.index, df['pm2_5'], color='darkorange', label='PM2.5 (Fine Particulate)', linewidth=1.8)\n"
+        "        plt.plot(df.index, df['pm10'], color='royalblue', label='PM10 (Inhalable Particulate)', linewidth=1.5, linestyle='--')\n"
+        "        plt.axhline(15, color='orange', linestyle=':', label='WHO PM2.5 24h Guideline (15 μg/m³)')\n"
+        "        plt.axhline(45, color='blue', linestyle=':', label='WHO PM10 24h Guideline (45 μg/m³)')\n\n"
+        "        # Subsample ticks\n"
+        "        step = max(1, len(df) // 10)\n"
+        "        plt.xticks(range(0, len(df), step), [df['time'].iloc[i][:13] for i in range(0, len(df), step)], rotation=35, ha='right')\n"
+        "        plt.title('Hourly Particulate Matter Trends (Kochi, Kerala)')\n"
+        "        plt.xlabel('Timestamp (Hourly)')\n"
+        "        plt.ylabel('Concentration (μg/m³)')\n"
+        "        plt.grid(True, linestyle='--', alpha=0.6)\n"
+        "        plt.legend(loc='upper right')\n"
+        "        p1 = os.path.join(OUTPUT_DIR, 'air_quality_pm_trends.png')\n"
+        "        plt.savefig(p1, dpi=150, bbox_inches='tight')\n"
+        "        plt.close()\n"
+        "        print(f\"✓ Saved Particulate Trend Plot: {p1}\")\n\n"
+        "        # Chart 2: US AQI Time Series with Health Threshold Bands\n"
+        "        plt.figure(figsize=(11, 4.5))\n"
+        "        plt.plot(df.index, df['us_aqi'], color='purple', label='US AQI', linewidth=2.0)\n"
+        "        plt.axhspan(0, 50, color='green', alpha=0.15, label='Good (0-50)')\n"
+        "        plt.axhspan(50, 100, color='yellow', alpha=0.15, label='Moderate (51-100)')\n"
+        "        plt.axhspan(100, 150, color='orange', alpha=0.15, label='Sensitive (101-150)')\n"
+        "        plt.xticks(range(0, len(df), step), [df['time'].iloc[i][:13] for i in range(0, len(df), step)], rotation=35, ha='right')\n"
+        "        plt.title('US Air Quality Index (AQI) Health Thresholds')\n"
+        "        plt.xlabel('Timestamp')\n"
+        "        plt.ylabel('AQI Value')\n"
+        "        plt.grid(True, linestyle='--', alpha=0.6)\n"
+        "        plt.legend(loc='upper right')\n"
+        "        p2 = os.path.join(OUTPUT_DIR, 'air_quality_aqi_thresholds.png')\n"
+        "        plt.savefig(p2, dpi=150, bbox_inches='tight')\n"
+        "        plt.close()\n"
+        "        print(f\"✓ Saved AQI Threshold Chart: {p2}\")\n"
+        "    else:\n"
+        "        print(\"\\nℹ️  Notice: matplotlib not installed. Statistical metrics printed above; plot generation skipped.\")\n\n"
+        "if __name__ == '__main__':\n"
+        "    main()\n"
+    )
+
+    # dashboard.py
+    files["dashboard.py"] = (
+        "import os\n"
+        "import pandas as pd\n"
+        "import streamlit as st\n\n"
+        "st.set_page_config(page_title='Program 14: Kochi Air Quality', layout='wide')\n"
+        "st.title('💨 Kochi Air Quality & Health Index Dashboard')\n"
+        "st.caption('MSc/MCA IoT Practical — Program 14 (Open-Meteo Air Quality Analysis)')\n\n"
+        "CSV_PATH = os.path.join(os.path.dirname(__file__), 'data', 'air_quality_kochi.csv')\n\n"
+        "if not os.path.exists(CSV_PATH) or os.path.getsize(CSV_PATH) == 0:\n"
+        "    st.warning('No air quality data found. Run `python fetch_air_quality.py` to retrieve observations.')\n"
+        "else:\n"
+        "    df = pd.read_csv(CSV_PATH)\n"
+        "    latest = df.dropna().iloc[-1] if not df.dropna().empty else df.iloc[-1]\n\n"
+        "    c1, c2, c3, c4 = st.columns(4)\n"
+        "    c1.metric('Latest PM2.5', f\"{latest['pm2_5']} μg/m³\")\n"
+        "    c2.metric('Latest PM10', f\"{latest['pm10']} μg/m³\")\n"
+        "    c3.metric('Latest US AQI', f\"{int(latest['us_aqi']) if pd.notna(latest['us_aqi']) else 'N/A'}\")\n"
+        "    c4.metric('Total Observations', len(df))\n\n"
+        "    st.subheader('📈 Particulate Matter Trends (PM2.5 & PM10)')\n"
+        "    st.line_chart(df.set_index('time')[['pm2_5', 'pm10']], use_container_width=True)\n\n"
+        "    st.subheader('📊 Air Quality Index (US AQI)')\n"
+        "    st.line_chart(df.set_index('time')['us_aqi'], use_container_width=True)\n\n"
+        "    st.subheader('📋 Detailed Air Quality Observations Log')\n"
+        "    st.dataframe(df.tail(30), use_container_width=True)\n"
+    )
+
+    # Initial sample dataset for offline verification
+    files["data/air_quality_kochi.csv"] = (
+        "time,pm10,pm2_5,us_aqi\n"
+        "2024-11-01T00:00,34.2,28.5,85\n"
+        "2024-11-01T03:00,38.1,31.2,91\n"
+        "2024-11-01T06:00,45.6,37.8,106\n"
+        "2024-11-01T09:00,32.4,25.1,78\n"
+        "2024-11-01T12:00,26.8,20.4,68\n"
+        "2024-11-01T15:00,24.5,18.9,65\n"
+        "2024-11-01T18:00,35.7,29.3,87\n"
+        "2024-11-01T21:00,41.2,34.6,98\n"
+    )
+
+    # README.md
+    if mode == "learning":
+        readme_content = (
+            "# Program 14 — Kochi Hourly Air Quality & Health Index Analysis\n\n"
+            "## 1. Overview\n"
+            "This practical performs environmental health analytics on real atmospheric particulate measurements:\n"
+            "- Collects authentic hourly PM10, PM2.5, and US AQI data for Kochi (Lat: `9.93°N`, Lon: `76.27°E`) from Open-Meteo Air Quality API.\n"
+            "- Performs rigorous data auditing: clearly distinguishes raw API observations, missing observations (NaNs), and calculated dispersion statistics.\n"
+            "- Analyzes pollution curves against WHO 24-hour health guidelines.\n"
+            "- Generates time-series plots and provides an interactive Streamlit dashboard.\n\n"
+            "## 2. Execution Guide\n\n"
+            "### Step A: Fetch Live Hourly Air Quality\n"
+            "```bash\n"
+            "pip install -r requirements.txt\n"
+            "python fetch_air_quality.py\n"
+            "```\n\n"
+            "### Step B: Run Analytics & Generate Plots\n"
+            "```bash\n"
+            "python analyzer.py\n"
+            "```\n"
+            "Generated charts in `output/`:\n"
+            "- `air_quality_pm_trends.png` (PM2.5 and PM10 with WHO guideline thresholds)\n"
+            "- `air_quality_aqi_thresholds.png` (US AQI with health risk color bands)\n\n"
+            "### Step C: Launch Dashboard\n"
+            "```bash\n"
+            "streamlit run dashboard.py\n"
+            "```\n\n"
+            "## 3. Viva Questions and Answers\n"
+            "**Q1: Why is PM2.5 considered more hazardous to human health than PM10?**  \n"
+            "A: PM2.5 particles are small enough (<= 2.5 um) to penetrate past the nasal passage and bronchioles, reaching deep into the alveoli of the lungs and directly diffusing into the bloodstream.\n\n"
+            "**Q2: How does US AQI differ from raw pollutant concentration?**  \n"
+            "A: US AQI is a standardized piecewise linear index (0 to 500) that normalizes different pollutant measurements onto a unified scale reflecting relative health hazard categories (Good, Moderate, Unhealthy, Hazardous).\n"
+        )
+    else:
+        readme_content = (
+            "# Program 14 — Air Quality Analysis (Exam Mode)\n\n"
+            "## Execution\n"
+            "1. Fetch data: `python fetch_air_quality.py`\n"
+            "2. Analyze & plot: `python analyzer.py`\n"
+            "3. Dashboard: `streamlit run dashboard.py`\n\n"
+            "## Viva Q&A\n"
+            "- **Q: What is the WHO recommended 24-hour limit for PM2.5?**  \n"
+            "  A: 15 $\\mu\\text{g/m}^3$ (updated in 2021 WHO Global Air Quality Guidelines).\n"
+            "- **Q: Why distinguish missing observations from calculated statistics?**  \n"
+            "  A: Failing to separate missing values from zero readings distorts statistical measures like mean and variance.\n"
+        )
+
+    files["README.md"] = readme_content
+    return files