astro py:docs

- Index
- Modules

### Navigation

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

# NDData

## Overview

The `NDData` class is a container for gridded N-dimensional data. It has a `data` attribute, which can be any object that presents an array-like interface, and optional attributes:

- `meta`, for metadata
- `unit` for the `data` unit
- `uncertainty` for the uncertainty of the data (which could be standard deviation,variance, or something else),
- `mask` for the `data`
- `wcs`, representing the relationship between `data` and world coordinates.

Of these, only `mask` and `uncertainty` may be changed after the NDData object is created.

## Initializing

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)

Note that the data in `ndd` is a reference to the original `array`, so changing the data in `ndd` will change the corresponding data in `array` in most circumstances.

An `NDData` object can also be instantiated by passing it an `NDData` object:

    >>> ndd1 = NDData(array)
    >>> ndd2 = NDData(ndd1)

As above, the data in``ndd2`` is a reference to the data in `ndd1`, so changes to one will affect the other.

It can also be instantiated by passing in an object that can be converted to a numpy numerical array:

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

The final way to instantiate an `NDData` object is with a data object that presents a numpy array-like interface. If the object passed to the intializer has all three of the attributes `shape`, `__getitem__` (so it is indexable) and `__array__` (so that it can act like a numpy array in expression) then the `data` attribute will be set to that object.

The purpose of this mechanism is to allow considerable flexibility in the objects used to store the data while providing a useful to default (numpy array).

## Mask

Values can be masked using the `mask` attribute. One straightforward way to provide a mask is to use a boolean numpy array:

    >>> ndd_masked = NDData(ndd, mask = ndd.data > 0.9)
    INFO: Overwriting NDData's current mask with specified mask [astropy.nddata.nddata]

Another is to simply initialize an `NDData` object with a masked numpy array:

    >>> masked_array = np.ma.array([1, 2, 3, 4], mask=[1, 0, 0, 1])
    >>> ndd_masked = NDData(masked_array)
    >>> ndd_masked.mask
    array([ True, False, False,  True], dtype=bool)

A mask value of `True` indicates a value that should be ignored, while a mask value of `False` indicates a valid value.

There is no requirement that the mask actually be a numpy array; for example, a function which evaluates a mask value as needed is acceptable as long as it follows the convention that `True` indicates a value that should be ignored.

## Unit

The unit of the data can be set by either explicitly providing an astropy unit when creating the `NDData` object:

    >>> import astropy.units as u
    >>> ndd_unit = NDData([1, 2, 3, 4], unit="meter")
    >>> ndd_unit.unit
    Unit("m")

or by initializing with data that is an astropy `Quantity`:

    >>> q = [1, 2, 3, 4] * u.meter
    >>> ndd_unit2 = NDData(q)
    >>> ndd_unit2.unit
    Unit("m")

## Uncertainties

`NDData` objects have an `uncertainty` attribute that can be used to set the uncertainty on the data values. The `uncertainty` must have an attribute `uncertainty_type` which is a string.

While not a requirement, the following `uncertainty_type` strings are strongly recommended for common ways of specifying normal distributions:

- `"std"`: if `uncertainty` stores the standard deviation/sigma (either a single value or on a per-pixel basis).
- `"var"`: if `uncertainty` stores the variance (either a single value or on a per-pixel basis).
- `"ivar"`: if `uncertainty` stores the inverse variance (either a single value or on a per-pixel basis).

Note

For information on creating your own uncertainty classes, see Subclassing.

## Meta-data

The `NDData` class includes a `meta` attribute that defaults to an empty ordered dictionary, and can be used to set overall meta- data for the dataset:

    ndd.meta['exposure_time'] = 340.
    ndd.meta['filter'] = 'J'

Elements of the meta-data dictionary can be set to any valid Python object:

    ndd.meta['history'] = ['calibrated', 'aligned', 'flat-fielded']

The metadata can be any python object that presents a dict-like interface. For example, a FITS header can be used as the metadata:

    >>> from astropy.io import fits
    >>> header = fits.Header()
    >>> header['observer'] = 'Edwin Hubble'
    >>> ndd = NDData(np.zeros([10, 10]), meta=header)
    >>> ndd.meta['observer']
    'Edwin Hubble'

## WCS

At the moment the `wcs` attribute can be set to any object, though in the future it may be restricted to an `WCS` object once a generalized WCS object is developed.

## Converting to Numpy arrays

Data should be accessed through the `data` attribute:

    >>> array = np.asarray(ndd.data)

Though using `np.asarray` is not required it will ensure that an additional copy of the data is not made if the data is a numpy array.

Note that if the data is masked you must explicitly construct a numpy masked array like this:

    >>> input_array = np.ma.array([1, 2, 3, 4], mask=[1, 0, 0, 1])
    >>> ndd_masked = NDData(input_array)
    >>> masked_array = np.ma.array(ndd_masked.data, mask=ndd_masked.mask)