Version 1.8 Build 235

News	FAQ
Search	Home

Next: 3. GBT Continuum Single dish Imaging Up: Volume 3 - Telescope Specific Processing Previous: 1. VLA reduction

Subsections

2. GBT Standard Data Reduction Guide

J McMullin, J Braatz, B Garwood

2.1 Introduction

This chapter provides brief guidelines on how to reduce the currently supported observing modes at the GBT.

2.2 Example Session

An example data reduction session is shown to demonstrate the look and feel of data reduction in DISH. We calibrate and average position switched scans.

> . /home/aips++/gbt/aipsinit.sh 		(BASH)
> source /home/aips++/gbt/aipsinit.csh		(T/CSH)
>
> dish
- d.open('stjul13SP')
- d.gms()
Scan     Object   Proctype    SWState   SWtchsig   Procseqn   Procsize
  35         S8      Track    FSWITCH      FSW01          1          1
  36         S8      Track    FSWITCH      FSW12          1          1
  37         S8      Track    FSWITCH      FSW12          1          1
  38         S8      OffOn PSWITCHOFF   TPWCALSP          1          2
  40         S8      OnOff  PSWITCHON   TPWCALSP          1          2
  42         S8      Track       NONE   TPWCALSP          1          1
- d.calib(36)
- d.calib(37)
- avg\_spc:=d.aver([36,37]);
- d.plotscan(avg\_spc)
- d.header()
Proj : standards\_jul13    Src  : S8                 Proc : Track          
Obs  : Richard            RA   : 05:47:21.406       PType: SIMPLE         
Scan : 36                 Dec  : -001.40.19.036     OType: LINE           
Seq  : 1/1                Epoch: J2000              Swtch: FSWITCH        
Date : 2002-07-13         Az   : -112.772           Swsig: FSW12          
Time : 19:31:14.500 UT    El   : 23.733             Ints : 31             

Tsys : 16.58              Trx  : 7.58               Tcal : 1.60           
Tsys : 16.86              Trx  : 8.88               Tcal : 1.64           

BW   : 4.995    (MHz)     Res  : 4.883    (kHz)
Expos: 54.549             Durat: 247.856        
T 
- d.setregion()
Use the left button to set location, right button to exit
region =  [15 180 296 681 810 1009] 
T 
- d.nfit(1)
T 
- d.bshape()
T
- d.fileout('S8\_avgbl')
New file  S8\_avgbl  is created
T 
- d.keep()
globalscan saved to  S8\_avgbl
T

2.3 Data Path

The following lists the most often used utilities. There are many more available functions in dish. Type "help('Refman:dish')" at the command line prompt to redirect your browser to the DISH command line documentation; 'd.info()' will also provide an alphabetical, table of all available DISH functions); typing d.help('function_name') will provide information on the function (d.help('function_name',T) will also automatically drive your web browser to the AIPS++ User Reference Manual entry on this function).

File Access Scan Access Editing Calibration Analysis Display

import getr msplot calib (all operations) plotr

open getc viewer TPcal e.g., aver plotc

filein getscan clip FScal base plotscan

fileout flag SRcal etc

2.4 Data and File Access

2.4.1 File Access

GBT data must be converted from their raw FITS files to an AIPS++ MeasurementSet before being accessed with dish functions. The command to fill raw GBT data is import. Once data have been filled, they can be accessed with the open function. Two additional file access functions, filein and fileout, are used to set the focus for where data is read from and written to.

$\fbox{Hint: The name of the MS should not begin with a numeral nor should it contain a '.'}$

1.

import - Fills an AIPS++ MeasurementSet from raw GBT FITS files and makes the data accessible from dish via the open command.

Example:

d.import(projdir='/home/gbtdata/OHsurvey',outms='oh',startscan=100,stopscan=105)

Parameters:

projdir - The project directory
outms - The name of the MeasurementSet to be created
outmsdir - The directory where outms will be written
startscan - First scan to fill
stopscan - Last scan to fill
backend - Backend to fill (e.g., 'SP' or 'SPECTROMETER')
calflag - Calibrate the data after filling (beta).

2.

open - This function will load an existing MeasurementSet on disk into dish memory, that is, it can be used on datasets which have already been filled using the import function. This places it into the Results Manager, making it globally accessible in the Glish session (it can be manipulated from the command line, etc.). This also performs a filein on the MeasurementSet which indicates that subsequent commands/functions will use this MeasurementSet.

Example:

d.open('ohSP');

Parameters:

file - The full path to the MeasurementSet file on disk
access - The access permission on the MeasurementSet(r=read,w=write)
new - Create a blank(new) MeasurementSet on disk
corrdata - Look at the CORRECTED_DATA column (this will be a copy of the FLOAT_DATA (raw data) initially)
filein - Point to this MeasurementSet for subsequent operations

3.

filein - This function sets the scan group that will be examined and displayed. The files function will indicate the current settings for the selected filein and fileout. This allows the user to select between several open MeasurementSets in memory.

Example:

d.filein('ohSP')

Parameters:

wsname - The name of the MeasurementSet in Glish (NOTE: if there are files with the same name, it will append the name with a numeric designator).

