Previous: ReduceNight  Up: Contents   Next: Coherent Analysis

List of Procedures in MIA

Index

  1. xmidispvisi - the core of MIA
    1. Creation & Initialization
    2. The Graphical User Interface
    3. Routines dealing with the Mask
    4. How to measure the White Light Fringe Amplitude
    5. Wavelength Calibration and Binning
    6. Thresholds for Signal and Noise Scans
    7. Intermediate Results
    8. Final Results
    9. Print the Results
    10. Clean up after you're done
  2. Photometry
    1. chop_nod_disp - analyse dispersed photometric data
    2. chop_nod_phot - analyse undispersed data (e.g. acquisition images)
  3. Helper Routines
    1. midifile_search - find MIDI files matching given criteria
    2. make_maskname - derive name of mask from name of MIDI file
    3. make_midi_log - print overview of files
    4. MIDIname_... - extract parts of MIDI file name
    5. mtv - display image data in MIDI format
    6. baseline - find length and position angle of the projected baseline
    7. plot_visibility - plot one or more visibility curves

xmidispvisi

 This is the core of MIA, the object that does all the work, solves all the problems, answers all the questions, and helps to write the Nature papers. Ok, it's object-oriented, but there's no reason to be afraid, objects don't bite, unless you tell them to.

Creation / Initialization

Objects are like universes, in the beginning, they have to be created. Xmidispvisi objects differ, however, they need some MIDI data to work with. So the syntax to create an xmidispvisi-object, read in the data, and initialize everything, is 

   x = obj_new('xmidispvisi',fringefile,photfileA,photfileB[,options])
(Note that the part in [...] is optional, that's why it's called options. The names of the options are in fact different, see below.)

There is also a shortcut for people who are too lazy to type all that, to challenged to get words with more than 4 letters right, or too scared of objects to call them bu name: 

   x = xmdv(files[,options])
Here, the three filesnames have to be given in an array. This is quite handy, since midigui returns the filenames in an array already. The order of files in the array is not important, xmdv will try to figure out which file has the fringes and which have the photometry, and crash happily if it can't.

Since January 2007, you can feed xmdv an array with even more files, and it will create an xmidispvisi-object for every triple of fringe-track, photometry A, and -B files. The results will be returned in an array of objects.

There are a number of options that can be used with obj_new and xmdv. The most important are top secret, the not-so-important important are (in alphabetical order, not order of unimportance):

All the magic happening when the object is created and initialized should be described elsewhere in this manual.

The Graphical User Interface

The GUI is started by telling the object to start it: 

   x->gui

There are two options for this command:

The GUI itself has many menus, buttons, and plots for you to play with, which should be described elsewhere.

The diagrams in the GUI are scaled automatically by default, but according to Murphy's law, this does never work quite right. Since version 1.3, there are a number of routines to set the limits (only the long diagrams in the upper half of the window, feel free to implement something similar for the others).

All routines expect an array with two values as input, which gives the minimum and maximum of the corresponding axis. Currently, the routines do not re-plot the data, so to see their effect, you have to re-start the GUI.

To obtain the information shown in the GUI in a postscript-file, use 

   x->hardcopy, filename, /NOCOLOR, /TRACES, /DONTCLOSE
filename is the name of the ps-file to print to, if omitted, it will be created from the name of the fringe data. /NOCOLOR prints in black and white, /TRACES prints the traces, too, and /DONTCLOSE doesn't close the file afterwards, so you can append more plots.

Routines dealing with the Mask

The mask is handled by an object that is described elsewhere. This object is embedded in the xmidispvisi-object, so you don't have to worry about its creation, destruction, and funeral. There are a few functions in xmidispvisi to access it:

Get the traces (i.e. the position and FWHM of the masks).
Up to and including MIA+EWS version 1.1: 

   tr = x->get_trace(i,/WIN1,/WIN2)

