API#

Axis#

class xgcm.Axis(ds, axis_name, periodic=True, default_shifts={}, coords=None, boundary=None, fill_value=None)[source]#

An object that represents a group of coordinates that all lie along the same physical dimension but at different positions with respect to a grid cell. There are four possible positions:

Center |------o-------|——o——-|------o-------|——o——-|

[0] [1] [2] [3]

Left |------o-------|——o——-|------o-------|——o——-|

[0] [1] [2] [3]

Right |------o-------|——o——-|------o-------|——o——-|

[0] [1] [2] [3]

Inner |------o-------|——o——-|------o-------|——o——-|

[0] [1] [2]

Outer |------o-------|——o——-|------o-------|——o——-|

[0] [1] [2] [3] [4]

The center position is the only one without the c_grid_axis_shift attribute, which must be present for the other four. However, the actual value of c_grid_axis_shift is ignored for inner and outer, which are differentiated by their length.

__init__(ds, axis_name, periodic=True, default_shifts={}, coords=None, boundary=None, fill_value=None)[source]#

Create a new Axis object from an input dataset.

Parameters

dsxarray.Dataset

Contains the relevant grid information. Coordinate attributes should conform to Comodo conventions [1].

axis_namestr

The name of the axis (should match axis attribute)

periodicbool, optional

Whether the domain is periodic along this axis

default_shiftsdict, optional

Default mapping from and to grid positions (e.g. {‘center’: ‘left’}). Will be inferred if not specified.

coordsdict, optional

Mapping of axis positions to coordinate names (e.g. {‘center’: ‘XC’, ‘left: ‘XG’})

boundarystr or dict, optional,

boundary can either be one of {None, ‘fill’, ‘extend’, ‘extrapolate’, ‘periodic’}

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition where the difference at the boundary will be zero.)
‘extrapolate’: Set values by extrapolating linearly from the two points nearest to the edge
‘periodic’ : Wrap arrays around. Equivalent to setting periodic=True

This sets the default value. It can be overriden by specifying the boundary kwarg when calling specific methods.

fill_valuefloat, optional

The value to use in the boundary condition when boundary=’fill’.

References

1: Comodo Conventions https://web.archive.org/web/20160417032300/http://pycomodo.forge.imag.fr/norm.html

cumsum(da, to=None, boundary=None, fill_value=0.0, keep_coords=False)[source]#

Cumulatively sum a DataArray, transforming to the intermediate axis position.

Parameters

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

fill_valuefloat, optional

The value to use in the boundary condition with boundary=’fill’.

keep_coordsboolean, optional

Preserves compatible coordinates. False by default.

Returns

da_cumxarray.DataArray: The cumsummed data

diff(da, to=None, boundary=None, fill_value=None, boundary_discontinuity=None, vector_partner=None, keep_coords=False)[source]#

Difference neighboring points to the intermediate grid point.

Parameters

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

fill_valuefloat, optional

The value to use in the boundary condition with boundary=’fill’.

vector_partnerdict, optional

A single key (string), value (DataArray)

keep_coordsboolean, optional

Preserves compatible coordinates. False by default.

Returns

da_ixarray.DataArray: The differenced data

interp(da, to=None, boundary=None, fill_value=None, boundary_discontinuity=None, vector_partner=None, keep_coords=False)[source]#

Interpolate neighboring points to the intermediate grid point along this axis.

Parameters

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

fill_valuefloat, optional

The value to use in the boundary condition with boundary=’fill’.

vector_partnerdict, optional

A single key (string), value (DataArray)

keep_coordsboolean, optional

Preserves compatible coordinates. False by default.

Returns

da_ixarray.DataArray: The interpolated data

max(da, to=None, boundary=None, fill_value=None, boundary_discontinuity=None, vector_partner=None, keep_coords=False)[source]#

Maximum of neighboring points on intermediate grid point.

Parameters

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

fill_valuefloat, optional

The value to use in the boundary condition with boundary=’fill’.

vector_partnerdict, optional

A single key (string), value (DataArray)

keep_coordsboolean, optional

Preserves compatible coordinates. False by default.

Returns

da_ixarray.DataArray: The differenced data

min(da, to=None, boundary=None, fill_value=None, boundary_discontinuity=None, vector_partner=None, keep_coords=False)[source]#

