pdplt

pdplt is a graphical tool for examining, viewing and editing of pointing data. pdplt reads the log file produced when pointing data was taken and generates a number of graphs which are designed to help the user to examine and edit the data. The data can then be saved as an output file in xtrac format, or printed to a postscript printer. Please refer to the xtrac manual for information on that file format.

1.2 Definitions

Log file Field System log file containing pointing data.

Log directory directory in which Field System log files are stored, usually /usr2/log

Antenna type XYNS (X/Y, North/South); XYEW (X/Y, East/West); HADC (Hour Angle/Declination) or AZEL (Azimuth/Elevation).

1^st axis X, Hour Angle or Azimuth axis, depending on the current antenna type.

2^nd axis Y, Declination or Elevation axis, depending on the current antenna type.

2.0 User Guide

2.1 Getting started: the File-New menu item

This section describes how to start pdplt, and the New menu item in the File menu.

To start the program, just type pdplt at the command prompt. A window will open on your screen, from which you can run the program interactively with your pointing device. If no window opens, please go to the section 5.0 Installation in this manual for further reference.

To open a new log file for input, select the New menu item in the File menu. A window will open, labeled Open new FS log file, in which you should enter the filename of the log file you want to examine. If you do not enter a directory path, pdplt defaults to the log directory. In order to open a file in the current directory (from which pdplt was started), you must enter ./filename, to specify that the file is in the current directory.

After you hit return in the Open new FS log file window, pdplt tells you if the filename was valid or not. If the filename was a valid log file, the day number of the initial entry is displayed. Hit return again, or press OK, to accept this log file. (NB! When running pdplt under Tk 4.0 and higher, pdplt may open the log file without first displaying the day number for confirmation). pdplt will now run the xtrac and error programs to extract data from the log file. This might take some time on older computers. If your system is correctly set up (i.e. the Tcl/Tk interpreter was found, and the xtrac and error programs were installed) the screen will eventually show a plot of the pointing data, 1^st axis vs. 2^nd axis. If an error occurred, see Troubleshooting in section 5.2 for further information.

Two error messages are possible in the Open new FS log file window. The first, The file specified could not be opened , is displayed if the open system call generated an error. The most probable reason for this is that the file did not exist. Please note that pdplt defaults to the log directory, not the current directory, unless otherwise specified. The second error message, The file specified did not start with a valid day no., is displayed if the file did exist, but did not start with five numeric (range 0-9) characters. All FS log files should start with a day number of five numeric characters. If it does not, the file may be corrupt and must be repaired before it can be opened by the pdplt program.

When you open a new log file, you may notice that the labels on the upper-right part of the screen change to fit your antenna type. The current antenna type is set by pdplt as specified in the xtrac control file, when reading the xtrac output file. Now, try selecting the graph menu, and switch between the different plots available.

2.2 Examining pointing data: the Graph menu

You can examine the pointing data using the different types of plots available in the Graph menu. These are:

1^st axis vs. 2^nd axis

1^st axis vs. 1^st and 2^nd axis offsets

2^nd axis vs. 1^st and 2^nd axis offsets

To change plot type, click on the Graph menu, and then on the plot desired. You may also use the n key on the keyboard, which switches to the next plot in the menu, and the p key, which switches to the previous plot. Changing plots may take some time on older computers.

2.2.1 Rescaling: the input fields in the main window

To rescale any plot, enter the new minimum and maximum values for the plot in the entry fields on the right part of the screen. The plot is updated when you hit return in any of those fields. Also, autoscaling is available by clicking on the appropriate autoscale button on the screen's lower-right.

NB! If a data point is out of range, i.e. the value is not within the minimum and maximum values of the current plot, it does not turn invisible, but is displayed on the border. That is, all points, or error bars, that are on the border of the plot may have any value that is out of range. A way to be certain of the accuracy of all points or error bars plotted is to use the autoscale buttons on the main screen. When a plot is first selected in the graph menu, the vertical axis is always autoscaled. The horizontal axis is set to certain default values, for example -90 to 90 degrees if you have an XYNS, XYEW or HADC type antenna.

2.2.2 Viewing data affiliated with data points: data points in the main window

To view data affiliated with a certain data point, simply move the pointer over the data point. The data fields on the screen's upper-right will tell you the following for the data point:

the 1^st axis coordinate

the 2^nd axis coordinate

the 1^st axis offset

the 2^nd axis offset

the 1^st axis offset sigma (current selected sigma, see section 2.2.3)

the 2^nd axis offset sigma (current selected sigma, see section 2.2.3)

the source for the data point

the elevation of the antenna when the data point was taken

For example, on an XYNS antenna, when moving the pointer over a data point, the data point fields might read:

X: -71.8

Y: -44.4

X-offset: -0.002

Y-offset: -0.00606

X-sigma: 0.00131

Y-sigma: 0.00472

Source: orion-a

Elevation: 13.0

2.2.3 Changing the current sigma type: the Sigma menu

When plotting the offsets, you will notice that error bars will be shown for the data points. If you have the latest version of the error program, there are different types of sigma values available. These are:

Input sigma values. These are the input sigma values to the error program.

A-priori sigma values.

A-posteriori sigma values.

You can change the current sigma type by clicking on the Sigma menu and choosing a new sigma type. The selected sigma value affects the error bars plotted, as well as the sigma value shown in the screen's upper-right part when the cursor is over a data point. Note that older versions of the error program only support Input sigma values.

2.2.4 Viewing statistics: the Statistics menu

Statistics, such as mean and rms values, can be viewed by clicking on the Statistics menu. The statistics are shown on the pull-down menu. Note that the statistics originate from the last time the error program was run. If you are editing data points out, the statistics will not be up to date until you have reprocessed your editing. See section 2.3.4 for instructions on how to do this.

2.3 Editing pointing data: manual editing in the main window

You may edit a data point out manually by moving the pointer over the data point and clicking the left mouse button once. The data point will turn white, which means that it is inactive. If you make a mistake, and want to re-add the point, just click on it a second time, and it will again turn black, which means that it is active. Manual editing can be done in any of the plots available in the Graph menu.

Note that the right part of the status bar on the bottom of the screen always tells you the number of good data points, and the total number of data points. When you click on a black point, turning it inactive, the number of good data points will be decreased by one.

Inactive data points are still plotted, but the autoscale procedure bypasses them. Hence, if the extreme value of any plot was edited out, that data point will be displayed on the border when the plot is autoscaled.

2.3.1 x-sigma editing: the Edit - x-sigma menu item

If you click on the Edit menu, and select the x-sigma menu item, a dialog box will open. In the dialog box you may enter a factor for x-sigma removal of data points. The default value is 3. This means that all data points which are more than three sigma away from the zero line, in any of the plots, will be automatically edited out. The value entered for x-sigma removal must be greater then zero.

2.3.2 Re-adding all points: the Edit - Add all points menu item

To turn all data points active, thus discarding any manual or x-sigma editing made, select the Add all points menu item in the Edit menu. All points will turn active, and they will all be plotted in black on screen. This is useful, for example, when an x-sigma process did not render the expected result.

2.3.3 Highlighting sources: the Sources menu

When editing data, it can be useful to highlight all data points originating from the same source. This may by done by using the Sources menu. When a file is opened, the input is scanned for all sources in the file. The sources found are put in the Sources menu. When selecting a certain source in the menu, all points (at least one) originating from that source are highlighted.

Note that you can also see what source a data point originated from by moving the mouse pointer over it. The source name will be displayed among the data fields on the upper-right part of the screen.

To turn source highlighting off, select the No source menu item in the Sources menu.

2.3.4 Reprocessing your data: the Edit - Reprocess menu item

After you have edited data points out, you might want to re-run the error program to update your data. This can be done by selecting the Reprocess menu item in the Edit menu. When Reprocess is selected, a new input file for the error program will be created, based upon your current editing. The error program is then executed, and the result again read into the pdplt program. For example, you will notice that the mean and rms values in the statistics menu will have changed.

2.4 Saving your work: the File - Save menu item

You can save your current editing by selecting the Save menu item in the File menu. When selecting Save the current editing will immediately be saved in the file names specified in I/O Setup . The setting of file names is discussed in section 2.4.2.

Two files are saved. The first is an output file of xtrac format. Please refer to the xtrac manual for information on this file format. Inactive data points are marked with a 0 in the first column of the file and active data points are marked with a 1 .

The second file is the output file from the error program. This is the file that was created when you last reprocessed your data. If you never reprocessed the data, it is the file generated by the error program when you started the pdplt program.

2.4.1 Opening a previously saved editing: the File - Open menu item

To open a previously saved editing, select the Open menu item in the File menu. In the entry field, give the file name to the file in xtrac format. Only files in xtrac format can be opened by selecting this menu item. When opening a new file, be sure that you have saved your current editing, or it will be discarded as the new input file is read.

2.4.2 File name conventions: the File - I/O setup menu item

File names are usually automatically set according to the FS naming conventions when you open a new log file. However, when you open a file of xtrac format, which is not named according to the FS naming conventions, pdplt cannot determine the proper file names. In that case, you must specify the output file names yourself. You may change the output file names by selecting the I/O setup menu item in the File menu. According to the FS naming conventions, the files should be named as follows:

Files in xtrac format: /usr2/log/xtrYYDDD

Files in error format: /usr2/log/errYYDDD

where YYDDD is the year and day number when the pointing data was taken. However, you may specify any valid output file name in I/O setup .

Other things that can be changed in I/O setup are the default directory for FS log files (which is usually /usr2/log), and the control files for the xtrac and error programs. Also, the file names of the temporary files pdplt uses can be changed, but these may only be changed before any log file has been opened. When the temporary files have been created, their file names cannot be changed.

Please note that all changes in I/O setup are temporary, and will not stay in effect the next time you run pdplt. To make permanent changes, you must change the parameters in the initialization section of the source code. These have comments to help you, but be sure that you know what you are doing.

2.5 Printing: the File - Print menu item

You can print any plot by selecting the Print menu item in the File menu. Plots are printed in encapsulated postscript (eps) format. If you select destination Printer , the lpr command will be used to print the plot. If you select destination File , the postscript output will be saved in the file specified in the Filename entry field. If you do not specify a directory, the current directory is used as default.

3.0 Implementation

pdplt is an event-driven program. After an initialization procedure, it sleeps and waits for user input. The user input calls a procedure, and when that procedure is finished executing, the program returns to sleep and waits for more user input.

The main task of pdplt is just to provide graphical user interface for the xtrac and error programs. Both of them are called when necessary, by giving execution commands to the operating system. The output from these programs is redirected to temporary files, which are read (and deleted at exit) by pdplt. The file names of the temporary files can be changed, see section 2.4.2 for information on how to do that.

4.0 Hints for Maintenance and Further Development

4.1 On Tcl/Tk

pdplt was developed using Tcl 7.3 and Tk 3.6. Tcl stands for "Tool Command Language", and Tk for "Toolkit", which is an extension to Tcl for writing graphical user interfaces. The language is normally interpreted, although compilers are now available. To start the interpreter, type wish -f sourcefile at the UNIX command prompt, where sourcefile is the Tcl/Tk script you want to execute. To be able to run the script without first starting the interpreter, the first line of the script should give the path to the interpreter, which is the case for pdplt, where it reads:

#!/usr/local/bin/wish

since this is the location of the interpreter on the GSFC workstations.

Since the language is interpreted it is fairly easy to port it to another platform, e.g., Windows 3.1/95/NT. Theoretically, all you would have to do is to install the Windows version of the interpreter, and start the same script as you did in the UNIX environment. However, some things must be changed, i.e. file names and operating system calls. Please refer to the Tcl/Tk for Windows manual pages for further information on porting Tcl/Tk scripts to this platform.

One of the main features of the Tk extension to Tcl is the ability to bind commands to X (or Windows) events. An X event is i.e. when the user moves the mouse, clicks the mouse buttons, or presses a key on the keyboard. This makes it very convenient to write interactive programs like pdplt. However, in pdplt, very few application-specific X event bindings are used. Most Tk widgets created keep their default bindings as specified in the Tcl/Tk manual pages. The application-specific bindings made can be found be searching for bind commands in the source code.

4.2 On the source code of pdplt

The source code is divided into sections, each of them containing related Tcl/Tk procedures. This is a short description of them.

4.2.1 The initialization section

This section is executed only once, at startup. Some of the Tk widgets section is also executed at startup.

Since there is no #DEFINE statement in Tcl, pdplt starts with setting a number of global variables. These are later made accessible in sub-procedures by use of the global command. Those variables that are not trivial have comments in the source code, like Default directory for log files etc.

4.2.2 The disk I/O section

This section contains procedures whose main task is to perform disk I/O, for example to:

Read the output of the error and xtrac programs.

Scan the input data for sources and build the Sources menu.

Create a new input file for the error program and execute error when necessary.

Save the current editing.

However, some procedures in the newfile and openfile sections also performs disk I/O. Those sections are directly related to dialog boxes.

4.2.3 The plot section

This is the core part of the program. All mathematics required for calculating screen coordinates for the plots is implemented in this section. Also, the procedures for toggling points active/inactive are here. The parent plot procedure is named Replot, which calls a child procedure, called pdplt, to do the actual work.

4.2.4 The newfile and openfile sections

These sections are directly related to the dialog boxes they are controlling. They are very similar. The first procedure is the procedure called when the corresponding menu item is selected. It creates the dialog box by calling a procedure in the Tk widgets section and does some initializing. The second procedure is called when the user has clicked the OK button. It takes care of opening the file selected, and running the xtrac and error external programs. There is also a procedure for checking if the file name entered is valid, and finally, there is a procedure for clearing the entry fields in the dialog box.

4.2.5 The print, preferences and sigma sections

