# cf.Field.anchor

`Field.``anchor`(axes, value, i=False, dry_run=False, **kwargs)

  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`

  Examples 1: |

  Anchor the cyclic X axis to a value of 180:

      >>> g = f.anchor('X', 180)

  Parameters: | axes, kwargs: optional Select axes. The axes parameter may be one, or a sequence, of: `None`. If no kwargs arguments have been set then all axes are selected. This is the default. An integer. Explicitly selects the axis corresponding to the given position in the list of axes of the field’s data array. Example: To select the third data array axis: `axes=2`. To select the last axis: `axes=-1`. A `slice` object. Explicitly selects the axes corresponding to the given positions in the list of axes of the field’s data array. Example: To select the last three data array axes: `axes=slice(-3, None)` A domain axis identifier. Explicitly selects this axis. Example: To select axis “dim1”: `axes='dim1'`. Any value accepted by the description parameter of the field’s `items` method. Used in conjunction with the kwargs parameters to select the axes which span the items that would be identified by this call of the field’s `items` method: `f.items(items=axes, axes=None, **kwargs)`. See `cf.Field.items` for details. Example: To select the axes spanned by one dimensionsal time coordinates: `f.anchor('T', ndim=1)`. If axes is a sequence of any combination of the above then the selected axes are the union of those selected by each element of the sequence. If the sequence is empty then no axes are selected. value: data-like object Anchor the dimension coordinate values for the selected cyclic axis to the value. 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. 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`. 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`. A data-like object is any object containing array-like or scalar data which could be used to create a `cf.Data` object. Example: Instances, `x`, of following types are all examples of data-like objects (because `cf.Data(x)` creates a valid `cf.Data` object): `int`, `float`, `str`, `tuple`, `list`, `numpy.ndarray`, `cf.Data`, `cf.Coordinate`, `cf.Field`. i: `bool`, optional If True then update the field in place. By default a new field is created. In either case, a field is returned. dry_run: `bool`, optional Return a dictionary of parameters which describe the anchoring process. The field is not changed, even if i is True.
  Returns: | out: `cf.Field` or `dict`
  Examples 2: |

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

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