Minimum of neighboring points on intermediate grid point.

Parameters

daxarray.DataArray

The data on which to operate

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

fill_valuefloat, optional

The value to use in the boundary condition with boundary=’fill’.

vector_partnerdict, optional

A single key (string), value (DataArray)

keep_coordsboolean, optional

Preserves compatible coordinates. False by default.

Returns

da_ixarray.DataArray: The differenced data

transform(da, target, target_data=None, method='linear', mask_edges=True, bypass_checks=False, suffix='_transformed')[source]#

Convert an array of data to new 1D-coordinates. The method takes a multidimensional array of data da and transforms it onto another data_array target_data in the direction of the axis (for each 1-dimensional ‘column’).

target_data can be e.g. the existing coordinate along an axis, like depth. xgcm automatically detects the appropriate coordinate and then transforms the data from the input positions to the desired positions defined in target. This is the default behavior. The method can also be used for more complex cases like transforming a dataarray into new coordinates that are defined by e.g. a tracer field like temperature, density, etc.

Currently three methods are supported to carry out the transformation:

‘linear’: Values are linear interpolated between 1D columns along axis of da and target_data. This method requires target_data to increase/decrease monotonically. target values are interpreted as new cell centers in this case. By default this method will return nan for values in target that are outside of the range of target_data, setting mask_edges=False results in the default np.interp behavior of repeated values.
‘log’: Same as ‘linear’, but with values interpolated logarithmically between 1D columns. Operates by applying np.log to the target and target data values prior to linear interpolation.
‘conservative’: Values are transformed while conserving the integral of da along each 1D column. This method can be used with non-monotonic values of target_data. Currently this will only work with extensive quantities (like heat, mass, transport) but not with intensive quantities (like temperature, density, velocity). N given target values are interpreted as cell-bounds and the returned array will have N-1 elements along the newly created coordinate, with coordinate values that are interpolated between target values.

Parameters

daxr.xr.DataArray: Input data
target{np.array, xr.DataArray}: Target points for transformation. Depending on the method is interpreted as cell center (method=’linear’ and method=’log’) or cell bounds (method=’conservative). Values correspond to target_data or the existing coordinate along the axis (if target_data=None). The name of the resulting new coordinate is determined by the input type. When passed as numpy array the resulting dimension is named according to target_data, if provided as xr.Dataarray naming is inferred from the target input.
target_dataxr.DataArray, optional: Data to transform onto (e.g. a tracer like density or temperature). Defaults to None, which infers the appropriate coordinate along axis (e.g. the depth).
methodstr, optional: Method used to transform, by default “linear”
mask_edgesbool, optional: If activated, target values outside the range of target_data are masked with nan, by default True. Only applies to ‘linear’ and ‘log’ methods.
bypass_checksbool, optional: Only applies for method=’linear’ and method=’log’. Option to bypass logic to flip data if monotonically decreasing along the axis. This will improve performance if True, but the user needs to ensure that values are increasing along the axis.
suffixstr, optional: Customizable suffix to the name of the output array. This will be added to the original name of da. Defaults to _transformed.

Returns

xr.DataArray: The transformed data

Grid#

class xgcm.Grid(ds, check_dims=True, periodic=True, default_shifts={}, face_connections=None, coords=None, metrics=None, boundary=None, fill_value=None)[source]#

An object with multiple xgcm.Axis objects representing different independent axes.

__init__(ds, check_dims=True, periodic=True, default_shifts={}, face_connections=None, coords=None, metrics=None, boundary=None, fill_value=None)[source]#

Create a new Grid object from an input dataset.

Parameters

dsxarray.Dataset

Contains the relevant grid information. Coordinate attributes should conform to Comodo conventions [1].

check_dimsbool, optional

Whether to check the compatibility of input data dimensions before performing grid operations.

periodic{True, False, list}

Whether the grid is periodic (i.e. “wrap-around”). If a list is specified (e.g. ['X', 'Y']), the axis names in the list will be be periodic and any other axes founds will be assumed non-periodic.

default_shiftsdict

A dictionary of dictionaries specifying default grid position shifts (e.g. {'X': {'center': 'left', 'left': 'center'}})

face_connectionsdict

Grid topology

coordsdict, optional

