File: introduction.docbook

package info (click to toggle)
qtiplot 0.9.8-1
  • links: PTS, VCS
  • area: main
  • in suites: squeeze
  • size: 22,504 kB
  • ctags: 13,661
  • sloc: cpp: 125,507; ansic: 5,544; python: 426; makefile: 102; sh: 26
file content (358 lines) | stat: -rw-r--r-- 22,310 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
<chapter id="introduction">
<title>Introduction</title>

<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract.  Don't include a
revision history. (see installation appendix comment) -->

<sect1 id="sec-qtiplot-intro">
<title>What &appname; does</title>

<para>&appname; is a program for two- and three-dimensional graphical presentation of data sets and for data analysis. The plots can be produced from data sets stored in <link linkend="sec-intro-table">tables</link> or from analytical functions.</para>
<para>The projet has been created by &ion; in 2000, and he was the only programmer between 2000 and 2005. Since 2006, new contributors have joined Ion and the project is hosted by <ulink url="www.berlios.de/projects/qtiplot/">BerliOS Developper</ulink>. The software aims to be a tool for analysis and graphical representation of data in the way of commercial software like Origin.</para>

<para>&appname; is a dynamic tool, the plots created from data sets and the spreadsheets owing the data are interconected. When the spreadsheets are modified, all the objects in the depending plots (curves, axes scales, legends) are automatically updated. For example, deleting a spreadsheet or only some columns will automatically remove all the corresponding curves from the depending plots.</para>

<para>All settings of a complete set of tables, matrix and plots can be saved in project files, having the extention ".qti". These project files may be opened using the <link linkend="specify-a-file">command line</link>, or using the <link linkend="sec-file-menu">File menu</link>, or by using the <emphasis>Open project</emphasis> icon from the <link linkend="sec-file-toolbar">File toolbar</link>.</para>

<para>The plots can be exported to several graphic formats such as JPEG or png and inserted as images in documents or presentations.</para>

<para>Data analysis operations (integration, interpolation, FFT, curve fitting, etc...) can be performed on the curves in a 2D plot via the Analysis menu. The results of all these operations are also stored in the project files. They can be visualized at any moment using the &results-log-lnk; and can be deleted from the project file via the &clear-log-lnk;.</para>

<para>When the application is launched, a new untitled project file is created consisting of a grey main window
(the workspace) which may contains an empty window, depending on your preferences. The type of the initial
window can be customized using the <link linkend="preferences-dialog">Preferences dialog</link>. It may be a table, a matrix,
a note or an empty 2D graph window. In order to be operational, the workspace must
be populated with tables storing data sets, either by creating empty tables/matrices first (&new-table-lnk;)
and then filling them with data, or by importing ASCII files (&import-ascii-lnk;),
which automatically creates new tables.</para>

<para>The user can easily navigate through the objects of a project file using the project explorer or the Windows menu. The project explorer also allows the user to perform various operations on the windows (tables and plots) in the workspace: hiding, minimazing, closing, renaming, printing, etc...</para>

</sect1>

<sect1 id="command-line-options">
<title>Command Line Parameters</title>
<sect2 id="specify-a-file">
	<sect2info><indexterm><primary>Command line parameters</primary><secondary>Specify a File</secondary></indexterm></sect2info>
<title>Specify a File</title>

<para>When starting &appname; from the command prompt, you can supply the name of a project file:</para>

<screen>
qtiplot file_name.&file-ext;
</screen>

<para>Other file formats are also accepted: <emphasis>.opj, .ogm, .ogw, .ogg</emphasis> for Origin projects, and <emphasis>.qti, qti.gz</emphasis> for &appname; projects.</para>
<para>The name can also refer to an ASCII file:</para>

<screen>
qtiplot ASCII_file_name
</screen>

