### 12 Browsing and selecting from the command line

catview is available for browsing catalogues and selecting subsets from the command line. It provides the same functionality as xcatview7, but is much less easy to use. Indeed it is not really intended for casual, interactive usage. If at all possible I recommend that you use xcatview for casual, interactive browsing of a catalogue. However, if you do not have an X display available then you will have to use catview. It is also useful for running prepared scripts which perform routine, standard, ‘batch’ type operations.

In order to run catview type:

catview

and the following prompt should appear:

ACTION - Action: /’’/ >

Using catview you can create an arbitrary number of selections from the catalogue, each defined by its own criteria. catview has the notion of the ‘current selection’, which is the selection that it is working on currently. Columns chosen for display to the screen or a text file, are listed from the current selection and statistics are computed from the current selection. Similarly when a new selection is created it is extracted from the rows in the current selection. By default the most recent selection is the current one, though you may choose to make any of the selections the current one. If no selections have been made, the current selection is the entire catalogue.

You issue commands to invoke the various functions supported by catview and reply to the prompts that they issue, as appropriate. Type HELP for a list of the commands available. They are as follows.

OPEN
Open a catalogue. You will be prompted for the name of the catalogue.
SHOWCOL
List a summary of all the columns in the catalogue.
DETCOL
List full details of all the columns in the catalogue.
SHOWPAR
List a summary of all the parameters in the catalogue.
DETPAR
List full details of all the parameters in the catalogue.
SHOWTXT
List the textual information associated with the catalogue.
SHOWROWS
Display the number of rows in the current selection.
SETCMP
Enter the list of columns which are to be displayed. The list defines the columns which are listed by commands ‘LIST’ or ‘PREV’. Both columns in the catalogue and new, computed columns may be listed. Items in the list should be separated by a semi-colon (‘;’). New columns have the form:
name{expression}units

where name is the name of the new column, expression is the expression which defines it and units are the units. name and expression are mandatory, but units is optional. See Appendix A for the syntax of expressions.

As an example, to list catalogue columns V, B_V and a computed column B defined by ‘V + B_V’ you would enter:

V;B_V;B{V+B_V}

Occasionally you may need to enter a list of columns and expressions which is longer than a single line. Such long lists can be entered using a continuation line mechanism. This mechanism is described in Section 12.2.

SHOWSEL
List details of all the selections which currently exist.
CHOSEL
Choose one of the existing selections to become the current selection.
SETSEL
Create a new selection. You will be prompted to enter the expression defining the selection (see Appendix A). Occasionally you may need to enter an expression which is longer than a single line. Such long expressions can be entered using a continuation line mechanism. This mechanism is described in Section 12.2.
SHOWRNG
List the columns on which a (fast) range selection can be created; that is, the columns on which the catalogue is sorted. In practice the catalogue is unlikely to be simultaneously sorted on more than one column.
SETRNG
Create a new range selection. Range selections can be created essentially instantaneously, irrespective of the size of the catalogue. However they can only be created on sorted columns. You will be prompted for the name of the required column and the minimum and maximum values to be included in the range. If the column contains a celestial coordinate in a format that CURSA can recognise (see Appendix B) then the minimum and maximum values can optionally be entered as sexagesimal values in hours or degrees. The usual rules for interpreting sexagesimal values in expressions are followed. For example any of the following three values could be entered and all correspond to the same coordinate:
 3:00:00 (hours) +45:00:00 (degrees) 0.78539816 (radians)
SETROW
Set the current row number. You will be prompted to supply the required row number.
LIST
List the next page of output to the display terminal.
PREV
List the previous page of output to the display terminal.
SETSTAT
Enter the list of columns for which statistics are to be computed. The list should comprise column names separated be semi-colons (‘;’). For example, to compute statistics for columns V, B_V and U_B you would enter:
V;B_V;U_B

Occasionally you may need to enter a list of columns which is longer than a single line. Such long lists can be entered using a continuation line mechanism. This mechanism is described in Section 12.2.

