1. API Reference Guide

1.1. Abstract Classes

These classes are the top of their respective hierarchies, and need to be fully implemented before being used. DRAGONS ships with implementations covering the usage of Gemini-style FITS files.

1.1.1. AstroData

class astrodata.core.AstroData(provider)

Base class for the AstroData software package. It provides an interface to manipulate astronomical data sets.

Parameters:provider (DataProvider) – The data that will be manipulated through the AstroData instance.
add(oper)

Alias for __iadd__

subtract(oper)

Alias for __isub__

multiply(oper)

Alias for __imul__

divide(oper)

Alias for __idiv__

__itruediv__(oper)

Alias for __idiv__

__add__(oper)

Implements the binary arithmetic operation + with AstroData as the left operand.

Parameters:oper (number or object) – The operand to be added to this instance. The accepted types depend on the DataProvider
Returns:
Return type:A new AstroData instance
__contains__(attribute)

Implements the ability to use the in operator with an AstroData object. It will look up the specified attribute name within the exposed members of the internal DataProvider object. Refer to the concrete DataProvider implementation’s documentation to know what members are exposed.

Parameters:attribute (string) – An attribute name
Returns:
Return type:A boolean
__deepcopy__(memo)

Returns a new instance of this class, initialized with a deep copy of the associted DataProvider

Parameters:memo (dict) – See the documentation on deepcopy for an explanation on how this works
Returns:
Return type:A deep copy of this instance
__delattr__(attribute)

Implements attribute removal. If self represents a single slice, the

__delitem__(idx)

Called to implement deletion of self[idx]. Supports standard Python syntax (including negative indices).

Parameters:idx (integer) – This index represents the order of the element that you want to remove.
Raises:IndexError – If idx is out of range
__div__(oper)

Implements the binary arithmetic operation / with AstroData as the left operand.

Parameters:oper (number or object) – The operand to be added to this instance. The accepted types depend on the DataProvider
Returns:
Return type:A new AstroData instance
__getattr__(attribute)

Called when an attribute lookup has not found the attribute in the usual places (not an instance attribute, and not in the class tree for self).

This is implemented to provide access to objects exposed by the DataProvider

Parameters:attribute (string) – The attribute’s name
Raises:AttributeError – If the attribute could not be found/computed.
__getitem__(slicing)

Returns a sliced view of the instance. It supports the standard Python indexing syntax.

Parameters:

slice (int, slice) – An integer or an instance of a Python standard slice object

Raises:
  • TypeError – If trying to slice an object when it doesn’t make sense (eg. slicing a single slice)
  • ValueError – If slice does not belong to one of the recognized types
  • IndexError – If an index is out of range

Examples

>>> single = ad[0]
>>> multiple = ad[:5]
__iadd__(oper)

Implements the augmented arithmetic assignment +=.

Parameters:oper (number or object) – The operand to be added to this instance. The accepted types depend on the DataProvider
Returns:
Return type:self
__idiv__(oper)

Implements the augmented arithmetic assignment /=.

Parameters:oper (number or other) – The operand to be added to this instance. The accepted types depend on the DataProvider
Returns:
Return type:self
__imul__(oper)

Implements the augmented arithmetic assignment *=.

Parameters:oper (number or object) – The operand to be added to this instance. The accepted types depend on the DataProvider
Returns:
Return type:self
__init__(provider)

Initialize self. See help(type(self)) for accurate signature.

__isub__(oper)

Implements the augmented arithmetic assignment -=.

Parameters:oper (number or object) – The operand to be added to this instance. The accepted types depend on the DataProvider
Returns:
Return type:self
__len__()

Number of independent extensions stored by the DataProvider

Returns:
Return type:A non-negative integer.
__mul__(oper)

Implements the binary arithmetic operation * with AstroData as the left operand.

Parameters:oper (number or object) – The operand to be added to this instance. The accepted types depend on the DataProvider
Returns:
Return type:A new AstroData instance
__radd__(oper)

Implements the binary arithmetic operation + with AstroData as the left operand.

Parameters:oper (number or object) – The operand to be added to this instance. The accepted types depend on the DataProvider
Returns:
Return type:A new AstroData instance
__rmul__(oper)

Implements the binary arithmetic operation * with AstroData as the left operand.

Parameters:oper (number or object) – The operand to be added to this instance. The accepted types depend on the DataProvider
Returns:
Return type:A new AstroData instance
__setattr__(attribute, value)

Called when an attribute assignment is attempted, instead of the normal mechanism. This method will check first with the DataProvider: if the DP says it will contain this attribute, or that it will accept it for setting, then the value will be stored at the DP level. Otherwise, the regular attribute assignment mechanisme takes over and the value will be store as an instance attribute of self.

