source: trunk/SRC/Documentation/xmldoc/wiki/MiniNotice @ 351

= Mini Guide for Basic Commands in the XXX Program =
[[PageOutline]]
  
    
    
    
     
  


== Launching XXX ==


There is several ways to launch XXX which we will detail in the next sections:
  {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span></code></strong>
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>/separate</code></em></code></strong>
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>restore = 'file.dat'</code></em></code></strong>
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>'file.nc'</code></em></code></strong>
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>'file.nc'</code></em>, <em class="parameter"><code>keywd1 = 
</code></em>, <em class="parameter"><code>keywd2 = 
</code></em></code></strong>
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>'file.nc'</code></em>, <em class="parameter"><code>'initgrid'</code></em></code></strong>
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>'file.nc'</code></em>, <em class="parameter"><code>'initgrid'</code></em>, <em class="parameter"><code>keywd1 = 
</code></em>, <em class="parameter"><code>keywd2 = 
</code></em></code></strong>
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>'file.nc'</code></em>, <em class="parameter"><code>'initgrid'</code></em>, <em class="parameter"><code>'arg1, arg2, 
'</code></em></code></strong>
  </pre>
}}}


=== idl&gt; xxx ===
  
    A window will open with 3 parts to consider.

Window xxx 1








[[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0101.png)]] 



Data file name


Grid initialization method


Grid initialization parameters






  

==== Data file name ====
  
    The name of the data file. It can be typed directly in the window provided, or selected with the help of the browse button.
  

==== Grid initialization method ====
  
    For visualising grilled data, you need to [wiki:FirstSteps define the grid] on which are located the data. By default, "automatic grid construction with initncdf.pro" is checked. This means that the grid will be defined by using the informations contained in the data file (through the IDL prodecure {{{initncdf}}}) without needing any other auxiliary file. If you checked "grid construction with other IDL batch or procedure", this means that you don't want to use the default {{{initncdf}}} procedure to define the grid and you will provide your own IDL procedure or the so-called IDL batch file (a file which is called by using @, see IDL documentation).
  

==== Grid initialization parameters ====
  
    This third part allows you to specify the name, the argument and the keywords of the routine you want to use to initialize the grid.
By default the name of the procedure is {{{initncdf}}}, its argument will be automatically defined so you cannot change them. If you If you checked "grid construction with other IDL batch or procedure", you have to select the name of the IDL procedure or batch file and its suitable arguments and keywords. Note that if you select an IDL batch file you cannot give any parameter or keyword.
    
      Window xxx 1
      
  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0102.png)]]
  
      
    
  
  
    Once these two lines have been completed, click on let's go.
  
  For example, we choose the IDL batch file "tst_initlev". Compare the result with "automatic grid construction with initncdf.pro" checked. Cf [#Launching XXX]
  

  
      Oceania at 125 meters of depth with proper grid initialization


  [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0103.png)]]

      
  




=== idl&gt; xxx, /separate ===

This is the same as the simple idl&gt; xxx except that once the xxx window open, you will have 2 separate windows (command and plotting window) instead of one.



=== idl&gt; xxx, restore = 'file.dat' ===

In that case xxx window will open directly in the same state as it was when the file "file.dat" was created. see +++++++



=== idl&gt; xxx, 'file.nc' ===

In this case, the xxx window directly open the data file 'file.nc' and build the grid automatically with the IDL procedure {{{initncdf}}}. For example:
  {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>'Levitus98_1m_01_12_Temperature_Pot_1x1.nc'</code></em></code></strong>
  </pre>
}}}



=== idl&gt; xxx, 'file.nc', keywd1 = 
, keywd2 = 
 ===

In this case, the xxx window directly open the data file 'file.nc', build the grid automatically with the IDL procedure {{{initncdf}}} and use the keywords keywd1 = 
, keywd2 = 
 in the call of {{{initncdf}}}. For example:
  {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>'Levitus98_1m_01_12_Temperature_Pot_1x1.nc'</code></em>, <em class="parameter"><code>useasmask = 'votemper'</code></em>, <em class="parameter"><code>missing_value = 31.0720</code></em></code></strong>
  </pre>
}}}



