Perl script wireguidestars checks that a sufficient number of guide stars are available for planned observations. It independently applies the same guide star rules used by the WIRE scheduler to produce a prioritized guide-star list for each observation. It also checks the WIRE telescope field-of-view for bright sources by searching a bright-source subset of the IRAS catalog for 12-um and 25-um sources that have flux densities >10 Jy. It optionally produces a list of possible dither positions for each observation. Observation parameters are read either from a plan file, from a timeline (in combination with one or more plan files), or from command-line data lists, as described below. If a timeline file is specified, the tool compares its guide-star list with the corresponding list in the timeline, and optionally presents the comparison results graphically. The interface specification of the main subroutine of the tool is given below for integration of the tool into WIRESKY.
The plan-file checking that is done by the tool is on a tile-by-tile basis. All tiles in the plan file will be processed by this tool. (A tile is a 2-D representation of time during the WIRE mission, with orbit number running on the horizontal edge, and angle-from-ascending-node running along the vertical edge. During this time, data for a survey sample are acquired, which involves taking multiple exposures in the vicinity of a pre-selected survey area on the celestial sky.) Each tile may include one or more adjacent WIRE fields in a survey area. Each field is checked for guide stars at regularly selected orbits over its entire orbit range (no assumption is made about the assignment of specific orbits to a given field); during this time, the telescope roll angle may change, which will affect the guide stars in the star-tracker field of view. Within an orbit segment, all possible dither positions are checked.
The timeline-file checking that is done by the tool is for the specific fields and dither keys listed in the timeline file. One or more plan files that are associated with the timeline must be specified, which is done so either via command line or read from the timeline's header comments. Since the timeline does not contain the pathname that specifies where the plan file(s) is stored (the tool assumes that all the plan files are located in the same subdirectory if their filenames are obtained from the timeline header comments), it must be specified on the command line using the -pp option. All observation segments in the timeline file that are included in the plan file(s) will be processed by this tool. Additionally, filler segments (with area ID = 0) are processed; the associated area definition filename is survey_filler, obtained from the timeline-file directory. Since the dither key is available from the timeline for each segment, only those dither-table values that correspond to the dither key are checked, which decreases the processing time required by the tool (all dither-table possibilities need not be checked in this case).
When the timeline-file checking option is exercised, the -plot switch can be enabled to automatically create a postscript-plot file called wireguidestars.ps (here, an IDL script is launched, which plots the wireguidestars output file called wireguidestars.dat). The user's environment must be set up for IDL in order to use this option.
If there are at least two of the same guide stars common to all orbit times and dither positions checked for a given field, then the guide-star requirement is met and the observation can be scheduled; otherwise a different survey area must be selected in its place.
If the verbose mode is set, a prioritized list of guide stars in a way that maximizes the performance of the star tracker will be output for each field, using the same rules as the scheduler. If more than five guide stars are found for a given field, then rules are applied by the tool to narrow down the list to just five guide stars, just like the scheduler.
The required inputs are RA, Dec, starting modified Julian date, ending modified Julian date, and survey type symbol for each survey area of interest. Also needed are the correction quaternions for the misalignment between the star-tracker and telescope boresights, and orbit-ephemeris data (inclination, RA of ascending node, and associated time). The orbit ephemeris data is essential for computing the field center positions for each survey area. When processing a timeline file, the orbit ephermeris data are read in from comment lines at the beginning of the timeline file.
The outputs are guide-star data for each field of each survey area specified, and include the minimum, maximum, mean and standard deviation of the guide-star numbers found for all dither positions; and (RA, Dec, GSCindex, X, Y, Z, Magnitude) of the final guide-star set for each observation. Each final set includes up to a maximum of 5 guide stars. The quantities (GSCindex, X, Y, Z, Magnitude) are taken directly from the guide-star catalog.
The guide-star catalog that is searched by this tool by default is our ASCII version of the SWAS guide-star catalog that goes down to magnitude 6.0 deep. It is located at /proj/wire/soda/so/guide_stars_ymei/guide_stars_swas23. The environment variable GUIDESTARCAT can be set to override this default.
IRAS bright sources are checked for in a telescope FOV that is defined to be 35 arcminutes on each side. The 1-arcminute padding all-the-way around the nominal 33-arcminute FOV accounts for the potential maximum misalignment between the 12-um and 25-um telescope boresights. Every dither position is checked in the 35-arcminute and 40-arcminute FOVs. The IRAS bright-source catalog, which include >10 Jy source in both the 12-um and 25-um IRAS bands, is located at /wire/well/catalogs/brightness. The environment variable IRASBRIGHTSOURCECAT can be set to override this default. If the -check1Jy switch is set (with the penalty of added processing time), a bigger and deeper catalog, which goes down to 1 Jy, located at /wire/well/catalogs/brightness1jy is checked instead.
The environment variable DITHERTABLE sets the path and file name of the dither table; the default is /proj/wire/soda/so/dith/dithtab.v5.txt.
If the tool is exercised in the timeline-checking mode, the path name of the required area definition files is taken to be the same as that of the timeline. Otherwise, the environment variable ADFPATH sets the path name of the area definition files. The partial pathnames included with the plan-file area-definition file names are ignored.
Perl library gsutils.pl contains the subroutines needed by wireguidestars. The main subroutine called for each tile to be processed is documented below for the purpose of defining its interface for WIRESKY integration.
($nfields,$stats,$stars,$gsselected,$bstars,$dithra,$dithdec) =
checkforguidestars($areara,$areadec,
$mjdobsstart,$mjdobsend,$guidestarfile,
$irasbrightsourcefile,
$dithertable,$adfpath,$surveytype,
$xpath,\@qcorr,$no1Jycheck,$debug,
$disttol,$disttol2,$crota2tel,
$orbitperiod,$mjdobsout,$fieldindex[$j],
$timeline,$basex,$basey,$basez,$secondx,
$secondy,$secondz,$ditherkey[$j]);
$nfields is a scalar; the remaining returned items are array references.
$nfields = Number of fields in the tile processed
$i = field index (for the indices below only)
$j = guide-star index (for the indices below only)
$stats[$i][0] = Guide-star flag (1=OK, 0=insufficient)
$stats[$i][1] = Minimum number of guide stars found in all fields,
orbit times, and extreme dither positions checked
$stats[$i][2] = Maximum number of guide stars found in all fields,
orbit times, and extreme dither positions checked
$stats[$i][3] = Mean number of guide stars found in all fields and
orbit times, and extreme dither positions checked
$stats[$i][4] = Standard deviation of number of guide stars found
in all fields, orbit times, and extreme dither
positions checked
$stats[$i][5] = Number of fields, orbit times, and extreme dither
positions checked
$stats[$i][6] = Number of guide stars common to all fields, orbit
times, and extreme dither positions checked
$stats[$i][7] = Number of guide stars selected (up to 5; only
relevant if guide-star flag = 1)
$stats[$i][8] = Star-tracker RA
$stats[$i][9] = Star-tracker Dec
$stats[$i][10] = Star-tracker CROTA2
$stats[$i][11] = IRAS bright-source flag (1=OK, 0=1 or more found)
$stats[$i][12] = Number of IRAS bright-sources found (> 10 Jy)
$stars[$i][$j][0] = RA of guide star
$stars[$i][$j][1] = Dec of guide star
$stars[$i][$j][2] = Catalog index of guide star
$stars[$i][$j][3] = X of guide star
$stars[$i][$j][4] = Y of guide star
$stars[$i][$j][5] = Z of guide star
$stars[$i][$j][6] = Magnitude of guide star
$gsselected[$i][$j] = Priority order of selected guide star (values
range from 1 to $stats[$i][7]; 1 has the
high priority)
$bstars[$i][$j][0] = RA of IRAS bright source
$bstars[$i][$j][1] = Dec of IRAS bright source
$bstars[$i][$j][2] = 12-um IRAS band flux density (Jy)
$bstars[$i][$j][3] = 25-um IRAS band flux density (Jy)
where all arguments are scalars (\@qcorr is a reference to an array of correction quaternions). The subroutine arguments are defined either above, or in the table below.
The tool is under both CVS version control (/proj/wire/cvsroot/da/russ/guidestars), and make control (makefile.p-bin, makefile.p, makefile.c). The source code is located in /proj/wire/russ/guidestars. Many of subroutines used by the tool are in gsutils.pl. The binary execuatable getamat (built from getamat.c, targ2dircos.c, and assorted header files) and the IDL script wireguidestars.pro are also called by the tool. The tool has been delivered to the /proj/wire/so_tst/ directory.
| Command-line input | Definition |
|---|---|
| -planfilepath or -pp path of plan files | Plan-file pathname. Default is current directory. |
| -planfile or -pf plan-file filename(s) |
List of comma-separated plan file name(s), which include information
about the observation to be checked.
Plan-file-checking mode is initiated if a plan file is specified, but no timeline is specified. In this case, only the first plan file in the list is applicable (the rest are ignored since only one plan file is processed in the plan-file-checking mode). Timeline-checking mode is initiated if a timeline is specified (see below). Plan-file name(s) are needed if a timeline is specified, and if they are not specified here, then the plan-file filenames that are listed in the timeline's header comments will be used, along with the plan-file pathname specified by the -planfilepath command-line option (see above). Currently, the only information used from the plan files in the timeline-checking mode are the starting and ending observation dates and the tile note fields. If neither a plan file nor a timeline file is specified, then separate lists of the required data for specifying survey areas can be provided via command-line options (see below). |
| -timeline or -tl path and file name of timeline file | Path and file name of timeline file, which contains a list of selected RA, selected Dec, observation MJ date, alignment MJ date, and area ID for each observation segment of a survey area. One or more plan files are needed if this option is exercised, in order to get the required starting and ending observation dates, and the tile note fields, which are looked-up by area ID; if the plan file(s) is not specified via the -pf option, then the plan files that are listed in the timeline's header comments will be used, along with the plan-file pathname specified by the -planfilepath command-line option (see above). Note that the only plan files specified in the timelines that are recognized by this tool are those with filenames that begin with either "surv", "ops", "AI", "fill", "tar", or "lmc". |
| -pffilter or -fl | Switch relevant to the timeline-checking mode, that causes plan file(s) specified by the -pf command-line option to be used in lieu of the plan files specified in the timelines. |
| -ratel or -ra list of RA values | RA values of the survey areas (tiles), pointed by the telescope. Use only if neither timeline file nor plan file is specified. |
| -dectel or -dec list of Dec values | Dec. values of the survey areas (tiles), pointed by the telescope. Use only if neither timeline file nor plan file is specified. |
| -mjdstart list of start MJ date values | Starting MJ date values of the survey areas (tiles). Use only if neither timeline file nor plan file is specified. |
| -mjdend list of end MJ date values | Ending MJ date values of the survey areas (tiles). Use only if neither timeline file nor plan file is specified. |
| -mjdout list of MJ date values | MJ date values of the survey areas (tiles) used for computing the field-center roll angles for application of guide-star rules. The guide-star lists outputted when the verbose switch is enabled correspond to this date. The dither positions outputted when the listdithers switch is enabled also correspond to this date. Can use this options even when either timeline file or plan file is specified. |
| -surveytype or -sv list of path and file names of area definition files | Path and file names of area definitions of the survey areas (tiles). Use only if neither timeline file nor plan file is specified. |
| -qcorrS_T or -qc list of star-tracker/telescope quaternions | Quaternions for rotating FROM the star-tracker boresight to the telescope boresight. Default values are (0, 0, 0, 1). In the timeline-checking mode they are read from the first timeline if not specified on the command line. |
| -listdithers or -ld | Switch that causes list of all possible dither positions for each field of each survey area at the alignment date to be outputted to data file wireguidestars.dit. |
| -plot | Switch that causes the output data file wireguidestars.dat to be plotted using IDL script wireguidestars.pro. This option is available only when a timeline file is specified. The number of guide stars versus segment is plotted. A negative number of guide stars indicates that the list of guide stars found by wireguidestars is different from the corresponding timeline list. After viewing the plot (or capturing with xv), type exit to quit IDL and return control to wireguidestars. |
| -disttolst or -dst value | Initial guide-star-catalog search radius. The default value is 10 degrees. |
| -disttoltel or -dtl value | Initial IRAS-bright-source-catalog search radius. The default value is 2 degrees. |
| -allsky or -as | Switch to process a tile at 10-degree steps in RA and Dec over the entire sky. This option has not been very well tested and may be changed to accommodate user needs as they arise. |
| -execPath or -xpath pathname | Pathname for the binaries used by wireguidestars. |
| -verbose or -v | Enable verbose mode. |
Here is an example of how to execute wireguidestars for checking a plan file. First make sure that the ADFPATH environment variable is set.
wireguidestars -pf /proj/wire/russ/planskycheck/junkjuly.plan -v -ld
Lists of guide stars for each field are printed to standard output when the verbose switch is enabled. Summary output IPAC-tables are listed in wireguidestars.tbl, and, for failed segments only, in wireguidestars_fail.tbl. More information about the failed segments is given in wireguidestars.out. The (RA, Dec) positions of the dithers for each field are given in wireguidestars.dit, which is only created when the -ld switch is thrown.
The tool can also be used as a timeline checker:
wireguidestars \ -tl /proj/wire/soda/so/ops/timelines/tl_test_2/I99069REGOTL.0/I99069REGOTL00.0 \ -pp /proj/wire/soda/so/ops/timelines/tl_test_2/I99069REGOTL.0/ \ -plot -v -ld | & tee wireguidestars.scr
Click here to see the corresponding standard output. Summary output IPAC-tables are listed in wireguidestars.tbl, and, for failed segments only, in wireguidestars_fail.tbl. More information about the failed segments is given in wireguidestars.out. The -plot switch invokes the IDL script wireguidestars.pro to produce a plot called wireguidestars.ps from the output data file wireguidestars.dat (this data file is created by wireguidestar regardless of whether -plot is enabled). The -ld switch causes the output file wireguidestars.dit, which lists the (RA, Dec) positions of the dithers for each field, to be created.
Last revised: February 3, 1999
Software developer: Russ Laher (laher@ipac.caltech.edu)
URL: http://spider.ipac.caltech.edu/staff/laher/wireguidestars.html