Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Bulk Processing of data in new DISH Up: NOTE 236 - DISH: User's Manual Previous: The Dish Plotter

Subsections

The Dish Command Line Interface

In the following we document the publically available commands from the main tool level and at the operations, results manager and plotter levels.

The scripter is intended as both a tutorial and a means of constructing batch command scripts. It is invoked from the AIPS++ command line as:

- ds.gui()
F

The Options menu "Write Script commands" must then be selected. Subsequent commands will then be written to the scripter. See other info on scripter. NOTE: The submit button on the scripter will not work since this command executes the script as a shell client which doesn't know about the tool you've created. Instead to run a stored script (default name is aips++.script.g), simply include it (include "aips++.script.g").

dish functions

addop

A means of adding new operations formally to the DISH tool (see Operation template).

mydish.addop(include_file, operation_name);

busy

A developer tool to yield a busy cursor.

mydish.busy(T or F);

dologging

A toggle switch which determines whether commands from the GUI will be logged to the scripter.

mydish.dologging(T or F);

doselect

A toggle switch which determines whether commands operations will operate on the last viewed (the default behavior) or upon the selected item in the results manager. This gives the ability of performing bulk processing on SDIterators. Selecting will also change the GUI state of the Option 'select from rm (for SDITs)'.

mydish.doselect(T or F);

done

Exits and destroys the current Dish tool.

gui

history

Returns a history line. It takes two arguments: 1) a string of the command executed , 2) a record of the inputs to that command. This line can then be appended to the history of an SDRecord or SDIterator.

- mydish.history('dish.ops().smooth.settype',[type='HANNING']);
ok := mydish.ops().smooth.settype(type="HANNING" )

logcommand

Writes a command to the scripter. logcommand uses the same syntax as history but the information is logged to the scripted rather than to the record's history.

message

Writes a command to the DISH GUI message entry.

open

Opens date (MeasurementSet or Flat Table) for use in DISH (it is loaded into the results manager and can be manipulated).

ops

Access all of the operations and their functions (see dish operation functions).

plotter

Access the plotter and its functions (see dish plotter functions).

restorestate

rm

Access the results manager and its functions (see dish results manager functions).

savestate

Saves the state of the GUIs and plotter to a file. The default file is in the home aips++/dishstate directory called default. This may be altered with the statefile function.

statefile

Changes the location that the state of Dish's GUIs and plotter will be saved to. The full pathname is required.

mydish.statefile('mydefaultstate');
mydish.savestate();			# saves to mydefaultstate in the
					# current directory

type

A mandatory function required by the toolmanager. The type of any dish tool is 'dish'.

dish plotter functions - dish.plotter()

destroy_plotter

Dismisses the plotter.

clear_plotter

Clears plotter.

get_data_vector

Retrieves either the x or y data vectors for a viewed SDRecord.

mydish.plotter().get_data_vector('x');
mydish.plotter().get_data_vector('y');

compute_statistics

An internal tool for calculation of the statistics. It can also be used easily by the user. The inputs are the x-vector, y-vector, x-inital, and x-final. For example, to get the statistics on the channels 1-25 on the currently displayed data at the command line.

- myx:=mydish.plotter().get_data_vector('x');
- myy:=mydish.plotter().get_data_vector('y');
- mydish.plotter().compute_statistics(myx,myy,myx[1],myx[25]);
[mean=0.0554615276, stddev=0.104077502, x1=221122.843, x2=270078.864]

redraw

Redraws the screen.

plotrec

Plots an SDRecord to the plotter. The inputs are:

mydish.plotter().plotrec(xvector,yvector,name,object,xlabel,ylabel,overlay=T
	or F,refocus=T or F,startChan,endChan)
For example, to manually plot an SDRecord from the results manager called 
myrec:

- mydish.plotter().plotrec(myrec.data.desc.chan_freq.value,myrec.data.arr,'dumb','Title','my x','my y')
T

plotter_command

Gives the full range of PGPLOT commands within DISH for augmenting plots. Any command can be duplicated (NOTE: only 9 arguments are currently accepted):

- mydish.plotter().plotter_command('sci',5);                          
- mydish.plotter().plotter_command('mtxt','t',2.0,0,0,'Hello Reno!');
- # this will write a light blue message of Hello Reno, 2 characters above
- # the top line of the plotter window.

create

Creates a plotter frame if one doesn't already exist.

Developer tools:

cursor_agent

register_range

clear_entry

data_exists

set_button_state

is_active

not_active

assert_range_cursor

deassert_range_cursor

prod_statistics

set_range_notify

cursorpos

b3cursorcall

compute_statistics

brief_header

full_header

view_sdrec

dish results manager functions - dish.rm()

add

Add an SDRecord to the Results Manager. The syntax is:

mydish.rm().add(name,description,value,type,decorate)
For example, using myrec:
mydish.rm().add('myrec','something I did', myrec, type='SDRECORD');

getstate

Returns the state vector (all of the information on the results manager, the SDIterators/SDRecords that it contains, etc).

setstate

Allows changing the state of the results manager. This command is invoked when a restore state operation is selected from the DISH file menu.

delete

Deletes the item in the results manager based on it's index.

size

Gives the number of items in the results manager.

selectionsize

Gives the number of items currently selected (highlighted) in the results manager.

getselectionnames

Returns the names of the items in the results manager that have been selected (highlighted) in the GUI.

getselectionvalues

Gets the values of all selected items in the Results Manager.

getselectiondescriptions

Gets the descriptions of all selected items in the Results Manager.

getnames

For a specified index value, it returns the name of the item in the results manager:

- mydish.rm().getnames(9)
myrec1

getdescriptions

For a specified index value, it returns the description of the item in the results manager.

setdescription

For a specified index value, it will set the description to a specified string:

mydish.rm().setdescription(9,'my description is now different');

copy

Copies currently viewed to the clipboard.

paste

Pastes from the clipboard into the results manager.

getvalues

For a specified index value, it returns the values of the item in the Results Manager.

select

For a specified index value, it will select (and consequently display) the item in the Results Manager.

selectbyname

Selects the item in the Results Manager by name.

getlastviewed

Returns the SDRecord of the last viewed item in the plotter.

setlastviewed

For a specified index value in the results manager, it will set this as the last viewed item.

gui

Opens the GUI for the Results Manager if it isn't already viewed.

nogui

Specifies whether the GUI for the Results Manager should be viewed.

done

Deletes and closes down the Results Manager Tool (not recommended).

Developer Tools:

wscombobox

dish operation functions - dish.ops()

dish universal operation functions

Most public functions of an operation either set variables or execute obvious actions. Table 1 summarizes the public functions of the available operations.

average function gaussian regrid save select smooth statistics write

setweighting getfn setheight setboxwidth setws cws setboxwidth setstart setof

setalignment setfn setcenter setdecimate - newworkingset setdecimate setstop -

doselection - setwidth setgausswidth - setcriteria setgausswidth - -

dorestshift - fixheight setgridfact - setws settype - -

- - fixcenter settype - - - - -

- - fixwidth - - - - - -

apply

Perform the relevant operation. See Bulk Processing for more details.

done

This closes down access to the operation's functions. Generally this should *not* be done by the user.

getstate

- mydish.ops().average.getstate()
[selection=T, alignment=NONE, restshift=F, weighting=NONE]

average

setweighting

The accepted weighting schemes are: NONE, RMS, and TSYS.

- mydish.ops().average.setweighting("RMS")
T

setalignment

The accepted alignment options are: NONE, VELOCITY, and XAXIS.

- mydish.ops().average.setalignment("VELOCITY")
T

dorestshift

This option is enabled only when the alignment has been set to VELOCITY. This option will shift spectra to match the first in the average.

- mydish.ops().average.dorestshift(T)
T

doselection

This option determines if an active selection (from the select operation) should be used prior to the average.

- mydish.ops().average.doselection(T) 
T

If the GUI is enabled, these functions will also check the relevant button on the average GUI.

An example scripter session looks as follows:

ok := mydish.ops().average.setalignment(alignment="NONE" )
ok := mydish.ops().average.setweighting(weighting="NONE" )
ok := mydish.ops().average.apply()

baseline

settype

The accepted types are: sinusoid and polynomial.

- mydish.ops().baseline.settype("sinusoid")
T

setaction

The accepted types are: show and subtract.

- mydish.ops().baseline.setaction("show")
T

getaction

Retrieves status of the action parameter.

- mydish.ops().baseline.getaction()
show

setunits

The acceptable types are: channels and xaxis.

- mydish.ops().baseline.setunits("channels")
T

setorder

If the type of fit is polynomial, this sets the order.

- mydish.ops().baseline.setorder(3)
T

recalculate

The fit is recalculated if this state is true when apply is done.

- mydish.ops().baseline.recalculate(T)
T

setamplitude

This and the following four functions apply in cases of a sinusoid fit. This sets the amplitude of the sinusoid.

- mydish.ops().baseline.setamplitude(2.)    
T

setperiod

Sets the period of a sinusoid fit.

setx0

Sets the X0 of a sinusoid fit.

setmaxiter

Sets the maximum number of iterations for the fit of a sinusoid.

setcriteria

Sets the convergence criteria for a sinusoid fit.

setrange

getrange

This function retrieves the range for the baseline.

- mydish.ops().baseline.getrange()
[[1:2,]
    85.861813
    119.882504]

The following functions are used mainly internally but are provided as public functions as well: setrangestring, convertunits, polynomial, sinusoidal.

If the GUI is enabled, these functions will also check the relevant button on the average GUI.

An example script follows. It fits a second order polynomial over the specified range, first to see it ("show") and then to apply it ("subtract"):

ok := mydish.ops().baseline.setorder(order=2)
ok := mydish.ops().baseline.setrange(newrange=[-70603.3518, -53031.125] ,
	units="xaxis" ,changeunits=F)
ok := mydish.ops().baseline.setaction(action="show" )
ok := mydish.ops().baseline.setrange(newrange=[119.882504,85.861813] ,
	units="channels" )
