Perl script Starsearch.pl searches the ACT and USNOA star catalogs for matches to an input source list with approximate (RA, Dec) positions and optional WIRE-IR-band magnitudes. Its objective is to replace the approximate positions with more accurate ones from the star catalogs, which are required for subsequent processing by WIRE position-refinement software.
The ACT catalog is searched first, since it is more accurate. If a match with an ACT star is found, then no attempt is made to search and match the source in question to a USNOA star.
Because there are many fewer ACT stars than USNOA stars (one million versus a half a billion), the distance tolerance for an ACT-catalog match can be larger than for a USNOA-catalog match. Too large a matching window may result in an unacceptably large number of random matches.
An underlying assumption of this software is that the sources in the input list are all contained within a square search window, whose size is specified via command-line parameters (default is 0.8 degrees on a side).
The software is now under both CVS version control (/proj/wire/cvsroot/da/russ/acs), and make control. The executables have been delivered to /proj/wire/tst. The source codes are located in /proj/wire/russ/acs/ (Starsearch.pl, makefile.p-bin), /proj/wire/russ/act/ (searchact.f, makefile.f), and /proj/wire/russ/usnoa/ (searchusnoa.f, makefile.f).
The following is a list of the required inputs for Starsearch.pl:
The format of the ASCII data file is given as follows. The first two lines are IPAC table headers. Each subsequent line includes requisite data for a particular source, which are the seven values: source index number, approximate right ascension (decimal degrees), approximate declination (decimal degrees), x pixel coordinate, y pixel coordinate, position measurement confidence-weight (inverse of the square of the DAOPHOT extraction error), and absolute magnitude. These values should be separated by whitespace (no commas, etc.). An example data file is given as follows (this is Starsearch.dat, referred to in the Usage section below):
|Index |RA |Dec |x |y |Sky |Weight |Mag |Err |Chi |Sharp| |i |r |r |r |r |r |r |r |r |r |r | 1 228.312900 81.643800 197.847 179.456 1.0 4.572 6.110 2.0 3.0 4.0 2 228.291809 81.415573 164.816 62.270 1.0 77.519 17.108 2.0 3.0 4.0 3 230.044114 81.808117 48.876 79.979 1.0 121.951 17.506 2.0 3.0 4.0 4 228.317535 81.654461 154.227 173.311 1.0 123.457 17.999 2.0 3.0 4.0 5 225.767951 81.546250 39.178 83.291 1.0 105.263 18.222 2.0 3.0 4.0 6 228.687119 81.422291 26.815 63.671 1.0 90.909 18.259 2.0 3.0 4.0 7 228.534973 81.405125 80.010 56.274 1.0 85.470 18.665 2.0 3.0 4.0 8 228.690521 81.534222 25.104 115.746 1.0 60.241 18.734 2.0 3.0 4.0 9 228.265289 81.576611 172.941 137.355 1.0 79.365 6.570 2.0 3.0 4.0
The table below describes the available command-line inputs. Note that the first two are required.
| Command-line input | Definition |
|---|---|
| -indat or -ind inputfilename | Input source data filename. Required. |
| -band or -b value | WIRE band corresponding to the input data: specify 1 for 12-µm band, or 2 for 25-µm band. Required. |
| -disttol list of two values | Maximum allowable distance for a match between input source and cataloged star. Two values are required, the first for ACT-catalog matching, and the second for USNOA-catalog matching. Defaults are 7.2 and 3.6 arcseconds, respectively. |
| -matchtol value | Maximum allowable number of matches to a given input source from a given star catalog. Default is 1 match. This option is useful for pruning out ambiguous matches. |
| -fluxtol value | Enables IR-flux matching, in addition to distance matching. Absolute value of the relative difference in WIRE-IR-band flux density allowable for a match between input source and cataloged star. |
| -ratol value | Right-ascension half-width of the search window in decimal degrees. Default is 0.4 degrees (changed from 0.5 degrees to reduce number of USNOA-catalog sources and speed-up matching). Division by the cosine of the declination is subsequently done to correct for converging meridians. |
| -dectol value | Declination half-width of the search window in decimal degrees. Default is 0.4 degrees (changed from 0.5 degrees to reduce number of USNOA-catalog sources and speed-up matching). |
| -ACTstdtol value | Maximum allowable ACT-catalog RA and Dec standard deviations, in milliarcseconds. Default is 1000 milliarcseconds. |
| -ACTq | Reject ACT-catalog star if quality flag indicates poor astrometry. |
| -ACTqtol value | Astrometric quality factor tolerance. Default is 5 (smaller values indicate better astrometry). |
| -ACTv | If IR-flux-matching, reject ACT-catalog star if flag indicates variability. |
| -USNOAbright value | Magnitude of brightest star accepted from USNOA catalog. Default is 12. |
| -USNOAdim value | Magnitude of dimmest star accepted from USNOA catalog. Default is 18 (changed from 22 to reduce number of USNOA-catalog sources and speed-up matching). |
| -list value | Low flux cutoff (Jy) for IPAC-table output lists of stars returned by search engines on ACT and USNOA catalogs (see *.dbg output files). Default is 0.005 Jy. |
| -verbose or -v | Verbose mode. Default is off. |
| -execPath or -xp path | Pathname for the binaries used by Starsearch.pl. |
| -debug or -dvalue | Set value to one or more of the characters 1234 to get different debug outputs. In particular, -d 4 gives listings of catalog stars in search window after pre-filtering. |
The ACT and USNOA star-catalog files (6-7 Gbytes), which are needed as inputs to search engines searchact.f and searchusnoa.f, reside in /wire/well/catalogs.
A 50,000-trial Monte-Carlo sampling of WIRE fields was done to ascertain distributions of the numbers of ACT stars contained in the fields. The assumed field size was 0.5 x 0.5 square degrees. The sampling was uniform on the celestial sphere with CROTA2=0. Each of the links below are plots for various cases of absolute field positions above different values of galactic latitude. For each of these cases, scatter plots of the field positions and histograms of ACT star numbers above different flux densities are given.
In addition to detailed standard output (examples of which are given below), several other different output files are created:
Starsearch.pl -ind Starsearch.dat -b 1 -disttol 0.02,0.015 \ -usnoadim 22 -ratol 0.5 -dectol 0.5 -vSee the above "Required and Optional Inputs" section for a listing of Starsearch.dat. The corresponding standard output is:
Now logging to file Starsearch.pl.log, GETFD=0 but true, FH=3 . Starsearch.pl version $Id: Starsearch.pl,v 1.29 1998/09/15 20:20:41 laher Exp $ update Tue_1998/09/15(258)_13:20:41 , PID=8464 Date/time: Tue_1998/09/15(258)_13:38:30 PCPU: 1.21/0.3/2 CCPU: 0.15/0.14 Named parameters for Starsearch.pl: indat = Starsearch.dat; suffixsearch = undef; suffixmatch = undef; debug = undef; execpath = undef; verbose = 1; log = undef; ratol = 0.5; dectol = 0.5; disttol = (0.02,0.015); fluxtol = undef; matchtol = 1; band = 1; actstdtol = 1000; actq = undef; actqtol = 5; actv = undef; list = 0.005; usnoabright = 12; usnoadim = 22; Star catalog matching based on distance only. Time to epoch 2000 = -1.2940175742135 Input data filename = Starsearch.dat Number of input sources = 9 Centroid values: RA = 228.318782842059 Dec = 81.5576427541888 Searching ACT catalog... Number of ACT candidate sources = 21 Number of ACT candidate sources returned = 21 Number of ACT candidate source after pre-filtering = 19 ACT catalog star coordinates (after pre-filtering): # RA Dec Est. IR flux (Jy at 12 um) 1 225.024491 81.291119 0.0330942616958248 2 225.237730 81.590972 0.00147109065323231 3 225.561213 81.177783 0.0151157016112044 4 225.768313 81.545760 0.0380486051287894 5 226.055563 81.316374 0.00659562319351259 6 226.559912 81.797979 0.00532780588289371 7 226.775636 81.630986 0.00628545268546129 8 226.817317 81.608546 0.00286142109297987 9 227.196459 81.722261 0.10863996575182 10 228.121010 81.905089 1.47364829482392 11 228.321960 81.612802 0.00365846115767923 12 229.263943 81.147802 0.0039625206923243 13 229.470759 81.555433 0.00622675243646311 14 229.633188 81.987176 0.137277335001257 15 229.821050 81.545667 0.00511991652190894 16 229.951881 81.141852 0.185056848915246 17 230.041358 81.808099 0.0146449699408488 18 230.904362 81.335278 0.0139507338133735 19 231.117978 81.895032 0.0830050998890643 Looking for ACT-star-catalog matches... ACT-star-catalog matches based on distance only = 2 # RA Dec Bmag Vmag B-V StdRA StdDec Aq Qf Kv Vf Dist. (deg.) IR flux (Jy) 3 230.041358 81.808099 11.704 10.709 0.862 24.900 27.300 0 4 0 0 3.931e-04 1.464e-02 5 225.768313 81.545760 11.844 10.534 1.110 23.400 25.100 0 4 0 0 4.929e-04 3.805e-02 Number of input sources unmatched to ACT star catalog = 7 Searching USNOA catalog... Number of USNOA candidate sources returned = 3070 Number of USNOA candidate sources with visible mag. in [12,22] range = 3012 Looking for USNOA-star-catalog matches... USNOA-star-catalog matches based on distance only = 2 Number of input sources unmatched to either star catalog = 5 End of Starsearch.pl status 0, PID=8464 Date/time: Tue_1998/09/15(258)_13:38:43 PCPU: 8.58/0.42/15 CCPU: 3.73/0.88
In this case, the five of the input sources are unmatched, not for lack of close-enough stars, but because there were more matches than allowed by the default value of the number of matches tolerated for a given input source, which is one. (This is revealed by examination of the diagnostic output file, which shows the best match for each input source, regardless of whether they were rejected by the -matchtol criterion.) Had the -matchtol value been raised to 2, all but one of the input sources would have been matched.
Here is a listing of the corresponding output file Starsearch.dat-match, which is used for input to the position-refinement processing in the WIRE data-analysis pipeline:
\ This star-catalog-match IPAC table was created by Starsearch.pl at 13:5:22 on 9/16/98. \ $Id: Starsearch.pl,v 1.29 1998/09/15 20:20:41 laher Exp $ \ Name of this output file: Starsearch.dat-match \ indat = Starsearch.dat; suffixsearch = undef; suffixmatch = undef; \ debug = undef; execpath = undef; verbose = 1; log = undef; ratol = 0.5; \ dectol = 0.5; disttol = (0.02,0.015); fluxtol = undef; matchtol = 1; \ band = 1; actstdtol = 1000; actq = undef; actqtol = 5; actv = undef; \ list = 0.005; usnoabright = 12; usnoadim = 22; \int nmatches = 4 \real crpix1 = 116.50000000 \real crpix2 = 88.50000000 \real cdelt1 = -0.00214859 \real cdelt2 = 0.00214859 \real crval1 = 92.23931885 \real crval2 = 24.32257843 \real crota2 = -0.14983408 | ra | dec | x | y | weight | type | Dist (arcsec.) | Fluxin (Jy) | Input mag. | | r | r | r | r | r | c | r | r | r | 230.041359 81.808099 48.8760 79.9790 1000.0000 ACT 1.415e+00 9.945e-08 17.506 225.768312 81.545760 39.1780 83.2910 1000.0000 ACT 1.774e+00 5.143e-08 18.222 228.629058 81.411819 26.8150 63.6710 1.0000 USNOA 4.893e+01 4.970e-08 18.259 228.708536 81.545794 25.1040 115.7460 1.0000 USNOA 4.274e+01 3.209e-08 18.734
Example of how to execute Starsearch.pl for matching based on both distance and IR flux density, and with a different -matchtol criterion than used in the above example:
Starsearch.pl -ind Starsearch.dat -b 1 -disttol 0.02,0.015 \ -usnoadim 22 -ratol 0.5 -dectol 0.5 -v -fluxtol 1 -matchtol 2The corresponding standard output is:
Now logging to file Starsearch.pl.log, GETFD=0 but true, FH=3 . Starsearch.pl version $Id: Starsearch.pl,v 1.29 1998/09/15 20:20:41 laher Exp $ update Tue_1998/09/15(258)_13:20:41 , PID=8478 Date/time: Tue_1998/09/15(258)_13:41:19 PCPU: 1.4/0.23/2 CCPU: 0.17/0.11 Named parameters for Starsearch.pl: indat = Starsearch.dat; suffixsearch = undef; suffixmatch = undef; debug = undef; execpath = undef; verbose = 1; log = undef; ratol = 0.5; dectol = 0.5; disttol = (0.02,0.015); fluxtol = 1; matchtol = 2; band = 1; actstdtol = 1000; actq = undef; actqtol = 5; actv = undef; list = 0.005; usnoabright = 12; usnoadim = 22; Star catalog matching based on distance and flux. Time to epoch 2000 = -1.29401225061475 Input data filename = Starsearch.dat Number of input sources = 9 Centroid values: RA = 228.318782842059 Dec = 81.5576427541888 Searching ACT catalog... Number of ACT candidate sources = 21 Number of ACT candidate sources returned = 21 Number of ACT candidate source after pre-filtering = 19 ACT catalog star coordinates (after pre-filtering): # RA Dec Est. IR flux (Jy at 12 um) 1 225.024491 81.291119 0.0330942616958248 2 225.237730 81.590972 0.00147109065323231 3 225.561213 81.177783 0.0151157016112044 4 225.768313 81.545760 0.0380486051287894 5 226.055563 81.316374 0.00659562319351259 6 226.559912 81.797979 0.00532780588289371 7 226.775636 81.630986 0.00628545268546129 8 226.817317 81.608546 0.00286142109297987 9 227.196459 81.722261 0.10863996575182 10 228.121010 81.905089 1.47364829482392 11 228.321960 81.612802 0.00365846115767923 12 229.263943 81.147802 0.0039625206923243 13 229.470759 81.555433 0.00622675243646311 14 229.633188 81.987176 0.137277335001257 15 229.821050 81.545667 0.00511991652190894 16 229.951881 81.141852 0.185056848915246 17 230.041358 81.808099 0.0146449699408488 18 230.904362 81.335278 0.0139507338133735 19 231.117978 81.895032 0.0830050998890643 Looking for ACT-star-catalog matches... ACT-star-catalog matches based on distance and IR flux = 0 Number of input sources unmatched to ACT star catalog = 9 Searching USNOA catalog... Number of USNOA candidate sources returned = 3070 Number of USNOA candidate sources with visible mag. in [12,22] range = 3012 Looking for USNOA-star-catalog matches... USNOA-star-catalog matches based on distance and IR flux = 1 Number of input sources unmatched to either star catalog = 8 End of Starsearch.pl status 0, PID=8478 Date/time: Tue_1998/09/15(258)_13:41:32 PCPU: 8.8/0.32/15 CCPU: 3.1/0.91
In this case, the IR-flux matching criterion eliminated all matches but one, and this match occurred only because the -matchtol criterion was increased from 1 to 2.
Software developer: Russ Laher (laher@ipac.caltech.edu)
Webpage updates:
URL: http://spider.ipac.caltech.edu/staff/laher/Starsearch.html