aXe-visualization

aXe2web

aXe-spectral extraction

aXe2web

  1. The aim of 'aXe2web'
  2. How 'aXe2web' works
  3. aXe input files
  4. Special input files
    1. CSS file
    2. Selection file

  5. Output
    1. Object pages
    2. Overview page
    3. Index page
    4. Info page
    5. Spectral data

  6. MAN-like Help

1. The aim of 'aXe2web'

The program aXe2web aims to provide a quick look facility for slitless ACS data reduced with aXe. To do that it produces a series of contiguous webpages which show the main results of the reduced data. The main results are the extracted spectra and object information which is derived from the input SExtractor catalogues such as the object brightness and position. With any web-browser those webpages can then be viewed to pick out interesting objects or to reveal flaws in the data reduction. aXe2web is a manageable tool to examine hundreds to thousands of spectra without undue eyestrain.

2. How 'aXe2web' works

A complete overview on aXe2web and all its settings is given below. Here we give only a brief introduction on how aXe2web can be used and emphasize some important points.

Similar to other shell commands aXe2web is invoked with the syntax:

aXe2web [--parameter1 value1] [--parameter2 value2] [--parameter3 value3] ...

In total aXe2web has around 20 different parameters or settings which all have an influence on the content or appearance of the webpages created.
All settings can either be specified on the command line using the above syntax " ... [--parameter_n value_n]" or listed in a separate parameter file. In the parameter file the parameter values must be given in the form "parameter_n=value_n" at the beginning of a line. Empty lines are discarded, and the sign '#' marks a comment which extends until the end of the line. An example parameter file is aXe2web.par.
The name of the parameter file is transferred to aXe2web with the setting "--parfile file".
In case the same setting is given in the parameter file and as a command line setting, the value specified by the latter method takes preference.

The whole group of settings can be divided into a subgroup which addresses the content and another subgroup which addresses the layout of the webpages.

The content group contains settings which are usually mandatory to deliver a complete data set and to provide the proper execution of aXe2web. This group of mandatory settings consists of:

However if the setting only_html=yes (in the parameter file) or --only_html yes (as online setting) is applied, it is assumed that the graphics (stamp images and spectra) already exist from a previous aXe-run. Then only the HTML files are created and the only remaining mandatory setting is sextract_cat.

The layout group of settings exists to allow the user to alter the appearance of the webpages. The layout settings specify for example the wavelength range shown in the spectra, whether the exact location of the source is marked in the direct image stamp or not, give the name of the HTML files or specify a column used to order the objects on the webpages. Layout settings are all non-mandatory. For the layout settings there exist reasonable default values which are used if the according setting is not specified by the user.
For a complete list of all settings look at Section 6 below.

Since most of the processing time is spent on creating the stamp images and graphics files of the spectra, the setting --only_html yes plays an important role. After a first run with --only_html no (default) to create the stamp images and graphic files the setting --only_html yes in subsequent runs allows the re-processing of the data with different layout settings until a decent overall look is found.

3. aXe input files

The aXe input files for aXe2web are generated in a normal aXe reduction of slitless ACS data plus the input SExtractor catalogue for the aXe reduction. In detail those files are: The program aXe2web attempts to create a preview for all entries in the SExtractor catalogue. The cross-identification of objects in the various input files is done using the object numbers of the catalogue. To give an example, the direct image stamp for object 13 from the SExtractor catalogue test.cat is extracted from test.fits using the pixel coordinates given in test.cat. On the webpages the direct stamp image is shown together with a grism stamp image derived from test.STP.fits[BEAM_13A] and the spectra stored in test.SPC.fits[BEAM_13A]

4. Special input files

4a. CSS style sheet

Since version 1.1 aXe2web uses a CSS style sheet to control basic layout features of the generated HTML pages. Instead of using the css style sheet which comes with the aXe2web installation, the user can specify a style sheet which should be used for the HTML pages generated with aXe2web. In this css style sheet the user can give e.g. fonts and background colours and produce nicer HTML pages or HTML pages which comply with the corporate identity of the project.

The most reasonable way to develop an individual css file would be to run aXe2web with the default concerning the css style file. aXe2web then copies the default css file into the output directory. With the default style file as the basis, the user can develop his own style file and give its name in the following aXe2web runs in the according parameter setting ('--css_file').

