cf.Field.compress

Field.compress(*args, **kwargs)[source]

Compress the field construct.

Compression can save space by identifying and removing unwanted missing data. Such compression techniques store the data more efficiently and result in no precision loss.

The field construct data is compressed, along with any applicable metadata constructs.

Whether or not the field construct is compressed does not alter its functionality nor external appearance.

A field that is already compressed will be returned compressed by the chosen method.

When writing a compressed field construct to a dataset, compressed netCDF variables are written, along with the supplementary netCDF variables and attributes that are required for the encoding.

The following type of compression are available (see the method parameter):

  • Ragged arrays for discrete sampling geometries (DSG). Three different types of ragged array representation are supported.

  • Compression by gathering.

New in version (cfdm): 1.7.11

See also

uncompress

Parameters
method: str

The compression method. One of:

  • 'contiguous'

    Contiguous ragged array representation for DSG “point”, “timeSeries”, “trajectory” or “profile” features.

    The field construct data must have exactly 2 dimensions for which the first (leftmost) dimension indexes each feature and the second (rightmost) dimension contains the elements for the features. Trailing missing data values in the second dimension are removed to created the compressed data.

  • 'indexed'

    Indexed ragged array representation for DSG “point”, “timeSeries”, “trajectory”, or “profile” features.

    The field construct data must have exactly 2 dimensions for which the first (leftmost) dimension indexes each feature and the second (rightmost) dimension contains the elements for the features. Trailing missing data values in the second dimension are removed to created the compressed data.

  • 'indexed_contiguous'

    Indexed contiguous ragged array representation for DSG “timeSeriesProfile”, or “trajectoryProfile” features.

    The field construct data must have exactly 3 dimensions for which the first (leftmost) dimension indexes each feature; the second (middle) dimension indexes each timeseries or trajectory; and the third (rightmost) dimension contains the elements for the timeseries or trajectories. Trailing missing data values in the third dimension are removed to created the compressed data.

  • 'gathered'

    Compression by gathering over any subset of the field construct data dimensions.

    Not yet available.

count_properties: dict, optional

Provide properties to the count variable for contiguous ragged array representation or indexed contiguous ragged array representation.

Parameter example:

count_properties={'long_name': 'number of timeseries'}

index_properties: dict, optional

Provide properties to the index variable for indexed ragged array representation or indexed contiguous ragged array representation.

Parameter example:

index_properties={'long_name': 'station of profile'}

list_properties: dict, optional

Provide properties to the list variable for compression by gathering.

Parameter example:

list_properties={'long_name': 'uncompression indices'}

inplace: bool, optional

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

Returns
Field or None

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

Examples

>>> f.data.get_compression_type()
''
>>> print(f.array)
[[3.98  0.0  0.0  --    --   --   --  --  --]
 [ 0.0  0.0  0.0  3.4  0.0  0.0 4.61  --  --]
 [0.86  0.8 0.75  0.0 4.56   --   --  --  --]
 [ 0.0 0.09  0.0 0.91 2.96 1.14 3.86 0.0 0.0]]
>>> g = f.compress('contiguous')
>>> g.equals(f)
True

>>> cfdm.write(g, 'compressed_file_contiguous.nc')
>>> h = cfdm.read( 'compressed_file_contiguous.nc')[0]
>>> h.equals(f)
True

>>> g.data.get_compression_type()
'ragged contiguous'
>>> g.data.get_count()
<Count: (4) >
>>> print(g.data.get_count().array)
[3 7 5 9]
>>> g.compress('indexed', inplace=True)
>>> g.data.get_index()
<Index: (24) >
>>> print(g.data.get_index().array)
[0 0 0 1 1 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 3 3 3 3]
>>> cfdm.write(g, 'compressed_file_indexed.nc')