.\" Automatically generated by Pod::Man version 1.02 .\" Wed Jan 28 12:56:52 2004 .\" .\" Standard preamble: .\" ====================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Ip \" List item .br .ie \\n(.$>=3 .ne \\$3 .el .ne 3 .IP "\\$1" \\$2 .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used .\" to do unbreakable dashes and therefore won't be available. \*(C` and .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` ` . ds C' ' 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and .\" index entries marked with X<> in POD. Of course, you'll have to process .\" the output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" . . . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it .\" makes way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. .bd B 3 . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ====================================================================== .\" .IX Title "FITSIO_MERGE 1" .TH FITSIO_MERGE 1 "January 2004" "0.2" "CASU" .UC .SH "NAME" fitsio_merge \- WCS-based general purpose catalogue matching software .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBfitsio_merge\fR \fIcatfile1\fR \fIcatfile2\fR \fI......\fR \fIoutfile\fR [] .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fB\s-1FITSIO_MERGE\s0\fR generic program for matching CASU-style \s-1FITS\s0 binary table catalogues and merging the photometric, astrometric and classification information together. Forms the basic driver for eg. multipassband \s-1CMD\s0 generation and multicolour master catalogue generation (the alternative is to use a deep stacked image eg. from \fIfitsio_stack\fR followed by \&\fIimcore_conf\fR to derive a deep master catalogue). Embedded pointer records refer back to the original catalogue entries for more complete catalogue information requirements. The output \s-1FITS\s0 binary merge table headers enfold all the astrometric, and photometric calibration information required to produce CMDs and so on. .PP Only generic CASU-style multi-extension input \s-1FITS\s0 catalogues may be used as input. The \s-1WCS\s0 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. .SH "OPTIONS" .IX Header "OPTIONS" The following arguments are required: .Ip "\fIcatfile1\fR" 4 .IX Item "catfile1" \&\s-1CASU\s0 \s-1FITS\s0 binary table to be used as the reference catalogue for coordinate mapping. .Ip "\fIcatfile2\fR" 4 .IX Item "catfile2" Second \s-1FITS\s0 binary table catalogue to be be matched onto the reference system .Ip "\fI........\fR" 4 .IX Item "........" subsequent catalogue files, up to 12 in total for matching. .Ip "\fIoutfile\fR" 4 .IX Item "outfile" The file for the resulting merged \s-1FITS\s0 binary table output. The format of this file is given below. .Ip "\fIsecret=......\fR" 4 .IX Item "secret=......" An optional `hidden' switch allowing the use of the following overrides: .Sp \&\fBsecret=n\fR disable astrometric refinement during the merge process .Sp \&\fBsecret=w\fR do not use the \s-1WCS\s0 information, base matching on pixel coordinates .Sp \&\fBsecret=verbose\fR produce lots of diagnostic output .Sp \&\fBsecret=nodistort\fR disable in-built \s-1ZPN\s0 photometric distortion correction (see http://www.ast.cam.ac.uk/vdfs/docs/reports/astrom/ for explanation) .SH "DESCRIPTION OF OUTPUT FILE" .IX Header "DESCRIPTION OF OUTPUT FILE" The merged catalogues are in the form of \s-1FITS\s0 binary tables with a standard empty primary \s-1HDU\s0. The extension contains the merged file information. .PP 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. .PP Each detector occupies a separate merge file extension with sufficient header information to identify object location, which detector, original \s-1WCS\s0 catalogue data and so on. .PP For each file merged, including the reference, there are 6 column entries plus two additional columns explicitly listing \s-1RA\s0 and Dec in radians. Hence the no. of matched files can be deduced from (#TFIELDS-2)/6, or by interpreting the \s-1FITS\s0 header directly. .PP The reference file, against which the comparison files are matched, has:\- .PP Standard coordinates in arcsecs with respect to \s-1TPA\s0 and \s-1TPD\s0 (see header) from which celestial coordinates can be directly computed, or you can use the \s-1RA\s0 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 \f(CW\*(C`core\*(C'\fR flux, a flux error, the object morphological classification, and a pointer to the original catalogue row number. .PP Comparison files have:\- .PP Differential standard coordinates with respect to the reference file in arcsec, an aperture and sky-corrected \f(CW\*(C`core\*(C'\fR flux, the flux error, the object morphological classification, and a pointer to the original catalogue row number. .PP 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 \f(CW\*(C`dark sky\*(C'\fR correction factor to compensate for the slight \s-1QE\s0 colour differences between the detectors. This manifests itself as a slight imbalance (~1%) between twilight flatfield gain correction factors and the \f(CW\*(C`dark sky\*(C'\fR derived gain factors \- in the optical particularly for the i, I and z passbands. \f(CW\*(C`Dark sky\*(C'\fR is a better match to the majority of astronomical objects. .PP All images, whether matching or not, are included in the merged catalogue file. .SH "OUTPUT HEADERS" .IX Header "OUTPUT HEADERS" An example header follows:\- .PP .Vb 10 \& 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 .Ve .Vb 44 \& 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 .Ve .Vb 3 \& ........................................................................ \& repeated for however many files have been merged \& ........................................................................ .Ve .Vb 51 \& 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 .Ve .Vb 3 \& ........................................................................ \& repeated for however many files have been merged \& ........................................................................ .Ve .Vb 1 \& END .Ve The \s-1WCS\s0 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). .SH "EXAMPLES" .IX Header "EXAMPLES" .Vb 1 \& fitsio_merge r_cat.fits b_cat.fits v_cat.fits i_cat.fits merge.fits .Ve .SH "AUTHOR" .IX Header "AUTHOR" Mike Irwin (mike@ast.cam.ac.uk)