i selects the dataset: -1 is the fringe data, 0 is photometry A, 1 is photometry B. If /WIN2 is set, the trace of window 2 will be returned, else that of window 1.
Since MIA+EWS version 1.2: 

   tr = x->get_trace(i,WIN=w)

i selects the dataset: -1 is the fringe data, 0 is photometry A, 1 is photometry B. If WIN is not set, an array of the traces for all windows is returned. If WIN is set, only the trace for this window is returned. WIN can be 1 or 2 for HIGH_SENS data, or 1-4 for SCI_PHOT data.

tr is a midisptrace structure (or an array of those):
tr.trace   the measured position of the peak as function of pixel number
tr.FWHM   the measured FWHM
tr.fluxmax   the height of the peak (as returned by the 1D-gaussfit)
tr.range   the indices of good trace-measurements
tr.nRange   the number of good measurements
tr.trace_coeff  the coefficients of the trace-polynomial
tr.sigma_coeff  the coefficients of the sigma-polynomial

Show the traces 

   x->show_traces, filename
Calls the routine with the same name in the mask-object. Nobody knows what might happen then.

Open the Mask-GUI 

   x->maskgui
calls the gui-function of the mask object. Note that changes to the mask have no effect once the xmidispvisi-object is initialized, you can use the mask-GUI only to check the parameters. Any changes to them will be ignored.

How to measure the White Light Fringe Amplitude

To decide whether a scan was at the right spot in OPD or not, MIA uses the fringe amplitude of the white light (i.e. integrated over the full N-band). Unfortunately, if MIDI was tracking at an OPD different from zero, the fringe amplitude of the white light is always low (because the fringe packet with a wide wavelength band is too small). This is often the case if dispersed fringe tracking is used. Our way around this problem is to split the N-band into a number of narrow(er) bands, measure the fringe amplitude in each of them, and sum up the results.

To enable this, use 

   x->make_white_fringe
The (current) default is to integrate the light. To enable the code for dispersed fringe tracking, use 
   x->make_white_fringe, /BINS
The default is to use 10 bins, which is enough for the standard OPD offset. If you think you need a different number of bins, give it after the BINS keyword, e.g. 
   x->make_white_fringe, BINS=14

Wavelength Calibration and Binning

To find out what the object thinks the wavelengths are, ask it: 

   lambda = x->lambda()
Returns an array that gives wavelength in microns as function of pixel number. If you want or need the wavelength as function of wavelength bin, see photometry or correlflux.

If you want to convince the object that the wavelengths are different, tell it: 

   x->set_lambda, lambda
This sets the wavelength as function of pixel number. This might be useful with GRISM-data, where the default wavelength calibration is less than perfect. Of course, I would like to improve this, so if you happen to have a better one and are willing to share it, tell me.

Wavelength Binning

Look at the wavelength-binning parameters and set them interactively: 

   x->lambda_gui

Find out what the parameters are in a script or from the command line: 

   array = x->get_lambda_bins()
array[0]: the number of the first column used
array[1]: the number of the last column used
array[2]: the spacing between columns
array[3]: the number of columns added for one bin.

Set the parameters: 

   x->set_lambda_bins, start, end, step, width
start  the number of the first column used
end   the number of the last column used
step   the spacing between columns
width  the number of columns added for one bin.

For example: 

   x->set_lambda_bins, 0, 100, 25, 50
will set bins from 0 to 49, 25 to 74, 50 to 99, 75 to 124, and 100 to 149 pixels.

It is checked if the start and end values are within the detector window. If not, they are set to 0 and the highest pixel number. If you pass the two values via variables, you can find out what they are set to afterwards: 

   lstart = -1
   lend   = 999
   x->set_lambda_bins, lstart, lend, 3, 3
   print, lstart, lend
will probably give the result: 
       0     170
Why this doesn't work if start and end are given as numbers is left as an exercise to the reader.

Thresholds for Signal and Noise Scans