ok := mydish.ops().baseline.apply()
ok := mydish.ops().baseline.setaction(action="subtract" )
ok := mydish.ops().baseline.setrange(newrange=[119.882504:85.861813] ,
	units="channels" )
ok := mydish.ops().baseline.apply()

calculator

The calculator functions are all accessible from the command line already so no special interface has been provided within DISH.

function

This operation will perform some function on the data array of the selected SDRecord or SDIterator. The data array is accessed directly through the variable ARR.

getfn

This function retrieves the function which has been set either through the CLI or the GUI.

- mydish.ops().function.getfn()
3*ARR

setfn

This function sets the function to be used. If the GUI is active, this will also be reflected in the GUI entry field.

- mydish.ops().function.setfn("4*ARR")
T

An example scripter session looks as follows:

ok := mydish.ops().function.setfn(fn="3*ARR" )
ok := mydish.ops().function.apply()

gaussfit

This operation allows gaussian fitting of an SDRecord(s).

setheight

Sets the initial guess for the height.

setcenter

Sets the initial guess for the center.

setwidth

Sets the initial guess for the width.

fixheight

Determines whether it will hold the height fixed (T or F).

fixcenter

Determines whether it will hold the center fixed (T or F).

fixwidth

Determines whether it will hold the center fixed (T or F).

ok := mydish.ops().gaussfit.setnumber(numgauss=1)
ok := mydish.ops().gaussfit.setheight(heights="37.149597" ,fixed=F)
ok := mydish.ops().gaussfit.setcenters(centers="8980.08289" ,fixed=F)
ok := mydish.ops().gaussfit.setwidth(widths="18358.5081" ,fixed=F)
ok := mydish.ops().gaussfit.apply()

regrid

This operation allows for more general regridding of data in an SDRecord. It allows all of the options in smooth in addition to a spline interpolation and a Fourier Transform interpolation.

The following are identical to the smooth operation: setboxwidth, setdecimate, setgausswidth.

setgridfact

Sets the Grid Factor for interpolations (Spline or FFT).

settype

Additional types are splineint and ftint.

save

This operation will store results (i.e. SDRecords) to a specified SDIterator or working set. The working set must already exist (create through the File menu, New command).

setws

An example session would look like:

- mydish.ops().save.setws('tempsave') # Note name must be a string
T 
- mydish.ops().save.apply()
T 
- The currently viewed SDRecord has been appended to the selected working set

Object Name Selection
---------------------
- mydish.ops().select.setws('dishparkes')                                   
T 
- mydish.ops().select.setcriteria(critrec=[header=[source\_name='ngc1808']]) 
T
- mydish.ops().select.apply(F)	# Note (F designates that this is not from
				# the GUI
T
Record Selection
----------------
single values,e.g., rows 1,2,4:
- mydish.ops().select.setcriteria(critrec=[row=array([1,1,2,2,4,4],2,3)]);
ranges,e.g., rows 1-4:
- mydish.ops().select.setcriteria(critrec=[row=array([1,4],2,1)]);

Scan Selection
--------------
single values,e.g., scans 2,20:
mydish.ops().select.setcriteria(critrec=[header=[scan_number=array([2,2,20,20],2,2)]]);

ranges,e.g., scans 14-16:
- mydish.ops().select.setcriteria(critrec=[header=[scan_number=array([14,16],2,1)]]);     

Date Selection
--------------
mydish.ops().select.setws('working_set1');
mydish.ops().select.setcriteria(critrec=[header=[date='1997-04-14']]);
mydish.ops().select.apply(F);

UTC Selection - in seconds since date
-------------
mydish.ops().select.setws('dishparkes1');
mydish.ops().select.setcriteria(critrec=[header=[ut=array([310.5],2,1)]]);
mydish.ops().select.apply(F);

Rest Freq. (Hz) Selection
--------------------------
mydish.ops().select.setws('dishparkes1');
mydish.ops().select.setcriteria(critrec=[data=[desc=[restfrequency=array([1.102014e11,1.102015e11],2,1)]]]);
mydish.ops().select.apply(F); # the F designates that it is not from the GUI

- mydish.ops().write.setof('myspectrum')
T

An example script looks as follows:

ok := mydish.ops().write.setof(ofname="myspectrum" )
ok := mydish.ops().write.apply()

Next: Bulk Processing of data in new DISH Up: NOTE 236 - DISH: User's Manual Previous: The Dish Plotter Contents

average	function	gaussian	regrid	save	select	smooth	statistics	write
setweighting	getfn	setheight	setboxwidth	setws	cws	setboxwidth	setstart	setof
setalignment	setfn	setcenter	setdecimate	-	newworkingset	setdecimate	setstop	-
doselection	-	setwidth	setgausswidth	-	setcriteria	setgausswidth	-	-
dorestshift	-	fixheight	setgridfact	-	setws	settype	-	-
-	-	fixcenter	settype	-	-	-	-	-
-	-	fixwidth	-	-	-	-	-	-