Add global download workflow and fix wave variable mapping

app.py

@@ -1,5 +1,7 @@
 import os
+import io
 import json
+import tempfile
 import datetime as dt
 from typing import List, Optional, Tuple, Union
 
@@ -19,11 +21,11 @@ WAVE_MODELS = {
 }
 
 WAVE_VARIABLES = {
-    "SWH": ("Significant wave height", "m"),
-    "MWD": ("Mean wave direction", "° (true)"),
-    "MWP": ("Mean wave period", "s"),
-    "MP2": ("Mean zero-crossing wave period", "s"),
-    "PP1D": ("Peak wave period", "s"),
+    "swh": ("Significant wave height", "m"),
+    "mwd": ("Mean wave direction", "° (true)"),
+    "mwp": ("Mean wave period", "s"),
+    "mp2": ("Mean zero-crossing wave period", "s"),
+    "pp1d": ("Peak wave period", "s"),
 }
 
 
@@ -80,6 +82,25 @@ def build_members_list(raw: str, model: str) -> Optional[List[int]]:
     return members or None
 
 
+def make_alias(name: str) -> str:
+    """Create a lowercase alias compatible with the API response."""
+    cleaned = "".join(ch.lower() if ch.isalnum() else "_" for ch in name)
+    cleaned = "_".join(part for part in cleaned.split("_") if part)
+    return cleaned or "value"
+
+
+def parse_variable_list(raw: str) -> List[str]:
+    """Split a comma/newline separated list of variable names."""
+    if not raw:
+        return []
+    parts = []
+    for chunk in raw.replace("\n", ",").split(","):
+        chunk = chunk.strip()
+        if chunk:
+            parts.append(chunk)
+    return parts
+
+
 def decode_json_response(response: requests.Response) -> List[dict]:
     """Parse GribStream JSON/NDJSON responses into a list of dictionaries."""
     try:
@@ -102,49 +123,74 @@ def decode_json_response(response: requests.Response) -> List[dict]:
 def fetch_wave_history(
     token: str,
     model: str,
-    variable: str,
-    latitude: float,
-    longitude: float,
-    from_time: str,
-    until_time: str,
+    variables: List[dict],
+    *,
+    from_time: Optional[str] = None,
+    until_time: Optional[str] = None,
+    times_list: Optional[List[str]] = None,
     min_horizon: int,
     max_horizon: int,
+    coordinates: Optional[List[dict]] = None,
+    grid: Optional[dict] = None,
     members: Optional[List[int]] = None,
-) -> Tuple[pd.DataFrame, str]:
-    """Call GribStream's history endpoint and return a dataframe + alias."""
+    accept: str = "application/ndjson",
+    timeout: int = 120,
+) -> pd.DataFrame:
+    """Call GribStream's history endpoint and return a dataframe."""
+    if not variables:
+        raise ValueError("At least one variable must be specified.")
+
+    if not coordinates and not grid:
+        raise ValueError("Provide either coordinates or a grid definition.")
+
+    if from_time and until_time:
+        if until_time <= from_time:
+            raise ValueError("until_time must be after from_time.")
+    elif not times_list:
+        raise ValueError("Provide either a time range or an explicit times list.")
+
     url = f"{API_BASE_URL}/{model}/history"
     headers = {
         "Authorization": f"Bearer {token}",
         "Content-Type": "application/json",
-        "Accept": "application/ndjson",
+        "Accept": accept,
     }
 
