regionate

Create xgcm-grid-consistent regional masks and boundaries for ocean model output.

regionate turns a geographic polygon into a discrete, grid-aware region: it snaps the polygon to a model grid and produces a boolean cell mask plus the staggered (u, v) velocity faces that trace the region’s boundary. Because the mask and the boundary faces come from the same construction, a volume, mass, or heat budget integrated over the masked region is exactly consistent with the fluxes through its boundary — the property that makes closed regional budgets possible.

It leans on its sibling package sectionate for the section- and face-tracing math, and builds on xgcm grids.

The central object is GriddedRegion (a polygon bound to an xgcm.Grid); BoundedRegion defines a region from named sections instead of a raw polygon, and Regions collects many of them. See the worked examples below for thickness, heat, and mass budgets over named regions.

Contents

• Installation
  • Requirements
  • From conda-forge
  • From PyPI
  • From GitHub (development version)
• Horizontal convergence of thickness fluxes
  • Analysis of vertically-integrated thickness budget
• Horizontal convergence of vertically-integrated heat fluxes
  • 1. Load data
  • 2. Explanatory analysis of the heat budget terms
  • 3. Regional heat budgets
• Corner case: bipolar grid fold
  • 0. Load data
  • 1. Determine a mask for the region of interest.
  • 2. We use regionate to find the sections that bound the region
  • 3. We use sectionate to compute the advective heat fluxes that converge into the region.
  • 4. We verify our calculation by comparing against the volume integral of the masked tendency terms
  • 5. The pay-off: understanding advective tendencies by tracing them back to boundary fluxes
• Regions bounded by a series of named sections
  • 1. Load data
  • 2. Define the BoundedRegion
  • 3. Use the BoundedRegion’s mask to compute the net heat flux convergence
  • 4. Use the grid indices of the BoundedRegion’s boundary to compute convergent heat fluxes along the boundary
  • 5. Testing that our methods satisfy the divergence theorem on the model grid
• Contributor guide
  • Development environment
  • Example notebooks
  • Building the docs
• API reference
  • regionate