## "Fossies" - the Fresh Open Source Software Archive

### Member "scidavis-2.3.0/doc/introduction.tex" (12 Jun 2020, 25891 Bytes) of package /linux/misc/scidavis-2.3.0.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 \chapter{Introduction}
2
3 %The introduction chapter contains a brief introduction for the
4 %application that explains what it does and where to report
5 %problems. Basically a long version of the abstract.  Don't include a
6 %revision history. (see installation appendix comment)
7
8 \label{sec-scidavis-intro}
9 \section{What is \SciDaVis?}
10
11 \SciDaVis{} stands for {\em Sci}entific {\em D}ata {\em A}nalysis and
12          {\em Vis}ualization. It is a free cross-platform program for
13          two- and three-dimensional graphical presentation of data
14          sets and for data analysis. The plots can be produced from
15          data sets stored in \htmlref{tables}{sec-intro-table}, in
16          \htmlref{matrix}{sec-intro-matrix} or from analytical
17          functions.
18
19 The \SciDaVis{} project started as a fork of QtiPlot with the aim of
20 introducing some changes in design as well as project structure. The
21 QtiPlot development was initiated in 2004 by Ion Vasilief. He was the
22 only programmer until May 2006 when Knut Franke and Tilman Hoener zu
23 Siederdissen joined the project. Not much later, Roger Gadiou
24 officially joined as the main documentation writer. In June 2007,
25 insuperable disagreements among the developers lead to the fork and
26 the creation of the \SciDaVis{} project by Knut and Tilman, soon
27 followed by Roger. In November 2012, after approximately two years of
28 inactivity in the project, Russell Standish assumed the development of
29 \SciDaVis. The project is hosted partially at
32 its source code development was moved from the \SciDaVis{} subversion
33 repository to
35 June 2015.
36
37 \SciDaVis{} aims to be a tool for analysis and graphical
38 representation of data, allowing powerfull mathematical treatment and
39 visualization of scientific data while keeping a user-friendly
40 graphical user interface. Another keypoint for the \SciDaVis{} project
41 is to be a multi-system software, it should work on Windows, Linux,
42 and OS-X systems.
43
44 \SciDaVis{} is a dynamic tool, the plots created from data sets and
45 the spreadsheets owing the data are interconected. When the
46 spreadsheets are modified, all the objects in the depending plots
47 (curves, axes scales, legends) are automatically updated. For example,
48 deleting a spreadsheet or only some columns will automatically remove
49 all the corresponding curves from the depending plots.
50
51 All settings of a complete set of tables, matrix and plots can be
52 saved in project files, having the extention .sciprj". These project
53 files may be opened using the \htmlref{command line}{specify-a-file},
55 \icon{fileopen.png} icon from the \htmlref{File
56   toolbar}{file-toolbar-lnk}.
57
58 The plots can be exported to several graphic formats such as JPEG or
59 PNG and inserted as images in documents or presentations.
60
61 Data analysis operations (integration, interpolation, FFT, curve
62 fitting, etc) can be performed on the curves in a 2D plot via the
64 all these operations are also stored in the project files. They can be
65 visualized at any moment using the \htmlref{Results Log command}{results-log-lnk} and can be
66 deleted from the project file via the \htmlref{Clear Log Information command}{clear-log-information-lnk}.
67
68 When the application is launched, a new project file is created
69 consisting of a grey main window (the workspace) which contains an
70 empty table. In order to be operational, this workspace must be
71 populated with tables storing data sets, either by creating empty
72 tables first (\htmlref{New $\rightarrow$ New Table
73   command}{new-table-lnk}) and then filling them with data, or by
74 importing ASCII files (\htmlref{Import ASCII
75   command}{import-ascii-lnk}), which automatically creates new tables.
76
77 The user can easily navigate through the objects of a project file
78 using the \htmlref{Project Explorer command}{project-explorer-lnk} or
80 also allows the user to perform various operations on the windows
81 (tables and plots) in the workspace: hiding, minimazing, closing,
82 renaming, printing, etc.
83
84 %************************************************************************
85 %
86 %           Command line parameters
87 %
88 %************************************************************************
89 \section{Command Line Parameters}\label{command-line-options}
90
91 \subsection{Specify a File}\label{specify-a-file}
92 \index{Command line parameters!Specify a File}
93
94 When starting \SciDaVis{} from the command prompt, you can supply the name of a project file:
95
96 \begin{verbatim}
97 scidavis file_name.sciprj
98 \end{verbatim}
99
100 Other file format are also accepted: {\em .opj, .ogm, .ogw, .ogg} for
101 Origin projects, and {\em .qti, qti.gz} for Qtiplot projects.
102
103 The name can also refer to an ASCII file:
104
105 \begin{verbatim}
106 scidavis ASCII_file_name
107 \end{verbatim}
108
109 In this latter case a new untitled" project will be created,
110 containing a spreadsheet with the ASCII data in the file and a 2D plot
111 of all columns as a function of the first column in the file. You must
112 take care of the format of the ASCII file because it will be read with
113 the current parameters of the \htmlref{Import ASCII
114   command}{import-ascii-lnk} dialog. The default values are:
115
116 \begin{itemize}
117   \item the default field separator is ; but it can be changed in the
118     \htmlref{Preferences command}{preferences-lnk} dialog,
119   \item all lines are read,
120   \item the first line is used to name the columns,
121   \item the spaces at the end of the lines are not removed,
122   \item the spaces are not simplified.
123 \end{itemize}
124
125 \subsection{Command Line Options}\label{scidavis-options}
126 \index{Command line parameters!Options}
127
128 Valid options are:
129 \begin{itemize}
131 \item \verb+-h+ or \verb+--help+: show command line options
132 \item \verb+-l=XX+ or \verb+--lang=XX+: start \SciDaVis; in language XX (en', fr', de', \ldots)
133 \item \verb+-m+ or \verb+--manual+: show \SciDaVis{} manual in a standalone window
134 \item \verb+-v+ or \verb+--version+: print \SciDaVis{} version and release date
135 \item \verb+-x+ or \verb+--execute+: execute the script file given as argument
136 \end{itemize}
137
138 %**************************************************************************
139 %
140 %           General concepts and terms
141 %
142 %**************************************************************************
143
144 \section{General Concepts and Terms}\label{general-concepts}
145 Several plots and all the data related to these plots can be save in a
146 {\em project} file, the project is therefore the main container of
147 \SciDaVis. The following screenshot gives an example of a typical
148 session. This example shows the \htmlref{log
149   panel}{sec-intro-log-window} at the top of the workspace, the
150 \htmlref{project explorer}{sec-intro-project-explorer} at the bottom,
151 a \htmlref{table}{sec-intro-table} and a \htmlref{plot
152   window}{sec-intro-plot-window} are shown while other are docked or
153 hidden.
154
155 \begin{figure}
156   \resizebox{\textwidth}{!}{\includegraphics{pics/scidavis-session.png}}
157   \caption{A typical \SciDaVis{} session}
158   \label{fig-scidavis-session}
159 \end{figure}
160
161 There are numerous commands available in \SciDaVis{} depending on the
162 element which is selected. Therefore, the main menu bar changes when
163 you select a particular element of the project. Moreover, you can
164 access to the set of commands relevant of an element by activating the
165 context menu with the right button of the mouse.
166
167 In a project, the objects which can be used are:
168
169 \begin{description}
170   \item[Tables]\index{Table}
171     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. In addition, columns can be labelled as errors on X or on Y values (see \htmlref{Set Column as command}{set-column-as-lnk}).
172
173     A table can be created by the \htmlref{New $\rightarrow$ New Table
174       command}{new-table-lnk}. Then there are several ways to fill the
175     table with your data. If you want to read a table from an ASCII
176     file, you can import the data from the file to a table with the
177     \htmlref{Import ASCII command}{import-ascii-lnk}. You can also
178     enter each value from the keyboard, or copy and paste from another
179     spreadsheet program. The last way to enter your data is to fill
180     the table with the results of a mathematical function
181     (\htmlref{Assign Formula command}{assign-formula-lnk} from the
183
184     \item[Matrix]\index{Matrix} A matrix is a
185       special table which is used to store the data points for surface
186       3D plots. It contains Z-values and doesn't include any column or
187       row which could be designated as X-values or
188       Y-values. Nevertheless, you can specify the X-values and the
189       Y-values with the \htmlref{Set Coordinates
190         command}{set-coordinates-lnk} from the \htmlref{Matrix
192
193       A matrix can be created by the \htmlref{New$\rightarrow$ New
194         Matrix command}{new-matrix-lnk}. If you want to read a matrix
195       from an ASCII file, you can import the data of the file to a
196       table with the \htmlref{Import ASCII command}{import-ascii-lnk}
197       and then convert this table to a matrix with the \htmlref{Conver
198         to Matrix command}{convert-to-matrix-lnk}. In the same way as
199       for tables, you can also fill matrix with the results of a
200       function $z=f(i,j)$ in which $i$ and $j$ are row and column numbers,
201       or $z=f(x,y)$. (see \htmlref{Assign Formula
202         command}{assign-formula-lnk} from the \htmlref{Matrix
204
205     \item[A Graph]\index{Plot} A graph
206       can contain one or several plots. Each of these plots is
207       contained in a different {\em layer}, these layers can be
208       arranged in many ways to build matrix of plots.
209
210       A new layer can be added to an existing graph with the
213       existing layer with the \htmlref{Remove Layer
214         command}{remove-layer-lnk}, but if you remove a layer, the
215       plot will be deleted. You can also copy a layer from one graph
216       to another, or copy an existing graph into another, the window
217       will be added as a new layer (see the section on
218       \htmlref{Multilayer Plots}{sec-multilayer-plots} for more
219       details).
220
221       Plots can be created in several ways. You can select data in
222       tables or matrix and build a plot, or create new plots from
223       functions of one or two variables (see sections \htmlref{2D
224         plots}{sec-2d-plots} and \htmlref{3D plots}{sec-3d-plots}).
225
226     \item[A Note] This window is a text
227       container which can simply be used to insert comments into a
228       project. This object is nevertheless far more powerfull than
229       that: it can be used as a calculator, for executing single
230       commands and for writing scripts (see the \htmlref{Scripting
231         section}{scripting} for more details).
232
233     \item[The Log Window]
234       This window is used to store the results of all the calculations
235       which have been done. If this window is not visible, you can
236       find it with the \htmlref{Project
237         Explorer}{sec-intro-project-explorer} or with the
238       \htmlref{Result Log command}{results-log-lnk}.
239
240       The text in the log window is also saved in the project file, so
241       that when you load a previously saved project, the results-log
242       panel is re-filled with the results of the calculations.
243
244     \item[The Project Explorer]
245       This window is used to list all the windows contained in a
246       project. The Project Explorer is opened by the \htmlref{Project
247         Explorer command}{project-explorer-lnk}, and gives a quick
248       access to all elements of a project, hidden or visibles. It can
249       be used to do some operations on the windows related to these
250       items such as hiding a window, renaming windows, etc.
251
252       A project file can include several independant projects. In this case,
253       the containers of each project are stored in different folders.
254
255 \end{description}
256 %       General description of a table
257 %       ==============================
258
259 \subsection{Tables}\label{sec-intro-table}
260 \index{Table}
261
262 The table is the main part of \SciDaVis{} when working with data. For
263 controlling and converting data the spreadsheet contains a highly
264 customizable table: all colors and font preferences can be set using
265 the \htmlref{Preferences command}{preferences-lnk} of the \htmlref{Edit
267 in terms of rows and columns using the \htmlref{Dimensions command}{table-dimensions-lnk} command
268 of the \htmlref{Table menu}{table-menu-lnk}. On the left side of the table, the button can
269 be used to develop the properties tags. This allows to customize the
270 main parameters of the table.
271
272 \begin{figure}
273   \resizebox{\textwidth}{!}{\includegraphics{pics/table.png}}
274   \caption{A \SciDaVis{} table with the properties dialog developped
275     and the type tag selected.}
276   \label{fig-the-table}
277 \end{figure}
278
279 In a spreadsheet, columns can have the following flags: X, Y, Z,
280 X-error, Y-error or can be simple columns without any special
281 flag. The X columns are abscissae columns while the Y columns are
282 ordinates columns used when creating a 2D plot from data. The X-error
283 and Y-error columns can be used in order to add error bars to 2D
284 plots. These flags can be changed using the \htmlref{Set Column as
285   command}{set-column-as-lnk}.
286
287 \index{Table!Number format}
288
289 The tag which is selected in figure \ref{fig-the-table} is used to
290 assign a type to columns: numeric, text, date or time. The format used
291 to display the data can then be chosen, the format in tables is not
292 used for plots (use the \htmlref{Axes command}{format-axes-lnk} to
293 define display format for axes labels).
294
295 \begin{figure}
296   \resizebox{\textwidth}{!}{\includegraphics{pics/table_tag_1_3.png}}
297   \caption{The two other tags of the properties dialog of \SciDaVis{} tables.}
298   \label{fig-the-table_2}
299 \end{figure}
300
301 \index{Table!Labels}
302
303 Every column of the table has a label, this can be defined in the
304 description tag (figure \ref{fig-the-table_2}). This label will be
305 used by default in plots for curve selection and legend display. You
306 can use complex labels with spaces and special characters like Vol
307 (cc/g)" if needed. This command can also be reached by the
308 \htmlref{Edit Column Description command}{edit-column-description-lnk}
310
311 \index{Table!Assign formula}
312
313 The last tag of the properties dialog correspond to the command
314 \htmlref{Assign Formula command}{assign-formula-lnk} of the
315 \htmlref{Table menu}{table-menu-lnk} (figure \ref{fig-the-table_2}). It is used to fill the column with the result of a mathematic expression. Refer to the \htmlref{Assign Formula command}{assign-formula-lnk} for more details.
316
317 You can select all the columns of the spreadsheet (\verb|Ctrl+A|) or
318 only some of them by clicking on the column label while keeping the
319 \verb+Ctrl+ key pressed, or by moving the mouse over the column
320 label. This also allows you to deselect columns.
321
322 On the selected columns you can perform various operations:
323
324 \begin{itemize}
325 \item Fill with data. You can insert the row numbers (\htmlref{Fill
326   Selection With$\rightarrow$Row Numbers
327   command}{fill-selection-with-row-number-lnk}), random numbers
328   (\htmlref{Fill Selection With$\rightarrow$Random
329   Values}{fill-selection-with-random-values-lnk}), or the result of a
330   function (\htmlref{Assign Formula command}{assign-formula-lnk});
331 \item\index{table!normalize columns} normalize columns with the \verb+Normalize Columns+ command of the context menu;
332 \item\index{table!sort columns}  sort columns with the \htmlref{Sort
333   Table command}{sort-table-lnk} of the \htmlref{Table
336 \item compute statistical data on columns and rows with the
337   \htmlref{Statistics on Columns command}{statistics-on-columns-lnk}
338   and \htmlref{Statistics on Rows command}{statistics-on-rows-lnk}
340 \item build a plot from selected columns with the \verb+plot+ command
342 \end{itemize}
343
344 All these functions can be reached by right clicking when a column is
345 selected. Most of them can also be reached by using the \htmlref{Table
347
348 You can cut, copy and paste data between spreadsheets or between a
349 spreadsheet and another application (Excel, Gnumeric, OpenOffice Calc,
350 etc).
351
352 You can import single or multiple ASCII files using the
353 \htmlref{Import ASCII command}{import-ascii-lnk} from the
355 tables. You can also export the data from the spreadsheet to a text
356 file using the \htmlref{Export ASCII command}{export-ascii-lnk}.
357
358 %       General description of a matrix
359 %       ===============================
360 \subsection{Matrix}\label{sec-intro-matrix}\index{Matrix}
361
362 The matrix is a special table which is used for data which depends on
363 two variables. This special table is used to store data for
364 3D-plots. The difference between a table and a matrix is that there is
365 that columns are assigned to the abscissae x while rows define
366 abscissae y.
367
368 The defaut size of a matrix is $32\times32$ cells. You can modify this size
369 with the \htmlref{Dimensions command}{matrix-dimensions-lnk}. Column and row numbers are named $i$
370 and $j$ respectively, ranging from 1 to the size of the matrix. You can
371 specify an X-scale and an Y-scale with the \htmlref{Set Coordonates command}{set-coordinates-lnk}, this
372 define values of $x$ and $y$ for columns and rows (figure
373 \ref{fig-matrix}).
374
375 \begin{figure}
376   \resizebox{\textwidth}{!}{\includegraphics{pics/matrix.png}}
377   \caption{The \SciDaVis{} matrix.}
378   \label{fig-matrix}
379 \end{figure}
380
381
382 The values which are stored in a matrix can be obtained from a
383 function of the form $z=f(i,j)$ or $z=f(x,y)$ with the \htmlref{Assign
384   Formula command}{assign-formula-lnk}. They can also be read from a
385 file with the \htmlref{Import ASCII command}{import-ascii-lnk} which
386 inserts the file data into a table, and then the table can be
387 converted to a matrix with the \htmlref{Convert to Matrix
388   command}{convert-to-matrix-lnk} of the \htmlref{Matrix
390
391 As in the case of tables, a property tag can be shown or hidden by
392 clicking on the vertical button on the right.
393
394 Through the \htmlref{Matrix menu}{matrix-menu-lnk}, several operations can be done on a
395 matrix like transposition (\htmlref{Transpose command}{transpose-lnk}), mirroring
396 (\htmlref{Mirror Horizontally command}{mirror-horizontally-lnk} and
397 \htmlref{Mirror Vertically command}{mirror-vertically-lnk}), inversion
398 (\htmlref{Invert command}{invert-lnk}), computation of the determinant
399 (\htmlref{Determinant}{determinant-lnk}). The data of a matrix can then be used to build a
400 3D plot with the commands present in the \htmlref{plot3d menu}{plot3d-menu-lnk} and in
401 the \htmlref{3D surface toolbar}{d3-surface-toolbar-lnk}.
402
403 %
404 %</sect2>
405 %
406 %<!--
407 %       General description of a plot window
408 %       ====================================
409 %-->
410
411 \subsection{Plot Window}\label{sec-intro-plot-window}\index{Plot}\index{Plot!Layer}
412
413 The plot window is the one in which the graphic is plotted. The main
414 container of the plot window is the layer. You can have several layers
415 in a plot, which may be arranged as you want. Each layer can contain a
416 plot, or another item like a label.
417
418 Each new plot can be inserted in a new layer of this plot window, it
419 has its own geometry and graphic properties (background color, frame,
420 etc). The figure \ref{fig-plot-window} shows a graph with two layers
421 which have different geometries. Inside a layer, the area in which the
422 curves are plotted is the {\em canvas}.
423
424 \begin{figure}
425   \resizebox{\textwidth}{!}{\includegraphics{pics/plot-window.png}}
426   \caption{An example of \SciDaVis{} 2D graph with 2 layers.}
427   \label{fig-plot-window}
428 \end{figure}
429
430 Each layer can be activated by clicking on the corresponding gray
431 button  \icon{layer-button.png} in
432 the top-left corner of the window. The elements which can be accessed
433 by a double click in a layer are:
434
435 %
436 %<itemizedlist>
437 %<listitem>
438 \begin{itemize}
439 \item the graph itself: this will open the \htmlref{Plot
440   details}{format-plot-cmd} dialog box. You can then change the way
441   the curves are plotted.
442
443 \item The axes or the axes labels: this will open the \htmlref{General
444   Plot Options Dialog}{format-axes-cmd}. It is used to customize the
445   axes, the numbers and labels of the axes, and the grid.
446
447 \item Any other text item: this will open the \htmlref{Text
448   Dialog}{sec-adding-text} which allows to customize the font of the
449   label and the frame in which it is drawn.
450 \end{itemize}
451
452 All these functions can be reached through the \htmlref{Format
454
455 %<!--
456 %       General description of a note
457 %       =============================
458 %-->
459 \subsection{Note}\label{sec-intro-note}
460 \index{Note}
461 A note can simply be used to insert text (comments, notes, etc) into a
462 project, but is really far more powerfull than that. It can be used as
463 a calculator, for executing single commands and for writing scripts.
464
465 \begin{figure}
466   \resizebox{\textwidth}{!}{\includegraphics{pics/new-note1.png}}
467   \caption{The \SciDaVis{} Note Window.}
468   \label{fig-note-window}
469 \end{figure}
470
471 You can also change the text input method. {\em Simple Composing
472 Input Method} is the standard method to enter text in QT
473 applications. {\em Xim} is the X input method, it is
474 the legacy system of the X window environment to support localized
475 text input. The default choice is the second one, it allows to enter
476 special characters and accents from your localised environment.
477
478 \index{Calculator}
479 The second use of notes is calculator. The evaluation of mathematical
480 expressions and execution of code is done via a note's context menu,
481 the Scripting menu or the convenient keyboard shortcuts. In figure
482 \ref{fig-note-window-1},
483 it is shown that you just need to place the cursor on an expression
484 and use the {\tt Ctrl-Return} command to evaluate the
485 expression.
486
487 \begin{figure}
488   \resizebox{\textwidth}{!}{\includegraphics{pics/new-note2.png}}
489   \caption{The \SciDaVis{} Note Window used as a calculator.}
490   \label{fig-note-window-1}
491 \end{figure}
492
493 you can define variables and refer to them to build complex
494 expressions, but you must evaluate each line with the
495 {\tt Ctrl-Return} command to fill the variable with its
496 value. All variable are private to the note in which it is defined,
497 and you can't refer to it in another note. With a right click, you
499 mathematical functions.
500
501 For information on expression syntax, supported mathematical functions and how to write scripts, see the \htmlref{scripting section}{scripting}.
502 %<!--
503 %       General description of the log window
504 %       =====================================
505 %-->
506 \subsection{Log Window}\label{sec-intro-log-window}
507
508 \index{Log Window}
509 \index{Analysis!Results}
510
511 This window keeps a history of all analysis which have been done in
512 the project. This panel contains the results of all the correlations,
513 fittings, etc. It can be shown or hidden with the \htmlref{Results Log
515
516 \begin{figure}
517   \resizebox{\textwidth}{!}{\includegraphics{pics/log-window.png}}
518   \caption{The \SciDaVis{} Log window with the information related to a fit on a curve.}
519   \label{fig-log-window}
520 \end{figure}
521
522
523 You can clear the content of the log window with the command
526 which some analysis has been done, the computations will be done again
527 and the log window will be filled with the results.
528 %<!--
529 %       General description of the project explorer
530 %       ===========================================
531 %-->
532
533 \subsection{The Project Explorer}\label{sec-intro-project-explorer}
534 \index{Project Explorer}
535
536 The project explorer can be opened/closed using the \htmlref{Project
537   Explorer command}{project-explorer-lnk} from the \htmlref{View
539   icon}{project-explorer-icon} in the \htmlref{file toolbar}{sec-file-toolbar}.
540
541
542 \begin{figure}
543   \resizebox{\textwidth}{!}{\includegraphics{pics/explorer1.png}}
544   \caption{The \SciDaVis{} Project Explorer.}
545   \label{fig-project-explorer}
546 \end{figure}
547
548
549 It gives an overview of the structure of a project and allows the user
550 to perform various operations on the windows (tables and plots) in the
551 workspace: hiding, minimazing, closing, renaming, printing,
552 etc\ldots{} These functions can be reached via the context menu, by
553 right-clicking on an item in the explorer.
554
555 By double-clicking on an item, the corresponding window is shown
556 maximized in the workspace, even if it was hidden before.
557
558 You can organize the differents objects in folders. When selecting a
559 folder, the default policy is that only the objects contained in it
560 will be showed in the workspace window. You can also display all the
561 objects in the subfolders if you change this policy with the View
562 Windows'' command to Windows in Active Folder and Subfolders''.
563
564
`