None

Note

This tutorial was generated from an IPython notebook that can be accessed from github.

# Create 3D mask of approximate fractional overlap

Working with fractional overlap - indicating how much of the grid cell is covered by the region - can help to create more exact regional means, allow to exclude gridpoints from regions if the overlap is too small etc.. Since v0.12.0 regionmask can create a 3D masks with the approximate fractional overlap of a set of regions for equally-spaced latitude and longitude grids. The mask is a float `xarray.DataArray` with shape `region x lat x lon`, with the overlap given as fraction (i.e. between 0 and 1).

Attention

There are three caveats when creating fractional overlaps:

1. The passed longitude and latitude coordinates must be equally spaced - otherwise an `InvalidCoordsError` is raised.

2. Calculating the fractional overlap can be memory intensive (especially when passing many coordinates).

Despite these restrictions using an approximation has advantages over calculating the exact overlap - it is considerably faster. Many concepts were already introduced in 3D masks.

Import libraries and check the regionmask version:

```import numpy as np
import xarray as xr

# don't expand data
xr.set_options(display_style="text", display_expand_data=False, display_width=60)

```
```'0.12.1'
```

Define a lon/ lat grid with a 2° grid spacing, where the points define the center of the grid:

```lon = np.arange(0, 360, 2)
lat = np.arange(90, -91, -2)
```

The function `mask_3D_frac_approx` calculates the fractional overlap of each gridpoint with each region. Here using the AR6 land regions (Iturbide et al., 2020):

```mask = regionmask.defined_regions.ar6.land.mask_3D_frac_approx(lon, lat)
```
```Downloading file 'IPCC-WGI-reference-regions-v4.zip' from 'https://github.com/regionmask/regionmask/raw/v0.12.1/data/IPCC-WGI-reference-regions-v4.zip' to '/home/docs/.cache/regionmask/v0.12.1'.
```

## Illustration

As mentioned, `mask` is a float `xarray.DataArray` with shape `region x lat x lon`. It contains `region` (=`numbers`) as dimension coordinate as well as `abbrevs` and `names` as non-dimension coordinates (see the xarray docs for the details on the terminology).

The regions northwestern North-America, and northeastern North-America (regions 1, and 2) look as follows:

```import cartopy.crs as ccrs

subplot_kws=dict(projection=ccrs.PlateCarree()),
col="region",
col_wrap=2,
transform=ccrs.PlateCarree(),
aspect=1.5,
cmap="Blues",

)

fg.cbar.set_label("Fractional overlap")

for ax in fg.axs.flatten():
ax.set_extent([-172, -47.5, 35, 90], ccrs.PlateCarree())
```

## Working with a 3D mask

masks can be used to select data in a certain region and to calculate regional averages. Let’s illustrate this with a ‘real’ dataset - the example data is a temperature field over North America.

```airtemps = xr.tutorial.load_dataset("air_temperature")
```

An xarray object can be passed to the `mask_3D_frac_approx` function:

```mask_3D_frac_approx = regionmask.defined_regions.ar6.land.mask_3D_frac_approx(airtemps)
```

As `airtemps` has another grid than the example above, the resulting mask looks different:

```fg = mask_3D_frac_approx.sel(region=slice(1, 2)).plot(
subplot_kws=dict(projection=ccrs.PlateCarree()),
col="region",
col_wrap=2,
transform=ccrs.PlateCarree(),
aspect=1.5,
cmap="Blues",

)

fg.cbar.set_label("Fractional overlap")

for ax in fg.axs.flatten():
ax.set_extent([-172, -47.5, 35, 90], ccrs.PlateCarree())
```

### Use an overlap threshold

To restrict the region to gridcells that overlap more to a certain threshold, grid points can be masked out using `where`:

```threshold = 0.5

```

This sets all grid points with an overlap of less than 50% to 0. The second options is to convert the fractional mask to a boolean one:

```mask_3D_bool = mask_3D_frac_approx >= threshold
```

### Calculate weighted regional averages

As for the boolan 3D mask, we can calculate the regional averages using fractional mask. In this case each grid point contributes according to its overlap and area. As proxy of the grid cell area we use `cos(lat)`.

Note

It is better to use a model’s original grid cell area (e.g. `areacella`). `cos(lat)` works reasonably well for regular lat/ lon grids. For irregular grids (regional models, ocean models, …) it is not appropriate.

```weights = np.cos(np.deg2rad(airtemps.lat))

ts_airtemps_regional = airtemps.weighted(mask_3D_frac_approx * weights).mean(dim=("lat", "lon"))
```

This is almost the same as for the boolean 3D mask: by multiplying `mask_3D * weights` we get a DataArray where the fractional overlap is scaled by the grid cell area. `airtemps.weighted(mask_3D * weights).mean(["lat", "lon"])` calculates the weighted `mean` over the lat and lon dimensions:

```ts_airtemps_regional
```
```<xarray.Dataset> Size: 234kB
Dimensions:  (time: 2920, region: 9)
Coordinates:
* time     (time) datetime64[ns] 23kB 2013-01-01 ... 20...
* region   (region) int64 72B 0 1 2 3 4 5 6 7 8
abbrevs  (region) <U3 108B 'GIC' 'NWN' ... 'SCA' 'CAR'
names    (region) <U17 612B 'Greenland/Iceland' ... '...
Data variables:
air      (time, region) float64 210kB 251.4 ... 299.3```

The regionally-averaged time series can be plotted:

```ts_airtemps_regional.air.sel(region=slice(0, 2)).plot(col="region", col_wrap=3);
```

## References

• Iturbide, M., Gutiérrez, J. M., Alves, L. M., Bedia, J., Cerezo-Mota, R., Cimadevilla, E., Cofiño, A. S., Di Luca, A., Faria, S. H., Gorodetskaya, I. V., Hauser, M., Herrera, S., Hennessy, K., Hewitt, H. T., Jones, R. G., Krakovska, S., Manzanas, R., Martínez-Castro, D., Narisma, G. T., Nurhati, I. S., Pinto, I., Seneviratne, S. I., van den Hurk, B., and Vera, C. S.: An update of IPCC climate reference regions for subcontinental analysis of climate model data: definition and aggregated datasets, Earth Syst. Sci. Data, 12, 2959–2970, https://doi.org/10.5194/essd-12-2959-2020, 2020.