<para> In this latter case a new "untitled" project will be created, containing a spreadsheet with the ASCII data in the file and a 2D plot of all columns as a function of the first column in the file.
You must take care of the format of the ASCII file because it will be read with the current values of the &import-ascii-lnk; dialog. These default values are:</para>
<itemizedlist>
  <listitem><para>the default field separator is ; but it can be changed in the &preferences-lnk; dialog,</para></listitem>
  <listitem><para>all lines are read,</para></listitem>
  <listitem><para>the first line is used to name the columns,</para></listitem>
  <listitem><para>the spaces at the end of the lines are not removed,</para></listitem>
  <listitem><para>the spaces are not simplified.</para></listitem>
</itemizedlist>

</sect2>

<sect2 id="qtiplot-options">
	<sect2info><indexterm><primary>Command line options</primary><secondary>Options</secondary></indexterm></sect2info>
<title>Command Line Options</title>

<para>Valid options are:</para>
<itemizedlist>
<listitem><para>-a or --about: show about dialog and exit</para></listitem>
<listitem><para>-c or --console: show standalone scripting window</para></listitem>
<listitem><para>-d or --default-settings: start &appname; with the default settings</para></listitem>
<listitem><para>-h or --help: show command line options</para></listitem>
<listitem><para>-l=XX or --lang=XX: start &appname; in language XX ('en', 'fr', 'de', ...)</para></listitem>
<listitem><para>-m or --manual: show &appname; manual in a standalone window</para></listitem>
<listitem><para>-v or --version: print &appname; version and release date</para></listitem>
<listitem><para>-x or --execute: execute the script file given as argument</para></listitem>
<listitem><para>-X: execute the script file given as argument without displaying the user interface.
Warning: 2D plots are not correctly handled in this functioning mode!</para></listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="general-concepts">
<title>General Concepts and Terms</title>
<para>Several plots and all the data related to these plots can be save in a <emphasis>project</emphasis> file, the project is therefore the main container of &appname;. The following screenshot gives an example of a typical session. This example shows the <link linkend="sec-intro-log-window">log panel</link> at the top of the workspace, the <link linkend="sec-intro-project-explorer">project explorer</link> at the bottom, a <link linkend="sec-intro-table">table</link> and a <link linkend="sec-intro-plot-window">plot window</link> are shown while other are docked or hidden.</para>

<figure id="fig-qtiplot-session">
  <title>A typical &appname; session</title>
  <mediaobject>
    <imageobject>
      <imagedata  format="PNG" fileref="pics/qtiplot-session.png"/>
    </imageobject>
  </mediaobject>
</figure>

<para>There are numerous commands available in &appname; depending on the element which is selected. Therefore, the main menu bar changes when you select a particular element of the project. Moreover, you can access to the set of commands relevant of an element by activating the context menu with the right button of the mouse.</para>
<para>In a project, the containers which can be used are:</para>