SETDECPL
Set the number of decimal places to which the statistics will be displayed; you will be prompted to enter the required number. Note that this option merely controls the number of decimal places to which the statistics are displayed. They are always computed as DOUBLE PRECISION numbers in order to ensure the maximum possible accuracy.
STATS
Compute statistics for the specified columns from the current selection. Optionally the statistics can be saved as a text file. You will be prompted for the required file name; enter ‘none’ if this option is not required. In either case the statistics will be listed on the display terminal.
SCOPEN
Open a new scatter-plot. You will be prompted for the following information.
GRPHDV
The name of the graphics device on which the plot will be drawn. See Section 18.2 and Table 8 for details of the graphics devices available.
TITLE
The title of the plot.
XEXPR
The column or expression to be plotted as the $x$ axis.
YEXPR
The column or expression to be plotted as the $y$ axis.
SCRANGE
Set the axis ranges of a scatter-plot. You will be prompted to indicate whether the plot is to be auto-scaled and also the axis ranges required. Note that the ranges are prompted for (but not used) even if the plot is to be auto-scaled.
SCPLOT
Plot a scatter-plot from the current selection. You will be prompted for the plotting symbol and symbol colour required.
SCSHRNG
Show the range of the current scatter-plot.
SCLOSE
Close the current scatter-plot.
HSOPEN
Open a new histogram. You will be prompted for the following information.
GRPHDV
The name of the graphics device on which the plot will be drawn. See Section 18.2 and Table 8 for details of the graphics devices available.
TITLE
The title of the plot.
XEXPR
The column or expression to be plotted as the $x$ axis.
HSRANGE
Set the $x$ axis range and other details of a histogram. You will be prompted to indicate whether the histogram is to be auto-scaled and also the $x$ axis range required. Note that the range is prompted for (but not used) even if the plot is to be auto-scaled. Other details required are the specification for each histogram bin (the total number of bins or the width of each bin) and whether the histogram is to be normalised.
HSPLOT
Plot a histogram from the current selection. You will be prompted for the line colour required.
HSSHRNG
Show the range of the current histogram.
HSCLOSE
Close the current histogram.
FILE
List the current selection to a text file. You will be prompted for the first and last rows (within the current selection) to be listed and for the output file name. If you enter 0 for the last row number the last row in the selection will be listed (this trick avoids having to find the number of the last row). The columns specified by SETCMP are listed.
SAVECAT
Save the current selection as a catalogue. You will be prompted for the following information.
CATOUT
The name of the new catalogue.
CFLAG
The set of columns to be included in the new catalogue. The possible replies are:
TRUE
include all the columns in the original catalogue,
FALSE
include only the columns currently specified by SETCMP.
TFLAG
Specify whether or not to copy the textual information associated with the original catalogue to the new catalogue. The possible replies are:
TRUE
copy the textual information,
FALSE
do not copy the textual information.
COMM
Enter a line of text to be added as comments to the new catalogue.
SHOWFMT
Show the data type, units and external display format for a column. You will be prompted for the name of the required column.
SETFMT
Set a new external display format and units for a given column. You will be prompted for the name of the column and the new external display format and units. Remember that the external display format must be a valid Fortran 77 format for the data type of the column.
SETCONF
Set a number of screen configuration options. You will be prompted to supply the following options.
SWID
The screen height in characters.
SHT
The screen width in characters.
SEQNO
Specify whether each line listed by LIST or PREV is started with a sequence number. The options are:
TRUE
include a sequence number,
FALSE
do not include a sequence number.
NLIST
The number of lines to be output by a single invocation of LIST or PREV.
ANGRPN
Specify the way in which columns recognised by CURSA as containing angles (see Section 6 and Appendix B) are to be listed. The options are:
SEXAGESIMAL
output as sexagesimal hours or degrees,
RADIANS
ANGRF
Specify whether UNITS attribute of angles is to be reformatted prior to display. The options are:
TRUE
reformat the UNITS attribute,
FALSE
do not reformat the UNITS attribute.
SETFILE
Set a number of configuration options for the output text file. Most of these options define the items which will be included in the text file. You will be prompted to supply the following options.
FPGSZE
The number of lines in each page of the output file.
FWID
The width of each line of the output file in characters.
FSUMM
Specify whether a summary of the catalogue is to be included. The options are:
A
do not include a summary,
F
include a summary.
FCOL
Specify whether details of all the columns are to be included. The options are:
A
do not include any details,
S
include a summary,
F
include full details.
FPAR
Specify whether details of all the parameters are to be included. The options are:
A
do not include any details,
S
include a summary,
F
include full details.
FTXT
Specify whether a copy of the textual information is to be included. The options are:
A
do not include the textual information,
F
include the textual information.
FTABL
Specify whether a table of values is to be included. The options are:
A
do not include the table,
S
include the table, but without any column headings,
F
include the table with column headings.
COLNAME
List the names of all the columns in the catalogue.
HELP
Display a brief list of all the commands available.
EXIT
Terminate catview.

