Manual¶

This manual explains how astrolyze can be used to ease reduction, analysis and modification of (radio-)astronomical data and images.

astrolyze¶

I started to develop astrolyze to be able to inter-operate the Programs PyFits, MIRIAD and GILDAS. One reason was that the Gildas task are very cumbersome to script and once scripted, the scripts are not very flexible. Also there are some tasks in GILDAS that are (in my opinion) easier to use than in miriad and vice-versa, due to different sets of features.

However, the real power of astrolyze comes from it’s internal tracking of changes to the most important parameters of the maps (or spectral-files), which are stored directly in the file-names. This principle is based on a naming-convention. An additional databases can be setup so that more informations can be loaded depending on the file-name-keywords.

Naming Convention¶

A Name that follows the ‘Naming Convention’ is for example: M33_30m-HERA_CO21_Ta*_12_cube_regrid.fits

All items MUST be separated by an underscore (_) and HAVE to include at the following properties in this very order:

source
telescope
species (wavelength OR frequency OR line-name)
flux unit
resolution

When opening a map with astrolyze these items are transferred to python variables of the Map class (see below). All additional items separated by underscores are treated as comments. Comments are not transferred to individual internal variables of the map objects but are passed on as a list to the single variable comments.

The last item is followed by the files extension:

.fits -> FITS
.gdf, .mean, .velo, .width, .lmv -> GILDAS
nothing -> MIRIAD (Miriads file format uses directories to store the data.)

Maps that are not following this name convention are not supported. This is to assure that all parts of the program work, since they strongly depend on the parameters passed on by the file-name.

Using the example file-name above, opening this file with astrolyze as follows:

from astrolyze import *
map_ = FitsMap('M33_30m_12CO10_Tmb_12_cube_regrid.fits')

would generate the following variables:

map_.source = 'M33'
map_.telescope = '30m'
map_.species = '12CO10'
map_.fluxUnit = 'Tmb'
map_.resolution = '12'
map_.comments = ['cube', 'regrid']
map_.dataFormat = 'fits'

Using the parameter database with line-names, objects and telescope parameters, that can be edited by the user (see Installation of astrolyze), astrolyze pulls more information about the object, telescope and line emission of the map. When the information is present it generates automatically the following variables:

map_.frequency [Hz]
map_.wavelength [m]
map_.calibrationError
map_.type [Hubble Type]
map_.distance [pc]
map_.vlsr [km/s]
map_.centralPosition [RA, DEC] J2000
map_.pa [degrees]
map_.inclination [degrees]
map_.R25 [kpc]

If not present in the database these variables are set to ‘NaN’ (Not a Number).

Although, all of this information is somewhat redundant to the header information in the files, it has been decided to go that way since unfortunately not all headers are kept up to date and manipulating the file name is easier to do.

Nevertheless, the maps module tries to keep track if a variable that should go into the header of a fits file is changed and up-dates the header subsequently (This is however hard to maintain and not true in all cases, though.).

Last but not least using this name convention has another benefit since it makes the life of your fellow astronomers easier when they have to work with your data since they readily know their most important basic properties.

Modules¶

astrolyze is divided in different modules and classes which can inter-operate with each other and which are:

maps
spectra
sed
functions
lte

In the following I will introduce the individual modules of astrolyze and their functionality.

Not all functions of the individual astrolyze modules will be covered in this manual-page. All functions are documented and can be found HERE TODO. The next sections attempts to show the basis principles, structure and work-flow of astrolyze.

maps¶

The maps module is the heart of the astrolyze package. It provides the framework to work with astronomical images (and spectra). It is able to modify and to track the most important properties of the maps such that they are always fast at hand if needed. Further it contains genuine functions written in python (and pyGildas), alongside wrapper functions to functions and tasks of GILDAS and MIRIAD.

The maps module contains the following modules/Classes itself:

main.Main

fits.FitsMap

gildas.GilsdasMap

miriad.MiriadMap

stack.Stack

tools

main¶

This module contains the class: Main, which is the parent class for all actions not depending on the actual data-type. In principle it is the implementation of the Naming Convention and is not directly used to open a map. All other classes in maps inherit from the Main class, such that it is used any time the other modules of maps are used. Also the Using the sed module uses Main.

Variables created by Main¶

When opening a map with Main variables are created that contain information about the maps and can be used to work with the data. The variables are class attributes. They can be accessed by attaching them to the object with a dot between object and attribute:

object.attribute

In astrolyze the maps that are opened are objects. The information for the variables come from different places:

From naming convention¶

map_name
prefix
source
telescope
species
fluxUnit
resolution
comments
dataFormat

Calculated Values¶

Assuming a Gaussian beam size the following variables are calculates from the resolution keyword.

beamSizeM2       Beam-Size in m^2
beamSizeSterad   Beam-Size in sterad

Known Format endings of the different file types¶

These variables contain a list that contain all strings that are recognized by the system as a valid file name ending (TODO: find the correct name for file ending).

fits_formats
miriad_formats
gildas_formats
class_formats

Warning

These are hard-coded, should be initialized via the cfg/ folder of the package when installing.

Variables loaded from Database¶

As explained in TODO. Astrolyze uses a database to store additional informations about maps. The database is set-up during installation as explained in Installation of astrolyze.

From Line Database¶

Using the species keyword:

frequency  : [GHz]
wavelength : [TODO]

From Galaxy Database¶

Using the source keyword.:

centralPosition : [RA, DEC]
distance : [kpc]
R25 : [kpc TODO]
inclination : [degrees]
vlsr : [km/s]
pa : [degrees]
type :  The Hubble type of the galaxy.

From Calibration Database¶

Using the species and telescope keywords.:

calibrationError

The in-depth documentation of the internal functions can be found here Main.

fits¶

The fits module contains the class FitsMap. This class inherits all functions from Main but adds functionality and methods needed to work with fits data. This class makes use of the python-pyfits package. Please check the pyfits web-page (follow the previous link) for the pyfits documentation.

To open a fits-map do, e.g.

from astrolyze import *
map = FitsMap('M33_30m_12CO10_Tmb_12.fits')

Variables created by FitsMap¶

Opening a Fits map creates, besides the variables discussed in Main the following additional variables specific to the FitsMap:

Variables loaded with pyfits¶

header : a dictionary with the fits-header cards
data : numpy.ndarray containing the data
hdulist : Some fits-files have more than one plane. HDUlist contains all
      planes.

Calculated values¶

Because the fits-header is read via python-pyfits the pixel dimensions are known and thus the pixel-sizes can be caluclated:

pixelSizeM2 : [m^2]
pixelSizeSterad [sterad] .

Known header keywords¶

headerKeywords : A dictionary containing different fits-header keywords that
         are used for the same quantity.

Known names of units¶

The FitsMap class contains the method change_unit which is able to check the conversion that is needed to change to the desired unit. However for this another Unit Naming Convention is needed. The following variables contain lists of valid names for certain variables:

tmb_names
jansky_beam_names
MJy_per_sterad_names
erg_sec_pixel_names
erg_sec_beam_names
jansky_pixel_names
erg_sec_sterad_names
known_units .

Warning

This should also be setup during installation of astrolyze to be able to customize unit-names easily.

Working with Fits Maps¶

Changing Formats¶

Note

Changing formats works the same way in all maps modules.

The loaded fits map can be transformed to the Gildas and Miriad Formats via the methods:

toGildas()
toMiriad()

and from either of the other two Formats to Fits via:

toFits()

This creates a copy of the image in the Gildas, Miriad (or Fits) Format on the disk in the same folder as the actual map. To keep working with the map in the new format one can use:

map = map.toGildas()

to change the out-put folder there are two ways:

1. Set the ``map.prefix`` variable to the new path prior to
   changing the map format as shown above.
2. Give the new path to the function, e.g. map.toGildas(folder='new_path')

Thus e.g.:

map.prefix = 'new_path'
map = map.toGildas()

or:

map = map.toGildas(folder='new_path')

Making use of Pyfits¶

As listed in Variables created by FitsMap a data and a header variable is created. These are a numpy.ndarray of the image data and a dictionary containing the header keywords with their arguments. Thus changing the properties of the fits map and the header variables is straight-forward.

For example you may want to change the units of a map M33_30m_12CO10_Tmb_12.fits that is in main beam temperature to Jansky/beam by multiplying all pixels with the corresponding conversion factor. This can be done via:

from astrolyze import *
map = FitsMap('M33_30m_12CO10_Tmb_12.fits')
conversion_factor = map.flux_conversion()
map.data = map.data * conversion_factor

The conversion factor between the two units is calculated here via flux_conversion please refer to the function fro more details.

