cf.DomainAncillary.halo

DomainAncillary.halo(*args, **kwargs)

Expand the data by adding a halo.

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.

Corresponding axes expanded in the bounds, if present.

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

Data for 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 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 (defined by its integer position in the data) 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 first and last dimensions depth=2, axes=[0, -1] or equivalently depth={0: 2, -1: 2}.

axes: (sequence of) int

Select the domain axes to be expanded, defined by their integer positions in the data. By default, or if axes is None, all axes are selected. No axes are expanded if axes is an empty sequence.

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 their integer positions in the data.

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 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

DomainAncillary or None

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

Examples

TODO