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
__itruediv__
- __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.
- 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
- 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
- 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
- __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
- __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.
- Return type
self
- __imul__(oper)
Implements the augmented arithmetic assignment *=.
- Parameters
oper (number or object) – The operand to be multiplied to this instance. The accepted types depend on the DataProvider.
- Return type
self
- __init__(provider)
- __isub__(oper)
Implements the augmented arithmetic assignment -=.
- Parameters
oper (number or object) – The operand to be subtracted to this instance. The accepted types depend on the DataProvider.
- Return type
self
- __len__()
Number of independent extensions stored by the DataProvider
- 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 multiplied to this instance. The accepted types depend on the DataProvider.
- 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.
- 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 multiplied to this instance. The accepted types depend on the DataProvider.
- 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 subtracted to this instance. The accepted types depend on the DataProvider.
- Return type
A new AstroData instance
- __truediv__(oper)
Implements the binary arithmetic operation / with AstroData as the left operand.
- Parameters
oper (number or object) – The operand to be divided to this instance. The accepted types depend on the DataProvider.
- 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.
- property descriptors
Returns a sequence of names for the methods that have been decorated as descriptors.
- Return type
A tuple of str
- abstract info()
Prints out information about the contents of this instance. Implemented by the derived classes.
- abstract 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
- property 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.
- abstract __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
- abstract __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.
- abstract __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.
- abstract __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.
- abstract __itruediv__(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.
- abstract __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.
- Return type
An integer
- __weakref__
list of weak references to the object (if defined)
- abstract 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
- abstract property 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.
- property 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'])
- abstract 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) –
- Return type
A boolean
- property is_single
If this data provider represents a single slice out of a whole dataset, return True. Otherwise, return False.
- Return type
A boolean
- property is_sliced
If this data provider instance represents the whole dataset, return False. If it represents a slice out of the whole, return True.
- Return type
A boolean
- abstract property 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.
- abstract property 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
- abstract property 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.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 someAstroData
specifics.This class implements an
NDData
-like container that supports reading and writing as implemented in theastropy.io.registry
and also slicing (indexing) and simple arithmetics (add, subtract, divide and multiply).A very important difference between
NDAstroData
andNDData
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
orNDDataBase
, i.e. simple arithmetics:>>> from astropy.nddata import 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.- property 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 replacedinput (
NDData
-like instance) – This object needs to implement at leastdata
,uncertainty
, andmask
. Their entire contents will replace the data in the area defined bysection
.
Examples
>>> sec = NDData(np.zeros((100,100))) >>> ad[0].nddata.set_section((slice(None,100),slice(None,100)), sec)
- property variance
A convenience property to access the contents of
uncertainty
, squared (as the uncertainty data is stored as standard deviation).
- property 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 useof 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
, andmask
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
- 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
- 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
- Return type
A function