x refnet User Applications refnet NAME refnet - get a list of star locations from a star catalog SYNOPSIS refnet [-ah header] [-ap aptype] [-bl lomaglim] [-bh himaglim] [-cm catfile] [-dn density] [-fl focallength] [-ih himaglim] [-il lomaglim] [-in infile] [-ms maxlistsize] [-os outstyle] [-ot outfile] [-pr prtype] [-ps pixelsize] [-rh himaglim] [-rl lomaglim] [-so sortorder] [-sm smvalue] [-st sortfield] DESCRIPTION The refnet program selects a list stars from a star catalog and makes star coordinate and magnitude information available to the user. Refnet 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 selection criteria. 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: -ah header This option controls the headers (and trailers) on the ASCII output style. The argument 'header' can have the value 'in' or 'out'. If the value is 'in', the headers/trailers will be included. If the value is 'out' the headers/trailers will be excluded. The default value is 'in'. This option is useful when refnet is used in a pipe or when an ASCII style output file is required without headers. -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. A rectangular aperture is the default when the switch is not specified -bh himaglim This option allows the user to specify the blue 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. -bl lomaglim This option allows the user to specify the blue 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. -cm catname This option allows users to select a different star catalog or to spread the catalog over multiple partitions or to use a single CD-ROM drive as the catalog location. The argument 'catname' is the name of a file that contains 24 pathnames, one pathname for each zone in the catalog. Of course, the corresponding 'cat' and 'acc' catalog files must be in the specified directory or the program will fail. Details on the required file structure are specified in the FILE FORMATS section below. If this option is not specified, the file 'USNO-A1.0' is selected as the default. Notice that the default 'catname' has the same name as the default catalog. This naming convention is not required but it makes good sense. (A subset version of the catalog (600 Mbytes), called SA1.0, has been released. This option will make it simpler to switch between the full catalog and the subset catalog.) -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. -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 is meters. Failure to specify this option when using 'IRAF' output will cause the program to terminate with an error. -ih himaglim This option allows the user to specify the color index (red-blue) high 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. -il lomaglim This option allows the user to specify the color index (red-blue) low 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. -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. -ms maxlistsize This option forces the program to limit the number of objects selected to maxlistsize or less. If more stars are selected the program returns with an error condition. If this option is not specified, then maxlistsize will default to some resonably large internal maximum value (currently 100,000). If the user specifies more than the internal maximum, the program will use the internal maximum. -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 'ascii' 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 mode or one of two interactive modes. 'prtype' may have the value 'b', 'i', or 'p'. The value 'b' selects batch processing. The value 'i' selects interactive processing with minimal prompts, and 'p' selects interactive processing with full prompts. If 'prtype' is not specified, interactive processing with full prompting is selected. Interactive processing with minimal prompts will prompt the user for RA, Decl., and aperture size and then present the results in the form requested by the user. Interactive processing with full prompts will prompt the user for every possible relevant value before each search. Command line switches will set the initial default values in this mode. 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 modes 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 microns. Failure to specify this option when using 'IRAF' output will cause the program to terminate with an error. -rh himaglim This option allows the user to specify the red 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. -rl lomaglim This option allows the user to specify the red 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. -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. -sm smvalue This option allows the user to include or exclude objects with questionable magnitude values. Magnitude values can be questionable when the objects are bright (saturation) or when the background is bright (negative flux) or when the object appears in the GSC but does not have a red and/or a blue detection. The argument can have the values of 'include' or 'exclude'. If the switch is not specified, then include is the default. In the ASCII output mode, saturated magnitudes are flagged with a trailing 'e' character and missing magnitudes are flagged with a trailing 'm' character. The missing magnitudes also have strange values. Specifying 'exclude' can lead to unexpected results especially in catalogs for which only one magnitude is specified (PPM). In the case of PPM, everything will be excluded. -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', 'a', 'r', 'b' and 'i'. These values will sort the selected stars by RA, Decl., radius from the center of the aperture, angle from north in RA direction, red magnitude, blue magnitude and color index (blue-red). If this option is not specified, the selected stars will be sorted by RA. 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 width Decl width hr min sec deg min sec (arcsec) (arcsec) 99 99 99.999 99 99 99.99 999999.99 999999.99 Red Bright mag lim Red Dim mag lim Blue Bright mag lim (mag) (mag) (mag) 99.9 99.9 99.9 Blue Dim mag lim Color Index (CI) CI Dim mag lim Density (mag) Bright mag lim (mag) (mag) (stars/sq.deg.) 99.9 99.9 99.9 9999999.9 The following limits must be observed: 0 hr <= RA <= 24 hr -90 deg <= Decl <= 90 deg 0 deg <= RA width <= 90 deg 0 deg <= Decl width <= 90 deg -5 mag <= Red Bright mag lim <= 30 -5 mag <= Red Dim mag lim <= 30 -5 mag <= Blue Bright mag lim <= 30 -5 mag <= Blue Dim mag lim <= 30 -10 mag <= Color index mag lim <= 10 -10 mag <= Color index mag lim <= 10 0 star/deg^2 < Density Catalog map file The catalog map file specifies the path/directory for each zone in the catalog. The catalog is organized into 24 zones labeled 0000, 0075, 0150, ..., 1575, 1650, 1725. Each zone represents a band of declination 7.5 degrees wide with the first zone's southern limit at -90 deg. The zones move northward consecutively with the zone labels. There are two files associated with each zone: the 'acc' file and the 'cat' file. The 'acc' file is a list of indices that point into the catalog ('cat') file at intervals of 0.25 hr RA. The two files form a pair and should always be loaded in the same directory. The catalog map file is an ASCII file of 24 lines. Each line of the file specifies the path to a single zone. The first line is associated with zone 0000 and the lines and zones increase consecutively through the remaining 23 zones. The first 64 characters of each line must contain the full path name for the zone (terminated with a '/'). The next 64 characters may contain a message to be printed at stdout if the file is not found. The default catalog map file name is 'USNO-A1.0'. If you intend to use the default catalog map, It must be in your default directory. Otherwise you must specify its location with the -cm switch. A sample 'USNO-A1.0' file is included below. For this example, assume that the catalog is placed on two disk drives called /mycpu/data2/ and /mycpu/data3/. The messages should never occur but are included to confuse the reader. (The CD number corresponds to the CD where the file was recorded in the USNO's A1.0 distribution.) /mycpu/data2/ Insert CD 1 /mycpu/data2/ Insert CD 1 /mycpu/data2/ Insert CD 6 /mycpu/data2/ Insert CD 5 /mycpu/data2/ Insert CD 3 /mycpu/data2/ Insert CD 2 /mycpu/data2/ Insert CD 1 /mycpu/data2/ Insert CD 4 /mycpu/data2/ Insert CD 6 /mycpu/data3/ Insert CD 5 /mycpu/data3/ Insert CD 7 /mycpu/data3/ Insert CD 10 /mycpu/data3/ Insert CD 8 /mycpu/data3/ Insert CD 7 /mycpu/data3/ Insert CD 8 /mycpu/data3/ Insert CD 9 /mycpu/data3/ Insert CD 9 /mycpu/data3/ Insert CD 4 /mycpu/data3/ Insert CD 10 /mycpu/data3/ Insert CD 3 /mycpu/data3/ Insert CD 2 /mycpu/data3/ Insert CD 6 /mycpu/data3/ Insert CD 2 /mycpu/data3/ Insert CD 3 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) 99 99 99.999 999 99 99.99 99.9x 99.9x 999.99 999.99 99 99 99.999 999 99 99.99 99.9x 99.9x 999.99 999.99 99 99 99.999 999 99 99.99 99.9x 99.9x 999.99 999.99 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 99 99.999 999 99 99.99 99.9x 99.9x 999.99 999.99 99 99 99.999 999 99 99.99 99.9x 99.9x 999.99 999.99 99 99 99.999 999 99 99.99 99.9x 99.9x 999.99 999.99 The 'x' field following the magnitudes ishe magnitude error flag described in the '-sm' switch section. 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. (All heading may be suppressed with the -ah switch.) iraf iraf results are formatted just as IRAF 'starlist' output files. An example of the format is shown below: 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 . . . . . . . . . The magnitude is the average of the 'red' and 'blue' values when both values exist and are valid. Other approximations are used to obtain something reasonable when values are missing or in error. 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. Note: The refnet program will not be able to use these files because they will not have a corresponding 'acc' file and they will not necessarily fit in a 7.5 deg Decl. range and they will not necessarily be ordered by RA. The refnet program depends on all of these factors. EXAMPLES 1. Invoke the program in the minimal prompts interactive mode accepting all the defaults: % refnet -pr i With this command you get the following defaults: aperture type = rectangular density = 100,000,000 stars/sq. deg. himaglim = 30 mag in both colors lomaglim = -5 mag in both colors color index lomaglim=-10 color index himaglim=10 outstyle = ASCII outfile = terminal (stdout) sortorder = ascending sortfield = RA 2. Invoke the program in interactive mode and create a sequence of IRAF starlist files. % refnet -ot iraf.lis -os IRAF -fl 2.0 -ps 15 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 15 microns. 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. % refnet -pr b -in regions.dat -bl 14.0 -bh 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 refnet 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 refnet'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 refnet will use stdin and stdout if no input and output files are specified for the batch mode. % select_region | refnet -pr b -os IRAF -fl 1.1 -ps 15 | image_gen 5. Create a region specification file that will search 5 adjacent regions at the equator. 12 00 00 00 00 00 3600 3600 -5 30 -5 30 -10 10 1000000 12 04 00 00 00 00 3600 3600 -5 30 -5 30 -10 10 1000000 12 08 00 00 00 00 3600 3600 -5 30 -5 30 -10 10 1000000 12 12 00 00 00 00 3600 3600 -5 30 -5 30 -10 10 1000000 12 16 00 00 00 00 3600 3600 -5 30 -5 30 -10 10 1000000 Notice that the width in RA is 3600 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 3600 3600 -5 30 -5 30 0.5 2.0 1000000 12 00 00 89 30 00 3600 3600 -5 30 -5 30 0.5 2.0 1000000 00 00 00 89 30 00 3600 3600 -5 30 -5 30 0.5 2.0 1000000 00 00 00 88 30 00 3600 3600 -5 30 -5 30 0.5 2.0 1000000 Since the width in both RA and Decl is 3600 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 (CI) between red and blue and requiring 0.5 <= CI <= 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. VERSION DIFFERENCES Version 1.1 (the original version) user interface is documented in the 'manpage' included in the distribution. Version 1.2 user interface is also documented in the 'manpage' included in its distribution. Version 1.2 is primarily concerned with changing the user interface and changing the name from 'astronet' to 'starnet'. The following switches have been deleted: -mt, -ml, -mh. They have been replaced with -rl, -rh, -bl, -bh, -il, -ih. This change allows several magnitude criteria to be specified at the same time. An additional interactive mode has been added and the new mode is the default processing mode (pr -p). It is the prompting interactive mode. In this mode, the user is prompted for all relevant values. That is, possible promts include: High (dim) blue magnitude limit : 30.0 Low (bright) blue magnitude limit : -5.0 High (dim) red magnitude limit : 30.0 Low (bright) red magnitude limit : -5.0 High (dim) color index magnitude limit : 30.0 Low (bright) color index magnitude limit : -5.0 Catalog name (file name) : USNO-A0.9 Star density (stars/sq.deg) : 1000000.0 Output style (ascii | iraf | catalog) : ascii Output file (file name | blank if terminal) : refnet.out The next two prompt appear only if 'iraf' is chosen as output style. Pixel size (microns) : 15.0 Focal length (meters) : 7.0 Sort by (RA | Decl | Red | Blue | Index | Radius | Angle ) : RA Sort order (ascending | descending ) : ascending The prompts for aperture size depend on the aperture type: For circular Aperture diameter (arcsec) : 120 For rectangular Aperture width E/W (arcsec) : 120 Aperture height N/S (arcsec) : 120 Aperture center RA (hr) : 00 00 00.0 Aperture center Decl. (deg) : 00 00 00.0 In the previous version, aperture size was requested as the width or radius. In this version it is requested as the full-width or diameter. A new switch has been added (-ah) that controls whether or not the column headers are printed in the 'ascii' output style. New default behavior: The default sorting parameters is always RA. The default aperture is always rectangular. Bug fixes: The 'angle' given at the pole is forced to lie between 0 and 360 degrees. Version 1.3 was for bug fixes. Version 1.4 was for a name change ('starnet' to 'refnet'), many bug fixes and minor changes in the user interface to incorporate the new switches. Two new switches were added -sm (include/exclude objects with uncertain magnitudes) and -ms (limit the maximum number of objects selected). 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 When near the pole, the 'angle' reported is not calculated correctly because of approximations in the FORTRAN DTAN2 function. $Id: manpage,v 1.8 1997/01/31 22:17:19 koehn Exp koehn $