CHAPTER 2 Getting Started

Main Menu (i.e., File, Options, Tools, PCMDI Tools, Help)

There are five static pull down options in VCDAT's main menu. In addition, the user can add their own customized pull down menus to VCDAT's main menu.

• File: Under the "File" option, the user can choose to: open data files located on their local disk, select searches for specific data types (e.g., netCDF, XML, etc.), send plots directly to local printers, save the state of the system for total recall, read Python or VCS script files into the system, and exit out of VCDAT.
• Options: The "Options" option sets information referring to a selected or defined variable, or sets the state of the graphical user interface. For example, the "Select Predefined Region" selects a region of the globe (e.g., "Africa", "Asia", etc.). Thus, every selected or defined variable will automatically be set to the predefined region. Note: This works only if the x-axis equals longitude and the y-axis equals latitude.
• Dimension aliases for longitude, latitude, time, and level can also be set under the "Options" pull down menu. For example, the user can set "X", "lon" and "X_Long" as aliases for longitude. So when VCDAT sees these dimension names it will interpret them as longitude axes.
• If the user modifies the VCDAT GUI and wants to save the settings for the next session, then select "Save GUI State..." located under this option.
• Tools (IDLE): The "Tools" option displays additional GUIs that allow the user to: create new script files for edit, edit old script files, issue keystroke commands, add new user menu options to the "Main Menu" (note, the new menu option will be placed between the PCMDITools and Help menu options), and view recorded script commands.
• When invoked, the "Command Line Window..." option is really executing the Python Integrated DeveLopment Environment (IDLE) developed by Guido van Rossum, who is also the developer of Python. The Python Shell Window gives the user access into Python's interactive mode. This Python Shell Window has been slightly modified to allow the user to register keystroke script commands and GUI button commands simultaneously and seamlessly in VCDAT.
• When the "Python Shell Window" (i.e., called "VCDAT's Command Line Window" in VCDAT) appears, the user should read the information describing hooks into VCS. For additional online information about the "Python Shell Window", select the "F1" button while running it.
• The script editors are also part of IDLE. IDLE can also be invoked outside of VCDAT. That is, at the prompt type, "idle". For more information on IDLE, visit: http://www.python.org/idle.
• To add more menus to "Main Menu", the user must select the "Add User New Menu..." menu item. See help balloons to assist with the addition of new menus. Once the new menu has been added, the user must select "Save GUI State..." located under "Main Menu" -> "Options" to retain the new menu for later VCDAT sessions.
• PCMDITools: The "PCMDITools" option contains the start of time tools and statistical functions deemed necessary (by the PCMDI climate researchers) to do common fundamental analysis. For the "Time Tools", the data must have a time dimension in order to work. Under "Options", see "Dimension Aliases for" specifying additional time axis names.
• For in-depth information on these tools and their functionalities, see the CDAT Utilities Reference Guide.
• Help: The "Help" option allows the user to turn the help balloons off or on, display CDAT related web sites by means of the user's client web browser, and displays information about VCDAT to the user (for example, version number and place of execution).

Select Variable

The main purpose of this section is to select a variable for analysis and/or display. There are five main components here: the "Directory"; the "Database", this component take the place of the "Directory" when it is invoked; the "File"; the "Datasets", this component takes the place of the "File" when the "Database" is invoked, and the Variable.