<variablelist>
  <varlistentry>
    <term><link linkend="sec-intro-table">A Table</link></term>
    <listitem>
      <indexterm><primary>table</primary></indexterm>
      <para>A table is a spreadsheet which can be used to store the datas you are entering.
      It can also be used to do some calculations and statistical analysis of datas.
      In each table, columns can be labelled as X-values or Y-values for 2D-plotting, or Z-values if you plan to build a
      3D-plot.</para>
      <para>A table can be created by the &new-table-lnk;. Then there are several ways to fill the table with your data.
      If you want to read a table from an ASCII file, you can import the data from the file to a table with the &import-ascii-lnk;. You can also enter each value from the keyboard. The last way to enter your data is to fill the table with the results of a mathematical function (&set-column-values-lnk; from the &table-menu-lnk;)</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><link linkend="sec-intro-matrix">A Matrix</link></term>
    <listitem>
      <indexterm><primary>matrix</primary></indexterm>
      <para>A matrix is a special table which is used to store the data points for surface 3D plots. It contains Z-values and doesn't include any column or row which could be designed as X-values or Y-values. Nevertheless, you can specify the X-values and the Y-values with the &set-dimensions-lnk; command from the &matrix-menu-lnk;.</para>
      <para>A matrix can be created by the &new-matrix-lnk;. If you want to read a matrix from an ASCII file, you can import the data of the file to a table with the &import-ascii-lnk; and then convert this table to a matrix with the &convert-to-matrix-lnk;. In the same way as for tables, you can also fill matrix with the results of a function z=(i,j) in which i and j are row and column numbers (&set-values-lnk; from the &matrix-menu-lnk;)</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><link linkend="sec-intro-plot-window">A Graph</link></term>
    <listitem>
      <indexterm>
        <primary>graph</primary>
      </indexterm>
      <para>A graph can contain one or several plots. Each of these plots is contained in a different <emphasis>layer</emphasis>, these layers can be arranged in many ways to build matrix of plots.</para>
      <para>A new layer can be added to an existing graph with the &add-layer-lnk; from the &graph-menu-lnk;. you can also remove an existing layer with the &remove-layer-lnk;, but if you remove a layer, the plot will be deleted. You can also copy a layer from one graph to another. You can also copy an existing graph into another, the window will be added as a new layer (see the section on <link linkend="sec-multilayer-plots">Multilayer Plots</link> for more details).</para>
      <para>Plots can be created in several ways. You can select data in tables or matrix and build a plot, or create new plots from functions of one or two variables (see sections <link linkend="sec-2d-plots">2D plots</link> and <link linkend="sec-3d-plots">3D plots</link>).</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><link linkend="sec-intro-note">A Note</link></term>
    <listitem>
      <para>This window is a text container which can simply be used to insert comments
      into a project, but is really far more powerfull than that.
      It can be used as a calculator, for executing single commands and for writing scripts.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><link linkend="sec-intro-log-window">The Log Window</link></term>
    <listitem>
      <para>This window is used to store the results of all the calculations which have been done. If this window is not visible, you can find it with the <link linkend="sec-intro-project-explorer">Project Explorer</link> or with the &results-log-lnk;.</para>
      <para>The text in the log window is also saved in the project file, so that when you load a previously saved project, the results-log panel is re-filled with the results of the calculations.</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><link linkend="sec-intro-project-explorer">The Project Explorer</link></term>
    <listitem>
      <para>This window is used to list all the windows contained in a projet. The <link linkend="project-explorer-dialog">Project Explorer</link> gives a quick access to all elements of a project, hidden or visibles. It can be used to do some operations on the windows related to these items such as hidding a window, renaming windows, etc.</para>
      <para>Since the version 0.8.5, a project file can include several independant projects. In this case, the containers of each project are stored in different folders.</para>
    </listitem>
  </varlistentry>
</variablelist>

<!--
		General description of a table
		==============================
-->
<sect2 id="sec-intro-table">
<title>Tables</title>

      <indexterm><primary>table</primary></indexterm>
<para>
The table is the main part of QtiPlot when working with data. For controlling and converting data the spreadsheet contains a highly customizable table: all colors and font preferences can be set using the &preferences-lnk; of the &view-menu-lnk;. You can resize a table in terms of rows and columns using the &table-menu-lnk; with &rows-lnk; or &columns-lnk;.
</para>

<figure id="fig-the-table">
  <title>The &appname; table</title>
  <mediaobject>
    <imageobject>
      <imagedata  format="PNG" fileref="pics/table.png"/>
    </imageobject>
  </mediaobject>
</figure>

<para> Every column of the table has a label and can be assigned a format: numeric, text, date or time. In a spreadsheet, columns can have the following flags: X, Y, Z, X-error, Y-error or can be simple columns without any special flag. The X columns are abscissae columns while the Y columns are ordinates columns used when creating a 2D plot from data. The X-error and Y-error columns can be used in order to add error bars to 2D plots. These flags can be changed using the <link linkend="column-options-dialog">Column options dialog</link>. To reach this dialog you simply have to double-click on the column label or to use the  &column-options-lnk; of the &table-menu-lnk;.</para>

<para> You can select all the columns of the spreadsheet (<keycode>Ctrl+A</keycode>) or only some of them by clicking on the column label while keeping the <keycode>Ctrl</keycode> key pressed, or by moving the mouse over the column label. This also allows you to deselect columns.</para>

<para> On the selected columns you can perform various operations: fill with data, normalize, sort, view statistics and finally make plots out of your data. All these functions can be reached by right clicking on the column label or by using the &table-menu-lnk;.</para>

<para> Any other spreadsheet function: rename, duplicate, export, print, close can be reached via the context menu (right click anywhere in the table outside the column labels area). </para>

<para> You can cut, copy and paste data between spreadsheets or between a spreadsheet and another application (Excel, Gnumeric, etc...).</para>

<para> You can import single or multiple ASCII files using the &import-ascii-lnk; from the &file-menu-lnk;. Of course you can export the data from the spreadsheet to a text file using the &export-ascii-lnk;.</para>

</sect2>

<!--
		General description of a matrix
		===============================
-->
<sect2 id="sec-intro-matrix">
<title>Matrix</title>

      <indexterm><primary>matrix</primary></indexterm>
<para>The matrix is a special table which is used for data depending on two variables.
This special table can be used to create 3D plots as well as 2D image/contour plots
via the &plot3d-menu-lnk; and the &plot3d-toolbar-lnk;.

The difference between a table and a matrix is that matrices have a dual functioning mode:
they can display data in a table form or they can display an image.

Therefore matrices can be used as a basic image viewer and also as an image editor,
since they implement some image manipulation funcions like: 90 degrees rotation, horizontal
and vertical mirroring, etc...</para>

<para>In matrices there is no special column
nor special row for X or Y labels or values. Nevertheless,
you can specify an X-scale and an Y-scale with the &set-dimensions-lnk;.</para>

<figure id="fig-matrix">
  <title>The &appname; matrix</title>
  <mediaobject>
    <imageobject>
      <imagedata  format="PNG" fileref="pics/matrix.png"/>
    </imageobject>
  </mediaobject>
</figure>

<para>The values which are stored in a matrix can be obtained from a function of the form
z=f(i, j, x, y) with the &set-values-lnk;,
i and j beeing the column and row numbers and x and y the corresponding coordinates.

They can also be read directly from an ASCII file with the &import-ascii-lnk; or from an image file.</para>

</sect2>

<!--
		General description of a plot window
		====================================
-->
<sect2 id="sec-intro-plot-window">
<title>Plot Window</title>

<para>The plot window is the one in which the graphic is plotted. It contains at least one layer, which is the main container of the plot window. Each new plot can be inserted in a new layer of this plot window, it has its own geometry and graphic properties (background color, frame, etc). The example presented below shows a graph with two layers which have different geometries.</para>

<figure id="fig-plot-window">
  <title>An example of &appname; 2D graph</title>
  <mediaobject>
    <imageobject>
      <imagedata  format="PNG" fileref="pics/plot-window.png"/>
    </imageobject>
  </mediaobject>
</figure>

<para>Each layer can be activated by clicking on the corresponding gray button  <inlinemediaobject><imageobject><imagedata format="PNG" fileref="pics/layer-button.png"/></imageobject></inlinemediaobject> in the top-left corner of the window.</para>

<para>The elements which can be accessed by a double click in a layer are:</para>

<itemizedlist>
<listitem>
<para>the graph itself: this will open the <link linkend="custom-curves-dialog">Custom Curve Dialog</link>. You can then add new curves to the plot, or change the way the curves are plotted.</para>
</listitem>
<listitem>
<para>The axes or the axes labels: this will open the <link linkend="plot-options-dialog">General Plot Options Dialog</link>. It is used to customize the axes, the numbers and labels of the axes, and the grid.</para>
</listitem>
<listitem>
<para>Text items, including the legend of the plot: this will open the <link linkend="text-options-dialog">Text Options Dialog</link> which allows to customize the font of the label and the frame in which it is drawn.</para>
</listitem>
<listitem>
<para>Arrow/Line items: this will open the <link linkend="arrow-dialog">Line Options Dialog</link>.</para>
</listitem>
<listitem>
<para>Image items: this will open a dialog allowing to customize the geometry and the position of the image.</para>
</listitem>
</itemizedlist>

<para>A left click on a plot element selects it. You can deselect any element by presing the <emphasis>Escape</emphasis> key.
A right click on a plot element pops-up a context menu allowing fast access to its properties dialog.
Last but not least, you should know that QtiPlot provides multiple selection for objects in a plot layer.
In order to add an object to an existing selection keep the <emphasis>Shift</emphasis>
key pressed and click on the element you want to add to the selection.
Elements in a multiple selection can be moved and resized together with the mouse.</para>

</sect2>

<!--
		General description of a note
		===========================================
-->
<sect2 id="sec-intro-note">
<title>Note</title>

<para>A note can simply be used to insert text (comments, notes, etc) into a project,
  but is really far more powerfull than that. It can be used as a calculator,
  for executing single commands and for writing scripts.
  Evaluation of mathematical expressions and execution of code is done via a note's context menu,
  the Scripting menu or the convenient keyboard shortcuts.
  For information on expression syntax, supported mathematical functions and how to write scripts,
  see <link linkend="scripting">here</link>.</para>

<figure id="fig-note-window">
  <title>The &appname; Note Window</title>
  <mediaobject>
    <imageobject>
      <imagedata  format="PNG" fileref="pics/new-note1.png"/>
    </imageobject>
  </mediaobject>
</figure>

<para>Note windows provide powerful text editor functionalities, particularly helpful
when writing scripts: customizable Python syntax highlighting, line numbers display, find and replace text,
autocompletion suggestions for words that have more than two characters.
You can trigger autocompletion using Ctrl+U. The colors used for syntax highlighting can be customized
via the <emphasis>Notes</emphasis> tab in the <link linkend="fig-preferences-dialog-notes">Preferences dialog</link>.</para>
</sect2>

<!--
		General description of the log window
		=====================================
-->
<sect2 id="sec-intro-log-window">
<title>Log Window</title>

<para>This window keeps a history of all analysis which have been done in the project. This panel contains the results of all the correlations, fittings, etc.</para>

<figure id="fig-log-window">
  <title>The &appname; Log window</title>
  <mediaobject>
    <imageobject>
      <imagedata  format="PNG" fileref="pics/log-window.png"/>
    </imageobject>
  </mediaobject>
</figure>
</sect2>

<!--
		General description of the project explorer
		===========================================
-->
<sect2 id="sec-intro-project-explorer">
<title>The Project Explorer</title>

<para>The project explorer can be opened/closed using the &project-explorer-lnk; from the &view-menu-lnk; or by clicking on the &project-explorer-icon; in the <link linkend="sec-file-toolbar">file toolbar</link>.</para>

<figure id="fig-project-explorer">
  <title>The &appname; Project Explorer</title>
  <mediaobject>
    <imageobject>
      <imagedata  format="PNG" fileref="pics/explorer1.png"/>
    </imageobject>
  </mediaobject>
</figure>

<para>It gives an overview of the structure of a project and allows the user to perform various operations on the windows (tables and plots) in the workspace: hiding, minimazing, closing, renaming, printing, etc... These functions can be reached via the context menu, by right-clicking on an item in the explorer.</para>
<para>By double-clicking on an item, the corresponding window is shown maximized in the workspace, even if it was hidden before.</para>
<para>You can organize the differents objects in folders. When selecting a folder, the default policy is that only the objects contained in it will be showed in the workspace window. You can also display all the objects in the subfolders if you change this policy with the "View Windows" command to "Windows in Active Folder and Subfolders".</para>

</sect2>

</sect1>

</chapter>