#### 12.1 Running catview from a script

In order to run catview from a script simply type the commands and responses that you would have issued interactively into a text file. They should be typed exactly as you would enter them interactively.

Figure 1 shows an example of a script for catview. It selects quasars with redshift greater than three and brighter than nineteenth magnitude from a catalogue8 and writes selected columns from the subset to a file in a format suitable for passing to subsequent applications (that is, without any annotation). The individual commands are:

OPEN
Open the catalogue, here called ‘qsover’.
SETSEL
Select the objects with redshift greater than three and brighter than nineteenth magnitude.
SETCMP
Specify the columns to be listed: ra, dec, redshift, v.
SETFILE
Set the configuration options for the information to be included in the text file. The options given correspond to including only the specified columns, without any annotation.
FILE
Write the text file. All the rows in the selection are written to file qso.lis.
EXIT
Terminate catview.

 OPEN qsover SETSEL Redshift>3.0 .and. v<19.0 SETCMP ra;dec;redshift;v SETFILE 60 132 A A A A S FILE 1 0 qso.lis EXIT

Figure 1: Example script for catview

To run catview from a script simply use Unix’s input redirection mechanism:

catview < catview_script.lis

where catview_script.lis is the name of the script.

#### 12.2 Continuation lines for long lists of columns and expressions

Occasionally you might need to enter a long list of columns and expressions for display (catview option SETCMP) or a long expression for a selection (catview option SETSEL). In both these cases a continuation line mechanism is available which allows lists and expressions which are longer than a single input line to be entered. This option is only available in catview, not in xcatview. If you need to specify long lists of columns and expressions to be displayed, or a long expression defining a selection, then you must use catview. In practice this restriction is not too onerous because long lines usually arise when expressions are being used to compute a set of new columns, which is often done from the command line anyway.

In order to extend the list of columns and expressions to be displayed across several lines simply append an ‘@’ character to the end of the line to be continued. The prompt:

CMPLIST - Columns to be listed>

will be repeated and the line can be continued. The details are as follows.

• An arbitrary number of continuation lines can be entered.
• A line which does not end in ‘@’ is assumed to be the last.
• The ‘@’ used to indicate continuation lines is quite separate from the ‘;’ used to separate columns and expressions; ending a line in ‘@’ does not allow a ‘;’ to be omitted.
• The list can be split at any point: in the middle of names, expressions etc. (though the input is more easily read by eye if it is split at a natural break point such as the end of a column name).

Though this mechanism allows long lists and expressions to be entered, there are necessarily still limits on the length of the list of columns and expressions for display and on expressions defining selections, because they are represented within catview as Fortran 77 CHARACTER variables. In Version 6.4 of CURSA these limits are:

 List of columns and expressions for display: 1000 characters. Expression defining a selection: 200 characters.
##### 12.2.1 Examples
(1)
This example defines two new columns (ra2000 and dec2000) and sets some existing columns to be displayed.
(2)
This example shows the definition of a single column (ra2000) being split across several lines.
ans{hours};
(3)
This example is a complete catview script for computing and listing two new columns.
open
PLN
setcmp
7Technically xcatview is a ‘front-end’ tcl/tk graphical user interface which manages the dialogue boxes and forwards input from the user to the catview ADAM A-task, which, in turn, manipulates the catalogue. Thus, strictly speaking, you are running the same application in both cases. However, as a user you will not normally be concerned with these details.