cf.Field.anchor

Field.anchor(axis, value, inplace=False, dry_run=False, i=False, **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 1.0.

See also

axis, cyclic, iscyclic, period, roll

Parameters:
axis:

The cyclic axis to be rolled, defined by that which would be selected by passing the given axis description to a call of the field construct’s domain_axis method. For example, for a value of 'X', the domain axis construct returned by f.domain_axis('X')) is selected.

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 field is not changed, even if i is True.

i: deprecated at version 3.0.0

Use the inplace parameter instead.

kwargs: deprecated at version 3.0.0
Returns:
Field

The rolled field.

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>