Users' Manual for SPEX

SPEX is software written in the IDL language, and uses routines from the IDL Astrolib.
SPEX has only been developed and tested on UNIX-type OSes and will probably not run on other platforms.

Warning This site is under construction. Navigation within the page may still prove misleading sometimes, and some sections may need further attention before they actually answer most questions of the user. If you want to contribute explanations, or have suggestions for the TO DO section, please contact us.

Also, the package is not generally available but will have to be requested. Again, contact us in this case. In case the package is available to you, and you don't care about the following introductory General remarks for some reason, you may want to get a quick start.

Next: General remarks

Contents
General remarks
Preparing the calibration images

Creating a median bias image
Creating a median flatfield image
Wavelength calibration

Working with spex_reduce

Creating the logfile

structure, entries

Starting the reduction

call, keywords

Running the reduction

Spectrum position on the ccd
Extract spectrum, remove cosmics
Wavelength calibration
Flux calibration
Final evaluation

Details and hints

Spectrum position on the ccd
Extract spectrum, remove cosmics
Wavelength calibration
Flux calibration
Final evaluation

Complete List of Keywords

Subroutines
To do / Recent changes
Contact

Next: Preparing the calibration images Previous: Table of Contents

General remarks

A logfile guides the reduction process of a whole set of longslit spectra. They should have been taken with the same instrument and should be similar to each other in terms of the wavelength range covered. If flux calibration is desired, the first star in the logfile has to be the standard star; other details about how to create the logfile may be found under Creating the logfile. Once the logfile has been written, and the calibration images are available, too, (see Preparing the calibration images), the reduction is started by calling
IDL> spex_reduce,"logfile"
A description of additional keywords that might be necessary can be found in the chapter Starting the reduction. A complete List of all available Keywords is also provided. spex_reduce and the sub-routines it calls require regular interaction; clues on how to handle individual requests are summerized in Running the reduction and are further explained in Details and hints. The steps spex_reduce will go through one after the other are the following:

read the total number of spectra to go through, then

read the specifications for the first/next object from the logfile

read in the necessary images

calculate the illumination function (silently; for later use)

apply bias and flatfield correction to the images

determine where the spectrum runs on the chip (as follows)

"number of cuts through the spectrum" clicks on the approximate location

determine the position at each pixel along the dispersion direction by a gauss fit perpendicular to the dispersion direction

find a function to describe the spectrum position at each pixel along the dispersion direction by evaluating the results from the individual gauss fits

fine-tune the parameters of this function (user interaction required)

extract star spectrum and remove cosmics

fit a gaussian to the counts at the current pixel position (cut at the current pixel position determined above perpendicular to the dispersion direction)

replace all counts higher than a pre-defined level by the fit value

several levels of interaction and different actions are possible to influence the proposed choice

sum up all counts at the current pixel position except the replaced ones (from center, half "Width of the spectrum" wide)

sum up all sky counts at the current pixel position (includes silent cosmic filtering; in "Space between spectrum and sky" distance from the center and "Width of the sky" wide)

subtract sky from spectrum counts (corrected for the size of the integration area) to obtain the sky-free spectrum

show image of rejected cosmics from sky filtering

show filtered image of spectrum and sky extraction ranges

plot the extracted, sky-corrected spectrum

modify the extracted, sky-corrected spectrum if desired

correct extracted spectrum with illumination function

plot this "raw" spectrum

extract and plot the wavelength calibration spectrum

find the dispersion relation

identify lines (input from the user required)

identify lines (with the given starting points, try an automatic identification now)

calculate the resulting dispersion relation

fine-tune the resulting dispersion relation (user interaction required)

apply the dispersion relation to the spectrum

plot the wavelength calibrated spectrum

save the wavelength calibrated spectrum to a file

if requested: flux calibrate object's spectrum

interpolate flux calibration table data to spectrum wavelengths

plot flux calibration table data and interpolation

plot flux calibration factor

modify flux calibration factor if desired (user interaction required)

if requested: apply flux calibration to object

if requested: plot flux calibrated spectrum

if requested: save the flux calibrated spectrum to a file

go back to 2. or exit if all spectra have been processed

The output produced will be mainly a originalfilename_spec file, and if flux calibration was requested, a originalfilename_fcspec file. Additional files will be produced but are mainly of interest for the program itself during its run. They should however not be deleted, unless you want to start over from zero for a particular reason.

Next: Creating a median bias Previous: General remarks

Preparing the calibration images

