Getting Started Documentation Glish Learn More Programming Contact Us
Version 1.9 Build 1488
News FAQ
Search Home


next up previous contents
Next: Copyright Up: Volume 2 - Generic Processing Previous: 5. GBT Continuum Single dish Imaging

Subsections



6. Single Dish Analysis

R.W. Garwood & J.P. McMullin

6.1 Introduction

DISH is a collection of Glish scripts and clients which provide an environment within AIPS++ for single dish radioastronomy analysis.

The latest version of DISH merges development between the single dish and interferometric efforts in AIPS++. DISH is a standard tool and may take advantage of the tool manager interface. DISH also has a new and much simplified Command Line Interface (CLI). Note: If you have used previous versions of AIPS++/DISH, you must remove the file containing the previous state information. This is contained in a file called default which will be under your home directory in the aips++/dishstate directory:

> rm ~/aips++/dishstate/default

This will prevent spurious errors from appearing upon startup due to the changes in the software from the last release.

More information is available on DISH in the User Reference Manual.

DISH may be accessed in several ways:

1.
After setting up the environment for AIPS++:

> . /aips++/release/aipsinit.sh       # bash shell AIPS++ setup
> source /aips++/release/aipsinit.csh # (t)csh shell AIPS++ setup

execute:

> glish -l dish.g                     # to load just the single dish analysis
or
> aips++ -l dish.g                    # to start AIPS++ with single dish

2.
Once in AIPS++, it can be accessed through the tool manager interface.
(a)
Select on Packages, dish.
(b)
Select on Modules, dish.
(c)
Select on Tools, dish.
(d)
Press create.
(e)
Choose the toolname for the new DISH tool and press "Create".

3.
Once in AIPS++, it can be accessed from the command line.
(a)
include 'dish.g'
(b)
d:=dish();

The default is to start the dish tool with the GUI interface as before. However, this may be over-ridden using a local .aipsrc value:

#dish.gui.auto:T
dish.gui.auto:F

In this release (v1.7), DISH may use AIPS++ flat tables (filled through the fits2table command) or MeasurementSets (either generated naturally or converted via sdfits2ms or through facility fillers (e.g., gbtmsfiller)).

6.2 Getting Data Into Dish

There are several ways to get data into DISH:

6.2.1 MeasurementSets

If you have data produced as a MeasurementSet, it merely needs to be loaded into the system. From the GUI, this entails using the Open option in the File menu (either Read only or Read and Write). This opens up a file chooser GUI which allows you to select the relevant file. From the command line, the command:

- d.open('pne.ms');

Loads the file into the results manager and is ready for use.

6.2.2 Facility filler (e.g., GBT)

Some facilities have native fillers which directly convert raw data formats into the MS format. An example based on the GBT is provided below:

gbtmsfiller project=zeroSpacing01 minscan=401 maxscan=441 msrootname='oriona1_'
 fillrawpointing=True

where project = the GBT project directory
      minscan = first scan to fill
      maxscan = last scan to fill
   msrootname = the name of the output MS; this will have the Backend used
                appended to it.

A dish utility function, import, streamlines this process, filling the data and doing an open on the resulting MeasurementSet.

6.2.3 SDFITS data file (e.g., Arecibo Observatory)

1.
Convert to MS

Use the AIPS++ utility sdfits2ms to convert from a fits file following the SDFITS convention to an AIPS++ table. The syntax, from the UNIX prompt, is:

sdfits2ms sdfits_name ms_name, for example:

charybdis<965>$ sdfits2ms n7027.sdfits n7027.ms
0%....10....20....30....40....50....60....70....80....90....100%
End Successfully:      34.79 real        5.43 user        5.03 system

2.
Use the AIPS++ utility fits2table to convert from a binary table following the SDFITS convention to an AIPS++ table. The syntax, from the UNIX prompt, is:
fits2table input=sdfits_file output=aips2_table [which_hdu=#]
where ``sdfits_file'' is the name of the SDFITS file and ``aips2_table'' is the desired name of the new AIPS++ table created by this step. The third argument, ``which_hdu'', is optional. Use this to specify a specific FITS header data unit (hdu) other than the first one after the primary hdu. For example, if you have a FITS file which has three tables following the primary hdu and the second table is a valid SDFITS table then you would use which_hdu=2 to indicate that that hdu is the one to be converted to the indicated output AIPS++ table.

Note: Arecibo Observatory data may be brought into DISH in this manner.

6.2.4 UniPOPS SDD data file

There are three steps to getting a UniPOPS SDD data file into DISH:

1.
Convert UniPOPS SDD data to UniPOPS FITS binary table.

Use the UniPOPS utility uni2fits to convert the SDD data to FITS binary format. To use the program, you must be logged onto a Sun workstation where UniPOPS has previously been installed and have your path include:

export popsdir=~unipops/test/
export PATH=$popsdir/sunbin:$popsdir/utilities:$PATH
purgatory<143>$ uni2fits
Starting uni2fits ver 1.3 
So you want to write UniPOPS data to FITS tape eh?
 (to abort this dialog, type CNTRL-C)
 
Do you want output file on disk(D) or tape(T)? [default=D]: 
Using default (D).
Please enter name of output FITS file: hbnmeth.fits
Output file will be: hbnmeth.fits 
 
Choose line or continuum (L, C) [default=L]:    
Using default (L)
 
Label scan axis as Frequency(F) or Velocity(V) [default=F]: V
 
Please type input UniPOPS file name: sdd.www_001
Do you want to choose a scan number range? (y or n) n
--------------------------------------------------------
Ready to make FITS file, name = hbnmeth.fits
 Will use all L scans from sdd.www_001.
 is this ok? (type Y to proceed) Y 
 
Getting initial information from UniPOPS file.
1+0 records in
1+0 records out
 
Previewing the UniPOPS file.

u2f version 1.5 (22Apr98),  run: Fri Oct 13 14:19:36 2000
12182+0 records in
12182+0 records out
Wrote 0 scans out of 3018; 0 fits records written. 
 
Converting the data to FITS.

u2f version 1.5 (22Apr98),  run: Fri Oct 13 14:20:50 2000
12182+0 records in
12182+0 records out
Wrote 2674 scans out of 3018; 1675 fits records written. 
 
FITS writing complete.

2.
Convert UniPOPS FITS to standard SDFITS.

Use the AIPS++ utility uni2sdfits to convert the data file. The syntax is:

uni2sdfits input=unipops_fits_file output=sdfits_file
e.g.
charybdis<276>$ which uni2sdfits
/aips++/daily/linux/bin/uni2sdfits
charybdis<277>$ uni2sdfits input=hbnmeth.fits output=hbnmeth.sdfits  
uni2sdfits: Version 1999/07/30 BEG/TPPR/PJT/GvD

Scanning all HDUs looking for any non-constant DATA column shapes
Skipping HDU 0 of type : 1
Scanning HDU 1 of type : 4
HDU 1 is a BinaryTable with fixed shape DATA column with TDIM = (128,1,1,1,1)
Primary HDU
HDU # 1
column SERIES renamed to DATA
column BANDWIDT renamed to BANDWID
column PROJECT renamed to PROJID
column VELOCITY renamed to VFRAME
column VCORR renamed to RVSYS
column TOUTSIDE renamed to TAMBIENT
column BEAMWIDT renamed to BMAJ
NMATRIX keyword removed
MAXIS keyword removed
MAXIS2 keyword removed
MAXIS3 keyword removed
MAXIS4 keyword removed
MAXIS5 keyword removed
Removing column 2 : MAXIS1  
keyword value set: TDIM195 = (128,1,1,1,1)
done.

3.
Convert the SDFITS file to an AIPS++ table (either a MS or a flat table). See Section 2.2.

6.2.5 Dish demo data

There is also a utility for loading demonstration data into dish as a check of the functionality. More information is given on this in the Getting Results in AIPS++ Documentation.

- include 'dishdemodata.g'
- dishdemodata() # this will create several demo working sets
- 		 # on disk, which are then available to be loaded and
-		 # worked upon.
-                # dishdemo1, dishdemo2, dishmopra, dishparkes, dishspecproc
-		 # each of these can be accessed through the open command, e.g.
- d.open('dishdemo2'); # assumes 'd' is the defined DISH tool.

6.3 The Dish Graphical User Interface

In DISH, wherever practical, what you see is what you are operating on. So, for example, when you press the ``Apply'' button in the ``Baselines'' graphical user interface (GUI) frame of DISH, a baseline will be fit to whatever is currently plotted in the DISH plotter. Results appear in the results manager and, when appropriate, are immediately displayed on the plotter. Results can be moved between the results manager, the calculator, and the browser through the use of a menu which appears when the user presses the right mouse button in one of these frames. This default behavior can be changed so that selections from the Results Manager will be operated upon. This change is necessary to perform functions on SDIterators (see Bulk Processing).

The current state of DISH (the contents of the results manager, the settings of all of the operations, the contents of the calculator, and any active browsers) can be saved at any time either to the default state file or to a location of the user's choosing. DISH can be restored to a previously saved state. By default, DISH saves its state upon exit from glish and restores itself to that same state when DISH is started in a new Glish session.

The following sections detail the major graphical components of DISH.

6.3.1 Results Manager

The Results Manager is the heart of DISH. All results which DISH creates in response to user actions are stored in the results manager and listed in the Results window. These results are all available at the Glish command line as glish variables of the same name for the user to interact with. DISH immediately plots the currently selected result if it can be plotted. A description is associated with each result. The user can change the description or the name of the result if they choose to do so. Certain results can also be browsed. Since each result is also a glish variable of the same name, new names are limited to be a valid glish variable name.

Results can be copied to and from the clipboard or to the calculator. This Copy/Paste facility is activated by pressing the right mouse button when the mouse pointer is over the Results window. A popup menu appears with the three possible options. The current selection is copied to the chosen destination when a copy option is selected. The contents of the clipboard are pasted into the results manager when that option is selected.

6.3.1.1 Working sets, SDRECORDs, and everything else

Results are either working sets (also known as sditerators), SDRECORD, and anything else.

A working set is a collection of SDRECORDs. Specifically, it is an sditerator tool. When you open a data set through the File menu (either a new one or an existing one) the result is a working set which will be shown in the results manager. The other way to create a working set is to use the ``Apply'' button in the ``Selection'' operation. When you make a selection this way the result is also a working set. It does not make a copy of the selected data, rather it makes a reference to the selected data in the underlying data. This means that if you change the underlying data, the reference in the selected data is also changed. Working sets can be browsed. See the Reference Manual for more information on the Sditerator tool.

An SDRECORD is a Glish record which has the structure described below. It is data (generally spectra at this point in DISH development) plus some standard header values, any non-standard header values, and a history of what has been done to that particular SDRECORD. SDRECORDs can be browsed and plotted.

Anything may appear in the results manager. If it isn't a working set or an SDRECORD it can not be browsed or plotted.

6.3.2 Menubar and Message Line

New data files are created, existing data files are opened, the state of DISH is saved, a previously saved state is restored, and DISH is reset to its default initial state through the File menu. The GUI panels for each available operation are enabled and dismissed through the Operations menu. The Options menu has two options which can be turned on or off. The ``Write to Script'' option, when turned on, causes DISH to echo the underlying glish commands to the AIPS++ defaultscripter (ds) tool when a GUI operation occurs in DISH. This can be a way to learn more about what DISH is doing behind the scenes and write glish scripts to do operations not yet available in DISH. When the ``Save when done'' option is turned on, the state of DISH is saved to the current state file when the ``done'' function is invoked (e.g. dish.done()). The ``done'' function is always invoked whenever you exit glish. Because DISH can not be restarted after ``done'' has been called it is best not to do that unless you are about to exit glish. This deficiency will be corrected in the next release.

The Message Line is the text immediately below the Results Manager. These messages are also echoed to the AIPS++ logger for longer term storage.

6.3.3 Browsing

A working set within the results manager can be 'browsed' or examined by hitting the 'Browse' button. This brings up a frame which lists all of the scan numbers and objects, record by record, within the working set. Each SDRECORD can also be browsed to examine all of the contents (e.g., all of the header information and data).

When browsing a working set, individual records can be copied to the clipboard or to the results manager. This copy facility is activated by pressing the right mouse button when the mouse pointer is over the browser window. A popup menu appears with the three possible options. The current selection is copied to the chosen destination when one of the copy options is selected.

6.3.4 Inspecting

Inspecting is another way of viewing the values of the results within the results manager. It lists all of the contents of the selected result. These may be accessed via the Glish command line by the names shown while inspecting.

6.3.5 Operations

Currently there are eleven operations pre-defined within Dish. These operations are general utilities available from the basic Dish Gui. All operations have two basic buttons: a green Apply button which will execute the given operation and a yellow Dismiss button which will close the operation frame but retain all information in that frame for subsequent use.

6.3.5.1 Averaging

The Averaging operation offers several options for performing the averaging (Figure 6.1). Alignment which may be either None, By Velocity, or By X-Axis, 2) Rest Frequency, which allows shifting to match the first in the average (for example, for averaging spectra from transients), 3) Weighting which may be None, Tsys and Time or by RMS, and 4) which will use any selections chosen from the Selection Operation prior to averaging.