• Directory: The "Directory" component of "Select Variable" contains: a home directory icon, which if selected will take the user directly to their $HOME directory; a file selection browser icon that will display a file selection GUI for selecting the directory and a file; an input window for specifying the directory by means of a keypad; a bookmark icon for saving favorite working directories; and a cycle icon for cycling through the list of favorite working directories.
• Note: the "Directory" input window will turn salmon pink when the user enters text. The textual information requesting a new directory will not be excepted until the <Return> key is depressed.
• Database: The "Database" component is displayed only when the user has changed the choice button from "Directory" to "Database". If the user has not installed "esg" on their system and the environment variable "CDMSROOT" has not been set, then the "Database" option will not appear. If the "Database" option is selected, then a popup will appear allowing the user to log onto a remote database. After connecting to a remote database the "File" component will change to display "Datasets".
• File: The "File" component displays all the files located in the directory. To view only a specific file type, select under "Main Menu" -> "File" -> "Open File Types" the desired file specifications. If an OPeNDAP enabled version of CDAT has been installed, then, a URL of a dataset on an OPeNDAP server may be entered.
• Datasets: The "Datasets" components displays all the datasets located in the database. This is only visible if the "Database" component is visible.
• Variable: The "Variable" component displays the variables, axes, and bounds in a file or dataset. To alter the viewing of "Variable" (i.e., don't display or display axes, bounds and weights), toggle "Main Menu" -> "Options" -> "View axes in Variable List" and "Main Menu" -> "Options" -> "View bounds and weights in Variable List".

Graphics (i.e., Plot, Boxfill, VCS Canvas 1, Options, Define)

There are only four components to "Graphics", but because of screen real estate and design considerations, the "Define" button was added to this row. Therefore, "Graphics" consist of five components: the "Plot" button, the "Graphics Method" (e.g., "Boxfill", "Isofill", etc.) choice button, the "VCS Canvas" choice button, the graphics "Options" menu, and the "Define" button.

• Plot: After the "Variable" has been selected, the user can select the "Plot" button to display the variable. The user can also select the "Plot" button to display a "Define Variable", which is described later in this document.
• Graphics Method: By default, the "Boxfill" graphics method will be displayed. To choose a different graphics method, the user must depress and hold the choice menu button. Then move the pointer over the desired graphics method (e.g., "Isofill"). At this point, the user can reselect the "Plot" button to redisplay the variable.
• VCS Canvas: VCDAT allows up to four VCS Canvases. More can be added if necessary. The user can select which canvas to display the variable information. Note, if the user wishes to display the information on the "Background Canvas", then rendering is done in memory and no canvas drawing is visible to the user, but the user can still send the unseen plot to the printer or to a graphics output file. See "Main Menu" -> "Save Plot As" and "Main Menu" -> "Print Plot On" for sections on file output and printer selections. Also, view the VCS document for details on the PCMDI_GRAPHICS directory and the HARD_COPY file.
• Options: The "Options" menu displays additional GUIs for controlling the outcome of the plot. These plot options are: "Continents Types", "Page Orientation", "Overlay", "Isoline Labels", "Annotation", "Set VCS Canvas Geometry", "Set Min Max Values", "Set Graphics Method Attributes", Number of Plots on VCS Canvas", "Set Plot Map Projection", "Editors", "Animate", "Clear VCS Canvas", and "Close VCS Canvas".
• Define: After the "Variable" has been selected, the user can select the "Define" button to transfer the variable from a file or remote database to memory. The selected variable will be visible in the "Defined Variables" below.
• The "Define" button is also used to save a defined variable under a new name and can be used to overwrite an existing defined variable. That is, in the "Defined Variable List" window, select a defined variable, and then select the "Define" button. A pop up will appear with simple instructions for both actions.

Dimensions Panel

The "Dimension Panel" is blank if no variable or defined variable is selected. It is located just under the "Graphics" section. It can currently display up to six dimensions. But more display dimensions can be easily added if necessary. The displayed dimensions are separated by lines and contain four components: the "Dimension Menu"; the "Dimension Selection"; the "Dimension Sliders"; and the "Dimension Functions".

• Dimension Menu: The "Dimension Menu" allows the user to change the view of the "Dimension Selection" from axes defined values to index values. For example, from longitude or latitude coordinate values to index values. In the case of the time dimension, the user can change the time coordinate values, i.e., "units since base time" (See Handling Time.) to either raw time values or index values.
• The user can get the weights of an axis' by selecting the "Get Axis Weight Values" menu item. The weights variable will be stored in memory and displayed in the "Defined Variable" window below.
• By selecting the "Replace Axis Values", the user can replace the axis node values with a defined variable, provided that the axes and the defined variable are the same size. The new axis must be visible in the "Defined Variables" window.
• To reorder the dimensions, depress and hold the "Re-Order Dimensions". Then select the desired dimension to trade places. The "Dimensions Panel" will restructure itself accordingly.
• Dimension Selection: The "Dimension Selection" allows the user to select a single node value, a subset of node values, and a selection of every nth node value. When selecting the arrow button to the right will display the list axes node values. The highlighted value indicates the selected node(s). The input text window representation the dimension as "first: last by stride".
• The user can enter the node value(s) in the input text window. When entering values, the input window becomes salmon pink. To except the changes, the user must depress the <Return> key. To select every nth node value, the user must enter the stride number after the "by" and then depress the <Return> key.
• To select a single node, the user can either enter the value in the input text window or select the arrow button to the right and then select the desired node value. To select a sub-range, the user can either enter the values in the input text window or select the arrow button to the right and then select the second desired node value.
• Dimension Slider: The slider bars are yet another way to select the first and last values of a sub-range or single node point. The top slider changes the first selected node value and the bottom slider changes the last selected node value. The values below the second slider bar represent the first selected node value and the last selected node value.
• Dimension Functions: Each dimension can have a function operate on it exclusively. Select the choice menu button for a detailed description of each function operation. The last two functions "awt" and "gtm" are slightly different. "awt" allows the user to replace the weights before operating the weighted average function. The new weights must be located in the "Defined Variables" window before using this function. The geometrical mean "gtm" is generated by the following function: gtm(x) = exp(mean ( log(x)))).

