DVO Examples

User Interface

The interface has an interaction similar to tcsh. The arrows allow editing of previous commands. You can also use emacs-like commands such as cntl-a to reach the beginning of the line and cntl-e to reach the end. There is command and file completion: if you type part of a command (as the first thing on a line) and then type tab, it will fill in as much as possible, until the word is not unique. Typing tab twice at that point will list the possible endings. For any but the first word on a line, the same thing will happen for the files in the current directory. It is also possible to type just a fraction of a command, as long as it is unique. An ambiguous command will list the possible alternatives. For example:
 dvo: c
 ambiguous command: c ( catalog cgrid clear create cursor )
The shell is an interpretive programming language. Variables are set as follows:
 dvo: $fred = 10
Any expression within curly brackets {} is assumed to be an arithmetical expression and is evaluated before the line is executed. For example:
 echo {$fred*dcos(45)}
would give the response 7.07107. There are math functions cos, sin, and tan, which operate on radian expressions, and also dcos, dsin, dtan, which operate on degree expressions. There are also the equivalent inverse functions: eg., asin and dasin return radians and degrees, respectively. The help section on Math defines all of the available math functions.

Miscellaneous Commands

 !                         -- system call
 ?                         -- list commands 
 ??                        -- list variables 
 echo                      -- type this line 
 exec                      -- system call
 exit                      -- exit program 
 help                      -- get help on a function 
 output                    -- redirect output to file
 quit                      -- exit program 
 scan                      -- scan line from keyboard or file to variable 
 wait                      -- wait until return is typed
 which                     -- show command 
Most of these are self-explanatory. The command ?? prints the system variables. The help command will provide help on a single command or, without any arguments, will list all available help files (this includes general help not associated with a specific command).

Shell Programing

 break                     -- escape from function 
 for                       -- loops 
 if                        -- logical cases 
 input                     -- read command lines from a file 
 macro                     -- deal with the macros 

There are several options for programming in status. First, a file which contains a series of commands can be executed with input (filename). It is also possible to define macros which will behave much like regular commands. A macro is defined by typing macro name or macro create name followed by the commands. Arguments to the macro are assigned to the variables $1 .. $N and the number of arguments is given by $0. Macros may be defined in input files, and in fact when status is started, it loads the file ~/.statusrc which may contain default macros. Simple loops and if statements can be performed, and are quite useful for complex macros.

'If' statements are similar in syntax to C if statements. Math expresions in the if statement must be contained in curly braces, as elsewhere. Variables with string values may use the logical == operator to test if two strings are the same. 'For' loops are quite simplistic. The form is:

 for var first last delta

The value of $var will start at the value first and increment by delta after each loop. The loop will stop after $var is greater than stop. The value delta is optional, with 1 assumed. The value of $var may be changed during the loop, and if set beyong the value of last will end the loop early.

Vector Plotting

 box                       -- draw a box on the plot
 clear                     -- erase plot
 create                    -- create a new vector
 cursor                    -- get coords from cursor
 grid                      -- plot cartesian grid
 hist                      -- create histogram from a vector
 labels                    -- define labels for plot
 limits                    -- define plot limits
 plot                      -- plot a pair of vectors
 print                     -- write vectors to file
 ps                        -- define labels for plot
 set                       -- vector math
 style                     -- set the style for graph plots
 vectors                   -- list vectors
 zplot                     -- plot scaled points 

In addition to scalar variables, status can manipulate and display 1-D vector variables. Many of the commands which extract data from the photometry database place the data in vectors as well as plotting them. A vector can also be created based on a number sequence with the command create name Nelements start delta. The resulting vector has $Nelements$ entries, starting at a value of $start$ and running until $start + delta*Nelements$. If $delta$ is 0.0, all elements will have the value of $start$. A histogram of a vector may be made with the command hist, which creates a new vector containing the histogram of the first vector. The data range and bin size of the histogram are defined in same way as with create. This makes it easy to create the index vector that goes with a histogram vector:

 hist y Ny 1 100 0.1
 create dx 1 100 0.1

The above will create a histogram of y in Ny and the index in dx. Plotting this with plot dx Ny will show the histogram.

Vector math is performed with a command of the form set new = (expression). The expression is some math function employing vectors and scalars. A complete listing of the math operators available in set can be found in the help for set.

Once vectors are defined, they may be plotted. A pair of vectors can be plotted against each other if they have the same number of entries. The plotting is performed on the graphics window, Kapa. There are actually several graphics windows available to status, any of which may be used to plot at any time. Some of the more complex operations default to either graphics window 0 or 1, depending on the context. Except for those functions with a pre-defined window, all plotting functions apply to the current graphics window unless an option -n N is given to specify a different window. The plotting style is determined by the command style which can set the line width, the line type (solid, dashed, dotted, etc), the point type (box, cross, etc), the point size, the color, and whether a pair of vectors is plotted as a sequence of points, a set of connected lines, or a histogram. Some functions which make plots use their own styles, as discussed below. The function limits lets the user set the range of the plot axes, or check the current setting. The command plot will plot a pair of vectors on the current graphics window using the current plotting style for that window. The command zplot will plot a pair of vectors with the point size scaled by a third vector, with maximum and minimum point sizes representing specified values. The cursor command goes the other way: this command puts the Kapa window in cursor mode and waits for input from Kapa. The user can then type any alphanumeric key on the graphics windows and will be told both the pointer location (in the graphics coordinates) and will have the coordinates stored in status variables. For example, by typing ``1'' in the sky display window, the RA and DEC of the pointer are stored in the variables $R1 and $D1. This command can be used to let the user define locations or regions of interest on the Kapa window. (Future addition: button, which does the same with the mouse buttons).

