astrodata package

This package add another abstraction layer to astronomical data by parsing the information contained in the headers as attributes. To do so, one must subclass astrodata.AstroData and add parse methods accordingly to the TagSet received.

class astrodata.AstroData(nddata=None, tables=None, phu=None, indices=None, is_single=False)[source]

Bases: object

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

Parameters:

nddata (astrodata.NDAstroData or list of astrodata.NDAstroData) – List of NDAstroData objects.
tables (dict[name, astropy.table.Table]) – Dict of table objects.
phu (astropy.io.fits.Header) – Primary header.
indices (list of int) – List of indices mapping the astrodata.NDAstroData objects that this object will access to. This is used when slicing an object, then the sliced AstroData will have the .nddata list from its parent and access the sliced NDAstroData through this list of indices.

add(oper)

Performs inplace addition by evaluating self += operand.

Parameters:: oper (number or object) – The operand to perform the operation self += operand.
Return type:: AstroData instance

append(ext, name=None, header=None)[source]

Adds a new top-level extension.

Parameters:

ext (array, astropy.nddata.NDData, astropy.table.Table, other) – The contents for the new extension. 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 astropy.io.fits.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. If the name cannot be derived from the metadata associated to ext, you will have to provider one. 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 – Raised if the extension is of a proper type, but its value is illegal somehow.

crop(x1, y1, x2, y2)[source]

Crop the NDData objects given indices.

Parameters:

x1 (int) – Minimum and maximum indices for the x and y axis.
y1 (int) – Minimum and maximum indices for the x and y axis.
x2 (int) – Minimum and maximum indices for the x and y axis.
y2 (int) – Minimum and maximum indices for the x and y axis.

property data: A list of the arrays (or single array, if this is a single slice) corresponding to the science data attached to each extension.

property descriptors

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

Return type:: tuple of str

divide(oper)

Performs inplace division by evaluating self /= operand.

Parameters:: oper (number or object) – The operand to perform the operation self /= operand.
Return type:: AstroData instance

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 (i.e. data objects that have been added dynamically).

Examples

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

property ext_tables: Return the names of the astropy.table.Table objects associated to an extension.

property filename: Return the file name.

property hdr: Return all headers, as a astrodata.fits.FitsHeaderCollection.

property header

property id: Returns the extension identifier (1-based extension number) for sliced objects.

property indices: Returns the extensions indices for sliced objects.

info()[source]: Prints out information about the contents of this instance.

instrument()[source]: Returns the name of the instrument making the observation.

is_settable(attr)[source]: Return True if the attribute is meant to be modified.

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

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.

classmethod load(source, extname_parser=None): Read from a file, file object, HDUList, etc.

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.

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

multiply(oper)

Performs inplace multiplication by evaluating self *= operand.

Parameters:: oper (number or object) – The operand to perform the operation self *= operand.
Return type:: AstroData instance

property nddata

Return the list of astrodata.NDAstroData objects.

If the AstroData object is sliced, this returns only the NDData objects of the sliced extensions. And if this is a single extension object, the NDData object is returned directly (i.e. not a list).

object()[source]: Returns the name of the object being observed.

operate(operator, *args, **kwargs)[source]

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:
    ext.data = operator(ext.data, *args, **kwargs)
    if ext.mask is not None:
        ext.mask = operator(ext.mask, *args, **kwargs)
    if ext.variance is not None:
        ext.variance = operator(ext.variance, *args, **kwargs)

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

Parameters:

operator (callable) – A function that takes an array (and, maybe, other arguments) and returns an array.
args (optional) – Additional arguments to be passed to the operator.
kwargs (optional) – Additional arguments to be passed to the operator.

Examples

>>> import numpy as np
>>> ad.operate(np.squeeze)

property orig_filename: Return the original file name (before it was modified).

property path: Return the file path.

property phu: Return the primary header.

classmethod read(source, extname_parser=None)[source]: Read from a file, file object, HDUList, etc.