Figure 1 shows different layouts created by varying the default css style file

object page object page
Figure 1: Different layouts created with css style sheets

4b. Selection file

The webpages produced by aXe2web may contain a large number of objects. Apart from the aXe2web pages which contain all objects it might be desirable to have web pages which cover only objects selected according certain criteria. Creating sub-catalogues from the main SExtractor catalogue can be very tedious, especially since tools to load/modify/save the SExtractor catalogue format are not available.

In these circumstances it is possible to specify, in a so-called selection file , the ID's of the objects which should be on the HTML files created in the aXe2web run. The selection file is a free format ASCII file which lists, either in one or several rows, the ID's of the objects. Within a row the individual ID's must be separated either with blanks, tabs, , , : , ; or |. Lines which start with a # are discarded as comments. A typical selection file might look as:

################
# OB-stars:
#
3
10
65
21
90
#################

or:

################
# z > 5:
#
5 | 1| 101 | 65
#################

The name of the selection file parameter setting is '--sel_file'. On the HTML pages the objects are ordered as in the selection file in case that no catalogue column for ordering was specified.

5. Output

aXe2web produces a contiguous set of linked webpages. The complete set of webpages created in an aXe2web run consists of individual pages of four different kinds. The detailed previews for the objects is given on the object pages.
Some basic information on all objects is comprised in the overview page. To facilitate easy access to all objects the index page offers links to the previews stored on the object pages. The info page lists all setting-value pairs which were used to produce the current webpages.

The filenames of all HTML pages are composed by the expression given with the setting --pagename plus extensions for the different kind of pages ('_pnumber.html' for the object pages, '_over.html', '_index.html', '_info.html' for overview, index and info page, respectively). The setting --overview no restricts aXe2web to making only object pages without overview, index and info pages.

The setting --outputpath specifies the name of a directory where all output files are transferred to. The directory given in the setting is created in case that it does not yet exist. All HTML pages are directly stored in the output directory. The large number of images (image stamps and graphics) are all stored in the directory images within the output directory.
It is strongly recommended to use different output directories for different sets of input files, since file names for the various graphics (image stamps, spectra) are differentiated only by object numbers and not by input file names. For example the filename of the grism stamp image of object number 80 for both SExtractor catalogues 'hdf_n.cat' und 'hdf_s.cat' is 'stampgri80.png'. The stamp images for those different objects would overwrite each other in case that they are directed to the same output directory.

The setting --data_out yes creates for every source displayed on an object page a gnu-zipped file with its spectral data. Links lead from the column 'Obj.no.' on the object pages to the ascii-table. These spectra data is stored in the directory images within the output directory.

5a. Object pages

Figure 2 shows part of an object page. The main part of an object page is a table which shows previews for the objects in the table rows. The header on top of the table and the number of objects per individual object page is controlled by the settings --page_header and --pagesize, respectively.

object page
Figure 2: An object page

The individual columns contain:

5b.Overview page

Figure 3 displays the top of an overview page. In various tables the overview page lists the basic properties of the objects from the object pages.

overview page
Figure 3: An overview page

The content of the columns 'Sequence number', 'Object number', 'Magnitude', 'X-coord','Y-coord', 'RA', 'DEC' correspond to the entries in the columns 'Seq. no.', 'Obj. no.', 'Magnitude' and 'Image coordinates' from the object pages.
Links lead from the columns 'Sequence number' and 'Object number' to the corresponding positions of the objects in the object pages.

5c.Index page

Figure 4 shows a cutout from an index page. The aim of the index page is to provide links to all objects in a table with the catalogue object numbers. This allows an easy navigation to all individual objects.

index page
Figure 4: An index page

5d.Info page

Figure 5 displays the top of an info page. This page lists all settings which were used in the aXe2web run. This helps to characterize a particular aXe preview in case that multiple aXe2web runs with different input files or different settings were done.

info page
Figure 5: An info page

5e.Spectral data

Gnu-zipped files can be written with the spectral data as spectrumID.dat.gz, with ID the catalogue ID number of the object. The content of the files are the columns LAMBDA, COUNT, ERROR, FLUX, FERROR and CONTAM of the corresponding fits-table extension in the SPC-file. Independent of the values given in the setting --lambda_range, which limit the plotted wavelength range, the spectral data files always contain all data stored in the fits-table extension. The first lines of the spectral data of object 3 (file name: spectrum3.dat.gz) are, for example:

