Astrodata User Manual¶
Document ID
PIPE-USER-106_AstrodataUserManual
Introduction¶
This is the AstroData User’s Manual. AstroData is a DRAGONS package.
The current chapter covers basic concepts
like what is the astrodata package and how to install it (together with the
other DRAGONS’ packages). Chapter 2
explains with more details what is AstroData and how the data is represented
using it. Chapter 3 describes input and output operations and
how multi-extension (MEF) FITS files are represented. Chapter 4
provides information regarding the TagSet class, its usage and a few advanced
topics. In Chapter 5 you will find information about the FITS
headers and how to access/modify the metadata. The last two chapters,
Chapter 6 and Chapter 7 cover more details about
how to read, manipulate and write pixel data and tables, respectively.
If you are looking for a quick reference, please, have a look on the AstroData Cheat Sheet.
Reference Documents¶
What is astrodata?¶
astrodata is a package that wraps together tools to represent internally
astronomical datasets stored on disks and to properly parse their metadata
using the AstroData and the TagSet classes. astrodata provides uniform
interfaces for working on datasets from different
instruments. Once a dataset has been opened with astrodata, the object
“knows about itself”. Information like instrument, observation mode, and how
to access headers, is readily available through the uniform interface. All
the details are coded inside the class associated with the instrument, that
class then provides the interface. The appropriate class is selected
automatically when the file is opened and inspected by astrodata.
Currently astrodata implements a representation for Multi-Extension FITS (MEF)
files. (Other representations can be implemented.)
Installing Astrodata¶
The astrodata package has a few dependencies, astropy, numpy and others.
The best way to get everything you need is to install Anaconda, and the
DRAGONS stack from the AstroConda channel.
astrodata itself is part of DRAGONS. It is available from the
repository, as a tar file, or as a conda package. The bare astrodata package
does not do much by itself, it needs a companion instrument definitions
package. For Gemini, this is gemini_instruments, also included in
DRAGONS.
Installing Anaconda and the DRAGONS stack¶
This is required whether you are installing DRAGONS from the
repository, the tar file or the conda package.
- Install Anaconda.
Go to https://www.anaconda.com/download/ and install the latest 64-bit Anaconda.
- Open a bash session.
Anaconda requires bash. If you are not familiar with bash, note that the shell configuration files are named
.bash_profileand.bashrc. During the installation, a PATH setting has been added to your.bash_profileor.bashrcto add the Anaconda bin directory to thePATH.
- Activate Anaconda.
Normal Python 3 installation puts the software in
~/anaconda3/.:$ conda init
- Set up conda channels.
Configure the
condapackage manager to look in the AstroConda channel hosted by STScI, and in the GEMINI Conda Channel. This is a one-time step. It affects current and future Anaconda installations belonging to the same user on the same machine.:$ conda config --add channels http://ssb.stsci.edu/astroconda $ conda config --add channels http://astroconda.gemini.edu/public
- Create an environment.
To keep things clean, Anaconda offers virtual environments. Each project can use its own environment. For example, if you do not want to modify the software packages needed for a previous project, just create a new environment for the new project.
Here we set up an environment where the
DRAGONSdependencies can be installed without affecting the rest of the system when not using that virtual environement. The new virtual environment here is nameddragons. The software has been tested with Python 3.7 hence we recommend that you use this specific version of Python with DRAGONS.$ conda create -n dragons python=3.7 dragons stsci
- Activate your new virtual environment.
$ conda activate dragons
- Configure DRAGONS.
These configurations are not stricktly required when using only
astrodata. It however likely that if you are usingastrodatayou will be using DRAGONS too at some point. So let’s configure it to have it ready to go.DRAGONS requires a configuration file located in
~/.geminidr/. Thersys.cfgfile contains basic configuration for DRAGONS local calibration manager used byreduce.$ cd ~ $ mkdir .geminidr $ cd .geminidr $ touch rsys.cfg
Open
rsys.cfgwith your favorite editor and add these lines:[calibs] standalone = True database_dir = ~/.geminidr/
Next time you start a DRAGONS project, set the
database_dirto a path of your liking, this is where the local calibration database will be written.Then configure buffers for
ds9:$ cd ~/ $ cp $CONDA_PREFIX/lib/python3.7/site-packages/gempy/numdisplay/imtoolrc ~/.imtoolrc $ vi .bash_profile (or use your favority editor) Add this line to the .bash_profile: export IMTOOLRC=~/.imtoolrc
Update an existing DRAGONS installation¶
To check for newer version:
$ conda search dragons
The * will show which version is installed if multiple packages are available.
To update to the newest version:
$ conda update dragons
Smoke test the Astrodata installation¶
From the configured bash shell:
$ type python
python is hashed (<home_path>/anaconda3/envs/dragons/python)
Make sure that python is indeed pointing to the Anaconda environment you
have just set up.
$ python
>>> import astrodata
>>> import gemini_instruments
Expected result: Just a python prompt and no error messages.
Try it yourself¶
Try it yourself
Download the data package if you wish to follow along and run the examples presented in this manual. It is available at:
Unpack it:
$ cd <somewhere_convenient>
$ tar xvf ad_usermanual_datapkg-v1.tar
$ bunzip2 ad_usermanual/playdata/*.bz2
Then
$ cd ad_usermanual/playground
$ python
Astrodata Support¶
Astrodata is developed and supported by staff at the Gemini Observatory.
Questions about the reduction of Gemini data should be directed to the
Gemini Helpdesk system at https://www.gemini.edu/sciops/helpdesk/
The github issue tracker can be used to report software bugs in DRAGONS.
The AstroData Object¶
The AstroData object is an internal representation of a file on disk.
As of this version, only a FITS layer has been written, but AstroData itself
is not limited to FITS.
The internal structure of the AstroData object makes uses of
astropy.nddata.NDData, astropy.table, and
astropy.io.fits.Header, the latter simply because it is a
convenient ordered dictionary.
Try it yourself
Download the data package (Try it yourself) if you wish to follow along and run the examples. Then
$ cd <path>/ad_usermanual/playground
$ python
Global vs Extension-specific¶
At the very top level, the structure is divided in two types of information. In the first category, there is the information that applies to the data globally, for example the information that would be stored in a FITS Primary Header Unit, a table from a catalog that matches the RA and DEC of the field, etc. In the second category, there is the information specific to individual science pixel extensions, for example the gain of the amplifier, the data themselves, the error on those data, etc.
Let us look at an example. The info() method shows
the content of the AstroData object and its organization, from the user’s
perspective.:
>>> import astrodata
>>> import gemini_instruments
>>> ad = astrodata.open('../playdata/N20170609S0154_varAdded.fits')
>>> ad.info()
Filename: N20170609S0154_varAdded.fits
Tags: ACQUISITION GEMINI GMOS IMAGE NORTH OVERSCAN_SUBTRACTED OVERSCAN_TRIMMED
PREPARED SIDEREAL
Pixels Extensions
Index Content Type Dimensions Format
[ 0] science NDAstroData (2112, 256) float32
.variance ndarray (2112, 256) float32
.mask ndarray (2112, 256) uint16
.OBJCAT Table (6, 43) n/a
.OBJMASK ndarray (2112, 256) uint8
[ 1] science NDAstroData (2112, 256) float32
.variance ndarray (2112, 256) float32
.mask ndarray (2112, 256) uint16
.OBJCAT Table (8, 43) n/a
.OBJMASK ndarray (2112, 256) uint8
[ 2] science NDAstroData (2112, 256) float32
.variance ndarray (2112, 256) float32
.mask ndarray (2112, 256) uint16
.OBJCAT Table (7, 43) n/a
.OBJMASK ndarray (2112, 256) uint8
[ 3] science NDAstroData (2112, 256) float32
.variance ndarray (2112, 256) float32
.mask ndarray (2112, 256) uint16
.OBJCAT Table (5, 43) n/a
.OBJMASK ndarray (2112, 256) uint8
Other Extensions
Type Dimensions
.REFCAT Table (245, 16)
The “Pixel Extensions” contain the pixel data. Each extension is represented
individually in a list (0-indexed like all Python lists). The science pixel
data, its associated metadata (extension header), and any other pixel or table
extensions directly associated with that science pixel data are stored in
a NDAstroData object which is a subclass of astropy NDData. We will
return to this structure later. An AstroData extension is accessed like
any list: ad[0]. To access the science pixels, one uses ad[0].data; for
the object mask of the first extension, ad[0].OBJMASK.
In the example above, the “Other Extensions” at the bottom of the
info() display contains a REFCAT table which in
this case is a list of stars from a catalog that overlaps the field of view
covered by the pixel data. The “Other Extensions” are global extensions. They
are not attached to any pixel extension in particular. To access a global
extension one simply uses the name of that extension: ad.REFCAT.
Organization of the Global Information¶
All the global information is stored in attributes of the AstroData object.
The global headers, or Primary Header Unit (PHU), is stored in the phu
attribute as an astropy.io.fits.Header.
Any global tables, like REFCAT above, are stored in the private attribute
_tables as a Python dictionary with the name (eg. “REFCAT”) as the key.
All tables are stored as astropy.table.Table. Access to those table
is done using the key directly as if it were a normal attribute, eg.
ad.REFCAT. Header information for the table, if read in from a FITS table,
is stored in the meta attribute of the astropy.table.Table, eg.
ad.REFCAT.meta['header']. It is for information only, it is not used.
Organization of the Extension-specific Information¶
The pixel data are stored in the AstroData attribute nddata as a list
of NDAstroData object. The NDAstroData object is a subclass of astropy
NDData and it is fully compatible with any function expecting an NDData as
input. The pixel extensions are accessible through slicing, eg. ad[0] or
even ad[0:2]. A slice of an AstroData object is an AstroData object, and
all the global attributes are kept. For example:
>>> ad[0].info()
Filename: N20170609S0154_varAdded.fits
Tags: ACQUISITION GEMINI GMOS IMAGE NORTH OVERSCAN_SUBTRACTED OVERSCAN_TRIMMED
PREPARED SIDEREAL
Pixels Extensions
Index Content Type Dimensions Format
[ 0] science NDAstroData (2112, 256) float32
.variance ndarray (2112, 256) float32
.mask ndarray (2112, 256) uint16
.OBJCAT Table (6, 43) n/a
.OBJMASK ndarray (2112, 256) uint8
Other Extensions
Type Dimensions
.REFCAT Table (245, 16)
Note how REFCAT is still present.
The science data is accessed as ad[0].data, the variance as ad[0].variance,
and the data quality plane as ad[0].mask. Those familiar with astropy
NDData will recognize the structure “data, error, mask”, and will notice
some differences. First AstroData uses the variance for the error plane, not
the standard deviation. Another difference will be evident only when one looks
at the content of the mask. NDData masks contain booleans, AstroData masks
are uint16 bit mask that contains information about the type of bad pixels
rather than just flagging them a bad or not. Since 0 is equivalent to
False (good pixel), the AstroData mask is fully compatible with the
NDData mask.
Header information for the extension is stored in the NDAstroData meta
attribute. All table and pixel extensions directly associated with the
science extension are also stored in the meta attribute.
Technically, an extension header is located in ad.nddata[0].meta['header'].
However, for obviously needed convenience, the normal way to access that header
is ad[0].hdr.
Tables and pixel arrays associated with a science extension are
stored in ad.nddata[0].meta['other'] as a dictionary keyed on the array
name, eg. OBJCAT, OBJMASK. As it is for global tables, astropy tables
are used for extension tables. The extension tables and extra pixel arrays are
accessed, like the global tables, by using the table name rather than the long
format, for example ad[0].OBJCAT and ad[0].OBJMASK.
When reading FITS Table, the header information is stored in the
meta['header'] of the table, eg. ad[0].OBJCAT.meta['header']. That
information is not used, it is simply a place to store what was read from disk.
The header of a pixel extension directly associated with the science extension
should match that of the science extension. Therefore such headers are not
stored in AstroData. For example, the header of ad[0].OBJMASK is the
same as that of the science, ad[0].hdr.
A Note on Memory Usage¶
When an file is opened, the headers are loaded into memory, but the pixels are not. The pixel data are loaded into memory only when they are first needed. This is not real “memory mapping”, more of a delayed loading. This is useful when someone is only interested in the metadata, especially when the files are very large.
Input and Output Operations and Extension Manipulation - MEF¶
AstroData is not intended to be Multi-Extension FITS (MEF) centric. The core
is independent of the file format. At Gemini, our data model uses MEF.
Therefore we have implemented a FITS handler that maps a MEF to the
internal AstroData representation. A different handler can be implemented
for a different file format.
In this chapter, we present examples that will help the reader understand how
to access the information stored in a MEF with the AstroData object and
understand that mapping.
Try it yourself
Download the data package (Try it yourself) if you wish to follow along and run the examples. Then
$ cd <path>/ad_usermanual/playground
$ python
Imports¶
Before doing anything, you need to import AstroData and the Gemini instrument
configuration package gemini_instruments.
>>> import astrodata
>>> import gemini_instruments
Open and access existing dataset¶
Read in the dataset¶
The file on disk is loaded into the AstroData class associated with the
instrument the data is from. This association is done automatically based on
header content.
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> type(ad)
<class 'gemini_instruments.gmos.adclass.AstroDataGmos'>
From now on, ad knows it is GMOS data. It knows how to access its headers
and when using the Recipe System (recipe_system), it will trigger the
selection of the GMOS primitives and recipes.
The original path and filename are stored in the object. If you were to write
the AstroData object to disk without specifying anything, those path and
filename would be used.
>>> ad.path
'../playdata/N20170609S0154.fits'
>>> ad.filename
'N20170609S0154.fits'
Accessing the content of a MEF file¶
Accessing pixel data, headers, and tables will be covered in details in the following chapters. Here we just introduce the basic content interface.
For details on the AstroData structure, please refer to the
previous chapter.
AstroData uses NDData as the core of its structure. Each FITS extension
becomes a NDAstroData object, subclassed from NDData, and is added to
a list.
Pixel data¶
To access pixel data, the list index and the .data attribute are used. That
returns a numpy.ndarray. The list of NDAstroData is zero-indexed.
Extension number 1 in a MEF is index 0 in an |AstroData| object.
>>> ad = astrodata.open('../playdata/N20170609S0154_varAdded.fits')
>>> data = ad[0].data
>>> type(data)
<type 'numpy.ndarray'>
>>> data.shape
(2112, 256)
Remember that in a ndarray the y-axis is the first number.
The variance and data quality planes, the VAR and DQ planes in Gemini MEF
files, are represented by the .variance and .mask attributes,
respectively. They are not their own “extension”, they don’t have their
own index in the list, unlike in a MEF. They are attached to the pixel data,
packaged together by the NDAstroData object. They are represented as
numpy.ndarray just like the pixel data
>>> var = ad[0].variance
>>> dq = ad[0].mask
Tables¶
Tables in the MEF file will also be loaded into the AstroData object. If a table
is associated with a specific science extension through the EXTVER header, that
table will be packaged within the same AstroData extension as the pixel data.
The AstroData “extension” is the NDAstroData object plus any table or other pixel
array. If the table is not associated with a specific extension and applies
globally, it will be added to the AstroData object as a global addition. No
indexing will be required to access it. In the example below, one OBJCAT is
associated with each extension, while the REFCAT has a global scope
>>> ad.info()
Filename: ../playdata/N20170609S0154_varAdded.fits
Tags: ACQUISITION GEMINI GMOS IMAGE NORTH OVERSCAN_SUBTRACTED OVERSCAN_TRIMMED
PREPARED SIDEREAL
Pixels Extensions
Index Content Type Dimensions Format
[ 0] science NDAstroData (2112, 256) float32
.variance ndarray (2112, 256) float32
.mask ndarray (2112, 256) uint16
.OBJCAT Table (6, 43) n/a
.OBJMASK ndarray (2112, 256) uint8
[ 1] science NDAstroData (2112, 256) float32
.variance ndarray (2112, 256) float32
.mask ndarray (2112, 256) uint16
.OBJCAT Table (8, 43) n/a
.OBJMASK ndarray (2112, 256) uint8
[ 2] science NDAstroData (2112, 256) float32
.variance ndarray (2112, 256) float32
.mask ndarray (2112, 256) uint16
.OBJCAT Table (7, 43) n/a
.OBJMASK ndarray (2112, 256) uint8
[ 3] science NDAstroData (2112, 256) float32
.variance ndarray (2112, 256) float32
.mask ndarray (2112, 256) uint16
.OBJCAT Table (5, 43) n/a
.OBJMASK ndarray (2112, 256) uint8
Other Extensions
Type Dimensions
.REFCAT Table (245, 16)
The tables are stored internally as astropy.table.Table objects.
>>> ad[0].OBJCAT
<Table length=6>
NUMBER X_IMAGE Y_IMAGE ... REF_MAG_ERR PROFILE_FWHM PROFILE_EE50
int32 float32 float32 ... float32 float32 float32
------ ------- ------- ... ----------- ------------ ------------
1 283.461 55.4393 ... 0.16895 -999.0 -999.0
...
>>> type(ad[0].OBJCAT)
<class 'astropy.table.table.Table'>
>>> refcat = ad.REFCAT
>>> type(refcat)
<class 'astropy.table.table.Table'>
Headers¶
Headers are stored in the NDAstroData .meta attribute as astropy.io.fits.Header objects,
which is a form of Python ordered dictionaries. Headers associated with extensions
are stored with the corresponding NDAstroData object. The MEF Primary Header
Unit (PHU) is stored “globally” in the AstroData object. Note that when slicing an AstroData object,
for example copying over just the first extension, the PHU will follow. The
slice of an AstroData object is an AstroData object.
Headers can be accessed directly, or for some predefined concepts, the use of
Descriptors is preferred. See the chapters on headers for details.
Using Descriptors:
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> ad.filter_name()
'open1-6&g_G0301'
>>> ad.filter_name(pretty=True)
'g'
Using direct header access:
>>> ad.phu['FILTER1']
'open1-6'
>>> ad.phu['FILTER2']
'g_G0301'
Accessing the extension headers:
>>> ad.hdr['CCDSEC']
['[1:512,1:4224]', '[513:1024,1:4224]', '[1025:1536,1:4224]', '[1537:2048,1:4224]']
>>> ad[0].hdr['CCDSEC']
'[1:512,1:4224]'
With descriptors:
>>> ad.array_section(pretty=True)
['[1:512,1:4224]', '[513:1024,1:4224]', '[1025:1536,1:4224]', '[1537:2048,1:4224]']
Modify Existing MEF Files¶
Before you start modify the structure of an AstroData object, you should be
familiar with it. Please make sure that you have read the previous chapter
on the structure of the AstroData object.
Appending an extension¶
In this section, we take an extension from one AstroData object and append it
to another. Because we are mapping a FITS file, the EXTVER keyword gets
automatically updated to the next available value to ensure that when the
AstroData object is written back to disk as MEF, it will be coherent.
Here is an example appending a whole AstroData extension, with pixel data, variance, mask and tables.
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> advar = astrodata.open('../playdata/N20170609S0154_varAdded.fits')
>>> ad.info()
Filename: ../playdata/N20170609S0154.fits
Tags: ACQUISITION GEMINI GMOS IMAGE NORTH RAW SIDEREAL UNPREPARED
Pixels Extensions
Index Content Type Dimensions Format
[ 0] science NDAstroData (2112, 288) uint16
[ 1] science NDAstroData (2112, 288) uint16
[ 2] science NDAstroData (2112, 288) uint16
[ 3] science NDAstroData (2112, 288) uint16
>>> ad.append(advar[3])
>>> ad.info()
Filename: ../playdata/N20170609S0154.fits
Tags: ACQUISITION GEMINI GMOS IMAGE NORTH RAW SIDEREAL UNPREPARED
Pixels Extensions
Index Content Type Dimensions Format
[ 0] science NDAstroData (2112, 288) uint16
[ 1] science NDAstroData (2112, 288) uint16
[ 2] science NDAstroData (2112, 288) uint16
[ 3] science NDAstroData (2112, 288) uint16
[ 4] science NDAstroData (2112, 256) float32
.variance ndarray (2112, 256) float32
.mask ndarray (2112, 256) int16
.OBJCAT Table (5, 43) n/a
.OBJMASK ndarray (2112, 256) uint8
>>> ad[4].hdr['EXTVER']
5
>>> advar[3].hdr['EXTVER']
4
As you can see above, the fourth extension of advar, along with everything
it contains was appended at the end of the first AstroData object. Also, note
that the EXTVER of the extension in advar was 4, but once appended
to ad, it had to be changed to the next available integer, 5, numbers 1 to
4 being already used by ad’s own extensions.
In this next example, we are appending only the pixel data, leaving behind the other associated data. One can attach the headers too, like we do here.
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> advar = astrodata.open('../playdata/N20170609S0154_varAdded.fits')
>>> ad.append(advar[3].data, header=advar[3].hdr)
>>> ad.info()
Filename: ../playdata/N20170609S0154.fits
Tags: ACQUISITION GEMINI GMOS IMAGE NORTH RAW SIDEREAL UNPREPARED
Pixels Extensions
Index Content Type Dimensions Format
[ 0] science NDAstroData (2112, 288) uint16
[ 1] science NDAstroData (2112, 288) uint16
[ 2] science NDAstroData (2112, 288) uint16
[ 3] science NDAstroData (2112, 288) uint16
[ 4] science NDAstroData (2112, 256) float32
Notice how a new extension was created but variance, mask, the OBJCAT
table and OBJMASK image were not copied over. Only the science pixel data was
copied over.
Please note, there is no implementation for the “insertion” of an extension.
Removing an extension or part of one¶
Removing an extension or a part of an extension is straightforward. The
Python command del() is used on the item to remove. Below are a few
examples, but first let us load a file
>>> ad = astrodata.open('../playdata/N20170609S0154_varAdded.fits')
>>> ad.info()
As you go through these examples, check the new structure with ad.info()
after every removal to see how the structure has changed.
Deleting a whole AstroData extension, the fourth one
>>> del ad[3]
Deleting only the variance array from the second extension
>>> ad[1].variance = None
Deleting a table associated with the first extension
>>> del ad[0].OBJCAT
Deleting a global table, not attached to a specific extension
>>> del ad.REFCAT
Writing back to disk¶
The AstroDataFits layer takes care of converting
the AstroData object back to a MEF file on disk. When writing to disk,
one should be aware of the path and filename information associated
with the AstroData object.
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> ad.path
'../playdata/N20170609S0154.fits'
>>> ad.filename
'N20170609S0154.fits'
Writing to a new file¶
There are various ways to define the destination for the new FITS file. The most common and natural way is
>>> ad.write('new154.fits')
>>> ad.write('new154.fits', overwrite=True)
This will write a FITS file named ‘new154.fits’ in the current directory.
With overwrite=True, it will overwrite the file if it already exists.
A path can be prepended to the filename if the current directory is not
the destination.
Note that ad.filename and ad.path have not changed, we have just
written to the new file, the AstroData object is in no way associated
with that new file.
>>> ad.path
'../playdata/N20170609S0154.fits'
>>> ad.filename
'N20170609S0154.fits'
If you want to create that association, the ad.filename and ad.path
needs to be modified first. For example:
>>> ad.filename = 'new154.fits'
>>> ad.write(overwrite=True)
>>> ad.path
'../playdata/new154.fits'
>>> ad.filename
'new154.fits'
Changing ad.filename also changes the filename in the ad.path. The
sequence above will write ‘new154.fits’ not in the current directory but
rather to the directory that is specified in ad.path.
WARNING: ad.write() has an argument named filename. Setting filename
in the call to ad.write(), as in ad.write(filename='new154.fits') will NOT
modify ad.filename or ad.path. The two “filenames”, one a method argument
the other a class attribute have no association to each other.
Updating an existing file on disk¶
Updating an existing file on disk requires explicitly allowing overwrite.
If you have not written ‘new154.fits’ to disk yet (from previous section)
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> ad.write('new154.fits', overwrite=True)
Now let’s open ‘new154.fits’, and write to it
>>> adnew = astrodata.open('new154.fits')
>>> adnew.write(overwrite=True)
Create New MEF Files¶
A new MEF file can be created from an existing, maybe modified, file or it can be created from scratch. We discuss both cases here.
Create New Copy of MEF Files¶
To create a new copy of a MEF file, modified or not, the user has already been given most of the tools in the sections above. Yet, let’s throw a couple examples for completeness.
Basic example¶
As seen above, a MEF file can be opened with astrodata, the AstroData
object can be modified (or not), and then written back to disk under a
new name.
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
... optional modifications here ...
>>> ad.write('newcopy.fits')
Needing true copies in memory¶
Sometimes it is a true copy in memory that is needed. This is not specific
to MEF. In Python, doing something like adnew = ad does not create a
new copy of the AstrodData object; it just gives it a new name. If you
modify adnew you will be modifying ad too. They point to the same
block of memory.
To create a true independent copy, the deepcopy utility needs to be used.
>>> from copy import deepcopy
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> adcopy = deepcopy(ad)
Be careful using deepcopy, your memory could balloon really fast. Use it
only when truly needed.
Create New MEF Files from Scratch¶
Before one creates a new MEF file on disk, one has to create the AstroData
object that will be eventually written to disk. The AstroData object
created also needs to know that it will have to be written using the MEF
format. This is fortunately handled fairly transparently by astrodata.
The key to associating the FITS data provider to the AstroData object
is simply to create the AstroData object from astropy.io.fits header
objects. Those will be recognized by astrodata as FITS and the
constructor for FITS will be used. The user does not need to do anything
else special. Here is how it is done.
Create a MEF with basic header and data array set to zeros¶
>>> import numpy as np
>>> from astropy.io import fits
>>> phu = fits.PrimaryHDU()
>>> pixel_data = np.zeros((100,100))
>>> hdu = fits.ImageHDU()
>>> hdu.data = pixel_data
>>> ad = astrodata.create(phu)
>>> ad.append(hdu, name='SCI')
or another way to do the last two blocs:
>>> hdu = fits.ImageHDU(data=pixel_data, name='SCI')
>>> ad = astrodata.create(phu, [hdu])
Then it is just a matter of calling ad.write('somename.fits') on that
new Astrodata object.
Represent a table as a FITS binary table in an AstroData object¶
One first needs to create a table, either an astropy.table.Table
or a BinTableHDU. See the astropy documentation
on tables and this manual’s section dedicated to tables for
more information.
In the first example, we assume that my_astropy_table is
a Table ready to be attached to an AstroData
object. (Warning: we have not created my_astropy_table therefore the
example below will not run, though this is how it would be done.)
>>> phu = fits.PrimaryHDU()
>>> ad = astrodata.create(phu)
>>> astrodata.add_header_to_table(my_astropy_table)
>>> ad.append(my_astropy_table, name='SMAUG')
In the second example, we start with a FITS BinTableHDU
and attach it to a new AstroData object. (Again, we have not created
my_fits_table so the example will not run.)
>>> phu = fits.PrimaryHDU()
>>> ad = astrodata.create(phu)
>>> ad.append(my_fits_table, name='DROGON')
As before, once the AstroData object is constructed, the ad.write()
method can be used to write it to disk as a MEF file.
Astrodata Tags¶
What are the Astrodata Tags?¶
The Astrodata Tags identify the data represented in the AstroData object.
When a file on disk is opened with astrodata, the headers are inspected to
identify which specific AstroData class needs to be loaded,
AstroDataGmos,
AstroDataNiri, etc. Based on the class the data is
associated with, a list of “tags” will be defined. The tags will tell whether the
file is a flatfield or a dark, if it is a raw dataset, or if it has been processed by the
recipe system, if it is imaging or spectroscopy. The tags will tell the
users and the system what that data is and also give some information about
the processing status.
As a side note, the tags are used by DRAGONS Recipe System to match recipes and primitives to the data.
Using the Astrodata Tags¶
Try it yourself
Download the data package (Try it yourself) if you wish to follow along and run the examples. Then
$ cd <path>/ad_usermanual/playground
$ python
Before doing anything, you need to import astrodata and the Gemini instrument
configuration package (gemini_instruments).
>>> import astrodata
>>> import gemini_instruments
Let us open a Gemini dataset and see what tags we get:
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> ad.tags
{'RAW', 'GMOS', 'GEMINI', 'NORTH', 'SIDEREAL', 'UNPREPARED', 'IMAGE', 'ACQUISITION'}
The file we loaded is raw, GMOS North data. It is a 2D image and it is an acquisition image, not a science observation. The “UNPREPARED” tag indicates that the file has never been touched by the Recipe System which runs a “prepare” primitive as the first step of each recipe.
Let’s try another
>>> ad = astrodata.open('../playdata/N20170521S0925_forStack.fits')
>>> ad.tags
{'GMOS', 'GEMINI', 'NORTH', 'SIDEREAL', 'OVERSCAN_TRIMMED', 'IMAGE',
'OVERSCAN_SUBTRACTED', 'PREPARED'}
This file is a science GMOS North image. It has been processed by the Recipe System. The overscan level has been subtracted and the section has been trimmed away. The tags do NOT include all the processing steps. Rather, at least from the time being, it focuses on steps that matter when associating calibrations.
The tags can be used when coding. For example:
>>> if 'GMOS' in ad.tags:
... print('I am GMOS')
... else:
... print('I am these instead:', ad.tags)
...
And:
>>> if {'IMAGE', 'GMOS'}.issubset(ad.tags):
... print('I am a GMOS Image.')
...
Using typewalk¶
In DRAGONS, there is a convenience tool that will list the Astrodata tags for all the FITS file in a directory.
To try it, from the shell, not Python, go to the “playdata” directory and run typewalk:
% cd <path>/ad_usermanual/playdata
% typewalk
directory: /data/workspace/ad_usermanual/playdata
N20170521S0925_forStack.fits ...... (GEMINI) (GMOS) (IMAGE) (NORTH) (OVERSCAN_SUBTRACTED) (OVERSCAN_TRIMMED) (PREPARED) (SIDEREAL)
N20170521S0926_forStack.fits ...... (GEMINI) (GMOS) (IMAGE) (NORTH) (OVERSCAN_SUBTRACTED) (OVERSCAN_TRIMMED) (PREPARED) (PROCESSED) (PROCESSED_SCIENCE) (SIDEREAL)
N20170609S0154.fits ............... (ACQUISITION) (GEMINI) (GMOS) (IMAGE) (NORTH) (RAW) (SIDEREAL) (UNPREPARED)
N20170609S0154_varAdded.fits ...... (ACQUISITION) (GEMINI) (GMOS) (IMAGE) (NORTH) (OVERSCAN_SUBTRACTED) (OVERSCAN_TRIMMED) (PREPARED) (SIDEREAL)
estgsS20080220S0078.fits .......... (GEMINI) (GMOS) (LONGSLIT) (LS) (PREPARED) (PROCESSED) (PROCESSED_SCIENCE) (SIDEREAL) (SOUTH) (SPECT)
gmosifu_cube.fits ................. (GEMINI) (GMOS) (IFU) (NORTH) (ONESLIT_RED) (PREPARED) (PROCESSED) (PROCESSED_SCIENCE) (SIDEREAL) (SPECT)
new154.fits ....................... (ACQUISITION) (GEMINI) (GMOS) (IMAGE) (NORTH) (RAW) (SIDEREAL) (UNPREPARED)
Done DataSpider.typewalk(..)
typewalk can be used to select specific data based on tags, and even create
lists:
% typewalk --tags RAW
directory: /data/workspace/ad_usermanual/playdata
N20170609S0154.fits ............... (ACQUISITION) (GEMINI) (GMOS) (IMAGE) (NORTH) (RAW) (SIDEREAL) (UNPREPARED)
new154.fits ....................... (ACQUISITION) (GEMINI) (GMOS) (IMAGE) (NORTH) (RAW) (SIDEREAL) (UNPREPARED)
Done DataSpider.typewalk(..)
% typewalk --tags RAW -o rawfiles.lis
% cat rawfiles.lis
# Auto-generated by typewalk, vv2.0 (beta)
# Written: Tue Mar 6 13:06:06 2018
# Qualifying types: RAW
# Qualifying logic: AND
# -----------------------
/Users/klabrie/data/tutorials/ad_usermanual/playdata/N20170609S0154.fits
/Users/klabrie/data/tutorials/ad_usermanual/playdata/new154.fits
Creating New Astrodata Tags [Advanced Topic]¶
For proper and complete instructions on how to create Astrodata Tags and
the AstroData class that hosts the tags, the reader is invited to refer to the
Astrodata Programmer Manual. Here we provide a simple introduction that
might help some readers better understand Astrodata Tags, or serve as a
quick reference for those who have written Astrodata Tags in the past but need
a little refresher.
The Astrodata Tags are defined in an AstroData class. The AstroData
class specific to an instrument is located in a separate package, not in
astrodata. For example, for Gemini instruments, all the various AstroData
classes are contained in the gemini_instruments package.
An Astrodata Tag is a function within the instrument’s AstroData class.
The tag function is distinguished from normal functions by applying the
astro_data_tag() decorator to it.
The tag function returns a astrodata.TagSet.
For example:
class AstroDataGmos(AstroDataGemini):
...
@astro_data_tag
def _tag_arc(self):
if self.phu.get('OBSTYPE) == 'ARC':
return TagSet(['ARC', 'CAL'])
The tag function looks at the headers and if the keyword “OBSTYPE” is set
to “ARC”, the tags “ARC” and “CAL” (for calibration) will be assigned to the
AstroData object.
A whole suite of such tag functions is needed to fully characterize all types of data an instrument can produce.
Tags are about what the dataset is, not it’s flavor. The Astrodata “descriptors” (see the section on Metadata and Headers) will describe the flavor. For example, tags will say that the data is an image, but the descriptor will say whether it is B-band or R-band. Tags are used for recipe and primitive selection. A way to understand the difference between a tag and a descriptor is in terms of the recipe that will be selected: A GMOS image will use the same recipe whether it’s a B-band or R-band image. However, a GMOS longslit spectrum will need a very different recipe. A bias is reduced differently from a science image, there should be a tag differentiating a bias from a science image. (There is for GMOS.)
For more information on adding to Astrodata, see the Astrodata Programmer Manual.
Metadata and Headers¶
Try it yourself
Download the data package (Try it yourself) if you wish to follow along and run the examples. Then
$ cd <path>/ad_usermanual/playground
$ python
You need to import Astrodata and the Gemini instrument configuration package.
>>> import astrodata
>>> import gemini_instruments
Astrodata Descriptors¶
We show in this chapter how to use the Astrodata Descriptors. But first let’s explain what they are.
Astrodata Descriptors provide a “header-to-concept” mapping that allows the
user to access header information from a unique interface, regardless of
which instrument the dataset is from. Like for the Astrodata Tags, the
mapping is coded in a configuration package separate from core Astrodata.
For Gemini instruments, that package is named gemini_instruments.
For example, if the user is interested to know the effective filter used
for an observation, normally one needs to know which specific keyword or
set of keywords to look at for that instrument. However, once the concept
of “filter” is coded as a Descriptor, the user only needs to call the
filter_name() descriptor to retrieve the information.
The Descriptors are closely associated with the Astrodata Tags. In fact,
they are implemented in the same AstroData class as the tags. Once
the specific AstroData class is selected (upon opening the file), all
the tags and descriptors for that class are defined. For example, all the
descriptor functions of GMOS data, ie. the functions that map a descriptor
concept to the actual header content, are defined in the AstroDataGmos
class.
This is all completely transparent to the user. One simply opens the data file and all the descriptors are ready to be used.
Note
Of course if the Descriptors have not been implemented for that specific data, they will not work. They should all be defined for Gemini data. For other sources, the headers can be accessed directly, one keyword at a time. This type of access is discussed below. This is also useful when the information needed is not associated with one of the standard descriptors.
To get the list of descriptors available for an AstroData object:
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> ad.descriptors
('airmass', 'amp_read_area', 'ao_seeing', ...
...)
Most Descriptor names are readily understood, but one can get a short description of what the Descriptor refers to by calling the Python help function. For example:
>>> help(ad.airmass)
>>> help(ad.filter_name)
The full list of standard descriptors is available in the Appendix List of Gemini Standard Descriptors.
Accessing Metadata¶
Accessing Metadata with Descriptors¶
Whenever possible the Descriptors should be used to get information from
headers. This allows for maximum re-usability of the code as it will then
work on any datasets with an AstroData class.
Here are a few examples using Descriptors:
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> #--- print a value
>>> print('The airmass is : ', ad.airmass())
>>> #--- use a value to control the flow
>>> if ad.exposure_time() < 240.:
... print('This is a short exposure.')
... else:
... print('This is a long exposure.')
...
>>> #--- multiply all extensions by their respective gain
>>> for ext, gain in zip(ad, ad.gain()):
... ext *= gain
...
>>> #--- do arithmetics
>>> fwhm_pixel = 3.5
>>> fwhm_arcsec = fwhm_pixel * ad.pixel_scale()
The return values for Descriptors depend on the nature of the information
being requested and the number of extensions in the AstroData object.
When the value has words, it will be string, if it is a number
it will be a float or an integer.
The dataset used in this section has 4 extensions. When the descriptor
value can be different for each extension, the descriptor will return a
Python list.
>>> ad.airmass()
1.089
>>> ad.gain()
[2.03, 1.97, 1.96, 2.01]
>>> ad.filter_name()
'open1-6&g_G0301'
Some descriptors accept arguments. For example:
>>> ad.filter_name(pretty=True)
'g'
A full list of standard descriptors is available in the Appendix List of Gemini Standard Descriptors.
Accessing Metadata Directly¶
Not all header content is mapped to Descriptors, nor should it. Direct access is available for header content falling outside the scope of the descriptors.
One important thing to keep in mind is that the PHU (Primary Header Unit) and
the extension headers are accessed slightly differently. The attribute
phu needs to be used for the PHU, and hdr for the extension headers.
Here are some examples of direct header access:
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> #--- Get keyword value from the PHU
>>> ad.phu['AOFOLD']
'park-pos.'
>>> #--- Get keyword value from a specific extension
>>> ad[0].hdr['CRPIX1']
511.862999160781
>>> #--- Get keyword value from all the extensions in one call.
>>> ad.hdr['CRPIX1']
[511.862999160781, 287.862999160781, -0.137000839218696, -224.137000839219]
Whole Headers¶
Entire headers can be retrieved as fits Header objects:
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> type(ad.phu)
<class 'astropy.io.fits.header.Header'>
>>> type(ad[0].hdr)
<class 'astropy.io.fits.header.Header'>
In interactive mode, it is possible to print the headers on the screen as follows:
>>> ad.phu
SIMPLE = T / file does conform to FITS standard
BITPIX = 16 / number of bits per data pixel
NAXIS = 0 / number of data axes
....
>>> ad[0].hdr
XTENSION= 'IMAGE ' / IMAGE extension
BITPIX = 16 / number of bits per data pixel
NAXIS = 2 / number of data axes
....
Updating, Adding and Deleting Metadata¶
Header cards can be updated, added to, or deleted from the headers. The PHU
and the extensions headers are again accessed in a mostly identical way
with phu and hdr, respectively.
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
Add and update a keyword, without and with comment:
>>> ad.phu['NEWKEY'] = 50.
>>> ad.phu['NEWKEY'] = (30., 'Updated PHU keyword')
>>> ad[0].hdr['NEWKEY'] = 50.
>>> ad[0].hdr['NEWKEY'] = (30., 'Updated extension keyword')
Delete a keyword:
>>> del ad.phu['NEWKEY']
>>> del ad[0].hdr['NEWKEY']
World Co-ordinate System attribute¶
The wcs of an extension’s nddata attribute (eg. ad[0].nddata.wcs;
see Pixel Data) may contain an instance of astropy.wcs.WCS (a standard
FITS WCS object) or gwcs.wcs.WCS (a “Generalized WCS” or gWCS object). These both define a transformation
between array indices and some other co-ordinate system such as “World”
co-ordinates (see APE 14). GWCS allows
multiple, almost arbitrary co-ordinate mappings from different calibration
steps (eg. CCD mosaicking, distortion correction & wavelength calibration) to
be combined in a single, reversible transformation chain — but this
information cannot all be represented as a FITS standard WCS. If a gWCS object
is defined here, it gets stored as a table extension named ‘WCS’ when the
AstroData instance is saved to a file (with the same EXTVER as the
corresponding ‘SCI’ array). This is independent of any WCS information already
stored in the FITS headers. The representation in the table is produced using
ASDF, with one line of text per row. Likewise,
when the file is re-opened, the gWCS object gets recreated in wcs from the
table.
In future, it is intended that the wcs attribute will get populated from
standard FITS headers where there is no overriding ‘WCS’ table extension and
will get saved to standard FITS headers when its type is astropy.wcs.WCS.
Also, where a gWCS object is used, a discrete sampling of the World co-ordinate
values will be stored as part of the FITS WCS, following Greisen et al. (2006), S6 (in addition to the
definitive ‘WCS’ table), allowing standard FITS readers to report accurate
World co-ordinates for each pixel.
Adding Descriptors [Advanced Topic]¶
For proper and complete instructions on how to create Astrodata Descriptors, the reader is invited to refer to the Astrodata Programmer Manual. Here we provide a simple introduction that might help some readers better understand Astrodata Descriptors, or serve as a quick reference for those who have written Astrodata Descriptors in the past but need a little refresher.
The Astrodata Descriptors are defined in an AstroData class. The
AstroData class specific to an instrument is located in a separate
package, not in astrodata. For example, for Gemini instruments, all the
various AstroData classes are contained in the gemini_instruments
package.
An Astrodata Descriptor is a function within the instrument’s AstroData
class. The descriptor function is distinguished from normal functions by
applying the @astro_data_descriptor decorator to it. The descriptor
function returns the value(s) using a Python type, int, float,
string, list; it depends on the value being returned. There is no
special “descriptor” type.
Here is an example of code defining a descriptor:
class AstroDataGmos(AstroDataGemini):
...
@astro_data_descriptor
def detector_x_bin(self):
def _get_xbin(b):
try:
return int(b.split()[0])
except (AttributeError, ValueError):
return None
binning = self.hdr.get('CCDSUM')
if self.is_single:
return _get_xbin(binning)
else:
xbin_list = [_get_xbin(b) for b in binning]
# Check list is single-valued
return xbin_list[0] if xbin_list == xbin_list[::-1] else None
This descriptor returns the X-axis binning as a integer when called on a single extension, or an object with only one extension, for example after the GMOS CCDs have been mosaiced. If there are more than one extensions, it will return a Python list or an integer if the binning is the same for all the extensions.
Gemini has defined a standard list of descriptors that should be defined one way or another for each instrument to ensure the re-usability of our algorithms. That list is provided in the Appendix List of Gemini Standard Descriptors.
For more information on adding to Astrodata, see the Astrodata Programmer Manual.
Pixel Data¶
Try it yourself
Download the data package (Try it yourself) if you wish to follow along and run the examples. Then
$ cd <path>/ad_usermanual/playground
$ python
Then import core astrodata and the Gemini astrodata configurations.
>>> import astrodata
>>> import gemini_instruments
Operate on Pixel Data¶
The pixel data are stored in the AstroData object as a list of
NDAstroData objects. The NDAstroData is a subclass of Astropy’s
NDData class which combines in one “package” the pixel values, the
variance, and the data quality plane or mask (as well as associated meta-data).
The data can be retrieved as a standard NumPy ndarray.
In the sections below, we will present several typical examples of data manipulation. But first let’s start with a quick example on how to access the pixel data.
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> the_data = ad[1].data
>>> type(the_data)
<class 'numpy.ndarray'>
>>> # Loop through the extensions
>>> for ext in ad:
... the_data = ext.data
... print(the_data.sum())
...
In this example, we first access the pixels for the second extensions.
Remember that in Python, list are zero-indexed, hence we access the second
extension as ad[1]. The .data attribute contains a NumPy ndarray.
In the for-loop, for each extension, we get the data and use the NumPy
.sum() method to sum the pixel values. Anything that can be done
with a ndarray can be done on AstroData pixel data.
Arithmetic on AstroData Objects¶
AstroData objects support basic in-place arithmetics with these methods:
| addition | .add() |
| subtraction | .subtract() |
| multiplication | .multiply() |
| division | .divide() |
Normal, not in-place, arithmetics is also possible using the standard
operators, +, -, *, and /.
The big advantage of using AstroData to do arithmetics is that the
variance and mask, if present, will be propagated through to the output
AstroData object. We will explore the variance propagation in the next
section and mask usage later in this chapter.
Simple operations¶
Here are a few examples of arithmetics on AstroData objects.:
>>> ad = astrodata.open('../playdata/N20170521S0925_forStack.fits')
>>> # Addition
>>> ad.add(50.)
>>> ad = ad + 50.
>>> ad += 50.
>>> # Subtraction
>>> ad.subtract(50.)
>>> ad = ad - 50.
>>> ad -= 50.
>>> # Multiplication (Using a descriptor)
>>> ad.multiply(ad.exposure_time())
>>> ad = ad * ad.exposure_time()
>>> ad *= ad.exposure_time()
>>> # Division (Using a descriptor)
>>> ad.divide(ad.exposure_time())
>>> ad = ad / ad.exposure_time()
>>> ad /= ad.exposure_time()
When the syntax adout = adin + 1 is used, the output variable is a copy
of the original. In the examples above we reassign the result back onto the
original. The two other forms, ad.add() and ad += are in-place
operations.
When a descriptor returns a list because the value changes for each extension, a for-loop is needed:
>>> for (ext, gain) in zip(ad, ad.gain()):
... ext.multiply(gain)
...
If you want to do the above but on a new object, leaving the original unchanged,
use deepcopy first.
>>> from copy import deepcopy
>>> adcopy = deepcopy(ad)
>>> for (ext, gain) in zip(adcopy, adcopy.gain()):
... ext.multiply(gain)
...
Operator Precedence¶
The AstroData arithmetics methods can be stringed together but beware that
there is no operator precedence when that is done. For arithmetics that
involve more than one operation, it is probably safer to use the normal
Python operator syntax. Here is a little example to illustrate the difference.
>>> ad.add(5).multiply(10).subtract(5)
>>> # means: ad = ((ad + 5) * 10) - 5
>>> # NOT: ad = ad + (5 * 10) - 5
This is because the methods modify the object in-place, one operation after the other from left to right. This also means that the original is modified.
This example applies the expected operator precedence:
>>> ad = ad + ad * 3 - 40.
>>> # means: ad = ad + (ad * 3) - 40.
If you need a copy, leaving the original untouched, which is sometimes useful
you can use deepcopy or just use the normal operator and assign to a new
variable.:
>>> adnew = ad + ad * 3 - 40.
Variance¶
When doing arithmetic on an AstroData object, if a variance is present
it will be propagated appropriately to the output no matter which syntax
you use (the methods or the Python operators).
Adding a Variance Plane¶
In this example, we will add the poisson noise to an AstroData dataset.
The data is still in ADU, therefore the poisson noise as variance is
signal / gain. We want to set the variance for each of the pixel
extensions.
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> for (extension, gain) in zip(ad, ad.gain()):
... extension.variance = extension.data / gain
...
Check ad.info(), you will see a variance plane for each of the four
extensions.
Automatic Variance Propagation¶
As mentioned before, if present, the variance plane will be propagated to the
resulting AstroData object when doing arithmetics. The variance
calculation assumes that the data are not correlated.
Let’s look into an example.
# output = x * x
# var_output = var * x^2 + var * x^2
>>> ad = astrodata.open('../playdata/N20170609S0154_varAdded.fits')
>>> ad[1].data[50,50]
56.160931
>>> ad[1].variance[50,50]
96.356529
>>> adout = ad * ad
>>> adout[1].data[50,50]
3154.05
>>> adout[1].variance[50,50]
607826.62
Data Quality Plane¶
The NDData mask stores the data quality plane. The simplest form is a
True/False array of the same size at the pixel array. In Astrodata we favor
a bit array that allows for additional information about why the pixel is being
masked. For example at Gemini here is our bit mapping for bad pixels.
| Meaning | Value |
|---|---|
| Bad pixel | 1 |
| Non Linear | 2 |
| Saturated | 4 |
| Cosmic Ray | 8 |
| No Data | 16 |
| Overlap | 32 |
| Unilluminated | 64 |
(These definitions are located in geminidr.gemini.lookups.DQ_definitions.)
So a pixel marked 10 in the mask, would be a “non-linear” “cosmic ray”. The
AstroData masks are propagated with bitwise-OR operation. For example,
let’s say that we are stacking frames. A pixel is set as bad (value 1)
in one frame, saturated in another (value 4), and fine in all the other
the frames (value 0). The mask of the resulting stack will be assigned
a value of 5 for that pixel.
These bitmasks will work like any other NumPy True/False mask. There is a usage example below using the mask.
The mask can be accessed as follow:
>>> ad = astrodata.open('../playdata/N20170609S0154_varAdded.fits')
>>> ad.info()
>>> ad[2].mask
Display¶
Since the data is stored in the AstroData object as a NumPy ndarray
any tool that works on ndarray can be used. To display to DS9 there
is the imexam package. The numdisplay package is still available for
now but it is no longer supported by STScI. We will show
how to use imexam to display and read the cursor position. Read the
documentation on that tool to learn more about what else it has
to offer.
Displaying with imexam¶
Here is an example how to display pixel data to DS9 with imexam.
>>> import imexam
>>> ad = astrodata.open('../playdata/N20170521S0925_forStack.fits')
# Connect to the DS9 window (should already be opened.)
>>> ds9 = imexam.connect(list(imexam.list_active_ds9())[0])
>>> ds9.view(ad[0].data)
# To scale "a la IRAF"
>>> ds9.view(ad[0].data)
>>> ds9.scale('zscale')
# To set the mininum and maximum scale values
>>> ds9.view(ad[0].data)
>>> ds9.scale('limits 0 2000')
Retrieving cursor position with imexam¶
The function readcursor() can be used to retrieve cursor
position in pixel coordinates. Note that it will not respond to
mouse clicks, only keyboard entries are acknowledged.
When invoked, readcursor() will stop the flow of the program and wait
for the user to put the cursor on top of the image and type a key. A
tuple with three values will be returned: the x and
y coordinates in 0-based system, and the value of the key the user
hit.
>>> import imexam
>>> ad = astrodata.open('../playdata/N20170521S0925_forStack.fits')
# Connect to the DS9 window (should already be opened.)
# and display
>>> ds9 = imexam.connect(list(imexam.list_active_ds9())[0])
>>> ds9.view(ad[0].data)
>>> ds9.scale('zscale')
>>> cursor_coo = ds9.readcursor()
>>> print(cursor_coo)
# To extract only the x,y coordinates
>>> (xcoo, ycoo) = cursor_coo[:2]
>>> print(xcoo, ycoo)
# If you are also interested in the keystroke
>>> keystroke = cursor_coo[2]
>>> print('You pressed this key: %s' % keystroke)
Useful tools from the NumPy, SciPy, and Astropy Packages¶
Like for the Display section, this section is not really specific to Astrodata but is rather a quick show-and-tell of a few things that can be done on the pixels with the big scientific packages NumPy, SciPy, and Astropy.
Those three packages are very large and rich. They have their own extensive documentation and it is highly recommend for the users to learn about what they have to offer. It might save you from re-inventing the wheel.
The pixels, the variance, and the mask are stored as NumPy ndarray’s.
Let us go through some basic examples, just to get a feel for how the
data in an AstroData object can be manipulated.
ndarray¶
The data are contained in NumPy ndarray objects. Any tools that works
on an ndarray can be used with Astrodata.
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> data = ad[0].data
>>> # Shape of the array. (equivalent to NAXIS2, NAXIS1)
>>> data.shape
(2112, 288)
>>> # Value of a pixel at "IRAF" or DS9 coordinates (100, 50)
>>> data[49,99]
455
>>> # Data type
>>> data.dtype
dtype('uint16')
The two most important thing to remember for users coming from the IRAF world or the Fortran world are that the array has the y-axis in the first index, the x-axis in the second, and that the array indices are zero-indexed, not one-indexed. The examples above illustrate those two critical differences.
It is sometimes useful to know the data type of the values stored in the
array. Here, the file is a raw dataset, fresh off the telescope. No
operations has been done on the pixels yet. The data type of Gemini raw
datasets is always “Unsigned integer (0 to 65535)”, uint16.
Warning
Beware that doing arithmetic on uint16 can lead to unexpected
results. This is a NumPy behavior. If the result of an operation
is higher than the range allowed by uint16, the output value will
be “wrong”. The data type will not be modified to accommodate the large
value. A workaround, and a safety net, is to multiply the array by
1.0 to force the conversion to a float64.
>>> a = np.array([65535], dtype='uint16')
>>> a + a
array([65534], dtype=uint16)
>>> 1.0*a + a
array([ 131070.])
Simple Numpy Statistics¶
A lot of functions and methods are available in NumPy to probe the array, too many to cover here, but here are a couple examples.
>>> import numpy as np
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> data = ad[0].data
>>> data.mean()
>>> np.average(data)
>>> np.median(data)
Note how mean() is called differently from the other two. mean()
is a ndarray method, the others are NumPy functions. The implementation
details are clearly well beyond the scope of this manual, but when looking
for the tool you need, keep in mind that there are two sets of functions to
look into. Duplications like .mean() and np.average() can happen,
but they are not the norm. The readers are strongly encouraged to refer to
the NumPy documentation to find the tool they need.
Clipped Statistics¶
It is common in astronomy to apply clipping to the statistics, a clipped
average, for example. The NumPy ma module can be used to create masks
of the values to reject. In the examples below, we calculated the clipped
average of the first pixel extension with a rejection threshold set to
+/- 3 times the standard deviation.
Before Astropy, it was possible to do something like that with only NumPy tools, like in this example:
>>> import numpy as np
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> data = ad[0].data
>>> stddev = data.std()
>>> mean = data.mean()
>>> clipped_mean = np.ma.masked_outside(data, mean-3*stddev, mean+3*stddev).mean()
There is no iteration in that example. It is a straight one-time clipping.
For something more robust, there is an Astropy function that can help, in particular by adding an iterative process to the calculation. Here is how it is done:
>>> import numpy as np
>>> from astropy.stats import sigma_clip
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> data = ad[0].data
>>> clipped_mean = np.ma.mean(sigma_clip(data, sigma=3))
Filters with SciPy¶
Another common operation is the filtering of an image, for example convolving
with a gaussian filter. The SciPy module ndimage.filters offers
several functions for image processing. See the SciPy documentation for
more information.
The example below applies a gaussian filter to the pixel array.
>>> from scipy.ndimage import filters
>>> import imexam
>>> ad = astrodata.open('../playdata/N20170521S0925_forStack.fits')
>>> data = ad[0].data
>>> # We need to prepare an array of the same size and shape as
>>> # the data array. The result will be put in there.
>>> convolved_data = np.zeros(data.size).reshape(data.shape)
>>> # We now apply the convolution filter.
>>> sigma = 10.
>>> filters.gaussian_filter(data, sigma, output=convolved_data)
>>> # Let's visually compare the convolved image with the original
>>> ds9 = imexam.connect(list(imexam.list_active_ds9())[0])
>>> ds9.view(data)
>>> ds9.scale('zscale')
>>> ds9.frame(2)
>>> ds9.view(convolved_data)
>>> ds9.scale('zscale')
>>> ds9.blink()
>>> # When you are convinced it's been convolved, stop the blinking.
>>> ds9.blink(blink=False)
Note that there is an Astropy way to do this convolution, with tools in
astropy.convolution package. Beware that for this particular kernel
we have found that the Astropy convolve function is extremely slow
compared to the SciPy solution.
This is because the SciPy function is optimized for a Gaussian convolution
while the generic convolve function in Astropy can take in any kernel.
Being able to take in any kernel is a very powerful feature, but the cost
is time. The lesson here is do your research, and find the best tool for
your needs.
Many other tools¶
There many, many other tools available out there. Here are the links to the three big projects we have featured in this section.
- NumPy: www.numpy.org
- SciPy: www.scipy.org
- Astropy: www.astropy.org
Using the Astrodata Data Quality Plane¶
Let us look at an example where the use of the Astrodata mask is necessary to get correct statistics. A GMOS imaging frame has large sections of unilluminated pixels; the edges are not illuminated and there are two bands between the three CCDs that represent the physical gap between the CCDs. Let us have a look at the pixels to have a better sense of the data:
>>> ad = astrodata.open('../playdata/N20170521S0925_forStack.fits')
>>> import imexam
>>> ds9 = imexam.connect(list(imexam.list_active_ds9())[0])
>>> ds9.view(ad[0].data)
>>> ds9.scale('zscale')
See how the right and left portions of the frame are not exposed to the sky, and the 45 degree angle cuts of the four corners. The chip gaps too. If we wanted to do statistics on the whole frames, we certainly would not want to include those unilluminated areas. We would want to mask them out.
Let us have a look at the mask associated with that image:
>>> ds9.view(ad[0].mask)
>>> ds9.scale('zscale')
The bad sections are all white (pixel value > 0). There are even some illuminated pixels that have been marked as bad for a reason or another.
Let us use that mask to reject the pixels with no or bad information and do calculations only on the good pixels. For the sake of simplicity we will just do an average. This is just illustrative. We show various ways to accomplish the task; choose the one that best suits your need or that you find most readable.
>>> import numpy as np
>>> # For clarity...
>>> data = ad[0].data
>>> mask = ad[0].mask
>>> # Reject all flagged pixels and calculate the mean
>>> np.mean(data[mask == 0])
>>> np.ma.masked_array(data, mask).mean()
>>> # Reject only the pixels flagged "no_data" (bit 16)
>>> np.mean(data[(mask & 16) == 0])
>>> np.ma.masked_array(data, mask & 16).mean()
>>> np.ma.masked_where(mask & 16, data).mean()
The “long” form with np.ma.masked_* is useful if you are planning to do
more than one operation on the masked array. For example:
>>> clean_data = np.ma.masked_array(data, mask)
>>> clean_data.mean()
>>> np.ma.median(clean_data)
>>> clean_data.max()
Manipulate Data Sections¶
So far we have shown examples using the entire data array. It is possible to work on sections of that array. If you are already familiar with Python, you probably already know how to do most if not all of what is in this section. For readers new to Python, and especially those coming from IRAF, there are a few things that are worth explaining.
When indexing a NumPy ndarray, the left most number refers to the
highest dimension’s axis. For example, in a 2D array, the IRAF section
are in (x-axis, y-axis) format, while in Python they are in
(y-axis, x-axis) format. Also important to remember is that the ndarray
is 0-indexed, rather than 1-indexed like in Fortran or IRAF.
Putting it all together, a pixel position (x,y) = (50,75) in IRAF or from
the cursor on a DS9 frame, is accessed in Python as data[74,49].
Similarly, the IRAF section [10:20, 30:40] translate in Python to
[9:20, 29:40]. Also remember that when slicing in Python, the upper limit
of the slice is not included in the slice. This is why here we request
20 and 40 rather 19 and 39.
Let’s put it in action.
Basic Statistics on Section¶
In this example, we do simple statistics on a section of the image.
>>> import numpy as np
>>> ad = astrodata.open('../playdata/N20170521S0925_forStack.fits')
>>> data = ad[0].data
>>> # Get statistics for a 25x25 pixel-wide box centered on pixel
>>> # (50,75) (DS9 frame coordinate)
>>> xc = 49
>>> yc = 74
>>> buffer = 25
>>> (xlow, xhigh) = (xc - buffer//2, xc + buffer//2 + 1)
>>> (ylow, yhigh) = (yc - buffer//2, yc + buffer//2 + 1)
>>> # The section is [62:87, 37:62]
>>> stamp = data[ylow:yhigh, xlow:xhigh]
>>> mean = stamp.mean()
>>> median = np.median(stamp)
>>> stddev = stamp.std()
>>> minimum = stamp.min()
>>> maximum = stamp.max()
>>> print(' Mean Median Stddev Min Max\n \
... %.2f %.2f %.2f %.2f %.2f' % \
... (mean, median, stddev, minimum, maximum))
Have you noticed that the median is calculated with a function rather
than a method? This is simply because the ndarray object does not
have a method to calculate the median.
Example - Overscan Subtraction with Trimming¶
Several concepts from previous sections and chapters are used in this
example. The Descriptors are used to retrieve the overscan section and
the data section information from the headers. Statistics are done on the
NumPy ndarray representing the pixel data. Astrodata arithmetics is
used to subtract the overscan level. Finally, the overscan section is
trimmed off and the modified AstroData object is written to a new file
on disk.
To make the example more complete, and to show that when the pixel data array is trimmed, the variance (and mask) arrays are also trimmed, let us add a variance plane to our raw data frame.
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> for (extension, gain) in zip(ad, ad.gain()):
... extension.variance = extension.data / gain
...
>>> # Here is how the data structure looks like before the trimming.
>>> ad.info()
Filename: ../playdata/N20170609S0154.fits
Tags: ACQUISITION GEMINI GMOS IMAGE NORTH RAW SIDEREAL UNPREPARED
Pixels Extensions
Index Content Type Dimensions Format
[ 0] science NDAstroData (2112, 288) uint16
.variance ndarray (2112, 288) float64
[ 1] science NDAstroData (2112, 288) uint16
.variance ndarray (2112, 288) float64
[ 2] science NDAstroData (2112, 288) uint16
.variance ndarray (2112, 288) float64
[ 3] science NDAstroData (2112, 288) uint16
.variance ndarray (2112, 288) float64
>>> # Let's operate on the first extension.
>>> #
>>> # The section descriptors return the section in a Python format
>>> # ready to use, 0-indexed.
>>> oversec = ad[0].overscan_section()
>>> datasec = ad[0].data_section()
>>> # Measure the overscan level
>>> mean_overscan = ad[0].data[oversec.y1: oversec.y2, oversec.x1: oversec.x2].mean()
>>> # Subtract the overscan level. The variance will be propagated.
>>> ad[0].subtract(mean_overscan)
>>> # Trim the data to remove the overscan section and keep only
>>> # the data section.
>>> #
>>> # Here we work on the NDAstroData object to have the variance
>>> # trimmed automatically to the same size as the science array.
>>> # To reassign the cropped NDAstroData, we use the reset() method.
>>> ad[0].reset(ad[0].nddata[datasec.y1:datasec.y2, datasec.x1:datasec.x2])
>>> # Now look at the dimensions of the first extension, science
>>> # and variance. That extension is smaller than the others.
>>> ad.info()
Filename: ../playdata/N20170609S0154.fits
Tags: ACQUISITION GEMINI GMOS IMAGE NORTH RAW SIDEREAL UNPREPARED
Pixels Extensions
Index Content Type Dimensions Format
[ 0] science NDAstroData (2112, 256) float64
.variance ndarray (2112, 256) float64
[ 1] science NDAstroData (2112, 288) uint16
.variance ndarray (2112, 288) float64
[ 2] science NDAstroData (2112, 288) uint16
.variance ndarray (2112, 288) float64
[ 3] science NDAstroData (2112, 288) uint16
.variance ndarray (2112, 288) float64
>>> # We can write this to a new file
>>> ad.write('partly_overscan_corrected.fits')
A new feature presented in this example is the ability to work on the
NDAstroData object directly. This is particularly useful when cropping
the science pixel array as one will want the variance and the mask arrays
cropped exactly the same way. Taking a section of the NDAstroData
object (ad[0].nddata[y1:y2, x1:x2]), instead of just the .data array,
does all that for us.
To reassign the cropped NDAstroData to the extension one uses the
.reset() method as shown in the example.
Of course to do the overscan correction correctly and completely, one would loop over all four extensions. But that’s the only difference.
Data Cubes¶
Reduced Integral Field Unit (IFU) data is commonly represented as a cube,
a three-dimensional array. The data component of an AstroData
object extension can be such a cube, and it can be manipulated and explored
with NumPy, AstroPy, SciPy, imexam, like we did already in this section
with 2D arrays. We can use matplotlib to plot the 1D spectra represented
in the third dimension.
In Gemini IFU cubes, the first axis is the X-axis, the second, the Y-axis,
and the wavelength is in the third axis. Remember that in a ndarray
that order is reversed (wlen, y, x).
In the example below we “collapse” the cube along the wavelenth axis to create a “white light” image and display it. Then we plot a 1D spectrum from a given (x,y) position.
>>> import imexam
>>> import matplotlib.pyplot as plt
>>> ds9 = imexam.connect(list(imexam.list_active_ds9())[0])
>>> adcube = astrodata.open('../playdata/gmosifu_cube.fits')
>>> adcube.info()
>>> # Sum along the wavelength axis to create a "white light" image
>>> summed_image = adcube[0].data.sum(axis=0)
>>> ds9.view(summed_image)
>>> ds9.scale('minmax')
>>> # Plot a 1-D spectrum from the spatial position (14,25).
>>> plt.plot(adcube[0].data[:,24,13])
>>> plt.show() # might be needed, depends on matplotlibrc interactive setting
Now that is nice but it would be nicer if we could plot the x-axis in units
of Angstroms instead of pixels. We use the AstroData’s WCS handler, which is
based on gwcs.wcs.WCS to get the necessary information. A particularity
of gwcs.wcs.WCS is that it refers to the axes in the “natural” way,
(x, y, wlen) contrary to Python’s (wlen, y, x). It truly requires you to pay
attention.
>>> import matplotlib.pyplot as plt
>>> adcube = astrodata.open('../playdata/gmosifu_cube.fits')
# We get the wavelength axis in Angstroms at the position we want to
# extract, x=13, y=24.
# The wcs call returns a 3-element list, the third element ([2]) contains
# the wavelength values for each pixel along the wavelength axis.
>>> length_wlen_axis = adcube[0].shape[0] # (wlen, y, x)
>>> wavelengths = adcube[0].wcs(13, 24, range(length_wlen_axis))[2] # (x, y, wlen)
# We get the intensity along that axis
>>> intensity = adcube[0].data[:, 24, 13] # (wlen, y, x)
# We plot
plt.clf()
plt.plot(wavelengths, intensity)
plt.show()
Plot Data¶
The main plotting package in Python is matplotlib. We have used it in the
previous section on data cubes to plot a spectrum. There is also relatively
new project called imexam which provides astronomy-specific tools for the
exploration and measurement of data. We have also used that package above to
display images to DS9.
In this section we absolutely do not aim at covering all the features of either package but rather to give a few examples that can get the readers started in their exploration of the data and of the visualization packages.
Refer to the projects web pages for full documentation.
- Matplotlib: https://matplotlib.org
- imexam: https://github.com/spacetelescope/imexam
Matplotlib¶
With Matplotlib you have full control on your plot. You do have to do a bit for work to get it perfect though. However it can produce publication quality plots. Here we just scratch the surface of Matplotlib.
>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from astropy import wcs
>>> ad_image = astrodata.open('../playdata/N20170521S0925_forStack.fits')
>>> ad_spectrum = astrodata.open('../playdata/estgsS20080220S0078.fits')
>>> # Line plot from image. Row #1044 (y-coordinate)
>>> line_index = 1043
>>> line = ad_image[0].data[line_index, :]
>>> plt.clf()
>>> plt.plot(line)
>>> plt.show()
>>> # Column plot from image, averaging across 11 pixels around colum #327
>>> col_index = 326
>>> width = 5
>>> xlow = col_index - width
>>> xhigh = col_index + width + 1
>>> thick_column = ad_image[0].data[:, xlow:xhigh]
>>> plt.clf()
>>> plt.plot(thick_column.mean(axis=1)) # mean along the width.
>>> plt.show()
>>> plt.ylim(0, 50) # Set the y-axis range
>>> plt.plot(thick_column.mean(axis=1))
>>> plt.show()
>>> # Contour plot for a section of an image.
>>> center = (1646, 2355)
>>> width = 15
>>> xrange = (center[1]-width//2, center[1] + width//2 + 1)
>>> yrange = (center[0]-width//2, center[0] + width//2 + 1)
>>> blob = ad_image[0].data[yrange[0]:yrange[1], xrange[0]:xrange[1]]
>>> plt.clf()
>>> plt.imshow(blob, cmap='gray', origin='lower')
>>> plt.contour(blob)
>>> plt.show()
>>> # Spectrum in pixels
>>> plt.clf()
>>> plt.plot(ad_spectrum[0].data)
>>> plt.show()
>>> # Spectrum in Angstroms
>>> spec_wcs = wcs.WCS(ad_spectrum[0].hdr)
>>> pixcoords = np.array(range(ad_spectrum[0].data.shape[0]))
>>> wlen = spec_wcs.wcs_pix2world(pixcoords, 0)[0]
>>> plt.clf()
>>> plt.plot(wlen, ad_spectrum[0].data)
>>> plt.show()
imexam¶
For those who have used IRAF, imexam is a well-known tool. The Python
imexam reproduces many of its IRAF predecesor, the interactive mode of
course, but it also offers programmatic tools. One can even control DS9
from Python. As for Matplotlib, here we really just scratch the surface of
what imexam has to offer.
>>> import imexam
>>> from imexam.imexamine import Imexamine
>>> ad_image = astrodata.open('../playdata/N20170521S0925_forStack.fits')
# Display the image
>>> ds9 = imexam.connect(list(imexam.list_active_ds9())[0])
>>> ds9.view(ad_image[0].data)
>>> ds9.scale('zscale')
# Run in interactive mode. Try the various commands.
>>> ds9.imexam()
# Use the programmatic interface
# First initialize an Imexamine object.
>>> plot = Imexamine()
# Line plot from image. Row #1044 (y-coordinate)
>>> line_index = 1043
>>> plot.plot_line(0, line_index, ad_image[0].data)
# Column plot from image, averaging across 11 pixels around colum #327
# There is no setting for this, so we have to do something similar
# to what we did with matplotlib.
>>> col_index = 326
>>> width = 5
>>> xlow = col_index - width
>>> xhigh = col_index + width + 1
>>> thick_column = ad_image[0].data[:, xlow:xhigh]
>>> mean_column = thick_column.mean(axis=1)
>>> plot.plot_column(0, 0, np.expand_dims(mean_column, 1))
>>> # Contour plot for a section of an image.
>>> center = (1646, 2355) # in python coordinates
>>> width = 15
>>> plot.contour_pars['ncolumns'][0] = width
>>> plot.contour_pars['nlines'][0] = width
>>> plot.contour(center[1], center[0], ad_image[0].data)
Table Data¶
Try it yourself
Download the data package (Try it yourself) if you wish to follow along and run the examples. Then
$ cd <path>/ad_usermanual/playground
$ python
Then import core astrodata and the Gemini astrodata configurations.
>>> import astrodata
>>> import gemini_instruments
Tables and Astrodata¶
Tables are stored as astropy.table Table class. FITS tables too
are represented in Astrodata as Table and FITS headers are stored in
the NDAstroData .meta attribute. Most table access should be done
through the Table interface. The best reference on Table is the
Astropy documentation itself. In this chapter we covers some common
examples to get the reader started.
The astropy.table documentation can be found at: http://docs.astropy.org/en/stable/table/index.html
Operate on a Table¶
Let us open a file with tables. Some tables are associated with specific extensions, and there is one table that is global to the AstroData object.
>>> ad = astrodata.open('../playdata/N20170609S0154_varAdded.fits')
>>> ad.info()
To access the global table named REFCAT:
>>> ad.REFCAT
To access the OBJCAT table in the first extension
>>> ad[0].OBJCAT
Column and Row Operations¶
Columns are named. Those names are used to access the data as columns. Rows are not names and are simply represented as a sequential list.
Read columns and rows¶
To get the names of the columns present in the table:
>>> ad.REFCAT.colnames
['Id', 'Cat_Id', 'RAJ2000', 'DEJ2000', 'umag', 'umag_err', 'gmag',
'gmag_err', 'rmag', 'rmag_err', 'imag', 'imag_err', 'zmag', 'zmag_err',
'filtermag', 'filtermag_err']
Then it is easy to request the values for specific columns:
>>> ad.REFCAT['zmag']
>>> ad.REFCAT['zmag', 'zmag_err']
To get the content of a specific row, row 10 in this case:
>>> ad.REFCAT[9]
To get the content of a specific row(s) from a specific column(s):
>>> ad.REFCAT['zmag'][4]
>>> ad.REFCAT['zmag'][4:10]
>>> ad.REFCAT['zmag', 'zmag_err'][4:10]
Change values¶
Assigning new values works in a similar way. When working on multiple elements it is important to feed a list that matches in size with the number of elements to replace.
>>> ad.REFCAT['imag'][4] = 20.999
>>> ad.REFCAT['imag'][4:10] = [5, 6, 7, 8, 9, 10]
>>> overwrite_col = [0] * len(ad.REFCAT) # a list of zeros, size = nb of rows
>>> ad.REFCAT['imag_err'] = overwrite_col
Add a row¶
To append a row, there is the add_row() method. The length of the row
should match the number of columns:
>>> new_row = [0] * len(ad.REFCAT.colnames)
>>> new_row[1] = '' # Cat_Id column is of "str" type.
>>> ad.REFCAT.add_row(new_row)
Add a column¶
Adding a new column can be more involved. If you need full control, please see the AstroPy Table documentation. For a quick addition, which might be sufficient for your use case, we simply use the “dictionary” technique. Please note that when adding a column, it is important to ensure that all the elements are of the same type. Also, if you are planning to use that table in IRAF/PyRAF, we recommend not using 64-bit types.
>>> import numpy as np
>>> new_column = [0] * len(ad.REFCAT)
>>> # Ensure that the type is int32, otherwise it will default to int64
>>> # which generally not necessary. Also, IRAF 32-bit does not like it.
>>> new_column = np.array(new_column).astype(np.int32)
>>> ad.REFCAT['my_column'] = new_column
If you are going to write that table back to disk as a FITS Bintable, then some additional headers need to be set. Astrodata will take care of that under the hood when the write method is invoked.
>>> ad.write('myfile_with_modified_table.fits')
Selection and Rejection Operations¶
Normally, one does not know exactly where the information needed is located in a table. Rather some sort of selection needs to be done. This can also be combined with various calculations. We show two such examples here.
Select a table element from criterion¶
>>> # Get the magnitude of a star selected by ID number
>>> ad.REFCAT['zmag'][ad.REFCAT['Cat_Id'] == '1237662500002005475']
>>> # Get the ID and magnitude of all the stars brighter than zmag 18.
>>> ad.REFCAT['Cat_Id', 'zmag'][ad.REFCAT['zmag'] < 18.]
Rejection and selection before statistics¶
>>> t = ad.REFCAT # to save typing
>>> # The table has "NaN" values. ("Not a number") We need to ignore them.
>>> t['zmag'].mean()
nan
>>> # applying rejection of NaN values:
>>> t['zmag'][np.where(~np.isnan(t['zmag']))].mean()
20.377306
Accessing FITS table headers directly¶
If for some reason you need to access the FITS table headers directly, here is how to do it. It is very unlikely that you will need this.
To see the FITS headers:
>>> ad.REFCAT.meta['header']
>>> ad[0].OBJCAT.meta['header']
To retrieve a specific FITS table header:
>>> ad.REFCAT.meta['header']['TTYPE3']
'RAJ2000'
>>> ad[0].OBJCAT.meta['header']['TTYPE3']
'Y_IMAGE'
To retrieve all the keyword names matching a selection:
>>> keynames = [key for key in ad.REFCAT.meta['header'] if key.startswith('TTYPE')]
Create a Table¶
To create a table that can be added to an AstroData object and eventually
written to disk as a FITS file, the first step is to create an Astropy
Table.
Let us first add our data to NumPy arrays, one array per column:
>>> import numpy as np
>>> snr_id = np.array(['S001', 'S002', 'S003'])
>>> feii = np.array([780., 78., 179.])
>>> pabeta = np.array([740., 307., 220.])
>>> ratio = pabeta / feii
Then build the table from that data:
>>> from astropy.table import Table
>>> my_astropy_table = Table([snr_id, feii, pabeta, ratio],
... names=('SNR_ID', 'FeII', 'PaBeta', 'ratio'))
Now we append this Astropy Table to a new AstroData object.
>>> # Since we are going to write a FITS, we build the AstroData object
>>> # from FITS objects.
>>> from astropy.io import fits
>>> phu = fits.PrimaryHDU()
>>> ad = astrodata.create(phu)
>>> ad.append(my_astropy_table, name='MYTABLE')
>>> ad.info()
>>> ad.MYTABLE
>>> ad.write('new_table.fits')
Appendix¶
List of Gemini Standard Descriptors¶
To run and re-use Gemini primitives and functions this list of Standard Descriptors must be defined for input data. This also applies to data that is to be served by the Gemini Observatory Archive (GOA).
For any AstroData objects, to get the list of the descriptors that are
defined use the AstroData.descriptors attribute:
>>> import astrodata
>>> import gemini_instruments
>>> ad = astrodata.open('../playdata/N20170609S0154.fits')
>>> ad.descriptors
('airmass', 'amp_read_area', 'ao_seeing', ..., 'well_depth_setting')
To get the values:
>>> ad.airmass()
>>> for descriptor in ad.descriptors:
... print(descriptor, getattr(ad, descriptor)())
Note that not all of the descriptors below are defined for all of the
instruments. For example, shuffle_pixels is defined only for GMOS data
since only GMOS offers a Nod & Shuffle mode.
| Descriptor | Short Definition | Python type |
|---|---|---|
| ad[0].desc() | ||
| ad.desc() | ||
| airmass | Airmass of the observation. | float |
| amp_read_area | Combination of amplifier name and 1-indexed section relative to the detector. | str |
| list of str | ||
| ao_seeing | Estimate of the natural seeing as calculated from the adaptive optics systems. | float |
| array_name | Name assigned to the array generated by a given amplifier, one array per amplifier. | str |
| list of str | ||
| array_section | Section covered by the array(s), in 0-indexed pixels, relative
to the detector frame (e.g. position of multiple amps read
within a CCD). Uses namedtuple “Section” defined in
gemini_instruments.common. |
Section |
| list of Section | ||
| azimuth | Pointing position in azimuth, in degrees. | float |
| calibration_key | Key used in the database that the getProcessed* primitives
use to store previous calibration association information. |
str |
| camera | Name of the camera. | str |
| cass_rotator_pa | Position angle of the Cassegrain rotator, in degrees. | float |
| central_wavelength | Central wavelength, in meters. | float |
| coadds | Number of co-adds. | int |
| data_label | Gemini data label. | str |
| data_section | Section where the sky-exposed data falls, in 0-indexed pixels.
Uses namedtuple “Section” defined in
gemini_instruments.common |
Section |
| list of Section | ||
| dec | Declination of the center of the field, in degrees. | float |
| decker | Name of the decker. | str |
| detector_name | Name assigned to the detector. | str |
| detector_roi_setting | Human readable Region of Interest (ROI) setting | str |
| detector_rois_requested | Section defining the Regions of Interest, in 0-indexed pixels.
Uses namedtuple “Section” defined in
gemini_instruments.common. |
list of Section |
| detector_section | Section covered by the detector(s), in 0-indexed pixels,
relative to the whole mosaic of detectors.
Uses namedtuple “Section” defined in
gemini_instruments.common. |
list |
| list of Section | ||
| detector_x_bin | X-axis binning. | int |
| detector_x_offset | Telescope offset along the detector X-axis, in pixels. | float |
| detector_y_bin | Y-axis binning. | int |
| detector_y_offset | Telescope offset along the detector Y-axis, in pixels. | float |
| disperser | Name of the disperser. | str |
| dispersion | Value for the dispersion, in meters per pixel. | float |
| list of float | ||
| dispersion_axis | Dispersion axis. | int |
| list of int | ||
| effective_wavelength | Wavelength representing the bandpass or the spectrum coverage. | float |
| elevation | Pointing position in elevation, in degrees. | float |
| exposure_time | Exposure time, in seconds. | float |
| filter_name | Name of the filter combination. | str |
| focal_plane_mask | Name of the mask in the focal plane. | str |
| gain | Gain in electrons per ADU | float |
| list of float | ||
| gain_setting | Human readable gain setting (eg. low, high) | str |
| gcal_lamp | Returns the name of the GCAL lamp being used, or “Off” if no lamp is in use. | str |
| group_id | Gemini observation group ID that identifies compatible data. | str |
| instrument | Name of the instrument | str |
| is_ao | Whether or not the adaptive optics system was used. | bool |
| is_coadds_summed | Whether co-adds are summed or averaged. | bool |
| local_time | Local time. | datetime |
| lyot_stop | Name of the lyot stop. | str |
| mdf_row_id | Mask Definition File row ID of a cut MOS or XD spectrum. | int ?? |
| nod_count | Number of nods to A and B positions. | tuple of int |
| nod_offsets | Nod offsets to A and B positions, in arcseconds | tuple of float |
| nominal_atmospheric_extinction | Nomimal atmospheric extinction, from model. | float |
| nominal_photometric_zeropoint | Nominal photometric zeropoint. | float |
| list of float | ||
| non_linear_level | Lower boundary of the non-linear regime. | float |
| list of int | ||
| object | Name of the target (as entered by the user). | str |
| observation_class | Gemini class name for the observation (eg. ‘science’, ‘acq’, ‘dayCal’). | str |
| observation_epoch | Observation epoch. | float |
| observation_id | Gemini observation ID. | str |
| observation_type | Gemini observation type (eg. ‘OBJECT’, ‘FLAT’, ‘ARC’). | str |
| overscan_section | Section where the overscan data falls, in 0-indexed pixels.
Uses namedtuple “Section” defined in
gemini_instruments.common. |
Section |
| list of Section | ||
| pixel_scale | Pixel scale in arcsec per pixel. | float |
| program_id | Gemini program ID. | str |
| pupil_mask | Name of the pupil mask. | str ?? |
| qa_state | Gemini quality assessment state (eg. pass, usable, fail). | str |
| ra | Right ascension, in degrees. | float |
| raw_bg | Gemini sky background band. | int ?? |
| raw_cc | Gemini cloud coverage band. | int |
| raw_iq | Gemini image quality band. | int |
| raw_wv | Gemini water vapor band. | int ?? |
| read_mode | Gemini name for combination for gain setting and read setting. | str |
| read_noise | Read noise in electrons. | float |
| list of float | ||
| read_speed_setting | human readable read mode setting (eg. slow, fast). | str |
| requested_bg | PI requested Gemini sky background band. | int |
| requested_cc | PI requested Gemini cloud coverage band. | int |
| requested_iq | PI requested Gemini image quality band. | int |
| requested_wv | PI requested Gemini water vapor band. | int |
| saturation_level | Saturation level. | int |
| list of int | ||
| shuffle_pixels | Charge shuffle, in pixels. (nod and shuffle mode) | int |
| slit | Name of the slit. | str |
| target_dec | Declination of the target, in degrees. | float |
| target_ra | Right Ascension of the target, in degrees. | float |
| telescope | Name of the telescope. | str |
| telescope_x_offset | Offset along the telescope’s x-axis. | float |
| telescope_y_offset | Offset along the telescope’s y-axis. | float |
| ut_date | UT date of the observation. | datetime.date |
| ut_datetime | UT date and time of the observation. | datetime |
| ut_time | UT time of the observation. | datetime.time |
| wavefront_sensor | Wavefront sensor used for the observation. | str |
| wavelength_band | Band associated with the filter or the central wavelength. | str |
| wcs_dec | Declination of the center of field from the WCS keywords. In degrees. | float |
| wcs_ra | Right Ascension of the center of field from the WCS keywords. In degrees. | float |
| well_depth_setting | Human readable well depth setting (eg. shallow, deep) | str |
Reference API¶
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(provider)[source]¶ Bases:
objectBase 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)¶ 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
-
append(extension, name=None, *args, **kw)[source]¶ 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
-
divide(oper)¶ Implements the augmented arithmetic assignment /=.
Parameters: oper (number or other) – The operand to be divided to this instance. The accepted types depend on the DataProvider. Returns: Return type: self
-
info()[source]¶ Prints out information about the contents of this instance. Implemented by the derived classes.
-
load(source)[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.
-
multiply(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. Returns: Return type: self
-
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: 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) # doctest: +SKIP
-
reset(data, mask=-23, variance=-23, 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 arrayValueError– 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
-
subtract(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. Returns: Return type: self
A set of strings that represent the tags defining this instance
-
-
class
astrodata.TagSet(add=None, remove=None, blocked_by=None, blocks=None, if_present=None)[source]¶ Bases:
astrodata.core.TagSetNamed 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.
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())
-
class
astrodata.NDAstroData(data, uncertainty=None, mask=None, wcs=None, meta=None, unit=None, copy=False, window=None)[source]¶ Bases:
astropy.nddata.mixins.ndarithmetic.NDArithmeticMixin,astropy.nddata.mixins.ndslicing.NDSlicingMixin,astropy.nddata.nddata.NDDataImplements
NDDatawith all Mixins, plus someAstroDataspecifics.This class implements an
NDData-like container that supports reading and writing as implemented in theastropy.io.registryand also slicing (indexing) and simple arithmetics (add, subtract, divide and multiply).A very important difference between
NDAstroDataandNDDatais that the former attempts to load all its data lazily. There are also some important differences in the interface (eg..datalets you reset its contents after initialization).Documentation is provided where our class differs.
See also
NDData,NDArithmeticMixin,NDSlicingMixinExamples
The mixins allow operation that are not possible with
NDDataorNDDataBase, 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
NDArithmeticMixinfor 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
NDSlicingMixinfor a description how slicing works (which attributes) are sliced.-
T¶
-
data¶ An array representing the raw data stored in this instance. It implements a setter.
-
mask¶ Mask for the dataset, if any.
Masks should follow the
numpyconvention that valid data points are marked byFalseand invalid ones withTrue.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 leastdata,uncertainty, andmask. Their entire contents will replace the data in the area defined bysection.
Examples
>>> sec = NDData(np.zeros((100,100))) # doctest: +SKIP >>> ad[0].nddata.set_section((slice(None,100),slice(None,100)), sec) # doctest: +SKIP
- section (
-
shape¶
-
uncertainty¶ Uncertainty in the dataset, if any.
Should have an attribute
uncertainty_typethat defines what kind of uncertainty is stored, such as'std'for standard deviation or'var'for variance. A metaclass defining such an interface is ~astropy.nddata.NDUncertainty but isn’t mandatory.Type: any type
-
variance¶ A convenience property to access the contents of
uncertainty, squared (as the uncertainty data is stored as standard deviation).
-
wcs¶ A world coordinate system (WCS) for the dataset, if any.
Type: any type
-
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
NDWindowingAstrodatainstance is returned
Examples
>>> ad[0].nddata.window[100:200, 100:200] # doctest: +SKIP <NDWindowingAstrodata .....>
- An instance of
-
-
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 Returns: 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 Returns: Return type: A wrapper function
-
astrodata.keyword¶
-
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(provider)[source]¶ Bases:
objectBase 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)¶ 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
-
append(extension, name=None, *args, **kw)[source]¶ 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
-
divide(oper)¶ Implements the augmented arithmetic assignment /=.
Parameters: oper (number or other) – The operand to be divided to this instance. The accepted types depend on the DataProvider. Returns: Return type: self
-
info()[source]¶ Prints out information about the contents of this instance. Implemented by the derived classes.
-
load(source)[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.
-
multiply(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. Returns: Return type: self
-
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: 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) # doctest: +SKIP
-
reset(data, mask=-23, variance=-23, 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 arrayValueError– 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
-
subtract(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. Returns: Return type: self
A set of strings that represent the tags defining this instance
-
-
class
astrodata.core.DataProvider[source]¶ Bases:
objectAbstract class describing the minimal interface that DataProvider derivative classes need to implement.
-
append(ext, name=None)[source]¶ 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 # doctest: +SKIP set(['OBJMASK', 'OBJCAT'])
-
is_settable(attribute)[source]¶ 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
-
-
class
astrodata.core.TagSet(add=None, remove=None, blocked_by=None, blocks=None, if_present=None)[source]¶ Bases:
astrodata.core.TagSetNamed 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.
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.core.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 Returns: Return type: The tagged method (not a wrapper)
-
astrodata.core.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 Returns: Return type: A wrapper function
-
astrodata.core.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 Returns: Return type: A function
astrodata.factory module¶
-
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:
-
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
-
astrodata.fits module¶
-
class
astrodata.fits.AstroDataFits(provider)[source]¶ Bases:
astrodata.core.AstroData-
extver(ver)[source]¶ Get an extension using its EXTVER instead of the positional index in this object.
Parameters: ver (int) – The EXTVER for the desired extension Returns: Return type: A sliced object containing the desired extension Raises: IndexError– If the provided EXTVER doesn’t exist
-
hdr¶
-
info()[source]¶ Prints out information about the contents of this instance. Implemented by the derived classes.
-
instrument()[source]¶ Returns the name of the instrument making the observation
Returns: instrument name Return type: str
-
classmethod
load(source)[source]¶ Implementation of the abstract method load.
It takes an HDUList and returns a fully instantiated AstroData instance.
-
phu¶
-
telescope()[source]¶ Returns the name of the telescope
Returns: name of the telescope Return type: str
-
update_filename(prefix=None, suffix=None, strip=False)[source]¶ This method updates 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/None) – new prefix (None => leave alone)
- suffix (str/None) – new suffix (None => leave alone)
- strip (bool) – Strip existing prefixes and suffixes if new ones are given?
-
-
exception
astrodata.fits.AstroDataFitsDeprecationWarning[source]¶ Bases:
DeprecationWarning
-
class
astrodata.fits.FitsHeaderCollection(headers)[source]¶ Bases:
objectThis class provides group access to a list of PyFITS 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.
-
class
astrodata.fits.FitsLazyLoadable(obj)[source]¶ Bases:
object-
data¶
-
dtype¶ Need to to some overriding of astropy.io.fits since it doesn’t know about BITPIX=8
-
header¶
-
shape¶
-
-
class
astrodata.fits.FitsLoader(cls=<class 'astrodata.fits.FitsProvider'>)[source]¶ Bases:
object-
load(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 FitsProvider (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.
-
-
class
astrodata.fits.FitsProvider[source]¶ Bases:
astrodata.core.DataProvider-
append(ext, name=None, header=None, reset_ver=True, add_to=None)[source]¶ 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.
-
default_extension= 'SCI'¶
-
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 # doctest: +SKIP set(['OBJMASK', 'OBJCAT'])
-
extver_map()[source]¶ Provide a mapping between the FITS EXTVER of an extension and the index that will be used to access it within this object.
Returns: A dictionary `{EXTVER Return type: index, ..}` Raises: ValueError– If used against a single slice. It is of no use in that situation.
-
filename¶
-
header¶
-
is_settable(attr)[source]¶ 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
-
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.
-
nddata¶
-
orig_filename¶
-
path¶
-
shape¶
-
tables¶
-
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
-
-
class
astrodata.fits.FitsProviderProxy(provider, mapping, single)[source]¶ Bases:
astrodata.core.DataProvider-
append(ext, name)[source]¶ 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 # doctest: +SKIP set(['OBJMASK', 'OBJCAT'])
-
extver_map()[source]¶ Provide a mapping between the FITS EXTVER of an extension and the index that will be used to access it within this object.
Returns: A dictionary `{EXTVER Return type: index, ..}` Raises: ValueError– If used against a single slice. It is of no use in that situation.
-
header¶
-
is_settable(attr)[source]¶ 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.
-
nddata¶
-
shape¶
-
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
-
wcs¶
-
-
class
astrodata.fits.KeywordCallableWrapper(keyword, default=<object object>, on_ext=False, coerce_with=None)[source]¶ Bases:
object
-
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.fits_ext_comp_key(ext)[source]¶ Returns a pair (integer, string) that will be used to sort extensions
-
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
Returns: Return type: BinTableHDU
-
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, **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?
- **kwargs – Additional args are passed to
func.
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)[source]¶ Bases:
astropy.nddata.mixins.ndarithmetic.NDArithmeticMixin,astropy.nddata.mixins.ndslicing.NDSlicingMixin,astropy.nddata.nddata.NDDataImplements
NDDatawith all Mixins, plus someAstroDataspecifics.This class implements an
NDData-like container that supports reading and writing as implemented in theastropy.io.registryand also slicing (indexing) and simple arithmetics (add, subtract, divide and multiply).A very important difference between
NDAstroDataandNDDatais that the former attempts to load all its data lazily. There are also some important differences in the interface (eg..datalets you reset its contents after initialization).Documentation is provided where our class differs.
See also
NDData,NDArithmeticMixin,NDSlicingMixinExamples
The mixins allow operation that are not possible with
NDDataorNDDataBase, 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
NDArithmeticMixinfor 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
NDSlicingMixinfor a description how slicing works (which attributes) are sliced.-
T¶
-
data¶ An array representing the raw data stored in this instance. It implements a setter.
-
mask¶ Mask for the dataset, if any.
Masks should follow the
numpyconvention that valid data points are marked byFalseand invalid ones withTrue.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 leastdata,uncertainty, andmask. Their entire contents will replace the data in the area defined bysection.
Examples
>>> sec = NDData(np.zeros((100,100))) # doctest: +SKIP >>> ad[0].nddata.set_section((slice(None,100),slice(None,100)), sec) # doctest: +SKIP
- section (
-
shape¶
-
uncertainty¶ Uncertainty in the dataset, if any.
Should have an attribute
uncertainty_typethat defines what kind of uncertainty is stored, such as'std'for standard deviation or'var'for variance. A metaclass defining such an interface is ~astropy.nddata.NDUncertainty but isn’t mandatory.Type: any type
-
variance¶ A convenience property to access the contents of
uncertainty, squared (as the uncertainty data is stored as standard deviation).
-
wcs¶ A world coordinate system (WCS) for the dataset, if any.
Type: any type
-
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
NDWindowingAstrodatainstance is returned
Examples
>>> ad[0].nddata.window[100:200, 100:200] # doctest: +SKIP <NDWindowingAstrodata .....>
- An instance of
-
astrodata.provenance module¶
-
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 not added if the incoming md5 is None or ‘’. These indicate source data for the provenance that are not on disk, so not useful as provenance.
Parameters: value (Provenance to add) – Returns: Return type: none
-
astrodata.provenance.add_provenance_history(ad, timestamp_start, timestamp_stop, primitive, args)[source]¶ Add the given ProvenanceHistory entry to the full set of history records on this object.
Parameters: - ad (AstroData to add history record to) –
- timestamp_start (datetime of the start of this operation) –
- timestamp_stop (datetime of the end of this operation) –
- primitive (str name of the primitive performed) –
- args (str arguments used for the primitive call) –
Returns: Return type: none
-
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 it’s original provenance and provenance_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 (outgoing AstroData object to add provenance data to) –
Returns: Return type: none
-
astrodata.provenance.clone_provenance_history(provenance_history_data, ad)[source]¶ For a single input’s provenance history, copy it into the output AstroData object as appropriate.
This takes a dictionary with a source filename, md5 and both it’s original provenance and provenance_history information. It duplicates the provenance data into the outgoing AstroData ad object.
Parameters: - provenance_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 (outgoing AstroData object to add provenance history data to) –
Returns: Return type: none
-
astrodata.provenance.provenance_summary(ad, provenance=True, provenance_history=True)[source]¶ Generate a pretty text display of the provenance information for an ~astrodata.core.AstroData.
This pulls the provenance and history information from a ~astrodata.core.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: Returns: Return type: str representation of the provenance
astrodata.testing module¶
Fixtures to be used in tests in DRAGONS
-
astrodata.testing.assert_most_close(actual, desired, max_miss, rtol=1e-07, atol=0, equal_nan=True, verbose=True)[source]¶ Raises an AssertionError if the number of elements in two objects that are not equal up to desired tolerance is greater than expected.
See also
Parameters: - actual (array_like) – Array obtained.
- desired (array_like) – Array desired.
- max_miss (iny) – Maximum number of mismatched elements.
- rtol (float, optional) – Relative tolerance.
- atol (float, optional) – Absolute tolerance.
- equal_nan (bool, optional.) – If True, NaNs will compare equal.
- verbose (bool, optional) – If True, the conflicting values are appended to the error message.
Raises: AssertionError– If actual and desired are not equal up to specified precision.
-
astrodata.testing.assert_most_equal(actual, desired, max_miss, verbose=True)[source]¶ Raises an AssertionError if more than n elements in two objects are not equal. For more information, check
numpy.testing.assert_equal().Parameters: Raises: AssertionError– If actual and desired are not equal.
-
astrodata.testing.assert_same_class(ad, ad_ref)[source]¶ Compare if two
AstroData(or any subclass) have the same class.Parameters: - ad (
astrodata.AstroDataor any subclass) – AstroData object to be checked. - ad_ref (
astrodata.AstroDataor any subclass) – AstroData object used as reference
- ad (
-
astrodata.testing.astrofaker()[source]¶ Wrapper fixture that prevents undesired behaviour when using astrofaker.
-
astrodata.testing.change_working_dir(path_to_outputs)[source]¶ Factory that returns the output path as a context manager object, allowing easy access to the path to where the processed data should be stored.
Parameters: path_to_outputs (pytest.fixture) – Fixture containing the root path to the output files. Returns: Enable easy change to temporary folder when reducing data. Return type: contextmanager
-
astrodata.testing.compare_models(model1, model2, rtol=1e-07, atol=0.0, check_inverse=True)[source]¶ Check that any two models are the same, within some tolerance on parameters (using the same defaults as numpy.assert_allclose()).
This is constructed like a test, rather than returning True/False, in order to provide more useful information as to how the models differ when a test fails (and with more concise syntax).
If check_inverse is True (the default), only first-level inverses are compared, to avoid unending recursion, since the inverse of an inverse should be the supplied input model, if defined. The types of any inverses (and their inverses in turn) are required to match whether or not their parameters etc. are compared.
This function might not completely guarantee that model1 & model2 are identical for some models whose evaluation depends on class-specific parameters controlling how the array of model parameters is interpreted (eg. the orders in SIP?), but it does cover our common use of compound models involving orthonormal polynomials etc.
-
astrodata.testing.download_from_archive(filename, sub_path='raw_files', env_var='DRAGONS_TEST')[source]¶ Download file from the archive and store it in the local cache.
Parameters: Returns: Name of the cached file with the path added to it.
Return type:
-
astrodata.testing.get_active_git_branch()[source]¶ Returns the name of the active GIT branch to be used in Continuous Integration tasks and organize input/reference files.
Note: This works currently only if the remote name is “origin”, though it would be easy to adapt for other cases if needed.
Returns: str or None – the branch name could not be retrieved. Return type: Name of the input active git branch. It returns None if
-
astrodata.testing.get_associated_calibrations(filename, nbias=5)[source]¶ Queries Gemini Observatory Archive for associated calibrations to reduce the data that will be used for testing. :param filename: Input file name :type filename: str
-
astrodata.testing.path_to_inputs(request, env_var='DRAGONS_TEST')[source]¶ PyTest fixture that returns the path to where the input files for a given test module live.
Parameters: - request (fixture) – PyTest’s built-in fixture with information about the test itself.
- env_var (str) – Environment variable that contains the root path to the input data.
Returns: Path to the input files.
Return type:
-
astrodata.testing.path_to_outputs(request, tmp_path_factory)[source]¶ PyTest fixture that creates a temporary folder to save tests outputs. You can set the base directory by passing the
--basetemp=mydir/argument to the PyTest call (See [Pytest - Temporary Directories and Files][1]).[1]: https://docs.pytest.org/en/stable/tmpdir.html#temporary-directories-and-files
Returns: Path to the output data. Return type: str Raises: IOError– If output path does not exits.
-
astrodata.testing.path_to_refs(request, env_var='DRAGONS_TEST')[source]¶ PyTest fixture that returns the path to where the reference files for a given test module live.
Parameters: - request (fixture) – PyTest’s built-in fixture with information about the test itself.
- env_var (str) – Environment variable that contains the root path to the input data.
Returns: Path to the reference files.
Return type:
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)[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
- shape (sequence) – shape to use for fiducial points
Returns: AffineMatrices(array, array)
Return type: affine matrix and offset
-
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_linear(header)[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(hdr)[source]¶ Create and return a gWCS object from a FITS header. 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: lists
-
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 (NDData) – The NDData whose wcs attribute we want converted
- hdr (fits.Header) – A Header object that may contain some useful keywords
Returns: dict
Return type: values to insert into the FITS header to express this WCS
-
astrodata.wcs.make_fitswcs_transform(header)[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.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
gemini_instruments package¶
Subpackages¶
gemini_instruments.bhros package¶
-
class
gemini_instruments.bhros.AstroDataBhros(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
dec()[source]¶ Returns the Declination of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_dec() if you really want the position of the target rather than the center of the field.
Returns: right ascension in degrees Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser. This is always ‘bHROS’
Parameters: Returns: The name of the disperser
Return type:
-
ra()[source]¶ Returns the Right Ascension of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_ra() if you really want the position of the target rather than the center of the field.
Returns: right ascension in degrees Return type: float
-
-
class
gemini_instruments.bhros.adclass.AstroDataBhros(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
dec()[source]¶ Returns the Declination of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_dec() if you really want the position of the target rather than the center of the field.
Returns: right ascension in degrees Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser. This is always ‘bHROS’
Parameters: Returns: The name of the disperser
Return type:
-
ra()[source]¶ Returns the Right Ascension of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_ra() if you really want the position of the target rather than the center of the field.
Returns: right ascension in degrees Return type: float
-
gemini_instruments.cirpass package¶
-
class
gemini_instruments.cirpass.AstroDataCirpass(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
target_dec()[source]¶ Returns the Declination of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Declination of the target in degrees.
Return type:
-
target_ra()[source]¶ Returns the Right Ascension of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Right Ascension of the target in degrees.
Return type:
-
-
class
gemini_instruments.cirpass.adclass.AstroDataCirpass(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
target_dec()[source]¶ Returns the Declination of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Declination of the target in degrees.
Return type:
-
target_ra()[source]¶ Returns the Right Ascension of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Right Ascension of the target in degrees.
Return type:
-
gemini_instruments.f2 package¶
-
class
gemini_instruments.f2.AstroDataF2(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
array_section(pretty=False)[source]¶ Returns the rectangular section that includes the pixels that would be exposed to light. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Location of the pixels exposed to light using Python slice values.
- string or list of strings – Location of the pixels exposed to light using an IRAF section format (1-based).
-
camera(stripID=False, pretty=False)[source]¶ Returns the string defining the f-ratio being used.
Returns: The string that defines the f-ratio which changes depending on whether AO is used or not. Historical value. Return type: string
-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
data_section(pretty=False)[source]¶ Returns the rectangular section that includes the pixels that would be exposed to light. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Location of the pixels exposed to light using Python slice values.
- string or list of strings – Location of the pixels exposed to light using an IRAF section format (1-based).
-
detector_section(pretty=False)[source]¶ Returns the section covered by the detector relative to the whole mosaic of detectors. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of the detector using Python slice values.
- string or list of strings – Position of the detector using an IRAF section format (1-based).
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
dispersion(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the dispersion in meters per pixel as a list (one value per extension) or a float if used on a single-extension slice. It is possible to control the units of wavelength using the input arguments.
Parameters: Returns: The dispersion(s)
Return type: list/float
-
dispersion_axis()[source]¶ Returns the axis along which the light is dispersed.
Returns: Dispersion axis. Return type: (list of) int (2)
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
gain()[source]¶ Returns the gain used for the observation. This is read from a lookup table using the read_mode and the well_depth.
Returns: Gain used for the observation Return type: float
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument and mode of observation will have its own rules. F2’s is quite a mouthful.
Returns: A group ID for compatible data. Return type: str
-
lyot_stop()[source]¶ Returns the LYOT filter used for the observation. This works around inconsistencies in the header keywords.
Returns: LYOT filter name, or None Return type: str
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal zeropoints (i.e., the magnitude corresponding to a pixel value of 1) for the extensions in an AD object.
Returns: zeropoint values, one per SCI extension Return type: list/float
-
non_linear_level()[source]¶ Returns the level at which the data become non-linear, in ADU.
Returns: Value at which the data become non-linear Return type: list/int
-
observation_type()[source]¶ Returns the observation type (OBJECT, DARK, BIAS, etc.)
Returns: Observation type Return type: str
-
pixel_scale()[source]¶ Returns the image scale in arcseconds per pixel
Returns: pixel scale Return type: float
-
read_mode()[source]¶ Returns the read mode (i.e., the number of non-destructive read pairs)
Returns: readout mode Return type: str
-
saturation_level()[source]¶ Returns the saturation level (in ADU)
Returns: saturation level Return type: int/float
-
-
class
gemini_instruments.f2.adclass.AstroDataF2(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
array_section(pretty=False)[source]¶ Returns the rectangular section that includes the pixels that would be exposed to light. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Location of the pixels exposed to light using Python slice values.
- string or list of strings – Location of the pixels exposed to light using an IRAF section format (1-based).
-
camera(stripID=False, pretty=False)[source]¶ Returns the string defining the f-ratio being used.
Returns: The string that defines the f-ratio which changes depending on whether AO is used or not. Historical value. Return type: string
-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
data_section(pretty=False)[source]¶ Returns the rectangular section that includes the pixels that would be exposed to light. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Location of the pixels exposed to light using Python slice values.
- string or list of strings – Location of the pixels exposed to light using an IRAF section format (1-based).
-
detector_section(pretty=False)[source]¶ Returns the section covered by the detector relative to the whole mosaic of detectors. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of the detector using Python slice values.
- string or list of strings – Position of the detector using an IRAF section format (1-based).
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
dispersion(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the dispersion in meters per pixel as a list (one value per extension) or a float if used on a single-extension slice. It is possible to control the units of wavelength using the input arguments.
Parameters: Returns: The dispersion(s)
Return type: list/float
-
dispersion_axis()[source]¶ Returns the axis along which the light is dispersed.
Returns: Dispersion axis. Return type: (list of) int (2)
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
gain()[source]¶ Returns the gain used for the observation. This is read from a lookup table using the read_mode and the well_depth.
Returns: Gain used for the observation Return type: float
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument and mode of observation will have its own rules. F2’s is quite a mouthful.
Returns: A group ID for compatible data. Return type: str
-
lyot_stop()[source]¶ Returns the LYOT filter used for the observation. This works around inconsistencies in the header keywords.
Returns: LYOT filter name, or None Return type: str
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal zeropoints (i.e., the magnitude corresponding to a pixel value of 1) for the extensions in an AD object.
Returns: zeropoint values, one per SCI extension Return type: list/float
-
non_linear_level()[source]¶ Returns the level at which the data become non-linear, in ADU.
Returns: Value at which the data become non-linear Return type: list/int
-
observation_type()[source]¶ Returns the observation type (OBJECT, DARK, BIAS, etc.)
Returns: Observation type Return type: str
-
pixel_scale()[source]¶ Returns the image scale in arcseconds per pixel
Returns: pixel scale Return type: float
-
read_mode()[source]¶ Returns the read mode (i.e., the number of non-destructive read pairs)
Returns: readout mode Return type: str
-
saturation_level()[source]¶ Returns the saturation level (in ADU)
Returns: saturation level Return type: int/float
-
-
class
gemini_instruments.f2.lookup.ArrayProperties(readnoise, gain, welldepth, linlimit, nonlinlimit, coeffs)¶ Bases:
tuple-
coeffs¶ Alias for field number 5
-
gain¶ Alias for field number 1
-
linlimit¶ Alias for field number 3
-
nonlinlimit¶ Alias for field number 4
-
readnoise¶ Alias for field number 0
-
welldepth¶ Alias for field number 2
-
gemini_instruments.flamingos package¶
-
class
gemini_instruments.flamingos.AstroDataFlamingos(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
dec()[source]¶ Returns the Declination of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_dec() if you really want the position of the target rather than the center of the field.
Returns: declination in degrees Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser.
Parameters: - stripID (<bool>) – Does nothing.
- pretty (<bool>) – Also does nothing.
Returns: Name of the disperser.
Return type: <str>
-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: Exposure time. Return type: float
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
ra()[source]¶ Returns the Right Ascension of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_ra() if you really want the position of the target rather than the center of the field.
Returns: right ascension in degrees Return type: float
-
-
class
gemini_instruments.flamingos.adclass.AstroDataFlamingos(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
dec()[source]¶ Returns the Declination of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_dec() if you really want the position of the target rather than the center of the field.
Returns: declination in degrees Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser.
Parameters: - stripID (<bool>) – Does nothing.
- pretty (<bool>) – Also does nothing.
Returns: Name of the disperser.
Return type: <str>
-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: Exposure time. Return type: float
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
ra()[source]¶ Returns the Right Ascension of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_ra() if you really want the position of the target rather than the center of the field.
Returns: right ascension in degrees Return type: float
-
gemini_instruments.gemini package¶
-
class
gemini_instruments.gemini.AstroDataGemini(provider)[source]¶ Bases:
astrodata.fits.AstroDataFits-
amp_read_area(pretty=False)[source]¶ Returns the readout area of each amplifier, as a 0-based tuple or 1-based string
Returns: the amp readout areas Return type: list/(tuple or string)
-
ao_seeing()[source]¶ Returns an estimate of the natural seeing as calculated from the adaptive optics systems.
Returns: AO estimate of the natural seeing Return type: float
-
array_name()[source]¶ Returns the name of each array
Returns: the array names Return type: list of str/str
-
array_section(pretty=False)[source]¶ Returns the section covered by the array(s) relative to the detector frame. For example, this can be the position of multiple amps read within a CCD. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of extension(s) using Python slice values
- str/list of str – Position of extension(s) using an IRAF section format (1-based)
-
azimuth()[source]¶ Returns the azimuth of the telescope, in degrees
Returns: azimuth Return type: float
-
calibration_key()[source]¶ Returns an object to be used as a key in the Calibrations dict. Multiple ADs can share a key but there can be only one of each type of calibration for each key. data_label() is the default. “_stack” is removed to avoid making a new request for a stacked frame, which will need the same calibration as the original.
Returns: identifier Return type: string
-
camera(stripID=False, pretty=False)[source]¶ Returns the name of the camera. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the camera with or without the component ID.
Return type:
-
cass_rotator_pa()[source]¶ Returns the position angle of the Cassegrain rotator, in degrees.
Returns: Position angle of the Cassegrain rotator. Return type: float
-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
coadds()[source]¶ Returns the number of co-adds used for the observation.
Returns: Number of co-adds. Return type: int
-
data_label()[source]¶ Returns the data label of an observation.
Returns: the observation’s data label Return type: str
-
data_section(pretty=False)[source]¶ Returns the rectangular section that includes the pixels that would be exposed to light. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Location of the pixels exposed to light using Python slice values.
- string or list of strings – Location of the pixels exposed to light using an IRAF section format (1-based).
-
dec()[source]¶ Returns the Declination of the center of the field, in degrees.
Returns: declination in degrees Return type: float
-
decker(stripID=False, pretty=False)[source]¶ Returns the name of the decker. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the decker with or without the component ID.
Return type:
-
detector_name(pretty=False)[source]¶ Returns the name of the detector
Returns: the detector name Return type: str
-
detector_roi_setting()[source]¶ Returns the ROI setting. Most instruments don’t allow this to be changed, so at the Gemini level it just returns ‘Fixed’
Returns: Name of the ROI setting used, ie, “Fixed” Return type: str
-
detector_rois_requested()[source]¶ Returns the ROIs requested. Since most instruments don’t have selectable ROIs, it returns None at the Gemini level
Returns: None Return type: NoneType
-
detector_section(pretty=False)[source]¶ Returns the section covered by the detector relative to the whole mosaic of detectors. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of the detector using Python slice values.
- string or list of strings – Position of the detector using an IRAF section format (1-based).
-
detector_x_bin()[source]¶ Returns the detector binning in the x-direction
Returns: The detector binning Return type: int
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_bin()[source]¶ Returns the detector binning in the y-direction
Returns: The detector binning Return type: int
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser. The “disperser” is a combination of all the dispersing elements along the light path.
The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the disperser with or without the component ID.
Return type:
-
dispersion(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the dispersion in meters per pixel as a list (one value per extension) or a float if used on a single-extension slice. It is possible to control the units of wavelength using the input arguments.
Parameters: Returns: The dispersion(s)
Return type: list/float
-
dispersion_axis()[source]¶ Returns the axis along which the light is dispersed.
Returns: Dispersion axis. Return type: int
-
effective_wavelength(output_units=None)[source]¶ Returns the wavelength representing the bandpass or the spectrum. For imaging data this normally is the wavelength at the center of the bandpass as defined by the filter used. For spectra, this is the central wavelength. The returned value is in meters.
This descriptor makes uses of a lookup table to associate filters with their effective_wavelength.
Returns: Wavelength representing the bandpass or the spectrum coverage. Return type: float
-
elevation()[source]¶ Returns the elevation of the telescope, in degrees
Returns: elevation Return type: float
-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: Exposure time. Return type: float
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
focal_plane_mask(stripID=False, pretty=False)[source]¶ Returns the name of the focal plane mask. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the focal plane mask with or without the component ID.
Return type:
-
gain()[source]¶ Returns the gain (electrons/ADU) for each extension
Returns: Gains used for the observation Return type: list of floats/float
-
gain_setting()[source]¶ Returns the gain setting for this observation (e.g., ‘high’, ‘low’)
Returns: the gain setting Return type: str
-
gcal_lamp()[source]¶ Returns the name of the GCAL lamp being used, or “Off” if no lamp is in used. This applies to flats and arc observations when a lamp is used. For other types observation, None is returned.
Returns: Name of the GCAL lamp being used, or “Off” if not in use. Return type: str
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument and mode of observation will have its own rules.
At the Gemini class level, the default is to group by the Gemini observation ID.
Returns: A group ID for compatible data. Return type: str
-
instrument(generic=False)[source]¶ Returns the name of the instrument making the observation
Parameters: generic (boolean) – If set, don’t specify the specific instrument if there are clones (but that is handled by the instrument-level descriptors) Returns: instrument name Return type: str
-
is_ao()[source]¶ Tells whether or not the data was taken with adaptive optics.
Returns: True if the data is AO, False otherwise. Return type: bool
-
is_coadds_summed()[source]¶ Tells whether or not the co-adds have been summed. If not, they have been averaged.
At the Gemini level, this descriptor is hardcoded to True as it is the default at the observatory.
Returns: True if the data has been summed. False if it has been averaged. Return type: bool
-
is_in_adu()[source]¶ Tells whether the data are in ADU (likely to be superseded by use of NDData’s unit attribute)
Returns: True if the data are in ADU Return type: bool
-
local_time()[source]¶ Returns the local time stored at the time of the observation.
Returns: Local time of the observation. Return type: datetime.datetime.time()
-
lyot_stop(stripID=False, pretty=False)[source]¶ Returns the Lyot stop used for the observation
Parameters: Returns: Lyot stop used for the observation
Return type:
-
mdf_row_id()[source]¶ Returns row ID from the MDF (Mask Definition File) table associated with the spectrum. Applies to “cut” MOS or X-dispersed data.
Returns: Row of the MDF associated with the extension. Return type: int
-
nominal_atmospheric_extinction()[source]¶ Returns the nominal atmospheric extinction at observation airmass and bandpass.
Returns: Nominal atmospheric extinction from model. Return type: float
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal photometric zeropoint (i.e., magnitude corresponding to 1 pixel count) for each extension
Returns: Photometric zeropoint Return type: float/list of floats
-
non_linear_level()[source]¶ Returns the level at which the data become non-linear, in ADU. This is expected to be overridden by the individual instruments, so at the Gemini level it returns the values of the NONLINEA keywords (or None)
Returns: non-linearity level level in ADU Return type: int/list
-
observation_class()[source]¶ Returns the class of an observation, e.g., ‘science’, ‘acq’, ‘dayCal’.
Returns: the observation class Return type: str
-
observation_epoch()[source]¶ Returns the observation’s epoch.
Returns: the observation’s epoch Return type: str
-
observation_id()[source]¶ Returns the ID of an observation.
Returns: the observation ID Return type: str
-
observation_type()[source]¶ Returns the type of an observation, e.g., ‘OBJECT’, ‘FLAT’, ‘ARC’.
Returns: the observation type Return type: str
-
overscan_section(pretty=False)[source]¶ Returns the section covered by the overscan regions relative to the detector frame. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array. If more than one array, the tuples/strings are return in a list. Otherwise, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of extension(s) using Python slice values
- str/list of str – Position of extension(s) using an IRAF section format (1-based)
-
pixel_scale()[source]¶ Returns the image scale in arcseconds per pixel, as an average over the extensions
Returns: the pixel scale Return type: float
-
program_id()[source]¶ Returns the ID of the program the observation was taken for
Returns: the program ID Return type: str
-
pupil_mask(stripID=False, pretty=False)[source]¶ Returns the name of the focal plane mask. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the focal plane mask with or without the component ID.
Return type:
-
qa_state()[source]¶ Returns the Gemini quality assessment flags.
Returns: Gemini quality assessment flags. Return type: str
-
ra()[source]¶ Returns the Right Ascension of the center of the field, in degrees.
Returns: right ascension in degrees Return type: float
-
raw_bg()[source]¶ Returns the BG percentile band of the observation. BG refers to the sky/background brightness.
Returns: BG percentile band of the observation. Return type: str
-
raw_cc()[source]¶ Returns the CC percentile band of the observation. CC refers to the cloud coverage.
Returns: CC percentile band of the observation. Return type: str
-
raw_iq()[source]¶ Returns the IQ percentile band of the observation. IQ refers to the image quality or seeing.
Returns: IQ percentile band of the observation. Return type: str
-
raw_wv()[source]¶ Returns the WV percentile band of the observation. WV refers to the water vapor.
Returns: WV percentile band of the observation. Return type: str
-
read_mode()[source]¶ Returns the readout mode used for the observation
Returns: the read mode used Return type: str
-
read_noise()[source]¶ Returns the read noise in electrons for each extension. A list is returned unless called on a single-extension slice, when a float
Returns: the read noise Return type: float/list of floats
-
read_speed_setting()[source]¶ Returns the read speed setting for the observation
Returns: the read speed setting Return type: str
-
requested_bg()[source]¶ Returns the BG percentile band requested by the PI. BG refers to the sky/background brightness.
Returns: BG percentile band requested by the PI. Return type: str
-
requested_cc()[source]¶ Returns the CC percentile band requested by the PI. CC refers to the cloud coverage.
Returns: CC percentile band requested by the PI. Return type: str
-
requested_iq()[source]¶ Returns the IQ percentile band requested by the PI. IQ refers to the image quality or seeing.
Returns: IQ percentile band requested by the PI. Return type: str
-
requested_wv()[source]¶ Returns the WV percentile band requested by the PI. WV refers to the water vapor.
Returns: WV percentile band requested by the PI. Return type: str
-
saturation_level()[source]¶ Returns the saturation level of the data, in ADU. This is expected to be overridden by the individual instruments, so at the Gemini level it returns the values of the SATLEVEL keywords (or None)
Returns: saturation level in ADU Return type: list/float
-
slit()[source]¶ Returns the name of the entrance slit used for the observation
Returns: the slit name Return type: str
-
target_dec(offset=False, pm=True, icrs=False)[source]¶ Returns the Declination of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Declination of the target in degrees.
Return type:
-
target_ra(offset=False, pm=True, icrs=False)[source]¶ Returns the Right Ascension of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Right Ascension of the target in degrees.
Return type:
-
telescope_x_offset()[source]¶ Returns the telescope offset along the telescope x-axis, in arcseconds.
Returns: the telescope offset along the telescope x-axis (arcseconds) Return type: float
-
telescope_y_offset()[source]¶ Returns the telescope offset along the telescope y-axis, in arcseconds.
Returns: the telescope offset along the telescope y-axis (arcseconds) Return type: float
-
ut_date()[source]¶ Returns the UT date of the observation as a datetime object.
Returns: UT date. Return type: datetime.datetime
-
ut_datetime(strict=False, dateonly=False, timeonly=False)[source]¶ Returns the UT date and/or time of the observation as a datetime or date or time object.
Parameters: Returns: UT date and/or time
Return type: datetime.datetime / datetime.date / datetime.time
-
ut_time()[source]¶ Returns the UT time of the observation as a datetime object.
Returns: UT time. Return type: datetime.datetime
-
wavefront_sensor()[source]¶ Returns the name of the wavefront sensor used for the observation. If more than one is being used, the names will be joined with ‘&’.
Returns: Name of the wavefront sensor. Return type: str
-
wavelength_band()[source]¶ Returns the name of the bandpass of the observation. This is just to broadly know what type of data one is working with, eg. K band, H band, B band, etc.
Returns: Name of the bandpass. Return type: str
-
wcs_dec()[source]¶ Returns the Declination of the center of the field based on the WCS rather than the DEC header keyword.
Returns: declination in degrees Return type: float
-
-
class
gemini_instruments.gemini.adclass.AstroDataGemini(provider)[source]¶ Bases:
astrodata.fits.AstroDataFits-
amp_read_area(pretty=False)[source]¶ Returns the readout area of each amplifier, as a 0-based tuple or 1-based string
Returns: the amp readout areas Return type: list/(tuple or string)
-
ao_seeing()[source]¶ Returns an estimate of the natural seeing as calculated from the adaptive optics systems.
Returns: AO estimate of the natural seeing Return type: float
-
array_name()[source]¶ Returns the name of each array
Returns: the array names Return type: list of str/str
-
array_section(pretty=False)[source]¶ Returns the section covered by the array(s) relative to the detector frame. For example, this can be the position of multiple amps read within a CCD. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of extension(s) using Python slice values
- str/list of str – Position of extension(s) using an IRAF section format (1-based)
-
azimuth()[source]¶ Returns the azimuth of the telescope, in degrees
Returns: azimuth Return type: float
-
calibration_key()[source]¶ Returns an object to be used as a key in the Calibrations dict. Multiple ADs can share a key but there can be only one of each type of calibration for each key. data_label() is the default. “_stack” is removed to avoid making a new request for a stacked frame, which will need the same calibration as the original.
Returns: identifier Return type: string
-
camera(stripID=False, pretty=False)[source]¶ Returns the name of the camera. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the camera with or without the component ID.
Return type:
-
cass_rotator_pa()[source]¶ Returns the position angle of the Cassegrain rotator, in degrees.
Returns: Position angle of the Cassegrain rotator. Return type: float
-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
coadds()[source]¶ Returns the number of co-adds used for the observation.
Returns: Number of co-adds. Return type: int
-
data_label()[source]¶ Returns the data label of an observation.
Returns: the observation’s data label Return type: str
-
data_section(pretty=False)[source]¶ Returns the rectangular section that includes the pixels that would be exposed to light. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Location of the pixels exposed to light using Python slice values.
- string or list of strings – Location of the pixels exposed to light using an IRAF section format (1-based).
-
dec()[source]¶ Returns the Declination of the center of the field, in degrees.
Returns: declination in degrees Return type: float
-
decker(stripID=False, pretty=False)[source]¶ Returns the name of the decker. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the decker with or without the component ID.
Return type:
-
detector_name(pretty=False)[source]¶ Returns the name of the detector
Returns: the detector name Return type: str
-
detector_roi_setting()[source]¶ Returns the ROI setting. Most instruments don’t allow this to be changed, so at the Gemini level it just returns ‘Fixed’
Returns: Name of the ROI setting used, ie, “Fixed” Return type: str
-
detector_rois_requested()[source]¶ Returns the ROIs requested. Since most instruments don’t have selectable ROIs, it returns None at the Gemini level
Returns: None Return type: NoneType
-
detector_section(pretty=False)[source]¶ Returns the section covered by the detector relative to the whole mosaic of detectors. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of the detector using Python slice values.
- string or list of strings – Position of the detector using an IRAF section format (1-based).
-
detector_x_bin()[source]¶ Returns the detector binning in the x-direction
Returns: The detector binning Return type: int
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_bin()[source]¶ Returns the detector binning in the y-direction
Returns: The detector binning Return type: int
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser. The “disperser” is a combination of all the dispersing elements along the light path.
The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the disperser with or without the component ID.
Return type:
-
dispersion(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the dispersion in meters per pixel as a list (one value per extension) or a float if used on a single-extension slice. It is possible to control the units of wavelength using the input arguments.
Parameters: Returns: The dispersion(s)
Return type: list/float
-
dispersion_axis()[source]¶ Returns the axis along which the light is dispersed.
Returns: Dispersion axis. Return type: int
-
effective_wavelength(output_units=None)[source]¶ Returns the wavelength representing the bandpass or the spectrum. For imaging data this normally is the wavelength at the center of the bandpass as defined by the filter used. For spectra, this is the central wavelength. The returned value is in meters.
This descriptor makes uses of a lookup table to associate filters with their effective_wavelength.
Returns: Wavelength representing the bandpass or the spectrum coverage. Return type: float
-
elevation()[source]¶ Returns the elevation of the telescope, in degrees
Returns: elevation Return type: float
-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: Exposure time. Return type: float
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
focal_plane_mask(stripID=False, pretty=False)[source]¶ Returns the name of the focal plane mask. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the focal plane mask with or without the component ID.
Return type:
-
gain()[source]¶ Returns the gain (electrons/ADU) for each extension
Returns: Gains used for the observation Return type: list of floats/float
-
gain_setting()[source]¶ Returns the gain setting for this observation (e.g., ‘high’, ‘low’)
Returns: the gain setting Return type: str
-
gcal_lamp()[source]¶ Returns the name of the GCAL lamp being used, or “Off” if no lamp is in used. This applies to flats and arc observations when a lamp is used. For other types observation, None is returned.
Returns: Name of the GCAL lamp being used, or “Off” if not in use. Return type: str
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument and mode of observation will have its own rules.
At the Gemini class level, the default is to group by the Gemini observation ID.
Returns: A group ID for compatible data. Return type: str
-
instrument(generic=False)[source]¶ Returns the name of the instrument making the observation
Parameters: generic (boolean) – If set, don’t specify the specific instrument if there are clones (but that is handled by the instrument-level descriptors) Returns: instrument name Return type: str
-
is_ao()[source]¶ Tells whether or not the data was taken with adaptive optics.
Returns: True if the data is AO, False otherwise. Return type: bool
-
is_coadds_summed()[source]¶ Tells whether or not the co-adds have been summed. If not, they have been averaged.
At the Gemini level, this descriptor is hardcoded to True as it is the default at the observatory.
Returns: True if the data has been summed. False if it has been averaged. Return type: bool
-
is_in_adu()[source]¶ Tells whether the data are in ADU (likely to be superseded by use of NDData’s unit attribute)
Returns: True if the data are in ADU Return type: bool
-
local_time()[source]¶ Returns the local time stored at the time of the observation.
Returns: Local time of the observation. Return type: datetime.datetime.time()
-
lyot_stop(stripID=False, pretty=False)[source]¶ Returns the Lyot stop used for the observation
Parameters: Returns: Lyot stop used for the observation
Return type:
-
mdf_row_id()[source]¶ Returns row ID from the MDF (Mask Definition File) table associated with the spectrum. Applies to “cut” MOS or X-dispersed data.
Returns: Row of the MDF associated with the extension. Return type: int
-
nominal_atmospheric_extinction()[source]¶ Returns the nominal atmospheric extinction at observation airmass and bandpass.
Returns: Nominal atmospheric extinction from model. Return type: float
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal photometric zeropoint (i.e., magnitude corresponding to 1 pixel count) for each extension
Returns: Photometric zeropoint Return type: float/list of floats
-
non_linear_level()[source]¶ Returns the level at which the data become non-linear, in ADU. This is expected to be overridden by the individual instruments, so at the Gemini level it returns the values of the NONLINEA keywords (or None)
Returns: non-linearity level level in ADU Return type: int/list
-
observation_class()[source]¶ Returns the class of an observation, e.g., ‘science’, ‘acq’, ‘dayCal’.
Returns: the observation class Return type: str
-
observation_epoch()[source]¶ Returns the observation’s epoch.
Returns: the observation’s epoch Return type: str
-
observation_id()[source]¶ Returns the ID of an observation.
Returns: the observation ID Return type: str
-
observation_type()[source]¶ Returns the type of an observation, e.g., ‘OBJECT’, ‘FLAT’, ‘ARC’.
Returns: the observation type Return type: str
-
overscan_section(pretty=False)[source]¶ Returns the section covered by the overscan regions relative to the detector frame. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array. If more than one array, the tuples/strings are return in a list. Otherwise, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of extension(s) using Python slice values
- str/list of str – Position of extension(s) using an IRAF section format (1-based)
-
pixel_scale()[source]¶ Returns the image scale in arcseconds per pixel, as an average over the extensions
Returns: the pixel scale Return type: float
-
program_id()[source]¶ Returns the ID of the program the observation was taken for
Returns: the program ID Return type: str
-
pupil_mask(stripID=False, pretty=False)[source]¶ Returns the name of the focal plane mask. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the focal plane mask with or without the component ID.
Return type:
-
qa_state()[source]¶ Returns the Gemini quality assessment flags.
Returns: Gemini quality assessment flags. Return type: str
-
ra()[source]¶ Returns the Right Ascension of the center of the field, in degrees.
Returns: right ascension in degrees Return type: float
-
raw_bg()[source]¶ Returns the BG percentile band of the observation. BG refers to the sky/background brightness.
Returns: BG percentile band of the observation. Return type: str
-
raw_cc()[source]¶ Returns the CC percentile band of the observation. CC refers to the cloud coverage.
Returns: CC percentile band of the observation. Return type: str
-
raw_iq()[source]¶ Returns the IQ percentile band of the observation. IQ refers to the image quality or seeing.
Returns: IQ percentile band of the observation. Return type: str
-
raw_wv()[source]¶ Returns the WV percentile band of the observation. WV refers to the water vapor.
Returns: WV percentile band of the observation. Return type: str
-
read_mode()[source]¶ Returns the readout mode used for the observation
Returns: the read mode used Return type: str
-
read_noise()[source]¶ Returns the read noise in electrons for each extension. A list is returned unless called on a single-extension slice, when a float
Returns: the read noise Return type: float/list of floats
-
read_speed_setting()[source]¶ Returns the read speed setting for the observation
Returns: the read speed setting Return type: str
-
requested_bg()[source]¶ Returns the BG percentile band requested by the PI. BG refers to the sky/background brightness.
Returns: BG percentile band requested by the PI. Return type: str
-
requested_cc()[source]¶ Returns the CC percentile band requested by the PI. CC refers to the cloud coverage.
Returns: CC percentile band requested by the PI. Return type: str
-
requested_iq()[source]¶ Returns the IQ percentile band requested by the PI. IQ refers to the image quality or seeing.
Returns: IQ percentile band requested by the PI. Return type: str
-
requested_wv()[source]¶ Returns the WV percentile band requested by the PI. WV refers to the water vapor.
Returns: WV percentile band requested by the PI. Return type: str
-
saturation_level()[source]¶ Returns the saturation level of the data, in ADU. This is expected to be overridden by the individual instruments, so at the Gemini level it returns the values of the SATLEVEL keywords (or None)
Returns: saturation level in ADU Return type: list/float
-
slit()[source]¶ Returns the name of the entrance slit used for the observation
Returns: the slit name Return type: str
-
target_dec(offset=False, pm=True, icrs=False)[source]¶ Returns the Declination of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Declination of the target in degrees.
Return type:
-
target_ra(offset=False, pm=True, icrs=False)[source]¶ Returns the Right Ascension of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Right Ascension of the target in degrees.
Return type:
-
telescope_x_offset()[source]¶ Returns the telescope offset along the telescope x-axis, in arcseconds.
Returns: the telescope offset along the telescope x-axis (arcseconds) Return type: float
-
telescope_y_offset()[source]¶ Returns the telescope offset along the telescope y-axis, in arcseconds.
Returns: the telescope offset along the telescope y-axis (arcseconds) Return type: float
-
ut_date()[source]¶ Returns the UT date of the observation as a datetime object.
Returns: UT date. Return type: datetime.datetime
-
ut_datetime(strict=False, dateonly=False, timeonly=False)[source]¶ Returns the UT date and/or time of the observation as a datetime or date or time object.
Parameters: Returns: UT date and/or time
Return type: datetime.datetime / datetime.date / datetime.time
-
ut_time()[source]¶ Returns the UT time of the observation as a datetime object.
Returns: UT time. Return type: datetime.datetime
-
wavefront_sensor()[source]¶ Returns the name of the wavefront sensor used for the observation. If more than one is being used, the names will be joined with ‘&’.
Returns: Name of the wavefront sensor. Return type: str
-
wavelength_band()[source]¶ Returns the name of the bandpass of the observation. This is just to broadly know what type of data one is working with, eg. K band, H band, B band, etc.
Returns: Name of the bandpass. Return type: str
-
wcs_dec()[source]¶ Returns the Declination of the center of the field based on the WCS rather than the DEC header keyword.
Returns: declination in degrees Return type: float
-
gemini_instruments.gmos package¶
-
class
gemini_instruments.gmos.AstroDataGmos(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
amp_read_area()[source]¶ Returns a list of amplifier read areas, one per extension, made by combining the amplifier name and detector section. Or returns a string if called on a single-extension slice.
Returns: read_area of each extension Return type: list/str
-
array_name()[source]¶ Returns a list of the names of the arrays of the extensions, or a string if called on a single-extension slice
Returns: names of the arrays Return type: list/str
-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or specified units
Parameters: Returns: The central wavelength setting
Return type:
-
detector_name(pretty=False)[source]¶ Returns the name(s) of the detector(s), from the PHU DETID keyword. Calling with pretty=True will provide a single descriptive string.
Parameters: pretty (bool) – If True, return a single descriptive string Returns: detector name Return type: str
-
detector_roi_setting()[source]¶ Looks at the first ROI and returns a descriptive string describing it These are more or less the options in the OT
Returns: Name of the ROI setting used or “Custom” if the ROI doesn’t match “Undefined” if there’s no ROI in the header Return type: str
-
detector_rois_requested()[source]¶ Returns a list of ROIs, as tuples in a 1-based inclusive (IRAF-like) format (x1, x2, y1, y2), in physical (unbinned) pixels.
Returns: Return type: list of tuples, one per ROI
-
detector_x_bin()[source]¶ Returns the detector binning in the x-direction
Returns: The detector binning Return type: int
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_bin()[source]¶ Returns the detector binning in the y-direction
Returns: The detector binning Return type: int
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser used for the observation. In GMOS, the disperser is a grating.
Parameters: Returns: name of the grating
Return type:
-
dispersion(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the dispersion in meters per binned pixel as a list (one value per extension) or a float if used on a single-extension slice. It is possible to control the units of wavelength using the input arguments.
Parameters: Returns: The dispersion(s)
Return type: list/float
-
dispersion_axis()[source]¶ Returns the axis along which the light is dispersed.
Returns: Dispersion axis. Return type: (list of) int (1)
-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: Exposure time. Return type: float
-
focal_plane_mask(stripID=False, pretty=False)[source]¶ Returns the name of the focal plane mask.
Parameters: Returns: The name of the focal plane mask
Return type:
-
gain()[source]¶ Returns the gain (electrons/ADU) for each extension
Returns: Gains used for the observation Return type: list/float
-
gain_setting()[source]¶ Returns the gain settings of the observation.
Returns: Gain setting Return type: str
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument and mode of observation will have its own rules.
GMOS uses the detector binning, amp_read_area, gain_setting, and read_speed_setting. Flats and twilights have the pretty version of the filter name included. Science data have the pretty filter name and observation_id as well. And spectroscopic data have the grating. Got all that?
Returns: A group ID for compatible data. Return type: str
-
instrument(generic=False)[source]¶ Returns the name of the instrument making the observation
Parameters: generic (boolean) – If set, don’t specify the specific instrument if there are clones (e.g., return “GMOS” rather than “GMOS-N” or “GMOS-S”) Returns: instrument name Return type: str
-
nod_count()[source]¶ Returns a tuple with the number of integrations made in each of the nod-and-shuffle positions
Returns: number of integrations in the A and B positions Return type: tuple
-
nod_offsets()[source]¶ Returns a tuple with the offsets from the default telescope position of the A and B nod-and-shuffle positions (in arcseconds)
Returns: offsets in arcseconds Return type: tuple
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal zeropoints (i.e., the magnitude corresponding to a pixel value of 1) for the extensions in an AD object. Zeropoints in table are for electrons, so subtract 2.5*lg(gain) if the data are in ADU
Returns: zeropoint values, one per SCI extension Return type: float/list
-
non_linear_level()[source]¶ Returns the level at which the data become non-linear, in ADU. For GMOS, this is just the saturation level.
Returns: Value(s) at which the data become non-linear Return type: int/list
-
overscan_section(pretty=False)[source]¶ Returns the overscan (or bias) section. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array. If more than one array, the tuples/strings are return in a list. Otherwise, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of the overscan section using Python slice values.
- string or list of strings – Position of the overscan section using an IRAF section format (1-based).
-
pixel_scale()[source]¶ Returns the image scale in arcsec per pixel, accounting for binning
Returns: pixel scale Return type: float
-
read_mode()[source]¶ Returns a string describing the readout mode, which sets the gain and readout speed
Returns: read mode used Return type: str
-
read_noise()[source]¶ Returns the read noise in electrons. Returns a list if multiple extensions, or a float on a single-extension slice.
Returns: read noise Return type: float/list
-
read_speed_setting()[source]¶ Returns the setting for the readout speed (slow or fast)
Returns: the setting for the readout speed Return type: str
-
saturation_level()[source]¶ Returns the saturation level (in ADU)
Returns: saturation level Return type: int/list
-
shuffle_pixels()[source]¶ Returns the number of rows that the charge has been shuffled, in nod-and-shuffle data
Returns: The number of rows by which the charge is shuffled Return type: int
-
-
class
gemini_instruments.gmos.adclass.AstroDataGmos(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
amp_read_area()[source]¶ Returns a list of amplifier read areas, one per extension, made by combining the amplifier name and detector section. Or returns a string if called on a single-extension slice.
Returns: read_area of each extension Return type: list/str
-
array_name()[source]¶ Returns a list of the names of the arrays of the extensions, or a string if called on a single-extension slice
Returns: names of the arrays Return type: list/str
-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or specified units
Parameters: Returns: The central wavelength setting
Return type:
-
detector_name(pretty=False)[source]¶ Returns the name(s) of the detector(s), from the PHU DETID keyword. Calling with pretty=True will provide a single descriptive string.
Parameters: pretty (bool) – If True, return a single descriptive string Returns: detector name Return type: str
-
detector_roi_setting()[source]¶ Looks at the first ROI and returns a descriptive string describing it These are more or less the options in the OT
Returns: Name of the ROI setting used or “Custom” if the ROI doesn’t match “Undefined” if there’s no ROI in the header Return type: str
-
detector_rois_requested()[source]¶ Returns a list of ROIs, as tuples in a 1-based inclusive (IRAF-like) format (x1, x2, y1, y2), in physical (unbinned) pixels.
Returns: Return type: list of tuples, one per ROI
-
detector_x_bin()[source]¶ Returns the detector binning in the x-direction
Returns: The detector binning Return type: int
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_bin()[source]¶ Returns the detector binning in the y-direction
Returns: The detector binning Return type: int
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser used for the observation. In GMOS, the disperser is a grating.
Parameters: Returns: name of the grating
Return type:
-
dispersion(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the dispersion in meters per binned pixel as a list (one value per extension) or a float if used on a single-extension slice. It is possible to control the units of wavelength using the input arguments.
Parameters: Returns: The dispersion(s)
Return type: list/float
-
dispersion_axis()[source]¶ Returns the axis along which the light is dispersed.
Returns: Dispersion axis. Return type: (list of) int (1)
-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: Exposure time. Return type: float
-
focal_plane_mask(stripID=False, pretty=False)[source]¶ Returns the name of the focal plane mask.
Parameters: Returns: The name of the focal plane mask
Return type:
-
gain()[source]¶ Returns the gain (electrons/ADU) for each extension
Returns: Gains used for the observation Return type: list/float
-
gain_setting()[source]¶ Returns the gain settings of the observation.
Returns: Gain setting Return type: str
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument and mode of observation will have its own rules.
GMOS uses the detector binning, amp_read_area, gain_setting, and read_speed_setting. Flats and twilights have the pretty version of the filter name included. Science data have the pretty filter name and observation_id as well. And spectroscopic data have the grating. Got all that?
Returns: A group ID for compatible data. Return type: str
-
instrument(generic=False)[source]¶ Returns the name of the instrument making the observation
Parameters: generic (boolean) – If set, don’t specify the specific instrument if there are clones (e.g., return “GMOS” rather than “GMOS-N” or “GMOS-S”) Returns: instrument name Return type: str
-
nod_count()[source]¶ Returns a tuple with the number of integrations made in each of the nod-and-shuffle positions
Returns: number of integrations in the A and B positions Return type: tuple
-
nod_offsets()[source]¶ Returns a tuple with the offsets from the default telescope position of the A and B nod-and-shuffle positions (in arcseconds)
Returns: offsets in arcseconds Return type: tuple
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal zeropoints (i.e., the magnitude corresponding to a pixel value of 1) for the extensions in an AD object. Zeropoints in table are for electrons, so subtract 2.5*lg(gain) if the data are in ADU
Returns: zeropoint values, one per SCI extension Return type: float/list
-
non_linear_level()[source]¶ Returns the level at which the data become non-linear, in ADU. For GMOS, this is just the saturation level.
Returns: Value(s) at which the data become non-linear Return type: int/list
-
overscan_section(pretty=False)[source]¶ Returns the overscan (or bias) section. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array. If more than one array, the tuples/strings are return in a list. Otherwise, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of the overscan section using Python slice values.
- string or list of strings – Position of the overscan section using an IRAF section format (1-based).
-
pixel_scale()[source]¶ Returns the image scale in arcsec per pixel, accounting for binning
Returns: pixel scale Return type: float
-
read_mode()[source]¶ Returns a string describing the readout mode, which sets the gain and readout speed
Returns: read mode used Return type: str
-
read_noise()[source]¶ Returns the read noise in electrons. Returns a list if multiple extensions, or a float on a single-extension slice.
Returns: read noise Return type: float/list
-
read_speed_setting()[source]¶ Returns the setting for the readout speed (slow or fast)
Returns: the setting for the readout speed Return type: str
-
saturation_level()[source]¶ Returns the saturation level (in ADU)
Returns: saturation level Return type: int/list
-
shuffle_pixels()[source]¶ Returns the number of rows that the charge has been shuffled, in nod-and-shuffle data
Returns: The number of rows by which the charge is shuffled Return type: int
-
gemini_instruments.gnirs package¶
-
class
gemini_instruments.gnirs.AstroDataGnirs(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
array_section(pretty=False)[source]¶ Returns the section covered by the array(s) relative to the detector frame. For example, this can be the position of multiple amps read within a CCD. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of extension(s) using Python slice values
- string or list of strings – Position of extension(s) using an IRAF section format (1-based)
-
data_section(pretty=False)[source]¶ Returns the rectangular section that includes the pixels that would be exposed to light. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Location of the pixels exposed to light using Python slice values.
- string or list of strings – Location of the pixels exposed to light using an IRAF section format (1-based).
-
dec()[source]¶ Returns the Declination of the center of the field in degrees. Uses the Dec derived from the WCS, unless it is wildly different from the target Dec stored in the headers (with telescope offset and in ICRS). When that’s the case the target Dec is used.
Returns: Declination of the center of the field in degrees. Return type: float
-
detector_section(pretty=False)[source]¶ Returns the section covered by the detector relative to the whole mosaic of detectors. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of the detector using Python slice values.
- string or list of strings – Position of the detector using an IRAF section format (1-based).
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser group as the name of the grating and of the prims joined with ‘&’, unless the acquisition mirror is in the beam, then returns the string “MIRROR”. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The disperser group, as grism&prism, with or without the component ID.
Return type:
-
focal_plane_mask(stripID=False, pretty=False)[source]¶ Returns the name of the focal plane mask group as the slit and the decker joined with ‘&’, or as a shorter (pretty) version. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the focal plane mask with or without the component ID.
Return type:
-
gain()[source]¶ Returns the gain used for the observation. This is read from a lookup table using the read_mode and the well_depth.
Returns: Gain used for the observation. Return type: float
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument, mode of observation, and data type will have its own rules.
Returns: A group ID for compatible data. Return type: str
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal photometric zeropoint for the observation. This value is obtained from a lookup table based on gain, the camera used, and the filter used.
Returns: The nominal photometric zeropoint as a magnitude. Return type: float
-
non_linear_level()[source]¶ Returns the level at which the array becomes non-linear. The return units are ADUs. A lookup table is used and the value is based on read_mode, well_depth_setting, and saturation_level.
Returns: Level in ADU at which the non-linear regime starts. Return type: int/list
-
pixel_scale()[source]¶ Returns the pixel scale in arc seconds. GNIRS pixel scale is determined soley by the camera used, long or short, regardless of color band (red|blue).
GNIRS instrument page,
Short camera (0.15”/pix) – lookup.pixel_scale_shrt Long camera (0.05”/pix) – lookup.pixel_scale_long
Returns: Pixel scale in arcsec Return type: <float>, Raises: ValueError– If ‘camera’ is neither short nor long, it is unrecognized.
-
ra()[source]¶ Returns the Right Ascension of the center of the field in degrees. Uses the RA derived from the WCS, unless it is wildly different from the target RA stored in the headers (with telescope offset and in ICRS). When that’s the case the target RA is used.
Returns: Right Ascension of the target in degrees. Return type: float
-
read_mode()[source]¶ Returns the read mode for the observation. Uses a lookup table indexed on the number of non-destructive read pairs (LNRS) and the number of digital averages (NDAVGS)
Returns: Read mode for the observation. Return type: str
-
read_noise()[source]¶ Returns the detector read noise, in electrons. A lookup table indexed on read_mode and well_depth_setting is used to retrieve the read noise.
Returns: Detector read noise in electrons. Return type: float
-
saturation_level()[source]¶ Returns the saturation level or the observation, in ADUs. A lookup table indexed on read_mode and well_depth_setting is used to retrieve the saturation level.
Returns: Saturation level in ADUs. Return type: int/list
-
-
gemini_instruments.gnirs.tests.test_gnirs.ad(request)[source]¶ Fixture that will download a file from specified as a test parameter, open it as an AstroData object and return it.
Parameters: request (fixture) – Pytest built-in fixture containing information about the parent test. Returns: Raw file downloaded from the archive and cached locally. Return type: AstroData
-
gemini_instruments.gnirs.tests.test_gnirs.test_descriptor_matches_type(ad, descriptor, expected_type)[source]¶
-
gemini_instruments.gnirs.tests.test_gnirs.test_ra_and_dec_always_returns_float(ad, monkeypatch)[source]¶ Tests that the get the RA/DEC coordinates using descriptors.
Parameters: ad (fixture) – Custom fixture that downloads and opens the input file.
-
gemini_instruments.gnirs.tests.test_gnirs.test_ra_and_dec_wcs_fallback(ad, monkeypatch)[source]¶ Tests that the get the RA/DEC coordinates using descriptors when the WCS coordinate mapping fails
Parameters: ad (fixture) – Custom fixture that downloads and opens the input file.
-
class
gemini_instruments.gnirs.adclass.AstroDataGnirs(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
array_section(pretty=False)[source]¶ Returns the section covered by the array(s) relative to the detector frame. For example, this can be the position of multiple amps read within a CCD. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of extension(s) using Python slice values
- string or list of strings – Position of extension(s) using an IRAF section format (1-based)
-
data_section(pretty=False)[source]¶ Returns the rectangular section that includes the pixels that would be exposed to light. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Location of the pixels exposed to light using Python slice values.
- string or list of strings – Location of the pixels exposed to light using an IRAF section format (1-based).
-
dec()[source]¶ Returns the Declination of the center of the field in degrees. Uses the Dec derived from the WCS, unless it is wildly different from the target Dec stored in the headers (with telescope offset and in ICRS). When that’s the case the target Dec is used.
Returns: Declination of the center of the field in degrees. Return type: float
-
detector_section(pretty=False)[source]¶ Returns the section covered by the detector relative to the whole mosaic of detectors. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of the detector using Python slice values.
- string or list of strings – Position of the detector using an IRAF section format (1-based).
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser group as the name of the grating and of the prims joined with ‘&’, unless the acquisition mirror is in the beam, then returns the string “MIRROR”. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The disperser group, as grism&prism, with or without the component ID.
Return type:
-
focal_plane_mask(stripID=False, pretty=False)[source]¶ Returns the name of the focal plane mask group as the slit and the decker joined with ‘&’, or as a shorter (pretty) version. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the focal plane mask with or without the component ID.
Return type:
-
gain()[source]¶ Returns the gain used for the observation. This is read from a lookup table using the read_mode and the well_depth.
Returns: Gain used for the observation. Return type: float
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument, mode of observation, and data type will have its own rules.
Returns: A group ID for compatible data. Return type: str
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal photometric zeropoint for the observation. This value is obtained from a lookup table based on gain, the camera used, and the filter used.
Returns: The nominal photometric zeropoint as a magnitude. Return type: float
-
non_linear_level()[source]¶ Returns the level at which the array becomes non-linear. The return units are ADUs. A lookup table is used and the value is based on read_mode, well_depth_setting, and saturation_level.
Returns: Level in ADU at which the non-linear regime starts. Return type: int/list
-
pixel_scale()[source]¶ Returns the pixel scale in arc seconds. GNIRS pixel scale is determined soley by the camera used, long or short, regardless of color band (red|blue).
GNIRS instrument page,
Short camera (0.15”/pix) – lookup.pixel_scale_shrt Long camera (0.05”/pix) – lookup.pixel_scale_long
Returns: Pixel scale in arcsec Return type: <float>, Raises: ValueError– If ‘camera’ is neither short nor long, it is unrecognized.
-
ra()[source]¶ Returns the Right Ascension of the center of the field in degrees. Uses the RA derived from the WCS, unless it is wildly different from the target RA stored in the headers (with telescope offset and in ICRS). When that’s the case the target RA is used.
Returns: Right Ascension of the target in degrees. Return type: float
-
read_mode()[source]¶ Returns the read mode for the observation. Uses a lookup table indexed on the number of non-destructive read pairs (LNRS) and the number of digital averages (NDAVGS)
Returns: Read mode for the observation. Return type: str
-
read_noise()[source]¶ Returns the detector read noise, in electrons. A lookup table indexed on read_mode and well_depth_setting is used to retrieve the read noise.
Returns: Detector read noise in electrons. Return type: float
-
saturation_level()[source]¶ Returns the saturation level or the observation, in ADUs. A lookup table indexed on read_mode and well_depth_setting is used to retrieve the saturation level.
Returns: Saturation level in ADUs. Return type: int/list
-
-
class
gemini_instruments.gnirs.lookup.Config(mdf, offsetsection, pixscale, mode)¶ Bases:
tuple-
mdf¶ Alias for field number 0
-
mode¶ Alias for field number 3
-
offsetsection¶ Alias for field number 1
-
pixscale¶ Alias for field number 2
-
-
gemini_instruments.gnirs.lookup.DetectorConfig¶
gemini_instruments.gpi package¶
-
class
gemini_instruments.gpi.AstroDataGpi(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
dec()[source]¶ Returns the Declination of the center of the field in degrees. It coincides with the position of the target, so that is used since the WCS in GPI data is completely bogus. For code re-used, use target_dec() if you really want the position of the target rather than the center of the field.
Returns: declination in degrees Return type: float
-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: Exposure time. Return type: float
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If ‘pretty’ is True, ‘IFSFILT’ is stripped from the start of the name.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
classmethod
load(source)[source]¶ Implementation of the abstract method load.
It takes an HDUList and returns a fully instantiated AstroData instance.
-
ra()[source]¶ Returns the Right Ascension of the center of the field in degrees. It coincides with the position of the target, so that is used since the WCS in GPI data is completely bogus. For code re-used, use target_ra() if you really want the position of the target rather than the center of the field.
Returns: right ascension in degrees Return type: float
-
-
class
gemini_instruments.gpi.adclass.AstroDataGpi(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
dec()[source]¶ Returns the Declination of the center of the field in degrees. It coincides with the position of the target, so that is used since the WCS in GPI data is completely bogus. For code re-used, use target_dec() if you really want the position of the target rather than the center of the field.
Returns: declination in degrees Return type: float
-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: Exposure time. Return type: float
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If ‘pretty’ is True, ‘IFSFILT’ is stripped from the start of the name.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
classmethod
load(source)[source]¶ Implementation of the abstract method load.
It takes an HDUList and returns a fully instantiated AstroData instance.
-
ra()[source]¶ Returns the Right Ascension of the center of the field in degrees. It coincides with the position of the target, so that is used since the WCS in GPI data is completely bogus. For code re-used, use target_ra() if you really want the position of the target rather than the center of the field.
Returns: right ascension in degrees Return type: float
-
gemini_instruments.graces package¶
-
class
gemini_instruments.graces.AstroDataGraces(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
dec()[source]¶ Returns the Declination of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_dec() if you really want the position of the target rather than the center of the field.
Returns: declination in degrees Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser. For GRACES, this is always “GRACES”.
Parameters: Returns: The name of the disperser, “GRACES”.
Return type:
-
ra()[source]¶ Returns the Right Ascension of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_ra() if you really want the position of the target rather than the center of the field.
Returns: right ascension in degrees Return type: float
-
-
class
gemini_instruments.graces.adclass.AstroDataGraces(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
dec()[source]¶ Returns the Declination of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_dec() if you really want the position of the target rather than the center of the field.
Returns: declination in degrees Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser. For GRACES, this is always “GRACES”.
Parameters: Returns: The name of the disperser, “GRACES”.
Return type:
-
ra()[source]¶ Returns the Right Ascension of the center of field in degrees. Since a fiber is used it coincides with the position of the target. For code re-used, use target_ra() if you really want the position of the target rather than the center of the field.
Returns: right ascension in degrees Return type: float
-
gemini_instruments.gsaoi package¶
-
class
gemini_instruments.gsaoi.AstroDataGsaoi(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
array_name()[source]¶ Returns a list of the array names of each extension
Returns: names of the arrays Return type: list/str
-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
gain()[source]¶ Returns the gain (electrons/ADU) of the extensions
Returns: gain (e/ADU) Return type: list/float
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument and mode of observation will have its own rules.
Returns: A group ID for compatible data Return type: str
-
is_coadds_summed()[source]¶ Tells whether or not the co-adds have been summed. If not, they have been averaged. GSAOI averages them.
Returns: True if the data has been summed. False if it has been averaged. Return type: bool
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal zeropoints (i.e., the magnitude corresponding to a pixel value of 1) for the extensions in an AD object. Zeropoints in table are for electrons, so subtract 2.5*lg(gain) if the data are in ADU
Returns: zeropoint values, one per SCI extension Return type: float/list
-
non_linear_level()[source]¶ Returns the level at which the data become non-linear, in ADU.
Returns: Value at which the data become non-linear Return type: int/list
-
nonlinearity_coeffs()[source]¶ For each extension, return a tuple (a0,a1,a2) of coefficients such that the linearized counts are a0 + a1*c _ a2*c^2 for raw counts c
Returns: coefficients Return type: tuple/list
-
read_noise()[source]¶ Returns the read noise of each extension in electrons, as a float or a list of floats
Returns: read noise in electrons Return type: float/list
-
read_speed_setting()[source]¶ Returns a string describing the read speed setting, as used in the OT
Returns: read speed setting Return type: str
-
saturation_level()[source]¶ Returns the saturation level in ADU for each extension, as a list or a single value
Returns: saturation level in ADU Return type: int/list
-
-
class
gemini_instruments.gsaoi.adclass.AstroDataGsaoi(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
array_name()[source]¶ Returns a list of the array names of each extension
Returns: names of the arrays Return type: list/str
-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
gain()[source]¶ Returns the gain (electrons/ADU) of the extensions
Returns: gain (e/ADU) Return type: list/float
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument and mode of observation will have its own rules.
Returns: A group ID for compatible data Return type: str
-
is_coadds_summed()[source]¶ Tells whether or not the co-adds have been summed. If not, they have been averaged. GSAOI averages them.
Returns: True if the data has been summed. False if it has been averaged. Return type: bool
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal zeropoints (i.e., the magnitude corresponding to a pixel value of 1) for the extensions in an AD object. Zeropoints in table are for electrons, so subtract 2.5*lg(gain) if the data are in ADU
Returns: zeropoint values, one per SCI extension Return type: float/list
-
non_linear_level()[source]¶ Returns the level at which the data become non-linear, in ADU.
Returns: Value at which the data become non-linear Return type: int/list
-
nonlinearity_coeffs()[source]¶ For each extension, return a tuple (a0,a1,a2) of coefficients such that the linearized counts are a0 + a1*c _ a2*c^2 for raw counts c
Returns: coefficients Return type: tuple/list
-
read_noise()[source]¶ Returns the read noise of each extension in electrons, as a float or a list of floats
Returns: read noise in electrons Return type: float/list
-
read_speed_setting()[source]¶ Returns a string describing the read speed setting, as used in the OT
Returns: read speed setting Return type: str
-
saturation_level()[source]¶ Returns the saturation level in ADU for each extension, as a list or a single value
Returns: saturation level in ADU Return type: int/list
-
-
class
gemini_instruments.gsaoi.lookup.ArrayProperties(readnoise, gain, welldepth, linlimit, coeffs, nonlinlimit)¶ Bases:
tuple-
coeffs¶ Alias for field number 4
-
gain¶ Alias for field number 1
-
linlimit¶ Alias for field number 3
-
nonlinlimit¶ Alias for field number 5
-
readnoise¶ Alias for field number 0
-
welldepth¶ Alias for field number 2
-
gemini_instruments.hokupaa_quirc package¶
-
class
gemini_instruments.hokupaa_quirc.AstroDataHokupaaQUIRC(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
detector_name(pretty=False)[source]¶ Returns the name of the detector. For HOKUPAA+QUIRC, this is always ‘QUIRC’
Returns: Detector name Return type: <str>
-
filter_name(pretty=False)[source]¶ This descriptor is used to display ‘WaveBand’ in the archive.
Parameters: pretty (<bool>) – This keyword parameter is present for API purposes. It has no effect for this descriptor. Returns: wavelength band substituting for filter_name(pretty=True) Return type: <str>
-
instrument(generic=False)[source]¶ Returns the name of the instrument making the observation
Parameters: generic (<bool>) – Request the generic instrument name, if applicable. Returns: instrument name Return type: <str>
-
observation_type()[source]¶ Returns ‘type’ the observation.
Returns: observation type. Return type: <str>
-
target_dec()[source]¶ Returns the Declination of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Declination of the target in degrees.
Return type:
-
target_ra()[source]¶ Returns the Right Ascension of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Right Ascension of the target in degrees.
Return type:
-
-
class
gemini_instruments.hokupaa_quirc.adclass.AstroDataHokupaaQUIRC(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
detector_name(pretty=False)[source]¶ Returns the name of the detector. For HOKUPAA+QUIRC, this is always ‘QUIRC’
Returns: Detector name Return type: <str>
-
filter_name(pretty=False)[source]¶ This descriptor is used to display ‘WaveBand’ in the archive.
Parameters: pretty (<bool>) – This keyword parameter is present for API purposes. It has no effect for this descriptor. Returns: wavelength band substituting for filter_name(pretty=True) Return type: <str>
-
instrument(generic=False)[source]¶ Returns the name of the instrument making the observation
Parameters: generic (<bool>) – Request the generic instrument name, if applicable. Returns: instrument name Return type: <str>
-
observation_type()[source]¶ Returns ‘type’ the observation.
Returns: observation type. Return type: <str>
-
target_dec()[source]¶ Returns the Declination of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Declination of the target in degrees.
Return type:
-
target_ra()[source]¶ Returns the Right Ascension of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Right Ascension of the target in degrees.
Return type:
-
gemini_instruments.hrwfs package¶
-
class
gemini_instruments.hrwfs.AstroDataHrwfs(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
target_dec()[source]¶ Returns the Declination of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Declination of the target in degrees.
Return type:
-
target_ra()[source]¶ Returns the Right Ascension of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Right Ascension of the target in degrees.
Return type:
-
-
class
gemini_instruments.hrwfs.adclass.AstroDataHrwfs(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
target_dec()[source]¶ Returns the Declination of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Declination of the target in degrees.
Return type:
-
target_ra()[source]¶ Returns the Right Ascension of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Right Ascension of the target in degrees.
Return type:
-
gemini_instruments.igrins package¶
-
class
gemini_instruments.igrins.AstroDataIgrins(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
detector_name(pretty=False)[source]¶ Returns the name of the detector
Returns: Detector name Return type: <str>
-
filter_name(pretty=False)[source]¶ IGRINS has no filters or filter names. But this descriptor is used to display ‘WaveBand’ in the archive. So, IGRINS data needs to “fake it.” wavelength_band() returns a string exactly equal to a call on filter_name(pretty=True).
Parameters: pretty (<bool>) – This keyword parameter is present for API purposes. It has no effect for this descriptor. Returns: wavelength band substituting for filter_name(pretty=True) Return type: <str>
-
instrument(generic=False)[source]¶ Returns the name of the instrument making the observation
Parameters: generic (<bool>) – Request the generic instrument name, if applicable. Returns: instrument name Return type: <str>
-
observation_class()[source]¶ Returns ‘class’ the observation; one of,
‘science’, ‘acq’, ‘projCal’, ‘dayCal’, ‘partnerCal’, ‘acqCal’An ‘acq’ is defined by BAND == ‘S’, where ‘S’ indicates a slit image.
Returns: oclass – One of the above enumerated names for observation class. Return type: <str>
-
observation_type()[source]¶ Returns ‘type’ the observation. For IGRINS, this will be one of,
‘OBJECT’, ‘DARK’, ‘FLAT’, ‘ARC’Returns: otype – Observation type. Return type: <str>
-
target_dec()[source]¶ Returns the Declination of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Declination of the target in degrees.
Return type:
-
target_ra()[source]¶ Returns the Right Ascension of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Right Ascension of the target in degrees.
Return type:
-
-
class
gemini_instruments.igrins.adclass.AstroDataIgrins(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
detector_name(pretty=False)[source]¶ Returns the name of the detector
Returns: Detector name Return type: <str>
-
filter_name(pretty=False)[source]¶ IGRINS has no filters or filter names. But this descriptor is used to display ‘WaveBand’ in the archive. So, IGRINS data needs to “fake it.” wavelength_band() returns a string exactly equal to a call on filter_name(pretty=True).
Parameters: pretty (<bool>) – This keyword parameter is present for API purposes. It has no effect for this descriptor. Returns: wavelength band substituting for filter_name(pretty=True) Return type: <str>
-
instrument(generic=False)[source]¶ Returns the name of the instrument making the observation
Parameters: generic (<bool>) – Request the generic instrument name, if applicable. Returns: instrument name Return type: <str>
-
observation_class()[source]¶ Returns ‘class’ the observation; one of,
‘science’, ‘acq’, ‘projCal’, ‘dayCal’, ‘partnerCal’, ‘acqCal’An ‘acq’ is defined by BAND == ‘S’, where ‘S’ indicates a slit image.
Returns: oclass – One of the above enumerated names for observation class. Return type: <str>
-
observation_type()[source]¶ Returns ‘type’ the observation. For IGRINS, this will be one of,
‘OBJECT’, ‘DARK’, ‘FLAT’, ‘ARC’Returns: otype – Observation type. Return type: <str>
-
target_dec()[source]¶ Returns the Declination of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Declination of the target in degrees.
Return type:
-
target_ra()[source]¶ Returns the Right Ascension of the target in degrees. Optionally, the telescope offsets can be applied. The proper motion can also be applied if requested. Finally, the RA can be converted to ICRS coordinates.
Parameters: Returns: Right Ascension of the target in degrees.
Return type:
-
gemini_instruments.michelle package¶
-
class
gemini_instruments.michelle.AstroDataMichelle(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: Exposure time. Return type: float
-
-
class
gemini_instruments.michelle.adclass.AstroDataMichelle(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: Exposure time. Return type: float
-
gemini_instruments.nici package¶
-
class
gemini_instruments.nici.AstroDataNici(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: exposure time for each extension Return type: float/list of floats
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
NICI has filter names in the extension HDUs, so this can return a list
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type: str/list of str
-
-
class
gemini_instruments.nici.adclass.AstroDataNici(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
exposure_time()[source]¶ Returns the exposure time in seconds.
Returns: exposure time for each extension Return type: float/list of floats
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
NICI has filter names in the extension HDUs, so this can return a list
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type: str/list of str
-
gemini_instruments.nifs package¶
-
class
gemini_instruments.nifs.AstroDataNifs(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
Parameters: Returns: The name of the filter with or without the component ID.
Return type:
-
gain()[source]¶ Returns the gain used for the observation. A lookup table is uses to compare the bias value in the headers to the bias values associate with the various gain settings.
Returns: Gain used for the observation. Return type: float
-
gcal_lamp()[source]¶ Returns the name of the GCAL lamp being used, or “Off” if no lamp is in used. This applies to flats and arc observations when a lamp is used. For other types observation, None is returned.
This overrides the gemini level descriptor, as NIFS has more lamp names than are accommodated by that descriptor function.
Returns: lamps – Name of the GCAL lamp, or “Off” Return type: <str>
-
non_linear_level()[source]¶ Returns the level at which the array becomes non-linear. The return units are ADUs. A lookup table is used. Whether the data has been corrected for non-linearity or not is taken into account. A list is returned unless called on a single-extension slice.
Returns: Level in ADU at which the non-linear regime starts. Return type: int/list
-
pixel_scale()[source]¶ Returns the pixel scale in arc seconds. A lookup table indexed on focal_plane_mask, disperser, and filter_name is used.
Returns: Pixel scale in arcsec. Return type: lfloat
-
read_mode()[source]¶ Returns the read mode for the observation. The read mode is directly associated with the LNRS header keyword value.
Returns: Read mode for the observation. Return type: str
-
read_noise()[source]¶ Returns the detector read noise, in electrons. A lookup table is used. The read noise depends on the gain setting and is affected by the number of coadds and non-destructive pairs. A list is returned unless called on a single-extension slice.
Returns: Detector read noise in electrons. Return type: list/float
-
-
class
gemini_instruments.nifs.adclass.AstroDataNifs(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
Parameters: Returns: The name of the filter with or without the component ID.
Return type:
-
gain()[source]¶ Returns the gain used for the observation. A lookup table is uses to compare the bias value in the headers to the bias values associate with the various gain settings.
Returns: Gain used for the observation. Return type: float
-
gcal_lamp()[source]¶ Returns the name of the GCAL lamp being used, or “Off” if no lamp is in used. This applies to flats and arc observations when a lamp is used. For other types observation, None is returned.
This overrides the gemini level descriptor, as NIFS has more lamp names than are accommodated by that descriptor function.
Returns: lamps – Name of the GCAL lamp, or “Off” Return type: <str>
-
non_linear_level()[source]¶ Returns the level at which the array becomes non-linear. The return units are ADUs. A lookup table is used. Whether the data has been corrected for non-linearity or not is taken into account. A list is returned unless called on a single-extension slice.
Returns: Level in ADU at which the non-linear regime starts. Return type: int/list
-
pixel_scale()[source]¶ Returns the pixel scale in arc seconds. A lookup table indexed on focal_plane_mask, disperser, and filter_name is used.
Returns: Pixel scale in arcsec. Return type: lfloat
-
read_mode()[source]¶ Returns the read mode for the observation. The read mode is directly associated with the LNRS header keyword value.
Returns: Read mode for the observation. Return type: str
-
read_noise()[source]¶ Returns the detector read noise, in electrons. A lookup table is used. The read noise depends on the gain setting and is affected by the number of coadds and non-destructive pairs. A list is returned unless called on a single-extension slice.
Returns: Detector read noise in electrons. Return type: list/float
-
-
class
gemini_instruments.nifs.lookup.Config(mdf, offsetsection, pixscale, mode)¶ Bases:
tuple-
mdf¶ Alias for field number 0
-
mode¶ Alias for field number 3
-
offsetsection¶ Alias for field number 1
-
pixscale¶ Alias for field number 2
-
-
class
gemini_instruments.nifs.lookup.Constants(readnoise, gain, well, linearlimit, coeff1, coeff2, coeff3, nonlinearlimit)¶ Bases:
tuple-
coeff1¶ Alias for field number 4
-
coeff2¶ Alias for field number 5
-
coeff3¶ Alias for field number 6
-
gain¶ Alias for field number 1
-
linearlimit¶ Alias for field number 3
-
nonlinearlimit¶ Alias for field number 7
-
readnoise¶ Alias for field number 0
-
well¶ Alias for field number 2
-
gemini_instruments.niri package¶
-
class
gemini_instruments.niri.AstroDataNiri(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
array_section(pretty=False)[source]¶ Returns the section covered by the array(s) relative to the detector frame. For example, this can be the position of multiple amps read within a CCD. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of extension(s) using Python slice values
- str/list of str – Position of extension(s) using an IRAF section format (1-based)
-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
data_section(pretty=False)[source]¶ Returns the rectangular section that includes the pixels that would be exposed to light. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Location of the pixels exposed to light using Python slice values.
- string or list of strings – Location of the pixels exposed to light using an IRAF section format (1-based).
-
detector_roi_setting()[source]¶ Returns the ROI setting. Most instruments don’t allow this to be changed, so at the Gemini level it just returns ‘Fixed’
Returns: Name of the ROI setting used, ie, “Fixed” Return type: str
-
detector_section(pretty=False)[source]¶ Returns the section covered by the detector relative to the whole mosaic of detectors. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of the detector using Python slice values.
- string or list of strings – Position of the detector using an IRAF section format (1-based).
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the disperser with or without the component ID.
Return type:
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. The component IDs can be removed from the filter names. Alternatively, a single descriptive filter name can be returned, based on a lookup table.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
gain()[source]¶ Returns the gain (electrons/ADU) for each extension
Returns: gain Return type: float/list
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument, mode of observation, and data type will have its own rules.
Returns: A group ID for compatible data. Return type: str
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal photometric zeropoint (i.e., magnitude corresponding to 1 pixel count) for each extension
Returns: Photometric zeropoint Return type: float/list of floats
-
non_linear_level()[source]¶ Returns the ADU level at which the data become non-linear. A list is returned with a value for each extension (i.e., one value for NIRI) unless called on a single-extension slice.
Returns: non-linearity level in ADU Return type: int/list
-
nonlinearity_coeffs()[source]¶ Returns a namedtuple containing the necessary information to perform a nonlinearity correction.
Returns: nonlinearity info (max counts, exptime correction, gamma, eta) Return type: namedtuple/list
-
pupil_mask(stripID=False, pretty=False)[source]¶ Returns the name of the pupil mask used for the observation
Returns: the pupil mask Return type: str
-
read_mode()[source]¶ Returns the readout mode used for the observation. This has one of 3 settings, depending on the number of reads and averages. If these numbers do not conform to a standard setting, ‘Invalid’ is returned
Returns: the read mode used Return type: str
-
read_noise()[source]¶ Returns the read noise in electrons, as a list unless called on a single-extension slice.
Returns: read noise Return type: float/list
-
-
class
gemini_instruments.niri.adclass.AstroDataNiri(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
array_section(pretty=False)[source]¶ Returns the section covered by the array(s) relative to the detector frame. For example, this can be the position of multiple amps read within a CCD. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of extension(s) using Python slice values
- str/list of str – Position of extension(s) using an IRAF section format (1-based)
-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or the specified units
Parameters: Returns: The central wavelength setting
Return type:
-
data_section(pretty=False)[source]¶ Returns the rectangular section that includes the pixels that would be exposed to light. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Location of the pixels exposed to light using Python slice values.
- string or list of strings – Location of the pixels exposed to light using an IRAF section format (1-based).
-
detector_roi_setting()[source]¶ Returns the ROI setting. Most instruments don’t allow this to be changed, so at the Gemini level it just returns ‘Fixed’
Returns: Name of the ROI setting used, ie, “Fixed” Return type: str
-
detector_section(pretty=False)[source]¶ Returns the section covered by the detector relative to the whole mosaic of detectors. If pretty is False, a tuple of 0-based coordinates is returned with format (x1, x2, y1, y2). If pretty is True, a keyword value is returned without parsing as a string. In this format, the coordinates are generally 1-based.
One tuple or string is return per extension/array, in a list. If the method is called on a single slice, the section is returned as a tuple or a string.
Parameters: pretty (bool) – If True, return the formatted string found in the header. Returns: - tuple of integers or list of tuples – Position of the detector using Python slice values.
- string or list of strings – Position of the detector using an IRAF section format (1-based).
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
disperser(stripID=False, pretty=False)[source]¶ Returns the name of the disperser. The component ID can be removed with either ‘stripID’ or ‘pretty’ set to True.
Parameters: Returns: The name of the disperser with or without the component ID.
Return type:
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. The component IDs can be removed from the filter names. Alternatively, a single descriptive filter name can be returned, based on a lookup table.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
gain()[source]¶ Returns the gain (electrons/ADU) for each extension
Returns: gain Return type: float/list
-
group_id()[source]¶ Returns a string representing a group of data that are compatible with each other. This is used when stacking, for example. Each instrument, mode of observation, and data type will have its own rules.
Returns: A group ID for compatible data. Return type: str
-
nominal_photometric_zeropoint()[source]¶ Returns the nominal photometric zeropoint (i.e., magnitude corresponding to 1 pixel count) for each extension
Returns: Photometric zeropoint Return type: float/list of floats
-
non_linear_level()[source]¶ Returns the ADU level at which the data become non-linear. A list is returned with a value for each extension (i.e., one value for NIRI) unless called on a single-extension slice.
Returns: non-linearity level in ADU Return type: int/list
-
nonlinearity_coeffs()[source]¶ Returns a namedtuple containing the necessary information to perform a nonlinearity correction.
Returns: nonlinearity info (max counts, exptime correction, gamma, eta) Return type: namedtuple/list
-
pupil_mask(stripID=False, pretty=False)[source]¶ Returns the name of the pupil mask used for the observation
Returns: the pupil mask Return type: str
-
read_mode()[source]¶ Returns the readout mode used for the observation. This has one of 3 settings, depending on the number of reads and averages. If these numbers do not conform to a standard setting, ‘Invalid’ is returned
Returns: the read mode used Return type: str
-
read_noise()[source]¶ Returns the read noise in electrons, as a list unless called on a single-extension slice.
Returns: read noise Return type: float/list
-
gemini_instruments.oscir package¶
-
class
gemini_instruments.oscir.AstroDataOscir(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
dec()[source]¶ Returns the Declination of the center of the field, in degrees.
Returns: declination in degrees Return type: float
-
-
class
gemini_instruments.oscir.adclass.AstroDataOscir(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
dec()[source]¶ Returns the Declination of the center of the field, in degrees.
Returns: declination in degrees Return type: float
-
gemini_instruments.phoenix package¶
-
class
gemini_instruments.phoenix.AstroDataPhoenix(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
dec()[source]¶ Returns the Declination of the center of the field, in degrees.
Returns: declination in degrees Return type: float
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
ra()[source]¶ Returns the Right Ascension of the center of the field, in degrees.
Returns: right ascension in degrees Return type: float
-
-
class
gemini_instruments.phoenix.adclass.AstroDataPhoenix(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
dec()[source]¶ Returns the Declination of the center of the field, in degrees.
Returns: declination in degrees Return type: float
-
filter_name(stripID=False, pretty=False)[source]¶ Returns the name of the filter(s) used. The component ID can be removed with either ‘stripID’ or ‘pretty’. If a combination of filters is used, the filter names will be join into a unique string with ‘&’ as separator. If ‘pretty’ is True, filter positions such as ‘Open’, ‘Dark’, ‘blank’, and others are removed leaving only the relevant filters in the string.
Parameters: Returns: The name of the filter combination with or without the component ID.
Return type:
-
ra()[source]¶ Returns the Right Ascension of the center of the field, in degrees.
Returns: right ascension in degrees Return type: float
-
gemini_instruments.skycam package¶
-
class
gemini_instruments.skycam.AstroDataSkyCam(provider)[source]¶
-
class
gemini_instruments.skycam.adclass.AstroDataSkyCam(provider)[source]¶
gemini_instruments.texes package¶
-
class
gemini_instruments.texes.AstroDataTexes(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
dec()[source]¶ Returns the Declination of the center of the field, in degrees.
Returns: declination in degrees Return type: float
-
classmethod
load(source)[source]¶ Implementation of the abstract method load.
It takes an HDUList and returns a fully instantiated AstroData instance.
-
-
class
gemini_instruments.texes.adclass.AstroDataTexes(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
dec()[source]¶ Returns the Declination of the center of the field, in degrees.
Returns: declination in degrees Return type: float
-
classmethod
load(source)[source]¶ Implementation of the abstract method load.
It takes an HDUList and returns a fully instantiated AstroData instance.
-
gemini_instruments.trecs package¶
-
class
gemini_instruments.trecs.AstroDataTrecs(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or specified units
Parameters: Returns: The central wavelength setting
Return type:
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
dispersion(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the dispersion in meters per pixel as a list (one value per extension) or a float if used on a single-extension slice. It is possible to control the units of wavelength using the input arguments.
Parameters: Returns: The dispersion(s)
Return type: list/float
-
-
class
gemini_instruments.trecs.adclass.AstroDataTrecs(provider)[source]¶ Bases:
gemini_instruments.gemini.adclass.AstroDataGemini-
central_wavelength(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the central wavelength in meters or specified units
Parameters: Returns: The central wavelength setting
Return type:
-
detector_x_offset()[source]¶ Returns the offset from the reference position in pixels along the positive x-direction of the detector
Returns: The offset in pixels Return type: float
-
detector_y_offset()[source]¶ Returns the offset from the reference position in pixels along the positive y-direction of the detector
Returns: The offset in pixels Return type: float
-
dispersion(asMicrometers=False, asNanometers=False, asAngstroms=False)[source]¶ Returns the dispersion in meters per pixel as a list (one value per extension) or a float if used on a single-extension slice. It is possible to control the units of wavelength using the input arguments.
Parameters: Returns: The dispersion(s)
Return type: list/float
-
Submodules¶
gemini_instruments.common module¶
Structures and functions that can be shared across instrument code.
When should you add something here? Here’s some criteria: the code that belongs in here is not generally useful outside of gemini_instruments, and:
- more than one instrument share the code to override a method that provides default behaviour, meaning that there’s no common ancestor where you can put this; or,
- it doesn’t make sense to put the code in a method, as it doesn’t rely on internal knowledge of a class.
gemini_instruments.gmu module¶
-
gemini_instruments.gmu.convert_units(input_units, input_value, output_units)[source]¶ Parameters: - input_units (string) – the units of the value specified by input_value. Possible values are ‘meters’, ‘micrometers’, ‘nanometers’ and ‘angstroms’.
- input_value (float) – the input value to be converted from the input_units to the output_units
- output_units (string) – the units of the returned value. Possible values are ‘meters’, ‘micrometers’, ‘nanometers’ and ‘angstroms’.
Return type: Returns: the converted value of input_value from input_units to output_units
-
gemini_instruments.gmu.removeComponentID(instr)[source]¶ Remove a component ID from a filter name :param instr: the filter name :type instr: string :rtype: string :return: the filter name with the component ID removed, or None if the input is not a valid string
-
gemini_instruments.gmu.sectionStrToIntList(section)[source]¶ Convert the input section in the form ‘[x1:x2,y1:y2]’ to a tuple in the form (x1 - 1, x2, y1 - 1, y2), where x1, x2, y1 and y2 are integers. The values in the output tuple are converted to use 0-based and non-inclusive indexing, making it compatible with numpy.
Parameters: section (str) – The section (in the form [x1:x2,y1:y2]) to be converted to a tuple. Returns: tuple – non-inclusive in the form (x1 - 1, x2, y1 - 1, y2). Return type: the converted section as a tuple that uses 0-based and