reset(data, mask=<object object>, variance=<object object>, check=True)[source]

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 shape

subtract(oper)

Performs inplace subtraction by evaluating self -= operand.

Parameters:: oper (number or object) – The operand to perform the operation self -= operand.
Return type:: AstroData instance

table()[source]

property tables: Return the names of the astropy.table.Table objects associated to the top-level object.

property tags: A set of strings that represent the tags defining this instance.

telescope()[source]: Returns the name of the telescope.

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.

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

See also

variance: The actual array supporting the uncertainty object.

update_filename(prefix=None, suffix=None, strip=False)[source]

Update the “filename” attribute of the AstroData object.

A prefix and/or suffix can be specified. If strip=True, these will replace the existing prefix/suffix; if strip=False, they will simply be prepended/appended.

The current filename is broken down into its existing prefix, root, and suffix using the ORIGNAME phu keyword, if it exists and is contained within the current filename. Otherwise, the filename is split at the last underscore and the part before is assigned as the root and the underscore and part after the suffix. No prefix is assigned.

Note that, if strip=True, a prefix or suffix will only be stripped if ‘’ is specified.

Parameters:

prefix (str, optional) – New prefix (None => leave alone)
suffix (str, optional) – New suffix (None => leave alone)
strip (bool, optional) – Strip existing prefixes and suffixes if new ones are given?

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.

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

See also

uncertainty: The uncertainty objects used under the hood.

property wcs: Returns the list of WCS objects for each extension.

write(filename=None, overwrite=False)[source]

Write the object to disk.

Parameters:

filename (str, optional) – If the filename is not given, self.path is used.
overwrite (bool) – If True, overwrites existing file.

exception astrodata.AstroDataError[source]: Bases: Exception

class astrodata.AstroDataMixin[source]

Bases: object

A Mixin for NDData-like classes (such as Spectrum1D) to enable them to behave similarly to AstroData objects.

These behaviors are:

mask attributes are combined with bitwise, not logical, or, since the individual bits are important.
The WCS must be a gwcs.WCS object and slicing results in the model being modified.
There is a settable variance attribute.
Additional attributes such as OBJMASK can be extracted from the .meta[‘other’] dict

has_mask()[source]: Returns True if the mask is not None without loading the whole array.

has_variance()[source]: Returns True if the mask is not None without loading the whole array.

property shape

property size

property variance: A convenience property to access the contents of uncertainty.

property wcs

class astrodata.NDAstroData(data, uncertainty=None, mask=None, wcs=None, meta=None, unit=None, copy=False, window=None, variance=None)[source]

Bases: AstroDataMixin, NDArithmeticMixin, NDSlicingMixin, NDData

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 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 T

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

property mask

Mask for the dataset, if any.

Masks should follow the numpy convention that valid data points are marked by False and invalid ones with True.

Type:: any type

set_section(section, input)[source]

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)

transpose()[source]

property uncertainty

Uncertainty in the dataset, if any.

Should have an attribute uncertainty_type that defines what kind of uncertainty is stored, such as 'std' for standard deviation or 'var' for variance. A metaclass defining such an interface is NDUncertainty but isn’t mandatory.

Type:: any type

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 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.Section(*args, **kwargs)[source]

Bases: tuple

A class to handle n-dimensional sections

asIRAFsection(binning=None)[source]

Produce string of style ‘[x1:x2,y1:y2]’ that is 1-indexed and end-inclusive

Parameters:: binning (iterable) – A length-2 iterable of (x_binning, y_binning). Binning is assumed to be 1 for all axes if not given.

asslice(add_dims=0)[source]: Return the Section object as a slice/list of slices. Higher dimensionality can be achieved with the add_dims parameter.

contains(section)[source]: Return True if the supplied section is entirely within self

static from_shape(value)[source]: produce a Section object defining a given shape

static from_string(value)[source]: The inverse of __str__, produce a Section object from a string

