astronet User Applications astronet NAME astronet - get a list of star locations from a star catalog SYNOPSIS astronet [-ap aptype] [-dn density] [-fl focallength] [-in infile] [-mh himaglim] [-ml lomaglim] [-mt magtype] [-os outstyle] [-ot outfile] [-pr prtype] [-ps pixelsize] [-so sortorder] [-st sortfield] DESCRIPTION The astronet program selects a list stars from a star catalog and makes star coordinate and magnitude information available to the user. Astronet was designed to use the United States Naval Observatory's 1996 star catalog release A0.9 although it should be able to use any later version of this catalog. The program has an interactive and a batch mode. The interactive mode allows the user to repeatedly select stars by interactively specifying the Right Ascension (RA), Declination (Decl.) and aperture size. The batch mode does not have an interactive interface. Instead, it reads a file, prepared by the user, which contains catalog search criteria. The results can be presented in several user selectable formats. These include a simple ASCII list of selected star positions and magnitudes, a binary catalog format, and an IRAF format suitable for creating an image of the selected sky region. OPTIONS The following options are supported: -ap aptype This option selects the search aperture type. 'aptype' may have the value 'c' or 'r'. The value 'c' will use a circular aperture and the value 'r' will use a rectangular aperture in the search algorithm. This option is used only in the interactive mode. The batch mode will always use the rectangular aperture. If the option is omitted in the interactive mode, the circular aperture will be used. -dn density This option enables the user to select the star density. 'density' is the maximum number of stars per square degree allowed in the selected list. If this option is not selected then 'density' defaults to a very high value so that no stars are eliminated. If stars must be eliminated to achieve the requested density, they are eliminated with a bias toward bright stars. That is, dimmer stars are eliminated whenever a choice is available. The algorithm attempts to eliminate stars uniformly over the selected region. -fl focallength This option allows the user to specify the focal length of the telescope used to simulate an image by IRAF. This option must be specified if the output format is 'IRAF'. Pixel size must also be specified using the -ps option. This option has no meaning in other situations. The units used to specify the focal length must be the same units used to specify the pixel size. Failure to specify this option when using 'IRAF' output will cause the program to terminate with an error. -in infile This option allows the user to specify a file containing the list of regions to be searched. The option has no meaning in the interactive mode. If the option is not specified in the batch mode, standard input is used. This enables the program to be used in a pipe. -mh himaglim This option allows the user to specify the high magnitude limit (dim limit) of stars that will be selected. That is, stars dimmer than this limit will not be selected. 'himaglim' must be a number between -5.0 and 30.0. If this option is not used, 'himaglim' defaults to 30.0. -ml lomaglim This option allows the user to specify the low magnitude limit (bright limit) of stars that will be selected. That is, stars brighter than this limit will not be selected. 'lomaglim' must be a number between -5.0 and 30.0. If this option is not used, 'lomaglim' defaults to -5.0. -mt magtype This option allows the user to specify which magnitude will be used to compare to the magnitude limits specified by 'lomaglim' and 'himaglim'. 'magtype' may have the values 'r', 'b', and 'rb'. These values stand for 'red', 'blue', and 'red - blue' respectively. The red and blue magnitudes are part of the catalog entry for each star. If this option is not selected, blue magnitudes are used by default. -os outstyle This option enables the user to select the format for the output. 'outstyle' can have the values 'ascii', 'cat', or 'iraf'. If this option is not selected, then 'ascuu' is used. If no output file is specified, then 'cat' will not be accepted as an option. See the FILE FORMATS section for detailed information on the format for each of these styles. -ot outfile This option allows the user to specify the prototype output file name. Since multiple regions can be selected in both the batch and interactive mode, the selected stars from each region will be placed in a separate file. The filenames are generated by appending a different integer on the prototype filename. The integers are consecutively generated starting from 1 each time a new region is selected. If this option is not used, the output is directed to stdout. This will enable this program to be part of a pipe. EXCEPTION: If the output style 'outstyle' is 'cat', this option must be selected. If not, the program will be terminated. This restriction is needed because catalog files are FORTRAN direct access, unformatted files. This file type may cause pipes to burst. It will certainly make terminals go up in flame. -pr prtype This option selects batch or interactive processing. 'prtype' may have the value 'b' or 'i'. The value 'b' selects batch processing. The value 'i' selects interactive processing. If 'prtype' is not specified, interactive processing is selected. Interactive processing will prompt the user for RA, Decl., and aperture size and then present the results in the form requested by the user. Batch processing will read a file (file format discussed in the FILE FORMAT section) to find selection parameters and then present the results in the form selected by the user. NOTE1: Through appropriate use of redirection and other program characteristics, the batch mode can be used interactively and the interactive mode can simulate the batch mode. The real difference is the number of selection parameters required by each mode. NOTE2: If the batch mode is reading from the terminal rather than a file, the program can be terminated normally by typing the EOF character (CTRL-D). -ps pixelsize This option allows the user to specify the pixel of the camera used to simulate an image by IRAF. This option must be specified if the output format is 'IRAF'. Focal length must also be specified using the -fl option. This option has no meaning in other situations. The units used to specify the pixel size must be the same units used to specify the focal length. Failure to specify this option when using 'IRAF' output will cause the program to terminate with an error. -so sortorder This option allows the user to specify in which order the selected stars are to be sorted. 'sortorder' can have the values 'a' and 'd'. These values will sort the selected stars in ascending and descending order respectively. If this option is not selected, the stars will be sorted into ascending order. -st sortfield This option allows the user to specify by which parameter the selected stars are to be sorted. 'sortfield' may have the following values: 'RA', 'D', 'rad', 'r', 'b' and 'i'. These values will sort the selected stars by RA, Decl., radius from the center of the aperture, red magnitude, blue magnitude and color index (blue-red). If this option is not specified, the selected stars will be sorted by RA in the batch mode and by radius in the interactive mode. FILE FORMATS Input files Region Specification File The file used to supply selection information is a text file. Each line of the file contains all the selection information needed for one region. The file can contain as many regions (lines) as required. Selection information on each line is positional and each field must contain valid information. All numeric fields may use integer or floating-point number formats, i.e., integer (S...999), floating point (S...999.999...). The fields are ordered in the following sequence: RA Decl RA half-width Decl half-width hr min sec deg min sec (arcsec) (arcsec) 99 99 99.999 99 99 99.99 999999.99 999999.99 Brite mag lim Dim mag lim Mag select Density (mag) (mag) B/R/D (stars/sq.deg.) 99.9 99.9 Z 9999999.9 The following limits must be observed: 0 hr <= RA <= 24 hr -90 deg <= Decl <= 90 deg 0 deg <= RA half-width <= 45 deg 0 deg <= Decl half-width <= 45 deg -5 mag <= Brite mag lim <= 30 -5 mag <= Dim mag lim <= 30 0 star/deg^2 < Density Output files There are three output file formats (ascii, iraf and cat). Each of them are discussed below: ascii ascii results are formatted in the following way: RA Decl. Magnitude Radius Angle hr min sec deg min sec Red Blue (arcsec) (deg) xx xx xx.xxx xxx xx xx.xx xx.x xx.x xxx.xx xxx.xx xx xx xx.xxx xxx xx xx.xx xx.x xx.x xxx.xx xxx.xx xx xx xx.xxx xxx xx xx.xx xx.x xx.x xxx.xx xxx.xx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx xx xx.xxx xxx xx xx.xx xx.x xx.x xxx.xx xxx.xx xx xx xx.xxx xxx xx xx.xx xx.x xx.x xxx.xx xxx.xx xx xx xx.xxx xxx xx xx.xx xx.x xx.x xxx.xx xxx.xx If no output file is specified in the interactive mode, only 19 lines of data are presented at a time. The user must depress the 'Return' key to get the next 19 lines. Also the headings are printed at the top of each page. If an output file is specified, the headings are printed only once. iraf iraf results are formatted just as IRAF 'starlist' output files. An example of the format is shown below: # Tue 10:51:30 19-Nov-96 begin temp.lis spatial uniform xmin 1. xmax 128. ymin 1. ymax 128. luminosity powlaw power 0.6 minmag 10. maxmag 20. nssample 100 sorder 10 sseed 1 nlsample 100 lorder 10 lseed 1 nstars 128 117.88 1.87 19.857 29.39 2.33 17.777 73.03 2.55 17.897 108.60 4.95 19.014 66.94 5.19 18.631 . . . . . . . . . This file can be used by IRAF 'mkobjects' to create an image of the sky containing the stars selected from the catalog. The 'IRAF' format cannot be used unless the telescope focal length and pixel size are specified with the -fl and -ps options. cat By specifying 'cat' as the 'outstyle' the program will create a file using the same file format as the USNO's catalog. That is, the file will be an unformatted, direct-access (FORTRAN nomenclature) file with 12 byte records for each star in the catalog. EXAMPLES 1. Invoke the program in interactive mode accepting all the defaults: % astronet With this command you get the following defaults: aperture type = circular density = 100,000,000 stars/sq. deg. himaglim = 30 mag lomaglim = -5 mag magtype = blue outstyle = ASCII outfile = terminal sortorder = ascending sortfield = radius 2. Invoke the program in interactive mode and create a sequence of IRAF starlist files. % astronet -ap r -ot iraf.lis -os IRAF -fl 2.0 -ps 0.000015 Since we are going to create a simulated CCD image we select a rectangular aperture. The prototype output file name is 'iraf.lis'. The output file style is IRAF. The focal length of the telescope is 2.0 meters and the camera pixel size is 0.000015 meters. The other defaults are as in example 1. In this situation, the sort order will default to ascending RA. The resulting files will be named iraf.lis1 iraf.lis2 iraf.lis3 . . . 3. Invoke the program in batch mode to create a sequence of sub-catalogs. % astronet -pr b -in regions.dat -ml 14.0 -mh 18.0 -os cat -ot scan.cat -st D In this instance, the input file is 'regions.dat' and the prototype output filename is scan.cat. The magnitude limits have been set to select stars between 14th and 18th magnitude in the blue. The resulting catalogs will be sorted in ascending order by Decl. 4. Put astronet into a pipe to generate FITS image files. Here, we make use of two fake routines to help with the example. The first fake routine, 'select_region', generates output acceptable to astronet's batch mode reader. The second fake routine, 'image_gen', creates FITS image files of the sky. It accepts IRAF 'starlist' files as input. Recall that astronet will use stdin and stdout if no input and output files are specified for the batch mode. % select_region | astronet -pr b -os IRAF | image_gen 5. Create a region specification file that will search 5 adjacent regions at the equator. 12 00 00 00 00 00 1800 1800 -5 30 B 1000000 12 04 00 00 00 00 1800 1800 -5 30 B 1000000 12 08 00 00 00 00 1800 1800 -5 30 B 1000000 12 12 00 00 00 00 1800 1800 -5 30 B 1000000 12 16 00 00 00 00 1800 1800 -5 30 B 1000000 Notice that the half-width in RA is 1800 arcsec. Therefore to select an adjacent region, the RA must move by one degree. One degree expressed in hour-angle is 4 minutes. 6. Create a region specification file that will search for Solar-like stars near the North pole. 12 00 00 88 30 00 1800 1800 0.5 2.0 D 1000000 12 00 00 89 30 00 1800 1800 0.5 2.0 D 1000000 00 00 00 89 30 00 1800 1800 0.5 2.0 D 1000000 00 00 00 88 30 00 1800 1800 0.5 2.0 D 1000000 Since the half-width in both RA and Decl is 1800 arcsec, each region is about one square degree. The regions start two degrees south of the pole an march right over the top to the other side ending two degrees from the pole. Solar-like stars are selected by using the magnitude difference between red and blue (D) and requiring 0.5 <= D <= 2.0. COMMENTS A major function of the command line interface is to allow interactive users better control of selection criteria. Batch users can control selection parameters in more detail using the selection file. In keeping with this idea, batch mode selection file values are always used if a duplicate parameter is defined in the command line. DIAGNOSTICS Exit status is 0 if the program runs without errors. Exit status is 1 otherwise. The software should report a detailed message any time an error occurs. It is the goal of all messages to enable the user to easily understand the problem and correct it. BUGS A way should exist to 'easily specify' star catalogs other than the default. Because current catalogs can be larger than 2 GB (the maximum that some operating sytems can handle), multiple partitions or multiple drives are sometimes required. This means that the various paths must be maped in some way to the internal workings of the program. This violates the 'easily specify' requirement.