PSRGUI is invoked by speaking (well, typing) its name, followed by zero or more filename arguments. There are a few other options you can give on the command line, mostly related to setting things like output verbosity and directly specifying the pgplot device to use (though anything other than an X11 based device would be a little self-defeating in terms of GUI functionality). A list of command line options can be summoned with the usual "-h" option.
The metafile option allows you to give the program the name of a file that contains a list of other filenames. The 'metafile' will be parsed, and all the files it contains will be given to the GUI.
PSRGUI can be run without any arguments, in which case it brings up the user interface and waits for the user to load an archive using the "Load" button. You can also specify one or more filenames on the command line. If a single file is given, it will be loaded automatically. If multiple files are given, they will be displayed in a box at the bottom of the control panel. Double clicking on a file name inside this box will load it into memory.
If there is a current file active, it's header information will be displayed in the status box, just below the 'Reload' button. Any processing or plot commands will be performed on this file. Hitting the reload button will re-read the current file, effectively undoing any processing you may have done. You can save a modified archive at any time using the "Save" and "Save As" buttons. "Save" overwrites the original data while "Save As" prompts you for a new filename to which the archive will then be written, leaving the original untouched.
The processing button group allows you to perform simple tasks:
T Scrunch : Scrunch the integrations in time
F Scrunch : Scrunch the profiles in frequency
P Scrunch : Scrunch the profiles in polarisation
Centre : Rotate the integrations so pulse phase zero
is centred on the screen
To perform one of these operations, tick the box next to its name and hit the 'Process' button.
Using the checkboxes causes the scrunch operations to scrunch all the data in one go. The scrunch buttons can be used to scrunch one level at a time for finer control.
If you are working with multiple files, it may be useful to have the program perform some of the processing by default whenever you load an archive. This can be done by selecting the "By Default" checkbox. If this box is ticked, any new archive that is loaded will be processed automatically, according to the state of the other 5 checkboxes. There is no need to press the "Process" button. Note that the additional processing can significantly increase the time it takes a file to load. The default processing will be done on archives loaded using the file menu or selected in the file box if multiple files were given on the command line. The reload button will also cause processing to be done if the default checkbox is selected.
Most archives will contain a number of sub-integrations, each of which will contain multiple frequency channels and polarisations. Any pulse profile in the archive can be viewed by selecting the appropriate values using the three sliders following the processing options box. The sliders will have their ranges set according to the dimensions of the archive. If a slider is stuck on zero, there is only one profile available in that dimension. The slider ranges will change according to any processing you do to the data.
Once you have selected which profile and/or integration you want using the sliders, it can be displayed using the plot buttons. You can do one of five things:
The next two sliders in the GUI allow you to split the view window into several section, each of which behaves like an independent plotting environment. To do this, select the dimensions you would like used when dividing the window (eg. setting Xdim = 2 and Ydim = 3 would give you six seperate plot regions, in 3 rows and 2 columns). Now hit the "Slice" button. The window will clear and the sliders will jump back to their leftmost position. The top left plotting zone is automatically selected. Any plotting you do will now appear in this smaller region. To select any of the other regions, just move the slider to the appropriate coordinates. There is no need to hit any buttons, changing the sliders is enough to select the new region. To clear the sub-division away and go back to a single plot window, hit the "Reset" button.
If you have multiple files loaded, and you are in multi-plot mode, the two buttons at the bottom of the GUI will be activated. These allow you to trawl through all the files you have in the selector box, plotting them in groups of as many will fit in your sub-division scheme at a time. Using these buttons in conjunction with the default processing checkbox is a good way of examining a large number of archives quickly.
Different colour maps can be chosen via a pull-down menu underneath the "Save" button. Sometimes subtle features in the data are easier to see in different colour maps.
It is also possible to automate the display of data using the movie mode feature. Start the show by selecting the desired display in the "Movie" pull-down menu. It will loop until the "Stop" item in the same menu is selected. Frame rates can (to a certain extent) be modified by changing the delay time.
A new feature since version 1.13 is the ability to zoom in on a pulse phase window using the two small text entry boxes either side of the button marked "Zoom", just above the plot control buttons. A phase window can be typed into the boxes directly (min on left, max on right) or you can hit the zoom button and click on the minimum and maximum points in the plot window to auto-select a phase range. Note that changes do not take effect until the next time a plot button is pressed.
It is possible to re-direct the output of the plot window to a postscript file on disk (thanks to the wonder of pgplot, assuming you have the postscript drivers compiled in). This is done via the "PS Mode" button. Clicking this button will open a postscript file (psrgui.ps) and any subsequent plot commands will be re-directed to this file. To close the file, simply click the "PS Mode" button again and the output will be re-directed back to the X11 pgplot window.