4.

fileout - This function sets the scan group that will be written to. The files function will indicate the current settings for the selected filein and fileout. This allows the user to select between several open MeasurementSets in memory. fileout assumes that the function already exists and has write permission (e.g., you should have already created the file with open).

Example:

d.fileout('avg_spectra')

Parameters:

wsname - The name of the MeasurementSet in Glish (NOTE: if there are files with the same name, it will append the name with a numeric designator).

2.4.2 Scan (Data) Access

Data in the MeasurementSet contains both the uncalibrated (raw or observed data) and the calibrated data. Initially, the calibrated data is simply a copy of the uncalibrated data. As the data is manipulated through the calibration routines (calib, TPcal, FScal, SRcal), the calibrated data becomes distinct.

The SDRecord (single dish record) is the data structure returned by the data access commands. The basic SDRecord has four sub-records which contain basic information on the observation:

data - this contains the basic data (data, flags, weights, restfrequency, etc.)
header - this contains the header information (scan number, project, bandwidth, tsys, etc.)
hist - contains information on functions applied to data
other - contains other non-standard information

See the Getting Results chapter on 'Single Dish Analysis' for a full breakdown of the SDRecord.

Several dish functions operate on a globally accessible SDRecord (spectrum) to help simplify the interface. In general, these functions will operate on the currently displayed spectrum or the contents of this globally accessible record (called globalscan1). Functions which take no arguments will in general access this spectrum and perform the operation on it.

1.

getr - Retrieve uncalibrated data. This function will return a SDRecord (a Glish record with all of the astronomical information (e.g., data, header, history, etc)) of the result. Specifying only the scan and phase will yield an average over all available integrations. The function accesses the FLOAT_DATA column of the MeasurementSet (the raw data) which is never modified.

Example:

- s35_1 := d.getr(35,1,1,1) #retrieve scan 35, phase 1, integration 1,
                            #polarization 1 from the opened MS and
                            #store in variable s35_1
- s35_1 := d.getr(35,1)     #retrieve scan 35, phase 1, average all 
                            #integrations, show all polarizations

Parameters:

scan - Scan number (required)
phase - Scan phase (required)
int - Scan integration (if more than 1). If this is not specified, it will average all integrations together.
pol - Polarization. If not specified, it will return all available polarizations.

2.

getc - Retrieve calibrated data. This function will return a SDRecord (a Glish record with all of the astronomical information (e.g., data, header, history, etc)) with the result. Specifying only the scan will yield an average over all available integrations. The function accesses the CORRECTED_DATA column of the MeasurementSet (the calibrated/corrected data).

Example:

- s35_c1 := d.getc(35,1,1)  #retrieve scan 35, integration 1,
                            #polarization 1 from the opened MS and
                            #store in variable s35_c1
- s35_c1 := d.getr(35)      #retrieve scan 35, average all integrations, 
                            #show all polarizations

Parameters:

scan - Scan number (required)
int - Scan integration (if more than 1). If this is not specified, it will average all integrations together.
pol - Polarization. If not specified, it will return all available polarizations.

3.

getscan - Retrieve an individual row (phase, integration) from a scan.

Example:

- s35_c1 := d.getscan(35,3) #retrieve scan 35, subscan 1

Generally, you need to understand how the data was taken to effectively use getscan.

Parameters:

scannum - Scan number (required)
subscan - Sub scan number (default=1)

$\fbox{Hint: Use d.qscan(scan\_number) to obtain information about a scan}$

2.5 Data Inspection and Display

2.5.1 Flagging

Flagging data is done in two basic modes: 1) command line and 2) GUI. There are two basic command line flagging utilities, clip and flag.

clip is a simple function which will allow you to flag a currently viewed spectrum.

Example:

d.clip(0.4);    #clip all above 0.4
d.clip(0.4,[100:500]);  #clip above 0.4 in the channel range 100-500
d.clip(-0.3,clipdir='low'); #clip below -0.3

Parameters:

cliplevel - Threshold for clipping
channelrange - range to apply clip. Default is whole spectrum.
clipdir - clip direction: 'high' (default) is above and 'low' is below.

flag is a more complete flagging utility allowing versatile flagging of data. Automated flagging based on data statistics is under development for single dish data.

Example:

d.open('stjul13SP');
d.gms();
d.plotc(36)
d.flag(36,channel=100:120)      #flag all subscans, polarizations of scan
                                #36 in the channel range of 100:120
d.plotc(36)                     #you should see the range masked
d.flag(36,flag=F);              #unset all flagging
d.plotc(36)                     #it's back!
d.flag(36,channel=500:550,polarization=1)
d.plotc(36)                     #you should see a gap just in the first
                                #polarization
d.flag(36,flag=F);
d.flag(36,1)                    #flag just the first integration
d.plotc(36)                     #should look okay though it doesn't
                                #include the first integration
d.plotc(36,1)                   #masked
d.plotc(36,2)                   #okay

Parameters:

scan - scan number(s) to flag. If no scan is specified, it will flag all scans in the data according to the other parameters (e.g., all channels within a range for the MeasurementSet can be flagged in this manner).
ints - integration number
polarization - polarization number(s); if none specified, it will flag all polarizations.
channel - channel (range) to flag; if none specified, it will flag all channels.
flag - flag (T) or unflag (F) the data; the default is T.

2.5.1.1 autoflag

autoflag is a utility within AIPS++ which allows automated (based on statistics, etc) flagging of data without direct examination of each flagged row/scan. A few specific examples are provided below. See the

Flag based on statistics

include 'autoflag.g'
af:=autoflag('stjul13SP')       #Specify the MeasurementSet to operate on
af.setfreqmed();		#Use a sliding median filter in frequency
				# default threshold is 5
af.run(plotscr=F);
af.done();			#important to release the MeasurementSet

**Figure 2.1:** Flagged dataset using the following commands: af.setfreqmed() af.run(plotscr=F,reset=T), af.setfreqmed(), af.run(plotscr=F), af.settimemed(), af.run(plotscr=F).
$\begin{figure} \centering\leavevmode \epsfxsize=.45\columnwidth \epsfbox{raw.eps}\hfil \epsfxsize=.45\columnwidth \epsfbox{flagged.eps}\par\end{figure}$

Clip data using autoflag

include 'autoflag.g'
af:=autoflag('stjul13SP')	#Specify the MeasurementSet to operate on

cliprec:=[=]			#set up a record to contain the clipping info
cliprec[1]:=[expr='ABS XX',min=0,max=200]
				#clip the XX correlation above 200 and below 0
af.setselect(clip=cliprec)	#specify the clip record as the selection
af.run(plotscr=F)		#execute (disable intermediate displays)

GUI modes of flagging are also enabled through the viewer and msplot tools.

For the viewer:

- include 'viewer.g'
- dv.gui();

This will bring up two GUIs. The first is for selecting what to display. You select the MeasurementSet and choose the type of display (only 'Raster' is available for MeasurementSets). This will then be displayed in the other display panel.

**Figure 2.2:** Display of the Adjust panel for the viewer with the flagging tab open alongside a viewer display. The data on the right has been flagged as bad. The selection will mark all times for the selected channels and all polarizations and spectral windows (from the Adjust panel selection)
$\begin{figure} \centering\leavevmode \epsfxsize=.45\columnwidth \epsfbox{adjust.eps}\hfil \epsfxsize=.45\columnwidth \epsfbox{viewer.eps}. \end{figure}$

For msplot:

- include 'msplot.g'
- mp := msplot('your\_measurementset\_name');

This brings up a GUI which will allow you to select the type of display ("X vs. Y" or "Display data as image") and optionally select a subset of the data.

2.5.2 Display

1.

plotr - Display the raw (observed data: in the FLOAT_DATA column) on the dish plotter.

arameters:

scan - Scan number (required)
phase - Scan phase (required)
int - Scan integration (if more than 1). If this is not specified, it will average all integrations together.
pol - Polarization. If not specified, it will return all available polarizations.

2.

plotc - Plots the calibrated (CORRECTED_DATA column) on the dish plotter.

Parameters:

scan - Scan number (required)
int - Scan integration (if more than 1). If this is not specified, it will average all integrations together.
pol - Polarization. If not specified, it will return all available polarizations.

3.

plotscan - Plots an SDRecord to the dish plotter (as returned from functions like getr, getc, getscan.

Parameters:

scanrec - A scan record (SDRecord, required)
overlay - Overlay the plot (T=true, F=false,default).

2.5.3 The dish plotter

The plotter is the standard dish display for spectral line data. It is built on the existing AIPS++ pgplotter tool and so has all of the basic PGPLOT functionality. In addition, 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) reversing the color scheme and b) providing a chalkboard draw facility
6.: toggling the X-axis autoscale
7.: unzoom (incrementally unzooms any zooms)
8.: activate the gaussian fit tool
9.: line identification (marks any molecular lines within the frequency ranges of the displayed plot

2.6 Calibration (SP,SPECTROMETER)

Calibration is applied to the data based on information in the STATE table of the MS, in particular, it utilizes the OBSMODE column to determine a procedure type, switching signal, and switching state. In addition, information on the procedure size and procedure sequence number are used.

The function applies a number of corrections:

1.

determine elevation, frequency; solve for opacity,gain correction.

2.

determine units used, solve for appropriate efficiency factor from table.

factor = $\displaystyle {\frac{e^{\tau (1/sin(elev))}}{\eta_x}}$

where $\eta_{x}^{}$ is the efficiency factor determined by the user selected units ( $\eta_{l}^{}$ for TA^*, $\eta_{m}^{}$ b for TMB).

3.

based on procedure, calibrate data. Typically, this entails calibrating "cal on" and "cal off" phases of signal (on source) and reference (off source) observations, where the "cal" is a known noise diode. e.g.,

V_sig( $\displaystyle \nu$ ) = $\displaystyle {\frac{(V_{sig,on}(\nu) w_{sig,on} + V_{sig,off}(\nu) w_{sig,off})}{w_{sig,on} + w_{sig,off}}}$

Similarly for the reference observation, leading the difference spectrum:

T_diff( $\displaystyle \nu$ ) = < T_{sys, ref} > $\displaystyle {\frac{V_{sig}(\nu) - V_{ref}(\nu)}{V_{ref}(\nu)}}$

where, < T_{sys, ref} > is:

< T_{sys, ref}( $\displaystyle \nu$ ) > = < $\displaystyle {\frac{T_{cal}(\nu) V_{ref}(\nu)}{V_{ref,on}(\nu) - V_{ref,off}(\nu)}}$ >

1.

calib - Function will calibrate any known procedure. It determines the procedure sequence number and looks in the MeasurementSet for the other scans in the procedure. It then does the appropriate thing (e.g., if it is a map, it will calibrate all of the scans in the map, if it is a OnOff scan sequence it will calibrate both scans and then perform the (sig-ref)/ref. See the calib function documentation in the User Reference Manual for dish for more details on this.

Parameters:

scan - The scan number or vector of scans
baseline - T or F to designate subtraction of a polynomial
range - The channel range over which to fit for a polynomial
order - The order of the fit for the polynomial
units - The output units: 1) TA*, 2) TMB, 3) Jy (not enabled)

2.

TPcal - Function to calibrate any TPwCAL scans. Unlike calib, it will only calibrate the specified scan(s).

Parameters:

scan - The scan number or vector of scans
baseline - T or F to designate subtraction of a polynomial
range - The channel range over which to fit for a polynomial
order - The order of the fit for the polynomial
units - The output units: 1) TA*, 2) TMB, 3) Jy (not enabled)

3.

FScal - Function to calibrate any FSWITCH scans. Unlike calib, it will only calibrate the specified scan(s).

Parameters:

scan - The scan number or vector of scans
baseline - T or F to designate subtraction of a polynomial
range - The channel range over which to fit for a polynomial
order - The order of the fit for the polynomial
units - The output units: 1) TA*, 2) TMB, 3) Jy (not
flipsr - Flip the sense of Sig of Ref
fold - Fold the data
flipfold - Flip the sense of which is Sig and Ref in the folded data enabled)

4.

SRcal - Function to perform a (SIG-REF)/REF calibration. Unlike the other calibration routines, SRcal uses the CORRECTED_DATA column (remember this is identical to the observed data in FLOAT_DATA if no calibration has been performed); this allows a layered approach to TPwCAL scans which can be noise diode calibrated and then subsequently calibrated with SRcal. SRcal is ideally suited for situations with many SIGs per REF. calib, it will only calibrate the specified scan(s).

Parameters:

scans - The scan number or vector of scans that are on signal
refscans - The scan number or vector of scans that are on reference - These are averaged and then applied to each signal scan
baseline - T or F to designate subtraction of a polynomial
range - The channel range over which to fit for a polynomial
order - The order of the fit for the polynomial
units - The output units: 1) TA*, 2) TMB, 3) Jy (not enabled)

2.7 Analysis

Each of the following operations has a GUI counterpart. We describe only the command line interface.

2.7.1 Averaging

The functionality for averaging is provided in the aver function.

aver - Average a group of scans, subscans.

Example:

- myavg := d.aver([303,305:308])	#average scans 303,305,306,307,308
- myavg := d.aver([159:165],'1/4')      #average every fourth subscan in 
-                                       #scans 159-165

Generally, you need to understand how the data was taken to effectively use getscan.

Parameters:

scanlist - a vector of scan numbers
subscanlist - a vector of subscans. This can also be the string 'odd', 'even', or 'n/m'. 'odd' will average every odd subscan in the specified scans, 'even' will average every even subscan in the specified scans, and 'n/m' will select every nth subscan in a sequence of m (for example ('1/4' will select subscans [1,5,9,..]).
weighting - 'NONE', 'RMS', 'TSYS'
alignment - 'NONE', 'VELOCITY', 'XAXIS'

There is also a means of averaging individual scans using an accumulator. Three functions are relevant: sclear(), accum(), and ave().

Example:

  d.sclear()    # clear the accumulator
  d.getc(35)    # retrieve calibrated scan 35
  d.accum()     # add the scan to the accumulator
  d.getc(36)    # retrieve calibrated scan 36
  d.accum()     # add the scan to the accumulator
  d.ave()       # average scans in the accumulator
  d.show()      # display the result on the plotter

Function sclear() takes no parameters, and clears the accumulator.

Function accum() also takes no parameters, and it adds the current contents of the globalscan1 spectrum into the accumulator.

Function ave() averages the contents of the accumulator, and the average is returned to the globalscan1 spectrum for further processing.

A UNIPOPS-like stack is also available. The stack is simply a vector of scan numbers which are intended to be averaged, or operated on in some other manner. It is possible to use Glish methods to accomplish the formation and manipulation of vector of scan numbers; nevertheless, these stack techniques provide another path for those familiar with the UNIPOPS syntax.

Four functions are used to manipulate the stack: empty(), addstack(), delete() and tellstack().

Example:

  d.empty()                 # clear the stack
  d.addstack(10,50,2)       # add even scans from 10 through 50 to the stack
  d.delete(24)              # remove scan 24
  d.delete(28)              # remove scan 28
  d.tellstack()             # show the contents of the stack
  d.aver(d.tellstack())     # average the scans listed in the stack

Function empty() takes no parameters, and simply clears the stack.

Function addstack(beg,end=beg,inc=1) is used to append new entries to the stack. Parameters:

beg : the first scan numer to add
end : the last scan number to add
inc : the increment

So, addstack(10) appends scan 10 to the stack; addstack(15,18) appends scans 15, 16, 17 and 18 to the stack, and addstack(21,28,3) appends scans 21, 24 and 27 to the stack. If these three commands were executed on an empty stack, the result would be [10, 15, 16, 17, 18, 21, 24, 27].

Function delete(value) removes a given scan from the stack. So to remove scan 16 from the stack constructed above, execute d.delete(16).

Function tellstack() takes no parameters, and is used to list the entries in the stack, and also to pass the stack to other functions in AIPS++. For example, to average the entries in the stack, execute d.aver(d.tellstack()).

2.7.2 Fitting Baselines

Baselines can be removed during the calibration step; this is the most efficient means if the baseline regions are constant and there are many to perform. Additional functions for baselining are also provided in the base function.

base - Perform a polynomial or sinusoidal baseline fit to a scan.

Example:

mybl := d.base(order=2,action='subtract',range='[50:400],[1500:2000]')
                                        # This will perform a 2nd order poly.
                                        # fit to the currently displayed scan.

Generally, you need to understand how the data was taken to effectively use getscan.

Parameters:

scanrec - an SDRecord. It will use the current display if none is specified.
order - the order of the polynomial
range - channel range for computing baseline. NOTE: currently this is specified as a string (e.g., range='[50:100],[800:1000]')
action - 'subtract' (to subtract the baseline) 'show' (to display the fit)
cursor - T (to set the region with a cursor; F is default)
autoplot - T (to automatically plot the results; F is default)

One can also use fit a baseline with the UniPOPS-like functions.

d.nregion(50,100,900,1000)# Provide pairs of numbers as the channel range for the
                          # baseline region
d.setregion()             # This will prompt the user to set the baseline regions
                          # with a cursor
d.nfit(1)                 # Fit a first order polynomial
d.bshape()                # Show the baseline fit superposed on the spectrum
d.baseline()              # Subtract the baseline; this also calls the 
                          # d.rms() function displaying the baseline region stats
d.show()                  # Show the result

2.7.3 Fitting Gaussians

Fitting Gaussians is best done with the GUI interface. Pressing the GFit button on the dish plotter will pull up the Profile Fitter window (if there are multiple polarizations, they need to be fit separately and so should be first displayed with the getr or getc functions or after use of the getpol function).

The appropriate sequence of events is:

1.

Select the number of gaussian components. This provides enumerated buttons which allow you to set and get the properties of each component.

2.

Get an estimate for each component:

Hit the Green "Estimate" button on the bottom of the window. This works best for single strong lines.
Hit the "Inter" button (under Estimates) to allow interactive (cursor) setting of the estimate gaussian parameters. If you select this (recommended), the message window in the lower left of the window will prompt you to "Put cursor at line center and click" followed by "Put cursor at line HWHM and click". After this is done, the flux, pos (center) and width entries are filled with the estimate. A yellow line will also appear showing the estimated gaussian. Each of these parameters can be edited or fixed.
Repeat this for each component. Select each enumerated button to toggle through the components.

3.

Fit the profile. Hit the Green "Fit profile" button to fit all the components.

The Plotter will show the Estimate (yellow), the Fit (green) and the Residual (red). Each of these can be toggled on/off by going to the "Plot" menu in the Profile Fitter window and selecting/deselecting a plot.

The gauss fitting routine can also be used at the command line.

gauss - Fit gaussians to displayed spectrum.

Example:

- d.gauss(2)          
defaultregionmanager (drm) ready for use
Creating (temp)image of shape [1023]
Gauss:  1
Center: 1.42037e+00   Height: 5.44724e+01    Width: 4.20960e-05
Cerr: 3.71902e-07   Herr: 1.30446e+00    Werr: 1.20558e-06
Gauss:  2
Center: 1.42037e+00   Height: 9.25963e+00    Width: 1.71623e-04
Cerr: 4.43034e-06   Herr: 1.10727e+00    Werr: 1.43272e-05
T

Parameters:

ngauss - Number of gaussians to fit.
guess - Estimates of the height, center and width
pol - Polarization to fit

2.7.4 Moments and Statistics

There are several functions for obtaining statistical information on a given spectrum.

1.

stat - Provide statistics on a spectrum.

Example:

- d.stat()				# look at spectrum (full range)
[peak=68.9537735, area=0.00448239934, min=-0.303991884, rms=5.74451895,
scan=35, centroid=1.42037562, vpeak=1.4203805, startint=1.41901819,
stopint=1.42400843] 
- d.stat(range='[700:800]');		# look at line
[peak=68.9537735, area=914.18058, min=0.242817193, rms=16.1565856,
scan=35, centroid=745, vpeak=744, startint=700, stopint=800] 
- d.stat(range='[550:650]')		# look at line free region
[peak=0.180041969, area=-1.33219323, min=-0.202106252, rms=0.0901912276,
scan=35, centroid=0, vpeak=554, startint=550, stopint=650]

Parameters:

scanrec - SDRecord to smooth; default is last viewed
range - Channel range to provide statistics over

2.

rms - Display statistics on a region.

This function will calculate statistics on the regions set via the setregion or nregion commands.

Example:

- d.rms()
Using 1023 for calculating baseline stats.
== Feed  1  ===
RMS   =  3.24550665    Mean =  0.000737983237    Num points =  1023
max   =  48.9361229   min =  -12.9025164
nregion =  [1 1023] 
== Feed  2  ===
RMS   =  3.29074012    Mean =  0.351124813    Num points =  1023
max   =  50.4430733   min =  -14.0051394
nregion =  [1 1023] 
T

3.

stats - Display statistics over a region.

This function will calculate statistics on a spectrum. It will use the global echan and bchan parameters for the region if available; these can also be set within the function.

Example:

- d.stats()
Feed : 1       bchan: 1        rms  : 5.744519       min  : -0.303992   
Npts : 1023    echan: 1023     mean : 0.898234       max  : 68.953773   

Feed : 2       bchan: 1        rms  : 6.180395       min  : -0.329462   
Npts : 1023    echan: 1023     mean : 0.912738       max  : 73.913177   

T

Parameters:

quiet - Suppress write of information to screen
feed - Limit information to a single polarization
bchan - Beginning channel for region
echan - End channel for region

4.

moment - Display statistics over a region.

This function will calculate statistics on a spectrum. It will use the global emoment and bmoment parameters for the region if available; these can be set with the bmoment and emoment functions.

Example:

- d.bmoment(700)
T
- d.emoment(800)
T
- d.moment()     
[peak=68.9537735, area=914.18058, min=0.242817193, rms=16.1565856,
scan=35, centroid=745, vpeak=744, startint=700, stopint=800]

2.7.5 Regridding

smooth - Smooth the resolution of a spectrum

Example:

- smooth_spc:=d.smooth(type='HANNING',decimate=T);
- d.plotscan(smooth_spc)

Parameters:

scanrec - SDRecord to smooth; default is last viewed
type - "HANNING", "BOXCAR", "GAUSSIAN" (default is "HANNING")
width - The boxcar smoothing width in channels.
decimate - decimate when smoothing (default=F)

boxcar, hanning, and chngres are streamlined cases for the smooth function using type BOXCAR, HANNING, or GAUSSIAN respectively, and with decimation=T.

boxcar - Perform a boxcar smooth on a spectrum

Example:

- d.show()
- d.boxcar(5)
- d.show()

Parameters:

smooth_width - The boxcar smoothing width in channels.

hanning - Perform a hanning smooth on a spectrum

Example:

- d.show()
- d.hanning()
- d.show()

chngres - Perform a gaussian smooth on a spectrum

Example:

- d.show()
- d.chngres(5)
- d.show()

Parameters:

smooth_width - The gaussian smoothing width in channels.

2.7.6 Saving Spectra

Saving spectra to into a new or existing output file is done using the fileout, lsoutfile, save, and keep commands. fileout was described in the Section on File access.

save, keep - Save spectrum to output file.

Example:

- d.files()
Current filein is  :  N1SP
Current fileout is :  exampleout
T 
- d.save()	  #save currently viewed spectrum to output file.

Parameters:

lv - An SDrecord. The default is last viewed.
outf - Specify a new output file (this must exist and be writable).

keep does the same thing as save in the default case; it takes no arguments.

lsoutfile - List the scan numbers in the specified output file.

Example:

- d.fileout('exampleout')
New file  exampleout  is created
- d.save()
- d.lsoutfile()
159

2.7.7 Writing Spectra

writetofile - Write ASCII columned data of x and y to a disk file.

Example:

- d.writetofile('final.spc'); #default is to write currently viewed spectrum.

The columns that are written out are: 1) the x-axis in the currently displayed units and 2)-n) the data arrays for each polarization/receptor.

Parameters:

outfile - The output file on disk.
scanrec - Scan record to write (default is currently displayed)

2.7.8 Imaging

Imaging in dish is done with the imager tool in AIPS++. Currently, there is a single function makeim in dish to achieve this.

makeim - Make a spectral line data cube.

Example:

- d.makeim('final.spc'); #default is to write currently viewed

This function selects the appropriate data from the MeasurementSet, regrids the data and constructs the image. The data are converted into the coordinate system of the image and then added to the image using a gridding function (BOX, SF, or PB). It also constructs a coverage image which is simply the gridded weights; this is used to normalize the data for the sampling density - the final output image is the image name with a "_corr" attached (imname_corr).

Parameters:

scan - The starting scan in a mapping procedure.
start - The starting channel along the spectral axis.
stop - The end channel along the spectral axis.
step - The number of channels to average. Default=10
imname - The output image name. Three images will be created:

1.
imname
2.
imname_weight
3.
imname_corr
spwid - Spectral Window ID; this is set automatically but can be over-ridden here.
nx - Number of grid points in x. This is automatically calculated by the program to be (map_extent_x/cellx) + buffer (several points, depends on convolution function). This may be over-ridden here.
ny - Same as nx but for latitude.
cellx - The cell size is automatically set by the frequency and the size of the telescope to be 1/2 * lambda/D. It may be over-ridden here.
celly - The same for y direction of cell. displayed)

2.7.8.1 Moments

The image tool function moments offers traditional moment analysis (weighted sums of profiles) of images. It offers a wide range of moments and a wide range of methods with which to calculate them. The word `moment' is used loosely here. It refers to collapsing an axis (the moment axis) to one pixel and setting the value of that pixel (for all of the other non-collapsed axes) to something computed from the data values along the moment axis. For example, take an RA-DEC-Velocity cube, collapse the velocity axis by computing the mean intensity at each RA-DEC pixel. This function offers many different moments and a variety of interactive and automatic methods to compute them. A quick summay of the available moments:

-1 - the mean value of the spectrum

$\displaystyle {{1\over n} {\sum {I_i}}}$
0 - the integrated value of the spectrum

M₀ = $\displaystyle \sum$ I_i
1 - the intensity weighted coordinate (this is traditionally used to get 'velocity fields')

M₁ = $\displaystyle {{\sum {I_i v_i}} \over {M_0}}$
2 - the intensity weighted dispersion of the coordinate (this is traditionally used to get 'velocity dispersion fields')

$\displaystyle \sqrt{{ {\sum {I_i \left(v_i - M_1\right)^2}} \over {M_0}}}$
3 - the median of I
4 - the median coordinate. Here we treat the spectrum as a probability distribution, generate the cumulative distribution, and then find the coordinate corresponding to the 50% value. This moment is not very robust, but it is useful for quickly generating a velocity field in a way that is not sensitive to noise. However, it will only give sensible results under certain conditions. The generation of the cumulative distribution and the finding of the 50% level really only makes sense if the cumulative distribution is monotonic. This essentially means only selecting pixels which are positive or negative. For this reason, this moment type is only supported with the basic method (see below - i.e. no smoothing, no windowing, no fitting) with a pixel selection range that is either all positive, or all negative
5 - the standard deviation about the mean of the spectrum

$\displaystyle \sqrt{{1\over {\left(n-1\right)}} \sum{\left(I_i - \bar{I}\right)^2 }}$
6 - the root mean square of the spectrum

$\displaystyle \sqrt{{1 \over n} \sum{I_i^2}}$
7 - the absolute mean deviation of the spectrum

$\displaystyle {1 \over n}$ $\displaystyle \sum$ |(I_i- $\displaystyle \bar{I}$ )|
8 - the maximum value of the spectrum
9 - the coordinate of the maximum value of the spectrum
10 - the minimum value of the spectrum
11 - the coordinate of the minimum value of the spectrum

- im:=image('g29im') 		#g29im is the data cube
- im.moments(moments=[-1,0]) 	#get the average and integrated moments
Moment axis type is Frequency


***********************************************************************
You have selected the following methods
The basic method
Created /home/despina2/scratch/jmcmulli/g29im.average
Created /home/despina2/scratch/jmcmulli/g29im.integrated
Begin computation of moments
Finished image::moments
       0.48 real        0.08 user        0.02 system
T 
- im2:=image('g29im_integrated')
- im2.view()
- im.summary();
- r:=drm.box(blc='1 1 1 5', trc='20 20 1 100') # create a region
- #using the channels 5 to 100; the first 2 coordinates are ra, dec,
- #the 3rd is stokes, and the 4th is the channel axis.
- im.moments(moments=0,region=r,outfile='g29im_lowvel') #create the
- #integrated intensity over channels 5-100

You can also use the GUI interface via:

- im:=image('g29im')            #g29im is the data cube
- im.momentsgui();		#use GUI to derive moments

See the User Reference Manual on the moments function for the most details moments and moment methods.

2.7.8.2 Source Fitting

Source fitting is achieved through the imagefitter tool. From the example above:

- imfit:=imagefitter('g29im_integrated')
- #Use the GUI to select a region (double click to derive source characteristics,
- #statistics, residuals, etc. The 'show' button will display the fit value.

2.7.8.3 Image math

Manipulation of images is done with the imagecalc tool. With this you can construct an image from expressions involving other images. For example,

im1 := imagecalc(outfile='x3', pixels='sin(x1) + min(x2) ')

where the image disk files x1 and x2 must pre-exist and the result is the image disk file called x3.

You can also construct a read-only image from expressions involving other images. The output image is never created, it is just evaluated each time you use it.

im2 := imagecalc(pixels='pi() - min(x2) + sqrt(x1)')

where the image disk files x1 and x2 must pre-exist. Note that by simply excluding the output file name (argment outfile) you have created the read-only image.

With the image calc function, you can change the pixel values of an image by replacing them with the result of the expression:

im1 := image('x2')
im2 := im1.calc('abs(x2) / min(x2)')

where the image disk file x2 must pre-exist. Because the scalar expression is evaluated first, the images in the expression can be the same as the image which is being overwritten.

Note that for image file names with special characters in them (like for example), you should (double) escape those characters or put the file name in ouble quotes. E.g.

- im1 := imagecalc(pixels='test\\-im')            # Note double escape
- im2 := imagecalc(pixels='"test-im"')

When using imagecalc, you can use either image disk file names, or an associated image tool name in the expression. For example,

im1 := image('im1')
im2a := imagecalc('im2a', '2*im1')     # Use disk file names
im2b := imagecalc('im2b', '2*$im1')    # Use tool name

For information on image manipulation (concatenation, addition, etc), see the Getting Results on Image Analysis.

2.8 Exiting dish

To exit dish, type 'exit' at the Glish command line. If you have enabled the "Save state when done" option, the state of dish will be preserved for your next session (it will be loaded automatically). You can also manually save the state of dish using the File menu options of the main dish GUI.

$\fbox{Hint: It is usually useful to purge the logger before exiting.}$

$\fbox{ Type dl.purge(n), where n are the number of logger lines to keep}$

2.9 Appendix

2.9.1 Index of commands

  aver	    Average a group of scans,subscans.
  base	    Perform a polynomial baseline fit to a scan.
  baseline  Perform a polynomial baseline fit to spectrum in globalscan1
  bdrop     Set value for dropping beginning channels of a spectrum in display
  boxcar    Perform a boxcar smoothing
  bshape    Show the baseline fit of order nfit to globalscan1
  calib     Apply calibration to a scan (GBT only currently).
  clearrm   Clear all variables from results manager, etc.
  clip      Clip/Edit data (set flags)
  done      Exits and destroys the current Dish tool.
  edrop     Set value for dropping end channels of a spectrum in display
  filein    Sets the scan group that will be manipulated.
  fileout   Sets the scan group that can be written to.
  files     Prints the currently set values for filein/out.
  find      Do a grep on a string to find glish variables.
  galactic  Provide the coordinates in the Galactic reference frame.
  gauss     Fit gaussian profiles.
  getc      Retrieve calibrated data (from the CORRECTED\_DATA column)
  getr      Retrieve raw data (from the FLOAT\_DATA column)
  getscan   Retrieve a scan (SDRecord) from a scan group.
  getvf     Return the velocity and frequency for a specified channel.
  getvfarray Return the velocities and frequences for the currently viewed 
            spectrum.
  gms       Print MeasurementSet summary to screen.
  gui       Toggles mapping of DISH main gui (results manager).
  hanning   Perform a hanning smooth
  header    Print formatted header information to the command line window
  help      Provide simple help on dish functions
  history   Add a string or vector of strings to the history of a current SDRecord
  imcal     Calibrate an imaging/mapping procedure
  import    Import GBT data into an AIPS++ MeasurementSet
  keep      Saves the current globalscan1 SDRecord to the designated fileout.
  listscans List the scan numbers from the active scan group.
  logcommand Writes command to scripter.
  lsoutfile Lists scans in the fileout scangroup
  makeim    Make an image from scans in a MeasurementSet.
  message   Writes a command to the DISH GUI message entry.
  mscal     Calibrate a MeasurementSet.
  mult      Scales (multiplies) a scan by a value.
  nfit      Set the order of the polynomial for baseline subtraction.
  nogui     Unmaps frame to DISH main GUI.
  nregion   Set the channel ranges for baseline subtraction.
  open      Load a scan group from disk into DISH and perform a fil ein on it.
  page      Clears the DISH plotter display.
  peak      Obtain the peak amplitude, half-width and center in the displayed 
            spectrum
  plotc     Plot calibrated data (from the CORRECTED\_DATA column)
  plotr     Plot raw data (from the FLOAT\_DATA column)
  plotscan  Plot an SDRecord.
  plotxy    Plot two vectors in the DISH plotter.
  qscan     Query characteristics of scan.
  reference See TPcal
  restore   Retrieve the contents of the uni Record from disk.
  restorestate Restore the state of DISH's GUIs.
  rmadd     Add an SDRecord to the results manager.
  rms       Display statistics on baseline regions.
  save      Save an SDRecord to file.
  savestate Save the current state of DISH.
  saxis     Set the units of the plotters displayed x axis
  scale     Multiply the array in an SDRecord by a value.
  scanadd   Add scan1 and scan2.
  scanbias  Adds a bias level to a scan.
  scandiv   Divide scan 1 by scan 2.
  scanmult  Multiply scan 1 by scan 2.
  scanscale Scale a scan by a value.
  scansrr   Performs a signal-reference/reference.
  scansub   Subtract scan2 from scan1.
  select    Select a subset of a scangroup.
  setregion Set the channel range for use in baseline subtraction
  show      Display the globalscan1 SDRecord
  show1     Display one polarization of the globalscan1 SDRecord
  signal    See TPcal
  smooth    Smooth (hanning, boxcar or gaussian) an SDRecord.
  stat      Generate statistics over a line region.
  statefile Changes file for state saving.
  stats     Generate statistics over a region.
  store     Store the contents of the uni Record on disk.
  summary   Print out a more detailed summary of scans from a scan group.
  upr       Print the current value of the specified variable in the uni-record.
  utable    Print channel and data columns to command window
  writetofile Write X,Y axes to an ascii file on disk.