Delivery: baches1-<rel>.tar.gz
Author: Carlos Guirao
Release: $Id: baches_data_reduction.README,v 1.1 2009-06-11 15:30:29 midasmgr Exp $

Content:
--------
  baches_calib.prg		# BACHES calibration
  baches_pipeline.prg           # BACHES pipeline
  compute_fits.prg	        # Pre-computation of fits files. Default:none
  file_ext.prg			# Check file extensions
  clean.prg	                # Cleaning procedure
  thar_ref.fit			# Thorium lamp used as reference
  thar_ref_ident.fit		# Identifier of a couple of thorium lines
  thar.fit			# Catalog of thorium-argon lines
  thar_1000lines.fit		# Table with XSTART and XEND for 1000 thar lines
  thar_300lines.fit		# Table with XSTART and XEND for 300 thar lines
  demo_ff.fit			# Spectrum of flat field (halogen) lamp
  demo_thar.fit  		# Spectrum of thorium-argon calibration lamp
  demo_zeta-tau.fit		# Spectrum of star Zeta-Tau

Installation:
-------------
Move or copy the content of this baches-<rel>.tar.gz file to directory 
with BACHES data you want to reduce.

Start MIDAS
----------
  % inmidas
  Midas 000> 
 
NOTE: The MIDAS package ECHELLE used here assumes raw data is delivered with 
      orders displayed
      from left to right, and with increasing order number from top to buttom 
      (red up, blue down); within an order the wavelength increases 
      from left to right (from blue to red). 
      The orientation of raw files can be changed by editing the 
      script "compute_fits.prg" (see examples with FLIP/IMA commands)


Calibration:
-----------
Execute the MIDAS script "baches_calib.prg" with two arguments:
<flat_field>.fit  Spectrum of a continuum lamp used to identified the orders. 
                  You may need to combine several flats with differnt filters 
                  in order to cover all the orders. The spectrum of a direct
                  halogen lamp is enough to cover 23 orders.
                  The spectrum of a halogen lamp with a blue filter (bg23) is
                  enough to cover upto 26 orders. 
                  To cover more orders (28-30) you will need a composite of 
                  flats with different filters and from UV lamps.
<thorium>.fit     Spectrum of a thorium-argon lamp.

Examples with demo data files:
Example 1:
  Midas 001> @@ baches_calib.prg demo_ff.fit demo_thar.fit
Example 2: To identify only the first 24 orders
  Midas 001> @@ baches_calib.prg demo_ff.fit demo_thar.fit ? 24 
Example 3: To increase the slit with of the orders to 16 pixels
  Midas 001> @@ baches_calib.prg demo_ff.fit demo_thar.fit ? ? 16

Input arguments for baches_calib.prg are:
 Required: 2-dimensional FITS/BDF image with the spectrum of flat field lamp.
 Required: 2-dimensional FITS/BDF image with the spectrum of a calibration lamp.
 Optional: MIDAS table of the calibration lamp in FITS format. Default thar.fit
 Optional: Number of orders to be calibrated. Default 26
 Optional: Slit width for order identification. Default 14
 Optional: Slit width for extraction. Default 10
 Optional: Final tolerance on RMS error. Default 0.3
 Optional: Final degree of polynomial defining dispersion. Default 3

The procedure will first display the flat field image and identify the orders 
(green lines). 

If the identification or orders stops with the prompt:
  **************************************************
  * Now you can:                                   *
  *  1 - Go on                                     *
  *  2 - Stop here                                 *
  **************************************************
  * Enter your choice :      

is because there was an error with the identification. Enter '2' to stop the
procedure and repeat it with less orders as in "Example 2" above,
or increase the slit with for order identification as in "Example 3" above,
or review the composition of your flat image to be as smooth as possible 
between orders.

The identification of orders gets completed with the prompt:

  baches_calib: do you want to continue [yn] (y)?      

If the identification is ok for you, enter 'y' and the procedure will continue
with the line identification of the thorium lamp spectrum. It will displayed
an old thorium spectrum as a reference (thar_ref.fit) and mark the lines to
be identified.

