xwmt.wm module

xwmt.wm module#

class xwmt.wm.WaterMass(grid, t_name='thetao', s_name='so', h_name='thkcello', eos=<object object>, cp=3992.0, rho_ref=1035.0, t_var='conservative', s_var='absolute', teos10=None)#

Bases: object

Stores water mass characteristics and supports methods for analyzing water masses on a numerical grid.

expand_surface_array_vertically(da_surf, target_position='outer')#

Expand surface xr.DataArray (with no “Z”-dimension coordinate) in the vertical, filling with zeros in all layers except the one that outcrops.

Parameters:

  • da_surf (xarray.DataArray) – Variable that is to be expanded in the vertical.

  • position (str) – Position of the desired vertical coordinate in the self.grid instance of xgcm.Grid. Default: “outer”. Other supported option is “center”.

get_density(density_name='rho')#

Derive a density variable from layer temperature and salinity, along with the thermal-expansion (alpha) and haline-contraction (beta) coefficients, and add them to the dataset (if not already present).

Density and the coefficients are evaluated with the equation of state selected at construction (self.eos), delegated to the xeos package. Temperature and salinity are first converted (via gsw) from the kinds declared by t_var/s_var to the kinds the EOS expects. If self.eos is None, “alpha”, “beta” and density_name must already be present in self.grid._ds.

Parameters:

density_name (str (default: "rho")) – Name of density variable. Supported density variables are: “rho” (in-situ density at the local pressure) and “sigma0”, “sigma1”, “sigma2”, “sigma3”, “sigma4” (potential density anomaly referenced to 0, 1000, …, 4000 dbar).

Return type:

xr.DataArray

Notes

Unless they were supplied by the caller at construction, “alpha” and “beta” are (re)computed at this call’s reference pressure and written to self.grid._ds. Calling get_density for different density_name`s on the same instance therefore overwrites them (each density gets alpha/beta at its own reference pressure); hold a copy if you need an earlier call’s values. The converted EOS-input temperature/salinity are used internally and are not added to `self.grid._ds.

get_outcrop_lev(position='center', incrop=False, min_thickness=1e-06)#

Return the first vertical level (starting from the relevant boundary) whose thickness exceeds min_thickness.

Assumes the native Z index increases downward (surface -> bottom).

Parameters:

  • position ({"center", "outer"}) – Vertical grid position for the coordinate/metric.

  • incrop (bool) – False (default): search from sea surface downward (“outcrop”). True: search from seafloor upward (“incrop”).

  • min_thickness (float) – Default: 1e-6. Minimum layer thickness required to count as the first “real” cell.

Returns:

Vertical coordinate value, broadcast across other dims, masked where no layer exceeds min_thickness.

Return type:

xr.DataArray

infer_bins(da, percentiles=[0.0, 1.0], nbins=100, surface=False)#

Specify bins based on the distribution of da, excluding outliers.

Parameters:

  • da (xarray.DataArray) – Variable used to determine bins.

  • percentiles (list) – List of length 2 containing the upper and lower percentiles to bound the array of bins. Default: [0., 1.], i.e. min and max.

  • nbins (int) – Number of bins. Default: 100.

  • surface (bool) – Default: False. If True, compute percentiles only from the outcropping layer of da.

sel_outcrop_lev(da, incrop=False, min_thickness=1e-06, position='center', **kwargs)#

Select da at the first vertical level (starting from the relevant boundary) whose thickness exceeds min_thickness.

Assumes the native Z index increases downward (surface -> bottom).

Parameters:

  • da (xr.DataArray) – DataArray to select from. Must have the same dims as the thickness metric after applying **kwargs.

  • incrop (bool) – Default: False. If True, selects the first thick level from the bottom upward.

  • min_thickness (float) – Minimum layer thickness required to count as the first “real” cell.

  • position ({"center", "outer"}) – Vertical grid position for the coordinate/metric.

  • **kwargs (dict) – Passed to .sel(**kwargs) on the thickness metric (and used to validate dims).

Returns:

da selected at the diagnosed level, masked where no level exceeds min_thickness.

Return type:

xr.DataArray

xwmt.wm.add_gridcoords(grid, coords, padding)#