Creating a median bias image
Creating a median flat image
Wavelength calibration

Next: Creating a median flat Up: Preparing the calibration images Previous: Preparing the calibration images

Creating a median bias image
This task may be tackled by using the following routines from the package:
tripp_write_zero_log.pro
tripp_zero.pro
Explanations on how to use these may be found here.

Next: Wavelength calibration Up: Preparing the calibration images Previous: Creating a median bias

Creating a median flatfield image
This task may be tackled by using the following routines from the package:
tripp_write_flat_log.pro
tripp_flat.pro
Explanations on how to use these may be found here.

Next: Working with spex_reduce Up: Preparing the calibration images Previous: Creating a median flat

Wavelength calibration
The wavelength calibration will be done using a single exposure taken under as similar as possible conditions as the spectrum that is to be calibrated. As only one exposure (or two) can have been taken right before or after the spectrum itself, or at least not too long before or after, SPEX only provides the possibilty to include a single file name per object in the logfile as the wavelength calibration file. If you nevertheless wish to use some sort of combination of several exposures, you will have to provide the respective result yourself, and it will have to have the format of a regular fits file.

Next: Creating the logfile Previous: Wavelength calibration

Working with `spex_reduce`

Creating the logfile
Starting the reduction
Running the reduction
Details and hints
Complete List of Keywords

Next: Starting the reduction Up: Working with spex_reduce Previous: Working with spex_reduce

Creating the logfile

Choose a name for the logfile to be written now; it could be something like an identifier for the data set you are about to tackle, followed by the extension .log.
Write the logfile in your favourite editor. It contains the total number of objects you want to reduce and then for each object:

Name of the object file.
Name of bias file.
Name of flat file.
Name of wave file.
Wavedegree.
Standard degree of polynomial fit used by wavelength calibration.
Number of cuts through the spectrum.
[approximate location...]
Begin of the usable spectrum.
Mark the location of the spectrum on the ccd: From this pixel position on, working on the spectrum is possible.
End of the usable spectrum.
Mark the location of the spectrum on the ccd: The highest pixel position, where the spectrum is visible.
Width of the spectrum.
Total number of pixels used for summing up the spectrum counts (i.e. from center, half "Width of the spectrum" wide).
Space between spectrum and sky.
Distance from the center to the area of silent cosmic filtering and summing up the sky counts.
Width of the sky.
Number of pixels used for summing up the sky counts and silent cosmic filtering (at each side of the spectrum).

Choose the same numbers for the usable spectrum; otherwise problems - for example while making the wavefit - will occur. Besides, don't forget to add the path to the objects, if they are not located in your working directory. If there are any doubts, you can check the numbers previously with appropriate IDL commands.
Now your logfile should look like this:
2
data/d1p5m_0231.fits
data/d1p5m_Zero.fits
data/d1p5m_Flat.fits
data/d1p5m_0232.fits
3
1
520      
2051
10
15
80
data/d1p5m_0197.fits
data/d1p5m_Zero.fits
data/d1p5m_Flat.fits
data/d1p5m_0232.fits
3
1
520      
2051
10
15
80
Next: Running the reduction Up: Working with spex_reduce Previous: Creating the logfile

Starting the reduction
IDL> spex_reduce,'logfile.log'                     $
                 [, spectrum='spectrum.dat',       $
                    wave_fit='wave_fit.dat',       $
                    xr=[*,*],                      $
                    /rotate,                       $
                    /fluxcalibonly,                $
                    stdfluxtable='stdfluxtable.dat']
The following additional keywords could be helpful (a complete list may be found here):

spectrum
spex_reduce expects a file with laboratory wavelengths named 'HeAr.dat'. Call spectrum, if you use another file, e.g. 'HeNe.dat'. You can also specify this file interactively.
wave_fit
If you want to save the wavelength fit coefficients in another name than 'wave_fit.dat'. You should call wave_fit for example, if you want to use several standard stars in the same directory - otherwise 'wave_fit.dat' will be overwritten.
xr
During the identification of the spectrum position, only the part of the image between those two limits (pixel) will be shown. Argument is a vector with two elements.
/rotate
spex_reduce expects that the spectrum is located on the ccd in horizontal direction. Otherwise call /rotate.
/fluxcalibonly
If wavelength calibrated spectra exist and you want to make flux calibration only, call /fluxcalibonly.
stdfluxtable
If you want to flux calibrate the objects, spex_reduce needs the file name of the standard flux table.

