Upload folder using huggingface_hub

src/eurus/config.py

@@ -632,6 +632,16 @@ Persistent Python kernel for custom analysis and visualization.
 - **Extremes**: Filter data where values exceed thresholds
 - **Visualizations**: Any matplotlib plot saved to PLOTS_DIR
 
+### 3b. ANOMALY MAP STRATEGY (CRITICAL)
+⚠️ When computing **anomaly maps** for large spatial areas (≥30°×30°):
+
+1. **Download target period** — 1 `retrieve_era5_data` call for the requested month
+2. **Download baseline** — MAX 3-5 `retrieve_era5_data` calls (same month, recent years like 2018-2022)
+3. **Compute in `python_repl`** — Load all files, average baseline, subtract from target
+
+**NEVER download 20-30 individual years** for climatology — that is extremely wasteful.
+A 5-year baseline is sufficient for spatial anomaly maps.
+
 ### 4. MEMORY
 Remembers conversation history and previous analyses.
 

src/eurus/retrieval.py

@@ -190,6 +190,7 @@ def retrieve_era5_data(
     min_longitude: float = 0.0,
     max_longitude: float = 359.75,
     region: Optional[str] = None,
+    api_key: Optional[str] = None,
 ) -> str:
     """
     Retrieve ERA5 reanalysis data from Earthmover's cloud-optimized archive.
@@ -204,6 +205,7 @@ def retrieve_era5_data(
         min_longitude: Western bound (0 to 360)
         max_longitude: Eastern bound (0 to 360)
         region: Optional predefined region name (overrides lat/lon)
+        api_key: Optional Arraylake API key (falls back to env var)
 
     Returns:
         Success message with file path, or error message.
@@ -213,8 +215,8 @@ def retrieve_era5_data(
     """
     memory = get_memory()
 
-    # Get API key
-    api_key = os.environ.get("ARRAYLAKE_API_KEY")
+    # Get API key: prefer explicit parameter, fall back to env var
+    api_key = api_key or os.environ.get("ARRAYLAKE_API_KEY")
     if not api_key:
         return (
             "Error: ARRAYLAKE_API_KEY not found in environment.\n"
@@ -327,9 +329,11 @@ def retrieve_era5_data(
             f"Error: Spatial queries are limited to 1 year max ({date_span_days} days requested).\n"
             f"The spatial dataset is optimised for maps, not long time series.\n\n"
             f"Options:\n"
-            f"1. Split into yearly requests (e.g. one call per year)\n"
-            f"2. Use query_type='temporal' for multi-year time-series analysis\n"
-            f"3. Narrow the date range to ≤ 366 days"
+            f"1. For anomaly maps: download ONLY the target period + a few recent baseline years "
+            f"(3-5 calls max), then compute climatology in python_repl\n"
+            f"2. Narrow the date range to ≤ 366 days\n\n"
+            f"⚠️ Do NOT split into 20-30 yearly retrieve_era5_data calls — "
+            f"that is extremely wasteful and slow!"
         )
 
     # Download with retry logic

src/eurus/tools/analysis_guide.py

@@ -118,8 +118,16 @@ ANALYSIS_GUIDES = {
 4. **Convert units** — Report in °C, mm, m/s (not K, m, Pa).
 5. **Assess magnitude** — Compare to σ of the baseline period.
 
+### Data Strategy for Large-Area Anomaly Maps
+⚠️ For spatial areas ≥30°×30° (e.g., tropical Pacific), do NOT download 30 years one-by-one!
+1. Download target period with 1 `retrieve_era5_data` call
+2. Download 3-5 recent years of the same month as baseline (3-5 calls)  
+3. Average baseline files in `python_repl` → climatology
+4. Subtract climatology from target → anomaly map
+A 5-year baseline is sufficient for spatial anomaly maps.
+
 ### Quality Checklist
-- [ ] Baseline ≥10 years
+- [ ] Baseline ≥10 years (for temporal/small-area analysis; 3-5 years OK for spatial maps)
 - [ ] Same calendar grouping for clim and analysis
 - [ ] Units converted for readability
 - [ ] Spatial context: is anomaly regional or localized?