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 fornumpy.ndarray
-like data.NDDataRef
: likeNDData
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
andwrite
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.
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 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. |