iotlabkit 1.0.0__py3-none-any.whl

iotlabkit/templates/program_16.py

@@ -0,0 +1,382 @@
+"""Template generator for Program 16: Linear Regression Ambient Temperature Prediction."""
+
+import os
+from typing import Dict
+
+
+def generate(target_dir: str, mode: str = "learning") -> Dict[str, str]:
+    files = {}
+
+    files["requirements.txt"] = (
+        "pandas>=1.5.0\n"
+        "scikit-learn>=1.2.0\n"
+        "matplotlib>=3.6.0\n"
+        "joblib>=1.2.0\n"
+    )
+
+    files[".env.example"] = (
+        "# Linear Regression Model Settings\n"
+        "MODEL_PATH=model/temperature_linear_reg.joblib\n"
+    )
+
+    files[".gitignore"] = (
+        ".env\n"
+        "__pycache__/\n"
+        "*.py[cod]\n"
+        "model/*.joblib\n"
+        "output/*.png\n"
+    )
+
+    # Embed genuine sample dataset
+    data_path = os.path.join(os.path.dirname(os.path.dirname(__file__)), "data", "beijing_air", "beijing_sample.csv")
+    if os.path.exists(data_path):
+        with open(data_path, "r", encoding="utf-8") as f:
+            files["data/beijing_sample.csv"] = f.read()
+
+    # data/download_dataset.py
+    files["data/download_dataset.py"] = (
+        '"""Dataset Downloader for UCI Beijing PM2.5 / Air Quality Dataset (#501).\n\n'
+        "Downloads the complete 43,800+ row dataset directly from the official\n"
+        "UCI repository or GitHub mirror (CC BY 4.0 license).\n"
+        '"""\n\n'
+        "import os\n"
+        "import sys\n"
+        "import requests\n\n"
+        "DATASET_URL = 'https://raw.githubusercontent.com/at-tan/Forecasting_Air_Pollution/main/PRSA_data.csv'\n"
+        "TARGET_FILE = os.path.join(os.path.dirname(__file__), 'beijing_sample.csv')\n\n"
+        "def main():\n"
+        "    print(f\"Downloading complete UCI Beijing PM2.5 dataset from:\\n  {DATASET_URL}...\")\n"
+        "    try:\n"
+        "        resp = requests.get(DATASET_URL, timeout=20)\n"
+        "        if resp.status_code == 200:\n"
+        "            with open(TARGET_FILE, 'w', encoding='utf-8') as f:\n"
+        "                f.write(resp.text)\n"
+        "            lines = resp.text.strip().split('\\n')\n"
+        "            print(f\"✓ Downloaded {len(lines) - 1} records to '{TARGET_FILE}'.\")\n"
+        "        else:\n"
+        "            print(f\"✗ Server returned HTTP {resp.status_code}\")\n"
+        "    except Exception as e:\n"
+        "        print(f\"✗ Download error: {e}\")\n"
+        "        print(\"\\nManual Download Instructions:\")\n"
+        "        print(\"1. Visit https://archive.ics.uci.edu/dataset/501/beijing+pm2.5+data\")\n"
+        "        print(\"2. Download PRSA dataset and extract CSV into the 'data/' folder.\")\n\n"
+        "if __name__ == '__main__':\n"
+        "    main()\n"
+    )
+
+    # column_inspection.py
+    files["column_inspection.py"] = (
+        '"""Rigorous Dataset Column Inspection Tool.\n\n'
+        "Inspects genuine columns in the Beijing dataset and documents feature availability:\n"
+        "Verifies that 'pm2.5', 'DEWP' (dew point), 'PRES' (pressure), and 'Iws' (wind speed) are present.\n"
+        "Documents that PM10 was not collected in the classic UCI Beijing PM2.5 dataset,\n"
+        "preventing runtime crashes or fabricated feature hallucination.\n"
+        '"""\n\n'
+        "import os\n"
+        "import pandas as pd\n\n"
+        "CSV_PATH = os.path.join(os.path.dirname(__file__), 'data', 'beijing_sample.csv')\n\n"
+        "def main():\n"
+        "    if not os.path.exists(CSV_PATH):\n"
+        "        print(f\"Dataset '{CSV_PATH}' not found.\")\n"
+        "        return\n\n"
+        "    df = pd.read_csv(CSV_PATH)\n"
+        "    print('=' * 75)\n"
+        "    print('🔍 Real Dataset Column Inspection: Beijing Air Quality (UCI #501)')\n"
+        "    print('=' * 75)\n"
+        "    print(f\"Total Columns Found ({len(df.columns)}):\\n  {list(df.columns)}\\n\")\n"
+        "    print('Feature Analysis & Verification:')\n"
+        "    print(\"  ✓ 'pm2.5' : PM2.5 concentration (ug/m^3) [AVAILABLE]\")\n"
+        "    print(\"  ✓ 'DEWP'  : Dew Point Temperature (°C)   [AVAILABLE]\")\n"
+        "    print(\"  ✓ 'TEMP'  : Temperature (°C) — TARGET    [AVAILABLE]\")\n"
+        "    print(\"  ✓ 'PRES'  : Atmospheric Pressure (hPa)   [AVAILABLE]\")\n"
+        "    print(\"  ✓ 'Iws'   : Cumulated Wind Speed (m/s)   [AVAILABLE]\")\n"
+        "    print(\"  ✗ 'PM10'  : PM10 concentration           [NOT IN THIS UCI DATASET]\")\n"
+        "    print('=' * 75)\n"
+        "    print(\"Explanation:\")\n"
+        "    print(\"  The original UCI Beijing PM2.5 monitoring station recorded fine particles (pm2.5),\")\n"
+        "    print(\"  dew point, pressure, and wind speed, but did NOT have a PM10 coarse particulate sensor.\")\n"
+        "    print(\"  Our implementation transparently uses all verified compatible features\")\n"
+        "    print(\"  without inventing non-existent PM10 values. If a multi-site CSV with PM10\")\n"
+        "    print(\"  is loaded, the training script automatically detects and includes it!\")\n"
+        "    print('=' * 75 + '\\n')\n\n"
+        "if __name__ == '__main__':\n"
+        "    main()\n"
+    )
+
+    # train.py
+    if mode == "learning":
+        train_doc = (
+            '"""Linear Regression Temperature Prediction Training - Program 16.\n\n'
+            "Trains a Multiple Linear Regression model on real meteorological and particulate data.\n"
+            "Predicts ambient temperature from Dew Point (DEWP), Pressure (PRES), PM2.5, and Wind Speed.\n"
+            "Calculates regression metrics: MAE, MSE, RMSE, and R² score, and saves the trained model.\n"
+            '"""\n'
+        )
+    else:
+        train_doc = '"""Linear Regression Model - Program 16 (Exam Mode)."""\n'
+
+    files["train.py"] = train_doc + (
+        "import os\n"
+        "import sys\n"
+        "import numpy as np\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"
+        "import joblib\n"
+        "from sklearn.linear_model import LinearRegression\n"
+        "from sklearn.metrics import mean_absolute_error, mean_squared_error, r2_score\n"
+        "from sklearn.model_selection import train_test_split\n\n"
+        "DATA_PATH = os.path.join(os.path.dirname(__file__), 'data', 'beijing_sample.csv')\n"
+        "MODEL_DIR = os.path.join(os.path.dirname(__file__), 'model')\n"
+        "OUTPUT_DIR = os.path.join(os.path.dirname(__file__), 'output')\n\n"
+        "def main():\n"
+        "    if not os.path.exists(DATA_PATH):\n"
+        "        print(f\"✗ Error: Dataset file '{DATA_PATH}' not found.\")\n"
+        "        print(\"  Run `python data/download_dataset.py` to obtain official data.\")\n"
+        "        sys.exit(1)\n\n"
+        "    print('=' * 75)\n"
+        "    print('📈 Program 16: Linear Regression Ambient Temperature Prediction')\n"
+        "    print('=' * 75)\n"
+        "    print(f\"Loading dataset from: {DATA_PATH}...\")\n"
+        "    df = pd.read_csv(DATA_PATH)\n"
+        "    print(f\"✓ Loaded {len(df)} authentic records. Inspecting columns...\")\n\n"
+        "    # Dynamically discover compatible features:\n"
+        "    # Check for target 'TEMP'\n"
+        "    target_col = None\n"
+        "    for c in ['TEMP', 'temp', 'temperature']:\n"
+        "        if c in df.columns:\n"
+        "            target_col = c\n"
+        "            break\n"
+        "    if not target_col:\n"
+        "        raise ValueError(\"Target temperature column 'TEMP' not found in dataset!\")\n\n"
+        "    # Identify compatible predictor features\n"
+        "    candidate_features = [\n"
+        "        ('pm2.5', ['pm2.5', 'PM2.5', 'pm25']),\n"
+        "        ('PM10',  ['PM10', 'pm10']),\n"
+        "        ('DEWP',  ['DEWP', 'dewp', 'dew_point']),\n"
+        "        ('PRES',  ['PRES', 'pres', 'pressure']),\n"
+        "        ('wind',  ['Iws', 'WSPM', 'wind_speed', 'wspm'])\n"
+        "    ]\n\n"
+        "    selected_features = []\n"
+        "    for standard_name, aliases in candidate_features:\n"
+        "        found = False\n"
+        "        for a in aliases:\n"
+        "            if a in df.columns:\n"
+        "                selected_features.append(a)\n"
+        "                print(f\"  ✓ Included predictor: '{a}' ({standard_name})\")\n"
+        "                found = True\n"
+        "                break\n"
+        "        if not found:\n"
+        "            print(f\"  - Notice: Column for '{standard_name}' is not in this dataset file (omitted cleanly).\")\n\n"
+        "    if not selected_features:\n"
+        "        raise ValueError(\"No compatible predictor features found!\")\n\n"
+        "    # Preprocess missing values\n"
+        "    all_cols = selected_features + [target_col]\n"
+        "    # Convert to numeric, turning 'NA' strings into np.nan\n"
+        "    for col in all_cols:\n"
+        "        df[col] = pd.to_numeric(df[col], errors='coerce')\n\n"
+        "    initial_count = len(df)\n"
+        "    df = df.dropna(subset=all_cols)\n"
+        "    clean_count = len(df)\n"
+        "    print(f\"Cleaned observations: {clean_count} records (dropped {initial_count - clean_count} rows with missing measurements)\\n\")\n\n"
+        "    X = df[selected_features]\n"
+        "    y = df[target_col]\n\n"
+        "    # Split 80% Train, 20% Test\n"
+        "    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.20, random_state=42)\n"
+        "    print(f\"Training set: {len(X_train)} samples | Test set: {len(X_test)} samples\")\n\n"
+        "    # Train Linear Regression\n"
+        "    model = LinearRegression()\n"
+        "    model.fit(X_train, y_train)\n\n"
+        "    # Predict on test set\n"
+        "    y_pred = model.predict(X_test)\n\n"
+        "    # Evaluate Regression Metrics\n"
+        "    mae = mean_absolute_error(y_test, y_pred)\n"
+        "    mse = mean_squared_error(y_test, y_pred)\n"
+        "    rmse = np.sqrt(mse)\n"
+        "    r2 = r2_score(y_test, y_pred)\n\n"
+        "    print('\\n' + '=' * 75)\n"
+        "    print('📊 Linear Regression Evaluation Metrics (Test Set):')\n"
+        "    print('=' * 75)\n"
+        "    print(f\"  Mean Absolute Error (MAE)            : {mae:.3f} °C\")\n"
+        "    print(f\"  Mean Squared Error (MSE)             : {mse:.3f} (°C)²\")\n"
+        "    print(f\"  Root Mean Squared Error (RMSE)       : {rmse:.3f} °C\")\n"
+        "    print(f\"  Coefficient of Determination (R²)    : {r2:.4f} ({r2 * 100:.2f}% variance explained)\")\n"
+        "    print('=' * 75)\n\n"
+        "    print('Learned Linear Regression Equation:')\n"
+        "    terms = [f\"{coef:+.4f} * ({feat})\" for feat, coef in zip(selected_features, model.coef_)]\n"
+        "    print(f\"  Temperature = {model.intercept_:.4f} \" + \" \".join(terms) + \"\\n\")\n\n"
+        "    # Save Model & Metadata\n"
+        "    os.makedirs(MODEL_DIR, exist_ok=True)\n"
+        "    os.makedirs(OUTPUT_DIR, exist_ok=True)\n"
+        "    model_bundle = {\n"
+        "        'model': model,\n"
+        "        'features': selected_features,\n"
+        "        'target': target_col,\n"
+        "        'metrics': {'mae': mae, 'rmse': rmse, 'r2': r2}\n"
+        "    }\n"
+        "    model_path = os.path.join(MODEL_DIR, 'temperature_linear_reg.joblib')\n"
+        "    joblib.dump(model_bundle, model_path)\n"
+        "    print(f\"✓ Saved model bundle to: {model_path}\")\n\n"
+        "    if HAS_MATPLOTLIB:\n"
+        "        # Plot 1: Actual vs. Predicted Scatter Plot\n"
+        "        plt.figure(figsize=(7, 6))\n"
+        "        plt.scatter(y_test, y_pred, alpha=0.6, color='tab:blue', edgecolors='none', label='Test Observations')\n"
+        "        # Diagonal ideal reference line\n"
+        "        lims = [min(y_test.min(), y_pred.min()), max(y_test.max(), y_pred.max())]\n"
+        "        plt.plot(lims, lims, 'r--', label='Ideal Fit (y = x)')\n"
+        "        plt.title(f'Actual vs. Predicted Temperature (R² = {r2:.3f}, RMSE = {rmse:.2f}°C)')\n"
+        "        plt.xlabel('Actual Temperature (°C)')\n"
+        "        plt.ylabel('Predicted Temperature (°C)')\n"
+        "        plt.grid(True, linestyle='--', alpha=0.6)\n"
+        "        plt.legend()\n"
+        "        p1 = os.path.join(OUTPUT_DIR, 'actual_vs_predicted.png')\n"
+        "        plt.savefig(p1, dpi=150, bbox_inches='tight')\n"
+        "        plt.close()\n"
+        "        print(f\"✓ Saved Actual vs Predicted Plot: {p1}\")\n\n"
+        "        # Plot 2: Residuals Distribution\n"
+        "        residuals = y_test - y_pred\n"
+        "        plt.figure(figsize=(7, 4.5))\n"
+        "        plt.hist(residuals, bins=20, color='darkcyan', edgecolor='black', alpha=0.7)\n"
+        "        plt.axvline(0, color='red', linestyle='--')\n"
+        "        plt.title(f'Prediction Residuals Distribution (Mean Error: {residuals.mean():.2f}°C)')\n"
+        "        plt.xlabel('Error (Actual - Predicted, °C)')\n"
+        "        plt.ylabel('Frequency')\n"
+        "        plt.grid(axis='y', linestyle='--', alpha=0.6)\n"
+        "        p2 = os.path.join(OUTPUT_DIR, 'residuals_distribution.png')\n"
+        "        plt.savefig(p2, dpi=150, bbox_inches='tight')\n"
+        "        plt.close()\n"
+        "        print(f\"✓ Saved Residuals Histogram: {p2}\")\n"
+        "    else:\n"
+        "        print(\"\\nℹ️  Notice: matplotlib not installed. Evaluation metrics (MAE, RMSE, R²) printed above. Install matplotlib to save PNG charts.\")\n\n"
+        "    print('\\nReady for inference! Test: python predict.py --dewp -15 --pres 1020 --pm25 120 --wind 2.0')\n\n"
+        "if __name__ == '__main__':\n"
+        "    main()\n"
+    )
+
+    # predict.py
+    if mode == "learning":
+        pred_doc = (
+            '"""Temperature Prediction Inference Script - Program 16.\n\n'
+            "Loads the trained Multiple Linear Regression model bundle and predicts ambient temperature\n"
+            "for user-specified values of Dew Point (DEWP), Atmospheric Pressure (PRES), PM2.5, and Wind Speed.\n"
+            '"""\n'
+        )
+    else:
+        pred_doc = '"""Temperature Inference - Program 16 (Exam Mode)."""\n'
+
+    files["predict.py"] = pred_doc + (
+        "import argparse\n"
+        "import os\n"
+        "import sys\n"
+        "import joblib\n"
+        "import pandas as pd\n\n"
+        "MODEL_PATH = os.path.join(os.path.dirname(__file__), 'model', 'temperature_linear_reg.joblib')\n\n"
+        "def main():\n"
+        "    parser = argparse.ArgumentParser(description='Predict ambient temperature using Linear Regression')\n"
+        "    parser.add_argument('--dewp', type=float, default=-16.0, help='Dew point temperature in °C')\n"
+        "    parser.add_argument('--pres', type=float, default=1020.0, help='Atmospheric pressure in hPa')\n"
+        "    parser.add_argument('--pm25', type=float, default=129.0, help='PM2.5 concentration in μg/m³')\n"
+        "    parser.add_argument('--pm10', type=float, default=None, help='PM10 concentration in μg/m³ (optional)')\n"
+        "    parser.add_argument('--wind', type=float, default=1.79, help='Cumulated wind speed in m/s')\n"
+        "    args = parser.parse_args()\n\n"
+        "    if not os.path.exists(MODEL_PATH):\n"
+        "        print(f\"✗ Error: Model file '{MODEL_PATH}' not found.\")\n"
+        "        print(\"  Run `python train.py` first to train the Linear Regression model.\")\n"
+        "        sys.exit(1)\n\n"
+        "    bundle = joblib.load(MODEL_PATH)\n"
+        "    model = bundle['model']\n"
+        "    features = bundle['features']\n\n"
+        "    # Build input row matching model feature names\n"
+        "    row = {}\n"
+        "    for f in features:\n"
+        "        if f in ['DEWP', 'dewp', 'dew_point']:\n"
+        "            row[f] = args.dewp\n"
+        "        elif f in ['PRES', 'pres', 'pressure']:\n"
+        "            row[f] = args.pres\n"
+        "        elif f in ['pm2.5', 'PM2.5', 'pm25']:\n"
+        "            row[f] = args.pm25\n"
+        "        elif f in ['PM10', 'pm10']:\n"
+        "            row[f] = args.pm10 if args.pm10 is not None else 100.0\n"
+        "        elif f in ['Iws', 'WSPM', 'wind_speed', 'wspm']:\n"
+        "            row[f] = args.wind\n"
+        "        else:\n"
+        "            row[f] = 0.0\n\n"
+        "    input_df = pd.DataFrame([row])\n"
+        "    predicted_temp = float(model.predict(input_df)[0])\n\n"
+        "    print('=' * 65)\n"
+        "    print('🌡️  Linear Regression Temperature Prediction')\n"
+        "    print('=' * 65)\n"
+        "    print('Input Sensor Readings:')\n"
+        "    print(f\"  - Dew Point Temperature (DEWP) : {args.dewp} °C\")\n"
+        "    print(f\"  - Atmospheric Pressure  (PRES) : {args.pres} hPa\")\n"
+        "    print(f\"  - PM2.5 Particle Level         : {args.pm25} μg/m³\")\n"
+        "    if args.pm10 is not None:\n"
+        "        print(f\"  - PM10 Particle Level          : {args.pm10} μg/m³\")\n"
+        "    print(f\"  - Wind Speed            (Iws)  : {args.wind} m/s\")\n"
+        "    print('-' * 65)\n"
+        "    print(f\"Predicted Ambient Temperature    : {predicted_temp:.2f} °C\")\n"
+        "    print(f\"Model R² Quality                 : {bundle['metrics']['r2']:.4f}\")\n"
+        "    print(f\"Expected Estimation Error (RMSE) : ±{bundle['metrics']['rmse']:.2f} °C\")\n"
+        "    print('=' * 65)\n\n"
+        "if __name__ == '__main__':\n"
+        "    main()\n"
+    )
+
+    # README.md
+    if mode == "learning":
+        readme_content = (
+            "# Program 16 — Linear Regression Temperature Prediction\n\n"
+            "## 1. Overview\n"
+            "This practical builds a supervised Multiple Linear Regression model predicting ambient temperature:\n"
+            "- Uses the genuine **UCI Beijing Air Quality Dataset (#501)** (CC BY 4.0).\n"
+            "- Performs rigorous column inspection: explains that while Dew Point (`DEWP`), Pressure (`PRES`), `pm2.5`, and Wind Speed (`Iws`) exist, `PM10` was not recorded by this specific monitoring station.\n"
+            "- Evaluates regression metrics: **Mean Absolute Error (MAE)**, **Mean Squared Error (MSE)**, **Root Mean Squared Error (RMSE)**, and **Coefficient of Determination ($R^2$)**.\n"
+            "- Visualizes predicted vs actual temperature and residual errors.\n"
+            "- Exports model to `model/temperature_linear_reg.joblib` with CLI inference.\n\n"
+            "## 2. Regression Formula Primer\n"
+            "Multiple Linear Regression models the target temperature as a linear combination of predictors:\n"
+            "$$\\hat{y} = \\beta_0 + \\beta_1 X_{\\text{DEWP}} + \\beta_2 X_{\\text{PRES}} + \\beta_3 X_{\\text{pm2.5}} + \\beta_4 X_{\\text{wind}}$$\n"
+            "- **Dew Point (DEWP)** exhibits the strongest positive coefficient because moisture-saturated air holds heat.\n"
+            "- **Atmospheric Pressure (PRES)** typically exhibits a negative coefficient as cold anticyclonic winter air masses create high surface pressures.\n\n"
+            "## 3. Step-by-Step Execution Guide\n\n"
+            "### Step A: Setup & Inspect Dataset Columns\n"
+            "```bash\n"
+            "pip install -r requirements.txt\n"
+            "python column_inspection.py\n"
+            "```\n\n"
+            "### Step B: Train Model & Evaluate Loss Metrics\n"
+            "```bash\n"
+            "python train.py\n"
+            "```\n"
+            "Check the printed evaluation metrics (MAE, RMSE, $R^2$) and generated charts in `output/`:\n"
+            "- `actual_vs_predicted.png`\n"
+            "- `residuals_distribution.png`\n\n"
+            "### Step C: Predict Temperature on New Readings\n"
+            "```bash\n"
+            "python predict.py --dewp -12.0 --pres 1018.0 --pm25 85.0 --wind 3.5\n"
+            "```\n\n"
+            "## 4. Viva Questions and Answers\n"
+            "**Q1: What does the R² (Coefficient of Determination) score represent?**  \n"
+            "A: $R^2 = 1 - \\frac{SS_{\\text{res}}}{SS_{\\text{tot}}}$ measures the proportion of total variance in the target variable that is explained by the regression model. $R^2 = 1.0$ indicates perfect prediction; $R^2 = 0.0$ indicates the model performs no better than guessing the mean.\n\n"
+            "**Q2: What is the physical reason Dew Point is strongly correlated with Temperature?**  \n"
+            "A: Dew point is the temperature to which air must be cooled to become saturated. Because warmer air can hold substantially more moisture than cold air, higher ambient temperatures consistently coincide with higher dew points.\n"
+        )
+    else:
+        readme_content = (
+            "# Program 16 — Linear Regression Temperature Prediction (Exam Mode)\n\n"
+            "## Execution\n"
+            "1. Inspect columns: `python column_inspection.py`\n"
+            "2. Train model: `python train.py`\n"
+            "3. Predict: `python predict.py --dewp -16 --pres 1020 --pm25 120 --wind 2.0`\n\n"
+            "## Viva Q&A\n"
+            "- **Q: Why check dataset columns before training?**  \n"
+            "  A: To avoid assuming columns like PM10 exist when they are absent in the official dataset, ensuring transparency and preventing runtime errors.\n"
+            "- **Q: Difference between MAE and RMSE?**  \n"
+            "  A: MAE takes the linear average of absolute errors ($|y - \\hat{y}|$), while RMSE squares errors before averaging, penalizing large outlier errors more heavily.\n"
+        )
+
+    files["README.md"] = readme_content
+    return files