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 ofnddata
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 theuncertainty
must have a attribute calleduncertainty_type
otherwise it will be converted to anUnknownUncertainty
.
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 onNDData
objects that include support propagation of uncertainties (in limited cases).NDIOMixin
to use existing astropy functionality for input (with the methodread
) and output (with the methodwrite
).
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.
Using nddata
¶
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. |