is_same_size(section)[source]: Return True if the Sections are the same size

property ndim

overlap(section)[source]: Determine whether the two sections overlap. If so, the Section common to both is returned, otherwise None

shift(*shifts)[source]: Shift a section in each direction by the specified amount

class astrodata.TagSet(add=None, remove=None, blocked_by=None, blocks=None, if_present=None)[source]

Bases: TagSet

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, optional

remove

Tags to be removed from the global set

Type:: set of str, optional

blocked_by

Tags that will prevent this TagSet from being applied

Type:: set of str, optional

blocks

Other TagSets containing these won’t be applied

Type:: set of str, optional

if_present

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

Type:: set of str, optional

Examples

>>> TagSet()
TagSet(add=set(), remove=set(), blocked_by=set(), blocks=set(), if_present=set())
>>> TagSet({'BIAS', 'CAL'})
TagSet(add={'BIAS', 'CAL'}, remove=set(), blocked_by=set(), blocks=set(), if_present=set())
>>> TagSet(remove={'BIAS', 'CAL'})
TagSet(add=set(), remove={'BIAS', 'CAL'}, blocked_by=set(), blocks=set(), if_present=set())

astrodata.add_header_to_table(table)[source]

astrodata.astro_data_descriptor(fn)[source]

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.astro_data_tag(fn)[source]

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.create(phu, extensions=None)

Creates an AstroData object from a collection of objects.

Parameters:

phu (fits.PrimaryHDU or fits.Header or dict or list) – FITS primary HDU or header, or something that can be used to create a fits.Header (a dict, a list of “cards”).
extensions (list of HDUs) – List of HDU objects.

astrodata.open(source)

Takes either a string (with the path to a file) or an HDUList as input, and tries to return an AstroData instance.

It will raise exceptions if the file is not found, or if there is no match for the HDUList, among the registered AstroData classes.

Returns an instantiated object, or raises AstroDataError if it was not possible to find a match

Parameters:: source (str or pathlib.Path or fits.HDUList) – The file path or HDUList to read.

astrodata.version(short=False, tag='')[source]

Returns DRAGONS’s version based on the api, feature and bug numbers.

Returns:: str
Return type:: formatted version

Submodules

astrodata.core module

class astrodata.core.AstroData(nddata=None, tables=None, phu=None, indices=None, is_single=False)[source]

Bases: object

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

Parameters:

nddata (astrodata.NDAstroData or list of astrodata.NDAstroData) – List of NDAstroData objects.
tables (dict[name, astropy.table.Table]) – Dict of table objects.
phu (astropy.io.fits.Header) – Primary header.
indices (list of int) – List of indices mapping the astrodata.NDAstroData objects that this object will access to. This is used when slicing an object, then the sliced AstroData will have the .nddata list from its parent and access the sliced NDAstroData through this list of indices.

add(oper)

Performs inplace addition by evaluating self += operand.

Parameters:: oper (number or object) – The operand to perform the operation self += operand.
Return type:: AstroData instance

append(ext, name=None, header=None)[source]

Adds a new top-level extension.

Parameters:

ext (array, astropy.nddata.NDData, astropy.table.Table, other) – The contents for the new extension. 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 astropy.io.fits.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. If the name cannot be derived from the metadata associated to ext, you will have to provider one. 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 – Raised if the extension is of a proper type, but its value is illegal somehow.

crop(x1, y1, x2, y2)[source]

Crop the NDData objects given indices.

Parameters:

x1 (int) – Minimum and maximum indices for the x and y axis.
y1 (int) – Minimum and maximum indices for the x and y axis.
x2 (int) – Minimum and maximum indices for the x and y axis.
y2 (int) – Minimum and maximum indices for the x and y axis.

property data: A list of the arrays (or single array, if this is a single slice) corresponding to the science data attached to each extension.

property descriptors

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

Return type:: tuple of str

divide(oper)

Performs inplace division by evaluating self /= operand.