Figure 6.1: Example window showing basic Dish frame with the Averaging and Selection Operation frames open.

6.3.5.2 Baselines

Figure 6.2: Example window showing basic Dish frame with the Baseline Operation frame open. In this example, one baseline region is selected and a 5th order polynomial will be shown overlayed on top of the spectrum.

The Baseline operation allows either a polynomial fit or a sinusoid fit. The baseline regions may be typed into the regions entry box at the bottom of the frame, or selected via cursor (the Plot Ranges and Cursor Active buttons should both be checked). The baseline operation frame can be seen in Figure 6.2.

The default action is to calculate the baseline and show it. Once the fit seems satisfactory, the 'Subtract' button must be checked and the fit 'Apply'd. This will remove the baseline and display the resultant spectrum. The baseline fit may be viewed from the results manager. The current ranges selected will be displayed in the entry field. A history of these is preserved within a cache which can be viewed by clicking on the down-arrow button. The RMS of the fit is displayed to the right of the frame. Units for ranges or fit parameters (sinusoid only) may be converted between channels and X-Axis units using the Convert button.

6.3.5.3 Calculator

The Calculator operation is a general tool for manipulating spectra in ways not facilitated by the basic set of operations. Spectra may be transferred into the calculator stack through the use of the Copy/Paste to Clipboard facility.

Figure 6.3: Example window showing basic Dish frame with the Calculator Operation frame open

The Copy/Paste facility is activated by the right mouse button. A popup menu appears with a two copy options and a paste option. ``Copy to clibpoard'' will copy whatever is selected in the Calculator stack listbox to the Clipboard; the Clipboard is simply a convenient virtual storage area. ``Copy to results manager'' copy whatever is selected in the Calculator stack listbox to the results manager. ``Paste from clipboard'' retrieves whatever was most recently sent to the clipboard. For example, in Figure 6.3, the Results Manager spectrum ``average3'' was copied into the Calculator stack. An ``_1'' designation was added to the label to distinguish it from the same value in the Results Manager. The spectrum was then multiplied by a factor, producing ``average3_1_2''. The additional id tag is an underscore and the stack number.

