API

Axis

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

An object that represents a group of coodinates 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__(self, ds, axis_name, periodic=True, default_shifts={}, coords=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’})

References

1

Comodo Conventions http://pycomodo.forge.imag.fr/norm.html

cumsum(self, da, to=None, boundary=None, fill_value=0.0)[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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_cumxarray.DataArray

The cumsummed data

diff(self, da, to=None, boundary=None, fill_value=0.0, boundary_discontinuity=None, vector_partner=None)[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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The differenced data

interp(self, da, to=None, boundary=None, fill_value=0.0, boundary_discontinuity=None, vector_partner=None)[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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The interpolated data

max(self, da, to=None, boundary=None, fill_value=0.0, boundary_discontinuity=None, vector_partner=None)[source]

Maximum of neighboring points on intermediate grid point.

Parameters
%(neighbor_binary_func.parameters.no_f)s
Returns
da_ixarray.DataArray

The differenced data

min(self, da, to=None, boundary=None, fill_value=0.0, boundary_discontinuity=None, vector_partner=None)[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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The differenced data

Grid

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

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

__init__(self, ds, check_dims=True, periodic=True, default_shifts={}, face_connections=None, coords=None, metrics=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

Excplicit specification of axis coordinates, e.g {'X': {'center': 'XC', 'left: 'XG'}}. Each key should be the name of an axis. The value should be a dictionary mapping positions (e.g. 'left') to names of coordinates in ds.

metricsdict, optional

Specification of grid metrics

References

1

Comodo Conventions http://pycomodo.forge.imag.fr/norm.html

average(self, 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.sum

Returns
da_ixarray.DataArray

The averaged data

cumint(self, 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

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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The cumulatively integrated data

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

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

Parameters
axisstr

Name of the axis on which to act

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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The cumsummed data

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

Take the centered-difference derivative along specified axis.

Parameters
axisstr

Name of the axis on which to act

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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The differentiated data

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

Difference neighboring points to the intermediate grid point.

Parameters
axisstr

Name of the axis on which to act

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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The differenced data

diff_2d_vector(self, 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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
vector_diffdict

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

get_metric(self, 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(self, 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(self, da, axis, metric_weighted=False, **kwargs)[source]

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

Parameters
axisstr

Name of the axis on which to act

metric_weightedstr or tuple of str

If an axis or list of axes is specified, the grid metrics will be used to determined the weight for interpolation. If False (default), the points will be weighted equally.

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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The interpolated data

interp_2d_vector(self, 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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
vector_interpdict

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

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

Maximum of neighboring points on the intermediate grid point.

Parameters
axisstr

Name of the axis on which to act

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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The maximal data

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

Minimum of neighboring points on the intermediate grid point.

Parameters
axisstr

Name of the axis on which to act

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 Neumann boundary condition.)

  • ‘extend’: Set values outside the array to the nearest array value. (i.e. a limited form of Dirichlet boundary condition.)

Returns
da_ixarray.DataArray

The minimal 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]