Parameters:: oper (number or object) – The operand to perform the operation self /= operand.
Return type:: AstroData instance

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 (i.e. data objects that have been added dynamically).

Examples

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

property ext_tables: Return the names of the astropy.table.Table objects associated to an extension.

property filename: Return the file name.

property hdr: Return all headers, as a astrodata.fits.FitsHeaderCollection.

property header

property id: Returns the extension identifier (1-based extension number) for sliced objects.

property indices: Returns the extensions indices for sliced objects.

info()[source]: Prints out information about the contents of this instance.

instrument()[source]: Returns the name of the instrument making the observation.

is_settable(attr)[source]: Return True if the attribute is meant to be modified.

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

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.

classmethod load(source, extname_parser=None): Read from a file, file object, HDUList, etc.

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.

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

multiply(oper)

Performs inplace multiplication by evaluating self *= operand.

Parameters:: oper (number or object) – The operand to perform the operation self *= operand.
Return type:: AstroData instance

property nddata

Return the list of astrodata.NDAstroData objects.

If the AstroData object is sliced, this returns only the NDData objects of the sliced extensions. And if this is a single extension object, the NDData object is returned directly (i.e. not a list).

object()[source]: Returns the name of the object being observed.

operate(operator, *args, **kwargs)[source]

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:
    ext.data = operator(ext.data, *args, **kwargs)
    if ext.mask is not None:
        ext.mask = operator(ext.mask, *args, **kwargs)
    if ext.variance is not None:
        ext.variance = operator(ext.variance, *args, **kwargs)

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

Parameters:

operator (callable) – A function that takes an array (and, maybe, other arguments) and returns an array.
args (optional) – Additional arguments to be passed to the operator.
kwargs (optional) – Additional arguments to be passed to the operator.

Examples

>>> import numpy as np
>>> ad.operate(np.squeeze)

property orig_filename: Return the original file name (before it was modified).

property path: Return the file path.

property phu: Return the primary header.

classmethod read(source, extname_parser=None)[source]: Read from a file, file object, HDUList, etc.

reset(data, mask=<object object>, variance=<object object>, check=True)[source]

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 shape

subtract(oper)

Performs inplace subtraction by evaluating self -= operand.

Parameters:: oper (number or object) – The operand to perform the operation self -= operand.
Return type:: AstroData instance

table()[source]

property tables: Return the names of the astropy.table.Table objects associated to the top-level object.

property tags: A set of strings that represent the tags defining this instance.

telescope()[source]: Returns the name of the telescope.

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.

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

See also

variance: The actual array supporting the uncertainty object.

update_filename(prefix=None, suffix=None, strip=False)[source]

Update the “filename” attribute of the AstroData object.

A prefix and/or suffix can be specified. If strip=True, these will replace the existing prefix/suffix; if strip=False, they will simply be prepended/appended.

The current filename is broken down into its existing prefix, root, and suffix using the ORIGNAME phu keyword, if it exists and is contained within the current filename. Otherwise, the filename is split at the last underscore and the part before is assigned as the root and the underscore and part after the suffix. No prefix is assigned.

Note that, if strip=True, a prefix or suffix will only be stripped if ‘’ is specified.

Parameters:

prefix (str, optional) – New prefix (None => leave alone)
suffix (str, optional) – New suffix (None => leave alone)
strip (bool, optional) – Strip existing prefixes and suffixes if new ones are given?

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.

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

See also

uncertainty: The uncertainty objects used under the hood.

property wcs: Returns the list of WCS objects for each extension.

write(filename=None, overwrite=False)[source]

Write the object to disk.

Parameters:

filename (str, optional) – If the filename is not given, self.path is used.
overwrite (bool) – If True, overwrites existing file.

astrodata.factory module

exception astrodata.factory.AstroDataError[source]: Bases: Exception

class astrodata.factory.AstroDataFactory[source]

Bases: object

