TMAG

Photometric package for ESO/MIDAS

http://www.eso.org/~ohainaut/prog/tmag

1.- Introduction

This package allows the user to measure standard stars on CCD frames in an interactive way, then to compute a photometric solution. The residuals of this solution can be plotted, and bad stars edited out interactivelly.

The measurements interface finds and measures the stars automatically on the frames (works quite well, cf Fig.1). For this reason, most of the original routines (called TMAG_something.prg or TMAG/something in Midas) have been evolved to AMAG_something (for "Automatic" Tmag). While it might be confusing, AMAG is just an upgrade of TMAG.

For the interactive computation of the photometric solution, a Graphic User Interface is available, as seen in Fig.3.

TMAG has some additional commands to deal with the EFOSC2, EMMI-red, WFI and SuSI2 instruments at La Silla.

Figure 1: Screen shot of a frame on which the standards have been found and measured automatically

Figure 2: Screen shot of a residual plots. The points can be interactivelly edited out.

Figure 3: screen shot of the G.U.I., showing it ready to process table std.tbl for filter V, solving for the ZeroPoint, but using 0.125 as default for the extinction, and the system default for the color term.

2.- Download and installation

Get the latest version of the package (they are listed and linked at the bottom of this page), and expand it in the directory where you keep source code of packages (in my case, ~/source). The prg requires MIDAS version 97NOV or newer. Check the INSTALL file. On a recent MIDAS (under SciSoft) installation on Linux, it should be sufficient to do
cd tmag/src
make all install clean

Some support can be provided by Olivier Hainaut (ohainaut @ eso.org), to whom bug reports and suggestions should also be sent.

3.- User's manual

3.1.- Introduction

The package works with the standard MIDAS command system, and uses its graphical capabilities. In the package, many commands appear in double, as amag_* and tmag_*. The amag ones correspond to the new, fairly user-friendly package, while tmag is an older version of the package, less user-friendly but more flexible. The manual below refers to the amag commands. The tmag commands are documented in the prg files.

Almost all commands come with a on-line help, which is accessible with @@ command ??? .

Section 3.2- is a step-by-step cookbook on how to use the program, while Section 3.3- is the detailed reference manual for all the commands.

3.2- Cookbook

Load the package
SET/CONT tmag
Measure the standards:
AMAG/MES std001.bdf 0.0805 0. -1
std001 is the image, 0.0805 the pixel scale, 0. the position angle (N up) and -1 indicates that the image is flipped (E right of N). The program loads the image, and overplot crosses at the (expected) position of the stars, using the header. Click on ONE of the cross, then the corresponding star to re-center. Done.
You may want to set keyword OFFCENT to do this more automatically: wri/key OFFCENT/r/1/2 12,-35 will shift the predicted position of the stars by that amount of pixels, and will not ask you to click every frame. So, experiment a little with values of OFFCENT, as this is typically stable for an instrument.
Measure all the standards:
Can be done at once with a catalogue:
CREA/ICA std std*bdf
If needed, edit std.cat to keep only the standard frames, then
EXEC/CAT AMAG/MES std.cat 0.0805 0. -1 will go tru all the frames.
The output is a series of Midas tables t_std...tbl (i.e. your images with a prefix t_).
Merge the measurement tables:
AMAG/MERGE std.cat std.tbl
Takes all the frames in std.cat, and collate the corresponding t_...tbl tables into the output table std.tbl.
Correct for the exposure times:
AMAG/EXPTIME std.tbl
The individual exposure times (kept in the table) are applied to the instrumental magnitudes for normalizations. Do not run this command if your images are already time-normalized...
Photometric Solution:
At this point, the GUI will come handy:
AMAG/GUI. In what follows, I describe both the command lines and the buttons on the GUI.
First attempt of a solution, computing only the ZeroPt (and not the Extinction nor the color term: switches set to 100). As this is a first pass, the stars are not yest identified (IDENT parameter set to N), and notify that you reset the table. nil,0.09,0.02 are the values for the zero point (nil = undefined, extn and color). We work with filter R.
AMAG/SOLVE std.tbl R ? 100 N nil,0.09,0.02 new
Kill a few stars:
AMAG/EDIT std D (D means "Do it, really delete"), to kill one star at the time.
AMAG/KILL std D
will kill a whole region of the plot.
Second attempt of photometric solution,
after editing out some points. We also filter out the stars with huge residuals:
AMAG/SOLVE std.tbl R ? 100 Y nil,0.09,0.02 abs(:dm_test).le.1.
Look at all the residuals and iterate.
AMAG/PLOT std R A
"A"ll the plots for filter R.
Re-plot the Magnitude plot to remove a couple of saturated stars
AMAG/PLOT std R F :stdmag
AMAG/EDIT std D
After more editing, try a full solution:
AMAG/SOLVE std.tbl R ? 111 Y
You are now happy with the solution. Copy the output of AMAG/SOLVE, and plot the summary sheed:
AMAG/PLOT std R A
Next filter:
Now, we can move to another filter: re-start with V, and use B-V as color term. Option new is mandatory.
AMAG/SOLVE std V ? 100 Y ? new

