=head1 NAME fitsio_merge - WCS-based general purpose catalogue matching software =head1 SYNOPSIS B I I I<......> I [] =head1 DESCRIPTION B generic program for matching CASU-style FITS binary table catalogues and merging the photometric, astrometric and classification information together. Forms the basic driver for eg. multipassband CMD generation and multicolour master catalogue generation (the alternative is to use a deep stacked image eg. from I followed by I to derive a deep master catalogue). Embedded pointer records refer back to the original catalogue entries for more complete catalogue information requirements. The output FITS binary merge table headers enfold all the astrometric, and photometric calibration information required to produce CMDs and so on. Only generic CASU-style multi-extension input FITS catalogues may be used as input. The WCS information is used to define a standard coordinate transformation as the basis for further refinement of the differential astrometry. The current version can optionally match up to 12 files in a single pass and produces output where each row summarise the flux, differential postiion (standard coordinates in arcsec) and classification information for each image. Although the first file is used as a reference (for differential astrometric matching) images not in the reference set are mutually matched between other passbands by iteratively combining otherwise unmatched images. In this way a unique master catalogue of images appearing in at least one or more passbands can be created. =head1 OPTIONS The following arguments are required: =over =item I CASU FITS binary table to be used as the reference catalogue for coordinate mapping. =item I Second FITS binary table catalogue to be be matched onto the reference system =item I<........> subsequent catalogue files, up to 12 in total for matching. =item I The file for the resulting merged FITS binary table output. The format of this file is given below. =item I An optional `hidden' switch allowing the use of the following overrides: B disable astrometric refinement during the merge process B do not use the WCS information, base matching on pixel coordinates B produce lots of diagnostic output B disable in-built ZPN photometric distortion correction (see http://www.ast.cam.ac.uk/vdfs/docs/reports/astrom/ for explanation) =back =head1 DESCRIPTION OF OUTPUT FILE The merged catalogues are in the form of FITS binary tables with a standard empty primary HDU. The extension contains the merged file information. Note that for simplicity in writing code to access these files, all the numbers in the columns are, as for the catalogue files, deliberately stored as real*4 even though some of them would more naturally be integers. Each detector occupies a separate merge file extension with sufficient header information to identify object location, which detector, original WCS catalogue data and so on. For each file merged, including the reference, there are 6 column entries plus two additional columns explicitly listing RA and Dec in radians. Hence the no. of matched files can be deduced from (#TFIELDS-2)/6, or by interpreting the FITS header directly. The reference file, against which the comparison files are matched, has:- Standard coordinates in arcsecs with respect to TPA and TPD (see header) from which celestial coordinates can be directly computed, or you can use the RA and Dec columns, at slightly reduced precision, directly - the last 2 columns in the file. These are in radians, equinox J2000, at whatever epoch is in the appropriate observation date keyword. Further entries are an aperture and sky-corrected C flux, a flux error, the object morphological classification, and a pointer to the original catalogue row number. Comparison files have:- Differential standard coordinates with respect to the reference file in arcsec, an aperture and sky-corrected C flux, the flux error, the object morphological classification, and a pointer to the original catalogue row number. The aperture and sky-corrected flux values referred to are the original catalogue recommended core flux entry corrected for aperture loss for stellar images. This seems to give a sensible galaxy aperture flux too. The fluxes are also normalised by a C correction factor to compensate for the slight QE colour differences between the detectors. This manifests itself as a slight imbalance (~1%) between twilight flatfield gain correction factors and the C derived gain factors - in the optical particularly for the i, I and z passbands. C is a better match to the majority of astronomical objects. All images, whether matching or not, are included in the merged catalogue file. =head1 OUTPUT HEADERS An example header follows:- SIMPLE = T / file does conform to FITS standard BITPIX = 8 / number of bits per data pixel NAXIS = 0 / number of data axes EXTEND = T / FITS dataset may contain extensions COMMENT FITS (Flexible Image Transport System) format defined in Astronomy COMMENT Astrophysics Supplement Series v44/p363,v44/p371,v73/p359,v73/p365. COMMENT Contact the NASA Science Office of Standards and Technology for the COMMENT FITS Definition document #100 and other FITS information. DATE = '2001-05-19T13:47:53' / file creation date END XTENSION= 'BINTABLE' / binary table extension BITPIX = 8 / 8-bit bytes NAXIS = 2 / 2-dimensional binary table NAXIS1 = 56 / width of table in bytes NAXIS2 = 7415 / number of rows in table PCOUNT = 0 / size of special data area GCOUNT = 1 / one data group (required keyword) TFIELDS = 14 / number of fields in each row TTYPE1 = 'Std_coord_Xi' / label for field 1 TFORM1 = '1E ' / data format of field: 4-byte REAL TUNIT1 = 'Arcsec ' / physical unit of field TTYPE2 = 'Std_coord_Xn' / label for field 2 TFORM2 = '1E ' / data format of field: 4-byte REAL TUNIT2 = 'Arcsec ' / physical unit of field TTYPE3 = 'Ref_core_fluxap' / label for field 3 TFORM3 = '1E ' / data format of field: 4-byte REAL TUNIT3 = 'Counts ' / physical unit of field TTYPE4 = 'Ref_flux_error' / label for field 4 TFORM4 = '1E ' / data format of field: 4-byte REAL TUNIT4 = 'Counts ' / physical unit of field TTYPE5 = 'Ref_class' / label for field 5 TFORM5 = '1E ' / data format of field: 4-byte REAL TUNIT5 = 'Number ' / physical unit of field TTYPE6 = 'Ref_pointer' / label for field 6 TFORM6 = '1E ' / data format of field: 4-byte REAL TUNIT6 = 'Number ' / physical unit of field TTYPE7 = 'Del_Xi_1' / label for field 7 TFORM7 = '1E ' / data format of field: 4-byte REAL TUNIT7 = 'Arcsec ' / physical unit of field TTYPE8 = 'Del_Xn_1' / label for field 8 TFORM8 = '1E ' / data format of field: 4-byte REAL TUNIT8 = 'Arcsec ' / physical unit of field TTYPE9 = 'Com1_core_fluxap' / label for field 9 TFORM9 = '1E ' / data format of field: 4-byte REAL TUNIT9 = 'Counts ' / physical unit of field TTYPE10 = 'Com1_flux_error' / label for field 10 TFORM10 = '1E ' / data format of field: 4-byte REAL TUNIT10 = 'Counts ' / physical unit of field TTYPE11 = 'Com1_class' / label for field 11 TFORM11 = '1E ' / data format of field: 4-byte REAL TUNIT11 = 'Number ' / physical unit of field TTYPE12 = 'Com1_pointer' / label for field 12 TFORM12 = '1E ' / data format of field: 4-byte REAL TUNIT12 = 'Number ' / physical unit of field ........................................................................ repeated for however many files have been merged ........................................................................ TTYPE13 = 'RA ' / label for field 13 TFORM13 = '1E ' / data format of field: 4-byte REAL TUNIT13 = 'RADIANS ' / physical unit of field TTYPE14 = 'DEC ' / label for field 14 TFORM14 = '1E ' / data format of field: 4-byte REAL TUNIT14 = 'RADIANS ' / physical unit of field EXTNAME = 'APM-BINARYTABLE' / name of this binary table extension TPA = 1.46666660E+01 / Tangent point RA TPD = 4.31234398E+01 / Tangent point DEC DASCHNR = 4 / WFC CCD no. REFFILE = 'r228663_4_cat.fits' / Reference_file FLIMREF = 7.67655E+02 / 5-sigma flux limit FILTREF = 'V ' / WFC filter EXPREF = 7.99350E+02 / Exposure time DATEREF = '2000-09-04 ' / UTC date start of observation UTSTREF = '04:29:23.5 ' / UTC of start of observation CTYPE1R = 'RA---ZPN' CTYPE2R = 'DEC--ZPN' PROJP1R = 1.00000E+00 PROJP3R = 2.20000E+02 CRPIX1R = 1.7781E+03 CRPIX2R = 3.0291E+03 CRVAL1R = 1.4666666E+01 CRVAL2R = 4.3123440E+01 CD1_1R = -1.0986921E-06 CD1_2R = -9.2521143E-05 CD2_1R = -9.2501665E-05 CD2_2R = 1.0917717E-06 MAGZPTR = 24.45 / Photometric ZP (mags) for default extinct MAGZRRR = 0.02 / Photometric ZP error (mags) EXTINCR = 0.12 / Extinction for observations AIRMASR = 1.08 / Airmass of observation DASCHNC1= 4 / WFC CCD no. COMFILE1= 'r228662_4_cat.fits' / Comparison_file1 FLIMCOM1= 1.33989E+03 / 5-sigma flux limit FILTCOM1= 'i ' / WFC filter EXPCOM1 = 7.99020E+02 / Exposure time DATECOM1= '2000-09-04 ' / UTC date start of observation UTSTCOM1= '04:13:53.3 ' / UTC of start of observation CRPIX1C1= 1.7780E+03 CRPIX2C1= 3.0291E+03 CRVAL1C1= 1.4666800E+01 CRVAL2C1= 4.3123360E+01 CD1_1C1 = -1.1058818E-06 CD1_2C1 = -9.2487986E-05 CD2_1C1 = -9.2473398E-05 CD2_2C1 = 1.0849185E-06 MAGZPTC1= 23.77 / Photometric ZP (mags) for default extinct MAGZRRC1= 0.04 / Photometric ZP error (mags) EXTINCC1= 0.05 / Extinction for observations AIRMASC1= 1.06 / Airmass of observation ........................................................................ repeated for however many files have been merged ........................................................................ END The WCS information enables pixel coordinates from the original file to be directly computed and the various flux and filter information in conjunction with the zero-points and extinction values enable magnitudes etc... to be derived (see catalogue description for more information). =head1 EXAMPLES fitsio_merge r_cat.fits b_cat.fits v_cat.fits i_cat.fits merge.fits =head1 AUTHOR Mike Irwin (mike@ast.cam.ac.uk) =cut