=== idl&gt; xxx, 'file.nc', 'initgrid' ===

In this case, the xxx window directly open the data file 'file.nc' and build the grid directly with the IDL procedure or batch file {{{initgrid}}}
  {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>'Levitus98_1m_01_12_Temperature_Pot_ORCA2.nc'</code></em>, <em class="parameter"><code>'tst_initorca2'</code></em></code></strong>
  </pre>
}}}



=== idl&gt; xxx, 'file.nc', 'initgrid', keywd1 = 
, keywd2 = 
 ===

In this case, the xxx window directly open the data file 'file.nc', build the grid directly with the IDL procedure {{{initgrid}}} and use the keywords keywd1 = 
, keywd2 = 
 in the call of {{{initgrid}}}.



=== idl&gt; xxx, 'file.nc', 'initgrid', 'arg1, arg2, 
' ===

In this case, the xxx window directly open the data file 'file.nc', build the grid directly with the IDL procedure {{{initgrid}}} and use the string 'arg1, arg2, 
' to specify the input arguments in the call of {{{initgrid}}}.





== Description of XXX window ==




Window xxx 2















[[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0201.png)]] 



Plot type


Menu


OK


Page layout


Variables list


Files list


Command text


Calendar


Domdef


Spefications








=== Plot type list ===
Allows specification of the type of plot desired.

    
      Different plot types available

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0202.png)]]
  
      
    



If the type plt is selected, the selection of plot type
is made by mouse. Cf [#Launching XXX]



=== The menu bar made up of 3 sub-menus ===
==== File sub-menu ====

    
      The File menu

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0203.png)]]
  
      
    



* #xA;* #xA;* #xA;


==== Save As sub-menu ====

    
      The Save As menu

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0204.png)]]
  
      
    



* #xA;* #xA;* #xA;* #xA;* #xA;* #xA;


==== Flag options sub-menu ====

    
      The Flag Option menu

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0205.png)]]
  
      
    



* #xA;* #xA;* #xA;* #xA;* #xA;

Careful, a selected option remains selected until it is re-clicked.



=== OK button ===
Click on this OK button is required to make a new plot appear


=== Page Layout ===
Specify the number of columns and rows for plots on the sheet of paper.

    
      Number of Column

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0206.png)]]
  
      
    


    
      Example: For 2 columns and 2 rows

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0206a.png)]]
  
      
    



=== List of variables ===
You can choose the variable to work on.

    
      Example of different Variables available

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0207.png)]]
  
      
    



=== List of open files ===
You can choose the file to work on.

    
      Example of list of open files

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0208.png)]]
  
      
    



=== Command text ===

To specify in the widget part number 7 the computation you want to do on the data
In all cases bellow, the name given to a field (a, b, c, 
) is of no importance.

==== Linear calculation ====

If you want to make basic linear computation (like difference between fields, add/multiply by a constant 
). you can simply put the following commands: {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">a - b</pre>
}}}{{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">numb1*a</pre>
}}}{{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">a + numb</pre>
}}} or any command with the following format {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">numb1*a + numb2*b  + numb3*c 
 + numb</pre>
}}} where numb1, numb2, 
 correspond to numbers and a, b, c 
 will be the data to read.


==== Any kind of computation ====

If you want to make a computation more complicated than a basic linear you must put designate the data you want to read between "" (with anything in between the "). For example: {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">"a"^2</pre>
}}}{{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">"a" - abs("b")</pre>
}}}{{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">grad("a", 'x')</pre>
}}} 





=== Calendar ===

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

    
      Example: first plot in January, second plot is from January to December

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0301.png)]]
  
      
    



