cfdm.Field.insert_dimension

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

Expand the shape of the data array.

New in version (cfdm): 1.7.0

See also

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 'time', the domain axis construct returned by f.domain_axis('time') is selected.

If axis is None then a new domain axis construct will be 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. Negative integers counting from the last position are allowed.

constructs: bool

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 (cfdm): 1.11.1.0

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 = cfdm.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('time', 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]