Parameters:
  • attribute (string) – The attribute’s name
  • value (object) – The value to be assigned to the attribute
Returns:

  • If the value is passed to the DataProvider, and it is not of an acceptable type,
  • a ValueError (or other exception) may be rised. Please, check the appropriate
  • documentation for this.

__sub__(oper)

Implements the binary arithmetic operation - with AstroData as the left operand.

Parameters:oper (number or object) – The operand to be added to this instance. The accepted types depend on the DataProvider
Returns:
Return type:A new AstroData instance
__weakref__

list of weak references to the object (if defined)

append(extension, name=None, *args, **kw)

Adds a new top-level extension to the provider. Please, read the the concrete DataProvider documentation that is being used to know the exact behavior and additional accepted arguments.

Parameters:
  • extension (array, Table, or other) – The contents for the new extension. Usually the underlying DataProvider will understand how to deal with regular NumPy arrays and with AstroData Table instances, but it may also accept other types.
  • name (string, optional) – A DataProvider will usually require a name for extensions. If the name cannot be derived from the metadata associated to extension, you will have to provider one.
  • args (optional) – The DataProvider may accept additional arguments. Please, refer to its documentation.
  • kw (optional) – The DataProvider may accept additional arguments. Please, refer to its documentation.
Returns:

  • The instance that has been added internally (potentially *not the same that*
  • was passed as *extension)*

Raises:
  • TypeError – Will be raised if the DataProvider doesn’t know how to deal with the data that has been passed.
  • ValueError – Raised if the extension is of a proper type, but its value is illegal somehow.
descriptors

Returns a sequence of names for the methods that have been decorated as descriptors.

Returns:
Return type:A tuple of str
info()

Prints out information about the contents of this instance. Implemented by the derived classes.

load(source)

Class method that returns an instance of this same class, properly initialized with a DataProvider that can deal with the object passed as source

This method is abstract and has to be implemented by derived classes.

operate(operator, *args, **kwargs)

Applies a function to the main data array on each extension, replacing the data with the result. The data will be passed as the first argument to the function.

It will be applied to the mask and variance of each extension, too, if they exist.

This is a convenience method, which is equivalent to:

for ext in ad:
ad.ext.data = operator(ad.ext.data, *args, **kwargs) ad.ext.mask = operator(ad.ext.mask, *args, **kwargs) if ad.ext.mask is not None else None ad.ext.variance = operator(ad.ext.variance, *args, **kwargs) if ad.ext.variance is not None else None

with the additional advantage that it will work on single slices, too.

Parameters:
  • operator (function, or bound method) – A function that takes an array (and, maybe, other arguments) and returns an array
  • args (optional) – Additional arguments to be passed positionally to the operator
  • kwargs (optional) – Additional arguments to be passed by name to the operator

Examples

>>> import numpy as np
>>> ad.operate(np.squeeze)
reset(data, mask=-23, variance=-23, check=True)

Sets the .data, and optionally .mask and .variance attributes of a single-extension AstroData slice. This function will optionally check whether these attributes have the same shape.

Parameters:
  • data (ndarray) – The array to assign to the .data attribute (“SCI”)
  • mask (ndarray, optional) – The array to assign to the .mask attribute (“DQ”)
  • variance (ndarray, optional) – The array to assign to the .variance attribute (“VAR”)
  • check (bool) – If set, then the function will check that the mask and variance arrays have the same shape as the data array
Raises:
  • TypeError – if an attempt is made to set the .mask or .variance attributes with something other than an array
  • ValueError – if the .mask or .variance attributes don’t have the same shape as .data, OR if this is called on an AD instance that isn’t a single extension slice
tags

A set of strings that represent the tags defining this instance

1.1.2. DataProvider

class astrodata.core.DataProvider

Abstract class describing the minimal interface that DataProvider derivative classes need to implement.

__getitem__(slice)

Returns a sliced view of the provider. It supports the standard Python indexing syntax, including negative indices.

Parameters:

slice (int, slice) – An integer or an instance of a Python standard slice object

Raises:
  • TypeError – If trying to slice an object when it doesn’t make sense (eg. slicing a single slice)
  • ValueError – If slice does not belong to one of the recognized types
  • IndexError – If an index is out of range

Examples

>>> single = provider[0]
>>> multiple = provider[:5]
__iadd__(oper)

This method should attempt to do an in-place (modifying self) addition of each internal science object and the oper.

Parameters:oper (object) – An operand to add to the internal science objects. The actual accepted type depends on the implementation
Returns:
  • Generally, it should return self. The implementations may decide to return
  • something else instead.
__idiv__(oper)

This method should attempt to do an in-place (modifying self) division of each internal science object and the oper.