addClass(cls)[source]: Add a new class to the AstroDataFactory registry. It will be used when instantiating an AstroData class for a FITS file.

createFromScratch(phu, extensions=None)[source]

Creates an AstroData object from a collection of objects.

Parameters:

phu (fits.PrimaryHDU or fits.Header or dict or list) – FITS primary HDU or header, or something that can be used to create a fits.Header (a dict, a list of “cards”).
extensions (list of HDUs) – List of HDU objects.

getAstroData(source)[source]

Takes either a string (with the path to a file) or an HDUList as input, and tries to return an AstroData instance.

It will raise exceptions if the file is not found, or if there is no match for the HDUList, among the registered AstroData classes.

Returns an instantiated object, or raises AstroDataError if it was not possible to find a match

Parameters:: source (str or pathlib.Path or fits.HDUList) – The file path or HDUList to read.

astrodata.fits module

class astrodata.fits.FitsHeaderCollection(headers)[source]

Bases: object

Group access to a list of FITS Header-like objects.

It exposes a number of methods (set, get, etc.) that operate over all the headers at the same time. It can also be iterated.

Parameters:: headers (list of astropy.io.fits.Header) – List of Header objects.

get(key, default=None)[source]

get_comment(key)[source]

remove(key)[source]

set(key, value=None, comment=None)[source]

set_comment(key, comment)[source]

class astrodata.fits.FitsLazyLoadable(obj)[source]

Bases: object

property data

property dtype: Need to to some overriding of astropy.io.fits since it doesn’t know about BITPIX=8

property header

property shape

astrodata.fits.ad_to_hdulist(ad)[source]: Creates an HDUList from an AstroData object.

astrodata.fits.add_header_to_table(table)[source]

astrodata.fits.asdftablehdu_to_wcs(hdu)[source]

Recreate a gWCS object from its serialization in a FITS table extension.

Returns None (issuing a warning) if the extension cannot be parsed, so the rest of the file can still be read.

astrodata.fits.card_filter(cards, include=None, exclude=None)[source]

astrodata.fits.fits_ext_comp_key(ext)[source]: Returns a pair (int, str) that will be used to sort extensions.

astrodata.fits.header_for_table(table)[source]

astrodata.fits.new_imagehdu(data, header, name=None)[source]

astrodata.fits.read_fits(cls, source, extname_parser=None)[source]

Takes either a string (with the path to a file) or an HDUList as input, and tries to return a populated AstroData (or descendant) instance.

It will raise exceptions if the file is not found, or if there is no match for the HDUList, among the registered AstroData classes.

astrodata.fits.table_to_bintablehdu(table, extname=None)[source]

Convert an astropy Table object to a BinTableHDU before writing to disk.

Parameters:

table (astropy.table.Table instance) – the table to be converted to a BinTableHDU
extname (str) – name to go in the EXTNAME field of the FITS header

Return type:

BinTableHDU

astrodata.fits.update_header(headera, headerb)[source]

astrodata.fits.wcs_to_asdftablehdu(wcs, extver=None)[source]

Serialize a gWCS object as a FITS TableHDU (ASCII) extension.

The ASCII table is actually a mini ASDF file. The constituent AstroPy models must have associated ASDF “tags” that specify how to serialize them.

In the event that serialization as pure ASCII fails (this should not happen), a binary table representation will be used as a fallback.

astrodata.fits.windowedOp(func, sequence, kernel, shape=None, dtype=None, with_uncertainty=False, with_mask=False, result=None, **kwargs)[source]

Apply function on a NDData obbjects, splitting the data in chunks to limit memory usage.

Parameters:

func (callable) – The function to apply.
sequence (list of NDData) – List of NDData objects.
kernel (tuple of int) – Shape of the blocks.
shape (tuple of int) – Shape of inputs. Defaults to sequence[0].shape.
dtype (str or dtype) – Type of the output array. Defaults to sequence[0].dtype.
with_uncertainty (bool) – Compute uncertainty?
with_mask (bool) – Compute mask?
result (NDData/None) – if not None, the output will be written to this object
**kwargs – Additional args are passed to func.

