Docs: output verification in examples + document fixed_season (#128)

climate_toolkit/climate_statistics/statistics.py

@@ -1349,7 +1349,9 @@ def _auto_season_slot_warning(season_results: List[Dict[str, Any]]) -> Optional[
     return (
         "Auto-detected season counts differ across years, so LTM season windows by "
         f"season_number would blend incomparable seasons. Counts by year: {summary}. "
-        "Use --fixed-season for stable multi-year seasonal LTM output."
+        "For stable multi-year seasonal LTM output, pin the season: "
+        'fixed_season="MM-DD:MM-DD" in the Python API '
+        "(or --fixed-season on the CLI), e.g. \"03-01:05-31\"."
     )
 
 

docs/api/fetching.md

@@ -2,4 +2,30 @@
 
 Available as `climate_toolkit.fetch_climate_data`.
 
+## Example
+
+```python
+from datetime import date
+import climate_toolkit as ct
+from climate_toolkit.fetch_data.source_data.sources.utils.models import ClimateVariable
+
+df = ct.fetch_climate_data(
+    source="nasa_power",                       # no credentials needed
+    location_coord=(-1.286, 36.817),
+    variables=[ClimateVariable.precipitation,
+               ClimateVariable.max_temperature,
+               ClimateVariable.min_temperature],
+    date_from=date(2020, 1, 1),
+    date_to=date(2020, 12, 31),
+    verbose=False,
+)
+print("rows:", df.shape[0], "| columns:", df.columns.tolist())
+print(df.head())
+```
+
+`fetch_climate_data` returns a **pandas DataFrame**. Earth Engine-backed sources
+(`agera_5`, `nex_gddp`, ...) use the same call after a one-time setup — see
+[Getting started](../getting_started.md#2-google-earth-engine-credentials). Full
+parameter reference below.
+
 ::: climate_toolkit.fetch_data.fetch_data.fetch_data

docs/getting_started.md

@@ -77,27 +77,60 @@ Setup steps:
 
 ## 3. First analysis
 
+Fetch daily data (NASA POWER needs no credentials) and confirm what came back:
+
 ```python
 import climate_toolkit as ct
 from datetime import date
 
-# Daily data — no credentials needed for nasa_power
 df = ct.fetch_climate_data(
     source="nasa_power",
-    location_coord=(-1.286, 36.817),
+    location_coord=(-1.286, 36.817),   # Nairobi (lat, lon)
     date_from=date(2020, 1, 1),
     date_to=date(2020, 12, 31),
+    verbose=False,
 )
+print("rows:", df.shape[0], "| columns:", df.columns.tolist())
+df.head()
+```
+
+`fetch_climate_data` returns a **pandas DataFrame**. NASA POWER carries no soil
+fields, so you'll see a note that those were skipped — the climate columns are
+still returned.
+
+### Seasonal statistics as a table
+
+`analyze_climate_statistics` returns a nested dict. Pin the season with
+`fixed_season="MM-DD:MM-DD"` for stable, comparable multi-year output, then
+tabulate the per-season results:
 
-# Crop hazards for a season (uses Earth Engine sources by default)
-hazards = ct.evaluate_hazards(
-    crop_name="maize",
+```python
+import pandas as pd
+
+stats = ct.analyze_climate_statistics(
     location_coord=(-1.286, 36.817),
-    date_from="2020-01-01",
-    date_to="2020-12-31",
+    start_year=2016, end_year=2020,
+    source="nasa_power",
+    fixed_season="03-01:05-31",        # March–May long rains
 )
+
+pd.DataFrame([
+    {
+        "year": s["year"],
+        "rain_mm": (s["precipitation"] or {}).get("total_mm"),
+        "NDWS": (s["water_balance"] or {}).get("NDWS"),
+        "WRSI": (s["water_balance"] or {}).get("WRSI"),
+    }
+    for s in stats["season_statistics"]
+])
 ```
 
+!!! note "Why `fixed_season`?"
+    With automatic detection, different years can have different season counts,
+    and the toolkit warns that it can't build comparable multi-year windows.
+    Passing `fixed_season="MM-DD:MM-DD"` (one or two comma-separated windows)
+    pins the season so results line up year to year.
+
 ## Getting help
 
 Every public function has full parameter documentation: