source: trunk/Documentation/xmldoc/firststeps.xml @ 65

Last change on this file since 65 was 65, checked in by pinsard, 18 years ago

upgrade of Documentation/xmldoc according to cerbere.lodyc.jussieu.fr: /usr/home/smasson/SAXO_RD/
  • Property svn:executable set to *
File size: 40.1 KB
Line 
1<?xml version='1.0' encoding='iso-8859-1'?>
2<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
4[
5<!ENTITY promptidl "idl&gt;">
6<!ENTITY numb1 '<inlinemediaobject><imageobject><imagedata fileref="images/callouts/1.png" format="PNG"/></imageobject><textobject><phrase>1</phrase></textobject></inlinemediaobject>'>
7<!ENTITY numb2 '<inlinemediaobject><imageobject><imagedata fileref="images/callouts/2.png" format="PNG"/></imageobject><textobject><phrase>2</phrase></textobject></inlinemediaobject>'>
8<!ENTITY showfig '<inlinemediaobject><imageobject><imagedata fileref="images/showfig.png" format="PNG"/></imageobject><textobject><phrase>show result</phrase></textobject></inlinemediaobject>'>
9]>
10
11<!--
12instructions to create html file
13xsltproc ?-?-param  section.autolabel 1 -output firststep.html /sw/share/xml/xsl/docbook-xsl/xhtml/docbook.xsl firststep.xml
14xsltproc -output firststep.html /sw/share/xml/xsl/docbook-xsl/xhtml/docbook.xsl firststep.xml
15xsltproc  /sw/share/xml/xsl/docbook-xsl/xhtml/chunk.xsl  firststep.xml
16xsltproc ?-?-param  section.autolabel 1 /sw/share/xml/xsl/docbook-xsl/xhtml/chunk.xsl firststep.xml
17
18wget http://www.lodyc.jussieu.fr/~smasson/japon.html
19curl -O  http://www.lodyc.jussieu.fr/~smasson/japon.html
20-->
21
22<!--
23module :
24first steps with SAXO...
25
26source :
27/Users/sebastie/SAXO_RD/Documentation/xmldoc/firststeps.xml
28
29mise à jour :
30
31-->
32<article lang="en">
33  <title>
34    First steps with <application>SAXO</application>
35  </title>
36 
37  <articleinfo>
38    <authorgroup>
39      <author><firstname>Sébastien</firstname><surname>Masson</surname><email>smasson@lodyc.jussieu.fr</email></author>
40      <author><firstname>Françoise</firstname><surname>Pinsard</surname></author>
41    </authorgroup>
42    <keywordset>
43      <keyword>idl</keyword>
44      <keyword>SAXO</keyword>
45    </keywordset>
46    <revhistory>
47      <revision>
48        <revnumber>0.0</revnumber>
49        <date>29 July 2005</date>
50        <revremark>First draft</revremark>
51      </revision>
52      <revision>
53        <revnumber>0.1</revnumber>
54        <date>29 August 2005</date>
55        <revremark>last japanese version!</revremark>
56      </revision>
57    </revhistory> 
58  </articleinfo>
59 
60  <sect1 id="install_saxo">
61    <title>
62      Install <application>SAXO</application>
63    </title>
64    <para>
65        <application>SAXO</application> needs at least <trademark>IDL 6.0</trademark>.
66        <remark><application>SAXO</application> can be used with the 7 minutes demo-mode (within the limitations of this mode: impossible to save data and create a file).</remark>
67    </para>
68    <sect2 id="get_saxo">
69      <title>
70        Get <application>SAXO</application> source files from this web page
71      </title>
72      <para>
73        Two tar.gz files are available:
74        <itemizedlist>
75          <listitem><simpara><ulink url="http://www.lodyc.jussieu.fr/~smasson/SAXO/SRC/SAXO_RD_&date;.tar.gz">SAXO_RD_&date;.tar.gz</ulink> (&szsrc;) contains the latest version of the source files</simpara></listitem>
76          <listitem><simpara><ulink url="http://www.lodyc.jussieu.fr/~smasson/SAXO/DATA/TestsData_&date2;.tar.gz">TestsData_&date2;.tar.gz</ulink> (&szdata;) contains only the <application>NetCDF</application> files used by the test programs</simpara></listitem>
77        </itemizedlist>
78        Those tar.gzip files could also be downloaded with
79        <variablelist>
80          <varlistentry><term><command>wget</command></term>
81          <listitem><screen>
82  <prompt>$</prompt> <userinput>wget http://www.lodyc.jussieu.fr/~smasson/SAXO/SRC/SAXO_RD_&date;.tar.gz</userinput>
83  <prompt>$</prompt> <userinput>wget http://www.lodyc.jussieu.fr/~smasson/SAXO/DATA/TestsData_&date2;.tar.gz</userinput>
84          </screen></listitem>
85          </varlistentry>
86          <varlistentry><term><command>curl</command></term>
87          <listitem><screen>
88  <prompt>$</prompt> <userinput>curl -O http://www.lodyc.jussieu.fr/~smasson/SAXO/SRC/SAXO_RD_&date;.tar.gz</userinput>
89  <prompt>$</prompt> <userinput>curl -O http://www.lodyc.jussieu.fr/~smasson/SAXO/DATA/TestsData_&date2;.tar.gz</userinput>
90          </screen></listitem>
91          </varlistentry>
92        </variablelist>
93      </para>
94    </sect2>
95   
96    <sect2 id="create_saxo_env">
97      <title>
98        Create <application>SAXO</application> environment
99      </title>
100      <para>
101        To simplify the explanation, we suppose that <application>SAXO</application> is installed in <envar>$HOME</envar>.
102        We need to create 2 directories:
103        <itemizedlist>
104          <listitem><simpara>SAXO_DIR that will contain the source files of <application>SAXO</application>. It should not be modified by the user to simplify later updates</simpara></listitem>
105          <listitem><simpara>MY_IDL that will contain user personal files (including modified <application>SAXO</application> files, if needed).</simpara></listitem>
106        </itemizedlist>
107      </para>
108      <para>
109        <screen format="linespecific">
110  <prompt>$</prompt> <userinput><command>cd <envar>$HOME</envar></command></userinput>
111  <prompt>$</prompt> <userinput><command>mkdir My_IDL</command></userinput>
112  <prompt>$</prompt> <userinput><command>mkdir SAXO_DIR</command></userinput>
113  <prompt>$</prompt> <userinput><command>mv SAXO_RD_*.tar.gz SAXO_DIR</command></userinput>
114  <prompt>$</prompt> <userinput><command>cd SAXO_DIR</command></userinput>
115  <prompt>$</prompt> <userinput><command>tar xvfz SAXO_RD_*.tar.gz</command></userinput>
116  <prompt>$</prompt> <userinput><command>rm SAXO_RD_*.tar.gz</command></userinput>
117        </screen>
118      </para>
119      <para>
120        If you also downloaded the data tests files (<filename>TestsData_&date2;.tar.gz</filename>), You may install this tar.gz file in
121        <itemizedlist>
122          <listitem><simpara>MY_IDL. This is the easiest solution but it could be unconvenient if your <envar>$HOME</envar> disk space is limited.</simpara></listitem>
123          <listitem><simpara>Any other Directory of your choice. In that case, when using IDL, you will need to define the variable <varname>iodir</varname> to the Directory you choose in order to let IDL find the data tests files. This can be done either through the init.pro file (see <link linkend="generate_init"><xref linkend="generate_init"/></link>) or directly within IDL with the following commad: <prompt>&promptidl;</prompt> <userinput><command>iodir = "the chosen directory"</command></userinput></simpara></listitem>
124        </itemizedlist>
125        <screen format="linespecific">
126  <prompt>$</prompt> <userinput><command>cd <envar>$HOME</envar></command></userinput>
127  <prompt>$</prompt> <userinput><command>mv TestsData_&date2;.tar.gz "CHOSEN_DIR"</command></userinput>
128  <prompt>$</prompt> <userinput><command>cd "CHOSEN_DIR"</command></userinput>
129  <prompt>$</prompt> <userinput><command>tar xvfz TestsData_&date2;.tar.gz</command></userinput>
130  <prompt>$</prompt> <userinput><command>rm TestsData_&date2;.tar.gz</command></userinput>
131        </screen>
132      </para>
133    </sect2>
134   
135    <sect2 id="generate_init">
136      <title>
137        Generate your init.pro file
138      </title>
139      <para>
140        To use <application>SAXO</application>, we need to build an idl script that we usually call "<filename>init.pro</filename>". This file contains a set of IDL commands and default definitions (paths and variables of the common files) that are necessary to <application>SAXO</application>. Once it has ben created, <filename>init.pro</filename> should the first executed command when starting IDL session.
141      </para>
142      <para>
143        <screen format="linespecific">
144  <prompt>$</prompt> <userinput><command>cd <envar>$HOME</envar>/SAXO_DIR</command></userinput>
145  <prompt>$</prompt> <userinput><command>idl</command></userinput>
146  <computeroutput>IDL Version 6.0, Mac OS X (darwin ppc m32). (c) 2003, Research Systems, Inc.</computeroutput>
147<!--
148  <computeroutput>Installation number: 35411.</computeroutput>
149  <computeroutput>Licensed for personal use by Jean-Philippe BOULANGER only.</computeroutput>
150  <computeroutput>All other use is strictly prohibited.</computeroutput>
151-->
152  <prompt>&promptidl;</prompt> <userinput><command>buildinit</command></userinput>
153  <computeroutput>% Compiled module: BUILDINIT.</computeroutput>
154        </screen>
155        You must then answer several questions:
156<!--    <itemizedlist mark='opencircle'> -->
157        <itemizedlist>
158          <listitem><simpara>give the path of $<envar>HOME</envar>/My_IDL</simpara></listitem>
159          <listitem><simpara>give the path of $<envar>HOME</envar>/SAXO_DIR</simpara></listitem>
160          <listitem><simpara>compatibility with the old version: No (except if you want to use old programs)</simpara></listitem>
161          <listitem><simpara>give a default path for the data directory</simpara></listitem>
162          <listitem><simpara>give a default path for the postscript directory</simpara></listitem>
163          <listitem><simpara>give a default path for the images directory</simpara></listitem>
164          <listitem><simpara>give a default path for the animation directory</simpara></listitem>
165          <listitem><simpara>number of accessible printer and their configuration</simpara></listitem>
166          <listitem><simpara>default color table</simpara></listitem>
167          <listitem><simpara>default page orientation (portrait/landscape)</simpara></listitem>
168          <listitem><simpara>default page size</simpara></listitem>
169          <listitem><simpara>default window size</simpara></listitem>
170          <listitem><simpara>postscript archiving options</simpara></listitem>
171          <listitem><simpara>name of the init file (<filename>init.pro</filename>)</simpara></listitem>
172        </itemizedlist>
173        <screen format="linespecific">
174   <computeroutput>% Compiled module: CW_FIELD.</computeroutput>
175   <computeroutput>% Compiled module: XMANAGER.</computeroutput>
176   <computeroutput>% Compiled module: LOADCT.</computeroutput>
177   <computeroutput>% Compiled module: FILEPATH.</computeroutput>
178   <computeroutput>% Compiled module: PATH_SEP.</computeroutput>
179   <computeroutput>% Compiled module: CW_FIELD.</computeroutput>
180   <computeroutput>% Compiled module: STRSPLIT.</computeroutput>
181   <computeroutput>% Compiled module: CW_FIELD.</computeroutput>
182   <computeroutput>% Compiled module: CW_FIELD.</computeroutput>
183   <computeroutput>% Compiled module: CW_FIELD.</computeroutput>
184   <prompt>&promptidl;</prompt> <userinput><command>exit</command></userinput>
185        </screen>
186        There is an example of the kind of <ulink url="idlfiles/init_example.pro"> <filename>init.pro</filename></ulink> you should get.
187      </para>
188     
189    </sect2>
190  </sect1>
191 
192  <sect1 id="first_plots">
193    <title>
194      First plots...
195    </title>
196    <sect2 id="start_with_init">
197      <title>
198        Start idl session: <userinput><command>@init</command></userinput>
199      </title>
200      <para>
201        Each idl session using <application>SAXO</application> must always start with: <prompt>&promptidl;</prompt> <userinput><command>@init</command></userinput>.     
202      </para>
203      <para>
204        <emphasis>The @ is equivalent to an include. It is used to execute a set of IDL commands that will be directly executed without any compilation (as it is the case for a procedure or a function). All variables defined and used in the @... file will still be accessible after the execution of the @... is finished (which is not the case for procedures and functions that ends with the return instruction).</emphasis>
205        <screen format="linespecific">
206  <prompt>$</prompt> <userinput><command>cd <envar>$HOME</envar>/My_IDL</command></userinput>
207  <prompt>$</prompt> <userinput><command>idl</command></userinput>
208  <computeroutput>IDL Version 6.0, Mac OS X (darwin ppc m32). (c) 2003, Research Systems, Inc.</computeroutput>
209  <computeroutput>Installation number: 35411.</computeroutput>
210  <computeroutput>Licensed for personal use by Jean-Philippe BOULANGER only.</computeroutput>
211  <computeroutput>All other use is strictly prohibited.</computeroutput>
212  <prompt>&promptidl;</prompt> <userinput><command>@init</command></userinput>
213  <computeroutput>% Compiled module: KEEP_COMPATIBILITY.</computeroutput>
214  <computeroutput>% Compiled module: FIND.</computeroutput>
215  <computeroutput>% Compiled module: PATH_SEP.</computeroutput>
216  <computeroutput>% Compiled module: STRSPLIT.</computeroutput>
217  <computeroutput>% Compiled module: DEF_MYUNIQUETMPDIR.</computeroutput>
218  <computeroutput>We forget the compatibility with the old version</computeroutput>
219  <computeroutput>% Compiled module: DEMOMODE_COMPATIBILITY.</computeroutput>
220  <computeroutput>% Compiled module: ISADIRECTORY.</computeroutput>
221  <computeroutput>% Compiled module: LCT.</computeroutput>
222  <computeroutput>% Compiled module: RSTRPOS.</computeroutput>
223  <computeroutput>% Compiled module: REVERSE.</computeroutput>
224  <computeroutput>% Compiled module: STR_SEP.</computeroutput>
225  <computeroutput>% Compiled module: LOADCT.</computeroutput>
226  <prompt>&promptidl;</prompt>
227        </screen>
228        As an IDL session using <application>SAXO</application> must always start with <prompt>&promptidl;</prompt> <userinput><command>@init</command></userinput>, it could be convenient to define the environment variable <envar>IDL_STARTUP</envar> to <filename><envar>$HOME</envar>/My_IDL/init.pro</filename>. In that way, init.pro will automatically been execuded when starting IDL. This can be done with the following command:
229      <variablelist>
230        <varlistentry><term><command>csh</command></term>
231        <listitem><screen><prompt>$</prompt> <userinput>setenv <envar>IDL_STARTUP</envar> <filename><envar>$HOME</envar>/My_IDL/init.pro</filename></userinput></screen></listitem>
232        </varlistentry>
233        <varlistentry><term><command>ksh</command></term>
234        <listitem><screen><prompt>$</prompt> <userinput>export <envar>IDL_STARTUP</envar>=<filename><envar>$HOME</envar>/My_IDL/init.pro</filename></userinput></screen></listitem>
235        </varlistentry>
236      </variablelist>
237      </para>
238 
239     
240    </sect2>
241    <sect2 id="basic_plots">
242      <title>
243        basic plots...
244      </title>
245      <sect3 id="basic_splot">
246      <title>
247        splot
248      </title>
249
250      <para>
251        <screenco>
252          <areaspec>
253            <area id="findgen" coords='2'/>
254          </areaspec>
255        <screen format="linespecific">
256   <prompt>&promptidl;</prompt> <userinput><command>n = 10</command></userinput>
257   <prompt>&promptidl;</prompt> <userinput><command>y = findgen(n)</command></userinput> &numb1;
258   <prompt>&promptidl;</prompt> <userinput><command>plot, y</command></userinput> <ulink url="figpng/basic_plot.png">&showfig;</ulink>
259        </screen>
260          <calloutlist>
261            <callout arearefs="findgen">
262              <para>
263                <command>findgen</command> stands for <command>f</command>loat <command>ind</command>ex <command>gen</command>erator.
264                <screen format="linespecific">
265  <prompt>&promptidl;</prompt> <userinput><command>print, findgen(6)</command></userinput>
266  <computeroutput>      0.00000      1.00000      2.00000      3.00000      4.00000      5.00000</computeroutput>
267                </screen>
268              </para> 
269            </callout>
270          </calloutlist>
271        </screenco>
272     </para>
273     
274      <para>
275        Using IDL <command>plot</command> command is quite unconvenient to save the figure as a postscript. In addition, positionning the figure on the window/page by using <varname>!p.position</varname>, <varname>!p.region</varname> and <varname>!p.multi</varname> is often a nightmare. That's why we developped <command>splot</command> (like super-plot) which can be used in the same way as plot but is much more convenient to make postcript and position the figure.
276        <screen format="linespecific">
277  <prompt>&promptidl;</prompt> <userinput><command>splot, y</command></userinput> <ulink url="figpng/basic_splot1.png">&showfig;</ulink>
278  <computeroutput>% Compiled module: SPLOT.</computeroutput>
279  <computeroutput>% Compiled module: REINITPLT.</computeroutput>
280  <computeroutput>% Compiled module: PLACEDESSIN.</computeroutput>
281  <computeroutput>% Compiled module: CALIBRE.</computeroutput>
282  <computeroutput>% Compiled module: GIVEWINDOWSIZE.</computeroutput>
283  <computeroutput>% Compiled module: GET_SCREEN_SIZE.</computeroutput>
284  <computeroutput>% Compiled module: TERMINEDESSIN.</computeroutput>
285        </screen>
286        Save the figure seen on the screen as a (real, not a screen capture) postscript in only one command.
287        <screenco>
288          <areaspec>
289            <area id="make_ps" coords='6'/>
290          </areaspec>
291        <screen format="linespecific">
292  <prompt>&promptidl;</prompt> <userinput><command>@ps</command></userinput>
293  <computeroutput>% Compiled module: GETFILE.</computeroutput>
294  <computeroutput>% Compiled module: PUTFILE.</computeroutput>
295  <computeroutput>% Compiled module: OPENPS.</computeroutput>
296  <computeroutput>% Compiled module: XQUESTION.</computeroutput>
297  <computeroutput>Name of the postscript file? (default answer is idl.ps) </computeroutput><userinput>first_ps</userinput> &numb1;
298  <computeroutput>% Compiled module: ISAFILE.</computeroutput>
299  <computeroutput>% Compiled module: XNOTICE.</computeroutput>
300  <computeroutput>% Compiled module: CLOSEPS.</computeroutput>
301  <computeroutput>% Compiled module: PRINTPS.</computeroutput>
302  <computeroutput>% Compiled module: FILE_WHICH.</computeroutput>
303  <computeroutput>% Compiled module: CW_BGROUP.</computeroutput>
304  <computeroutput>% Compiled module: XMANAGER.</computeroutput>
305        </screen>
306          <calloutlist>
307            <callout arearefs="make_ps">
308              <para>
309                <remark>If needed, the name of the postscript will automatically be completed with .ps. Just hit return, if you want to use the default posscript name: idl.ps.</remark> 
310              </para>
311            </callout>
312          </calloutlist>
313        </screenco>
314        Check that the 'first_ps.ps' file is now existing...
315        <screen format="linespecific">
316  <prompt>&promptidl;</prompt> <userinput><command>print, file_test(psdir + 'first_ps.ps')</command></userinput>
317  <computeroutput>           1</computeroutput>
318  <prompt>&promptidl;</prompt> <userinput><command>help, file_info(psdir + 'first_ps.ps'), /structure</command></userinput>
319  <computeroutput>** Structure FILE_INFO, 21 tags, length=64, data length=63:</computeroutput>
320  <computeroutput>   NAME            STRING    '/Users/sebastie/IDL/first_ps.ps'</computeroutput>
321  <computeroutput>   EXISTS          BYTE         1</computeroutput>
322  <computeroutput>   READ            BYTE         1</computeroutput>
323  <computeroutput>   WRITE           BYTE         1</computeroutput>
324  <computeroutput>   EXECUTE         BYTE         0</computeroutput>
325  <computeroutput>   REGULAR         BYTE         1</computeroutput>
326  <computeroutput>   DIRECTORY       BYTE         0</computeroutput>
327  <computeroutput>   BLOCK_SPECIAL   BYTE         0</computeroutput>
328  <computeroutput>   CHARACTER_SPECIAL</computeroutput>
329  <computeroutput>                   BYTE         0</computeroutput>
330  <computeroutput>   NAMED_PIPE      BYTE         0</computeroutput>
331  <computeroutput>   SETUID          BYTE         0</computeroutput>
332  <computeroutput>   SETGID          BYTE         0</computeroutput>
333  <computeroutput>   SOCKET          BYTE         0</computeroutput>
334  <computeroutput>   STICKY_BIT      BYTE         0</computeroutput>
335  <computeroutput>   SYMLINK         BYTE         0</computeroutput>
336  <computeroutput>   DANGLING_SYMLINK</computeroutput>
337  <computeroutput>                   BYTE         0</computeroutput>
338  <computeroutput>   MODE            LONG               420</computeroutput>
339  <computeroutput>   ATIME           LONG64                1122424373</computeroutput>
340  <computeroutput>   CTIME           LONG64                1122424373</computeroutput>       
341  <computeroutput>   MTIME           LONG64                1122424373</computeroutput>       
342  <computeroutput>   SIZE            LONG64                      4913</computeroutput>
343        </screen>
344      </para>
345      <para id="splot_description">
346        <command>splot</command> accepts the same keywords as <command>plot</command> (<computeroutput id="plot_kwd">/ISOTROPIC, MAX_VALUE=value, MIN_VALUE=value, NSUM=value, /POLAR, THICK=value, /XLOG, /YLOG, /YNOZERO</computeroutput>), including the graphics keywords (<computeroutput id="gr_kwd">BACKGROUND, CHARSIZE, CHARTHICK, CLIP, COLOR, DATA, DEVICE, FONT, LINESTYLE, NOCLIP, NODATA, NOERASE, NORMAL, POSITION, PSYM, SUBTITLE, SYMSIZE, T3D, THICK, TICKLEN, TITLE, [XYZ]CHARSIZE, [XYZ]GRIDSTYLE, [XYZ]MARGIN, [XYZ]MINOR, [XYZ]RANGE, [XYZ]STYLE, [XYZ]THICK, [XYZ]TICKFORMAT, [XYZ]TICKINTERVAL, [XYZ]TICKLAYOUT, [XYZ]TICKLEN, [XYZ]TICKNAME, [XYZ]TICKS, [XYZ]TICKUNITS, [XYZ]TICKV, [XYZ]TICK_GET, [XYZ]TITLE, ZVALUE</computeroutput>).
347      </para>
348      <simpara>
349        It can therefore be customized <emphasis>as much as you want</emphasis>. See this short example:
350      </simpara>
351      <para>
352        <screen format="linespecific">
353  <prompt>&promptidl;</prompt> <userinput><command>splot, y, y^2, linestyle = 2, thick = 2, title = 'y = x^2', /portrait</command></userinput> <ulink url="figpng/basic_splot2.png">&showfig;</ulink>
354        </screen>
355        <command>splot</command> can be used to setup the graphic environment (<varname>!p</varname>, <varname>!x</varname>, <varname>!y</varname>, <varname>!z</varname> variables) needed by procedures like <command>oplot</command>
356        <screen format="linespecific">
357  <prompt>&promptidl;</prompt> <userinput><command>splot, y, yrange = [0, (n-1)^2], title = 'x and x^2'</command></userinput>
358  <prompt>&promptidl;</prompt> <userinput><command>oplot, y^2, color = 50, linestyle = 2</command></userinput> <ulink url="figpng/basic_splot4.png">&showfig;</ulink>
359        </screen>
360        Use the keyword small to produce multi plots figures.
361        <screenco>
362          <areaspec>
363            <areaset id="small" coords="">
364              <area id="small.1" coords='1'/>
365              <area id="small.2" coords='2'/>
366            </areaset>
367            <area id="noerase" coords='2'/>
368          </areaspec>
369        <screen format="linespecific">
370  <prompt>&promptidl;</prompt> <userinput><command>splot, y, y^2, title = 'y = x^2', psym = 2, small &numb1; = [1, 2, 1]</command></userinput>
371  <prompt>&promptidl;</prompt> <userinput><command>splot, findgen(360)/36., findgen(360)*2.*!dtor, /polar $</command></userinput>
372  <prompt>&promptidl;</prompt> <userinput><command>    , small &numb1; = [1, 2, 2], /noerase &numb2;</command></userinput> <ulink url="figpng/basic_splot3.png">&showfig;</ulink>
373        </screen>
374          <calloutlist>
375            <callout arearefs="small">
376              <para>
377                the <computeroutput>small</computeroutput> keyword is a 3 elements vector which define how we devide the page in in which case we should make the plot: [number of columns, number of rows, case number]. The case numbering is starting at 1, from top to bottom and left to right.
378              </para>
379            </callout>
380            <callout arearefs="noerase">
381              <simpara>
382                you must put <computeroutput>/norease</computeroutput> otherwise the second plot will be done in a new window.
383              </simpara>
384            </callout>
385          </calloutlist>
386        </screenco>
387      </para>
388     
389      </sect3>
390
391      <sect3 id="basic_contour">
392      <title>
393        scontour
394      </title>
395      <para>
396        Following <command><link linkend="basic_splot">splot</link></command> example, we provide <command>scontour</command> as a "super <command>contour</command>".
397        <screen format="linespecific">
398  <prompt>&promptidl;</prompt> <userinput><command>z = dist(n)</command></userinput>
399  <computeroutput>% Compiled module: DIST.</computeroutput>
400  <prompt>&promptidl;</prompt> <userinput><command>scontour, z</command></userinput> <ulink url="figpng/basic_scontour1.png">&showfig;</ulink>
401  <computeroutput>% Compiled module: SCONTOUR.</computeroutput>
402  <computeroutput>% Compiled module: CHKSTRU.</computeroutput>
403        </screen>
404        <command>scontour</command> accepts the same keywords as <command>contour</command> (<computeroutput>C_ANNOTATION=vector_of_strings, C_CHARSIZE=value, C_CHARTHICK=integer, C_COLORS=vector, C_LABELS=vector{each element 0 or 1}, C_LINESTYLE=vector, { /FILL | /CELL_FILL | C_ORIENTATION=degrees}, C_SPACING=value, C_THICK=vector, /CLOSED, /DOWNHILL, /FOLLOW, /IRREGULAR, /ISOTROPIC, LEVELS=vector, NLEVELS=integer{1 to 60}, MAX_VALUE=value, MIN_VALUE=value, /OVERPLOT, {/PATH_DATA_COORDS, PATH_FILENAME=string, PATH_INFO=variable, PATH_XY=variable}, TRIANGULATION=variable, /PATH_DOUBLE, /XLOG, /YLOG, ZAXIS={0 | 1 | 2 | 3 | 4}</computeroutput>), including the <link linkend="gr_kwd">graphics keywords</link> (except <computeroutput>LINESTYLE, PSYM, SYMSIZE</computeroutput>).
405      </para>
406      <simpara>It can therefore be customized <emphasis>as much as you want</emphasis>. See these short examples:</simpara>
407      <para>
408        <screen format="linespecific">
409  <prompt>&promptidl;</prompt> <userinput><command>scontour, z, /fill, nlevels = 15, subtitle = 'nicer contour' $</command></userinput>
410  <prompt>&promptidl;</prompt> <userinput><command>    , xtitle = 'x index', charsize = 1.5</command></userinput> <ulink url="figpng/basic_scontour2.png">&showfig;</ulink>
411        </screen>
412It can be used in combinanson with contour to make more complex plots:
413        <screenco>
414          <areaspec>
415            <area id="rebin" coords='1'/>
416          </areaspec>
417        <screen format="linespecific">
418  <prompt>&promptidl;</prompt> <userinput><command>ind = findgen(2*n)/(2.*n)</command></userinput>
419  <prompt>&promptidl;</prompt> <userinput><command>scontour, z, levels = n*ind, c_orientation = 180*ind, c_spacing = 0.4*ind</command></userinput>
420  <prompt>&promptidl;</prompt> <userinput><command>contour, z, /overplot, c_label = rebin([1, 0], 2, n) &numb1;, levels = n*ind $</command></userinput>
421  <prompt>&promptidl;</prompt> <userinput><command>    , c_charthick = 2, c_charsize = 1.5, c_colors = 250*ind</command></userinput> <ulink url="figpng/basic_scontour3.png">&showfig;</ulink>
422        </screen>
423        <calloutlist>
424          <callout arearefs="rebin">
425            <para>
426              <command>rebin</command> is used to build an array containing an alternation of 1 and 0 in order to label one contour every two contours.
427                <screen format="linespecific">
428  <prompt>&promptidl;</prompt> <userinput><command>print, rebin([1, 0], 2, 3)</command></userinput>
429  <computeroutput>       1       0</computeroutput>
430  <computeroutput>       1       0</computeroutput>
431  <computeroutput>       1       0</computeroutput>
432                </screen>
433            </para>
434          </callout>
435        </calloutlist>
436        </screenco>
437        <command>scontour</command> is compatible with the positioning method associated with the <computeroutput>small</computeroutput> keyword. See for example the test file <ulink url="idlfiles/tst_basic.pro"><filename>tst_basic.pro</filename></ulink>:
438        <screen format="linespecific">
439  <prompt>&promptidl;</prompt> <userinput><command>tst_basic</command></userinput> <ulink url="figpng/tst_basic.png">&showfig;</ulink>
440        </screen>
441      </para>
442      </sect3>
443
444      <sect3 id="tvplus">
445        <title>
446          Quick look at 2D arrays: tvplus
447        </title>
448        <para>
449          <command>tvplus</command> is a enhanced version of tvscl and allow you to have a quick look and perform basic exploration of 2D arrays.
450          <screen format="linespecific">
451            <prompt>&promptidl;</prompt> <userinput><command>tvplus, dist(20)</command></userinput> <ulink url="figpng/tvplus.png">&showfig;</ulink>
452  <computeroutput>left button  : mouse position and associated array value</computeroutput>
453  <computeroutput>middle button: use it twice to define a zoom box</computeroutput>
454  <computeroutput>right button : quit</computeroutput>
455  <computeroutput>(x, y) = (  5,   5), value = 7.07107</computeroutput>
456  <computeroutput>(x, y) = ( 12,   8), value = 11.3137</computeroutput>
457          </screen>
458          For more informations on <command>tvplus</command>, try:
459          <screen format="linespecific">
460  <prompt>&promptidl;</prompt> <userinput><command>xhelp, 'tvplus'</command></userinput>
461          </screen>
462        </para>
463      </sect3>
464    </sect2>
465  </sect1>
466
467  <sect1 id="gridded_data">
468    <title>
469      Explore gridded data (model outputs and observations)
470    </title>
471    <para>
472      This section briefly describes the main fonctionalities offered by SAXO to explore gridded data on regular or irregular grid.
473    </para>
474
475    <sect2 id="load_grid">
476      <title>
477        Load the data grid
478      </title>
479      <para>
480        As we focus in this section on the gridded data, we must first load the grid informations before reading and plotting the data. Loading the grid independently of the data allow you to reload the grid only when it is strictly necessary and not every time you access the data. In <envar>$HOME</envar>/SAXO_DIR/Tests, we provide several examples to load a grid.
481      </para>
482      <sect3 id="load_fromdata">
483        <title>
484          Easiest solution: load data grid (regular or not) directly from the data file.
485        </title>
486        <para>
487          Example of Levitus temprature on a regular 1x1 grid.
488          <screen format="linespecific">
489  <prompt>&promptidl;</prompt> <userinput><command>@tst_initlev</command></userinput>
490  <computeroutput>% Compiled module: INITNCDF.</computeroutput>
491  <computeroutput>% Compiled module: ISAFILE.</computeroutput>
492  <computeroutput>% Compiled module: UNIQ.</computeroutput>
493  <computeroutput>% Loaded DLM: NCDF.</computeroutput>
494  <computeroutput>% Compiled module: COMPUTEGRID.</computeroutput>
495  <computeroutput>% Compiled module: DOMDEF.</computeroutput>
496  <computeroutput>% Compiled module: INTER.</computeroutput>
497  <computeroutput>% Compiled module: TRIANGULE.</computeroutput>
498  <computeroutput>% Compiled module: TRIANGULE_C.</computeroutput>
499  <computeroutput>% Compiled module: UNDEFINE.</computeroutput>
500  <computeroutput>% Compiled module: TESTVAR.</computeroutput>
501  <computeroutput>% Compiled module: DIFFERENT.</computeroutput>
502  <computeroutput>% Compiled module: DEFINETRI.</computeroutput>
503          </screen>
504          This <ulink url="idlfiles/tst_initlev.pro"><command>@tst_initlev</command></ulink> command allows us to define:
505          <itemizedlist>
506            <listitem><simpara>domain dimensions, stored in <varname>jpi, jpj and jpk</varname></simpara></listitem>
507            <listitem><simpara>points abscissa, stored in 2D array <varname></varname>glamt</simpara></listitem>
508            <listitem><simpara>points ordinates, stored in 2D array <varname></varname>gphit</simpara></listitem>
509            <listitem><simpara>points depths, stored in 1D array <varname></varname>gdept</simpara></listitem>
510            <listitem><simpara>cells corners abscissa, storde in 2D array <varname></varname>glamf</simpara></listitem>
511            <listitem><simpara>cells corners ordinates, stored in 2D array <varname></varname>gphif</simpara></listitem>
512            <listitem><simpara>cells upper bondary depth, stored in 1D array <varname></varname>gdepw</simpara></listitem>
513            <listitem><simpara>land-sea mask, stored in <varname></varname>tmask</simpara></listitem>
514            <listitem><simpara>the cells size in the longitudinal direction, stored in 2D array <varname></varname>e1t</simpara></listitem>
515            <listitem><simpara>the cells size in the latitudinal direction, stored in 2D array <varname></varname>e2t</simpara></listitem>
516            <listitem><simpara>the cells size in the vertical direction, stored in 1D array <varname></varname>e3t</simpara></listitem>
517            <listitem><simpara>the triangulation used to fill the land points, stored in <varname></varname>triangles_list</simpara></listitem>
518          </itemizedlist>
519
520          <screen format="linespecific">
521  <prompt>&promptidl;</prompt> <userinput><command>help, jpi,jpj,jpk</command></userinput>
522  <computeroutput>JPI (LOCAL_COORD)   LONG      =          360</computeroutput>
523  <computeroutput>JPJ (LOCAL_COORD)   LONG      =          180</computeroutput>
524  <computeroutput>JPK (LOCAL_COORD)   LONG      =           33</computeroutput>
525  <prompt>&promptidl;</prompt> <userinput><command>help, glamt, gphit,glamf, gphif</command></userinput>
526  <computeroutput>GLAMT (LONGITUDES)  FLOAT     = Array[360, 180]</computeroutput>
527  <computeroutput>GPHIT (LATITUDES)   FLOAT     = Array[360, 180]</computeroutput>
528  <computeroutput>GLAMF (LONGITUDES)  FLOAT     = Array[360, 180]</computeroutput>
529  <computeroutput>GPHIF (LATITUDES)   FLOAT     = Array[360, 180]</computeroutput>
530  <prompt>&promptidl;</prompt> <userinput><command>help, gdept, gdepw</command></userinput>
531  <computeroutput>GDEPT (VERTICAL)    FLOAT     = Array[33]</computeroutput>
532  <computeroutput>GDEPW (VERTICAL)    FLOAT     = Array[33]</computeroutput>
533  <prompt>&promptidl;</prompt> <userinput><command>help, e1t, e2t, e3t</command></userinput>
534  <computeroutput>E1T (SCALE_FACTORS) FLOAT     = Array[360, 180]</computeroutput>
535  <computeroutput>E2T (SCALE_FACTORS) FLOAT     = Array[360, 180]</computeroutput>
536  <computeroutput>E3T (VERTICAL)      FLOAT     = Array[33]</computeroutput>
537  <prompt>&promptidl;</prompt> <userinput><command>help, tmask</command></userinput>
538  <computeroutput>TMASK (MASKS)       BYTE      = Array[360, 180, 33]</computeroutput>
539  <prompt>&promptidl;</prompt> <userinput><command>help, triangles_list</command></userinput>
540  <computeroutput>TRIANGLES_LIST (LIEES_A_TRIANGULE) LONG      = Array[3, 128880]</computeroutput>
541  <prompt>&promptidl;</prompt> <userinput><command>tvplus, glamt*tmask[*,*,0]</command></userinput>
542  <prompt>&promptidl;</prompt> <userinput><command>tvplus, gphit*tmask[*,*,0]</command></userinput>
543          </screen>
544          We provide other initialization methods/examples
545          <itemizedlist>
546            <listitem><simpara><ulink url="idlfiles/tst_initorca2_short.pro">@tst_initorca2_short</ulink> : ORCA2 example</simpara></listitem>
547            <listitem><simpara><ulink url="idlfiles/tst_initorca05_short.pro">@tst_initorca05_short</ulink> : ORCA05 example</simpara></listitem>
548            <listitem><simpara><ulink url="idlfiles/tst_initlev_stride.pro">@tst_initlev_stride</ulink> : same as @tst_initlev but we skip on point over 2 in x and y direction</simpara></listitem>
549            <listitem><simpara><ulink url="idlfiles/tst_initorca2_short_stride.pro">@tst_initorca2_short_stride</ulink> : ORCA2 with stride</simpara></listitem>
550            <listitem><simpara><ulink url="idlfiles/tst_initorca05_short_stride.pro">@tst_initorca05_short_stride</ulink> : ORCA05 with stride</simpara></listitem>
551            <listitem><simpara><ulink url="idlfiles/tst_initlev_index.pro">@tst_initlev_index</ulink> : in that case we load the grid using points index as axis instead of the longitude/latitude position</simpara></listitem>
552            <listitem><simpara><ulink url="idlfiles/tst_initorca2_index.pro">@tst_initorca2_index</ulink> : load ORCA2 as it see by the model</simpara></listitem>
553            <listitem><simpara><ulink url="idlfiles/tst_initorca05_index.pro">@tst_initorca05_index</ulink> : load ORCA05 as it see by the model</simpara></listitem>
554            <listitem><simpara><ulink url="idlfiles/tst_initlev_index_stride.pro">@tst_initlev_index_stride</ulink> : @tst_initlev_index with stride</simpara></listitem>
555            <listitem><simpara><ulink url="idlfiles/tst_initorca2_index_stride.pro">@tst_initorca2_index_stride</ulink> : ORCA2 in index with stride</simpara></listitem>
556            <listitem><simpara><ulink url="idlfiles/tst_initorca05_index_stride.pro">@tst_initorca05_index_stride</ulink> : ORCA05 in index with stride</simpara></listitem>
557          </itemizedlist>
558        </para>
559      </sect3>
560      <sect3 id="load_meshmask">
561        <title>
562          Load the grid from OPA <filename>meshmask</filename> file
563        </title>
564        <para>
565          When the grid is really irregular (its abscissa and ordinate cannot be descried by a vector), loading the grid directly from the data forces us to make an approximation when computing the grid corners position and the cells size. In that case, it can be preferable to load the grid from the meshmask file created by OPA. As OPA use a Arakawa-C discretization, loading the grid from the meshmask will also define all parameters related to the U, V and F grids (glam[uv],gphi[uv], e[12][uvf]). Note that, when using a simple <link linkend="load_fromdata">grid definition from the data itself</link> (with <filename>initncdf</filename> or <filename>computegrid</filename>), adding the keyword /FULLCGRID leads also to the definition of all U, V and F grids parameters. There is the examples to load ORCA grids from OPA meshmask.
566          <itemizedlist>
567            <listitem><simpara><ulink url="idlfiles/tst_initorca2.pro">@tst_initorca2</ulink> : ORCA2</simpara></listitem>
568            <listitem><simpara><ulink url="idlfiles/tst_initorca05.pro">@tst_initorca05</ulink> : ORCA05</simpara></listitem>
569            <listitem><simpara><ulink url="idlfiles/tst_initorca2_stride.pro">@tst_initorca2_stride</ulink> : ORCA2 with stride</simpara></listitem>
570            <listitem><simpara><ulink url="idlfiles/tst_initorca05_stride.pro">@tst_initorca05_stride</ulink> : ORCA05 with stride</simpara></listitem>
571            <listitem><simpara><ulink url="idlfiles/tst_initorca2_index.pro">@tst_initorca2_index</ulink> : load ORCA2 as it see by the model</simpara></listitem>
572            <listitem><simpara><ulink url="idlfiles/tst_initorca05_index.pro">@tst_initorca05_index</ulink> : load ORCA05 as it see by the model</simpara></listitem>
573            <listitem><simpara><ulink url="idlfiles/tst_initorca2_index_stride.pro">@tst_initorca2_index_stride</ulink> : ORCA2 in index with stride</simpara></listitem>
574            <listitem><simpara><ulink url="idlfiles/tst_initorca05_index_stride.pro">@tst_initorca05_index_stride</ulink> : ORCA05 in index with stride</simpara></listitem>
575          </itemizedlist>
576        </para>
577        </sect3>
578    </sect2>
579
580    <sect2 id="plt">
581      <title>
582        horizontal plots and maps
583      </title>
584        <para>
585          A quick presentation of horizontal plots and maps is shown in <ulink url="idlfiles/tst_plt.pro">tst_plt</ulink>. After laoding any of the grid (for example with one of the <link linkend="load_grid">above examples</link>). Just try:
586          <screen format="linespecific">
587  <prompt>&promptidl;</prompt> <userinput><command>tst_plt</command></userinput>
588          </screen>
589        </para>
590        <simpara><emphasis>Beware, the command is <command>tst_plt</command> and not <command>@tst_plt</command> as tst_plt.pro is a procedure and not an include.</emphasis></simpara>
591        <para>
592          See the results with
593          <itemizedlist>
594          <listitem><simpara><command>@tst_initlev</command>&figsplt_lev;</simpara></listitem>
595          <listitem><simpara><command>@tst_initorca2</command>&figsplt_orca2;</simpara></listitem>
596          <listitem><simpara><command>@tst_initorca05</command>&figsplt_orca05;</simpara></listitem>
597          <listitem><simpara><command>@tst_initlev_stride</command>&figsplt_lev_stride;</simpara></listitem>
598          <listitem><simpara><command>@tst_initorca2_stride</command>&figsplt_orca2_stride;</simpara></listitem>
599          <listitem><simpara><command>@tst_initorca05_stride</command>&figsplt_orca05_stride;</simpara></listitem>
600          </itemizedlist>
601        </para>
602    </sect2>
603
604    <sect2 id="pltz">
605      <title>
606        vertical sections
607      </title>
608        <para>
609          A quick presentation of vertical sections is shown in <ulink url="idlfiles/tst_pltz.pro">tst_pltz</ulink>. After laoding any of the grid (for example with one of the <link linkend="load_grid">above examples</link>). Just try:
610          <screen format="linespecific">
611  <prompt>&promptidl;</prompt> <userinput><command>tst_pltz</command></userinput>
612          </screen>
613        </para>
614          <simpara><emphasis>Beware, the command is <command>tst_pltz</command> and not <command>@tst_pltz</command> as tst_pltz.pro is a procedure and not an include.</emphasis></simpara>     
615        <para>
616          See the results with
617          <itemizedlist>
618          <listitem><simpara><command>@tst_initlev</command>&figspltz_lev;</simpara></listitem>
619          <listitem><simpara><command>@tst_initorca2</command>&figspltz_orca2;</simpara></listitem>
620          <listitem><simpara><command>@tst_initorca05</command>&figspltz_orca05;</simpara></listitem>
621          <listitem><simpara><command>@tst_initlev_stride</command>&figspltz_lev_stride;</simpara></listitem>
622          <listitem><simpara><command>@tst_initorca2_stride</command>&figspltz_orca2_stride;</simpara></listitem>
623          <listitem><simpara><command>@tst_initorca05_stride</command>&figspltz_orca05_stride;</simpara></listitem>
624          </itemizedlist>
625        </para>
626    </sect2>
627
628    <sect2 id="pltt">
629      <title>
630        hovmoellers and time series
631      </title>
632        <para>
633          A quick presentation of hovmoellers and time series is shown in <ulink url="idlfiles/tst_pltt.pro">tst_pltt</ulink>. After laoding any of the grid (for example with one of the <link linkend="load_grid">above examples</link>). Just try:
634          <screen format="linespecific">
635  <prompt>&promptidl;</prompt> <userinput><command>tst_pltt</command></userinput>
636          </screen>
637        </para>
638          <simpara><emphasis>Beware, the command is <command>tst_pltt</command> and not <command>@tst_pltt</command> as tst_pltt.pro is a procedure and not an include.</emphasis></simpara>
639        <para>
640          See the results with
641          <itemizedlist>
642          <listitem><simpara><command>@tst_initlev</command>&figspltt_lev;</simpara></listitem>
643          <listitem><simpara><command>@tst_initorca2</command>&figspltt_orca2;</simpara></listitem>
644          <listitem><simpara><command>@tst_initorca05</command>&figspltt_orca05;</simpara></listitem>
645          <listitem><simpara><command>@tst_initlev_stride</command>&figspltt_lev_stride;</simpara></listitem>
646          <listitem><simpara><command>@tst_initorca2_stride</command>&figspltt_orca2_stride;</simpara></listitem>
647          <listitem><simpara><command>@tst_initorca05_stride</command>&figspltt_orca05_stride;</simpara></listitem>
648          </itemizedlist>
649        </para>
650    </sect2>
651
652    <sect2 id="plt1d">
653      <title>
654        1D plots
655      </title>
656        <para>
657          To be continued...
658        </para>
659   </sect2>
660
661
662  </sect1>
663 
664</article>
Note: See TracBrowser for help on using the repository browser.