NDLater

class ndmapper.data.NDLater(data=None, uncertainty=None, mask=None, wcs=None, flags=None, meta=None, unit=None, ident=None, iomap=None)

Bases: astropy.nddata.NDDataArray

A compatible variant of NDDataArray that facilitates lazy loading of pixel data, allowing code to work freely with NDData-like objects (including just doing bookeeping with the headers) without using more memory than necessary.

The main API difference from NDDataArray is that NDLater is initialized with a file name & indices (eg. FITS extension numbers) for getting/ saving the data on demand. This very simple interface does not include any safety checks and it’s the caller’s responsibility to take care of managing the file structure, existence etc., which can be taken care of by the higher-level DataFile class. A subset of NDData.__init__() parameters are also accepted, allowing creation from an existing NDData instance or ndarrays (eg. for writing to a new file); this will override any existing data in the file at the specified indices.

Any mask, wcs & unit values will be derived (once implemented) directly from the input meta-data, rather than specified here, and can then be overridden after instantiation if necessary.

Parameters:

data : ndarray or NDData, optional.

The main data array contained in this object, overriding any existing data in the mapped file, if applicable. If the intention is to use a new copy of the input object rather than a reference to it, the user should make that copy beforehand.

uncertainty : NDUncertainty, optional

Uncertainties on the data.

mask : ndarray-like, optional

Mask for the data, given as a boolean Numpy array or any object that can be converted to a boolean Numpy array with a shape matching that of the data. The values must be False where the data is valid and True when it is not (like Numpy masked arrays). If data is a numpy masked array, providing mask here will causes the mask from the masked array to be ignored.

Warning

This option is provided for compatibility with NDData but the mask attribute is currently unused in NDMapper (though it may still be manipulated by user code); information about bad pixels is instead propagated in flags. This may change in future.

flags : ndarray-like or FlagCollection, optional

Flags giving information about each pixel. These can be specified either as a Numpy array of any type (or an object which can be converted to a Numpy array) with a shape matching that of the data, or as a FlagCollection instance which has a shape matching that of the data.

wcs : undefined, optional

WCS-object containing the world coordinate system for the data.

Warning

This is not yet defind because the discussion of how best to represent this class’s WCS system generically is still under consideration. For now just leave it as None.

meta : dict-like object, optional

Metadata for this object. “Metadata” here means all information that is included with this object but not part of any other attribute of this particular object. e.g., creation date, unique identifier, simulation parameters, exposure time, telescope name, etc.

unit : UnitBase instance or str, optional

The units of the data.

ident : int (str to be supported later), optional

File-independent identifier for this NDLater instance (eg. MOS slit number, CCD/amplifier number or object name). This is used to determine the correspondence of NDLater instances across multiple DataFile objects. [The use of string identifiers would currently cause incompatibility with IRAF run_task, until more bookkeeping is added to map them to numeric EXTVERs for the FITS kernel; also, the back-end loader/saver would also need modifications to handle them.]

iomap : NDMapIO, optional

An object that maps the data, uncertainty & flags attributes to a file name and indices within that file, enabling those attribute values to be lazily loaded. Internally, this iomap remains pointing to the existing file location with which the NDLater instance was last synchronized (loaded/saved), independently of whether the host DataFile (if any) changes, ensuring that the expected data are loaded on demand (as long as the original file still exists). The iomap.ident attribute is therefore independent of NDLater.ident, to allow renaming/numbering.

Attributes

ident	(int (str to be supported later)) As described above. When the NDLater instance is read from a FITS file via DataFile, this value defaults to EXTVER (unless the file was saved from a previous instance with the value overridden). This attribute is an API short cut to meta[‘NDM_ID’], where the value persists.
(See NDDataArray doc string for other methods & attributes.	This is a Work in progress, to support DataFile.)

Attributes Summary

data
flags
ident
meta
uncertainty
unloaded

Methods Summary

add(operand, **kwargs)
bitwise_and(operand)	AND another dataset (operand) to/from/with/by this dataset.
bitwise_or(operand)	OR another dataset (operand) to/from/with/by this dataset.
bitwise_xor(operand)	XOR another dataset (operand) to/from/with/by this dataset.
divide(operand, **kwargs)
invert()	Calculate the bit-wise NOT of this dataset.
multiply(operand, **kwargs)
subtract(operand, **kwargs)

Attributes Documentation

data

flags

ident

meta

uncertainty

unloaded

Methods Documentation

add(operand, **kwargs)

bitwise_and(operand)

AND another dataset (operand) to/from/with/by this dataset.

Parameters:

operand : NDData or None

The second operand in the operation a & b. This should be None for unary operators.

Returns:

result : NDData

The resulting dataset.

Notes

For bit-wise arithmetic (where the use case is generally combining bad pixel masks), any uncertainty & flags are currently dropped. Any WCS is ignored and propagated from self.

bitwise_or(operand)

OR another dataset (operand) to/from/with/by this dataset.

Parameters:

operand : NDData or None

The second operand in the operation a | b. This should be None for unary operators.

Returns:

result : NDData

The resulting dataset.

Notes

For bit-wise arithmetic (where the use case is generally combining bad pixel masks), any uncertainty & flags are currently dropped. Any WCS is ignored and propagated from self.

bitwise_xor(operand)

XOR another dataset (operand) to/from/with/by this dataset.

Parameters:

operand : NDData or None

The second operand in the operation a ^ b. This should be None for unary operators.

Returns:

result : NDData

The resulting dataset.

Notes

For bit-wise arithmetic (where the use case is generally combining bad pixel masks), any uncertainty & flags are currently dropped. Any WCS is ignored and propagated from self.

divide(operand, **kwargs)

invert()

Calculate the bit-wise NOT of this dataset.

Returns:

result : NDData

The resulting dataset.

Notes

For bit-wise arithmetic (where the use case is generally combining bad pixel masks), any uncertainty & flags are currently dropped. Any WCS is ignored and propagated from self.

multiply(operand, **kwargs)

subtract(operand, **kwargs)