Next: Details and hints Up: Working with spex_reduce Previous: Starting the reduction

Running the reduction
The following chapter describes how to handle an individual reduction, the necessary inputs and the outputs of the routine. spex_reduce is quite talkative about which inputs are expected and what outputs are produced, so you can follow the instructions.
You have to reduce the first star - normally the standard star - at least one time. Then you can skip objects or work on them just as you want.
While running spex_reduce, you will go through the following steps:

Determination of the spectrum position on the ccd

X-axes.
Start with a left mouse click at the middle of the spectrum. At the standard star, you are asked for another two clicks, even if you want to skip it.
Y-axes.
The program fixes the position of the spectrum on the ccd and makes a polynomial fit. Cosmics appear as long vertical lines, which can be rejected now. Click here to learn about modifications.

Extract star spectrum and remove cosmics

Gauss fit at each pixel of the spectrum.
The vertical lines mark the part where the spectrum is evaluated. The program waits at pixel No 0 so you can choose level and plot switch if you want to. Usually, only the fits with questionable counts are shown. Start with return and follow the instructions.
Rejected cosmics from sky filtering.
Spectrum and sky extraction ranges.
Extracted, sky-corrected spectrum. At this first evaluation of the spectrum, manual modifications are possible.
Extracted and flatfielded spectrum of laboratory wavelengths.

Wavelength calibration

Standard star:

Identification of wavelengths: Mark lines and type the wavelength.
Dispersion relation.
Residuals. Improve of the fit possible.

Automatic identification of wavelengths. If you want to make changes type re-start. The proceeding will be like described for the standard star, but it won't leave a wavefit file.
Dispersion relation.
Residuals. Reject non-fitting points.
Final identification of the wavelengths.

Flux calibration

Standard star:

Flux calibration data (white) and interpolation to spectrum wavelengths (blue).
Flux calibration factor. Mark points to make the spline fit.
Flux calibration, applied to the object. You may go back to the flux calibration factor to improve the result.

Flux calibrated spectrum.

Final evaluation of the spectrum

Next: Complete List of Keywords Up: Working with spex_reduce Previous: Running the reduction

Details and hints
Determination of the spectrum position on the ccd

X-axes.
After each mouse click, several horizontal lines are shown. The higher one indicates the "Width of the spectrum", the two lower lines indicate the "Width of the sky", as you chose in the logfile.
Y-axes.
Optional modifications:

Reject points. Cosmics can falsify the polynomial fit. Type 'r' and follow instructions.
New polynomial fit. For better fitting type a different wave degree.

Extract star spectrum and remove cosmics

Gauss fit at each pixel of the spectrum.
The two vertical lines indicate the "Width of the spectrum" you chose in the logfile. Questionable counts are marked with green colour.
Optional modifications:

Modify manually. To delete more counts than marked or to keep only a part of them, type 'm' and follow the instructions. After each modification, a new gaussian is fitted.
Keep original data. To delete none of the marked counts, type 'k'.
New plot switch. To change the plot switch, type 'p'.

0 means silent filtering, i. e. no possibility to modify the cosmic filtering.
1 is put in as standard. Only the fits with questionable counts are plotted.
2 means plots at each pixel, stopping at the fits with questionable counts.
3 means plots at each pixel, stopping at the fits with questionable counts.

New level. All counts higher than the level you type (deviation from the gaussian) are replaced by the fit value.

Extracted, sky-corrected spectrum. Optional modifications (for example to remove cosmics which have been left):

Modify manually. Type 'm' to go back to the gaussian and reject counts. Just follow the instructions.
Linear interpolation. Type 'l' to replace a part of the spectrum with linear interpolation.

Wavelength calibration

Standard star:

Identification of wavelengths: Mark lines - at least three - and type the wavelength. The more the better: There will occur less faults in the automatic identification of lines, and you can choose a higher polynomial degree in the following.
Residuals: Difference between identified wavelengths and fit. Choose a new polynomial fit (type the degree) to change the deviation.

Residuals. Optional modifications:

New polynomial fit. Type a different degree to make the fit better.
Reject. Type 'r' to reject non-fitting points. The residuals should be better than the spectral resolution.

Flux calibration
Make a spline fit to ignore the absorption lines in the flux calibration factor.

Spline fit window. Possible interactions:

Mark area (left mouse click). Go ahead in the zoom window.
Delete points (right mouse click) that don't fit. After deletion, the new spline fit appears.
End (middle mouse click) and go to the applied flux calibration.