There are three parameters that control which scans are used to estimate the signal and the noise:

To find out what the thresholds are: 

   ts = x->get_thresholds()
The return value is an array of the three thresholds:
ts[0] the "good" threshold for scans used to estimate the signal
ts[1] the "bad" threshold for scans used to estimate the noise
ts[2] the noiseopd.

Set the thresholds: 

   x->set_thresholds, signal, noise, noiseopd
All parameters are optional. You will get a warning message if the noise threshold is larger than zero, or if the noiseopd is so small that you still have signal in the scans selected by it.

Finally, if you want to know how many scans get selected by those thresholds: 

   goodbad = x->get_percent_goodbad()
Returns the percentage of good and bad scans with the current thresholds.

Intermediate Results

Get the amplitude of the white light fringe: 

   a = x->whitefringeampl()
returns an array of the amplitude of the fringes in the white light, as function of scna-number. Unless DISPERSEDTRACK was used when the object was initialized, we integrated over wavelength first, and then determine the fringe amplitude! This is the quantity used to select scans with signal based on the "good" threshold.

Get the fringe signal: 

   fringes = x->fringes()
returns a 3D-array: fringes[0,*,*] is the opd, fringes[1,*,*] is the fringe signal, i.e. the difference in flux between the two interferometric channels. Note that this is integrated over wavelength. The second index counts the frame-no within a scan, the third index is the scan-number.

Get everything there is to know about the fringes: 

   dispfringes = x->dispfringes()
returns the spectrally dispersed fringe signal. The first index is the wavelength, the second the frame within a scan, and the third is the scan-number. The careful reader will have noticed that the fringe signal returned by x->fringes() can be obtained by integrating dispfringes over the first index, i.e. total(dispfringes,1).

Find out where the telescopes were pointing: 

   tartyp = x->tartyp()
returns an array of strings, one for each scan. The value of a string is "T" if the telescopes were pointing at the target during the corresponding scan, it is "S" if they were pointing at the sky, and "U" if they were doing funny things during the scan (like switching from target to sky in the middle of the scan).

Only scans pointing to the target are used to select "good" scans (those with fringe signal).

Get the filenames etc. (useful in scripts): 

  object    = x->get_objectname()
  fringefile= x->get_filename()
  photfiles = x->get_filename(/PHOT)
  maskfile  = x->get_filename(/MASK)
Photfiles is an array of filenames, the other results are simple strings.

Final Results

(Well, actually the results are only as final as you get them from MIA, you still have to interpret them and write the Nature paper yourself).

Photometry = Uncorrelated Flux (in fact, spectra): 

   phot = x->photometry(/Atotal,/Aphot,/Btotal,/Bphot,/Quiet,/PLOT)
returns a 3 by N array, where N is the number of bins in lambda. The first row (phot[0,*])is the wavelength in the center of the bins, the second row (phot[1,*]) is the width of the wavelength bins, and the third row (phot[2,*]) is a photometric spectrum in ADU/sec, binned in wavelength according to the wavelength-binning parameters.

Without any keywords, sqrt(A1*B1)+sqrt(A2*B2) is returned, which happens to be the combination of the fluxes we measure in the fringe signal (see this PDF-document). With keywords /Atotal or /Btotal, the total photometric flux from telescope A or B is returned. The keywords /Aphot and /Bphot (introduced on October 12., 2005) are only valid with data taken in SCI_PHOT-mode. They return the spectra in the additional channels in the photometric data files. The wavelength is not correct for these spectra!

For historic reasons, there is another way to get the spectra: 

   spec = x->get_photometry(LAMBDA=lambda,/Atotal,/Btotal,/PLOT)
This function may be removed in the future, therefore you should not use it in new code.

Correlated flux 

   cf = x->correlflux(/PLOT,/CFPLOT,/SSN)

returns a 3 by N array, where N is the number of bins in lambda. The first row (cf[0,*])is the wavelength in the center of the bins, the second row (cf[1,*]) is the width of the wavelength bins, and the third row (cf[2,*]) is the correlated flux in ADU/sec.