and so on...
Once your are happy with the photometric solution, you may want to print the plot ( copy/grap postscript ), and keep the summary for your logs: |Filter = R MAG = mag_instrum. + zero - extn*airmass + colr*(V-R) | zero = 25.882 +/- 0.017 (computed) | extn = 0.114 +/- 0.006 (computed) | colr = 0.035 +/- 0.0 (pre-set) 4R 6335.646 25.882 0.017 0.114 0.006 0.035 0.0 V-R ccp 0033
The last line is designed to be parsed by other programs.

3.3.- Command Reference Manual

3.3.1.- Standard Measurement Commands

SET/CONTEXT tmag
Load the package and defines the AMAG/* commands. If this is not done, the commands can be called using their file name as @@ amag_* .
AMAG/MES: measure the stars
First step is to measure the instrumental magnitudes of the stars. You need a set of flat-fielded images of standard stars, ideally taken in various filters. Lets call these frames stdFrame0001, stdFrame0002....
```
AMAG/MES    image pixScale posAng orientation
@@ amag_mes image pixScale posAng orientation
```
- Parameters:
  - image: input image (expects .bdf suffix)
  - pixScale: real pixel scale in arcsec (if the image is binned 2x2, give the original 1x1 pix.scale)
  - posAng: position angle of top of CCD, East of North, or AUTO for many VLT-compatible headers
  - orientation: +1 if E left of N, -1 if E right of N
- Usage:
  The image will be loaded. Click on one cross, and then on the corresponding star The prg will then compute the offset between the object and the catalogue, and measure all the stars in the catalogue.
  The output is a midas table t_inimage.tbl, where inimage is the name of the original image.
- Notes:
  - the coordinates are expected to be found in O_POS, in degrees
  - is posAng = AUTO, the angle is read in ESO.ADA.POSANG
  - the program knows only about Landolt's std in UBVRI
  - the program looks for the filter in FILTER or in ESO.INS.FILT1.NAME or ESO.INS.FILT1.NAME or FILTER
  - the prg tries to get the airmass from ESO.TEL.AIRM.START and ...END (averages them) or O_AIRM
  - the epoch is optained from o_time(4), and the exposure time from o_time(7)
  - if keyword OFFCENT/R/1/2 is defined, and contains an offset in pixel in X and Y, the positions of the standard stars are shifted by that offset, and the program will not ask the operator to click the star. As that offset is typically constant for a given instrument, this permits the automatic measurement of a catalogue of images.
- Example:
  For a SuSI2 frame, you would type:
  AMAG/MES stdFrame0001 0.0805 0. -1
  from there, you can measure the offset between the crosses and the star, and define the offset:
  WRIT/KEY offcent/r/1/2 12.,42.
  and then measure all the frames from that instrument:
  EXEC/CAT AMAG/MES std.cat 0.0805 0. -1
AMAG/MERGE: merge the individual measurement tables
All the t_stdFrame0001.tbl... tables created by AMAG/MES have to be merged into one single table.
```
AMAG/MERGE     in_cat.cat [out_tab.tbl] [prefix]                           
@@ amag_merge  in_cat.cat [out_tab.tbl] [prefix]  
```
- Parameters:
  - in_cat: the image catalogue that contains the measured images or the table catalogue that containes the measurment tables.
  - out_tab: the table that will contain all the measurements. Default is t_std.tbl
  - prefix: the prefix that was used to name the table during the measurements. Must be t_ (which is the default) if the in_cat is a catalogue of images measured with AMAG/MES. Can be set to null if in_cat is directly a catalogue of tables (i.e. no prefix needs to be added to the name).
- Example:
  AMAG/MERGE myImageCat.cat t_std.tbl
  AMAG/MERGE myTableCat.cat Standard.tbl null
AMAG/EXPTIME: normalize the exposure times
It is likely that the original frames were acquired with exposure times ranging between 10sec and 30sec or so. This command will correct the instrumental magnitudes to normalize the exp.time to 1sec.
```
AMAG/EXPTIME    intab [exptime] 
@@ amag_exptime intab [exptime] 
```
- Purpose: computes the exp-time normalized instrumental magnitudes mag = mag_mes + 2.5log(t)
- Parameters:
  - intab: input table, obtained with amag/merge, tmag/merge, amag/mes, tmag/mes or amag/objmes
  - exptime: if not give, the program looks for a column :exp_time, if :exp_time not present, looks for the o_time(7) descriptor of the original image. If exptime is given, it is used, over-riding automatic methods
- Example:
  AMAG/EXPTIME t_std.tbl
- Note: AMAG/EXPTIME can also be used to completely reset a table in case of disaster, as the original instrument magnitudes are used.

3.3.2.- Photometric Solution Commands

AMAG/SOLVE: Photometric solution
Computes the photometric solution on the measurements stored in a table generated by AMAG/MES and AMAG/MERGE.
```
AMAG/SOLVE measurements color DUMMY method [Ident?] [zero,extn,col] [Add_selec] [colr]
@@ amag    measurements color DUMMY method [Ident?] [zero,extn,col] [Add_selec] [colr]
```
- Purpose: compute a photmetric transformation
- Parameters:
  - measurements.tbl: table with the measurements
  - color: U, B, V, R, I, W(=wide VR), J, H, K or FILE: color to be processed. Other will be ignored for the reduction (which is done color by color)
  - dummy: not used anymore - for backw. compatibility (internally hardcoded to Landolt.tbl)
  - method: what is to be computed.
  -- Old method: one character sets what is computed and what is assumed:
```
               Zero Pt    Extinction    Colour term    
		A:   computed  Assumed=std/P6 assumed:def/p6 
		R:   computed     computed    assumed:def/p6 
		K:   computed  Assumed:std/p6    computed    
		C:   computed     computed       computed    
		Z:  Assumed/P6   Assumed/P6     Assumed/P6   
        
```
  -- New method: 3 characters setting what is Assumed, and what is Computed, resp. ZeroPt Extinction ColorTerm, eg CCC to compute everything. Can be written as a combination of A and C, or 0 and 1. Option K is equivallent to CAC or 101.
  - Id_found: Are the star already identified? Y/N. Set to N for first time, Y afterward. N also resets the table.
  - zero,ext,col: ZP, extincion and colorterm (resp) to be use for the solution, for the terms that are not computed (A/0 in the options). If given for an option set to C/1, it is ignored. If set to nil, use hardcoded default. Separate with comas
  - Add_select:
  --a. Additional selection to KEEP, like seq.ge.10.and.seq.le.20 or abs(:dm_test).le.0.5 No space allowed.
  --b. "new" when changing filter, this will compute the new idx and RESET all the selections. Mandatory for first execution, or for changing filter (if forgottent, expect strange results).
  - colr: color to be used for the color reduction, default R-I
- Input: measurements.tbl, created by AMAG/MES then AMAG/MERG (and AMAG/EXPT). Columns used: :MAGNITUDE, :airm, :filter.
- Output: new columns in meas.tbl::stdmag, :dmag, :extn
- Examples
  First attempt of a solution, computing only the ZeroPt. As this is a first pass, IDENT is N, and AddSel is new:
  AMAG/SOLVE std.tbl R ? CAA N nil,0.09,0.02 new
  Second attempt after editing out some points. We also filter out the stars with huge residuals:
  AMAG/SOLVE std.tbl R ? CAA Y nil,0.09,0.02 abs(:dm_test).le.1.
  After more editing, try a full solution:
  AMAG/SOLVE std.tbl R ? CCC Y
  Proceed to another filter:
  AMAG/SOLVE std.tbl V ? CAA Y nil,0.125,-0.05 new V-R
- GUI
  measurement.tbl is read from "Input Table"
  filter for the filter buttons
  the solution method from the 3 "Method" flag buttons
  The default values from the 3 "Defaults" boxes. Set to nil to use the internal defaults.
  Option "N"ot Identified and "new" are obtained by clicking [New/Reset and Solve]. Option "Y" (already identified) by clicking [Solve], which also takes into account the content "additional selection" box if the flag is clicked.
AMAG/PLOT: plot the magnitude residuals
The residual (standard - re-computed) of the photometric solution can be plotted as a function of several other parameters, permitting the identification of bad points (and later their removal) of trends which would correspond to poorly set terms in the solution.
```
AMAG/PLOT     meas color plot_flag  X Y [scale] [frame_diff?] [all_frames?]
@@ amag_plot  meas color plot_flag  X Y [scale] [frame_diff?] [all_frames?]
```
- Parameters:
  - meas: table containing the standard stars measurements and residual produced by AMAG/SOLVE
  - color: the filter to be considered (one letter)
  - plot_flag: how to plot
  -- F: full frame
  -- A: 4 small plots with epoch, airmass, mag and colors, as well as a summary of the solution. This is what you want to prind for your log book.
  --0, 1,2,3,4: internal commands plot only one quadrant
  - X
  -- columns to be plotted as X, must be :airm, :stdmag, :stdcol, :epoch, :xcen, :ycen
  -- 'label': no plot is generated, just info on the solution
  - Y columns to be plotted as Y; only :dm_mag at this point
  - scalex x1,x2: x plotted from x1 to x2. If not set, the program will either guess or use default.
  - frame_diff Y: different symbol is used for each image (experimental)
  - all Y: plot deleted stars. N (default): only active stars
- Examples:
  AMAG/PLOT std R F :stdmag
  plots the resudual as a function of the magnitude, full frame.
  AMAG/PLOT std R A
  plot the residuals as 4 small plots, plus a summary of the solution.
- GUI:
  The meas table is read from the "Input Table" box. The filter is read from the filter buttons. The various options for the type of plots are available from the Plot buttons.
AMAG/EDIT:Remove a bad point from the photometric solution
```
AMAG/EDIT     table Delete? [AdditionalSelection]
@@ amag_edit  table Delete? [AdditionalSelection]
```
- Purpose: Identify, and possibly mark the measurement corresponding to a point in a plot generated by AMAG/PLOT. Marked stars are not used by AMAG/SOLVE.
- Parameters:
  - table: a table processed by AMAG/SOLVE, and currently plotted by AMAG/PLOT.
  - Delete: N (Default) will just identify the point selected, D will additionally mark that star so that it is not taken into account in a subsequent fit with AMAG/SOLVE.
  - Additional selection: to restrict the points to be considered.
- Notes:
  - This command is kind of obsolete, compared to the more powerful AMAG/KILL.
  - After sending the command, identify one point on the plot by clicking it with the 1st button of the mouse.
  - This will work only on plots generated by AMAG/PLOT with the F (full frame) option. Running it on other plots might have some surprizing effects.
  - With option D, the stars are not deleted, just marked. A table can always be completely re-set by running AMAG/SOLVE with IDENT=N and new.
  - to identify/delete more than one star, re-run the command as many times as needed.
  - to reset a table (e.g. if too many stars were deleted), re-run AMAG/SOLVE with option new.
- Examples:
  AMAG/EDIT std D
  identifies a star and marks it as deleted
- GUI: This command is accessible with the [Delete 1 point] button (option D), or [Ident. 1 point] (option N).
AMAG/KILL: Remove a region of bad points
```
AMAG/KILL     table Delete? 
@@ amag_kill  table Delete? 
```
- Purpose: Identify, and possibly mark the measurement corresponding to a region in a plot generated by AMAG/PLOT. Marked stars are not used by AMAG/SOLVE.
- Parameters:
  - table: a table processed by AMAG/SOLVE, and currently plotted by AMAG/PLOT.
  - Delete: N will just identify the point selected, D (default) will additionally mark that star so that it is not taken into account in a subsequent fit with AMAG/SOLVE.
- Notes:
  - click two opposite corners of a rectangle. All points contained in the rectangle will be marked as bad.
  - After sending the command, identify one point on the plot by clicking it with the 1st button of the mouse.
  - This will work only on plots generated by AMAG/PLOT with the F (full frame) option. Running it on other plots might have some surprizing effects.
  - With option D, the stars are not deleted, just marked. A table can always be completely re-set by running AMAG/SOLVE with IDENT=N and new.
  - to identify/delete more than one star, re-run the command as many times as needed.
  - to reset a table (e.g. if too many stars were deleted), re-run AMAG/SOLVE with option new.
- Examples:
  AMAG/KILL std D
  identifies many star and marks them as bad.
- GUI: This command is accessible with the [Delete Region] button (always in D mode).

3.3.3.- Object Measurement Commands

amag_objmes: measures one object
```
@@ amag_objmes image diap_diam [pixScale]
```
- Purpose: measures one object in an image
- Parameters:
  - image: input image.
  - diap_diam: diameter of the diaphragm. Must star with @, a or s. @: diameter measured in unit of pixels. a: measured in arcsec. s: measured in unit of seeing.
  - pixScale: pixel scale (arcsec/pix), used in option a above.
- Notes:
  - can be used with EXEC/CAT
  - output in tm_{image}.tbl
  - results to be processed with amag_comp.
amag_comp: computes the magnitude of an object
```
@@ amag_comp inTab [solution]
```
- Purpose: Deals with a table that was obtained with various amag_objmes measurements. These tables are merged using amag_merge, and time normalized with amag_exptime. The table can contain as many measurements and filters as desired, but for only one object. This program will apply the photometric solution computed by amag/solve to the measurements of the objects. The color correction is applied iterativelly till the result converges. If some filters are missing, the color correction is computed assuming a standard TNO color.
- Parameters:
  -- intab: input table, obatained with amag_objmes, then amag_merge and amag_exptime. Must contain measurments of only one object, but as many measurements in as many filters as desired.
  -- solution: an midas include file containing the photometric solution, as in the example below. To test the file, execute @@ solution
  --example of solution include file:
```
! FORS2, october run
!
!-- zero points and their sigma
DEFI/LOC zero/R/1/5 -99.,26.967,27.31,27.482,26.533     ! U B V R I
DEFI/LOC zeroS/R/1/5 -99.,0.013,0.009,0.021,0.014       ! U B V R I
!
!-- extinctions and their sigma
DEFI/LOC extn/R/1/5 -99.,0.24,0.112,0.091,0.061 !U B V R I
DEFI/LOC extnS/R/1/5 -99.,0.007,0.005,0.007,0.006       ! U B V R I
!
!-- color terms and their sigma
DEFI/LOC color/R/1/5 -99.,-0.067,0.029,-0.010,-0.022    ! U B V R I
DEFI/LOC colors/R/1/5 -99.,0.006,0.004,0.011,0.006      ! U B V R I
!
!-- color used
defi/loc cindexU/c/1/3 U-B
defi/loc cindexB/c/1/3 B-V
defi/loc cindexV/c/1/3 B-V
defi/loc cindexR/c/1/3 V-R
defi/loc cindexI/c/1/3 V-I
```

3.3.4.- Instrument-specific commands

These commands are primarilly designed to be used as a quick-look tool when observing with WFI, EFOSC2, SuSI2 and EMMI-red. Probably of not much use for anybody else.

Each of the following command exist for the 4 instruments. Just replace INST by EMMI, SUSI, WFI or EFOSC.

INST/list: list the standard frames in the current directory.
Not a very clever command, but quite useful. It lists all the files with the type "STANDARD" in the current directory.
```
WFI/lis
```
INST/ZP: automatic measurement of a raw frame.
```
WFI/ZP       WFI_Ima.123.fits
@@ WFIamag_mesAuto WFI_Ima.123.fits
```
The quick-look wrapper. It will read the file in Midas (if needed), measure each chip with WFIamag/mes, correct for the exposure time, computes an average zero point per chip (using internal command WFIamag_oneZero) store the ZP in a table WFIzp (located on the E2P2OPS directory), and plot the evolution of the ZP per chip.
It calls a modified version of amag/mes, taylored for automatic measurements on the considered instrument. For the first measurement in the current directory, the program will load a default centering value, and will ask for interactive confirmation. For further measurements in the same Midas session, it will use the centering offset obtained interactivelly.
To reset this auto-centering, DELE/KEY centerx
The program rejects poorly identified stars, and saturated stars, and rejects the whole CCD subframe in case less than 30% of the stars in the field were properly identified.
In addition to the 1-letter filter ID, the original filter name is kept in col. :ffilter ("full-filer"), so that the analysis can be done separately for different filters of the same type (B123 vs B99).
The program stores the individual measurements in a table named zp_INST.date.tbl stored in /data/{TELESCOPE}OPS/pipeline/INST/Photometry. The history database is INSTzp.tbl in the same directory.

O.Hainaut

File archive:

Retreive the latest version from this list

tmag_2013-02-10.tar.gz
tmag_2004-10-04.tar.gz
tmag_2003-10-25.tar.gz
tmag_2002-08-19.tar.gz
tmag_2001-09-22.tar.gz
tmag_2001-03-11.tar.gz

TMAG

Photometric package for ESO/MIDAS

1.- Introduction

2.- Download and installation

3.- User's manual

3.1.- Introduction

3.2- Cookbook

3.3.- Command Reference Manual

3.3.1.- Standard Measurement Commands

`SET/CONTEXT tmag`

`AMAG/MES: measure the stars`

`AMAG/MERGE`: merge the individual measurement tables

`AMAG/EXPTIME`: normalize the exposure times

3.3.2.- Photometric Solution Commands

`AMAG/SOLVE`: Photometric solution

`AMAG/PLOT`: plot the magnitude residuals

`AMAG/EDIT`:Remove a bad point from the photometric solution

`AMAG/KILL`: Remove a region of bad points

3.3.3.- Object Measurement Commands

`amag_objmes`: measures one object

`amag_comp`: computes the magnitude of an object

3.3.4.- Instrument-specific commands

`INST/list`: list the standard frames in the current directory.

`INST/ZP`: automatic measurement of a raw frame.

File archive:

TMAG

Photometric package for ESO/MIDAS

1.- Introduction

2.- Download and installation

3.- User's manual

3.1.- Introduction

3.2- Cookbook

3.3.- Command Reference Manual

3.3.1.- Standard Measurement Commands

SET/CONTEXT tmag

AMAG/MES: measure the stars

AMAG/MERGE: merge the individual measurement tables

AMAG/EXPTIME: normalize the exposure times

3.3.2.- Photometric Solution Commands

AMAG/SOLVE: Photometric solution

AMAG/PLOT: plot the magnitude residuals

AMAG/EDIT:Remove a bad point from the photometric solution

AMAG/KILL: Remove a region of bad points

3.3.3.- Object Measurement Commands

amag_objmes: measures one object

amag_comp: computes the magnitude of an object

3.3.4.- Instrument-specific commands

INST/list: list the standard frames in the current directory.

INST/ZP: automatic measurement of a raw frame.

File archive:

`SET/CONTEXT tmag`

`AMAG/MES: measure the stars`

`AMAG/MERGE`: merge the individual measurement tables

`AMAG/EXPTIME`: normalize the exposure times

`AMAG/SOLVE`: Photometric solution

`AMAG/PLOT`: plot the magnitude residuals

`AMAG/EDIT`:Remove a bad point from the photometric solution

`AMAG/KILL`: Remove a region of bad points

`amag_objmes`: measures one object

`amag_comp`: computes the magnitude of an object

`INST/list`: list the standard frames in the current directory.

`INST/ZP`: automatic measurement of a raw frame.