In a second display the new thorium spectrum will be displayed and the cursor
will show a square that should be OK in size (5x10pixel)  but it could be 
resized if necessary (use arrows to increase/decrease the
square) to the size of a thorium line.

Using the reference display as a guide, try to center the square in the 
same lines and select them with a click of the mouse left botton in the
following order: 
	1st click: top left line 
	2nd click: top rigth line
	3rd click: buttom left line
	4th click: buttom right line

Finish the sequence by clicking the mouse right botton. The procedure will
ask you to enter the order number: 
 
  Enter absolute order number of first pointed line (square mark) : 32
  Sequence no. 0001, Order no. 0032. Enter wavelength : 6834.924
  Sequence no. 0002, Order no. 0048. Enter wavelength : 4579.390

And the calibration will start automatically.

The calibration will run several rounds of line identification. Typically 
you can stop the calibration when 80% of total lines have been identified.

You can continue the identification by hand if you type 'n' to the question:
"Do you want to clean temporary files [yn] (y)", and continue with MIDAS
command like:

  set/eche tol = 0.4 	(set the tolerance to 0.4. Default 0.3)
  ident/eche            (another round of identification)
  save/eche baches 	(save the solution if the number of lines identified is)
                        (greater than the previous round)

The calibration will leave two files:

  bachesORDE.fit
  bachesLINE.fit

that are needed for the next step: the bache_pipeline.

Optionally you can inmediately calibrate the spectrum of the calibration lamp 
,e.g. to check it agains an printed atlas of the same lines, or to automatically
calculate the Resolving Power (R:Lambda/DeltaLambda)  and extract the 
median R.

baches_pipeline.prg:
---------------------
You can calibrate any spectra after calibration with the procedure "baches_pipeline.prg".

Execute:
   Midas 001> @@ baches_pipeline.prg <target>.fit

Example with demo data files:
   Midas 001> @@ baches_pipeline.prg demo_zeta-tau.fit

The procedure will produce two FITS files:

   <target>_wr.fit 	Bi-dimensional file with each order per row.
   <target>_wrm.fit     Mono-dimensional file with all orders merged.

To plot a result with MIDAS try:

   Midas 001> CREA/GRAP 
   Midas 002> PLOT/AXES 6520,6620 0,6000 0 "Wavelength" "Relative Intensity"
   Midas 003> OVERPLOT/ROW <target>_wrm.fit
   
To measure the FWHM of a plotted line, try:

   Midas 001> CENTER/GAUSS gcursor (and type left and right of the given line)

To create a postscript file from your graph, try:

   Midas 001> COPY/GRAPH postscript

To clean the directory from the garbage left by MIDAS:

   Midas 001> @@ clean.prg

baches_resolving_power.prg
----------------------
This procedure could help you to calculate the resolving power for several
hundred lines of your calibration lamp (e.g. thorium). 

The header of the procedure explains the details.

Example:
   Midas 001> @@ baches_resolving_power.prg th1_wmr.fit

where "th1_wmr.fit" is the output generated by the procedure:

   Midas 001> @@ baches_pipeline.prg th1.fit 


NOTES
=====
How I created the thar_ref_ident.tbl
===================================
Table created with thar_ref_ident.dat
Where first two columns X, Y are obtained in thar_ref.fit with GET/CURSOR
     161      943       6834.924#32
    1487      883       6834.924#33
     250      886       6643.790#33
     327      329       4579.390#48
    1213      289       4579.390#49
and thar_ref_ident.fmt:
 DEFINE/FIELD 4  8   I      :X
 DEFINE/FIELD 11 17  I      :Y
 DEFINE/FIELD 25 35 C      :IDENT

 Midas 001> CREA/TABL thar_ref_ident 3 4 thar_ref_ident.dat thar_ref_ident.fmt
 Midas 002> OUTDISK/FITS thar_ref_ident.tbl thar_ref_ident.fit