The keyword /PLOT will plot the good and bad fringes in the lambda bins, and the correlated flux. Keyword /CFPLOT will plot only the correlated flux. To plot it again, use

   plot, cf[0,*], cf[2,*], ystyle=2

The secret keyword /SSN (for "Same Sky Noise") will estimate the noise from the same scans as the correlated flux. Contact an expert before you attempt to use it.

Visibility 

   visi = x->visibility(/PLOT,/VISPLOT)
The result has the same format as the result of correlflux(), except that visi[2,*] is the visibility, defined as 
   correlated_flux / uncorrelated_flux
as obtained from x->get_photometry and x->correlflux.
The keywords are secret and won't be explained here.

Instrumental Visibility from a Calibrator 

   insvis = x->instruvisi(diameter,NAME=name)
diameter is the diameter of the calibrator in mas. If the object is listed in the calibrator database, the diameter can be omitted. The name that should be used to find the object in the database can be given with the NAME parameter, otherwise the name given in the FITS-header will be used (which may or may not be correct). insvis is another 3 by N array with wavelengths and visibilities.

Calibrate a Science Target 

   calvis = x->calibratedvisi(cals,diameter,NAME=name,/plot,/visplot)
cals is an array of the xmidispvisi-objects of the calibrators you wish to use (can be an array with only one element). The instrumental visibility is obtained from each calibrator and the results averaged. Diameter and name are used to call its instruvisi()-function. This makes sense only if all the calibrator-objects are observations of the same calibrator, otherwise you have to rely on the automatic lookup in the calibrator database. The binning in lambda of the calibrator objects is set to the same values as in the science object.

Projected Baseline (since July 18., 2006) 

   base_len = x->baseline, base_pa, /QUIET
Returns length and position angle of the baseline projected on the plane of the sky. There is also another baseline-routine that can be used without an object.

Save the Visibility (since October 5., 2005) 

  x->save_visibility [, filename]
Although visibilities are not yet on the list of endangered species, you might want to save them. This routine writes it to a FITS-file in the standard format for visibilities specified by the IAU. If filename is omitted, a dialog will pop up and ask for it.

Print an Overview of the Results

(since October 12., 2005) 

   x->print_results [, filename] [, CALIBRATOR=cal]
prints photometric and correlated flux, the visibility, and the power spectra to a postscript file. The name can be given as argument, otherwise the name is MIAplots*.ps, where * is replaced by the date and time of the first fringe file.

The xmidispvisi-object of a calibrator star can be given with the CALIBRATOR-option. In this case, the fluxes and visibility of the calibrator, as well as the calibrated visibility of the science target are printed, too.

Destroy the object and hide the body

 

   obj_destroy, x
will remove the object from memory. If you do not destroy it before re-using the variable, the object will continue to haunt your computer like a zombie. The only way to get rid of it once the reference to it is lost is to call the IDL garbage-collector with heap_gc. If you don't do this, the memory of your computer will be filled with xmidispvisi-objects until it either explodes or collapses into a black hole (depending on the internal pressure of the objects, the theory of collapsing objects is beyond the scope of this manual).

Photometry

There are currently two routines in MIA that deal with photometry. Both are independent from the xmidispvisi-object.

chop_nod_disp

Like chop_nod_phot, but for dispersed (PRISM) data.

chop_nod_phot

Routine to measure photometry on chopping or nodding data.
Usage for chopping data: 

  chop_nod_phot, files
Usage for nodding data: 
  chop_nod_phot, files_on_star, files_on_sky
The "files" should be like the result of midigui("gorgonzola"), i.e. strings with space-separated names of all the files belonging to one dataset.