Parameters:oper (object) – An operand to divide the internal science objects by. The actual accepted type depends on the implementation
Returns:
  • Generally, it should return self. The implementations may decide to return
  • something else instead.
__imul__(oper)

This method should attempt to do an in-place (modifying self) multiplication of each internal science object and the oper.

Parameters:oper (object) – An operand to multiply the internal science objects by. The actual accepted type depends on the implementation
Returns:
  • Generally, it should return self. The implementations may decide to return
  • something else instead.
__isub__(oper)

This method should attempt to do an in-place (modifying self) subtraction of each internal science object and the oper.

Parameters:oper (object) – An operand to subtract from the internal science objects. The actual accepted type depends on the implementation
Returns:
  • Generally, it should return self. The implementations may decide to return
  • something else instead.
__len__()

“Length” of the object. This method will typically return the number of science objects contained by this provider, but this may change depending on the implementation.

Returns:
Return type:An integer
__weakref__

list of weak references to the object (if defined)

append(ext, name=None)

Adds a new component to the provider. Objects appended to a single slice will actually be made hierarchically dependent of the science object represented by that slice. If appended to the provider as a whole, the new member will be independent (eg. global table, new science object).

Parameters:
  • ext (array, NDData, Table, etc) – The component to be added. The exact accepted types depend on the class implementing this interface. Implementations specific to certain data formats may accept specialized types (eg. a FITS provider will accept an ImageHDU and extract the array out of it)
  • name (str, optional) –

    A name that may be used to access the new object, as an attribute of the provider. The name is typically ignored for top-level (global) objects, and required for the others.

    It can consist in a combination of numbers and letters, with the restriction that the letters have to be all capital, and the first character cannot be a number (“[A-Z][A-Z0-9]*”).

Returns:

  • The same object, or a new one, if it was necessary to convert it to a more
  • suitable format for internal use.

Raises:
  • TypeError – If adding the object in an invalid situation (eg. name is None when adding to a single slice)
  • ValueError – If adding an object that is not acceptable
data

A list of the the arrays (or single array, if this is a single slice) corresponding to the science data attached to each extension, in loading/appending order.

exposed

A collection of strings with the names of objects that can be accessed directly by name as attributes of this instance, and that are not part of its standard interface (ie. data objects that have been added dynamically).

Examples

>>> ad[0].exposed
set(['OBJMASK', 'OBJCAT'])
>>> ad[0].OBJCAT
...
is_settable(attribute)

Predicate that can be used to figure out if certain attribute of the DataProvider is meant to be modified by an external object.

This is used mostly by AstroData, which acts as a proxy exposing attributes of its assigned provider, to decide if it should set a value on the provider or on itself.

Parameters:attribute (str) –
Returns:
Return type:A boolean
is_single

If this data provider represents a single slice out of a whole dataset, return True. Otherwise, return False.

Returns:
Return type:A boolean
is_sliced

If this data provider instance represents the whole dataset, return False. If it represents a slice out of the whole, return True.

Returns:
Return type:A boolean
mask

A list of the mask arrays (or a single array, if this is a single slice) attached to the science data, for each extension, in loading/appending order.

For objects that miss a mask, None will be provided instead.

uncertainty

A list of the uncertainty objects (or a single object, if this is a single slice) attached to the science data, for each extension, in loading/appending order.

The objects are instances of AstroPy’s NDUncertainty, or None where no information is available.

See also

variance
The actual array supporting the uncertainty object
variance

A list of the variance arrays (or a single array, if this is a single slice) attached to the science data, for each extension, in loading/appending order.

For objects that miss uncertainty information, None will be provided instead.

See also

uncertainty
The NDUncertainty object used under the hood to propagate uncertainty when

operating

1.2. TagSet

class astrodata.core.TagSet(add=None, remove=None, blocked_by=None, blocks=None, if_present=None)

Named tuple that is used by tag methods to return which actions should be performed on a tag set. All the attributes are optional, and any combination of them can be used, allowing to create complex tag structures. Read the documentation on the tag-generating algorithm if you want to better understand the interactions.

The simplest TagSet, though, tends to just add tags to the global set.

It can be initialized by position, like any other tuple (the order of the arguments is the one in which the attributes are listed below). It can also be initialized by name.

add

Tags to be added to the global set

Type:set of str, or None
remove

Tags to be removed from the global set

Type:set of str, or None
blocked_by

Tags that will prevent this TagSet from being applied

Type:set of str, or None
blocks

Other TagSets containing these won’t be applied

Type:set of str, or None
if_present

This TagSet will be applied only all of these tags are present

Type:set of str, or None

Examples