astrodata.fits.write_fits(ad, filename, overwrite=False)[source]: Writes the AstroData object to a FITS file.

astrodata.nddata module

This module implements a derivative class based on NDData with some Mixins, implementing windowing and on-the-fly data scaling.

class astrodata.nddata.NDAstroData(data, uncertainty=None, mask=None, wcs=None, meta=None, unit=None, copy=False, window=None, variance=None)[source]

Bases: AstroDataMixin, NDArithmeticMixin, NDSlicingMixin, NDData

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 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 T

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

property mask

Mask for the dataset, if any.

Masks should follow the numpy convention that valid data points are marked by False and invalid ones with True.

Type:: any type

set_section(section, input)[source]

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)

transpose()[source]

property uncertainty

Uncertainty in the dataset, if any.

Should have an attribute uncertainty_type that defines what kind of uncertainty is stored, such as 'std' for standard deviation or 'var' for variance. A metaclass defining such an interface is NDUncertainty but isn’t mandatory.

Type:: any type

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 use of square brackets when specifying the window.
Ultimately, an NDWindowingAstrodata instance is returned.

Examples

>>> ad[0].nddata.window[100:200, 100:200]
<NDWindowingAstrodata .....>

astrodata.provenance module

astrodata.provenance.add_history(ad, timestamp_start, timestamp_stop, primitive, args)[source]

Add the given History entry to the full set of history records on this object.

Parameters:

ad (astrodata.AstroData) – AstroData object to add history record to.
timestamp_start (datetime.datetime) – Date of the start of this operation.
timestamp_stop (datetime.datetime) – Date of the end of this operation.
primitive (str) – Name of the primitive performed.
args (str) – Arguments used for the primitive call.

astrodata.provenance.add_provenance(ad, filename, md5, primitive, timestamp=None)[source]

Add the given provenance entry to the full set of provenance records on this object.

Provenance is added even if the incoming md5 is None or ‘’. This indicates source data for the provenance that are not on disk.

Parameters:

ad (astrodata.AstroData)
filename (str)
md5 (str)
primitive (str)
timestamp (datetime.datetime)

astrodata.provenance.clone_history(history_data, ad)[source]

For a single input’s history, copy it into the output AstroData object as appropriate.

This takes a dictionary with a source filename, md5 and both its original provenance and history information. It duplicates the history data into the outgoing AstroData ad object.

Parameters:

history_data – pointer to the AstroData table with the history information. Note this may be the output AstroData as well, so we need to handle that.
ad (astrodata.AstroData) – Outgoing AstroData object to add history data to.

astrodata.provenance.clone_provenance(provenance_data, ad)[source]

For a single input’s provenance, copy it into the output AstroData object as appropriate.

This takes a dictionary with a source filename, md5 and both its original provenance and history information. It duplicates the provenance data into the outgoing AstroData ad object.

Parameters:

provenance_data – Pointer to the AstroData table with the provenance information. Note this may be the output AstroData as well, so we need to handle that.
ad (astrodata.AstroData) – Outgoing AstroData object to add provenance data to.

astrodata.provenance.find_history_column_indices(ad)[source]

astrodata.provenance.provenance_summary(ad, provenance=True, history=True)[source]

Generate a pretty text display of the provenance information for an AstroData.

This pulls the provenance and history information from a AstroData object and formats it for readability. The primitive arguments in the history are wrapped across multiple lines to keep the overall width manageable.

Parameters:

ad (AstroData) – Input data to read provenance from
provenance (bool) – True to show provenance
history (bool) – True to show the history with associated parameters and timestamps

Return type:

str representation of the provenance and history

astrodata.testing module

astrodata.utils module

exception astrodata.utils.AstroDataDeprecationWarning[source]: Bases: DeprecationWarning

