Mini Guide for Basic Commands in the XXX Program

Sébastien Masson

Albert Fisher

Françoise Pinsard

Steve Navarro

svn Id of xml source file : $Id: mini_notice.xml 144 2006-07-21 14:32:11Z pinsard $

Revision History
Revision 0.0 May 29, 2000
French release by Sébastien Masson
Revision 0.1 July, 2002
Translation by Albert Fisher
Revision 0.2 July 20, 2006
HTML to XML/Docbook migration by Françoise Pinsard

Table of Contents

1. Introduction and assumptions
2. Before this
3. Install the files init.pro and initgrid.pro
3.1. Modification or creation of the initgrid.pro script
4. Starting the SAXO package and an explanation of the XXX widget functions
4.1. Launching XXX
4.2. An explanation of the different widgets
5. Concrete examples of XXX in practice
5.1. First plots
5.2. Work with more than one file
5.3. Mouse actions in the graphics window on a horizontal plot
5.4. Create multiple plots on the same sheet and make them interact
6. How to quit when it crashes

1. Introduction and assumptions

This micro guide is unfortunately not a user's guide for all the scripts that have been written for IDL (version 5.2 or higher required). The goal is simply to clarify a few points on the use of the xxx.pro program.

For further help on the furnished scripts, here are several possibilities:

  • execute in IDL the command

    idl> xhelp, 'script_name'

  • consult the IDL online help for scripts whose source is unavailable

  • subscribe to the mailing list for updates and user questions/responses

    to subscribe, send a mail to: majordomo@lmd.jussieu.fr with no subject, containing the message: subscribe forum-idl e-mail address

  • consult the archives of this mail list: http://www.lmd.jussieu.fr/archives/form-idl/last/mail1.html

  • consult in desperation the feeble web pages we have started to write (while waiting for something better) http://www.ipsl.jussieu.fr/~smlod/

  • wait until we write a full user's manual!

The XXX widget is a layer on top of the scripts in the SAXO package (themselves layered on top of IDL). It is designed to permit the visualization and rapid exploration of data, offering a maximum in options, while not necessarily all those offered by the package and by IDL.

Based on the use of files in the NetCDF format, it can easily work with other file formats. For this, all that is necessary is to write an IDL function capable of extracting a matrix from a file as a function of the following parameters: the variable name, two dates, an experiment name, and a domain.

Developed to visualize the output of the OPA model, the SAXO package was conceived to work on C grids. To use it on grids where the T, U, and V points are the same, one must nevertheless declare the parameters of the grid that correspond to the U and V points. Careful, for this type of discretization, the calculation scripts of type div.pro and curl.pro are wrong.

The averaging routines are not adapted to warped grids, they sum following the i, j, and k indices, weighting each point by scale factors and the land-sea mask. Slices and Hovmoellers do not work in the diagonal, but are always done following i, j, or k. When a domain is given to one of the scripts, an average over the domain in the directions perpendicular to that displayed is automatically made before display.

Before continuing on to the practical part of this guide, the installation and use of the SAXO package, I'd like to thank Guillaume Roullet, who also participated in the writing of the scripts in the package (notably the drawing of vectors on warped grids).

2. Before this

In this document, we supposed that you followed Get SAXO recommandations.

3. Install the files init.pro and initgrid.pro

This version of the SAXO package depends a certain number of common variables that are primarily environmental parameters (working paths, color management, Postscript formatting) and the parameters of the grid on which you are working (longitude, latitude, depth, land-sea mask, scale factors, position of the zoom in relation to the original grid).

These two types of parameters are kept separately:

  • environmental parameters are defined at the very beginning of the IDL session, and are in principle never changed. They are initialized by the init.pro script.

  • Those that belong to the grid are reinitialized every time the grid is changed. They can therefore be called at any time during a session. These parameters are initialized by the initgrid.pro scripts, and are specific to each particular grid.

    For example: initorca.pro for the ORCA 2° grid, initorca05.pro for the ORCA 0.5° grid, or initorcapac.pro for the ORCA grid zoomed on the Pacific.

To begin, one must therefore copy packagedir/INIT/init.pro into homedir, and create in homedir a script of the type initgrid.pro.