-    alias = f"{variable}_value"
-    payload = {
-        "fromTime": from_time,
-        "untilTime": until_time,
+    payload: dict = {
         "minHorizon": int(min_horizon),
         "maxHorizon": int(max_horizon),
-        "coordinates": [{"lat": latitude, "lon": longitude}],
-        "variables": [{"name": variable, "level": DEFAULT_LEVEL, "alias": alias}],
+        "variables": variables,
     }
 
+    if from_time and until_time:
+        payload["fromTime"] = from_time
+        payload["untilTime"] = until_time
+    if times_list:
+        payload["timesList"] = times_list
+    if coordinates:
+        payload["coordinates"] = coordinates
+    if grid:
+        payload["grid"] = grid
     if members:
         payload["members"] = members
 
-    response = requests.post(url, headers=headers, json=payload, timeout=60)
+    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
     try:
         response.raise_for_status()
     except requests.HTTPError as exc:
         detail = response.text[:500]  # Trim to keep message readable.
         raise RuntimeError(f"API request failed: {response.status_code} {detail}") from exc
 
+    if accept == "text/csv":
+        buffer = io.BytesIO(response.content)
+        df = pd.read_csv(buffer)
+        return df
+
     records = decode_json_response(response)
     if not records:
-        return pd.DataFrame(), alias
+        return pd.DataFrame()
 
-    df = pd.DataFrame(records)
-    return df, alias
+    return pd.DataFrame(records)
 
 
 def prepare_results(
@@ -175,7 +221,7 @@ def prepare_results(
         (df["forecasted_time"] - df["forecasted_at"]).dt.total_seconds() / 3600.0
     )
 
-    variable_label, unit = WAVE_VARIABLES.get(variable.upper(), (variable, ""))
+    variable_label, unit = WAVE_VARIABLES.get(variable.lower(), (variable, ""))
     label = f"{variable_label} ({unit})" if unit else variable_label
 
     fig = go.Figure()
@@ -242,7 +288,9 @@ def run_query(
 ) -> Tuple[str, Optional[pd.DataFrame], Optional[go.Figure]]:
     try:
         token = get_token()
-        variable_name = (custom_variable or variable).strip()
+        dropdown_value = (variable or "").strip()
+        custom_value = (custom_variable or "").strip()
+        variable_name = custom_value or dropdown_value.lower()
         if not variable_name:
             raise ValueError("Select a variable or provide a custom variable name.")
 
@@ -262,17 +310,18 @@ def run_query(
 
         members = build_members_list(raw_members, model)
 
-        df, alias = fetch_wave_history(
+        alias = make_alias(variable_name)
+        df = fetch_wave_history(
             token=token,
             model=model,
-            variable=variable_name,
-            latitude=float(latitude),
-            longitude=float(longitude),
+            variables=[{"name": variable_name, "level": DEFAULT_LEVEL, "alias": alias}],
             from_time=window_start,
             until_time=window_end,
             min_horizon=lower,
             max_horizon=upper,
             members=members,
+            coordinates=[{"lat": float(latitude), "lon": float(longitude)}],
+            accept="application/ndjson",
         )
 
         display_df, fig, status = prepare_results(df, alias, variable_name)
@@ -284,6 +333,88 @@ def run_query(
         return f"❌ {exc}", None, None
 
 
+def run_global_download(
+    model: str,
+    variables: List[str],
+    custom_variables: str,
+    valid_time: str,
+    min_horizon: int,
+    max_horizon: int,
+    grid_step: float,
+    raw_members: str,
+) -> Tuple[str, Optional[pd.DataFrame], Optional[str]]:
+    try:
+        token = get_token()
+
+        selected_from_dropdown = [name.lower() for name in (variables or [])]
+        custom_list = parse_variable_list(custom_variables)
+        variable_names = list(dict.fromkeys([*selected_from_dropdown, *custom_list]))
+        if not variable_names:
+            raise ValueError("Select at least one variable or enter custom variable names.")
+
+        valid_iso = to_iso_utc(valid_time, "Valid time")
+        lower = int(min(min_horizon, max_horizon))
+        upper = int(max(min_horizon, max_horizon))
+
+        if grid_step <= 0:
+            raise ValueError("Grid step must be a positive number of degrees.")
+
+        members = build_members_list(raw_members, model)
+
+        variables_payload = [
+            {"name": name, "level": DEFAULT_LEVEL, "alias": make_alias(name)}
+            for name in variable_names
+        ]
+
+        df = fetch_wave_history(
+            token=token,
+            model=model,
+            variables=variables_payload,
+            times_list=[valid_iso],
+            min_horizon=lower,
+            max_horizon=upper,
+            grid={
+                "minLatitude": -90,
+                "maxLatitude": 90,
+                "minLongitude": -180,
+                "maxLongitude": 180,
+                "step": float(grid_step),
+            },
+            members=members,
+            accept="text/csv",
+            timeout=240,
+        )
+
+        if df.empty:
+            raise ValueError("No data returned for the requested global configuration.")
+
+        df = df.copy()
+        for col in ("forecasted_time", "forecasted_at"):
+            if col in df.columns:
+                df[col] = pd.to_datetime(df[col], utc=True, errors="coerce")
+
+        preview = df.head(500).copy()
+        preview_rows = len(preview)
+
+        tmp = tempfile.NamedTemporaryFile(delete=False, suffix=".csv", mode="w", newline="")
+        try:
+            df.to_csv(tmp.name, index=False)
+        finally:
+            tmp.close()
+
+        status = (
+            f"Fetched {len(df)} rows across {len(variable_names)} variable(s) "
+            f"for {valid_iso}. Showing the first {preview_rows} rows."
+        )
+
+        return status, preview, tmp.name
+
+    except ConfigurationError as exc:
+        return f"⚠️ {exc}", None, None
+    except Exception as exc:  # noqa: BLE001
+        return f"❌ {exc}", None, None
+
+
 def default_time_window(hours_back: int = 6, hours_forward: int = 24) -> Tuple[str, str]:
     now = dt.datetime.utcnow().replace(minute=0, second=0, microsecond=0)
     start = (now - dt.timedelta(hours=hours_back)).isoformat() + "Z"
@@ -291,111 +422,192 @@ def default_time_window(hours_back: int = 6, hours_forward: int = 24) -> Tuple[s
     return start, end
 
 
+def default_valid_time(offset_hours: int = 0) -> str:
+    now = dt.datetime.utcnow().replace(minute=0, second=0, microsecond=0)
+    return (now + dt.timedelta(hours=offset_hours)).isoformat() + "Z"
+
+
 def build_interface() -> gr.Blocks:
     start_default, end_default = default_time_window()
+    valid_default = default_valid_time()
 
     with gr.Blocks(title="GribStream IFS Wave Explorer") as demo:
         gr.Markdown(
             """
             # ECMWF Wave Data Explorer
-            Use your GribStream API token (stored as the `GRIB_API` secret) to pull the latest ECMWF wave forecasts.
-            Select the deterministic or ensemble wave model, choose a variable, and define the time window and horizons you
-            care about. Results include a table and interactive plot.
+            Use your GribStream API token (stored as the `GRIB_API` secret) to pull ECMWF IFS wave forecasts via GribStream.
+            Choose between a point time-series view or a global snapshot download of the latest wave fields.
             """
         )
 
-        with gr.Row():
-            with gr.Column(scale=1, min_width=320):
-                model_input = gr.Dropdown(
-                    choices=list(WAVE_MODELS.keys()),
-                    value="ifswave",
-                    label="Wave model",
-                    info="ifswave = deterministic, ifswaef = ensemble",
-                )
-                variable_input = gr.Dropdown(
-                    choices=list(WAVE_VARIABLES.keys()),
-                    value="SWH",
-                    label="Variable",
-                    info="Common wave parameters: SWH (height), MWD (direction), MWP (period), MP2, PP1D.",
-                )
-                custom_variable_input = gr.Textbox(
-                    label="Custom variable (optional)",
-                    placeholder="Override with another parameter name, e.g. swh",
-                    info="Leave blank to use the dropdown selection.",
-                )
-                latitude_input = gr.Number(
-                    label="Latitude",
-                    value=32.0,
-                    precision=4,
-                )
-                longitude_input = gr.Number(
-                    label="Longitude",
-                    value=-64.0,
-                    precision=4,
-                )
-                from_time_input = gr.Textbox(
-                    label="From time (UTC)",
-                    value=start_default,
-                    info="ISO 8601 format, e.g. 2025-10-23T00:00:00Z",
-                )
-                until_time_input = gr.Textbox(
-                    label="Until time (UTC)",
-                    value=end_default,
-                    info="ISO 8601 format, must be after the start time.",
-                )
-                min_horizon_input = gr.Slider(
-                    label="Minimum forecast horizon (hours)",
-                    value=0,
-                    minimum=0,
-                    maximum=360,
-                    step=1,
-                )
-                max_horizon_input = gr.Slider(
-                    label="Maximum forecast horizon (hours)",
-                    value=72,
-                    minimum=0,
-                    maximum=360,
-                    step=1,
+        with gr.Tabs():
+            with gr.Tab("Point time series"):
+                with gr.Row():
+                    with gr.Column(scale=1, min_width=320):
+                        series_model_input = gr.Dropdown(
+                            choices=list(WAVE_MODELS.keys()),
+                            value="ifswave",
+                            label="Wave model",
+                            info="Choose `ifswave` for the deterministic run or `ifswaef` for the ensemble.",
+                        )
+                        series_variable_input = gr.Dropdown(
+                            choices=[code.upper() for code in WAVE_VARIABLES.keys()],
+                            value="SWH",
+                            label="Variable",
+                            info="Wave parameters use ECMWF short names (e.g., SWH height, MWD direction, MWP period).",
+                        )
+                        series_custom_variable_input = gr.Textbox(
+                            label="Custom variable (optional)",
+                            placeholder="Override with another parameter, e.g. swh",
+                            info="Leave blank to use the dropdown selection.",
+                        )
+                        series_latitude_input = gr.Number(
+                            label="Latitude",
+                            value=32.0,
+                            precision=4,
+                        )
+                        series_longitude_input = gr.Number(
+                            label="Longitude",
+                            value=-64.0,
+                            precision=4,
+                        )
+                        series_from_time_input = gr.Textbox(
+                            label="From time (UTC)",
+                            value=start_default,
+                            info="ISO 8601 format, e.g. 2025-10-23T00:00:00Z",
+                        )
+                        series_until_time_input = gr.Textbox(
+                            label="Until time (UTC)",
+                            value=end_default,
+                            info="ISO 8601 format, must be after the start time.",
+                        )
+                        series_min_horizon_input = gr.Slider(
+                            label="Minimum forecast horizon (hours)",
+                            value=0,
+                            minimum=0,
+                            maximum=360,
+                            step=1,
+                        )
+                        series_max_horizon_input = gr.Slider(
+                            label="Maximum forecast horizon (hours)",
+                            value=72,
+                            minimum=0,
+                            maximum=360,
+                            step=1,
+                        )
+                        series_members_input = gr.Textbox(
+                            label="Ensemble members (IFS Waef only)",
+                            placeholder="e.g. 0,1,2",
+                            info="Leave blank for control (0). Ignored for deterministic model.",
+                        )
+                        series_submit = gr.Button("Fetch time series", variant="primary")
+
+                    with gr.Column(scale=2):
+                        series_status_output = gr.Markdown("Results will appear here once you hit **Fetch**.")
+                        series_table_output = gr.Dataframe(
+                            interactive=False,
+                            wrap=False,
+                        )
+                        series_chart_output = gr.Plot(show_label=False)
+
+                series_submit.click(
+                    fn=run_query,
+                    inputs=[
+                        series_model_input,
+                        series_variable_input,
+                        series_custom_variable_input,
+                        series_latitude_input,
+                        series_longitude_input,
+                        series_from_time_input,
+                        series_until_time_input,
+                        series_min_horizon_input,
+                        series_max_horizon_input,
+                        series_members_input,
+                    ],
+                    outputs=[series_status_output, series_table_output, series_chart_output],
                 )
-                members_input = gr.Textbox(
-                    label="Ensemble members (IFS Waef only)",
-                    placeholder="e.g. 0,1,2",
-                    info="Leave blank for control (0). Ignored for deterministic model.",
+
+            with gr.Tab("Global snapshot download"):
+                gr.Markdown(
+                    "Fetch the full global grid for a selected valid time, then download it as CSV. "
+                    "Reduce the grid spacing if you need a lighter file."
                 )
-                submit = gr.Button("Fetch wave data", variant="primary")
-
-            with gr.Column(scale=2):
-                status_output = gr.Markdown("Results will appear here once you hit **Fetch**.")
-                table_output = gr.Dataframe(
-                    headers=[
-                        "valid_time",
-                        "forecast_issue_time",
-                        "lead_time_hours",
-                        "value",
-                        "lat",
-                        "lon",
+                with gr.Row():
+                    with gr.Column(scale=1, min_width=320):
+                        global_model_input = gr.Dropdown(
+                            choices=list(WAVE_MODELS.keys()),
+                            value="ifswave",
+                            label="Wave model",
+                            info="`ifswave` deterministic or `ifswaef` ensemble.",
+                        )
+                        global_variables_input = gr.CheckboxGroup(
+                            label="Variables",
+                            choices=[code.upper() for code in WAVE_VARIABLES.keys()],
+                            value=["SWH", "MWD", "MWP"],
+                            info="Select one or more parameters to include in the download.",
+                        )
+                        global_custom_variables_input = gr.Textbox(
+                            label="Additional variables (optional)",
+                            placeholder="Comma-separated list, e.g. mp2,pp1d",
+                            info="Use ECMWF short names. Combined with the selection above.",
+                        )
+                        global_valid_time_input = gr.Textbox(
+                            label="Forecast valid time (UTC)",
+                            value=valid_default,
+                            info="ISO 8601 format corresponding to the wave field time you need.",
+                        )
+                        global_min_horizon_input = gr.Slider(
+                            label="Minimum forecast horizon (hours)",
+                            value=0,
+                            minimum=0,
+                            maximum=360,
+                            step=1,
+                        )
+                        global_max_horizon_input = gr.Slider(
+                            label="Maximum forecast horizon (hours)",
+                            value=24,
+                            minimum=0,
+                            maximum=360,
+                            step=1,
+                        )
+                        global_grid_step_input = gr.Slider(
+                            label="Grid spacing (degrees)",
+                            value=0.5,
+                            minimum=0.25,
+                            maximum=2.0,
+                            step=0.25,
+                        )
+                        global_members_input = gr.Textbox(
+                            label="Ensemble members (IFS Waef only)",
+                            placeholder="e.g. 0,1,2,3",
+                            info="Leave blank for default control member. Ignored for deterministic model.",
+                        )
+                        global_submit = gr.Button("Download global snapshot", variant="primary")
+
+                    with gr.Column(scale=2):
+                        global_status_output = gr.Markdown(
+                            "The download link and preview will appear here after processing."
+                        )
+                        global_preview_output = gr.Dataframe(
+                            interactive=False,
+                            wrap=False,
+                        )
+                        global_file_output = gr.File(label="Download CSV")
+
+                global_submit.click(
+                    fn=run_global_download,
+                    inputs=[
+                        global_model_input,
+                        global_variables_input,
+                        global_custom_variables_input,
+                        global_valid_time_input,
+                        global_min_horizon_input,
+                        global_max_horizon_input,
+                        global_grid_step_input,
+                        global_members_input,
                     ],
-                    interactive=False,
-                    wrap=False,
+                    outputs=[global_status_output, global_preview_output, global_file_output],
                 )
-                chart_output = gr.Plot(show_label=False)
-
-        submit.click(
-            fn=run_query,
-            inputs=[
-                model_input,
-                variable_input,
-                custom_variable_input,
-                latitude_input,
-                longitude_input,
-                from_time_input,
-                until_time_input,
-                min_horizon_input,
-                max_horizon_input,
-                members_input,
-            ],
-            outputs=[status_output, table_output, chart_output],
-        )
 
         demo.queue()
     return demo