>>> TagSet()
TagSet(add=set([]), remove=set([]), blocked_by=set([]), blocks=set([]), if_present=set([]))
>>> TagSet(set(['BIAS', 'CAL']))
TagSet(add=set(['BIAS', 'CAL']), remove=set([]), blocked_by=set([]), blocks=set([]), if_present=set([]))
>>> TagSet(remove=set(['BIAS', 'CAL']))
TagSet(add=set([]), remove=set(['BIAS', 'CAL']), blocked_by=set([]), blocks=set([]), if_present=set([]))

1.3. NDAstroData

class astrodata.nddata.NDAstroData(data, uncertainty=None, mask=None, wcs=None, meta=None, unit=None, copy=False, window=None)

Implements NDData with all Mixins, plus some AstroData specifics.

This class implements an NDData-like container that supports reading and writing as implemented in the astropy.io.registry and also slicing (indexing) and simple arithmetics (add, subtract, divide and multiply).

A very important difference between NDAstroData and NDData is that the former attempts to load all its data lazily. There are also some important differences in the interface (eg. .data lets you reset its contents after initialization).

Documentation is provided where our class differs.

See also

NDData, NDArithmeticMixin, NDSlicingMixin

Examples

The mixins allow operation that are not possible with NDData or NDDataBase, i.e. simple arithmetics:

>>> from astropy.nddata import NDAstroData, StdDevUncertainty
>>> import numpy as np

>>> data = np.ones((3,3), dtype=np.float)
>>> ndd1 = NDAstroData(data, uncertainty=StdDevUncertainty(data))
>>> ndd2 = NDAstroData(data, uncertainty=StdDevUncertainty(data))

>>> ndd3 = ndd1.add(ndd2)
>>> ndd3.data
array([[ 2.,  2.,  2.],
       [ 2.,  2.,  2.],
       [ 2.,  2.,  2.]])
>>> ndd3.uncertainty.array
array([[ 1.41421356,  1.41421356,  1.41421356],
       [ 1.41421356,  1.41421356,  1.41421356],
       [ 1.41421356,  1.41421356,  1.41421356]])

see NDArithmeticMixin for a complete list of all supported arithmetic operations.

But also slicing (indexing) is possible:

>>> ndd4 = ndd3[1,:]
>>> ndd4.data
array([ 2.,  2.,  2.])
>>> ndd4.uncertainty.array
array([ 1.41421356,  1.41421356,  1.41421356])

See NDSlicingMixin for a description how slicing works (which attributes) are sliced.

data

An array representing the raw data stored in this instance. It implements a setter.

set_section(section, input)

Sets only a section of the data. This method is meant to prevent fragmentation in the Python heap, by reusing the internal structures instead of replacing them with new ones.

Parameters:
  • section (slice) – The area that will be replaced
  • input (NDData-like instance) – This object needs to implement at least data, uncertainty, and mask. Their entire contents will replace the data in the area defined by section.

Examples

>>> sec = NDData(np.zeros((100,100)))
>>> ad[0].nddata.set_section((slice(None,100),slice(None,100)), sec)
variance

A convenience property to access the contents of uncertainty, squared (as the uncertainty data is stored as standard deviation).

window

Interface to access a section of the data, using lazy access whenever possible.

Returns:
  • An instance of NDWindowing, which provides __getitem__, to allow the use
  • of square brackets when specifying the window. Ultimately, an
  • NDWindowingAstrodata instance is returned

Examples

>>> ad[0].nddata.window[100:200, 100:200]
<NDWindowingAstrodata .....>
class astrodata.nddata.NDWindowingAstroData(target, window)

Allows “windowed” access to some properties of an NDAstroData instance. In particular, data, uncertainty, variance, and mask return clipped data.

1.4. Decorators and other helper functions

astrodata.core.astro_data_descriptor(fn)

Decorator that will mark a class method as an AstroData descriptor. Useful to produce list of descriptors, for example.

If used in combination with other decorators, this one must be the one on the top (ie. the last one applying). It doesn’t modify the method in any other way.

Parameters:fn (method) – The method to be decorated
Returns:
Return type:The tagged method (not a wrapper)
astrodata.core.astro_data_tag(fn)

Decorator that marks methods of an AstroData derived class as part of the tag-producing system.

It wraps the method around a function that will ensure a consistent return value: the wrapped method can return any sequence of sequences of strings, and they will be converted to a TagSet. If the wrapped method returns None, it will be turned into an empty TagSet.

Parameters:fn (method) – The method to be decorated
Returns:
Return type:A wrapper function
astrodata.core.returns_list(fn)

Decorator to ensure that descriptors that should return a list (of one value per extension) only returns single values when operating on single slices; and vice versa.

This is a common case, and you can use the decorator to simplify the logic of your descriptors.

Parameters:fn (method) – The method to be decorated
Returns:
Return type:A function