cf.Field.halo

Field.halo(depth, axes=None, tripolar=None, fold_index=-1, inplace=False, verbose=None, size=None)

Expand the field construct by adding a halo to its data.

The halo may be applied over a subset of the data dimensions and each dimension may have a different halo size (including zero). The halo region is populated with a copy of the proximate values from the original data.

The metadata constructs are similarly extended where appropriate.

Cyclic axes

A cyclic axis that is expanded with a halo of at least size 1 is no longer considered to be cyclic.

Tripolar domains

Global tripolar domains are a special case in that a halo added to the northern end of the “Y” axis must be filled with values that are flipped in “X” direction. Such domains can not be identified from the field construct’s metadata, so need to be explicitly indicated with the tripolar parameter.

New in version 3.5.0.

Parameters

depth: int or dict

Specify the size of the halo for each axis.

If depth is a non-negative int then this is the halo size that is applied to all of the axes defined by the axes parameter.

Alternatively, halo sizes may be assigned to axes individually by providing a dict for which a key specifies an axis (by passing the 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')) with a corresponding value of the halo size for that axis. Axes not specified by the dictionary are not expanded, and the axes parameter must not also be set.

Parameter example:

Specify a halo size of 1 for all otherwise selected axes: 1

Parameter example:

Specify a halo size of zero: 0. This results in no change to the data shape.

Parameter example:

For data with three dimensions, specify a halo size of 3 for the first dimension and 1 for the second dimension: {0: 3, 1: 1}. This is equivalent to {0: 3, 1: 1, 2: 0}

Parameter example:

Specify a halo size of 2 for the “longitude” and “latitude” axes: depth=2, axes=['latutude', 'longitude'], or equivalently depth={'latitude': 2, 'longitude': 2}.

axes: (sequence of) str or int, optional

Select the domain axes to be expanded, defined by the domain axes that would be selected by passing each 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.

By default, or if axes is None, all axes that span the data are selected. No axes are expanded if axes is an empty sequence.

Parameter example:

axes='X'

Parameter example:

axes=['Y']

Parameter example:

axes=['X', 'Y']

Parameter example:

axes='longitude'

Parameter example:

axes=2

Parameter example:

axes='ncdim%i'

tripolar: dict, optional

A dictionary defining the “X” and “Y” axes of a global tripolar domain. This is necessary because in the global tripolar case the “X” and “Y” axes need special treatment, as described above. It must have keys 'X' and 'Y', whose values identify the corresponding domain axis construct by passing the value to a call of the field construct’s domain_axis method. For example, for a value of 'ncdim%i', the domain axis construct returned by f.domain_axis('ncdim%i').

The “X” and “Y” axes must be a subset of those identified by the depth or axes parameter.

See the fold_index parameter.

Parameter example:

Define the “X” and Y” axes by their netCDF dimension names: {'X': 'ncdim%i', 'Y': 'ncdim%j'}

Parameter example:

Define the “X” and Y” axes by positions 2 and 1 respectively of the data: {'X': 2, 'Y': 1}

fold_index: int, optional

Identify which index of the “Y” axis corresponds to the fold in “X” axis of a tripolar grid. The only valid values are -1 for the last index, and 0 for the first index. By default it is assumed to be the last index. Ignored if tripolar is None.

inplace: bool, optional

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

verbose: int or str or None, optional

If an integer from -1 to 3, or an equivalent string equal ignoring case to one of:

• 'DISABLE' (0)

• 'WARNING' (1)

• 'INFO' (2)

• 'DETAIL' (3)

• 'DEBUG' (-1)

set for the duration of the method call only as the minimum cut-off for the verboseness level of displayed output (log) messages, regardless of the globally-configured cf.log_level. Note that increasing numerical value corresponds to increasing verbosity, with the exception of -1 as a special case of maximal and extreme verbosity.

Otherwise, if None (the default value), output messages will be shown according to the value of the cf.log_level setting.

Overall, the higher a non-negative integer or equivalent string that is set (up to a maximum of 3/'DETAIL') for increasing verbosity, the more description that is printed to convey information about the operation.

size: deprecated at version 3.14.0

Use the depth parameter instead.

Returns

Field or None

The expanded field construct, or None if the operation was in-place.

Examples

>>> f = cf.example_field(0)
>>> print(f)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(5), longitude(8)) 1
Cell methods    : area: mean
Dimension coords: latitude(5) = [-75.0, ..., 75.0] degrees_north
                : longitude(8) = [22.5, ..., 337.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]