=== Define the domain ===

  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.
  
    Domain by default

    
      [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0210.png)]]
    
      
  
  
    Change Domain area: zoom on Oceania

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0401.png)]]
  
      
  
  
    This configuration give us:

    
      [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0402.png)]]
    
      
  
  
    Change depth area: between depth 125 and 126

    
      [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0403.png)]]
    
      
  
  
    temperature of the ocean at depth 125 meters without proper land/sea mask

    
      [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0404.png)]]
    
      
  
  As you can see, at this depth, we better define a land/sea mask when loading the grid. Cf [#Launching XXX]



=== Specify your plot ===

==== Specify min, max and contour interval ====

  
    min, max, and contour interval specifications

    
      [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0501.png)]]
    
      
  
  You can restore configuration by default by pressing the Default button.
  The path of the file [../../ToBeReviewed/WIDGET/AUTOUR_de_XXX/definedefaultextra.pro definedefaultextra.pro] that defines the default values for each variable names is displayed when the cursor hovers over the button Default. This file contains a case statement based on the name of the variable and defining the min, max, contour interval and other keywords that should be used as default for the specified variable. You can copy this file in your own {{{${HOME}/My_IDL/}}} directory and easily modify it to suit your favorite default values.



==== Specify the palette to be used ====
For the color palette, you can either specify the name or go search for one among the palettes available.

    
      The Color menu

  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0502.png)]]
  
      
    



==== Add any keyword ====

  The "keywords" window allows specification of all desired keywords. There is a few examples of the use of this "keywords" window.
  
    Without any additional keyword

    
      [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0209.png)]]
    
      
  
  
    Add {{{/realcont}}} keyword

    
      [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0210a.png)]]
    
      
  
  
    Graphic with {{{/realcont}}} keyword

    
      [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0210.png)]]
    
      
  
  
    Add /realcont, map=[90,0,0], /ortho, cell_fill=2 keywords

    
      [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0211a.png)]]
    
      
  
  
    Graphic with /realcont, map=[90,0,0], /ortho, cell_fill=2 keywords

    
      [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0211.png)]]
    
      
  





== 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

* #xA;* #xA;* #xA;


In summary:



* #xA;* #xA;


* #xA;* #xA;


* #xA;* #xA;




If the plot selector is on something other than plt the indicated plot type is made.


=== 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: 


* #xA;* #xA;


* #xA;* #xA;

* #xA;

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



load xxx with the command:
  {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">
    <code class="prompt">idl&gt;</code> <strong class="userinput"><code><span><strong class="command">xxx</strong></span>, <em class="parameter"><code>'Levitus98_1m_01_12_Temperature_Pot_ORCA05.nc'</code></em>, <em class="parameter"><code>'tst_initorca05'</code></em></code></strong>
  </pre>
}}}




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




Create a horizontal plot in Frame 1





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.


    
      Frame with four plot
      
  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0901.png)]]
  
      
    





To redo the hovmoeller with the keyword {{{/nocontour}}}



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




Add the keyword
{{{/nocontour}}}


    
      Command text area
      
  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0902a.png)]]
  
      
    




click OK, and the plot is redone.


    
      The fourth plot with the keyword "nocontour"
      
  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0902.png)]]
  
      
    





in frame 5, let's create the same plot as in frame 2 except we use pltv instead of plt



DCL on frame 2




DCM on frame 5




change plt for pltv




Click on OK


    
      Frame with five plot
      
  
    [[Image(source:/trunk/SRC/Documentation/xmldoc/figpng/xxx_0903.png)]]
  
      
    





== What should I do when it breakdown ==





In the IDL window type (as many time you click on a button since a problem occurs in xxx !!!),
  {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">
<code class="prompt">idl&gt;</code> <strong class="userinput"><code>retall</code></strong>
</pre>
}}}



in the IDL window, type
  {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">
<code class="prompt">idl&gt;</code> <strong class="userinput"><code>domdef</code></strong>
</pre>
}}}


DCR to erase the problem frame.


change the orientation of the plot by pressing Flag options -&gt; Portrait/Landscape. Cf [#Launching XXX]

quit XXX cleanly using quit from the File menu. Cf [#Launching XXX]





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 want only killing the window will
leave a large number of unused variables in memory, which could in the end
overflow.
To clean up this memory:
  {{{
#!html
<pre xmlns:xl="http://www.w3.org/1999/xlink" class="screen">
<code class="prompt">idl&gt;</code> <strong class="userinput"><code>ptr_free, ptr_valid()</code></strong>
</pre>
}}}