class astrodata.utils.Section(*args, **kwargs)[source]

Bases: tuple

A class to handle n-dimensional sections

asIRAFsection(binning=None)[source]

Produce string of style ‘[x1:x2,y1:y2]’ that is 1-indexed and end-inclusive

Parameters:: binning (iterable) – A length-2 iterable of (x_binning, y_binning). Binning is assumed to be 1 for all axes if not given.

asslice(add_dims=0)[source]: Return the Section object as a slice/list of slices. Higher dimensionality can be achieved with the add_dims parameter.

contains(section)[source]: Return True if the supplied section is entirely within self

static from_shape(value)[source]: produce a Section object defining a given shape

static from_string(value)[source]: The inverse of __str__, produce a Section object from a string

is_same_size(section)[source]: Return True if the Sections are the same size

property ndim

overlap(section)[source]: Determine whether the two sections overlap. If so, the Section common to both is returned, otherwise None

shift(*shifts)[source]: Shift a section in each direction by the specified amount

class astrodata.utils.TagSet(add=None, remove=None, blocked_by=None, blocks=None, if_present=None)[source]

Bases: TagSet

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, optional

remove

Tags to be removed from the global set

Type:: set of str, optional

blocked_by

Tags that will prevent this TagSet from being applied

Type:: set of str, optional

blocks

Other TagSets containing these won’t be applied

Type:: set of str, optional

if_present

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

Type:: set of str, optional

Examples

>>> TagSet()
TagSet(add=set(), remove=set(), blocked_by=set(), blocks=set(), if_present=set())
>>> TagSet({'BIAS', 'CAL'})
TagSet(add={'BIAS', 'CAL'}, remove=set(), blocked_by=set(), blocks=set(), if_present=set())
>>> TagSet(remove={'BIAS', 'CAL'})
TagSet(add=set(), remove={'BIAS', 'CAL'}, blocked_by=set(), blocks=set(), if_present=set())

astrodata.utils.assign_only_single_slice(fn)[source]: Raise ValueError if assigning to a non-single slice.

astrodata.utils.astro_data_descriptor(fn)[source]

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.utils.astro_data_tag(fn)[source]

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.utils.deprecated(reason)[source]

astrodata.utils.normalize_indices(slc, nitems)[source]

astrodata.utils.returns_list(fn)[source]

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

astrodata.wcs module

class astrodata.wcs.AffineMatrices(matrix, offset)

Bases: tuple

matrix: Alias for field number 0

offset: Alias for field number 1

class astrodata.wcs.FrameMapping(cls, description)

Bases: tuple

cls: Alias for field number 0

description: Alias for field number 1

astrodata.wcs.calculate_affine_matrices(func, shape, origin=None)[source]

Compute the matrix and offset necessary of an affine transform that represents the supplied function. This is done by computing the linear matrix along all axes extending from the centre of the region, and then calculating the offset such that the transformation is accurate at the centre of the region. The matrix and offset are returned in the standard python order (i.e., y-first for 2D).

Parameters:

func (callable) – function that maps input->output coordinates; these coordinates are x-first, because “func” is usually an astropy.modeling.Model
shape (sequence) – shape to use for fiducial points
origin (sequence/None) – if a sequence, then use this as the opposite vertex (it must be the same length as “shape”)

Returns:

affine matrix and offset

Return type:

AffineMatrices(array, array)

astrodata.wcs.create_new_image_projection(transform, new_center)[source]

Modifies a simple imaging transform (Shift & Shift) | AffineTransformation2D | Pix2Sky | RotateNative2Celestial so that the projection center is in a different sky location

This works by rotating the AffineTransformation2D.matrix by the change in angle (in Euclidean geometry) to the pole when moving from the original projection center to the new one. The sign of this angle depends on whether East is to the left or right when North is up. This works even when the pole is on the image.

This is accurate to <0.1 arcsec for shifts of up to 1 degree

Parameters:

