cf.SubsampledArray

---

class cf.SubsampledArray(*args, **kwargs)

An underlying subsampled array.

For some structured coordinate data (e.g. coordinates describing remote sensing products) space may be saved by storing a subsample of the data, called tie points. The uncompressed data can be reconstituted by interpolation, from the subsampled values. This process will likely result in a loss in accuracy (as opposed to precision) in the uncompressed variables, due to rounding and approximation errors in the interpolation calculations, but it is assumed that these errors will be small enough to not be of concern to users of the uncompressed dataset. The creator of the compressed dataset can control the accuracy of the reconstituted data through the degree of subsampling and the choice of interpolation method.

See CF section 8.3 “Lossy Compression by Coordinate Subsampling” and Appendix J “Coordinate Interpolation Methods”.

>>> tie_point_indices=cf.TiePointIndex(data=[0, 4, 7, 8, 11])
>>> w = cf.InterpolationParameter(data=[5, 10, 5])
>>> coords = cf.SubsampledArray(
...     interpolation_name='quadratic',
...     compressed_array=cf.Data([15, 135, 225, 255, 345]),
...     shape=(12,),
...     tie_point_indices={0: tie_point_indices},
...     parameters={"w": w},
...     parameter_dimensions={"w": (0,)},
... )
>>> print(coords[...])
[ 15.          48.75        80.         108.75       135.
 173.88888889 203.88888889 225.         255.         289.44444444
 319.44444444 345.        ]

Cell boundaries

When the tie points array represents bounds tie points then the shape parameter describes the uncompressed bounds shape. See CF section 8.3.9 “Interpolation of Cell Boundaries”.

>>> bounds = cf.SubsampledArray(
...     interpolation_name='quadratic',
...     compressed_array=cf.Data([0, 150, 240, 240, 360]),
...     shape=(12, 2),
...     tie_point_indices={0: tie_point_indices},
...     parameters={"w": w},
...     parameter_dimensions={"w": (0,)},
... )
>>> print(bounds[...])
[[0.0 33.2]
 [33.2 64.8]
 [64.8 94.80000000000001]
 [94.80000000000001 123.2]
 [123.2 150.0]
 [150.0 188.88888888888889]
 [188.88888888888889 218.88888888888889]
 [218.88888888888889 240.0]
 [240.0 273.75]
 [273.75 305.0]
 [305.0 333.75]
 [333.75 360.0]]

Added in version (cfdm): 1.10.0.0

Initialisation

Parameters:

interpolation_name: str, optional

The name of the interpolation method.

Standardised interpolation method are defined in CF appendix J “Coordinate Interpolation Methods”.

If not set then the non-standardised interpolation method is assumed to be defined by the interpolation_description parameter

Parameter example:

'bi_linear'

compressed_array: array_like

The (bounds) tie points array.

shape: tuple

The uncompressed array shape.

tie_point_indices: dict

The tie point index variable for each subsampled dimension. A key identifies a subsampled dimension by its integer position in the compressed array, and its value is a TiePointIndex variable.

Parameter example:

{1: cf.TiePointIndex(data=[0, 16, 31])}

computational_precision: str, optional

The floating-point arithmetic precision used during the preparation and validation of the compressed data.

Parameter example:

'64'

interpolation_description: str, optional

A complete non-standardised description of the interpolation method.

parameters: dict, optional

Interpolation parameters required by the interpolation method. Each key is an interpolation parameter term name, whose value is an InterpolationParameter variable.

Interpolation parameter term names for the standardised interpolation methods are defined in CF Appendix J “Coordinate Interpolation Methods”.

Set to an empty dictionary for interpolation methods that do not require interpolation parameters.

Parameter example:

{}

Parameter example:

{'w': cf.InterpolationParameter(data=[5, 10, 5])}

parameter_dimensions: dict, optional

The tie point array dimensions that correspond to the dimensions of the interpolation parameters, keyed by the interpolation parameter term names.