Zoom window: Mark points on the spectrum with left mouse clicks. With a middle mouse click, you can go back to the spline fit window. After marking at least four points, a provisional spline fit appears there. Repeat this proceeding till the spline equals the main track of the spectrum.

Final evaluation of the spectrum

Next: Subroutines Up: Working with spex_reduce Previous: Details and Hints

Complete List of Keywords

The following keywords can be helpful:

/center
During the identification of the spectrum position, only the central part of the image will be shown.

filter
Switch for cosmic filtering in spex_extract.
0: no filtering.
1: with filtering (Default).
This option is helpful for a quick reduction or for noisy spectra, where gauss-filtering fails too often.

/fluxcalibonly
If wavelength calibrated spectra exist and you want to make flux calibration only, call /fluxcalibonly.

level
Rejection level for cosmic filtering in spex_extract.
Default: 1.1
This parameter can also be adjusted interactively.

lev_halbwertsbreite
Additional parameter for rejection of cosmic filtering in spex_extract.
Default: 5
The higher this value the stronger is the rejection level reduced at the wings of the gauss profile.

overscan
Overscan area. If this keyword is used the bias correction is read from the overscan. The argument is a vector with 4 elements:
left/right boundary on the left side of the CCD
left/right boundary on the right side of the CCD

pswitch
Switch to guide number of plots during cosmic filtering.
Default: 1
0: no plots ... 3: many plots. Check it out to see the results.

/rotate
spex_reduce expects that the spectrum is located on the CCD in horizontal direction. Otherwise call /rotate.

/signed
Switch to handle signed integer fits files.

spectrum
spex_reduce expects a file with laboratory wavelengths named 'HeAr.dat'. Call spectrum, if you use another file, e.g. 'HeNe.dat'. You can also specify this file interactively.

start
If you already identified lines in the calibration spectrum of the standard star you can re-run spex_reduce with start=0 in the following sessions. Make sure you used wave_fit if you have switched to another data set in the meantime.

stdfluxtable
If you want to flux calibrate the objects, spex_reduce needs the file name of the standard flux table.

/useoldstandard
Do not perform flux calibration. Use a previously determined one. You have to be sure that a previous calibration exists. Otherwise you crash.

/useoldwave
Do not perform wavelength calibration. Use a previously determined one. You have to be sure that a previous calibration exists. Otherwise you crash.

wave_fit
If you want to save the wavelength fit coefficients in another name than 'wave_fit.dat'. You should call wave_fit for example, if you want to use several standard stars in the same directory - otherwise 'wave_fit.dat' will be overwritten.

width
The typical width of the wavelength comparison lines in pixel.
Default: 14
Try to adjust this parameter if the automatic line identification during the wavelength calibration fails.

xr
During the identification of the spectrum position, only the part of the image between those two limits (pixel) will be shown. Argument is a vector with two elements.

Next: To do Previous: Details and hints

Subroutines called by above programs

SPEX routines
TRIPP, aitlib, astrolib



spex_reduce.pro

calls

    spex_signed.pro
    spex_fit_gauss.pro  
    spex_extract.pro    
    spex_fit_wave.pro  
    spex_fluxcal.pro

Also available:

spex_coadd.pro

uses

    
     spex_rectify.pro  

spex_writespec.pro
spex_readspec.pro
check_specs.pro

Next: Recent changes Previous: Subroutines

To do

HTML Help

complete the writing of explaining texts

check and correct the navigational links within the page

spex_extract

replace calls to tripp_curvefit by jwcurvefit or mpfit

spex_reduce

Allow quick-lock: no logfile? no flat or bias (-> no flux calibration), maybe no wavelength calibration, no filtering BUT: extraction! Would be easiest to use if a /quick keyword together with the filename instead of the logfilename would take care of all this.

Schraeglage

extinction correction

spex_wave

Koeffizienten fuer Polynomfit (Wellenlaengenkalibration)

others

two wavelength files

Next: Contact Previous: To do

Recent changes

Mail to: Iris Traulsen / Agnes Hoffmann / Stefan Dreizler / Sonja Schuh

Users' Manual for SPEX

Table of Contents

General remarks

Preparing the calibration images

Creating a median bias image

Creating a median flatfield image

Wavelength calibration

Working with spex_reduce

Creating the logfile

Starting the reduction

Running the reduction

Details and hints

Complete List of Keywords

Subroutines called by above programs

To do

Recent changes

Working with `spex_reduce`