# 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 astropy’s 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, ...]) |
Decorator to wrap functions that could accept an NDData instance with its properties passed as 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 information 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. |