astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v1.1.1 »
- N-dimensional datasets (`astropy.nddata`)

# 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.
- General utility functions (astropy.nddata.utils) for array operations.

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.

## Using `nddata`

- NDData
  - Overview
  - Initializing
  - Mask
  - Unit
  - Uncertainties
  - Meta-data
  - WCS
  - Converting to Numpy arrays
- Decorating functions to accept NDData objects
  - Introduction
  - Getting started
- Mixins for added functionality
  - Slicing mixin
  - Arithmetic mixin
  - I/O mixin
- Subclassing
  - `NDDataBase`
  - `NDData`
  - Subclassing `NDUncertainty`
- astropy.nddata.utils
  - Overview
  - 2D Cutout Images
- Reference/API
  - astropy.nddata.utils Module

## 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 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.
`NoOverlapError` | Raised when determining the overlap of non-overlapping arrays.
`PartialOverlapError` | Raised when arrays only partially overlap.
`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 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.