3.1. Modification or creation of the initgrid.pro script

In the packagedir/INIT directory you will find a certain number of scripts associated with the latest grids on which I've worked. If you are also working on one of these grids, for example ORCA, copy the file packagedir/INIT/initorca.pro to your homedir. If not, copy it nevertheless to use as a model. In the file initgrid.pro, adjust the zoom parameters (if it has not already been done).

Careful: unlike in previous versions of the SAXO package, all the zoom parameters must be defined. If you do not know them in advance, define their values to be -1.

In the rest of the script, define iodir as iodir, and verify the name of the mask file, if one exists.

4. Starting the SAXO package and an explanation of the XXX widget functions

4.1. Launching XXX

The first command to type is

idl> @init

Afterwards, to work directly with XXX, type:


idl> xxx

To work without the XXX interface, initialize a grid


idl> @initgrid

A window will open with 2 lines to complete.

Figure 1. Window xxx 1

Window xxx 1
1

datafile
2

initfile


These lines must contain the address of a file. The name can be typed directly in the window provided, or selected with the help of the browse button. The first line must contain the name of the data file, the second the name of the initgrid.pro script which will permit the reading and processing of the grid associated with the data file.

Once these two lines have been completed, click on let's go. Two other windows will then open, giving you the parameters for reading the grid and the file (these parameters are read in the initgrid.pro script). Click twice on OK.

4.2. An explanation of the different widgets

Now the XXX window will open.

Figure 2. Window xxx 2

Window xxx 2
1

Page layout
2

Calendar
3

Domain
4

Specify


It's configuration will change depending on whether you are in portrait or in landscape, but here are the different parts available for your use.

4.2.1. The menu bar made up of 3 submenus

4.2.1.1. File submenu

  • Open: to open a second file. Same procedure as during the launching of XXX. The new file can be on a different grid, with different variables, with a different time base.

  • New XXX: to open a second XXX window identical to the first.

  • Close: to close the XXX window.

4.2.1.2. Save As submenu

  • Postscript: to save in Postscript format

  • Animations: to create an animation from the XXX window. Careful, the creation of an animation is only possible if none of the plots have a time axis, and if the plots are all on the same time base (calendar). On the other hand, animations of horizontal and vertical plots, with different color palettes (for those not on an X-terminal), are possible.

  • Image: to save a gif of the XXX graphics window.

  • Script: to save the command history that has created the plot. For example if I save the commands in xxx_figure.pro, I can then launch a new IDL session and type:

    idl> @init
idl> xxx_figure

    and I'll obtain the saved figure.

    idl> xxx_figure,/post

    or

    idl> @ps

    will then create a Postscript file of the figure.

  • Prompt: lists in the IDL window the command history that created the last plot. Useful primarily for debugging...

4.2.1.3. Flag options submenu

  • OK To show/hide the OK button in the upper left corner.

  • Portrait/Landscape: changes the configuration of the plot.

  • Overlay: to plot contours of a different field on top the one represented as color-filled contours. It is necessary to relaunch the entire plot to make this work!

  • Vecteur: to plot a vector field on top of contours. Only works on horizontal plots (plt.pro). As for Overlay, a relaunch of the entire plot is necessary.

  • Longitude / x index: switches longitude labelling of the plot subdomain from degrees to indices following i.

  • Latitude / y index: switches latitude labelling of the plot subdomain from degrees to indices following j.

4.2.2. What type of plot and where?

  • OK Show/hide the OK button in the upper left. When present, a click is required to make a new plot appear. Otherwise each action creates a new plot.

  • Plot type list: allows specification of the type of plot desired.

    Note

    If the type plt is selected, the selection of plot type is made by mouse. Cf Section 5.3, “Mouse actions in the graphics window on a horizontal plot”

  • Layout configuration: specify the number of columns and rows for plots on the sheet of paper. There's no code behind the undo command! The clear button erases all plots.

  • List of open files: you can choose the file to work on.

  • Command window: this window permits simple operations on the fields:

    for example:

    toto - 10*field + 36

    Note

    In the default case, the name given to a field is of no importance.

4.2.3. Calendar

The calendar is made up of two droplists, which allow specification of two dates, the beginning and end of a time series, or the period over which to average before plotting.

