Initial deployment

README.md

@@ -1,14 +1,52 @@
 ---
 title: HappySardines
-emoji: 🦀
-colorFrom: yellow
+emoji: 🐟
+colorFrom: blue
 colorTo: blue
 sdk: gradio
-sdk_version: 6.2.0
+sdk_version: 4.44.0
 app_file: app.py
 pinned: false
 license: mit
 short_description: Predict bus crowding levels in Östergötland, Sweden
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🐟 HappySardines
+
+**How packed are buses in Östergötland?**
+
+Drop a pin on the map, pick a time, and find out how crowded buses typically are in that area. Built with ML using historical transit data from Östgötatrafiken.
+
+## How it works
+
+This tool predicts typical bus crowding levels based on:
+- **Location** - Different areas have different ridership patterns
+- **Time** - Rush hours vs. off-peak
+- **Day of week** - Weekdays vs. weekends
+- **Weather** - Temperature, precipitation, etc.
+- **Holidays** - Swedish red days and work-free days
+
+## Data sources
+
+- Historical bus occupancy data from Östgötatrafiken (GTFS-RT, Nov-Dec 2025)
+- Weather forecasts from [Open-Meteo](https://open-meteo.com/)
+- Swedish holiday calendar from [Svenska Dagar API](https://sholiday.faboul.se/)
+
+## Limitations
+
+- Predictions are based on historical patterns, not real-time data
+- Accuracy varies by location and time
+- The model predicts general area crowding, not specific bus lines
+
+## Technical details
+
+- **Model**: XGBoost Classifier trained on ~6M trip records
+- **Features**: Location, time, weather, holidays
+- **Feature Store**: Hopsworks
+- **Framework**: Gradio
+
+## Credits
+
+Built for **KTH ID2223 - Scalable Machine Learning and Deep Learning**
+
+By: Axel & Kajsa

app.py

@@ -0,0 +1,346 @@
+"""
+HappySardines - Bus Occupancy Predictor UI
+
+A Gradio app that predicts how crowded buses are in Östergötland based on
+location, time, weather, and holidays.
+"""
+
+import os
+import gradio as gr
+import folium
+import pandas as pd
+import numpy as np
+from datetime import datetime, timedelta
+
+# Import prediction and data fetching modules
+from predictor import predict_occupancy, predict_occupancy_mock, OCCUPANCY_LABELS
+from weather import get_weather_for_prediction
+from holidays import get_holiday_features
+
+# Try to load model on startup, fall back to mock
+USE_MOCK = os.environ.get("USE_MOCK", "false").lower() == "true"
+
+if not USE_MOCK:
+    try:
+        from predictor import load_model
+        load_model()
+        print("Model loaded successfully - using real predictions")
+    except Exception as e:
+        print(f"Could not load model: {e}")
+        print("Using mock predictions for testing")
+        USE_MOCK = True
+
+# Select predictor function
+_predict_fn = predict_occupancy_mock if USE_MOCK else predict_occupancy
+
+# Default map center: Linköping
+DEFAULT_LAT = 58.4108
+DEFAULT_LON = 15.6214
+DEFAULT_ZOOM = 12
+
+# Östergötland bounds (roughly)
+BOUNDS = {
+    "min_lat": 57.8,
+    "max_lat": 58.9,
+    "min_lon": 14.5,
+    "max_lon": 16.8
+}
+
+
+def create_map(lat=DEFAULT_LAT, lon=DEFAULT_LON, marker_lat=None, marker_lon=None):
+    """Create a Folium map with optional marker."""
+    m = folium.Map(
+        location=[lat, lon],
+        zoom_start=DEFAULT_ZOOM,
+        tiles="CartoDB positron"
+    )
+
+    # Add click instruction
+    if marker_lat is None:
+        folium.Marker(
+            [lat, lon],
+            popup="Click anywhere on the map to select a location",
+            icon=folium.Icon(color="gray", icon="info-sign")
+        ).add_to(m)
+    else:
+        # Add user's selected marker
+        folium.Marker(
+            [marker_lat, marker_lon],
+            popup=f"Selected: {marker_lat:.4f}, {marker_lon:.4f}",
+            icon=folium.Icon(color="blue", icon="map-marker", prefix="fa")
+        ).add_to(m)
+
+    return m._repr_html_()
+
+
+def parse_map_click(map_html, click_data):
+    """Parse click coordinates from map interaction."""
+    # This is a placeholder - Gradio's map handling varies by version
+    # We'll use a simpler approach with coordinate inputs
+    return None, None
+
+
+def make_prediction(lat, lon, date_choice, hour):
+    """
+    Make occupancy prediction for given inputs.
+
+    Returns formatted result HTML.
+    """
+    if lat is None or lon is None:
+        return create_result_card(
+            "Please select a location",
+            "Click on the map or enter coordinates to get a prediction.",
+            "gray",
+            None
+        )
+
+    # Validate coordinates are in Östergötland
+    if not (BOUNDS["min_lat"] <= lat <= BOUNDS["max_lat"] and
+            BOUNDS["min_lon"] <= lon <= BOUNDS["max_lon"]):
+        return create_result_card(
+            "Location outside coverage area",
+            "Please select a location within Östergötland.",
+            "gray",
+            None
+        )
+
+    # Determine date
+    today = datetime.now().date()
+    if date_choice == "Today":
+        selected_date = today
+    else:  # Tomorrow
+        selected_date = today + timedelta(days=1)
+
+    selected_datetime = datetime.combine(selected_date, datetime.min.time().replace(hour=int(hour)))
+
+    try:
+        # Get weather forecast
+        weather = get_weather_for_prediction(lat, lon, selected_datetime)
+
+        # Get holiday features
+        holidays = get_holiday_features(selected_datetime)
+
+        # Make prediction
+        prediction, confidence, probabilities = _predict_fn(
+            lat=lat,
+            lon=lon,
+            hour=int(hour),
+            day_of_week=selected_date.weekday(),
+            weather=weather,
+            holidays=holidays
+        )
+
+        # Format result
+        label_info = OCCUPANCY_LABELS[prediction]
+
+        # Build context string
+        day_name = selected_date.strftime("%A")
+        day_type = "Holiday" if holidays.get("is_red_day") else ("Work-free day" if holidays.get("is_work_free") else "Regular workday")
+        temp = weather.get("temperature_2m", "?")
+
+        context = f"{temp:.0f}°C  •  {day_name}  •  {day_type}"
+
+        return create_result_card(
+            label_info["label"],
+            label_info["message"],
+            label_info["color"],
+            context,
+            confidence
+        )
+
+    except Exception as e:
+        return create_result_card(
+            "Prediction failed",
+            f"Error: {str(e)}",
+            "gray",
+            None
+        )
+
+
+def create_result_card(title, message, color, context, confidence=None):
+    """Create HTML result card."""
+    color_map = {
+        "green": "#22c55e",
+        "yellow": "#eab308",
+        "orange": "#f97316",
+        "red": "#ef4444",
+        "gray": "#6b7280"
+    }
+    bg_color = color_map.get(color, "#6b7280")
+
+    confidence_html = ""
+    if confidence is not None:
+        confidence_html = f'<div style="font-size: 0.9em; opacity: 0.8;">Confidence: {confidence:.0%}</div>'
+
+    context_html = ""
+    if context:
+        context_html = f'<div style="margin-top: 15px; font-size: 0.9em; opacity: 0.7;">{context}</div>'
+
+    return f"""
+    <div style="
+        background: linear-gradient(135deg, {bg_color}22, {bg_color}11);
+        border-left: 4px solid {bg_color};
+        border-radius: 12px;
+        padding: 24px;
+        margin: 10px 0;
+    ">
+        <div style="
+            font-size: 1.4em;
+            font-weight: 600;
+            color: {bg_color};
+            margin-bottom: 8px;
+        ">{title}</div>
+        <div style="
+            font-size: 1.1em;
+            color: #374151;
+            line-height: 1.5;
+        ">{message}</div>
+        {confidence_html}
+        {context_html}
+    </div>
+    """
+
+
+def update_map_with_marker(lat, lon):
+    """Update map with new marker position."""
+    if lat is not None and lon is not None:
+        return create_map(lat, lon, lat, lon)
+    return create_map()
+
+
+# Custom CSS
+CUSTOM_CSS = """
+.main-title {
+    text-align: center;
+    margin-bottom: 0;
+}
+.subtitle {
+    text-align: center;
+    color: #6b7280;
+    margin-top: 5px;
+    margin-bottom: 20px;
+}
+"""
+
+# Build Gradio interface
+with gr.Blocks(title="HappySardines") as app:
+
+    # Header
+    gr.Markdown("# 🐟 HappySardines", elem_classes=["main-title"])
+    gr.Markdown("*How packed are buses in Östergötland?*", elem_classes=["subtitle"])
+
+    with gr.Row():
+        # Left column: Map
+        with gr.Column(scale=2):
+            gr.Markdown("### Select Location")
+            gr.Markdown("Enter coordinates or use the map as reference:")
+
+            map_display = gr.HTML(value=create_map())
+
+            with gr.Row():
+                lat_input = gr.Number(
+                    label="Latitude",
+                    value=DEFAULT_LAT,
+                    precision=6,
+                    minimum=BOUNDS["min_lat"],
+                    maximum=BOUNDS["max_lat"]
+                )
+                lon_input = gr.Number(
+                    label="Longitude",
+                    value=DEFAULT_LON,
+                    precision=6,
+                    minimum=BOUNDS["min_lon"],
+                    maximum=BOUNDS["max_lon"]
+                )
+
+            update_map_btn = gr.Button("Update Map", variant="secondary", size="sm")
+
+        # Right column: Controls
+        with gr.Column(scale=1):
+            gr.Markdown("### When?")
+
+            date_choice = gr.Radio(
+                choices=["Today", "Tomorrow"],
+                value="Today",
+                label="Date"
+            )
+
+            hour_slider = gr.Slider(
+                minimum=5,
+                maximum=23,
+                value=8,
+                step=1,
+                label="Hour",
+                info="Select time of day (24h format)"
+            )
+
+            # Show selected time
+            time_display = gr.Markdown("**Selected: 08:00**")
+
+            predict_btn = gr.Button("🔮 Predict Crowding", variant="primary", size="lg")
+
+    # Result section
+    gr.Markdown("### Prediction")
+    result_display = gr.HTML(
+        value=create_result_card(
+            "Select location and time",
+            "Then click 'Predict Crowding' to see the forecast.",
+            "gray",
+            None
+        )
+    )
+
+    # About section
+    with gr.Accordion("About this tool", open=False):
+        gr.Markdown("""
+        **How it works:**
+
+        This tool predicts typical bus crowding levels based on:
+        - **Location** - Different areas have different ridership patterns
+        - **Time** - Rush hours vs. off-peak
+        - **Day of week** - Weekdays vs. weekends
+        - **Weather** - Temperature, precipitation, etc.
+        - **Holidays** - Swedish red days and work-free days
+
+        **Data sources:**
+        - Historical bus occupancy data from Östgötatrafiken (GTFS-RT, Nov-Dec 2025)
+        - Weather forecasts from Open-Meteo
+        - Swedish holiday calendar from Svenska Dagar API
+
+        **Limitations:**
+        - Predictions are based on historical patterns, not real-time data
+        - Accuracy varies by location and time
+        - The model predicts general area crowding, not specific bus lines
+
+        **Built for KTH ID2223 - Scalable Machine Learning and Deep Learning**
+        """)
+
+    # Event handlers
+    def update_time_display(hour):
+        return f"**Selected: {int(hour):02d}:00**"
+
+    hour_slider.change(
+        fn=update_time_display,
+        inputs=[hour_slider],
+        outputs=[time_display]
+    )
+
+    update_map_btn.click(
+        fn=update_map_with_marker,
+        inputs=[lat_input, lon_input],
+        outputs=[map_display]
+    )
+
+    predict_btn.click(
+        fn=make_prediction,
+        inputs=[lat_input, lon_input, date_choice, hour_slider],
+        outputs=[result_display]
+    )
+
+
+# For local testing
+if __name__ == "__main__":
+    app.launch(
+        theme=gr.themes.Soft(primary_hue="blue", secondary_hue="cyan"),
+        css=CUSTOM_CSS
+    )

holidays.py

@@ -0,0 +1,68 @@
+"""
+Swedish holiday lookup for HappySardines predictions.
+
+Uses Svenska Dagar API to get holiday information.
+"""
+
+import requests
+from datetime import datetime
+
+# Svenska Dagar API
+SVENSKA_DAGAR_API_URL = "https://sholiday.faboul.se/dagar/v2.1"
+
+
+def get_holiday_features(target_datetime: datetime) -> dict:
+    """
+    Get holiday features for a specific date.
+
+    Args:
+        target_datetime: Target datetime
+
+    Returns:
+        Dict with holiday features for the model
+    """
+    try:
+        date = target_datetime.date()
+        url = f"{SVENSKA_DAGAR_API_URL}/{date.year}/{date.month:02d}/{date.day:02d}"
+
+        response = requests.get(url, timeout=30)
+
+        if response.status_code != 200:
+            print(f"Holiday API error: {response.status_code}")
+            return _default_holidays(target_datetime)
+
+        data = response.json()
+        days = data.get("dagar", [])
+
+        if not days:
+            return _default_holidays(target_datetime)
+
+        day = days[0]
+
+        return {
+            "is_work_free": day.get("arbetsfri dag") == "Ja",
+            "is_red_day": day.get("röd dag") == "Ja",
+            "is_day_before_holiday": day.get("dag före arbetsfri helgdag") == "Ja",
+            "holiday_name": day.get("helgdag"),
+            "day_of_week": int(day.get("dag i vecka", target_datetime.weekday() + 1)) - 1,  # Convert to 0-indexed
+        }
+
+    except Exception as e:
+        print(f"Error fetching holiday data: {e}")
+        return _default_holidays(target_datetime)
+
+
+def _default_holidays(target_datetime: datetime) -> dict:
+    """Return default holiday values based on day of week."""
+    day_of_week = target_datetime.weekday()
+
+    # Weekends are typically work-free
+    is_weekend = day_of_week >= 5
+
+    return {
+        "is_work_free": is_weekend,
+        "is_red_day": day_of_week == 6,  # Sundays are red days
+        "is_day_before_holiday": False,
+        "holiday_name": None,
+        "day_of_week": day_of_week,
+    }

predictor.py

@@ -0,0 +1,222 @@
+"""
+Model loading and prediction logic for HappySardines.
+
+Loads the XGBoost model from Hopsworks Model Registry and makes predictions.
+"""
+
+import os
+import numpy as np
+import pandas as pd
+
+# Global model cache
+_model = None
+_model_loaded = False
+
+# Occupancy class labels with display info
+OCCUPANCY_LABELS = {
+    0: {
+        "label": "Empty",
+        "message": "Plenty of room - pick any seat!",
+        "color": "green",
+        "icon": "🟢"
+    },
+    1: {
+        "label": "Many seats available",
+        "message": "Lots of seats to choose from.",
+        "color": "green",
+        "icon": "🟢"
+    },
+    2: {
+        "label": "Few seats available",
+        "message": "Some seats left - you might need to look around.",
+        "color": "yellow",
+        "icon": "🟡"
+    },
+    3: {
+        "label": "Standing room only",
+        "message": "Expect to stand - pack your patience!",
+        "color": "orange",
+        "icon": "🟠"
+    },
+    4: {
+        "label": "Crushed standing",
+        "message": "Very crowded - consider waiting for the next one.",
+        "color": "red",
+        "icon": "🔴"
+    },
+    5: {
+        "label": "Full",
+        "message": "Bus is full - you may not get on.",
+        "color": "red",
+        "icon": "🔴"
+    },
+    6: {
+        "label": "Not accepting passengers",
+        "message": "Bus is not accepting passengers.",
+        "color": "gray",
+        "icon": "⚫"
+    }
+}
+
+# Feature order expected by the model
+# Must match training pipeline exactly
+FEATURE_ORDER = [
+    "avg_speed",
+    "max_speed",
+    "speed_std",
+    "n_positions",
+    "lat_mean",
+    "lon_mean",
+    "hour",
+    "day_of_week",
+    "temperature_2m",
+    "precipitation",
+    "cloud_cover",
+    "wind_speed_10m",
+    "is_work_free",
+    "is_red_day",
+    "is_day_before_holiday",
+]
+
+# Default values for vehicle features (we don't have real-time vehicle data)
+# These are approximate averages from the training data
+DEFAULT_VEHICLE_FEATURES = {
+    "avg_speed": 20.0,      # typical urban bus speed (km/h)
+    "max_speed": 45.0,      # typical max speed
+    "speed_std": 12.0,      # typical speed variation
+    "n_positions": 30,      # typical GPS points per trip window
+}
+
+
+def load_model():
+    """
+    Load model from Hopsworks Model Registry.
+
+    Caches the model globally for reuse.
+    """
+    global _model, _model_loaded
+
+    if _model_loaded:
+        return _model
+
+    try:
+        import hopsworks
+        from xgboost import XGBClassifier
+
+        print("Connecting to Hopsworks...")
+        project = hopsworks.login()
+        mr = project.get_model_registry()
+
+        print("Fetching model from registry...")
+        model_entry = mr.get_model("occupancy_xgboost_model", version=None)  # Latest version
+
+        print(f"Downloading model version {model_entry.version}...")
+        model_dir = model_entry.download()
+
+        print("Loading XGBoost model...")
+        model = XGBClassifier()
+        model.load_model(os.path.join(model_dir, "model.json"))
+
+        _model = model
+        _model_loaded = True
+        print("Model loaded successfully!")
+
+        return model
+
+    except Exception as e:
+        print(f"Error loading model: {e}")
+        raise
+
+
+def predict_occupancy(lat, lon, hour, day_of_week, weather, holidays):
+    """
+    Predict occupancy for given inputs.
+
+    Args:
+        lat: Latitude
+        lon: Longitude
+        hour: Hour of day (0-23)
+        day_of_week: Day of week (0=Monday, 6=Sunday)
+        weather: Dict with temperature_2m, precipitation, cloud_cover, wind_speed_10m
+        holidays: Dict with is_work_free, is_red_day, is_day_before_holiday
+
+    Returns:
+        Tuple of (predicted_class, confidence, all_probabilities)
+    """
+    model = load_model()
+
+    # Assemble feature vector
+    features = {
+        # Vehicle features - use defaults
+        "avg_speed": DEFAULT_VEHICLE_FEATURES["avg_speed"],
+        "max_speed": DEFAULT_VEHICLE_FEATURES["max_speed"],
+        "speed_std": DEFAULT_VEHICLE_FEATURES["speed_std"],
+        "n_positions": DEFAULT_VEHICLE_FEATURES["n_positions"],
+
+        # Location
+        "lat_mean": lat,
+        "lon_mean": lon,
+
+        # Time
+        "hour": hour,
+        "day_of_week": day_of_week,
+
+        # Weather
+        "temperature_2m": weather.get("temperature_2m", 10.0),
+        "precipitation": weather.get("precipitation", 0.0),
+        "cloud_cover": weather.get("cloud_cover", 50.0),
+        "wind_speed_10m": weather.get("wind_speed_10m", 5.0),
+
+        # Holidays (convert bool to int)
+        "is_work_free": int(holidays.get("is_work_free", False)),
+        "is_red_day": int(holidays.get("is_red_day", False)),
+        "is_day_before_holiday": int(holidays.get("is_day_before_holiday", False)),
+    }
+
+    # Create DataFrame with correct feature order
+    X = pd.DataFrame([features])[FEATURE_ORDER]
+
+    # Get prediction probabilities
+    probabilities = model.predict_proba(X)[0]
+
+    # Get predicted class (highest probability)
+    predicted_class = int(np.argmax(probabilities))
+    confidence = float(probabilities[predicted_class])
+
+    return predicted_class, confidence, probabilities.tolist()
+
+
+# Mock prediction for testing without Hopsworks
+def predict_occupancy_mock(lat, lon, hour, day_of_week, weather, holidays):
+    """
+    Mock prediction for testing UI without model.
+    """
+    # Simple heuristic based on time
+    if 7 <= hour <= 9 or 16 <= hour <= 18:
+        # Rush hour
+        if holidays.get("is_work_free") or holidays.get("is_red_day"):
+            predicted_class = 1  # Holiday rush hour = many seats
+        else:
+            predicted_class = 2 if hour < 8 or hour > 17 else 3  # Peak = standing
+    elif 10 <= hour <= 15:
+        predicted_class = 1  # Midday = many seats
+    else:
+        predicted_class = 0  # Early/late = empty
+
+    # Mock probabilities
+    probabilities = [0.1] * 7
+    probabilities[predicted_class] = 0.6
+    confidence = 0.6
+
+    return predicted_class, confidence, probabilities
+
+
+# For testing - use mock if model not available
+def get_predictor():
+    """Get the appropriate predictor function."""
+    try:
+        load_model()
+        return predict_occupancy
+    except Exception as e:
+        print(f"Using mock predictor: {e}")
+        return predict_occupancy_mock

requirements.txt

@@ -0,0 +1,8 @@
+gradio>=4.0.0
+folium>=0.15.0
+hopsworks
+xgboost>=2.0.0
+pandas
+numpy
+requests
+python-dotenv

weather.py

@@ -0,0 +1,106 @@
+"""
+Weather forecast fetching for HappySardines predictions.
+
+Uses Open-Meteo API to get weather forecasts.
+"""
+
+import requests
+from datetime import datetime
+
+# Open-Meteo API
+OPENMETEO_FORECAST_URL = "https://api.open-meteo.com/v1/forecast"
+
+# Weather variables needed for prediction
+WEATHER_VARIABLES = [
+    "temperature_2m",
+    "precipitation",
+    "cloud_cover",
+    "wind_speed_10m",
+]
+
+
+def get_weather_for_prediction(lat: float, lon: float, target_datetime: datetime) -> dict:
+    """
+    Get weather forecast for a specific location and time.
+
+    Args:
+        lat: Latitude
+        lon: Longitude
+        target_datetime: Target datetime for prediction
+
+    Returns:
+        Dict with weather features for the model
+    """
+    try:
+        # Determine if we need forecast or recent past
+        now = datetime.now()
+        days_ahead = (target_datetime.date() - now.date()).days
+
+        # Open-Meteo provides up to 16 days forecast
+        if days_ahead > 16:
+            print(f"Warning: Date too far in future, using defaults")
+            return _default_weather()
+
+        params = {
+            "latitude": lat,
+            "longitude": lon,
+            "hourly": ",".join(WEATHER_VARIABLES),
+            "timezone": "Europe/Stockholm",
+            "forecast_days": max(2, days_ahead + 1),  # At least today + tomorrow
+        }
+
+        # Include past days if looking at today
+        if days_ahead <= 0:
+            params["past_days"] = 1
+
+        response = requests.get(OPENMETEO_FORECAST_URL, params=params, timeout=30)
+
+        if response.status_code != 200:
+            print(f"Weather API error: {response.status_code}")
+            return _default_weather()
+
+        data = response.json()
+        hourly = data.get("hourly", {})
+
+        if not hourly:
+            return _default_weather()
+
+        # Find the matching hour in the response
+        times = hourly.get("time", [])
+        target_str = target_datetime.strftime("%Y-%m-%dT%H:00")
+
+        try:
+            idx = times.index(target_str)
+        except ValueError:
+            # Try to find closest hour
+            target_hour = target_datetime.hour
+            target_date = target_datetime.strftime("%Y-%m-%d")
+
+            for i, t in enumerate(times):
+                if t.startswith(target_date) and f"T{target_hour:02d}:" in t:
+                    idx = i
+                    break
+            else:
+                print(f"Could not find matching time for {target_datetime}")
+                return _default_weather()
+
+        return {
+            "temperature_2m": hourly.get("temperature_2m", [None])[idx] or 10.0,
+            "precipitation": hourly.get("precipitation", [None])[idx] or 0.0,
+            "cloud_cover": hourly.get("cloud_cover", [None])[idx] or 50.0,
+            "wind_speed_10m": hourly.get("wind_speed_10m", [None])[idx] or 5.0,
+        }
+
+    except Exception as e:
+        print(f"Error fetching weather: {e}")
+        return _default_weather()
+
+
+def _default_weather() -> dict:
+    """Return default weather values."""
+    return {
+        "temperature_2m": 10.0,  # Typical Swedish temp
+        "precipitation": 0.0,
+        "cloud_cover": 50.0,
+        "wind_speed_10m": 5.0,
+    }