Radio Eyes Help

Source File Converter Tool

Radio Eyes uses a random access file format to store data about radio sources. In random access files all  records (individual sources) are the same length. This makes it possible to quickly access individual records when an appropriate index is available. The Radio Eyes radio data source file structure can be found here. A number of text catalogs of cosmic radio sources are available on the web. The Source File Converter tool allows you to convert most of these text formatted catalogs into files that Radio Eyes can read. While I have done what I could to make this process not too difficult, it may still be a bit challenging for the casual computer user.

Bring up the Source File Converter from the main menu's Tools / Data File Tools / Convert Radio Source File. The following steps are necessary to convert the text file catalog:

Retrieving Text Radio Source Catalogs
There are many places where you might find the appropriate catalogs. The Radio-Sky CDROM I has a number of catalogs, several with format files already made. A wonderful on line resource is the VizieR website.  This comprehensive listing of astronomical catalogs has search and sorting capabilities that are very useful. You may filter the retrieved catalog data from VizieR in numerous ways that useful to you in producing catalogs suitable for conversion into the Radio Eyes format. One especially nice feature is the ability of VizieR to add fields that specify RADEC coordinates in  the 2000 Epoch where no such fields exist in the original catalog. 

The absolutely necessary information for Radio Eyes is:

Any other available information can be converted from the table into either additional flux values, name, or comment fields of the Radio Eyes files. 

When specifying the VizieR output type use "ascii table", and be sure to use the largest "Max Entries per Table" so that all of the catalog sources will be presented at once. .  Select and copy the ASCII table data form the display into a text editor such as notepad or wordpad.  Edit out all of the blank lines or lines that are not just data then save the file with an appropriate name and the .dat extension in a safe place on your computer. Jot down what the various columns represent from the heading on the VizieR table output page.. you will need this info.

Creating a Format File
A format file is a simple text file that describes to the Radio Eyes Source File Converter where to find the needed information to produce the Radio Eyes random access catalog  ( _RE.dat). The ASCII text file from which the RE catalog is produced will be composed of single lines of data, each representing a single source. Within each of these "records" the pertinent data field will occupy a specific range of columns. For example, RA hours might extend from columns 8 to column 9 in each record. You may manually create the format file, or use the Create Format File Tool available on the Source File Converter window via the Open File Format Creator button. 

Using the Format File Creator
First use the Load Catalog File button to load the first line of the text radio source catalog into the text box at the top of the Format File Creator.  Now you will need those notes you wrote down that identified what each of the columns of the ASCII table represents.  Use the mouse to select the range of columns for a given value. For example, in the above image you see columns 14 through 17 selected. In this particular file my notes say this is the column range for RA seconds.  Now, double click in the appropriate text box, in this case the box immediately beneath RA SEC.  In fields other than the position fields you have to specify the name for the field but the columns range can still be transferred in the same way. In cases where it is not clear what the column limits are from the text line displayed, you can derive them from a hex editor such as Ultra Edit  (or one of the many free ones out there) and perusal through more of the file.

Note that you should name flux fields in a specific format.  Begin the field name with the capital letter "S" followed by the frequency in MHz for the entry. For example, a flux at a frequency of 617 MHz would be named "S617".

When all of the fields you want to reference are accounted for, press the "Create Format File" button.

Using the Source File Converter

Once the format file is in place (it must be in the same directory as the original ASCII text catalog!!!), use the Browse button on the converter window to locate the text catalog. The format file will be automatically loaded. Up to 30 fields within the records can be imported, but usually you will use less than 15 or so. Everything that does not deal with name, position, or flux measurement must be added into the comments section of the Radio Eyes data file.  Notice the 4 field columns.  On the left is the name of the field as suggested by the format file, the Field Name. If the format file plays by the rules and uses Field Names that the Source File Converter  recognizes, the proper field Type will be automatically selected in the Type column on the right. If for any reason this is not automatically done, you can scroll each Type setting to the proper name. Make sure that the Type name gets clicked on (it will turn blue) so that the program will recognize that it is selected.

The middle two columns are the beginning and ending character positions in the record where the data will be extracted from for each field type.  

Note: You can make changes to the Format File right in the Source File Converter. Just edit the lines in the format file multi-line text box and click the Update Format File button below it. The format file will be modified and reloaded into the Source File Converter.

Record Length
Records in the original text catalog must all be the same length. This is standard procedure though each text catalog may use a different record length; there is no rule making them all the same. However a problem can arise in how the records are separated. The usual case has each record ending with a carriage return and line feed character, but some catalogs may use just a carriage return, or possibly even no special character at all. When the Source File Converter or the Format File Creator loads the text file it tries to establish how the records or ending and then the proper length of the record.  Note the record length should include the special ending characters if they exist.

In a situation where the program cannot determine the record length, you can force it to use a record length that you know to be correct. Just make sure you have the Force Rec Len checkbox checked and the value you want to use typed into the Record Length box.  Check the documentation for the text catalog.  There is usually an associated Read Me file. You can also use a hex editor to try and determine how the records are terminated.

Source Name
Each source record must have a primary name. Some catalogs will have a name field and if so you can specify that field as the source of the name by giving it a Type of CAT NAME.  You can also allow the program to generate a standard name for the object from the coordinates based upon the epoch (J=2000) plus the RADEC coordinates. To have the program create the name this way select the Generate Standard Name checkbox.

Flux Minimum, Fields, and Units
Specify fields that indicate a flux measurement at a given frequency with a Field Name using the format SXXX, where XXX is the frequency in MHz for the measurement.  Give the entry a Type of FLUX. The default flux unit is the Jansky. If the source catalog uses some other unit of measurement you may specify it in the Units text box. If you only want the Radio Eyes catalog to include sources which have some minimum flux value and higher, specify that value in the Min Flux Filter text box.

Radio Eyes uses epoch 2000 coordinates.  If the catalog does not have position coordinates available in Epoch 2000 values, specify the the coordinate epoch year in the Epoch of Catalog text box. The positions will be precessed to epoch 2000 in the Radio Eyes source file.

Running the Converter
When you are certain you have everything correct press the Convert button. Depending upon various parameters, the program may ask you some additional questions during the conversion. Pay close attention to the message boxes if presented and to instructions in the status bar. The following steps are taken:

If you used some other directory to produce the new Radio Eyes source file, copy the file and its corresponding index file (.IDX) into the Radio Eyes \Catalogs\ directory for more convenient loading. Test the file by loading it into the program under View / Source / Source File.

Radio Eyes Help Home