cf.Field.insert_dimension

Field.insert_dimension(axis, position=0, constructs=False, inplace=False)[source]

Insert a size 1 axis into the data array.

New in version 3.0.0.

See also

domain_axis, flatten, flip, squeeze, transpose, unsqueeze

Parameters
axis:

Select the domain axis to insert, generally 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.

If axis is None then a new domain axis construct will created for the inserted dimension.

position: int, optional

Specify the position that the new axis will have in the data array. By default the new axis has position 0, the slowest varying position.

constructs: bool, optional

If True then also insert the new axis into all metadata constructs that don’t already include it. By default, metadata constructs are not changed.

New in version 3.16.1.

inplace: bool, optional

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

Returns
Field or None

The field construct with expanded data, 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]
>>> g = f.insert_dimension('T', 0)
>>> print(g)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(time(1), 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]

A previously non-existent size 1 axis must be created prior to insertion:

>>> f.insert_dimension(None, 1, inplace=True)
>>> print(f)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(time(1), key%domainaxis3(1), 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]