As a result, the routine creates a subdirectory PHOTOMETRY and creates a "Mask_*.fits" and a "Phot_*.txt" file, where "*" is the date and time part of the input filename. Mask*.fits contains the MIDI-mask used to extract the flux from the frames. The same mask should be used to extract the fringes. Phot*.fits is a simple text-file with the results of the photometry.

Here is an example: Start IDL and type 

  files = midiguida(dir=mididata0224,filter="*_[0-9][0-9].fits")
Select a chopping dataset, e.g. MIDI.2003-02-24T00:13:07.000_01.fits and click on "Select". Now do the photometry: 
  chop_nod_phot,files
It will first tell you that it treats the data as chopping data. Then it will display the gaussian fit that is used to find the position of the star. If you are happy with the result, hit return, "n" and return otherwise. Then it does aperture photometry with increasing radii and selects the best radius based on a convergence estimator. Finally, it prints some results to the screen and to the file PHOTOMETRY/Phot_2003-02-24T00:13:07.000_01.txt

For nodding data (if you managed to find some), start midigui as above, but pick the file on the object and the file on the sky of a nodding sequence, e.g. MIDI.2003-02-24T00:17:05.000_01.fits and MIDI.2003-02-24T00:17:57.000_01.fits.

Do the photometry like this: 

  chop_nod_phot, files[1], files[0]
It should tell you that it assumes nodding data, the rest should be like in the case of chopping.

Helper Routines

In this section a number of routines are described that might be useful for you.

midifile_search

Uses the IDL-function FILE_SEARCH to search files, checks which fulfill the criteria given by the caller, combines files belonging to the same data sets, and returns the result as an array: 

  files = midifile_search(paths[,options])
paths is a scalar string or an array of strings giving the path to the for MIDI files. If the PATTERN-option is not used, path should end in a pattern like "MIDI.*.fits" to make sure only valid MIDI FITS-file are checked.

Options are:

The following options can be used to obtain additional information about the data selected. They create string arrays with one entry for each file name:

make_maskname

Find out what the name of the mask created by chop_nod_phot is: 

   maskname = make_maskname(MIDI-file)
maskname will be the name of the mask created by chop_nod_phot if you give it "MIDI-file" as first argument.

make_midi_log

Print an overview of the parameters of the data-files in a directory: 

   make_midi_log, directory-name
The name of the output file can be given via the LOGBOOK-parameter, e.g. 
   make_midi_log, directory_name, LOGBOOK= directory_name+'.log'

mtv

Routine that puts MIDI-windows together into one array and calls atv with that array. Atv is an IDL-routine for displaying images (a kind of saoimage-clone written in IDL). It was written by Aaron Barth, its homepage is http://www.physics.uci.edu/~barth/atv/. 

   data = oirgetmeanrms(filename)
   mtv, data[1]
All the flags known by atv can also be used with mtv.

If data contains two data-tags (data1 and data2), they are displayed side by side, data1 to the left and data2 to the right. If data contains four data-tags (data1, -2, -3, and -4), the layout is this: 

	+-----------+
	|data1 data2|
	|           |
	|data3 data4|
	+-----------+
If the number of data-tags is not two or four, you are in trouble.

baseline

 

  baseline, filename, LENGTH=length, ANGLE=angle, /QUIET
Computes length and position angle of the baseline projected on the sky at the time of the observation in file "filename". The results are returned in the variables specified and printed on the screen (unless the option /QUIET was given).

The Name-utilities
str = MIDIname_date(filename) returns the date part of a MIDI filename
str = MIDIname_time(filename) returns the time part of a MIDI filename
str = MIDIname_datime(filename) returns the date and time part

plot_visibility

Plot the visibility as returned by x->visibility(), x->instruvisi(), or x->calibratedvisi(): 

   plot_visibility, vis1, vis2, ...
Up to five visibilities can be given. It also accepts all the keywords of IDL's plot-command, in particular YRANGE.

Previous: ReduceNight  Up: Contents   Next: Coherent Analysis
Rainer Köhler, 2-Jan-2007