Database Functions

 gcat                        -- get catalog at location
 gimages                     -- get images at location
 gstar                       -- get star statistics
 extract                     -- extract average vectors from catalogs
 mextract                    -- extract measurement vectors from catalogs
 imstats                    -- plot image statistics
 imextract                   -- extract image vectors from database
 lcat                        -- list catalogs in display region
 cmatch                      -- match two catalogs

There are a variety of other commands which directly refer to the photometry database. Some of these functions extract data of various types from the database, others perform more complex plotting operations. The commands listed above are those which simply extract data from the database. The first three list information relevant to a specific RA, DEC location on the sky: gcat (RA) (DEC) lists the catalog at the specified location and places the name in the variable $CATNAME, gimages (RA) (DEC) lists all images which overlap the specified location, gstars (RA) (DEC) (RADIUS) lists data about the stars within a specified radius of the specified location (all numbers above are given in decimal degrees). Similarly, lcat lists the catalogs in the region. Imstats lists statistics about each image

The next three commands extract a specific piece of information from the photometry database and places it in a vector. First, extract will extract average values for each star and place it in a vector. Next, mextract will extract measurement values for each star and place it in a vector: as a result a single star may have multiple entries in the measurement vectors. Finally, imextract will extract image statistics into vectors (not yet implemented).

 catalog                    -- plot catalog stars
 cgrid                      -- plot sky coordinate grid
 cplot                      -- plot vectors in sky coordinates
 czplot                     -- plot scaled vectors in sky coordinates
 images                     -- plot image boxes
 imdense                    -- image density plot
 lcurve                     -- plot lightcurve for a star
 pcat                       -- plot catalog boundaries
 region                     -- define sky region for plot
 resid                      -- plot residuals
 simage                     -- plot stars in an image

There are two types of database plotting functions: those that display or refer to the spatial charateristics of the data and those that refer to other types of charatersitics, such as the time domain. The graphics window 0 is reserved for all plots of objects on the sky. The command region defines the current sky coordinates for plots in graphic window 0. The command pcat plots the outline of all photometry database files which are within the currently defined region (and by default, only those with data). images plots the outline of the images in the image database, while imdense shows the number of images at a location by randomly spacing dots within the boundary of the images. The command cgrid draws a grid in celestial coordinates on the for the current region.

The most complex, but also one of the most useful command is catalog, which plots the positions of stars in the photometry database (and others) on the sky. There are many options to this command. One set allows the user to plot stars from the photometry database (the default), from the HST GSC, or from an ASCII text file with RA, DEC, and Mag in specified columns. If the ASCII file has a fixed number of bytes per line, the data can be more quickly loaded. The size of the points may be scaled by the star magnitude, by the number of observations of the star, or by the number of missing datapoints for the star. In addition, points may be plotted only if they land in specified magnitude ranges, or with specified numbers of measurements, or missed measurements. Also, objects may be plotted only if they have a specified Average.code, so that only asteroids or only perfect stars may be plotted. The plotted vectors may be saved, if desired, and the source catalog epoch may be specified as different from J2000 (only valid for ASCII data).

Several other commands relate to non-spatial charateristics of images and stars. lcurve will plot a light curve for all stars within some radius of a point. resid plots the photometry residuals for a particular region file.

Some Examples

\begin{figure} %\psfig{file=fullsky.ps,width=16cm} \caption{\label{allsky} \small Map of the entire sky, and images added to database. } \end{figure}

Fig.~\ref{allsky} shows a map of the entire sky, and the location of the images currently in the database. This picture was made with the following commands: (output is not shown)

 dvo: region 0 0 90 gls
 dvo: cgrid
 dvo: style -lw 2 -c red 
 dvo: images
 dvo: ps

In this example, on the graphics window, the image boxes are shown in red. The user now has the possiblitiy of using the cursor command to narrow in on a specific region, and so forth. \begin{figure} %\psfig{file=polar.ps,width=16cm} \caption{\label{polar} \small Map of the sky in polar project, and images added to database. } \end{figure}

Fig.~\ref{allsky} shows a map of the entire sky, and the location of the images currently in the database from a polar project. This picture was made with the following commands: (output is not shown)

 dvo: region 0 0 90 zea
 dvo: cgrid
 dvo: style -lw 2 -c red 
 dvo: images
 dvo: ps

In this example, on the graphics window, the image boxes are shown in red. The user now has the possiblitiy of using the cursor command to narrow in on a specific region, and so forth. \begin{figure} %\psfig{file=catalog.ps,width=9cm} \caption{\label{catalog} \small Comparison between HST GSC and photometry database astrometry. } \end{figure}

Fig.~\ref{catalog} shows an example comparison of the photometry database star positions and the HST Guide Star Catalog star positions. The crosses are all objects in the photometry database, while the boxes are only the stars identified as USNO stars. The circles are the stars from the HST GSC. The size of both points is a function of brightness. This plot was made with the following commands (starting from the previous image):

 dvo: cursor  (typed 1 on region of interest)
 1 137.097858 22.698305
 q 137.097858 22.698305
 dvo: region $R1 $D1 0.2 TAN
 dvo: cgrid
 dvo: box
 dvo: style -pt 0 
 dvo: gcat $R1 $D1 
   0 n2230/1951.cpt *
 dvo: style -pt 2; cat -all -m 12 18
 dvo: style -pt 1; cat -all -m 12 18 -ID $USNO
 dvo: style -pt 7; cat -all -m 12 18 -g