Skip to main content
`Ctrl`+`K`

# NDMetaABC

class ndcube.meta.NDMetaABC

  Bases: `Mapping`

  A sliceable object for storing metadata.

  Metadata can be linked to a data axis which causes it to be sliced when the standard Python numeric slicing API is applied to the object. Specific pieces of metadata can be obtain using the dict-like string slicing API. Metadata associated with an axis/axes must have the same length/shape as those axes.

  Parameters:

    - meta (dict-like) – The names and values of metadata.

    - key_comments (dict-like, optional) – Comments associated with any of the above pieces of metadata.

    - axes (dict-like, optional) – The axis/axes associated with the metadata denoted by the keys. Metadata not included are considered not to be associated with any axis. Each axis value must be an iterable of `int`. An `int` itself is also acceptable if the metadata is associated with a single axis. The value of axis-assigned metadata in meta must be same length as number of associated axes (axis-aligned), or same shape as the associated data array’s axes (grid-aligned).

  Notes

  Axis-aware Metadata There are two valid types of axis-aware metadata: axis-aligned and grid-aligned. Axis-aligned metadata gives one value per associated axis, while grid-aligned metadata gives a value for each data array element in the associated axes. Consequently, axis-aligned metadata has the same length as the number of associated axes, while grid-aligned metadata has the same shape as the associated axes. To avoid confusion, axis-aligned metadata that is only associated with one axis must be scalar or a string. Length-1 objects (excluding strings) are assumed to be grid-aligned and associated with a length-1 axis.

  Slicing and Rebinning Axis-aware Metadata Axis-aligned metadata is only considered valid if the associated axes are present. Therefore, axis-aligned metadata is only changed if an associated axis is dropped by an operation, e.g. slicing. In such a case, the value associated with the dropped axes is also dropped and hence lost. If the axis of a 1-axis-aligned metadata value (scalar) is slicing away, the metadata key is entirely removed from the NDMeta object.

  Grid-aligned metadata is mirrors the data array, it is sliced following the same rules with one exception. If an axis is dropped by slicing, the metadata name is kept, but its value is set to the value at the row/column where the axis/axes was sliced away, and the metadata axis-awareness is removed. This is similar to how coordinate values are transferred to `global_coords` when their associated axes are sliced away.

  Note that because rebinning does not drop axes, axis-aligned metadata is unaltered by rebinning. By contrast, grid-aligned metadata must necessarily by affected by rebinning. However, how it is affected depends on the nature of the metadata and there is no generalized solution. Therefore, this class does not alter the shape or values of grid-aligned metadata during rebinning, but simply removes its axis-awareness. If specific pieces of metadata have a known way to behave during rebinning, this can be handled by subclasses or mixins.

  Attributes Summary

  `axes` | Mapping from metadata keys to axes with which they are associated.
  `data_shape` | The shape of the data with which the metadata is associated.
  `key_comments` | Mapping from metadata keys to associated comments.
  `slice` | A helper class which, when sliced, returns a new NDMeta with axis- and grid-aligned metadata sliced.

  Methods Summary

  `add`(name, value[, key_comment, axes, overwrite]) | Add a new piece of metadata to instance.
  `rebin`(rebinned_axes, new_shape) | Adjusts grid-aware metadata to stay consistent with rebinned data.

  Attributes Documentation

  axes

    Mapping from metadata keys to axes with which they are associated.

    Metadata not associated with any axes need not be represented here.

  data_shape

    The shape of the data with which the metadata is associated.

  key_comments

    Mapping from metadata keys to associated comments.

    Metadata without a comment need not be represented here.

  slice

    A helper class which, when sliced, returns a new NDMeta with axis- and grid-aligned metadata sliced.

    Example

        >>> sliced_meta = meta.slice[0:3, :, 2]

  Methods Documentation

  abstractmethod add(name, value, key_comment=None, axes=None, overwrite=False)

    Add a new piece of metadata to instance.

    Parameters:

      - name (`str`) – The name/label of the metadata.

      - value (Any) – The value of the metadata. If axes input is not None, this must have the same length/shape as those axes as defined by `self.data_shape`.

      - key_comment (`str` or `None`) – Any comment associated with this metadata. Set to None if no comment desired.

      - axes (`int`, iterable of `int`, or `None`) – The axis/axes with which the metadata is linked. If not associated with any axis, set this to None.

      - overwrite (`bool`, optional) – If True, overwrites the entry of the name name if already present.

  abstractmethod rebin(rebinned_axes, new_shape)

    Adjusts grid-aware metadata to stay consistent with rebinned data.