Having changed the unit it may be a good idea to change the header variables that stores the actual unit as well as the unit-keyword from the naming convention., this can be done as follows:

from astrolyze import *
map = FitsMap('M33_30m_12CO10_Tmb_12.fits')
print map.header['BUNIT']
map.unit = 'JyB'
map.header['BUNIT'] = 'Jy/beam'

Note

The individual functions in of the FitsMap-class change the header of the Fits file automatically if map properties are changed. At the same time they have access to all fits-header variables if needed.

Finally you may want to save the modified image as a new fits file which can be done with:

map.updateFile()

This creates a file called M33_30m_12CO10_JyB_12.fits

Change Map Units¶

Since it is easy to modify all pixel via python-pyfits the function change_unit that converts units into another is implemented in the FitsMap-class. See the documentation of change_unit for the conversions that are implemented.

Using the information from the “Naming Convention” and the additional information from the database, the code has all information to calculate the conversion factors. And also to decide which conversion is to be applied. Changes are possible between any of the units that are implemented.

Warning

This is not thoroughly tested yet!!

For example the same change of units as in the previous section can be done as follows:

from astrolyze import *
map = FitsMap('M33_30m_12CO10_Tmb_12.fits')
map = map.change_unit('JyB')

Using gildas¶

When Opening a Gildas map with:

from astrolyze import *
map = GildasMap('M33_30m_12CO10_Tmb_12.gdf')  ,

astrolyze uses pyGildas to read some of the header variables and stores them as python variables. The following values are read.

Variables¶

Gildas Specific¶

dimensions
naxis_1 : number of pixels in x-axis.
naxis_2 : number of pixels in y-axis.

crpix_1 : The reference pixel (x-axis).
crval_1 : The coordinate value at crpix_1 [radians].
cdelt_1 : The pixel increment.

crpix_2 : Same as crpix_1 for y-axis.
crval_2 : Same as crval_1 for y-axis.
cdelt_2 : Same as crdelt_1 for y-axis.

ra_coordinate : RA coordinate.
dec_coordinate : DEC coordinate

ra_coordinate : TODO
dec_coordinate : TODO

central_coordinate_degrees : TODO
central_coordinate_equatorial : TODO

Note

If needed more variables can be loaded when opening a Gildas map without problems , so far only those that were needed are implemented.

How is Gildas used by astrolyze¶

Gildas is used in two different ways in Atrolyze:

1. A Gildas script, with a final exit at the end is created and executed via
   the os python package, sending commands to the bash.
2. The pyGildas package is used directly by astrolyze to tun command in SIC.

The first method is mainly used to wrap GREG (and maybe later CLASS) tasks since these are cumbersome to script so far in Gildas. To do so the GildasMap method create an init file and a temporary Greg script that is (normally) deleted after execution. The standard script looks as follows:

exit

Wrapping Gildas Tasks¶

Direc use of pyGildas¶

Using miriad¶

A miriad map is opened with:

from astrolyze import *
map = GildasMap('M33_30m_12CO10_Tmb_12.gdf')  ,

In this mode only the variables created by main are created.

Only the "smooth" function from miriad is implemented in astrolyze see smooth(). When all header variables are set correctly this function is aware of the map units and beam sizes and can calculate the correct scaling that has to be applied after convolution. The way astrolyze is set up the smooth function expects the map to be in units of Jy/beam.

Warning

Miriad could be excluded from astrolyze in the future if the GILDAS smooth wrapper is programmed such that it is aware of different input variables.

Using the stack module¶

The Stack class builds on top of the classes:

Main
FitsMap
GildasMap
MiriadMap

It provides the possibility to load a “stack” of maps inside a folder at once and perform changes on all maps. It’s intention is mainly to provide means to unify maps for further processing. Tasks such as for example pixel-to-pixel comparisons or the creation of temperature-maps from SED-fits needs individual maps to be on the same resolution and/or the same pixel grid.

Using the sed module¶

The module SED makes extensive use of the stack functionality of the maps module...

Using Functions¶

The module functions contains all functions that are not directly related to manipulation of maps or spectra and counter intuitive also all constants used in astrolyze as long as they are not available by the standard python installation (this may not be true however.).

Using LTE¶

References¶

[GILDAS]

http://www.iram.fr/IRAMFR/GILDAS

[MIRIAD]

http://www.atnf.csiro.au/computing/software/miriad/taskindex.html

[python-pyfits]

http://www.stsci.edu/institute/software_hardware/pyfits