>>> print(f.array)
[[0.007 0.034 0.003 0.014 0.018 0.037 0.024 0.029]
 [0.023 0.036 0.045 0.062 0.046 0.073 0.006 0.066]
 [0.11  0.131 0.124 0.146 0.087 0.103 0.057 0.011]
 [0.029 0.059 0.039 0.07  0.058 0.072 0.009 0.017]
 [0.006 0.036 0.019 0.035 0.018 0.037 0.034 0.013]]
>>> print(f.coordinate('X').array)
[ 22.5  67.5 112.5 157.5 202.5 247.5 292.5 337.5]

>>> g = f.halo(1)
>>> print(g)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(7), longitude(10)) 1
Cell methods    : area: mean
Dimension coords: latitude(7) = [-75.0, ..., 75.0] degrees_north
                : longitude(10) = [22.5, ..., 337.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]
>>> print(g.array)
[[0.007 0.007 0.034 0.003 0.014 0.018 0.037 0.024 0.029 0.029]
 [0.007 0.007 0.034 0.003 0.014 0.018 0.037 0.024 0.029 0.029]
 [0.023 0.023 0.036 0.045 0.062 0.046 0.073 0.006 0.066 0.066]
 [0.11  0.11  0.131 0.124 0.146 0.087 0.103 0.057 0.011 0.011]
 [0.029 0.029 0.059 0.039 0.07  0.058 0.072 0.009 0.017 0.017]
 [0.006 0.006 0.036 0.019 0.035 0.018 0.037 0.034 0.013 0.013]
 [0.006 0.006 0.036 0.019 0.035 0.018 0.037 0.034 0.013 0.013]]
>>> print(g.coordinate('X').array)
[ 22.5  22.5  67.5 112.5 157.5 202.5 247.5 292.5 337.5 337.5]

>>> g = f.halo(1, axes='Y')
>>> print(g)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(7), longitude(8)) 1
Cell methods    : area: mean
Dimension coords: latitude(7) = [-75.0, ..., 75.0] degrees_north
                : longitude(8) = [22.5, ..., 337.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]
>>> print(g.array)
[[0.007 0.034 0.003 0.014 0.018 0.037 0.024 0.029]
 [0.007 0.034 0.003 0.014 0.018 0.037 0.024 0.029]
 [0.023 0.036 0.045 0.062 0.046 0.073 0.006 0.066]
 [0.11  0.131 0.124 0.146 0.087 0.103 0.057 0.011]
 [0.029 0.059 0.039 0.07  0.058 0.072 0.009 0.017]
 [0.006 0.036 0.019 0.035 0.018 0.037 0.034 0.013]
 [0.006 0.036 0.019 0.035 0.018 0.037 0.034 0.013]]
>>> h = f.halo({'Y': 1})
>>> h.equals(g)
True

>>> g = f.halo({'Y': 2, 'X': 1})
>>> print(g)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(9), longitude(10)) 1
Cell methods    : area: mean
Dimension coords: latitude(9) = [-75.0, ..., 75.0] degrees_north
                : longitude(10) = [22.5, ..., 337.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]
>>> print(g.array)
[[0.007 0.007 0.034 0.003 0.014 0.018 0.037 0.024 0.029 0.029]
 [0.023 0.023 0.036 0.045 0.062 0.046 0.073 0.006 0.066 0.066]
 [0.007 0.007 0.034 0.003 0.014 0.018 0.037 0.024 0.029 0.029]
 [0.023 0.023 0.036 0.045 0.062 0.046 0.073 0.006 0.066 0.066]
 [0.11  0.11  0.131 0.124 0.146 0.087 0.103 0.057 0.011 0.011]
 [0.029 0.029 0.059 0.039 0.07  0.058 0.072 0.009 0.017 0.017]
 [0.006 0.006 0.036 0.019 0.035 0.018 0.037 0.034 0.013 0.013]
 [0.029 0.029 0.059 0.039 0.07  0.058 0.072 0.009 0.017 0.017]
 [0.006 0.006 0.036 0.019 0.035 0.018 0.037 0.034 0.013 0.013]]