4.2.4. Domain specification

A series of widgets that allow specification of the min/max limits of the domain in longitude/x-index, latitude/y-index, and depth in levels or meters. For depth, one can specify in levels for a horizontal plot, and in meters for a vertical plot.

4.2.5. Plot details

You can specify the min, max, and contour interval by filling out the provided boxes! For the color palette, you can either specify the name or go search for one among the palettes available.

The "keywords" window allows specification of all desired keywords. These keywords can be those of plt.pro, pltt.pro, pltz.pro, plt1d.pro, or those of contour, plot, or all other programs that are used. Cf Section 5.1, “First plots”

5. Concrete examples of XXX in practice

5.1. First plots

One single file, one single plot per page

Click on OK.

Test the various basic functions: change the dates, the zoom, the field...

Specify the min, max, and contour interval in the provided boxes.

Add some keywords in the "keywords:" box, for example:

/nocontour, /carte

or the keywords for a northern hortographic polar projection:

/nocontour, map=[90,0,0], /horto

Test the various possibilities in the Save As menu.

Note

the creation of animations has a tendency to saturate the video memory of X-terminals, crashing the entire program...

Test the various possibilities in the Flag options menu.

Caution

Careful, a selected option remains selected until it is reclicked.

5.2. Work with more than one file

Open some other files and go between them by selecting them from the file list... Note that the different widgets (calendar, domain, ...) follow the different file characteristics.

5.3. Mouse actions in the graphics window on a horizontal plot

Select a domain and select the horizontal plot (plt), vertical plot (pltz), or the hovmoeller plot (pltt):

The domain we'd like to select for the plot is determined by one of its diagonals, defined therefore by two points. The first point is defined when the mouse button is pushed, then the mouse is moved, and the second point is defined as the mouse button is released (click-drag). The domains are thus defined by a long click (LC). To determine which type of plot should be made of selection, use:

If the plot selector is on plt

the left mouse button to create horizontal plots (plt)

the middle mouse button to create vertical plots (pltz)

the right mouse button to create common hovmoellers for xt and yt cuts (pltt)

In summary: LCL--->plt

LCM--->pltz

LCR--->pltt

If the plot selector is on something other than plt

the indicated plot type is made.

5.4. Create multiple plots on the same sheet and make them interact

Select the number of columns and rows for the page.

Create a first plot. It will appear in the first frame.

To create a plot in another frame double-click in the frame with the middle button (DCM). A black dotted frame will surround the designated frame, the “target” frame. A black frame will surround the first plot. This is the “reference” frame, in other words the one that all the XXX widgets refer to. Change for example the date and create a new plot. With a left button double-click in the first frame, all the widgets change and refer again to the first plot. A double-click with the right button in the second frame will erase the plot.

In summary: DCL--->“reference” frame

DCM--->“target” frame

DCR--->erase the frame

Here's a series of commands to show how this works.

  1. Select a 3-D field and create 6 frames for the sheet of paper.

  2. Create a horizontal plot in Frame 1

  3. DCM in frame 2, LCL on the plot in frame 1, to create a horizontal zoom in frame 2.

    DCM in frame 3, LCM on the plot in frame 1, to create a vertical cut in frame 3.

    DCM in frame 4, LCR on the plot in frame 1, to create a hovmoeller in frame 4.

To redo the hovmoeller with the keyword

/nocontour

  1. DCL in frame 4 which now becomes the reference and target frame.

  2. Add the keyword

    /nocontour

  3. click OK, and the plot is redone.

in frame 5, let's create the same plot as in frame 2 except with different dates

  1. DCL on frame 2

  2. DCM on frame 5

  3. change the date

  4. click on OK , and voilà, the new plot.

6. How to quit when it crashes

  1. in the IDL window, type

    idl> retall

  2. DCR to erase the problem frame

  3. press the clear button

  4. change the orientation of the plot

  5. quit XXX cleanly using quit from the File menu

Note

Always avoid if at all possible closing and killing the XXX window, but rather select quit from the File menu. XXX uses a large number of pointers, and wantonly killing the window will leave a large number of unused variables in memory, which could in the end overflow. To clean up this memory:

idl> ptr_free, ptr_valid()