N-dimensional datasets (astropy.nddata)

Introduction

The nddata package provides a uniform interface to N-dimensional datasets (for tabulated data please have a look at astropy.table) in astropy through:

  • NDData: a basic container for numpy.ndarray-like data.
  • NDDataRef: like NDData but with additional functionality like an reading/writing, simple arithmetic operations and slicing.
  • StdDevUncertainty a class that can store and propagate uncertainties for a NDData object.
  • General utility functions (astropy.nddata.utils) for operations on these classes, including a decorator to facilitate writing functions for such classes.
  • A framework including different mixins and metaclasses to facilitate customizing subclasses.

Getting started

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
>>> ndd1 = NDData(array)

or something that can be converted to an numpy.ndarray:

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

and can be accessed again via the data attribute:

>>> ndd2.data
array([1, 2, 3, 4])

It also supports additional properties like a unit or mask for the data, a wcs (world coordinate system) and uncertainty of the data and additional meta attributes:

>>> data = np.array([1,2,3,4])
>>> mask = data > 2
>>> unit = 'erg / s'
>>> from astropy.nddata import StdDevUncertainty
>>> uncertainty = StdDevUncertainty(np.sqrt(data)) # representing standard deviation
>>> meta = {'object': 'fictional data.'}
>>> from astropy.coordinates import SkyCoord
>>> wcs = SkyCoord('00h42m44.3s', '+41d16m09s')
>>> ndd = NDData(data, mask=mask, unit=unit, uncertainty=uncertainty,
...              meta=meta, wcs=wcs)
>>> ndd
NDData([1, 2, 3, 4])

The representation only displays the data; the other attributes need to be accessed directly, for example ndd.mask to access the mask.

NDDataRef

Building upon this pure container NDDataRef implements:

  • a read and write method to access astropys unified file io interface.
  • simple arithmetics like addition, subtraction, division and multiplication.
  • slicing.

Instances are created in the same way:

>>> from astropy.nddata import NDDataRef
>>> ndd = NDDataRef(ndd)
>>> ndd
NDDataRef([1, 2, 3, 4])

But also support arithmetic (NDData Arithmetic) like addition:

>>> import astropy.units as u
>>> ndd2 = ndd.add([4, 3, 2, 1] * u.erg / u.s)
>>> ndd2
NDDataRef([ 5.,  5.,  5.,  5.])

Because these operations have a wide range of options these are not available using arithmetic operators like +.

Slicing or indexing (Slicing and Indexing NDData) is possible (issuing warnings if some attribute cannot be sliced):

>>> ndd2[2:]  # discard the first two elements
INFO: wcs cannot be sliced. [astropy.nddata.mixins.ndslicing]
NDDataRef([ 5.,  5.])
>>> ndd2[1]   # get the second element
INFO: wcs cannot be sliced. [astropy.nddata.mixins.ndslicing]
NDDataRef(5.0)

StdDevUncertainty

StdDevUncertainty implements uncertainty based on standard deviation and can propagate these using the arithmetic methods of NDDataRef:

>>> from astropy.nddata import NDDataRef, StdDevUncertainty
>>> import numpy as np

>>> uncertainty = StdDevUncertainty(np.arange(5))
>>> ndd = NDDataRef([5,5,5,5,5], uncertainty=uncertainty)

>>> doubled_ndd = ndd.multiply(2)  # multiply by 2
>>> doubled_ndd.uncertainty
StdDevUncertainty([0, 2, 4, 6, 8])

>>> ndd2 = ndd.add(doubled_ndd)    # add the doubled to the original
>>> ndd2.uncertainty
StdDevUncertainty([ 0.        ,  2.23606798,  4.47213595,  6.70820393,
                    8.94427191])

>>> # or taking into account that both of these uncertainties are correlated
>>> ndd3 = ndd.add(doubled_ndd, uncertainty_correlation=1)
>>> ndd3.uncertainty
StdDevUncertainty([  0.,   3.,   6.,   9.,  12.])

Note

The “amount” of correlation must be given, so 1 means correlated, -1 anti-correlated and 0 (default) uncorrelated. See also NDData Arithmetic for more information about correlation handling.

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 numpy.ndarray-based datasets, using the NDDataBase interface.
NDDataArray(data, *args, **kwd) An NDData object with arithmetic.
NDDataBase() Base metaclass that defines the interface for N-dimensional datasets with associated meta informations used in astropy.
NDDataRef(data[, uncertainty, mask, wcs, ...]) Implements NDData with all Mixins.
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, copy, unit]) This is the metaclass 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, copy, unit]) Standard deviation uncertainty assuming first order gaussian error propagation.
UnknownUncertainty([array, copy, unit]) This class implements any 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.