API
Contents
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
- 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 inds
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 areasarea_tracer
andarea_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
- 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
- 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
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 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
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
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 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
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 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
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
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 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
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
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 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
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 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 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#
|
Apply a function to the given arguments in a grid-aware manner. |
|
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]