The available functions may be seen in the figure. In addition, it works as any standard Reverse Polish Notation calculator. Numbers, vectors and arrays may be typed into the entry field. The calculator will only work with SDRECORDs, numbers, vectors and arrays.

6.3.5.4 Function on Data

The Function on Data operation is another means of manipulating the displayed data. The string typed in the entry box of this operation is evaluated by glish after any of the standard macros are replaced by their equivalent glish. The result of this evaluation is then reassigned to the data array of the last viewed SDRECORD. The standard macros and their meanings are:

DATA
sdrecname.data, the data record of sdrecname.
DESC
sdrecname.data.desc, the data description record of sdrecname.
ARR
sdrecname.data.arr, the data array.
HEADER
sdrecname.header, the header record.
NS_HEADER
sdrecname.ns_header, the ns_header record.
In the above definitions, sdrecname is whatever the name of the last viewed data set. For these macro substitutions to work, they must be given as upper case (to distinguish them from their lower case equivalents, in which no substitution would occur).

Since whatever this text evaluates to after macro substituion is reassigned to the data array, it must have the exact same shape as the data array initial had.

Basic scaling or manipulations can be obtained by typing expressions that operate on ARR. For example, a simple scaling can be obtained by typing the function ``ARR*1.5'', and then pressing ``Apply''. Any function available from within Glish or known at the command line (e.g. a function defined by the user during the run of Dish), can be accessed and used in these expressions.

6.3.5.5 G Fit

The Gaussian Fitting operation is not contained under the main operation menu. Instead, it is available directly from the plotter. Pushing the ``G Fit'' button calls up the interface window. The number of gaussians to fit is set by the ``No. components'' slider and entry field. The number can either be typed in or the slider can be adjusted to the number of gaussians desired. This number will be reflected in the number of component buttons created below. Depressing a component button makes it active, allowing setting of its properties.

Depressing the green ``Estimate'' button generates an auto-estimate of a component, generating an approximate flux, pos, and width (height, center, width for the gaussian). Depressing the green ``Fit profile'' button will generate a fit based on that guess. Interactive estimates for each component can be obtained by pressing the component button followed by the ``Inter'' button (below the ``Estimates'' title). This prompts the user to: ``Put cursor at line center and click (any)'' and then ``Put cursor at line HWHM and click (any)''. This fills the flux, pos and width fields with the appropriate guess. Continue with the next component and then hit ``Fit profile'' when all have been defined.

The Plot menu at the top of the frame allows the user to specify which aspects of the fit to view: Estimate, Fit, Residuals. Each of these may be toggled on-off interactively.

Figure 6.4: Example window showing the GUI gaussian fitting interface

Figure 6.5: Plot showing the results of a 2-component gaussian fit to line profile. The fit and residuals only are displayed. The chalkboard feature has been used to draw a label indicating the line (``HI''). fitting interface

6.3.5.6 Re-gridding

The Re-gridding operation is a more generalized version of the Smoothing Operation as it allows both finer and coarser adjustments of the grids. Currently, it allows Hanning, Boxcar and Gaussian smoothing along with Spline and Fourier Transform Interpolations.

Figure 6.6: Example window showing basic Dish frame with the Regrid Operation frame open

6.3.5.7 Saving

The Saving operation allows the user to store and organize spectra into named working sets. The working set must first be defined through the File Menu option ``Open'' (selecting on Read and Write). Once the working set is defined, any displayed spectrum may be written to the working set on disk.

6.3.5.8 Selection

The Selection operation allows a number of selection criteria to be chosen to create new working sets which are subsets of existing working sets. The available entry fields are: Object Name, Record, Scan, Date, LST, and Rest Frequency. Typing into any of these fields is allowed but the selection will only be used if the check box on the right is marked. A history of selected ranges or names will be preserved. For numerical selections, ranges may be made as follows:

Record,Scan Entry:
8,9,10				# Select scans 8, 9 and 10
8,[10:13],17			# Select scans 8, 10, 11, 12, 13, and 17

For Object Name selection you can type in a single name by typing any characters except quotes (single or double) and square brackets. That name will be used in the selection. The ``*'' can be used as a wildcard. For multiple source names you can either enclose the source names with double quotes or you can use the glish bracket syntax to indicate a vector of source names. The following examples illustrate these differences:

This is one long source name   # a single source name
"This is five source names"    # turned into five strings by glish
['This','is','five','source','names'] # same as previous example
['This','is three','source names'] # three sources

The ``All'' button will display all relevant values for the given entry field in a separate pop-up window.

6.3.5.9 Smoothing

The Smoothing operation is a more specific tool than the Re-gridding operation. It offers easy Hanning, Boxcar and Gaussian smoothing.

Figure 6.7: Example window showing basic Dish frame with the Smoothing Operation frame open

6.3.5.10 Statistics

