Customized regions

logo

2.1. Customized regions#

This notebook reproduces the functionalities of the C3S Atlas (https://atlas.climate.copernicus.eu/atlas) for data masking based on customized_regions. This functionality is particularly useful for selecting and analyzing specific geographical areas within the data. The customized_regions function supports five types of regions:

    1. User-defined regions: These are custom regions defined by the user based on specific criteria or geographic boundaries.

    1. AR6 regions: These are regions defined by the IPCC AR6 WG1, used for climate research and analysis (Iturbide et al. 2020).

    1. European countries: This includes masks for individual European countries, allowing for detailed country-level analysis.

    1. EUCRA regions: These are regions defined by the European Climate Assessment & Dataset project.

    1. GeoJSON files: Custom regions can also be defined using GeoJSON files, which allows for highly customizable geographic boundaries based on external data sources.

Users can use the acronyms available in the regions.json to select a specific region for any of the above types of regions.

Throughout this notebook, we will explore how to create and apply these masks to your datasets, enabling targeted and region-specific data analysis.

2.1.1. Load Python packages and clone and install the c3s-atlas GitHub repository from the ecmwf-projects#

Clone (git clone) the c3s-atlas repository and install them (pip install -e .).

Further details on how to clone and install the repository are available in the requirements section

import os
import xarray as xr
from pathlib import Path
import cdsapi
import requests, zipfile, io

from c3s_atlas.utils import (
    extract_zip_and_delete,
)
from c3s_atlas.customized_regions import (
    Mask
)

2.1.2. Download climate data with the CDS API#

To reduce data size and download time, a geographical subset focusing on the European region is selected.

project = "ERA5"
var = 't'
trend_period = period = slice('1991','2020')

dest = Path('./data/ERA5')
os.makedirs(dest, exist_ok=True)

filename = 't_ERA5_mon_194001-202212.zip'

dataset = "multi-origin-c3s-atlas"
request = {
    'origin': 'era5',
    'domain': 'global',
    'variable': 'monthly_mean_of_daily_mean_temperature',
    'area': [35, -25, 72, 65], # Europe
}

client = cdsapi.Client()
client.retrieve(dataset, request).download(dest / filename)
extract_zip_and_delete(dest / filename) 

ds = xr.open_dataset(dest / "t_ERA5_mon_194001-202212.nc")
# Select firs time step for faster results
ds = ds.isel(time=0)

ds['t'].plot()

<matplotlib.collections.QuadMesh at 0x712a61f2cc20>
../_images/701011b597fd8b958678c1797412d7e470c608395e52617225cef2e27625dcf9.png

Generate and apply a mask for the user-defined region.#

# Define a triangle mask using coordinates
mask_polygon = Mask(ds).polygon([[-20, 40], [20, 40], [0, 55]])

mask_polygon.plot()

<matplotlib.collections.QuadMesh at 0x712a4c30d130>
../_images/6f24c6c141e31e79c438222b87034f6a46a7ddccb2f4118aa6a92c5d0fb62ae1.png 
# Mask the dataset (ds) based on the polygon mask (mask_polygon)
ds_masked_polygon = ds.where(mask_polygon)

# Plot the masked dataset (ds_masked_polygon)
ds_masked_polygon[var].plot()

<matplotlib.collections.QuadMesh at 0x712a39ee5130>
../_images/cf32aaac5e5fb4f01858a170f35c8972d7be2fc07e8aa4ccc6a459c55bddea06.png 
# Define a square mask using coordinates (order matters)
mask_polygon = Mask(ds).polygon([[-20, 40], [20, 40], [20, 65], [-20, 55]])
ds_masked_polygon = ds.where(mask_polygon)
ds_masked_polygon[var].plot()

<matplotlib.collections.QuadMesh at 0x712a39c6b6e0>
../_images/91bf963d44402ec2a1854565612fa94ce1c5c6f4036682e95ccf9135eff4b61a.png

Generate and apply a mask for the AR6-regions.#

# Create a mask for a specific AR6 region (MED in this case)
mask_AR6 = Mask(ds).regions_AR6(['MED'])

# Mask the dataset (ds) based on the AR6 region mask (mask_AR6)
ds_masked_AR6 = ds.where(mask_AR6)

# Plot the masked dataset for the AR6 region (ds_masked_AR6)
ds_masked_AR6[var].plot()

<matplotlib.collections.QuadMesh at 0x723921575490>
../_images/15384767b489d08a05b2e3b025a39c66783a49ca3cf3f2db8069848301a620d4.png 
# Define a mask for AR6 regions using a list of region names
mask_AR6 = Mask(ds).regions_AR6(['MED','SAH','NEU'])
ds_masked_AR6 = ds.where(mask_AR6)
ds_masked_AR6[var].plot()

<matplotlib.collections.QuadMesh at 0x72392144fec0>
../_images/ebb0c9bc7d6504dddb16b4277fd7effd386ad6223800f790f1eb688f9bb334cd.png

Generate and apply a mask for the European countries.#

# Define a mask for European countries using a list (including only España)
mask_EUR = Mask(ds).European_contries(['ESP'])

# Mask the dataset (ds) based on the European countries mask (mask_EUR)
ds_masked_EUR = ds.where(mask_EUR)

# Plot the masked dataset for the European countries (ds_masked_EUR)
ds_masked_EUR[var].plot()

<matplotlib.collections.QuadMesh at 0x72392144dd00>
../_images/5cbc9897e11031b02497cea72ff43f0af86f0005d7fa196f01509bff582a80cb.png 
# Define a mask for European countries using a list of country abbreviations
mask_EUR = Mask(ds).European_contries(['ESP','FRA'])
ds_masked_EUR = ds.where(mask_EUR)
ds_masked_EUR[var].plot()

<matplotlib.collections.QuadMesh at 0x72392139d880>
../_images/6c7dbd34189172345def3a0ab0cd8f615852fa093a063cabcd5de5083d33680f.png

Generate and apply a mask for the EUCRA regions.#

# Define a mask for EUCRA areas using a list 
mask_EUCRA = Mask(ds).EUCRA_contries(['ST'])

# Mask the dataset (ds) based on the EUCRA countries mask (mask_EUCRA)
ds_masked_EUCRA = ds.where(mask_EUCRA)

# Plot the masked dataset for the EUCRA countries (ds_masked_EUCRA)
ds_masked_EUCRA[var].plot()

<matplotlib.collections.QuadMesh at 0x723920d9d640>
../_images/1516b9ea8104c5115b6da04581e3726d5fac527b0b713315a51eb5e4f28748ab.png 
# Define a mask for EUCRA countries using a list of abbreviations
mask_EUCRA = Mask(ds).EUCRA_contries(['ST', 'CT'])
ds_masked_EUCRA = ds.where(mask_EUCRA)
ds_masked_EUCRA[var].plot()

<matplotlib.collections.QuadMesh at 0x723920e87a70>
../_images/2b586ba32c30eeab71cadfb3ed75aa700030a7224b6a9e78a077772318c0d0f1.png

2.1.3. Download climate data with the CDS API#

project = "ERA5"
var = 't'
trend_period = period = slice('1991','2020')

dest = Path('./data/ERA5')
os.makedirs(dest, exist_ok=True)

filename = 't_ERA5_mon_194001-202212.zip'

dataset = "multi-origin-c3s-atlas"
request = {
    'origin': 'era5',
    'domain': 'global',
    'variable': 'monthly_mean_of_daily_mean_temperature',
    'area': [20, -150, 60, 67], # USA
}

client = cdsapi.Client()
client.retrieve(dataset, request).download(dest / filename)
extract_zip_and_delete(dest / filename) 

ds = xr.open_dataset(dest / "t_ERA5_mon_194001-202212.nc")
# Select firs time step for faster results
ds = ds.isel(time=0)

ds['t'].plot()

<matplotlib.collections.QuadMesh at 0x72392117a150>
../_images/77635fdfc3eb3821238a66c1737ee0a0d626ab0286afebeb0e7b8f57b48abdf6.png

Generate and apply a mask from a different GeoJSON.#

zip_url = "https://download2.exploratory.io/maps/states.zip"
r = requests.get(zip_url)
zip_file = io.BytesIO(r.content)

with zipfile.ZipFile(zip_file, 'r') as zip_ref:
        zip_ref.extractall("./geojsons/")

# Define a mask using a GeoJSON file and names
mask_json = Mask(ds).regions_geojson('./geojsons/states.geojson', "NAME", ["Nebraska", "Indiana", "Texas"])

# Mask the dataset (ds) based on the US states mask (mask_json)
ds_masked_json = ds.where(mask_json)

# Plot the masked dataset for the US states (ds_masked_json)
ds_masked_json[var].plot()

<matplotlib.collections.QuadMesh at 0x7239210577d0>
../_images/bdee6d02b7b6111d833f50449277950fb4df9890d0edea0dcf7f7989244588bd.png
Contents