	IDL Utilities for the OI_DATA Exchange Format

	John D. Monnier (monnier@umich.edu)
	University of Michigan, Astronomy Department

MODIFICATION HISTORY
	Release 0, 2003 February
	v0.1, 2003Feb13, updated OITARGET columns
        v0.2, 2003Feb18, now compatible back to IDL v5.1 (avoid structure 
	      concatenation problems); fixed small problems
	v1.0, 2003Apr07, no changes. but OI-DATA format 'frozen' at 1.0
	v1.1, 2003Jul01, Added merge_oidata; sped up concat_oitable for IDL>5.1
	v1.2, 2003Sep26, Added extract_*data, fixed small datatype bug in 
			write_oidata
	v1.3  2007Jan17	 New release with a few added routines.

LICENSING

This software is released into the public domain, in the hope that it
will be useful. There is of course no warranty of any sort.


GETTING THE SOFTWARE

You should be able to obtain software from the following link:
     www.astro.lsa.umich.edu/~monnier/oi_data

In order to function, the routines require a recent IDL Astrolib to be
installed on your machine, which can be found at
   http://idlastro.gsfc.nasa.gov/homepage.html
(most importantly, the fits_bintable distribution!)


OVERVIEW

Here is an IDL library designed to read and write optical interferometry
data conforming to the OI-DATA standard, as described on
   http://www.mrao.cam.ac.uk/~jsy1001/exchange/

All features of the OI-DATA format are supported in this release, including
the ability to read and write multiple OI-ARRAY, OI-WAVELENGTH, OI-VIS,
OI-VIS2, and OI-T3 binary tables.  This should make merging data from
different epochs and arrays very straightforward (see OI-DATA
standard for important specifications, such as having unique ARRNAME and
INSNAME for internal table cross-referencing).  

Each of the 6 allowed OI-DATA tables, OI-ARRAY, OI-TARGET,
OI-WAVELENGTH, OI-VIS, OI-VIS2, and OI-T3, is converted from FITS into
an IDL structure (see define_oi*.pro for structure definitions).
While values are stored directly in the structure when possible,
pointers (to vectors of length NWAVE) must be used in order to
accommodate the full standard which allows multiple OI_WAVELENGTH
tables.  Again, I refer you to the define_OI* files to see easily
the internal storage format.

Using the read_oidata.pro and write_oidata.pro, one should be able to
easily use OI-DATA in the IDL data analysis environment.  Hopefully, this 
will stimulate the adoption of OI_DATA format by the current
interferometer groups, especially those using IDL.  More information can 
be found in the headers of read_oidata.pro and write_oidata.pro routines.


FUTURE RELEASES

************************************************************************
I would appreciate hearing all bug reports and will endeavor to fix
problems in a timely fashion. In addition, I plan to maintain these
routines into the future as the OI-DATA format evolves.

Further, I hope to eventually include additional IDL utilities authored 
by others which add functionality to the library.
************************************************************************


EXAMPLES

 In order to read in the tables from the 'testdata.fits' file which
is distributed by John Young (http://www.mrao.cam.ac.uk/~jsy1001/exchange/)
one merely executes the following IDL command:

IDL> READ_OIDATA, 'testdata.fits', oiarray,oitarget,oiwavelength,$
     oivis, oivis2,oit3, /inventory
	This file Satisfies the requirements of the OI_DATA format
	Inventory:
	  OI_ARRAY:             1
	  OI_TARGET:            1
	  OI_WAVELENGTH:        1
	  OI_VIS:               1
	  OI_VIS2:              1
	  OI_T3:                1
	 Unknown Tables:        0
IDL> print,oivis2(0).time,*oivis2(0).vis2data,*oivis2(0).vis2err
         82810.000      0.67700000     0.064000000
IDL> print,string(*oivis(0).flag)
	   F

Writing the oi-data back is just as easy:

IDL> WRITE_OIDATA, 'testdata1.fits', oiarray,oitarget,oiwavelength,$
	oivis, oivis2,oit3


Also, the IDL reader can handle more complex files. I have included in this
distribution the test file 'bigtest.fits', which contains multiple
instances of tables (although the values are nonsensical).

IDL> READ_OIDATA, 'bigtest.fits', oiarray,oitarget,oiwavelength, $
     oivis,oivis2,oit3,/inventory

This file Satisfies the requirements of the OI_DATA format
Inventory:
  OI_ARRAY:             2
  OI_TARGET:            1
  OI_WAVELENGTH:        2
  OI_VIS:               2
  OI_VIS2:              2
  OI_T3:                2
 Unknown Tables:        0


---------------------------------------
FILES

The files in this package are as follows:

README			This file
bigtest.fits		Test FITS file containing full richness of 
			OI-data format
make_testfits.script	IDL script to create bigtest.fits
testdata.fits		A very basic test FITS file distributed by J. Young
read_oidata.pro		Routine to read oidata FITS files
write_oidata.pro	Routine to write oidata FITS files
define_oiarray.pro	Defines OI-ARRAY data structure
define_oitarget.pro	Defines OI-TARGET data structure
define_oiwavelength.pro	Defines OI-WAVELENGTH data structure
define_oivis.pro	Defines OI-VIS data structure
define_oivis2.pro	Defines OI-VIS2 data structure
define_oit3.pro		Defines OI-T3 data structure
define_vis2data.pro	Defines the vis2data structure (see extract_vis2data)
define_t3data.pro   	Defines the t3data structure (see extract_t3data)
concat_oitable.pro	Used to concatenate like structures (workaround for
			 IDL v5.1)
merge_oidata.pro	Used to combine oidata.fits files
extract_vis2data.pro	Extract data into 'usable' IDL variables, given 
			some constraints
extract_t3data.pro	See above.

In addition, there are few extra routines for averaging.

vis2data_aziavg
t3data_uvavg
vis2data_uvavg
t3data_tavg
vis2data_tavg

And I've included a few necessary helper routines:

ri2at
wtd_mean
wtd_mean_angle
angle_diff
uvchunks
timechunks