The Statistics operation calculates basic statistics on an interval of the spectrum. The interval must be defined by the cursor (activate the Plot Range and Cursor Active buttons) and then left click on the left and right regions of the spectrum which are of interest. The region will appear in the Range entry field and the Start and Stop fields will be populated by the beginning and end of the range; NOTE: currently, only the first range in the rangebox will be used for the calculation of statistics. If you want changes to the start and stop range for your interval, those changes should be edited or entered at the start/stop entries. The units may be converted between X-Axis units and channels through the convert button (similar to the Baseline operation capability). The Apply button will calculate the Peak value, the location of the peak, the Area over the region, the location of the centroid (half area), the rms, and the minimum. These values may be written as a record to the clipboard through the ``Copy to CB'' button. The record looks as follows:

- statrec:=dcb.paste()
- statrec
[peak=2.09596825, area=29425582.1, min=-0.26479581, rms=0.580018938, scan=20, ce
ntroid=2.22369707e+10, vpeak=2.22353317e+10] 
-

In addition, the data may be written to a file through the ``Print to File'' button. This pulls up a frame which prompts the user for a filename. If the file exists, it will append the values to the end of the file. The file looks as follows:

  scan  start          stop           atPeak         Centroid 
    20  2.2225160e+10  2.2245390e+10  2.2235332e+10  2.2236971e+10 
        Peak           Area           Mininum        rms 
        2.0959682e+00  2.9425582e+07 -2.6479581e-01  5.8001894e-01

Figure 6.8: Example window showing basic Dish frame with the interval Statistics Operation frame open

6.3.5.11 Write to File

This operation allows convenient output to a disk file in the current directory. It automatically defaults to the file name of ``scan_number.spc''; for example if you Write to File while looking at scan 20, the file will be ``20.spc''. The file looks as follows:

     FREQ              other axis 
       Hz              other unit 
22203023360.000000    -3.907563 
22203086216.617188    -4.986684 
22203149073.234375    -4.020397 
22203211929.851562    -4.558375 
22203274786.468750    -4.556173 
22203337643.085938    -3.856671 
22203400499.703125    -4.001695 
22203463356.320312    -3.464213 
22203526212.937500    -4.438780 
22203589069.554688    -3.296077 
...etc.

6.4 Saving/Restoring State

If you do nothing, a file called default will be created within the $HOME/aips++/dishstate directory upon exiting from a DISH session. The file is created automatically and dish will be restored to the state saved in that file automatically upon startup. The dish state file contains all of the values known to the results manager as well as the various settings for each GUI element and operation. So, by default a record is kept of the state of DISH after each use of DISH and DISH is restored to this state the next time DISH is used.

There are several ways in which you can alter this default behavior.

6.5 The Dish Plotter

The Dish Plotter is the familiar AIPS++ pgplotter tool, modified for additional utilities and capabilities. Any activity or task within Dish which produces a plottable result, will automatically have the result displayed in the Dish Plotter; for example, selecting entries within the Results Manger, the SDRecord Browser, or Calculator Operation stack will plot the selection chosen. The plotter features tools for 1) changing the X-axis units, 2) changing the reference frame for the X-axis, 3) toggling header information display, 4) toggling the overlay of subsequent plots, 5) options for a) altering the colors of the plot (reverse color) and b) allowing a draw facility (chalkboard), 6) toggling the X-axis autoscale, 7) unzoom (incrementally unzooms any zooms), 7) activate the gaussian fit tool, and 8) line identification (marks any molecular lines within the frequency ranges of the displayed plot. The cursor position is continuously displayed in the grooved box at the bottom of the plot whenever the cursor is within the DISH plotter frame. The plotter is arrayed as shown in Figure 6.9.

Figure 6.9: Dish Plotter Appearance. Displayed is a baselined GBT frequency switched spectrum. The baseline regions are marked by the white boxes whose height indicates the rms in that region. The different lines are different polarizations as labelled in the upper left.

File Menu

This is the standard pgplotter File menu. Open...: This operation will read a plot file on disk written by the Save command. Save: This operation will write a vector plot file of the displayed image to disk. Save will write to the file specified in Feature L (defaults to dish.plot). Print: This operation will print the current spectrum. Dismiss: This closes the plotter window while Done destroys the tool (not recommended!).

Tools Menu

This provides a zoom tool and colormap tool (not relevant for single dish case).

Edit Menu

This brings up a frame which allows interactive editing (changing of existing commands) or addition of new commands. For example, additional labeling or fiducial lines may be easily added. The frame lists all of the available PGPLOT commands. Selecting one brings up a brief explanation along with the various arguments required. The frame also lists the PGPLOT commands which produced the displayed frame. Again selecting a command brings up a small explanation along with the arguments used in its execution. Cut, Copy, and Paste features are available to duplicate and add additional commands. An example frame is shown in Figure 6.10.

Figure 6.10: Add commands frame for Dish Plotter.

Help Menu

Standard pgplotter help menu. The options are: 1) PGPlotter: will drive your Netscape browser to the help section on the PGPlotter. 2) Reference Manual: will drive the browser to the Reference Manual main page. 3) About Aips++...: provides basic information about the AIPS++ version being used.

Plotfile name

