R3D, a package for reducing IFS data
Index
Purpose
R3D is a package for reducing fiber based integral field spectroscopy data. The purpose of this package is to unify the reduction techniques for the different IFS instruments to a single one, in order to allow the general public to reduce different instruments data in an homogeneus, consistent and simple way.
Although still in its prototyping phase, it has been proved to be useful to reduce PMAS (both in the Larr and the PPAK modes), VIMOS and INTEGRAL data. The current version has been coded in Perl, using PDL, in order to speed-up the algorithm testing phase.
We have translated to C most of the time critical algorithms, and it is our intention to translate all of them. However, even in this phase R3D is fast enough to produce valuable science frames in reasonable time.
News
  • (03/06/2012) New scripts has been added to handle propertly the reduction of SparsePak data (Thanks to Tim Haines (University Missouri at Kansas City)
  • (01/06/2012) Flux calibration procedures corrected to handle better the attenuation curve (calib_det.pl and flux_calib.pl)
Download, Requirements and Installation (Perl Version)
The last stable Perl version of R3D can be download here.

R3D Perl version requires the following perl modules to be installed in your computer:

Statistics::OLS
Math::FFT
Math::Stat
Math::Spline qw(spline linsearch binsearch)
Math::Derivative qw(Derivative2)
Math::Approx
Astro::FITS::CFITSIO qw( :longnames :constants )
PGPLOT
PDL

All this modules can be found at CPAN. It is recomended the lastest possible version of PDL.
Once installed all these modules, and assuming that you have untar the files at the directory DIR, you should run the following script: 

./change_line.pl /home/sanchez/sda1/perl/MY/my.pl DIR/my.pl
You can test the scripts by running: 
./test_r3d.pl
If you do not get any error or warning message you have suscessfully installed R3D. Then, add the directory DIR to your PATH. If you find any problem, please send an email to S.F.Sanchez
Download, Requirements and Installation (C Version)
The last stable C version of R3D can be download here.
It required the Lyon-C library, and PGPLOT with Tcl/tk (basically the same requirements than E3D. To install it:
For binary releases:
1. Download the binary release for your platform into a directory of your choice: (a) Linux 64bits available
(b)Linux 32bits available
2. Unpack the distribution using e.g. tar xvzf R3D_c_linux.gz, this will create a directory R3D containing the R3D programs.
3. Add the new directory to your PATH.
For source code tarballs:
1. Download the last stable version of the R3D distribution (e.g. r3d-0.1.tar.gz) from the list of Downloads and copy it into the Euro3D directory (given by the environment variable IFU_PATH, read the preinstalation requeriments).
2. Extracting the archive via tar xvfz r3d-0.1.tar.gz under the $IFU_PATH path will create the directory e3d-1.3a or a newer version number respectively.
3. Change into the created directory and execute the configure and make scripts:
r3d> ./configure
r3d> make

Attention:
The make can fail due to a different definition of certain libraries. We have tested the procedure under the two main Linux distributions, RedHat (7.1 and 8.0) and Suse (8.2). They differ in the definition of TCL/TK libraries. You should edit the file add_defs/makedefs.local to select the proper definition of V3D_LIBS for your distribution and add your E3D path to the declaration of the chosen (#HOME) V3D_LIBS as well as to V3D_INC.
4. Add the directory user/bin of r3d to your PATH, e.g. for csh add in .login or .cshrc:
setenv PATH=${PATH}:${IFU_PATH}/r3d/user/bin
NOTE The command line programs require similar inputs and produce similar outputs in both versions.


R3D C version requires to have installed PGPLOT with Tcl/TK
Reduction Sequence
To reduce fiber-based IFS data it is needed to follow a basic sequence (assuming a bias-subtracted frame and possibly corrected for pixel-to-pixel response variation*):
  • Find the position of the spectra in the raw frame
    The location of the spectra in the central position of the CCD (or anyother defined by the user), can be found using the peak_find.pl script. The output of this script is an ASCII file with the location of each spectra. It requires a continuum illuminated frame (whatever its origing).
  • Trace the position of the spectra along the spectral direction
    Once located the spectra in the central position of the CCD, it is needed to trace this position along the spectral direction, using the trace_peaks_recursive.pl. This script requests the output of the previous one, and produce a FITS file (the trace) with the location of the spectra for each pixel in the spectral direction. It requires a continuum illuminated frame (like the previous one).
  • Extract the spectra
    Once located the spectra in the CCD it is possible to extract them, using the extract_aper.pl (for pure aperture extraction), or extract_aper_CT.pl (for Cross-talk corrected extraction, that is very slow). It requires the trace frame, a raw-frame and the output is a FITS file with the length of the pixels in the spectral direction and the height the number of spectra.
  • Correct for the distortion & dispersion
    The distortion and dispersion corrections are handle in R3D separately. Using as input an ARC or an image with well defined emission line, we perform a 1st order distortion correction, using the dist_cor.pl or dist_cor_cross.pl, identifing a single emission line. It produces as output a 1st-order distorted corrected frame and an ASCII file with the 1st order distortion corrections (*.dist.txt). Once performed this correction, it is possible to correct for second order distortion effects, using mdist_cor_sp.pl, identify several emission lines along the spectral dispersion direction. It produces as output a distorted corrected frame and a FITS file with the distortion correction solution (*.dist.fits).
    The distortion correction found using these scripts (*.dist.txt and *.disp.fits) can be applied to the science data using the mdist_cor_external.pl.
    The dispersion solution is found using the disp_cor.pl script, identifing the wavelength of several emission lines interactively. It produces as output a dispersion corrected frame and and an ASCII file with the dispersion solution, that can be applyied to the science data using the disp_cor_external.pl script.
  • Fiber-to-fiber transmission correction
    Fibers have different transmissions that may depend on the wavelength. To determine the fiber-to-fiber transmission difference we use the fiber_flat.pl or fiber_flat_trans.pl scripts. They require a continuum illuminated frame as input frame, and produces a FITS file with the fiber-to-fiber transmission difference.
    The science frames can be corrected for this effect by dividing for this file, using the imarith.pl script.
* In most of the fiber-based IFS it is not possible to illuminate the CCDs with an homogeneus continuum source, so it is not possible to perform an standard flat-field.
Typical reduction of PMAS data
Assuming that gbias.fits is the BIAS file, TRACE.fits a continuum illuminated file, and WAVE.fits an ARC frame, the following scripts will reduce the WAVE.fits file (appart from fiber-flat correction) and derive the distortion and dispersion corrrections: 
# BIAS subtraction:
imarith.pl WAVE.fits - gbias.fits wjunk.fits
# BIAS subtraction:
imarith.pl TRACE.fits - gbias.fits tjunk.fits
# PEAK finding
peak_find.pl tjunk.fits 0 5 1 5 2 3.5 0.1 tjunk.peaks
# TRACING THE PEAKS
trace_peaks_recursive.pl tjunk.fits 0 tjunk.peaks 1 3 0 5 2 tjunk.trc.fits 0 5
# EXTRACTING
extract_aper.pl wjunk.fits 0 tjunk.trc.fits 5 wjunk.ms.fits 0
# DISTORTION CORRECTION
dist_cor.pl wjunk.ms.fits wjunk.dc0.fits wjunk.dist.txt 0 675 50 2 0 3 1 675
mdist_cor_sp.pl wjunk.dc0.fits 6 30 4 wjunk.dc1.fits wjunk.dist.fits 1 1050 1
# DISPERSION CORRECTION
disp_cor.pl wjunk.dc1.fits 3700 3 5 128 5 3 wjunk.disp_cor.fits wjunk.disp.txt 1
mv wjunk.disp_cor.fits WAVE.disp_cor.fits
These scripts assume that there is an emission line near the pixel 675, and that the final dispersion solution is CRVAL1=3700AA and CDELT1=3AA.
Once reduced the ARC frame it is possible to reduce a science frame (PREFIX.fits), using the scripts: 
# BIAS subtraction:
imarith.pl PREFIX.fits - gbias.fits junk.fits
# EXTRACTING
extract_aper.pl junk.fits 0 tjunk.trc.fits 5 junk.ms.fits 0
# DISTORTION CORRECTION
mdist_cor_external.pl junk.dc0.fits wjunk.dist.txt wjunk.dist.fits junk.dc1.fits 0
# DISPERSION CORRECTION
disp_cor_external.pl junk.dc1.fits 3700 3 junk.disp_cor.fits wjunk.disp.txt 0
Publications
We are working on a publication on R3D, and an "User Guide". By now you can quote:

Publications about R3D
  • "R3D, a package for reducing IFS data", Sanchez S.F. & Cardiel N., 2005, Calar Alto Newsletter, n.10
    link
  • "Techniques for reducing fiber-fed and integral-field spectroscopy data: The software package R3D", S.F.Sanchez ADS, accepted for publishing in AN, (astro-ph/0606263)

Publicatons using R3D
S.F.Sanchez et al.