Weather-Induced Extremes - Data Access using DEDL HDA
This notebook demonstrates how to access and download sea ice coverage data from the Weather-Induced Extremes Digital Twin using the DestinE Data Lake Harmonised Data Access (DEDL HDA) API, including authentication, filtering, polling, and visualizing the result on a map.
Credit: Earthkit and HDA Polytope used in this context are both packages provided by the European Centre for Medium-Range Weather Forecasts (ECMWF).
Documentation DestinE Data Lake HDA
Documentation Digital Twin - Parameter Usage
DEDL Harmonised Data Access is used in this example.
Obtain Authentication Token¶
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
import ipywidgets as widgets
import json
import os
from getpass import getpass
import destinelab as deauth
DESP_USERNAME = input("Please input your DESP username or email: ")
DESP_PASSWORD = getpass("Please input your DESP password: ")
auth = deauth.AuthHandler(DESP_USERNAME, DESP_PASSWORD)
access_token = auth.get_token()
if access_token is not None:
print("DEDL/DESP Access Token Obtained Successfully")
else:
print("Failed to Obtain DEDL/DESP Access Token")
auth_headers = {"Authorization": f"Bearer {access_token}"}
Please input your DESP username or email: eum-dedl-user
Please input your DESP password: ········
Response code: 200
DEDL/DESP Access Token Obtained Successfully
Check if DT access is granted¶
If DT access is not granted, you will not be able to execute the rest of the notebook.
import importlib
installed_version = importlib.metadata.version("destinelab")
version_number = installed_version.split('.')[1]
if((int(version_number) >= 8 and float(installed_version) < 1) or float(installed_version) >= 1):
auth.is_DTaccess_allowed(access_token)
DT Output access allowed
Query using the DEDL HDA API¶
Filter¶
We have to setup up a filter and define which data to obtain.
Extreme DT data is available for specific time ranges (last 14 days) around the current date.
It is possible to use the ECMWF Aviso package to check data availability in the last 14 days (see https://github.com/destination-earth/DestinE-DataLake-Lab/blob/main/HDA/DestinE Digital Twins/ExtremeDT-dataAvailability.ipynb or extremes
from datetime import datetime, timedelta
# Get the current date and time in UTC
current_date = datetime.utcnow()
# Calculate the date 14 days before the current date
date_14_days_ago = current_date - timedelta(days=14)
# Format the date as YYYYMMDD and set the time to 0000 UTC
formatted_date = date_14_days_ago.strftime('%Y%m%d') + '0000'
# Convert the formatted date back to a datetime object
date_from = datetime.strptime(formatted_date, '%Y%m%d%H%M%S').date()
# Format the date as YYYYMMDD and set the time to 0000 UTC
formatted_date = current_date.strftime('%Y%m%d') + '0000'
# Convert the formatted date back to a datetime object
date_to = datetime.strptime(formatted_date, '%Y%m%d%H%M%S').date()
start_date_picker = widgets.DatePicker(description='Start Date:', disabled=False)
# Set initial values directly
start_date_picker.min = date_from
start_date_picker.max = date_to
start_date_picker.value = date_from
def get_selected_values():
selected_start_date = start_date_picker.value
return selected_start_date
# Display widgets
display(start_date_picker)
datechoice = get_selected_values().strftime("%Y-%m-%dT%H:%M:%SZ")
filters = {
key: {"eq": value}
for key, value in {
"class": "d1", # fixed (rd or d1)
"dataset": "extremes-dt", # fixed extreme dt
"expver": "0001", # fixed experiment version
"stream": "oper", # fixed oper
"step": "0", # Forcast step hourly (1..96)
"type": "fc", # fixed forecasted fields
"levtype": "sfc", # Surface fields (levtype=sfc), Height level fields (levtype=hl), Pressure level fields (levtype=pl), Model Level (Levtype=ml)
"param": "31" # Sea ice area fraction
}.items()
}
Make Data Request¶
#Sometimes requests to polytope get timeouts, it is then convenient define a retry strategy
retry_strategy = Retry(
total=5, # Total number of retries
status_forcelist=[500, 502, 503, 504], # List of 5xx status codes to retry on
allowed_methods=["GET",'POST'], # Methods to retry
backoff_factor=1 # Wait time between retries (exponential backoff)
)
# Create an adapter with the retry strategy
adapter = HTTPAdapter(max_retries=retry_strategy)
# Create a session and mount the adapter
session = requests.Session()
session.mount("https://", adapter)
response = session.post("https://hda.data.destination-earth.eu/stac/search", headers=auth_headers, json={
"collections": ["EO.ECMWF.DAT.DT_EXTREMES"],
"datetime": datechoice,
"query": filters
})
# Requests to EO.ECMWF.DAT.DT_EXTREMES always return a single item containing all the requested data
if(response.status_code!= 200):
(print(response.text))
response.raise_for_status()
product = response.json()["features"][0]
product["id"]
#product
'DT_EXTREMES_20250325_20250325_55b7e9b28e472cd4fbe3f1aa5390d4b57303e39a'
Submission worked ? Once our product found, we download the data.¶
from IPython.display import JSON
# DownloadLink is an asset representing the whole product
download_url = product["assets"]["downloadLink"]["href"]
HTTP_SUCCESS_CODE = 200
HTTP_ACCEPTED_CODE = 202
direct_download_url=''
response = session.get(download_url, headers=auth_headers)
if (response.status_code == HTTP_SUCCESS_CODE):
direct_download_url = product['assets']['downloadLink']['href']
elif (response.status_code != HTTP_ACCEPTED_CODE):
print(response.text)
response.raise_for_status()
print(download_url)
https://hda.data.destination-earth.eu/stac/collections/EO.ECMWF.DAT.DT_EXTREMES/items/DT_EXTREMES_20250325_20250325_55b7e9b28e472cd4fbe3f1aa5390d4b57303e39a/download?provider=dedt_lumi&_dc_qs=%257B%2522class%2522%253A%2B%2522d1%2522%252C%2B%2522dataset%2522%253A%2B%2522extremes-dt%2522%252C%2B%2522date%2522%253A%2B%252220250325%252Fto%252F20250325%2522%252C%2B%2522expver%2522%253A%2B%25220001%2522%252C%2B%2522levtype%2522%253A%2B%2522sfc%2522%252C%2B%2522param%2522%253A%2B%252231%2522%252C%2B%2522step%2522%253A%2B%25220%2522%252C%2B%2522stream%2522%253A%2B%2522oper%2522%252C%2B%2522time%2522%253A%2B%25220000%2522%252C%2B%2522type%2522%253A%2B%2522fc%2522%257D
Wait until data is there¶
This data is not available at the moment. And we can see that our request is in queued
status.
We will now poll the API until the data is ready and then download it.
Please note that the basic HDA quota allows a maximum of 4 requests per second. The following code limits polling to this quota.
pip install ratelimit --quiet
Note: you may need to restart the kernel to use updated packages.
from tqdm import tqdm
import time
import re
from ratelimit import limits, sleep_and_retry
# Set limit: max 4 calls per 1 seconds
CALLS = 4
PERIOD = 1 # seconds
@sleep_and_retry
@limits(calls=CALLS, period=PERIOD)
def call_api(url,auth_headers):
response = session.get(url, headers=auth_headers, stream=True)
return response
# we poll as long as the data is not ready
if direct_download_url=='':
while url := response.headers.get("Location"):
print(f"order status: {response.json()['status']}")
response = call_api(url,auth_headers)
if (response.status_code not in (HTTP_SUCCESS_CODE,HTTP_ACCEPTED_CODE)):
(print(response.text))
# Check if Content-Disposition header is present
if "Content-Disposition" not in response.headers:
print(response)
print(response.text)
raise Exception("Headers: \n"+str(response.headers)+"\nContent-Disposition header not found in response. Must be something wrong.")
filename = re.findall('filename=\"?(.+)\"?', response.headers["Content-Disposition"])[0]
total_size = int(response.headers.get("content-length", 0))
print(f"downloading {filename}")
with tqdm(total=total_size, unit="B", unit_scale=True) as progress_bar:
with open(filename, 'wb') as f:
for data in response.iter_content(1024):
progress_bar.update(len(data))
f.write(data)
order status: queued
downloading fd2422ba-b60a-4635-a356-7a4993e738e6.grib
100%|██████████| 3.26M/3.26M [00:00<00:00, 16.2MB/s]
Render the sea ice coverage on a map¶
Lets plot the result file
This section requires that you have ecCodes >= 2.35
installed on your system.
You can follow the installation procedure at https://
import xarray as xr
import cfgrib
import matplotlib.pyplot as plt
import numpy as np
ds = xr.load_dataset(filename, engine="cfgrib")
ds
import cartopy.crs as crs
import cartopy.feature as cfeature
fig = plt.figure(figsize=[10, 10])
#ax = fig.add_subplot(1,1,1, projection=crs.Robinson())
crs_epsg=crs.NorthPolarStereo(central_longitude=0)
ax = fig.add_subplot(1,1,1, projection=crs_epsg)
ax.set_extent([-3850000.0, 3750000.0, -5350000, 5850000.0],crs_epsg)
ax.add_feature(cfeature.COASTLINE)
ax.gridlines()
cs = plt.scatter(x=ds.longitude[::10], y=ds.latitude.data[::10], c=ds.siconc[::10], cmap="Blues",
s=1,
transform=crs.PlateCarree())
fig.colorbar(cs, ax=ax, location='right', shrink =0.8)
plt.show()