This is the filename that the Save option in the File menu will save to by default. The default plotfile name is dish.plot.

Clear Plotter

Clears all currently displayed plots. Resets most plot parameters to their defaults. The color of displayed data resets to red, but line styles and plot styles previously selected will be retained.

Cursor Position

Whenever the cursor is within the Dish Plotter frame, the cursor positions will be continuously read back. The coordinates shown are the X and Y position as defined by the X and Y axes' units.

Dismiss Plotter

Dismisses or closes the Dish Plotter frame. The frame will be automatically re-opened if an action occurs which produces a plottable result, i.e., if a spectrum is selected, a new Dish Plotter frame will be initialized to display the selection.

Plot Axes Menu

This menu allows selection of the units for the abcissa. The first selection determines whether the units will be absolute ("Abs") or relative ("Rel"). The second selection determines the actual abcissa unit ("GHz, MHz, KHz, Hz, km/s, m/s, or pix"). The third selection determines, for velocity units, whether the radio or optical definition should be used.

Header toggle

This determines whether the header information is displayed. If the header button is activated, the scan information listing the source, scan number, Time of observation, RA/DEC, AZ/EL, Trx, Tcal, Tsys, $ \Delta$$ \nu$ and Frequency are displayed. If the button is disabled, it only displays the source name.

Overlay Toggle

The overlays menu is a simple toggle switch between On and Off. In the Off mode, all new plot results or selections will clear the screen before plotting the new result. The only exceptions to this are the Baseline operation in Show mode, which will overplot the calculated baseline over the spectrum, and multi-channel data which will plot as many channels as found on the same screen. In the On mode, all new selections and results will be overplotted; the axes will not be scaled!

Reverse Color Toggle

This reverses the basic foreground and background colors for better displays under different illumination conditions (e.g. projection favors the reversed color display).

Chalk Board Toggle

This enables the third mouse button to be used as a piece of chalk on the current display for any annotations, doodles, etc.

X-Axis Autoscale Toggle

This is set by default but it can be toggled off to 'keep' the current x-axis range.

Unzoom

Allows incremental unzooms from any zooms performed. Zooming is done with the middle mouse button; unzooms may also be done with CNTRL-Middle Mouse Button.

G Fit Button

This brings up the Gaussian Fitting interface frame, and initializes the current display for fitting gaussians. NOTE: This button must be depressed each time a gaussian fit is desired.

LineID
This tool browses an aips++ table version of the Poynter and Pickett molecular line catalog, and plots any lines found that fall within the frequency range of the displayed plot. Line positions are plotted with short tick marks along the top of the plot while the corresponding molecular name tag is plotted vertically along the bottom.

6.6 The Dish Command Line Interface

The DISH CLI is detailed in the User Reference Manual.

6.7 Recipes

6.7.1 Recipe 1: Change syntax to suit

Finally, any syntax can be roughly approximated by a combination of Glish and the existing tools in DISH. You can always set a new variable to equal an existing function. In this way you can modify and create your own command line reduction language. An example of changing the syntax to approximate a UniPops command would be:

UniPops: hanning xx             #this will hanning smooth a spectrum and
                                #redisplay it

- hanning:=function() { d.smooth('HANNING');}
                                #create a new function that automatically does
                                #a hanning smooth; CLI defaults to operate on
                                #the currently displayed spectrum.
- hanning()                     #this now does the equivalent of the above
                                #UniPops command

6.7.2 Recipe 3: Add a function to DISH (or fun with extensibility)

Plugins are another standard means of adding functionality to DISH. Any file called mydish_*.gp that lives in the current directory will be picked up when DISH is started. An example plugin file with a simple squaring function is shown here:

pragma include once;
note('mydish_example included');
mydish_example := [=];
mydish_example.attach := function (ref public) {
        #new function
#####User adds functions here
        public.square := function(somevalue) {
                wider public;
                print 'the square of ',somevalue,' is: ',somevalue*somevalue;
		return T;
        }
# other functions go here
#       public.otherfunction := function(input1,input2,etc) {
#              some code goes here to do something
#              return; # can return a value too if you like
#       }
#       public.etc...
#
#####End user edit
return T;
}

If you then look at the functions contained in your DISH tool, d, it will now have a 'square' function.

Running this operation within dish looks like the following:

- field_names(d)
done dismiss gui rm ops addop normalcursor busycursor savestate restorestate debug open showscript message plotter gaufit myfunction
- d.square(4)
the square of 4 is: 16
T

6.8 sditerator

See the Reference Manual for information on the Sditerator tool. and the is_sditerator function.


6.9 SDFITS

SDFITS is a convention for the use FITS binary tables to store single dish data. This appendix will eventually be turned into a full fledged note. At the present time, it is simply a summary of the various rules regarding the interpretation of keywords and columns which, taken together, constute the Single Dish FITS convention.

A FITS binary table is also a SDFITS binary table if it follows these rules.

6.9.1 EXTNAME keyword

EXTNAME = 'SINGLE DISH'
The EXTNAME keyword must have a value of ``SINGLE DISH''. A table having this value for EXTNAME is assumed to be fully compliant with this convention.

