cf.Field.anchor

Field.anchor(*args, **kwargs)[source]

Roll a cyclic axis so that the given value lies in the first coordinate cell.

A unique axis is selected with the axes and kwargs parameters.

New in version 3.9.0.

See also

axis, cyclic, iscyclic, roll

Parameters
axis:

The cyclic axis to be anchored.

domain axis selection TODO.

value:

Anchor the dimension coordinate values for the selected cyclic axis to the value. May be any numeric scalar object that can be converted to a Data object (which includes numpy and Data objects). If value has units then they must be compatible with those of the dimension coordinates, otherwise it is assumed to have the same units as the dimension coordinates. The coordinate values are transformed so that value is “equal to or just before” the new first coordinate value. More specifically:

  • Increasing dimension coordinates with positive period, P, are transformed so that value lies in the half-open range (L-P, F], where F and L are the transformed first and last coordinate values, respectively.

  • Decreasing dimension coordinates with positive period, P, are transformed so that value lies in the half-open range (L+P, F], where F and L are the transformed first and last coordinate values, respectively.

Parameter example:

If the original dimension coordinates are 0, 5, ..., 355 (evenly spaced) and the period is 360 then value=0 implies transformed coordinates of 0, 5, ..., 355; value=-12 implies transformed coordinates of -10, -5, ..., 345; value=380 implies transformed coordinates of 380, 385, ..., 715.

Parameter example:

If the original dimension coordinates are 355, 350, ..., 0 (evenly spaced) and the period is 360 then value=355 implies transformed coordinates of 355, 350, ..., 0; value=0 implies transformed coordinates of 0, -5, ..., -355; value=392 implies transformed coordinates of 390, 385, ..., 30.

inplace: bool, optional

If True then do the operation in-place and return None.

dry_run: bool, optional

Return a dictionary of parameters which describe the anchoring process. The construct is not changed, even if inplace is True.

i: deprecated at version 3.0.0

Use the inplace parameter instead.

kwargs: deprecated at version 3.0.0

Returns

dict

Examples

>>> f.iscyclic('X')
True
>>> f.dimension_coordinate('X').data
<CF Data(8): [0, ..., 315] degrees_east> TODO
>>> print(f.dimension_coordinate('X').array)
[  0  45  90 135 180 225 270 315]
>>> g = f.anchor('X', 230)
>>> print(g.dimension_coordinate('X').array)
[270 315   0  45  90 135 180 225]
>>> g = f.anchor('X', cf.Data(590, 'degreesE'))
>>> print(g.dimension_coordinate('X').array)
[630 675 360 405 450 495 540 585]
>>> g = f.anchor('X', cf.Data(-490, 'degreesE'))
>>> print(g.dimension_coordinate('X').array)
[-450 -405 -720 -675 -630 -585 -540 -495]

>>> f.iscyclic('X')
True
>>> f.dimension_coordinate('X').data
<CF Data(8): [0.0, ..., 357.1875] degrees_east>
>>> f.anchor('X', 10000).dimension_coordinate('X').data
<CF Data(8): [10001.25, ..., 10358.4375] degrees_east>
>>> d = f.anchor('X', 10000, dry_run=True)
>>> d
{'axis': 'domainaxis2',
 'nperiod': <CF Data(1): [10080.0] 0.0174532925199433 rad>,
 'roll': 28}
>>> (f.roll(d['axis'], d['roll']).dimension_coordinate(
...     d['axis']) + d['nperiod']).data
<CF Data(8): [10001.25, ..., 10358.4375] degrees_east>