app.sections.model_training

  1#!/usr/bin/env python3
  2# -*- coding: utf-8 -*-
  3"""
  4Model Training Interface for Gradio Application.
  5
  6This module provides the Gradio UI components for training the garbage
  7classification model with custom hyperparameters. It includes real-time
  8progress tracking, carbon emissions monitoring, and training history
  9visualization.
 10
 11The interface allows users to:
 12- Configure training hyperparameters (batch size, learning rate, epochs)
 13- Track carbon emissions during training
 14- View training results and metrics
 15- Review training history with environmental impact metrics
 16
 17Notes
 18-----
 19Training emissions are automatically tracked using CodeCarbon and stored
 20in a CSV file alongside the model checkpoint. The interface displays
 21emissions as both absolute values (kg CO₂eq) and relative comparisons
 22(equivalent car driving distance).
 23"""
 24__docformat__ = "numpy"
 25
 26import gradio as gr
 27from source.train import train_model
 28from source.utils import config as cfg
 29from source.utils.carbon_utils import (
 30    format_car_distance_meters_only,
 31    format_total_emissions_display,
 32)
 33from pathlib import Path
 34import pandas as pd
 35
 36
 37def get_emissions_path():
 38    """
 39    Get the path to the emissions CSV file.
 40
 41    Returns
 42    -------
 43    pathlib.Path
 44        Path object pointing to the emissions.csv file in the model directory.
 45
 46    Notes
 47    -----
 48    The emissions file is stored in the same directory as the trained model
 49    checkpoint, as defined in the global configuration.
 50    """
 51    return Path(cfg.MODEL_PATH).parent / "emissions.csv"
 52
 53
 54def load_emissions_history():
 55    """
 56    Load and format emissions history from CSV file.
 57
 58    Returns
 59    -------
 60    pd.DataFrame
 61        DataFrame containing the last 10 training sessions with formatted
 62        columns including timestamp, duration, emissions, energy consumption,
 63        and car distance equivalent. Returns error/info message if file
 64        cannot be loaded or doesn't exist.
 65
 66    Notes
 67    -----
 68    The function performs the following transformations:
 69    - Selects relevant columns (timestamp, duration, emissions, energy)
 70    - Adds units to column names for clarity
 71    - Calculates car distance equivalent in meters
 72    - Formats numeric values with appropriate precision
 73    - Returns only the most recent 10 training sessions
 74
 75    If the emissions file doesn't exist or cannot be read, returns a
 76    DataFrame with an appropriate message.
 77    """
 78    emissions_file = get_emissions_path()
 79    if emissions_file.exists():
 80        try:
 81            df = pd.read_csv(emissions_file)
 82
 83            # Select and rename columns with units
 84            column_mapping = {
 85                "timestamp": "Timestamp",
 86                "duration": "Duration (s)",
 87                "emissions": "Emissions (kg CO₂eq)",
 88                "energy_consumed": "Energy (kWh)",
 89            }
 90
 91            # Get only available columns
 92            available_cols = [
 93                col for col in column_mapping.keys() if col in df.columns
 94            ]
 95            df_filtered = df[available_cols].copy()
 96
 97            # Rename columns to include units
 98            df_filtered.rename(
 99                columns={col: column_mapping[col] for col in available_cols},
100                inplace=True,
101            )
102
103            # Add car distance column if emissions exist
104            if "Emissions (kg CO₂eq)" in df_filtered.columns:
105                df_filtered["Car Distance Equivalent (m)"] = df_filtered[
106                    "Emissions (kg CO₂eq)"
107                ].apply(
108                    lambda x: (
109                        format_car_distance_meters_only(x)
110                        if pd.notna(x) else "N/A"
111                    )
112                )
113
114            # Format numeric columns
115            if "Duration (s)" in df_filtered.columns:
116                df_filtered["Duration (s)"] = \
117                    df_filtered["Duration (s)"].round(2)
118            if "Emissions (kg CO₂eq)" in df_filtered.columns:
119                df_filtered["Emissions (kg CO₂eq)"] = df_filtered[
120                    "Emissions (kg CO₂eq)"
121                ].apply(lambda x: f"{x:.6f}" if pd.notna(x) else "N/A")
122            if "Energy (kWh)" in df_filtered.columns:
123                df_filtered["Energy (kWh)"] = \
124                    df_filtered["Energy (kWh)"].round(4)
125
126            # Return last 10 trainings
127            return df_filtered.tail(10)
128
129        except Exception as e:
130            return pd.DataFrame(
131                {"Error": [f"Could not load emissions data: {str(e)}"]}
132            )
133    return pd.DataFrame({"Info": ["No training history yet"]})
134
135
136def run_training(
137    batch_size, learning_rate, max_epochs, track_carbon, progress=gr.Progress()
138):
139    """
140    Execute model training with specified hyperparameters.
141
142    This function serves as the Gradio wrapper for the training process,
143    handling progress updates, result formatting, and UI state management.
144
145    Parameters
146    ----------
147    batch_size : int
148        Number of samples per training batch. Larger values use more memory
149        but may improve training stability.
150    learning_rate : float
151        Step size for the optimizer (e.g., 0.001, 1e-4). Controls how much
152        model weights are updated during training.
153    max_epochs : int
154        Maximum number of complete passes through the training dataset.
155    track_carbon : bool
156        Whether to track and record carbon emissions during training using
157        CodeCarbon.
158    progress : gr.Progress, optional
159        Gradio progress tracker for updating the UI progress bar and status
160        messages.
161
162    Returns
163    -------
164    tuple of (str, pd.DataFrame, str)
165        - status_message : Markdown-formatted string with training results,
166          including metrics and carbon footprint information
167        - emissions_history : Updated DataFrame with training history
168        - carbon_display : Updated HTML string for the carbon counter display
169
170    Notes
171    -----
172    The function includes a progress callback that updates the Gradio UI
173    in real-time during training. Training results include:
174    - Training and validation accuracy
175    - Model checkpoint location
176    - Loss curves location
177    - Carbon emissions (if tracked)
178    - Car distance equivalent
179
180    If training fails, returns an error message while preserving the
181    existing emissions history and carbon display.
182
183    See Also
184    --------
185    source.train.train_model : Core training function
186    load_emissions_history : Load training history from CSV
187    """
188    status_messages = []
189
190    def progress_callback(message):
191        """
192        Callback to update progress in Gradio UI.
193
194        Parameters
195        ----------
196        message : str
197            Progress message to display
198        """
199        status_messages.append(message)
200        progress(len(status_messages) / (max_epochs + 3), desc=message)
201
202    try:
203        # Run training
204        result = train_model(
205            batch_size=int(batch_size),
206            lr=float(learning_rate),
207            max_epochs=int(max_epochs),
208            track_carbon=track_carbon,
209            progress_callback=progress_callback,
210        )
211
212        # Format metrics
213        metrics_info = ""
214        if result.get("metrics"):
215            metrics = result["metrics"]
216            metrics_info = "\n\n### 📊 Training Results\n"
217            if metrics.get("train_acc") is not None:
218                metrics_info += (
219                    f"- **Train Accuracy:** {metrics['train_acc']*100:.2f}%\n"
220                )
221            if metrics.get("val_acc") is not None:
222                metrics_info += (
223                    f"- **Validation Accuracy:** \
224                        {metrics['val_acc']*100:.2f}%\n"
225                )
226
227        # Format emissions
228        emissions_info = ""
229        if result.get("emissions"):
230            emissions_info = (
231                f"\n\n### 🌍 Carbon Footprint\n"
232                f"- **Emissions:** \
233                    {result['emissions']['emissions_g']:.2f}g CO₂eq "
234                f"({result['emissions']['emissions_kg']:.6f} kg)\n"
235                f"- **🚗 Car equivalent:** \
236                    {result['emissions']['car_distance_formatted']} driven\n"
237            )
238            if result["emissions"]["duration_seconds"]:
239                emissions_info += (
240                    f"- **Duration:** \
241                        {result['emissions']['duration_seconds']:.1f}s\n"
242                )
243
244            emissions_info += (
245                "\n*Based on average European car emissions of 120g CO₂/km*"
246            )
247
248        final_message = (
249            f"✅ **Training Complete!**\n\n"
250            f"### Training Configuration\n"
251            f"- **Batch Size:** {batch_size}\n"
252            f"- **Learning Rate:** {learning_rate}\n"
253            f"- **Epochs:** {max_epochs}\n"
254            f"{metrics_info}"
255            f"\n### Output\n"
256            f"- **Model saved at:** `{cfg.MODEL_PATH}`\n"
257            f"- **Loss curves saved at:** `{cfg.LOSS_CURVES_PATH}`"
258            f"{emissions_info}"
259        )
260
261        # Load updated emissions history
262        emissions_df = load_emissions_history()
263
264        # Update carbon display
265        carbon_text = format_total_emissions_display(get_emissions_path())
266
267        return final_message, emissions_df, carbon_text
268
269    except Exception as e:
270        error_msg = f"❌ **Training Failed!**\n\n**Error:** {str(e)}"
271        carbon_text = format_total_emissions_display(get_emissions_path())
272        return error_msg, load_emissions_history(), carbon_text
273
274
275def model_training_tab(carbon_display):
276    """
277    Create the Training Interface UI section.
278
279    Builds a Gradio interface for configuring and launching model training,
280    with real-time progress tracking, emissions monitoring, and training
281    history visualization.
282
283    Parameters
284    ----------
285    carbon_display : gr.HTML
286        The carbon counter display component to update after training
287        completes. This component shows cumulative emissions across all
288        training sessions.
289
290    Returns
291    -------
292    list of gr.Component
293        List containing [output, emissions_table] components for potential
294        external reference.
295
296    Notes
297    -----
298    The interface is organized into sections:
299
300    1. **Hyperparameters Panel:**
301       - Batch size slider (8-128)
302       - Learning rate input
303       - Max epochs slider (1-100)
304       - Carbon tracking checkbox
305       - Start training button
306
307    2. **Status Panel:**
308       - Real-time training progress
309       - Training results and metrics
310       - Carbon footprint statistics
311
312    3. **History Panel:**
313       - Recent training sessions table
314       - Emissions and energy consumption
315       - Car distance equivalents
316       - Refresh button
317
318    The carbon tracking uses CodeCarbon and compares emissions to average
319    European car travel (120g CO₂/km).
320
321    Examples
322    --------
323    >>> with gr.Blocks() as demo:
324    ...     carbon_display = gr.HTML()
325    ...     model_training_tab(carbon_display)
326    """
327    with gr.Column():
328        gr.Markdown("### ⚙️ Model Training Interface")
329        gr.Markdown(
330            "Configure and train the garbage \
331                classification model with custom hyperparameters. "
332            "Carbon emissions are tracked \
333                automatically and compared to car travel distance."
334        )
335
336        with gr.Row():
337            with gr.Column(scale=1):
338                gr.Markdown("#### Training Hyperparameters")
339
340                batch_size = gr.Slider(
341                    minimum=8,
342                    maximum=128,
343                    value=32,
344                    step=8,
345                    label="Batch Size",
346                    info="Number of samples per training batch",
347                )
348
349                learning_rate = gr.Number(
350                    value=1e-3,
351                    label="Learning Rate",
352                    info="Step size for optimizer (e.g., 0.001, 1e-4)",
353                )
354
355                max_epochs = gr.Slider(
356                    minimum=1,
357                    maximum=100,
358                    value=cfg.MAX_EPOCHS,
359                    step=1,
360                    label="Max Epochs",
361                    info="Number of training epochs",
362                )
363
364                track_carbon = gr.Checkbox(
365                    value=True,
366                    label="🌍 Track Carbon Emissions",
367                    info="Monitor environmental impact during training",
368                )
369
370                train_btn = gr.Button(
371                    "🚀 Start Training", variant="primary", size="lg"
372                )
373
374            with gr.Column(scale=1):
375                gr.Markdown("#### Training Status")
376                output = gr.Markdown(
377                    "Click 'Start Training' to begin...",
378                    label="Status", height=400
379                )
380
381        gr.Markdown("---")
382        gr.Markdown("#### 📊 Training History & Carbon Footprint")
383
384        # Load initial history
385        initial_history = load_emissions_history()
386
387        emissions_table = gr.Dataframe(
388            value=initial_history,
389            label="Recent Training Sessions",
390            interactive=False,
391            wrap=True,
392        )
393
394        refresh_btn = gr.Button("🔄 Refresh History", size="sm")
395
396        gr.Markdown("---")
397        gr.Markdown(
398            "**🚗 Car Distance Comparison:** Based on average \
399                European car emissions (120g CO₂/km). "
400            "Carbon Footprint was calculated using CodeCarbon. "
401            "Learn more about CodeCarbon at [codecarbon.io]\
402                (https://codecarbon.io/)"
403        )
404
405        # Connect button to training function - now updates carbon display too
406        train_btn.click(
407            fn=run_training,
408            inputs=[batch_size, learning_rate, max_epochs, track_carbon],
409            outputs=[output, emissions_table, carbon_display],
410        )
411
412        # Refresh emissions history independently
413        refresh_btn.click(
414            fn=load_emissions_history, inputs=[], outputs=emissions_table
415        )
416
417    return [output, emissions_table]