source.utils.carbon_utils

  1# source/utils/carbon_utils.py
  2"""
  3Utilities for carbon emissions calculations and conversions.
  4"""
  5from pathlib import Path
  6import pandas as pd
  7
  8
  9def kg_co2_to_car_distance(kg_co2: float) -> dict:
 10    """
 11    Convert CO2 emissions to equivalent car distance traveled.
 12
 13    Based on average European car emissions: 120 g CO₂/km (0.12 kg CO₂/km)
 14
 15    Parameters
 16    ----------
 17    kg_co2 : float
 18        CO2 emissions in kilograms
 19
 20    Returns
 21    -------
 22    dict
 23        Dictionary with distance in meters and kilometers
 24    """
 25    # Average European car: 120 g CO₂/km = 0.12 kg CO₂/km
 26    CO2_PER_KM = 0.12
 27
 28    distance_km = kg_co2 / CO2_PER_KM
 29    distance_m = distance_km * 1000
 30
 31    return {"distance_km": distance_km, "distance_m": distance_m}
 32
 33
 34def format_car_distance(kg_co2: float) -> str:
 35    """
 36    Format car distance in a human-readable way.
 37
 38    Parameters
 39    ----------
 40    kg_co2 : float
 41        CO2 emissions in kilograms
 42
 43    Returns
 44    -------
 45    str
 46        Formatted string with appropriate units
 47    """
 48    distances = kg_co2_to_car_distance(kg_co2)
 49
 50    if distances["distance_km"] >= 1:
 51        return f"{distances['distance_km']:.2f} km"
 52    else:
 53        return f"{distances['distance_m']:.1f} m"
 54
 55
 56def format_car_distance_meters_only(kg_co2: float) -> str:
 57    """
 58    Format car distance in meters only (for table display).
 59
 60    Parameters
 61    ----------
 62    kg_co2 : float
 63        CO2 emissions in kilograms
 64
 65    Returns
 66    -------
 67    str
 68        Distance in meters without units
 69    """
 70    distances = kg_co2_to_car_distance(kg_co2)
 71    return f"{distances['distance_m']:.1f}"
 72
 73
 74def get_total_emissions(emissions_csv_path: str) -> dict:
 75    """
 76    Calculate total accumulated CO2 emissions from emissions CSV file.
 77
 78    Parameters
 79    ----------
 80    emissions_csv_path : str or Path
 81        Path to the emissions.csv file generated by CodeCarbon
 82
 83    Returns
 84    -------
 85    dict
 86        Dictionary containing:
 87        - 'total_kg': Total emissions in kg CO₂eq
 88        - 'total_g': Total emissions in g CO₂eq
 89        - 'car_distance_km': Equivalent car distance in km
 90        - 'car_distance_m': Equivalent car distance in m
 91        - 'car_distance_formatted': Human-readable car distance
 92        - 'num_sessions': Number of tracked sessions
 93    """
 94    emissions_file = Path(emissions_csv_path)
 95
 96    if not emissions_file.exists():
 97        return {
 98            "total_kg": 0.0,
 99            "total_g": 0.0,
100            "car_distance_km": 0.0,
101            "car_distance_m": 0.0,
102            "car_distance_formatted": "0 m",
103            "num_sessions": 0,
104        }
105
106    try:
107        df = pd.read_csv(emissions_file)
108
109        if "emissions" not in df.columns or len(df) == 0:
110            return {
111                "total_kg": 0.0,
112                "total_g": 0.0,
113                "car_distance_km": 0.0,
114                "car_distance_m": 0.0,
115                "car_distance_formatted": "0 m",
116                "num_sessions": 0,
117            }
118
119        # Sum all emissions
120        total_kg = df["emissions"].sum()
121        total_g = total_kg * 1000
122
123        # Calculate car distance
124        car_distances = kg_co2_to_car_distance(total_kg)
125
126        return {
127            "total_kg": total_kg,
128            "total_g": total_g,
129            "car_distance_km": car_distances["distance_km"],
130            "car_distance_m": car_distances["distance_m"],
131            "car_distance_formatted": format_car_distance(total_kg),
132            "num_sessions": len(df),
133        }
134
135    except Exception as e:
136        print(f"Error reading emissions file: {e}")
137        return {
138            "total_kg": 0.0,
139            "total_g": 0.0,
140            "car_distance_km": 0.0,
141            "car_distance_m": 0.0,
142            "car_distance_formatted": "0 m",
143            "num_sessions": 0,
144        }
145
146
147def format_total_emissions_display(emissions_csv_path: str) -> str:
148    """
149    Format total emissions for display in UI.
150
151    Parameters
152    ----------
153    emissions_csv_path : str or Path
154        Path to the emissions.csv file
155
156    Returns
157    -------
158    str
159        Formatted HTML string for display
160    """
161    data = get_total_emissions(emissions_csv_path)
162
163    output_string = f"""\
164        <div style="display: flex; justify-content: space-between; \
165            width: 100%;">
166        <span>🌱 <strong>Carbon Footprint Tracker</strong> \
167            <em>(use this interactive demo responsibly)</em></span>
168        <span>🚗 {data['car_distance_formatted']} | 🌍 \
169            {data['total_g']:.2f}g CO₂</span>
170        </div>"""
171    return output_string