N-dimensional datasets (astropy.nddata)

Introduction

The nddata package provides a uniform interface to N-dimensional datasets in astropy through:

  • The NDDataBase metaclass to define an astropy-wide interface to N-dimensional data sets while allowing flexibility in how those datasets are represented internally.
  • The NDData class, which provides a basic container for gridded N-dimensional datasets.
  • Several mixin classes for adding functionality to NDData containers.
  • A decorator, support_nddata, for facilitating use of nddata objects in functions in astropy and affiliated packages.
  • General utility functions (astropy.nddata.utils) for array operations.

Getting started

Of the classes provided by nddata, the place to start for most users will be NDData, which by default uses a numpy array to store the data. Designers of new classes should also look at NDDataBase before deciding what to subclass from.

NDData

The primary purpose of NDData is to act as a container for data, metadata, and other related information like a mask.

An NDData object can be instantiated by passing it an n-dimensional Numpy array:

>>> import numpy as np
>>> from astropy.nddata import NDData
>>> array = np.zeros((12, 12, 12))  # a 3-dimensional array with all zeros
>>> ndd = NDData(array)

or something that can be converted to an array:

>>> ndd2 = NDData([1, 2, 3, 4])

It is also possible to initialize NDData with more exotic objects; see NDData for more information.

The underlying Numpy array can be accessed via the data attribute:

>>> ndd.data
array([[[ 0., 0., 0., ...
...

Values can be masked using the mask attribute:

>>> ndd_masked = NDData(ndd, mask = ndd.data > 0.9)

A mask value of True indicates a value that should be ignored, while a mask value of False indicates a valid value.

Similar attributes are available to store:

  • generic meta-data, in meta,
  • a unit for the data values, in unit and
  • an uncertainty for the data values, in uncertainty. Note that the uncertainty must have a attribute called uncertainty_type otherwise it will be converted to an UnknownUncertainty.

Note that a NDData object is not sliceable:

>>> ndd2[1:3]        
Traceback (most recent call last):
    ...
TypeError: 'NDData' object has no attribute '__getitem__'

Mixins for additional functionality

Several classes are provided to add functionality to the basic NDData container. They include:

  • NDSlicingMixin to handle slicing of N-dimensional data.
  • NDArithmeticMixin to allow arithmetic operations on NDData objects that include support propagation of uncertainties (in limited cases).
  • NDIOMixin to use existing astropy functionality for input (with the method read) and output (with the method write).

To use these mixins, create a new class that includes the appropriate mixins as subclasses. For example, to make a class that includes slicing, but not arithmetic or I/O:

>>> from astropy.nddata import NDData, NDSlicingMixin
>>> class NDDataSliceable(NDSlicingMixin, NDData): pass

Note that the body of the class need not contain any code; all of the functionality is provided by the NDData container and the mixins. The order of the classes is important because python works from right to left in determining the order in which methods are resolved.

NDDataSliceable is initialized the same way that NDData is:

>>> ndd_sliceable = NDDataSliceable([1, 2, 3, 4])

but can be sliced:

>>> ndd_sliceable[1:3]
NDDataSliceable([2, 3])

The class NDDataArray is an example of a class which utilizes mixins and adds functionality.

NDDataBase for making new subclasses

NDDataBase is a metaclass provided to support the creation of objects that support the NDData interface but need the freedom to define their own ways of storing data, unit, metadata and/or other properties. It should be used instead of NDData as the starting point for any class for which the NDData class is too restrictive.

Reference/API

astropy.nddata Package

The astropy.nddata subpackage provides the NDData class and related tools to manage n-dimensional array-based data (e.g. CCD images, IFU Data, grid-based simulation data, ...). This is more than just numpy.ndarray objects, because it provides metadata that cannot be easily provided by a single array.

Functions

add_array(array_large, array_small, position) Add a smaller array at a given position in a larger array.
block_reduce(data, block_size[, func]) Downsample a data array by applying a function to local blocks.
block_replicate(data, block_size[, conserve_sum]) Upsample a data array by block replication.
extract_array(array_large, shape, position) Extract a smaller array of the given shape and position from a larger array.
overlap_slices(large_array_shape, ...[, mode]) Get slices for the overlapping part of a small and a large array.
subpixel_indices(position, subsampling) Convert decimal points to indices, given a subsampling factor.
support_nddata([_func, accepts, repack, returns]) Decorator to split NDData properties into function arguments.

Classes

Conf Configuration parameters for astropy.nddata.
Cutout2D(data, position, size[, wcs, mode, ...]) Create a cutout object from a 2D array.
FlagCollection(*args, **kwargs) The purpose of this class is to provide a dictionary for containing arrays of flags for the NDData class.
IncompatibleUncertaintiesException This exception should be used to indicate cases in which uncertainties with two different classes can not be propagated.
MissingDataAssociationException This exception should be used to indicate that an uncertainty instance has not been associated with a parent NDData object.
NDArithmeticMixin Mixin class to add arithmetic to an NDData object.
NDData(data[, uncertainty, mask, wcs, meta, ...]) A container for ndarray-based datasets, using the NDDataBase interface.
NDDataArray(*arg, **kwd) An NDData object with arithmetic.
NDDataBase() Base metaclass that defines the interface for N-dimensional datasets with associated meta informations used in astropy.
NDIOMixin Mixin class to connect NDData to the astropy input/output registry.
NDSlicingMixin Mixin to provide slicing on objects using the NDData interface.
NDUncertainty([array, unit, copy]) This is the base class for uncertainty classes used with NDData.
NoOverlapError Raised when determining the overlap of non-overlapping arrays.
PartialOverlapError Raised when arrays only partially overlap.
StdDevUncertainty([array, unit, copy]) A class for standard deviation uncertainty.
UnknownUncertainty([array, unit, copy]) This implements any kind of unknown uncertainty type.

astropy.nddata.utils Module

This module includes helper functions for array operations.

Functions

extract_array(array_large, shape, position) Extract a smaller array of the given shape and position from a larger array.
add_array(array_large, array_small, position) Add a smaller array at a given position in a larger array.
subpixel_indices(position, subsampling) Convert decimal points to indices, given a subsampling factor.
overlap_slices(large_array_shape, ...[, mode]) Get slices for the overlapping part of a small and a large array.
block_reduce(data, block_size[, func]) Downsample a data array by applying a function to local blocks.
block_replicate(data, block_size[, conserve_sum]) Upsample a data array by block replication.

Classes

NoOverlapError Raised when determining the overlap of non-overlapping arrays.
PartialOverlapError Raised when arrays only partially overlap.
Cutout2D(data, position, size[, wcs, mode, ...]) Create a cutout object from a 2D array.