Specifies positions of dimension names along axes X, Y, Z, e.g {'X': {'center': 'XC', 'left: 'XG'}}. Each key should be an axis name (e.g., X, Y, or Z) and map to a dictionary which maps positions (center, left, right, outer, inner) to dimension names in the dataset (in the example above, XC is at the center position and XG at the left position along the X axis). If the values are not present in ds or are not dimensions, an error will be raised.

metricsdict, optional

Specification of grid metrics mapping axis names (X, Y, Z) to corresponding metric variable names in the dataset (e.g. {(‘X’,):[‘dx_t’], (‘X’, ‘Y’):[‘area_tracer’, ‘area_u’]} for the cell distance in the x-direction dx_t and the horizontal cell areas area_tracer and area_u, located at different grid positions).

boundary{None, ‘fill’, ‘extend’, ‘extrapolate’, dict}, optional

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)
‘extrapolate’: Set values by extrapolating linearly from the two points nearest to the edge

Optionally a dict mapping axis name to seperate values for each axis can be passed.

fill_value{float, dict}, optional

The value to use in boundary conditions with boundary=’fill’. Optionally a dict mapping axis name to seperate values for each axis can be passed.

References

1: Comodo Conventions https://web.archive.org/web/20160417032300/http://pycomodo.forge.imag.fr/norm.html

apply_as_grid_ufunc(func: Callable, *args: xarray.core.dataarray.DataArray, axis: Optional[Sequence[Sequence[str]]] = None, signature: Union[str, xgcm.grid_ufunc._GridUFuncSignature] = '', boundary_width: Optional[Mapping[str, Tuple[int, int]]] = None, boundary: Optional[Union[str, Mapping[str, str]]] = None, fill_value: Optional[Union[float, Mapping[str, float]]] = None, dask: Literal['forbidden', 'parallelized', 'allowed'] = 'forbidden', map_overlap: bool = False, **kwargs)[source]#

Apply a function to the given arguments in a grid-aware manner.

The relationship between xgcm axes on the input and output are specified by signature. Wraps xarray.apply_ufunc, but determines the core dimensions from the grid and signature passed.

Parameters

funccallable

Function to call like func(*args, **kwargs) on numpy-like unlabeled arrays (.data).

Passed directly on to xarray.apply_ufunc.

*argsxarray.DataArray

One or more xarray DataArray objects to apply the function to.

axisSequence[Sequence[str]], optional

Names of xgcm.Axes on which to act, for each array in args. Multiple axes can be passed as a sequence (e.g. ['X', 'Y']). Function will be executed over all Axes simultaneously, and each Axis must be present in the Grid.

signaturestring

Grid universal function signature. Specifies the xgcm.Axis names and positions for each input and output variable, e.g.,

"(X:center)->(X:left)" for ``diff_center_to_left(a)`.

boundary_widthDict[str: Tuple[int, int]

The widths of the boundaries at the edge of each array. Supplied in a mapping of the form {axis_name: (lower_width, upper_width)}.

boundary{None, ‘fill’, ‘extend’, ‘extrapolate’, dict}, optional

A flag indicating how to handle boundaries: * None: Do not apply any boundary conditions. Raise an error if

boundary conditions are required for the operation.

‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)
‘extrapolate’: Set values by extrapolating linearly from the two points nearest to the edge

Optionally a dict mapping axis name to separate values for each axis can be passed.

fill_value{float, dict}, optional

The value to use in boundary conditions with boundary=’fill’. Optionally a dict mapping axis name to separate values for each axis can be passed. Default is 0.

dask{“forbidden”, “allowed”, “parallelized”}, default: “forbidden”

How to handle applying to objects containing lazy data in the form of dask arrays. Passed directly on to xarray.apply_ufunc.

map_overlapbool, optional

Whether or not to automatically apply the function along chunked core dimensions using dask.array.map_overlap. Default is False. If True, will need to be accompanied by dask=’allowed’.

Returns

results: The result of the call to xarray.apply_ufunc, but including the coordinates given by the signature, which are read from the grid. Output is either a single object or a tuple of such objects.

See also

apply_as_grid_ufunc
as_grid_ufunc

average(da, axis, **kwargs)[source]#

Perform weighted mean reduction along specified axis or axes, accounting for grid metrics. (e.g. cell length, area, volume)

Parameters

axisstr, list of str: Name of the axis on which to act
**kwargs: dict: Additional arguments passed to xarray.DataArray.weighted.mean

Returns

da_ixarray.DataArray: The averaged data

cumint(da, axis, **kwargs)[source]#

Perform cumulative integral along specified axis or axes, accounting for grid metrics. (e.g. cell length, area, volume)

Parameters

axisstr or list or tuple

Name of the axis on which to act. Multiple axes can be passed as list or tuple (e.g. ['X', 'Y']). Functions will be executed over each axis in the given order.

tostr or dict, optional

The direction in which to shift the array (can be [‘center’,’left’,’right’,’inner’,’outer’]). If not specified, default will be used. Optionally a dict with separate values for each axis can be passed (see example)

boundaryNone or str or dict, optional

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

Optionally a dict with separate values for each axis can be passed.

fill_value{float, dict}, optional

The value to use in the boundary condition with boundary=’fill’. Optionally a dict with separate values for each axis can be passed.

metric_weightedstr or tuple of str or dict, optional

Optionally use metrics to multiply/divide with appropriate metrics before/after the operation. E.g. if passing metric_weighted=[‘X’, ‘Y’], values will be weighted by horizontal area. If False (default), the points will be weighted equally. Optionally a dict with seperate values for each axis can be passed.

Returns

da_ixarray.DataArray: The cumulatively integrated data

cumsum(da: xarray.core.dataarray.DataArray, axis: Union[str, Iterable[str]], to=None, boundary=None, fill_value=None, metric_weighted=None, keep_coords: bool = False) → xarray.core.dataarray.DataArray[source]#

Cumulatively sum a DataArray, transforming to the intermediate axis position.

Parameters

da: xarray.DataArray

Data to apply cumsum to.

axisstr or list or tuple

Name of the axis on which to act. Multiple axes can be passed as list or tuple (e.g. ['X', 'Y']). Functions will be executed over each axis in the given order.

tostr or dict, optional

The direction in which to shift the array (can be [‘center’,’left’,’right’,’inner’,’outer’]). If not specified, default will be used. Optionally a dict with seperate values for each axis can be passed (see example)

boundaryNone or str or dict, optional

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

Optionally a dict with separate values for each axis can be passed (see example)

fill_value{float, dict}, optional

The value to use in the boundary condition with boundary=’fill’. Optionally a dict with seperate values for each axis can be passed (see example)

metric_weightedstr or tuple of str or dict, optional

Returns

da_ixarray.DataArray: The cumsummed data

Examples

Each keyword argument can be provided as a per-axis dictionary. For instance, if we want to compute the cumulative sum of global 2D dataset in both X and Y axis, but the fill value at the boundary should be different for each axis, we can do this:

>>> grid.max(da, ["X", "Y"], fill_value={"X": 0, "Y": 100})

derivative(da, axis, **kwargs)[source]#

Take the centered-difference derivative along specified axis.

Parameters

axisstr or list or tuple

Name of the axis on which to act. Multiple axes can be passed as list or tuple (e.g. ['X', 'Y']). Functions will be executed over each axis in the given order.

tostr or dict, optional

boundaryNone or str or dict, optional

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

Optionally a dict with separate values for each axis can be passed (see example)

fill_value{float, dict}, optional

The value to use in the boundary condition with boundary=’fill’. Optionally a dict with seperate values for each axis can be passed (see example)

vector_partnerdict, optional

A single key (string), value (DataArray). Optionally a dict with seperate values for each axis can be passed (see example)

metric_weightedstr or tuple of str or dict, optional

Returns

da_ixarray.DataArray: The differentiated data

diff(da, axis, **kwargs)[source]#

Difference neighboring points to the intermediate grid point.

Parameters

axisstr or list or tuple

Name of the axis on which to act. Multiple axes can be passed as list or tuple (e.g. ['X', 'Y']). Functions will be executed over each axis in the given order.

tostr or dict, optional

boundaryNone or str or dict, optional

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

Optionally a dict with separate values for each axis can be passed (see example)

fill_value{float, dict}, optional

The value to use in the boundary condition with boundary=’fill’. Optionally a dict with seperate values for each axis can be passed (see example)

vector_partnerdict, optional

A single key (string), value (DataArray). Optionally a dict with seperate values for each axis can be passed (see example)

metric_weightedstr or tuple of str or dict, optional

Returns

da_ixarray.DataArray: The differenced data

Examples

Each keyword argument can be provided as a per-axis dictionary. For instance, if a global 2D dataset should be differenced on both X and Y axis, but the fill value at the boundary should be differenc for each axis, we can do this:

>>> grid.diff(da, ["X", "Y"], fill_value={"X": 0, "Y": 100})

diff_2d_vector(vector, **kwargs)[source]#

Difference a 2D vector to the intermediate grid point. This method is only necessary for complex grid topologies.

Parameters

vectordict: A dictionary with two entries. Keys are axis names, values are vector components along each axis.
%(neighbor_binary_func.parameters.no_f)s

Returns

vector_diffdict: A dictionary with two entries. Keys are axis names, values are differenced vector components along each axis

get_metric(array, axes)[source]#

Find the metric variable associated with a set of axes for a particular array.

Parameters

arrayxarray.DataArray: The array for which we are looking for a metric. Only its dimensions are considered.
axesiterable: A list of axes for which to find the metric.

Returns

metricxarray.DataArray: A metric which can broadcast against array

integrate(da, axis, **kwargs)[source]#

Perform finite volume integration along specified axis or axes, accounting for grid metrics. (e.g. cell length, area, volume)

Parameters

axisstr, list of str: Name of the axis on which to act
**kwargs: dict: Additional arguments passed to xarray.DataArray.sum

Returns

da_ixarray.DataArray: The integrated data

interp(da, axis, **kwargs)[source]#

Interpolate neighboring points to the intermediate grid point along this axis.

Parameters

axisstr or list or tuple

Name of the axis on which to act. Multiple axes can be passed as list or tuple (e.g. ['X', 'Y']). Functions will be executed over each axis in the given order.

tostr or dict, optional

boundaryNone or str or dict, optional

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

Optionally a dict with separate values for each axis can be passed (see example)

fill_value{float, dict}, optional

The value to use in the boundary condition with boundary=’fill’. Optionally a dict with seperate values for each axis can be passed (see example)

vector_partnerdict, optional

A single key (string), value (DataArray). Optionally a dict with seperate values for each axis can be passed (see example)

metric_weightedstr or tuple of str or dict, optional

Returns

da_ixarray.DataArray: The interpolated data

Examples

Each keyword argument can be provided as a per-axis dictionary. For instance, if a global 2D dataset should be interpolated on both X and Y axis, but it is only periodic in the X axis, we can do this:

>>> grid.interp(da, ["X", "Y"], periodic={"X": True, "Y": False})

interp_2d_vector(vector, **kwargs)[source]#

Interpolate a 2D vector to the intermediate grid point. This method is only necessary for complex grid topologies.

Parameters

vectordict

A dictionary with two entries. Keys are axis names, values are vector components along each axis.

to{‘center’, ‘left’, ‘right’, ‘inner’, ‘outer’}

The direction in which to shift the array. If not specified, default will be used.

boundary{None, ‘fill’, ‘extend’}

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

fill_valuefloat, optional

The value to use in the boundary condition with boundary=’fill’.

vector_partnerdict, optional

A single key (string), value (DataArray)

keep_coordsboolean, optional

Preserves compatible coordinates. False by default.

Returns

vector_interpdict: A dictionary with two entries. Keys are axis names, values are interpolated vector components along each axis

interp_like(array, like, boundary=None, fill_value=None)[source]#

Compares positions between two data arrays and interpolates array to the position of like if necessary

Parameters

arrayDataArray

DataArray to interpolate to the position of like

likeDataArray

DataArray with desired grid positions for source array

boundarystr or dict, optional,

boundary can either be one of {None, ‘fill’, ‘extend’, ‘extrapolate’} * None: Do not apply any boundary conditions. Raise an error if

boundary conditions are required for the operation.

‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition where the difference at the boundary will be zero.)
‘extrapolate’: Set values by extrapolating linearly from the two points nearest to the edge

This sets the default value. It can be overriden by specifying the boundary kwarg when calling specific methods.

fill_valuefloat, optional

The value to use in the boundary condition when boundary=’fill’.

Returns

arrayDataArray: Source data array with updated positions along axes matching with target array

max(da, axis, **kwargs)[source]#

Maximum of neighboring points on the intermediate grid point.

Parameters

axisstr or list or tuple

Name of the axis on which to act. Multiple axes can be passed as list or tuple (e.g. ['X', 'Y']). Functions will be executed over each axis in the given order.

tostr or dict, optional

boundaryNone or str or dict, optional

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

Optionally a dict with separate values for each axis can be passed (see example)

fill_value{float, dict}, optional

The value to use in the boundary condition with boundary=’fill’. Optionally a dict with seperate values for each axis can be passed (see example)

vector_partnerdict, optional

A single key (string), value (DataArray). Optionally a dict with seperate values for each axis can be passed (see example)

metric_weightedstr or tuple of str or dict, optional

Returns

da_ixarray.DataArray: The maximum data

Examples

Each keyword argument can be provided as a per-axis dictionary. For instance, if we want to find the maximum of sourrounding grid cells for a global 2D dataset in both X and Y axis, but the fill value at the boundary should be different for each axis, we can do this:

>>> grid.max(da, ["X", "Y"], fill_value={"X": 0, "Y": 100})

min(da, axis, **kwargs)[source]#

Minimum of neighboring points on the intermediate grid point.

Parameters

axisstr or list or tuple

Name of the axis on which to act. Multiple axes can be passed as list or tuple (e.g. ['X', 'Y']). Functions will be executed over each axis in the given order.

tostr or dict, optional

boundaryNone or str or dict, optional

A flag indicating how to handle boundaries:

None: Do not apply any boundary conditions. Raise an error if boundary conditions are required for the operation.
‘fill’: Set values outside the array boundary to fill_value (i.e. a Dirichlet boundary condition.)
‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Neumann boundary condition.)

Optionally a dict with separate values for each axis can be passed (see example)

fill_value{float, dict}, optional

The value to use in the boundary condition with boundary=’fill’. Optionally a dict with seperate values for each axis can be passed (see example)

vector_partnerdict, optional

A single key (string), value (DataArray). Optionally a dict with seperate values for each axis can be passed (see example)

metric_weightedstr or tuple of str or dict, optional

Returns

da_ixarray.DataArray: The mimimum data

Examples

Each keyword argument can be provided as a per-axis dictionary. For instance, if we want to find the minimum of sourrounding grid cells for a global 2D dataset in both X and Y axis, but the fill value at the boundary should be different for each axis, we can do this:

>>> grid.min(da, ["X", "Y"], fill_value={"X": 0, "Y": 100})

transform(da, axis, target, **kwargs)[source]#

Convert an array of data to new 1D-coordinates along axis. The method takes a multidimensional array of data da and transforms it onto another data_array target_data in the direction of the axis (for each 1-dimensional ‘column’).

Currently three methods are supported to carry out the transformation:

‘linear’: Values are linear interpolated between 1D columns along axis of da and target_data. This method requires target_data to increase/decrease monotonically. target values are interpreted as new cell centers in this case. By default this method will return nan for values in target that are outside of the range of target_data, setting mask_edges=False results in the default np.interp behavior of repeated values.
‘log’: Same as ‘linear’, but with values interpolated logarithmically between 1D columns. Operates by applying np.log to the target and target data values prior to linear interpolation.
‘conservative’: Values are transformed while conserving the integral of da along each 1D column. This method can be used with non-monotonic values of target_data. Currently this will only work with extensive quantities (like heat, mass, transport) but not with intensive quantities (like temperature, density, velocity). N given target values are interpreted as cell-bounds and the returned array will have N-1 elements along the newly created coordinate, with coordinate values that are interpolated between target values.

Parameters

daxr.DataArray: Input data
axisstr: Name of the axis on which to act
target{np.array, xr.DataArray}: Target points for transformation. Depending on the method is interpreted as cell center (method=’linear’ and method=’log’) or cell bounds (method=’conservative). Values correspond to target_data or the existing coordinate along the axis (if target_data=None). The name of the resulting new coordinate is determined by the input type. When passed as numpy array the resulting dimension is named according to target_data, if provided as xr.Dataarray naming is inferred from the target input.
target_dataxr.DataArray, optional: Data to transform onto (e.g. a tracer like density or temperature). Defaults to None, which infers the appropriate coordinate along axis (e.g. the depth).
methodstr, optional: Method used to transform, by default “linear”
mask_edgesbool, optional: If activated, target values outside the range of target_data are masked with nan, by default True. Only applies to ‘linear’ and ‘log’ methods.
bypass_checksbool, optional: Only applies for method=’linear’ and method=’log’. Option to bypass logic to flip data if monotonically decreasing along the axis. This will improve performance if True, but the user needs to ensure that values are increasing along the axis.
suffixstr, optional: Customizable suffix to the name of the output array. This will be added to the original name of da. Defaults to _transformed.

Returns

xr.DataArray: The transformed data

Grid ufuncs#

`xgcm.apply_as_grid_ufunc`(func, *args[, ...])	Apply a function to the given arguments in a grid-aware manner.
`xgcm.as_grid_ufunc`([signature, boundary_width])	Decorator which turns a numpy ufunc into a "grid-aware ufunc".

autogenerate#

xgcm.autogenerate.generate_axis(ds, axis, name, axis_dim, pos_from='center', pos_to='left', boundary_discontinuity=None, pad='auto', new_name=None, attrs_from_scratch=True)[source]#

Creates c-grid dimensions (or coordinates) along an axis of

Parameters

dsxarray.Dataset: Dataset with gridinformation used to construct c-grid
axisstr: The appropriate xgcm axis. E.g. ‘X’ for longitudes.
namestr: The name of the variable in ds, providing the original grid.
axis_dimstr: The dimension of ds[name] corresponding to axis. If name itself is a dimension, this should be equal to name.
pos_from{‘center’,’left’,’right’}, optional: Position of the gridpoints given in ‘ds’.
pos_to{‘left’,’center’,’right’}, optional: Position of the gridpoints to be generated.
boundary_discontinuity{None, float}, optional: If specified, marks the value of discontinuity across boundary, e.g. 360 for global longitude values and 180 for global latitudes.
pad{‘auto’, None, float}, optional: If specified, determines the padding to be applied across boundary. If float is specified, that value is used as padding. Auto attempts to pad linearly extrapolated values. Can be useful for e.g. depth coordinates (to reconstruct 0 depth). Can lead to unexpected values when coordinate is multidimensional.
new_namestr, optional: Name of the inferred grid variable. Defaults to name+’_’+pos_to’
attrs_from_scratchbool, optional: Determines if the attributes are created from scratch. Should be enabled for dimensions and deactivated for multidimensional coordinates. These can only be calculated after the dims are created.

xgcm.autogenerate.generate_grid_ds(ds, axes_dims_dict, axes_coords_dict=None, position=None, boundary_discontinuity=None, pad='auto', new_name=None)[source]#

Add c-grid dimensions and coordinates (optional) to observational Dataset

Parameters

dsxarray.Dataset: Dataset with gridinformation used to construct c-grid
axes_dims_dictdict: Dict with information on the dimension in ds corrsponding to the xgcm axis. E.g. {‘X’:’lon’,’Y’:’lat’}
axes_coords_dictdict, optional: Dict with information on the coordinates in ds corrsponding to the xgcm axis. E.g. {‘X’:’geolon’,’Y’:’geolat’}
position{None,tuple, dict}, optional: Position of the gridpoints given in ‘ds’ and the desired position to be generated. Defaults to (‘center’,’left’). Can be a tuple like (‘center’,’left’), or a dict with corresponding axes (e.g. {‘X’:(‘center’,’left’),’Z’:(‘left’,’center’)})
boundary_discontinuity{None, float, dict}, optional: Specifies the discontinuity at the boundary to wrap e.g. longitudes without artifacts. Can be defined globally (for all fields defined in axes_dims_dict and axes_coords_dict) {float, None} or per dataset variable (dict e.g. {‘longitude’:360,’latitude’:180})
pad{‘auto’, None, float}, optional: Specifies the padding at the boundary to extend values past the boundary. Can be defined globally (for all fields defined in axes_dims_dict and axes_coords_dict) {float, None} or per dataset variable ({dict} e.g. {‘z’:’auto’,’latitude’:0.0})
new_namestr, optional: Name of the inferred grid variable. Defaults to name+’_’+position[1]

xgcm v0.8 documentation

API

Contents

API#

Axis#

Grid#

Grid ufuncs#

autogenerate#