#
# Column1: LAMBDA
# Column2: COUNT
# Column3: ERROR
# Column4: FLUX
# Column5: FERROR
# Column6: CONTAM
#
# SPC-file: test_aXe_2.SPC.fits
# beamID: 3
#
5.517961e+03 1.398933e-02 3.520326e-03 3.967839e-18 1.134665e-18 0.000000e+00
5.541973e+03 1.410602e-02 3.498247e-03 3.234150e-18 8.984982e-19 0.000000e+00
5.565973e+03 1.906864e-02 3.511872e-03 3.690782e-18 7.915358e-19 0.000000e+00
5.589962e+03 2.209723e-02 3.524950e-03 3.691613e-18 6.826738e-19 0.000000e+00
5.613973e+03 2.145505e-02 3.508735e-03 3.153157e-18 5.675175e-19 0.000000e+00
5.637967e+03 2.703592e-02 3.464569e-03 3.551702e-18 5.057125e-19 0.000000e+00
5.661968e+03 3.025638e-02 3.450644e-03 3.592323e-18 4.487073e-19 0.000000e+00
5.685981e+03 3.011367e-02 3.425225e-03 3.287617e-18 4.009414e-19 0.000000e+00
5.709965e+03 3.043614e-02 3.416627e-03 3.097178e-18 3.747549e-19 0.000000e+00
5.733973e+03 3.055176e-02 3.455406e-03 2.923181e-18 3.547276e-19 0.000000e+00
5.757950e+03 3.314561e-02 3.444102e-03 2.997677e-18 3.401878e-19 0.000000e+00
...
...
...

6. MAN-like Help


Space Telescope - European Coordinating Facility
Author: Martin Kuemmel (mkuemmel@eso.org)
aXe2web Version 1.2, September 2010

Synopsis:

aXe2web [--parfile file.par] [--setting1 value1] [--setting2 value2] [...] ...

Description:

Task to visualize aXe-output via webpages. Uses as input the SExtractor catalogue and the direct image (aXe-input) as well as the STP- and SPC-file (aXe-output) to display information on the catalogue objects in an HTML file.
For each object a table row is filled with SExtractor data (object-nr and brightness, positional information) a stamp image of the direct image, the 2D stamp image of the grism exposure and the extracted spectra in both, counts and flux.
A large number of settings can be used to influence the displayed information and the appearance of the webpage. The settings can be set with a parameter file or in the command line or a combination of both. If a setting is done in a parameter file and in the command line the setting from the command line has precedence.
Mandatory settings are the SExtractor catalogue and, in case that '--only_html' (see below) is not set, the direct image plus STP-image plus SPC-table. For all other options reasonable default values are taken.

Settings:

--parfilefile specifies 'file' as the parameter file
--sextract_catfile specifies 'file' as the SExtractor catalogue
--direct_image file specifies 'file' as the direct fits image
--stamp_image file specifies 'file' as the STP (STamP) image file. This FITS-file contains the images of the extracted BEAMS
--spectr_table file specifies 'file' as the extracted spectra (SPC) file. This FITS-file contains the extracted spectra of all BEAMS
--outputpath string specifies 'string' as the directory to which all output files are written. While the HTML files are written directly in 'string', all images are stored in the directory 'string'/images. Relative and absolute pathnames are accepted. Default: 'outhtml'
--pagename string the name of the output HTML file. In case that only one file is created, it's name is 'file.html'. If several pages are created their name is 'file_p1.html', 'file_p2.html' ... 'file_pn.html'. Default: 'axe2web'
--page_title string the title in the header of the HTML files (object, overview, info and index pages). This string appears in the bookmarks. Default: 'aXe2web'
--page_header string the page-header which appears on top of each page. In case that blanks should appear in the header, they must be enclosed by " ". Default: the SExtractor catalogue name
--sort_column string if this setting is given, the objects are ordered in ascending order according to their values in the SExtractor column 'string'. If column name is followed by a '+' the value are sorted in increasing order. A '-' marks the desire for decreasing order. Default: no sorting, increasing
--mag_lambda float If the SExtractor catalogue has no column MAG_AUTO, but one or several magnitude columns in the format MAG_F606W or MAG_F850LP (as used in quantitative contamination), the magnitude column with a wavelength closest to the value given in this parameter (in nm) is identified, and all magnitudes displayed on object pages and the overview page are derived from this column. Default: 800.0
--start_objectnum start with the sorted object 'num'. In case that '--sortcolumn' has been given this refers the number refers to the sorted order. Default: 1
--number_objects num display num objects on the webpage(s). In case that '--sortcolumn' has been given 'num' objects from the ordered list are shown (starting from the object specified in '--start_object'). Default: all objects
--pagesize num the number of objects per HTML page. Default: 100
--spectrum_widthnum the width of the 2D stamp image from the grism exposure. Default: 162pix
--directim_width num the width of the direct stamp image. Default: 50 pixels
--lambda_range num,num the lower and upper wavelength cut for the spectra. In case that only one value should be specified, give only one number plus the comma (e.g. '6000,' or ',10000'). Unreasonable values <4000 and >11000 are not accepted, also plotting in descending wavelength is not supported. Default: 5500,10500
--error_bars yes/no enables or disables the error bars in the plots of the object spectra. Default: yes
--mark_sources yes/no enables or disables that sources are marked with a cross in the direct image. Default: yes
--only_html yes/no if set to 'yes', only the HTML files with the objects in the specified order are created, the stamp images and plots are not done. Default: no
--overview yes/no If set to 'yes', the overview, index and info pages are created. The overview page lists basic object properties without graphics. The index page gives links to all objects, and the info page lists all the settings chosen for the aXe2web run. Default: yes
--data_out yes/no If set to 'yes', a gnu-zipped file with the spectral data is created for each source on the object pages. The file is linked to the object ID number in the corresponding row of the object page. All spectral data files are stored in the directory 'data' within the output directory. Default: no
--css_file string The full pathname to the non-standard css file to be used in the html. Default: the default css file from the installation
--sel_file string The name of the selection file to be used. Integer numbers in the selection file are extracted, and the HTML pages created contain only the catalogue objects with these object ID's. If no sort column was specified, the objects are sorted as in the selection file.

Parameter file:

In the parameter file the task settings can be given. A setting in the parameter file must look as follows:

'option = value'

Here 'option' corresponds to the command line setting without the leading '--'.
Empty lines are neglected.
Also everything which appears after a '#' sign is discarded as comment.

Selection file:

The selection file contains the ID's of the objects which should be put on the HTML pages. The object ID numbers in the selection file can be given on several rows of the file. As separator blanks, tabs, ',', ':', ';' and '|' can be used. Rows starting with '#' are discarded as comments.

Examples:

  1. axe2web --parfile fieldU.par --sextract_cat Sex_F775W.cat --pagename apples_fu

    Here the file 'fieldU.par' looks as follows:

    #------------------------------------------------------------
    #
    # Parameter file for Apples, field U
    #
    pagename = apples_fu
    direct_image = direct775w.fits
    stamp_image = fieldu_g800l_drz_2.STP.fits
    spectr_table = fieldu_g800l_drz_2.SPC.fits
    sextract_cat = Sex_F775W.cat
    sort_column = MAG_AUTO
    pagesize=50 #
    #------------------------------------------------------------

    This creates the files 'apples_fu_p1.html', 'apples_fu_p2.html' ... 'apples_fu_pn.html'. Each file contains a table where the information on 50 objects is displayed in the table rows. The objects are sorted in ascending magnitude.

  2. axe2web --parfile fieldU.par --sextract_cat Sex_F775W.cat --pagename apples_fu --only_html yes --pagename bright --number_objects 70

    Creates the HTML files 'bright_p1.html' ... with the 70 brightest objects from the specified catalogue. Since the images and graphics were just prepared in the first example, only the HTML files are produced here.

  3. axe2web --parfile fieldU.par --sextract_cat Sex_F775W.cat --pagename apples_fu --sel_file highz_sel.txt --only_html yes

    As example 1., but only the object with ID's stored in the file 'highz_sel.txt' are used to create the HTML pages. Only the HTML files are produced. Here the file 'highz_sel.txt' looks as follows:

    #------------------------------------------------------------
    #
    # Selection of high-z objects from
    # the apples field:
    302, 405, 2, 54, 112
    98, 298, 369, 175
    #


aXe2web
Send comments to <help@stsci.edu>