astropy:docs

Navigation

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.

Warning

nddata has changed significantly in astropy 1.0. See the section Transition to astropy 1.0 for more information.

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)
INFO: Overwriting NDData's current mask with specified mask [astropy.nddata.nddata]

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 string attribute called uncertainty_type.

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.

Transition to astropy 1.0

The nddata package underwent substantial revision as a result of APE 7; please see that APE for an extensive discussion of the motivation and the changes.

The most important changes are that:

  • NDData does not provide a numpy-like interface; to use its data use the data attribute instead.
  • Slicing is no provided in the base NDData.
  • Arithmetic is no longer included in the base NDData class.

Code that only uses the metadata features of NDData should not need to be modified.

Code that uses the arithemtic methods that used to be included in NDData and relied on it to behave like a numpy array should instead subclass NDDataArray; that class is equivalent to the original NDData class.

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

support_nddata([_func, accepts, repack, returns]) Decorator to split NDData properties into function arguments.

Classes

Conf Configuration parameters for astropy.nddata.
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 basic class for array-based data.
NDDataArray(*arg, **kwd) An NDData object with arithmetic.
NDDataBase() Base metaclass that defines the interface for NDData
NDIOMixin Mixin class to connect NDData to the astropy input/output registry.
NDSlicingMixin Mixin to provide slicing on objects using the NDData interface.
NDUncertainty This is the base class for uncertainty classes used with NDData.
StdDevUncertainty([array, copy]) A class for standard deviation uncertainties

astropy.nddata.utils Module

This module includes helper functions for array operations.

Functions

extract_array(array_large, shape, position) Extract smaller array of given shape and position out of 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, ...) Get slices for the overlapping part of a small and a large array.

Page Contents