Region masks#

POP includes a default region mask as a component of the grid information. This is often not super relevant for analyses. pop_tools provides several alternative region masks; these are demostrated here.

Import packages#

%matplotlib inline
import matplotlib.colors as colors
import matplotlib.pyplot as plt
import numpy as np
import xarray as xr

import pop_tools

Plot default `REGION_MASK`#

The default REGION_MASK is a 2-D array with unique integer values for each region. Negative integers denote “marginal seas,” which are not directly connected to the ocean.

regions = np.array(np.unique(ds.REGION_MASK))
regions

array([-13, -12,  -5,   0,   1,   2,   3,   4,   6,   7,   8,   9,  10,
        11], dtype=int32)

ds.REGION_MASK.plot.contourf(levels=regions, cmap='tab20');

../_images/e5f071def04670f8d402402bc32a9888965e5058c1f54178ab26414143eafd22.png

Alternative region masks#

Other useful region masks are pre-defined in the package. list_region_masks returns a list of pre-defined masks.

region_masks = pop_tools.list_region_masks(grid_name)
region_masks

['lat-range-basin', 'Pacific-Indian-Atlantic']

We can visualize all of these using the helper function above.

for region_mask in region_masks:
    mask3d = pop_tools.region_mask_3d(grid_name, mask_name=region_mask)
    visualize_mask(mask3d)

../_images/8cf52b75fb6e8b99e0784a11c681ee36d2ca975a6a6678639d480c456ebfb620.png

../_images/b1841eef26efc9049c08b27641da26a9527356e7719a5f6a9230837a2ad4df52.png

To illustrated how regions cover the global domain, including with overlap, we can sum over the region dimension.

mask3d = pop_tools.region_mask_3d(grid_name, mask_name='lat-range-basin')
mask3d.sum('region').plot();

../_images/0fc51c3a146950b10bf7d897099fcec9b638b5bf489978c6237d3f0688dde0e4.png

User defined region masks#

Finally, it is also possible to make a region mask on the fly by building a dictionary containing the defining logic. region_mask_3d accepts a region_defs argument. This is a dictionary of the following form.

region_defs = {region1_name: list_of_criteria_dicts_1, 
               region2_name: list_of_criteria_dicts_2,...}

The list_of_criteria_dicts are lists of dictionaries; each must include the keys ‘match’ or ‘bounds’. For instance:

list_of_criteria_dicts_1 = [{'match': {'REGION_MASK': [1, 2, 3, 6]}, 
                             'bounds': {'TLAT': [-90., -30.]}}]

will return a mask where the default REGION_MASK matches the specified values and TLAT falls between the specified bounds. Multiple entries in the list_of_criteria_dicts are applied with an “or” condition.

Here’s an example region mask generated for the North Atlantic Subpolar and Subtropical Gyres.

region_defs = {
    'NAtl-STG': [
        {'match': {'REGION_MASK': [6]}, 'bounds': {'TLAT': [32.0, 42.0], 'TLONG': [310.0, 350.0]}}
    ],
    'NAtl-SPG': [
        {'match': {'REGION_MASK': [6]}, 'bounds': {'TLAT': [50.0, 60.0], 'TLONG': [310.0, 350.0]}}
    ],
}

mask3d = pop_tools.region_mask_3d(grid_name, region_defs=region_defs, mask_name='N. Atlantic Gyres')
visualize_mask(mask3d)

../_images/e5ea60f90eee8379f814cf2f9d09ba35c1ed48907b694e1f2f7330c3ad6d75f2.png

%load_ext watermark
%watermark -d -iv -m -g -h

Compiler    : GCC 11.3.0
OS          : Linux
Release     : 5.15.0-1004-aws
Machine     : x86_64
Processor   : x86_64
CPU cores   : 2
Architecture: 64bit

Hostname: build-21213814-project-451810-pop-tools

Git hash: d3c80c0576ae4838c0e04a0157734eb0c977e613

pop_tools : 2023.3.0.post2+dirty
xarray    : 2023.6.0
matplotlib: 3.7.1
numpy     : 1.24.4

Region masks

Contents

Region masks#

Import packages#

Load POP grid as `xarray.Dataset`#

Plot default `REGION_MASK`#

More useful region masks#

Alternative region masks#

User defined region masks#

Region masks

Contents

Region masks#

Import packages#

Load POP grid as xarray.Dataset#

Plot default REGION_MASK#

More useful region masks#

Alternative region masks#

User defined region masks#

Load POP grid as `xarray.Dataset`#

Plot default `REGION_MASK`#