Defined Variables

The "Defined Variables" section operates on variables that are stored in memory. Variables can be defined in memory by selecting the "Define" button located in the "Graphics" section. Variables can also be defined by operations located in the "Main Menu" section. For example: selecting from "Main Menu" -> "PCMDITools" -> "Statistics" -> "Mean" on a variable would produce "_Statistics_mean_variablename ()" in the "Defined Variables List". Other possible ways to produce a defined variable are: by the use of "Function Icons" and command line operations via VCDAT's "Command Line Window". For example: typing "import MV; a = MV.array((1,2,3))" in the VCDAT "Command Line Window" would produce "a (3)" in the "Defined Variables List".

Note that everything associated with defined variables has the same background color as the "Define" button located in the "Graphics" section.

• Operational Icons: The first column of icons (from top to bottom) allows the user to: edit the variable's attributes, save the variable to a netCDF file, display variable information, move selected defined variables to the trashcan, move all variables to the trashcan, view logged information about the size of variables in memory, and permanently remove or restore defined variables.
• Defined Variables List: The "Defined Variables List" is located to the right of the "Operational Icons" and contains, in alphabetical, the list of all variables stored in memory. As the user selects variables in the list, a record of the order of selection is kept. Among other things, this selection list is important when it becomes necessary to plot or do calculations by means of the "Function Icons".
• Function Icons: The "Function Icons" are located to the right of the "Defined Variables List". There are two modes for calculating defined variables. If the user moves the pointer over the top left icon, a detailed description of how the calculation works in both modes is given.

Variable Information

The "Variable Information" section immediately displays variable or defined variable information to the user. To quickly browser through many variables and examine their content, resize the variable information panel by selecting the small button located to the upper right of the "Variable Information" text. While keeping the button depressed, move the panel to the desired location.

Example 0: The basics

This example runs through some basic operations such as opening, closing, writing to files, and reading data by location or at specified time intervals. The tutorial is presented with a series of questions and answers in the style of a FAQ.

Example 1: Dealing with data from other sources

This example shows (in excruciating detail) how to read in Fortran formatted data, use it within CDAT, and writing to a netCDF file. Some simple averaging operations are carried out on the data. This example also shows how to change/insert metadata for the variable.

Example 2. Using Masks.

This example shows how to generate data masks, applying masks and averaging using area weights.

Using VCDAT

The VCDAT graphical user interface has a "help" button that provides access to all the documentation that a user may require at the click of a button. The interface also has helpful information in pop-up balloons that instruct the user when the cursor is moved over the buttons.

Using "docstrings"

Python also has a powerful feature: most objects in Python, including the modules, classes, and functions, have documentation strings ("docstrings") attached to them. The special attribute name "__doc__" (which has two underscores on each end) is used to access this string supplied by the module author. If you have an object x, try the command

>>> print x.__doc__

Using pydoc to generate documentation

You can also use the pydoc utility. This is a standard facility for extracting documentation from Python installations.

You can generate Python documentation in HTML or text for interactive use.

Interactive use

In the Python interpreter, do "from pydoc import help" to provide online help. Calling help(thing) on a Python object documents the object. Also, typing help() will put the user in a help environment indicated by the prompt changing to

help>

From the shell

At the shell command line outside of Python: Run "pydoc <name>" to show documentation on something. <name> may be the name of a function, module, package, or a dotted reference to a class or function within a module or module in a package. If the argument contains a path segment delimiter (e.g. slash on Unix, backslash on Windows) it is treated as the path to a Python source file. Run "pydoc -k <keyword>" to search for a keyword in the synopsis lines of all available modules.

Starting a browser / server

pydoc -g starts an HTTP server and also pops up a little window for controlling it.

Writing out HTML

Run "pydoc -w <name>" to write out the HTML documentation for a module to a file named "<name>.html".

Using happydoc

A utility named "happydoc" is able to generate documentation for modules written in Python.

Quick Start Guides

The documents cdms_quick_start.pdf and vcs_quick_start.pdf provide a quick look at useful commands in the core CDAT modules; cdms and vcs respectively on a single page that is useful even to the experienced user.

Programming reference guides

The core CDAT modules cdms and vcs are extensively documented in separate documents that can be downloaded from http://cdat.sf.net. The most up-to-date versions of the following guides can be found there.

• cdat.pdf : This document
• cdms.pdf : Climate Data Management System
• vcs.pdf : Visualization and Control System: Python Command Line and Application Programming Interface
• cdat_utilities.pdf : CDAT Utilities Reference Guide
• numpy.pdf : Numerical Python
• vcs_quick_ref.pdf A one page reference to VCS commands.