6.9.2 Virtual columns

Most keywords should be thought of as a column of the same name which has a constant value for all rows in the table.

There are a few exceptions to this rule. FITS keywords which are required to describe the structure of the table are not virtual columns. These include NAXIS, NAXIS1, NAXIS2, BITPIX, XTENSION,
[0]EXTNAME, EXTVER, EXTLEVEL, PCOUNT, GOUNT, TFIELDS, TFORM, TTYPE, TUNIT, TNULL, and TDISP. The TDIMnnn keyword is the only table description keyword which may be a column as described elsewhere in this appendix.

DATAMAX and DATAMIN are special keywords. When used as keywords it is most likely that the writer of that table meant them to reflect the range of all of the data found in that table and not to be used on a row-by-row sense. If the writer feels a need to supply row-by-row values for these two keywords, they should explicitly make them true columns.

When creating a table, a column may be made virtual if it's value can be represented as a single keyword (if it is constant over all rows) and if that constant value is NOT an IEEE special value (it has a standard ASCII representation) and the name of the column is 8 character or less.

If a column exists which has the same name as a keyword, the column values should be assumed to take precedence (writers should attempt to ensure that this confusing situation does not happen).

6.9.3 The DATA column and the DATA axes

The DATA column containsthe primary data array. It is required. Each row of this column contains an n-dimensional array of data. The axis descriptions are handled in a similar way to FITS images.

The TDIMnnn convention
This is how the shape of the DATA array should be specified.
TDIMnnn = '(n1,n2,n3,n4...)'
This convention may be used with other columns which do NOT use the same axis description (these will be site specific columns and readers are free to ignore these columns).
Axis description
This description applies to any column which has
TMATXnnn = T. It is assumed that TMATXnnn = T for the DATA column even when not present. The use of TMATXnnn = F for the DATA column is an error.

Axes descriptor keywords/columns include (not all need be present for each axis):

CTYPEn
The type of physical coordinate on axis n.
CRVALn
The value of the physical coordinate on axis n at the reference pixel.
CRPIXn
The array location of the reference pixel along axis n. CRPIX may be a fractional pixel and/or be outside of the limits of the array. This descriptor is optional for degenerate axes.
CDELTn
The increment in physical coordinates along axis n. This descriptor is optional for degenerate axes.
CROTAn
The axis rotation
CUNITn
The unit of coordinate values along this axis.
Note that these are the original FITS axes description keywords. It is anticipated that when an agreement is reached on the WCS convention that the appropriate keywords specified in that convention will be used to describe the axes here (e.g. CROTA is deprecated in favor of a more general mechanism).

Due to the virtual column convention, the following conflict may arrise:

TTYPE10 = 'CDELT4'
TFORM1  = '1E'
TUNIT10 = 'radian'
CUNIT4  = 'degree'
Writers should avoid this conflict. Readers encountering such a conflict should report this as an error in the FITS table. However, readers may also choose to proceed by arbitrarily resolving the conflict so that some attempt may be made within the anaysis package to deal with this error. It is recommended that the CUNITxxx specification take precedence over any TUNITxxx specification. In any case, this conflict and the readers resolution of the conflict (if at all) should be reported to the user.

The other standard FITS Image axis keywords may be used here. This will include all of the WCS convention keywords when they become accepted as part of the FITS standard.

Defined axis types (CTYPEnnn values) for this convention (others are allowed but their values may be ignored by readers) are:

frequency-like
An 8 character string consisting of the 4 character axis type plus 4 characters describing the reference frame. An axis having this type is required.
axis types
  • 'FREQ' - frequency (Hz)
  • 'VELO' - velocity (m/s) (radio convention, unless overridden by use of the VELDEF SHARED keyword)
  • 'FELO' - regularly gridded in frequency but expressed as velocity in the optical convention (m/s)
reference frames
  • '-LSR' : Local Standard of Rest
  • '-HEL' : heliocentric (barycentric)
  • '-OBS' : the frame of rest of the observer/telescope (topocentric)
  • 'LSRK' : LSR as a kinematical definition
  • '-GEO' : Geocentric
  • 'REST' : rest frequency
  • '-GAL' : Galactocentric
Longitude-like
'RA','GLON','ELON' plus an optional WCS projection code (degrees). This axis is required.
Latitude-like
'DEC','GLAT,'ELAT' plus an optional WCS projection code (degrees). This axis is required.
'TIME'
The time since DATE-OBS (seconds) If the TIMESYS keyword is present, that keyword defines the time system for this table, including this column, otherwise UTC is assumed. This axis is optional. If not present, a value of 0.0 should be assumed. This axis will often be absent if DATE-OBS contains a time as well as a date.
'STOKES'
The Stokes parameter of the data.
  • 1, 2, 3, 4 $ \Rightarrow$ I,Q,U,V
  • -1, - 2, - 3, - 4 $ \Rightarrow$ RR, LL, RL, LR
  • -5, - 6, - 7, - 8 $ \Rightarrow$ XX, YY, XY, YX
This axis is optional. If not present, a value of 1 (Stokes I) should be assumed.
'BEAM'
Beam ID. This axis is optional. If not present, a value of 1 should be assumed.
'RECEIVER'
receiver ID. This axis is optional. If not present, a value of 1 should be assumed.

