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’}

  • 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’.

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’.

vector_partnerdict, optional

A single key (string), value (DataArray)

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 two 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.

  • ‘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’) or cell bounds (method=’conservative). Values correpond 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’ method.

bypass_checksbool, optional

Only applies for method=’linear’. 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.

keep_coordsboolean, optional

Preserves compatible coordinates. False by default.

References

1

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

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, list of str

Name of the axis on which to act

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)

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

If an axis or list of axes is specified, the appropriate grid metrics will be used to determined the weight for interpolation. 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 (see example)

Returns
da_ixarray.DataArray

The cumulatively integrated data

cumsum(da, axis, **kwargs)[source]

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

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 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)

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

If an axis or list of axes is specified, the appropriate grid metrics will be used to determined the weight for interpolation. 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 (see example)

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

Name of the axis on which to act

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)

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

If an axis or list of axes is specified, the appropriate grid metrics will be used to determined the weight for interpolation. 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 (see example)

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

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)

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

If an axis or list of axes is specified, the appropriate grid metrics will be used to determined the weight for interpolation. 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 (see example)

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.

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
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

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)

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

If an axis or list of axes is specified, the appropriate grid metrics will be used to determined the weight for interpolation. 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 (see example)

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.

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
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

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)

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

If an axis or list of axes is specified, the appropriate grid metrics will be used to determined the weight for interpolation. 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 (see example)

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

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)

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

If an axis or list of axes is specified, the appropriate grid metrics will be used to determined the weight for interpolation. 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 (see example)

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’).

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 two 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.

  • ‘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. Dependin on the method is interpreted as cell center (method=’linear’) or cell bounds (method=’conservative). Values correpond 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’ method.

bypass_checksbool, optional

Only applies for method=’linear’. 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 alon 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

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]