These sections also control dialog boxes. They also contain the code that is executed when the OK button of the corresponding dialog box is pressed.

4.2.6 The Tk widgets section

This section contains everything that has to do with creating the graphical user interface. Creating the interface is a two-step procedure. First, the widgets (entry fields, labels, menus etc.) are created and given a unique name. Then they are displayed on the screen, using the Tk pack geometry manager.

Some of the code in the Tk widgets section is executed at startup. That is the code for creating the main window, and completing the File and Edit pull-down menus. The widgets used for dialog boxes are created when their menu item is selected, and destroyed when the OK or Cancel button is pressed. Other menus are completed when a log file is opened, for example the Sources menu.

Creating the menu widgets also includes specifying which commands that should be executed when the menu items are selected. For example, the line:

.mbar.edit.menu add command -label "Reprocess" -command runError

tells the interpreter to run the procedure named runError when the user selects the Reprocess menu item. To understand in which order the source code is executed, it is often a good start to search for the add command statement and following the procedures called. This can be a useful method for maintenance.

5.0 Installation

In order to work, pdplt requires the following installation procedure:

The Tcl/Tk interpreter wish must be installed. For information on how to do this, please read the Tcl/Tk information available on the Wold Wide Web. For example, Yahoo has a page on Tcl/Tk, from where software as well as documentation may be downloaded. Please note that pdplt was developed using Tcl version 7.2 and Tk version 3.6. If you are installing the latest version of Tcl/Tk (as of July 24, 1997, Tcl 7.6 and Tk 4.2), pdplt may require some conversion to work. As long as the major version number (Tcl 7.x and Tk 3.x) is the same, the version is backwards compatible. However, the upgrade to Tk version 4.x is not completely backwards compatible.

The first line of pdplt must be changed to give the path to the interpreter. For example, on the GSFC workstations, it reads #!/usr/local/bin/wish .

The error and xtrac programs of the Field System must be installed and in the search path.

The UNIX grep and tail commands must be available and in the search path.

5.1 Licensing

This is the license statement for the Tcl/Tk interpreter:

"This software is copyrighted by the Regents of the University of California, Sun Microsystems, Inc., and other parties. The following terms apply to all files associated with the software unless explicitly disclaimed in individual files.

"The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No written agreement, license, or royalty fee is required for any of the authorized uses. Modifications to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first page of each file where they apply.

"In no event shall the authors or distributors be liable to any party for direct, indirect, special incidental, or consequential damages arising out of the use of this software, its documentation, or any derivatives thereof, even if the authors have been advised of the possibility of such damage.

"The authors and distributors specifically disclaim any warranties, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement. This software is provided on an "as is" basis, and the authors and distributors have no obligation to provide maintenance, support, updates, enhancements, or modifications.

"Government use: If you are acquiring this software on behalf of the U.S. government, the Government shall have only "Restricted Rights" in the software and related documentation as defined in the Federal Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you are acquiring the software on behalf of the Department of Defense, the software shall be classified as "Commercial Computer Software" and the Government shall have only "Restricted Rights" as defined in the Clause 252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the authors grant the U.S. Government and others acting in its behalf permission to use and distribute the software in accordance with the terms specified in this license."

5.2 Troubleshooting

Problem: The log file cannot be opened. A Tcl error message shows up, ending with child killed: segmentation violation .

Solution: You are trying to run xtrac with a control file that specifies a different antenna type than the antenna type of the log file you are trying to open. You must change the antenna type in the xtrac control file to agree with that of the log file. Please see the xtrac manual for information on how to do this. You may temporarily change the path for the xtrac control file by selecting the I/O setup menu item in the File menu, see section 2.4.2.

Problem: When starting pdplt, the interpreter bails out at the focus default . command. The error message ends with should be: -displayof, -force or -lastfor

Solution: You are trying to run pdplt on a later version of Tk than it was developed for. The best solution is to install Tk 3.6. However, the focus default . command is not very important and can be removed from the source code, by typing a # in front of it. The # character is the Tcl/Tk remark character. However, if you continue to have problems with pdplt, you should install Tk version 3.6 or contact tech support.

Problem: When reprocessing data, or at startup, the Tcl/Tk interpreter bailed out with a very strange error message.

Solution: The xtrac or error program may have bailed out due to the nature of the data. In that case, an error message would have been written to your standard output device. You should save your editing, quit pdplt and read the error message generated by the external program.

Problem: The status bar reads WARNING: Check output file names in 'I/O setup' after trying to open a file in xtrac format.

Solution: pdplt was unable to determine the proper file names for your data according to the FS naming conventions. You must set the file names manually in order to be able to save your editing. See section 2.4.2 for details.