6.9.4 CORE keywords and columns

These must be provided in all SDFITS tables. They are essential and common to all observations and telescopes. All single dish FITS readers and writers must acknowledge (write and properly interpret) all CORE keywords.

OBJECT
A string value giving an object name.
TELESCOP
A string value giving the telescope name.
BANDWID
The total bandwidth of the backend in units of Hertz.
DATE-OBS
A string giving the observation date and optionally the time at the start using the new FITS y2k convention. The TIMESYS keyword may be used to indicate the time system. UTC is assumed if TIMESYS is absent.
EXPOSURE
The effective integration time in seconds.
TSYS
The system temperature in Kelvin.

6.9.5 SHARED keywords and columns

These have agreeded definitions and interpretions however their presense is obtional. These are largely common to all observations and telescopes but not essential. These may be ignored by a single dish FITS reader.
OBSERVER
A string giving the observer's name.
OBSID
A string describing the observation.
PROJID
A string describing the project.
SCAN
A scan ID number. Typically this is an identification number given to a chunk of data when the data is taken. Not all telescopes provide a scan ID number.
OBSMODE
The type of data and observing mode (8 characters total). The type (LINE, CONT, PULS, etc) + the mode (PSSW, FQSW, BMSQ, PLSQ, LDSW, TLPW, etc). These rules do NOT define these observing modes. Writers are strongly encouraged to use the FITS comments to document these modes.
MOLECULE
A string used as a line identifier (with TRANSITI).
TRANSITI
A string used as a line identifier (with MOLECULE.)
TEMPSCAL
A string describing the scaling applied to reach the output intensity scale (``TB'',``TA'',``TA*'',``TR'',``TR*'').
FRONTEND
A string giving the name of the front end device.
BACKEND
A string giving the name of the back end device.
TCAL
The calibration temp (K).
THOT
The hot load temp (K).
TCOLD
The cold load temp (K).
TRX
The receiver temp (K).
FREQRES
The frequency resolution in Hz. This may differ from the channel spacing.
TIMESYS
The time system which applies to all time columns and keywords (see the y2k FITS DATE agreement).
VELDEF
The velocity definition and frame (8 characters). The first 4 characters describe the velicity definition. Possible definitions include:
RADI
radio
OPTI
optical
RELA
relativistic
The second 4 characters describe the reference frame (e.g. ``-LSR'', ``-HEL'', ``-OBS''). If the frequency-like axis gives a frame, then the frame in VELDEF only applies to any velocities given as columns or keywords (virtual columns).
VFRAME
The radial velocity of the reference frame wrt the observer. Vframe - Vtelescope.
RVSYS
The radial velocity, Vsource - Vtelescope.
OBSFREQ
The observed frequency (Hz) at the reference pixel of the frequency-like axis.
IMAGFREQ
The image sideband freq (Hz) corresp. to OBSFREQ.
LST
The LST (seconds) at the start of scan.
AZIMUTH
The azimuth at TIME (deg) (if the TIME axis is non-degenerate, then this is the azimuth at the TIME of the first pixel on the TIME axis.
ELEVATIO
The elevation at TIME (deg) (same caveat as for AZIMUTH)
TAU
The opacity at OBSFREQ.
TAUIMAGE
The opacity at IMAGFREQ.
TAUZENIT
The opacity per unit air mass.
HUMIDITY
The relative humidity (fraction, 0..1).
TAMBIENT
The ambient temp (K).
PRESSURE
The atmospheric pressure (mm Hg).
DEWPOINT
The dew point (K).
WINDSPEE
The wind speed (m/s).
WINDDIRE
The wind direction (deg. west of north).
BEAMEFF
The main-beam efficiency.
APEREFF
The antenna aperture efficiency.
ETAL
The rear spillover and scattering efficiency.
ETAFSS
The forward spillover and scattering efficiency.
ANTGAIN
K per Jy.
BMAJ
The major main-beam FWHM (deg).
BMIN
The minor main-beam FWHM (deg).
BPA
The beam position angle (degrees east of north).
SITELONG
The site longitude (deg).
SITELAT
The site latitude (deg).
SITEELEV
The site elevation (m).
RESTFREQ
The rest frequency (Hz).

6.9.6 Other columns

Any additional columns not explicitly mentioned here can be added to an SDFITS table, although, obviously, most readers will not be able to propertly interpret those columns.

6.9.7 Multiple SDFITS tables in a single file

Any number of FITS binary tables can be attached to the same FITS table. This convention doesn't have anything to say about how the tables in such a file might be related. This strategy, attaching multiple SDFITS binary tables to a single FITS file, is one possible strategy for storing variable length DATA. DATA with similar sizes could be stored in separate tables, minimizing the amount of padding required in any one table without resorting to using the table heap convention to store variable length arrays. SDFITS readers should be capable of appending the contents of several SDFITS tables to a single result.


next up previous contents
Next: Copyright Up: Volume 2 - Generic Processing Previous: 5. GBT Continuum Single dish Imaging   Contents