Interpolation parameter term names for the standardised interpolation methods are defined in CF Appendix J “Coordinate Interpolation Methods”.

Set to an empty dictionary for interpolation methods that do not require interpolation parameters.

Parameter example:

{}

Parameter example:

{'w': (0,)}

Parameter example:

{'ce1': (1, 2), 'ca2': (2, 1)}

dependent_tie_points: dict, optional

The dependent tie point arrays needed by the interpolation method, keyed by the dependent tie point identities. Each key is a dependent tie point identity, whose value is a Data variable.

The identities must be understood the interpolation method. When interpolation_name is 'quadratic_latitude_longitude' or 'bi_quadratic_latitude_longitude'` then the *dependent_tie_points* dictionary must contain exactly one of the keys ``'latitude' or 'longitude.

Set to an empty dictionary for interpolation methods that do not require dependent tie points.

Parameter example:

{}

Parameter example:

{'latitude': cf.Data([30, 31, 32])}

dependent_tie_points_dimensions: dict, optional

The tie point array dimensions that correspond to the dimensions of the dependent tie points arrays, keyed the dependent tie point identities.

Set to an empty dictionary for interpolation methods that do not require dependent tie points.

Parameter example:

{}

Parameter example:

{'latitude': (0,)}

Parameter example:

{'longitude': (0, 1)}

Parameter example:

{'latitude': (2, 0, 1)}

source: optional

Convert source, which can be any type of object, to a SubsampledArray instance.

All other parameters, apart from copy, are ignored and their values are instead inferred from source by assuming that it has the SubsampledArray API. Any parameters that can not be retrieved from source in this way are assumed to have their default value.

Note that if x is also a SubsampledArray instance then cf.SubsampledArray(source=x) is equivalent to x.copy().

copy: bool, optional

If True (the default) then deep copy the input parameters prior to initialisation. By default the parameters are not deep copied.

Methods

compressed_dimensions	Mapping of compressed to uncompressed dimensions.
conformed_data	Return the conformed tie points and any ancillary data.
copy	Return a deep copy of the array.
get_attributes	The attributes of the array.
get_Subarray	Return the Subarray class.
get_calendar	The calendar of the array.
get_compressed_axes	Return axes that are compressed in the underlying array.
get_compressed_dimension	Returns the compressed dimension's position in the array.
get_compression_type	Returns the array's compression type.
get_computational_precision	Get the validation computational precision.
get_dependent_tie_point_dimensions	Get the dimension order of dependent tie points.
get_dependent_tie_points	Get the dependent tie points.
get_interpolation_description	Get the non-standardised interpolation method description.
get_interpolation_name	Get the name of a standardised interpolation method.
get_parameter_dimensions	Get the dimension order interpolation parameters.
get_parameters	Get the interpolation parameter variables.
get_tie_point_indices	Get the tie point index variables for subsampled dimensions.
get_units	The units of the array.
set_dependent_tie_point_dimensions	Set the dimension order of dependent tie points.
set_dependent_tie_points	Set the dependent tie points.
set_parameter_dimensions	Set the dimension order interpolation parameters.
set_parameters	Set the interpolation parameter variables.
set_tie_point_indices	Set the tie point index variables for subsampled dimensions.
source	Return the underlying array object.
subarray_parameters	Non-data parameters required by the Subarray class.
subarray_shapes	Create the subarray shapes along each uncompressed dimension.
subarrays	Return descriptors for every subarray.
to_dask_array	Convert the data to a dask array.
to_memory	Bring data on disk into memory.

Attributes

Units	The Units object containing the units of the array.
array	Returns a numpy array containing the uncompressed data.
astype	Cast the data to a specified type.
bounds	True if the compressed array represents bounds tie points.
compressed_array	Returns an independent numpy array with the compressed data.
dtype	Data-type of the uncompressed data.
ndim	Number of array dimensions.
shape	Shape of the uncompressed data.
size	Number of elements in the array.