transform (Model) – current forward imaging transform
new_center (tuple) – (RA, DEC) coordinates of new projection center

Returns:

Model

Return type:

a transform that is projected around the new center

astrodata.wcs.fitswcs_image(header)[source]

Make a complete transform from CRPIX-shifted pixels to sky coordinates from FITS WCS keywords. A Mapping is inserted at the beginning, which may be removed later

Parameters:: header (astropy.io.fits.Header or dict) – FITS Header or dict with basic FITS WCS keywords.

astrodata.wcs.fitswcs_other(header, other=None)[source]

Create WCS linear transforms for any axes not associated with celestial coordinates. We require that each world axis aligns precisely with only a single pixel axis.

Parameters:: header (astropy.io.fits.Header or dict) – FITS Header or dict with basic FITS WCS keywords.

astrodata.wcs.fitswcs_to_gwcs(input)[source]: Create and return a gWCS object from a FITS header or NDData object. If it can’t construct one, it should quietly return None.

astrodata.wcs.get_axes(header)[source]

Matches input with spectral and sky coordinate axes.

Parameters:: header (astropy.io.fits.Header or dict) – FITS Header (or dict) with basic WCS information.
Returns:: sky_inmap, spectral_inmap, unknown – indices in the output representing sky and spectral coordinates.
Return type:: list

astrodata.wcs.gwcs_to_fits(ndd, hdr=None)[source]

Convert a gWCS object to a collection of FITS WCS keyword/value pairs, if possible. If the FITS WCS is only approximate, this should be indicated with a dict entry {‘FITS-WCS’: ‘APPROXIMATE’}. If there is no suitable FITS representation, then a ValueError or NotImplementedError can be raised.

Parameters:

ndd (astropy.nddata.NDData) – The NDData whose wcs attribute we want converted
hdr (astropy.io.fits.Header) – A Header object that may contain some useful keywords

Returns:

values to insert into the FITS header to express this WCS

Return type:

dict

astrodata.wcs.make_fitswcs_transform(input)[source]

Create a basic FITS WCS transform. It does not include distortions.

Parameters:: header (astropy.io.fits.Header or dict) – FITS Header (or dict) with basic WCS information

astrodata.wcs.model_is_affine(model)[source]

” Test a Model for affinity. This is currently done by checking the name of its class (or the class names of all its submodels)

TODO: Is this the right thing to do? We could compute the affine matrices assuming affinity, and then check that a number of random points behave as expected. Is that better?

astrodata.wcs.pixel_frame(naxes, name='pixels')[source]

Make a CoordinateFrame for pixels

Parameters:: naxes (int) – Number of axes
Return type:: CoordinateFrame

astrodata.wcs.read_wcs_from_header(header)[source]

Extract basic FITS WCS keywords from a FITS Header.

Parameters:: header (astropy.io.fits.Header) – FITS Header with WCS information.
Returns:: wcs_info – A dictionary with WCS keywords.
Return type:: dict

astrodata.wcs.remove_axis_from_frame(frame, axis)[source]

Remove the numbered axis from a CoordinateFrame and return a modified CoordinateFrame instance.

Parameters:

frame (CoordinateFrame) – The frame from which an axis is to be removed
axis (int) – index of the axis to be removed

Returns:

CoordinateFrame

Return type:

the modified frame

astrodata.wcs.remove_axis_from_model(model, axis)[source]

Take a model where one output (axis) is no longer required and try to construct a new model whether that output is removed. If the number of inputs is reduced as a result, then report which input (axis) needs to be removed.

Parameters:

model (astropy.modeling.Model instance) – model to modify
axis (int) – Output axis number to be removed from the model

Returns:

tuple – needed (input axis == None if completely removed)

Return type:

Modified version of the model and input axis that is no longer

astrodata.wcs.remove_unused_world_axis(ext)[source]

Remove a single axis from the output frame of the WCS if it has no dependence on input pixel location.

Parameters:: ext (single-slice AstroData object)