"Fossies" - the Fresh Open Source Software Archive

Member "veusz-3.1/Documents/manual/html/introduction.html" (26 Oct 2019, 46843 Bytes) of package /linux/privat/veusz-3.1.tar.gz:

The requested HTML page contains a <FORM> tag that is unusable on "Fossies" in "automatic" (rendered) mode so that page is shown as HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    3   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    5 <html xmlns="http://www.w3.org/1999/xhtml">
    6   <head>
    7     <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    8     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    9     <title>Introduction &#8212; Veusz 3.1 documentation</title>
   10     <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
   11     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
   12     <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
   13     <script type="text/javascript" src="_static/jquery.js"></script>
   14     <script type="text/javascript" src="_static/underscore.js"></script>
   15     <script type="text/javascript" src="_static/doctools.js"></script>
   16     <script type="text/javascript" src="_static/language_data.js"></script>
   17     <link rel="index" title="Index" href="genindex.html" />
   18     <link rel="search" title="Search" href="search.html" />
   19     <link rel="next" title="Reading data" href="datasets.html" />
   20     <link rel="prev" title="Veusz documentation" href="index.html" />
   22   <link rel="stylesheet" href="_static/custom.css" type="text/css" />
   24   <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
   26   </head><body>
   29     <div class="document">
   30       <div class="documentwrapper">
   31         <div class="bodywrapper">
   32           <div class="body" role="main">
   34   <div class="section" id="introduction">
   35 <h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h1>
   36 <div class="section" id="veusz">
   37 <h2>Veusz<a class="headerlink" href="#veusz" title="Permalink to this headline"></a></h2>
   38 <p>Veusz is a 2D and 3D scientific plotting package. It is designed to be
   39 easy to use, easily extensible, but powerful. The program features a
   40 graphical user interface (GUI), which works under Unix/Linux, Windows
   41 or Mac OS. It can also be easily scripted (the saved file formats are
   42 similar to Python scripts) or used as module inside Python. Veusz
   43 reads data from a number of different types of data file, it can be
   44 manually entered, or constructed from other datasets.</p>
   45 <p>In Veusz the document is built in an object-oriented fashion, where a
   46 document is built up by a number of widgets in a hierarchy. For
   47 example, multiple function or xy widgets can be placed inside a graph
   48 widget, and many graphs can be placed in a grid widget. The program
   49 also supports a variety of 3D plots, including 3D point and surface
   50 plots. The program produces vector rather than rastered 3D output.</p>
   51 <p>Veusz can be extended by the user easily by adding plugins. Support
   52 for different data file types can be added with import
   53 plugins. Dataset plugins automate the manipulation of datasets. Tools
   54 plugins automate the manipulation of the document.</p>
   55 </div>
   56 <div class="section" id="installation">
   57 <h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline"></a></h2>
   58 <p>Please go to the <a class="reference external" href="https://veusz.github.io/">website</a> of Veusz to learn more about the
   59 program. Links to binaries, distribution packages and the source
   60 package can be found in <a class="reference external" href="https://veusz.github.io/download/">downloads</a>. For source installation, please
   61 see the package INSTALL.</p>
   62 </div>
   63 <div class="section" id="getting-started">
   64 <h2>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline"></a></h2>
   65 <p>Veusz includes a built-in tutorial which starts the first time the
   66 program is run. You can rerun it later from the Help menu. It also
   67 includes many <a class="reference external" href="https://veusz.github.io/examples/">examples</a>, to show how certain kinds of plots are
   68 produced. For more help and link to a video tutorial, see <a class="reference external" href="https://veusz.github.io/help-support/">help</a>.</p>
   69 </div>
   70 <div class="section" id="terminology">
   71 <h2>Terminology<a class="headerlink" href="#terminology" title="Permalink to this headline"></a></h2>
   72 <p>Here we define some terminology for future use.</p>
   73 <div class="section" id="widget">
   74 <h3>Widget<a class="headerlink" href="#widget" title="Permalink to this headline"></a></h3>
   75 <p>A document and its graphs are built up from widgets.  These widgets
   76 can often by placed within each other, depending on the type of the
   77 widget. A widget has children (those widgets placed within it) and its
   78 parent. The widgets have a number of different settings which modify
   79 their behaviour. These settings are divided into properties, which
   80 affect what is plotted and how it is plotted. These would include the
   81 dataset being plotted or whether an axis is logarithmic.  There are
   82 also formatting settings, including the font to be used and the line
   83 thickness. In addition they have actions, which perform some sort of
   84 activity on the widget or its children, like “fit” for a fit widget.</p>
   85 <p>As an aside, using the scripting interface, widgets are
   86 specified with a “path”, like a file in Unix or Windows. These
   87 can be relative to the current widget (do not start with a
   88 slash), or absolute (start with a slash). Examples of
   89 paths include, <cite>/page1/graph1/x</cite>, <cite>x</cite> and <cite>.</cite>.</p>
   90 <p>The widget types include</p>
   91 <ol class="arabic">
   92 <li><p class="first"><strong class="command">document</strong> - representing a complete document. A document
   93 can contain pages. In addition it contains a setting giving the
   94 page size for the document.</p>
   95 </li>
   96 <li><p class="first"><strong class="command">page</strong> - representing a page in a document. One or more
   97 graphs can be placed on a page, or a grid.</p>
   98 </li>
   99 <li><p class="first"><strong class="command">graph</strong> - defining an actual graph. A graph can be placed
  100 on a page or within a grid. Contained within the graph are its axes
  101 and plotters. A graph can be given a background fill and a border
  102 if required. It also has a margin, which specifies how far away
  103 from the edge of its parent widget to plot the body of the graph.
  104 A graph can contain several axes, at any position on the plot. In
  105 addition a graph can use axes defined in parent widgets, shared
  106 with other graphs.  More than one graph can be placed within in a
  107 page. The margins can be adjusted so that they lie within or
  108 besides each other.</p>
  109 </li>
  110 <li><p class="first"><strong class="command">grid</strong> - containing one or more graphs. A grid plots
  111 graphs in a gridlike fashion. You can specify the number of rows
  112 and columns, and the plots are automatically replotted in the
  113 chosen arrangement. A grid can contain graphs or axes. If an axis
  114 is placed in a grid, it can be shared by the graphs in the grid.</p>
  115 </li>
  116 <li><p class="first"><strong class="command">axis</strong> - giving the scale for plotting data. An axis
  117 translates the coordinates of the data to the screen. An axis can
  118 be linear or logarithmic, it can have fixed endpoints, or can
  119 automatically get them from the plotted data. It also has settings
  120 for the axis labels and lines, tick labels, and major and minor
  121 tick marks.  An axis may be “horizontal” or “vertical” and can
  122 appear anywhere on its parent graph or grid.  If an axis appears
  123 within a grid, then it can be shared by all the graphs which are
  124 contained within the grid.  The <strong class="command">axis-broken</strong> widget is an
  125 axis sub-type. It is an axis type where there are jumps in the
  126 scale of the axis.  The <strong class="command">axis-function</strong> widget allows the
  127 user to create an axis where the values are scaled by a monotonic
  128 function, allowing non-linear and non-logarithmic axis scales. The
  129 widget can also be linked to a different axis via the function.</p>
  130 </li>
  131 <li><p class="first">plotters - types of widgets which plot data or add other things on
  132 a graph. There is no actual plotter widget which can be added, but
  133 several types of plotters listed below. Plotters typically take an
  134 axis as a setting, which is the axis used to plot the data on the
  135 graph (default x and y).</p>
  136 <ol class="arabic simple">
  137 <li><strong class="command">function</strong> - a plotter which plots a function on the
  138 graph. Functions can be functions of x or y (parametric
  139 functions are not done yet!), and are defined in Python
  140 expression syntax, which is very close to most other
  141 languages. For example <cite>3*x**2 + 2*x - 4</cite>. A number of functions
  142 are available (e.g. sin, cos, tan, exp, log…). Technically,
  143 Veusz imports the numpy package when evaluating, so numpy
  144 functions are available.  As well as the function setting, also
  145 settable is the line type to plot the function, and the number
  146 of steps to evaluate the function when plotting. Filling is
  147 supported above/below/left/right of the function.</li>
  148 <li><strong class="command">xy</strong> - a plotter which plots scatter, line, or stepped
  149 plots. This versatile plotter takes an x and y dataset, and
  150 plots (optional) points, in a chosen marker and colour,
  151 connecting them with (optional) lines, and plotting (optional)
  152 error bars. An xy plotter can also plot a stepped line, allowing
  153 histograms to be plotted (note that it doesn’t yet do the
  154 binning of the data).  The settings for the xy widget are the
  155 various attributes for the points, line and error bars, the
  156 datasets to plot, and the axes to plot on.  The xy plotter can
  157 plot a label next to each dataset, which is either the same for
  158 each point or taken from a text dataset.  If you wish to leave
  159 gaps in a plot, the input value <cite>nan</cite> can be specified in the
  160 numeric dataset.</li>
  161 <li><strong class="command">fit</strong> - fit a function to data. This plotter is a like
  162 the function plotter, but allows fitting of the function to
  163 data. This is achieved by clicking on a “fit” button, or using
  164 the “fit” action of the widget. The fitter takes a function to
  165 fit containing the unknowns, e.g. <cite>a*x**2 + b*x + c</cite>, and
  166 initial values for the variables (here a, b and c). It then fits
  167 the data (note that at the moment, the fit plotter fits all the
  168 data, not just the data that can be seen on the graph) by
  169 minimising the chi-squared.  In order to fit properly, the y
  170 data (or x, if fitting as a function of x) must have a properly
  171 defined, preferably symmetric error. If there is none, Veusz
  172 assumes the same fractional error everywhere, or symmetrises
  173 asymmetric errors.  Note that more work is required in this
  174 widget, as if a parameter is not well defined by the data, the
  175 matrix inversion in the fit will fail. In addition Veusz does
  176 not supply estimates for the errors or the final chi-squared in
  177 a machine readable way.  If the fitting parameters vary
  178 significantly from 1, then it is worth “normalizing” them by
  179 adding in a factor in the fit equation to bring them to of the
  180 order of 1.</li>
  181 <li><strong class="command">bar</strong> - a bar chart which plots sets of data as
  182 horizontal or vertical bars. Multiple datasets are supported. In
  183 “grouped” mode the bars are placed side-by-side for each
  184 dataset. In “stacked” mode the bars are placed on top of each
  185 other (in the appropriate direction according to the sign of the
  186 dataset). Bars are placed on coordinates given, or in integer
  187 values from 1 upward if none are given. Error bars are plotted
  188 for each of the datasets.  Different fill styles can be given
  189 for each dataset given. A separate key value can be given for
  190 each dataset.</li>
  191 <li><strong class="command">key</strong> - a box which describes the data plotted. If a
  192 key is added to a plot, the key looks for “key” settings of the
  193 other data plotted within a graph. If there any it builds up a
  194 box containing the symbol and line for the plotter, and the text
  195 in the “key” setting of the widget. This allows a key to be very
  196 easily added to a plot.  The key may be placed in any of the
  197 corners of the plot, in the centre, or manually
  198 placed. Depending on the ordering of the widgets, the key will
  199 be placed behind or on top of the widget. The key can be filled
  200 and surrounded by a box, or not filled or surrounded.</li>
  201 <li><strong class="command">label</strong> - a text label places on a graph. The alignment
  202 can be adjusted and the font changed. The position of the label
  203 can be specified in fractional terms of the current graph, or
  204 using axis coordinates.</li>
  205 <li><strong class="command">rect, ellipse</strong> - these draw a rectangle or ellipse,
  206 respectively, of size and rotation given. These widgets can be
  207 placed directly on the page or on a graph. The centre can be
  208 given in axis coordinates or fractional coordinates.</li>
  209 <li><strong class="command">imagefile</strong> - draw an external graphs file on the graph
  210 or page, with size and rotation given. The centre can be given
  211 in axis coordinates or fractional coordinates.</li>
  212 <li><strong class="command">line</strong> - draw a line with optional arrowheads on the
  213 graph or page. One end can be given in axis coordinates or
  214 fractional coordinates.</li>
  215 <li><strong class="command">contour</strong> - plot contours of a 2D dataset on the
  216 graph. Contours are automatically calculated between the minimum
  217 and maximum values of the graph or chosen manually. The line
  218 style of the contours can be chosen individually and the region
  219 between contours can be filled with shading or color.  2D
  220 datasets currently consist of a regular grid of values between
  221 minimum and maximum positions in x and y. They can be
  222 constructed from three 1D datasets of x, y and z if they form a
  223 regular x, y grid.</li>
  224 <li><strong class="command">image</strong> - plot a 2D dataset as a colored
  225 image. Different color schemes can be chosen. The scaling
  226 between the values and the image can be specified as linear,
  227 logarithmic, square-root or square.</li>
  228 <li><strong class="command">polygon</strong> - plot x and y points from datasets as a
  229 polygon. The polygon can be placed directly on the page or
  230 within a graph. Coordinates are either plotted using the axis or
  231 as fractions of the width and height of the containing widget.</li>
  232 <li><strong class="command">boxplot</strong> - plot distribution of points in a dataset.</li>
  233 <li><strong class="command">polar</strong> - plot polar data or functions. This is a
  234 non-orthogonal plot and is placed directly on the page rather
  235 than in a graph.</li>
  236 <li><strong class="command">ternary</strong> - plot data of three variables which add up
  237 to 100 per cent.This is a non-orthogonal plot and is placed
  238 directly on the page rather than in a graph.</li>
  239 </ol>
  240 </li>
  241 <li><p class="first">3D widgets - 3D graphs can be created by adding a 3D scene widget
  242 (<strong class="command">scene3d</strong>) to a blank page, or by creating a new 3D
  243 document. The 3D scene has settings which control the angle the
  244 rotation angle of the plot, the position and color of lighting and
  245 the rendering method.</p>
  246 <p>To build up a 3D plot the following widgets can be placed inside
  247 it:</p>
  248 <ol class="arabic simple">
  249 <li><strong class="command">graph3d</strong> - this is an analogous widget to the 2D graph
  250 widget, plotting a 3D plot with cartesian axes. It contains
  251 three or more axis3d widgets, and plotting widgets. The graph
  252 contains settings for the graph size (the default is 1 in each
  253 direction) and the 3D position of the graph in the same
  254 units. Multiple graph widgets can be added to a scene, though
  255 the position and sizes may need to be adjusted.</li>
  256 <li><strong class="command">axis3d</strong> - normally a 3D graph has three axes (X, Y and
  257 Z), but more axes can be added to plot multiple things on a single
  258 axis direction. This works in a similar way to the 2D axis
  259 widget. The widget has options for the axis label, tick labels,
  260 tick marks and grid lines (which appear on the outside of the 3D
  261 cube). An axis can be swiched between linear and logorithmic
  262 mode. Scalings can be applied to the data values plotted in that
  263 dimension or to the axis labels.</li>
  264 <li><strong class="command">point3d</strong> - for plotting points, and optionally
  265 connecting lines, in 3D. This, and the other plotting widgets
  266 are placed in a graph3d widget. The user provides three 1D
  267 datasets for the x, y and z values. The markers can be scaled in
  268 size by another optional dataset. The markers can also be
  269 colored according to another optional dataset, according to a
  270 color map, minimum and maximum. Error bars can be provided for
  271 each of the x, y and z datasets. The connecting line can also be
  272 colored if a color dataset is provided and a colormap chosen.</li>
  273 <li><strong class="command">function3d</strong> - for plotting either a functional line in
  274 3D space or a functional surface. The type of plot is given by
  275 the mode parameter. In the case of the line, the x,y,z
  276 coordinates can be specified as a function of t, where t goes
  277 from 0 to 1, or by giving functions for two of the coordinates
  278 as a function of the other. For a surface, the value for x, y or
  279 z is given as a function of the other two. In addition, a
  280 function returning 0 to 1 can be provided for the color, which
  281 specifies the color map value for the surface at each position
  282 or the line color. For a 2D surface, the grid lines or surface
  283 fill can be hidden or shown. There are also settings giving the
  284 number of function evaluations to compute in each direction for
  285 a surface, or in one direction for a line.</li>
  286 <li><strong class="command">surface3d</strong> - for plotting a two dimensional surface
  287 from data values. The user should provide a 2D dataset for the
  288 height of a surface. The x, y or z axis for the height and other
  289 directions can be chosen. A second 2D dataset can be provided
  290 for the color of the surface at each point. Note that the
  291 coordinate of the 2D dataset lies at the center of each 2D grid
  292 point. The height of the grid at the edge is calculated by
  293 linear interpolation. Normally the grid is surrounded by four
  294 lines and the surface by two triangles. If a high resolution
  295 option is enabled, the each grid point is surrounded by eight
  296 lines and the surface drawn by eight triangles.</li>
  297 <li><strong class="command">volume3d</strong> - for plotting 3D volumes. In this widget,
  298 for a volume described by A×B×C values, then the user should
  299 provide four datasets, each containing up to A×B×C values (there
  300 can be holes in the representation). Three of the datasets give
  301 coordinates of the centers of the 3D cells and the fourth the
  302 color of the cell. An example set of datasets would be
  303 X=(0,0,0,0,1,1,1,1), Y=(0,0,1,1,0,0,1,1), Z=(0,1,0,1,0,1,0,1),
  304 color=(0.1,0.2,0.3,0.4,0.3,0.2,0.1,0). Additionally, the user
  305 can provide a transparency dataset, which can be useful for
  306 showing or hiding parts of the 3D space.</li>
  307 </ol>
  308 </li>
  309 </ol>
  310 </div>
  311 <div class="section" id="settings-properties-and-formatting">
  312 <h3>Settings: properties and formatting<a class="headerlink" href="#settings-properties-and-formatting" title="Permalink to this headline"></a></h3>
  313 <p>The various settings of the widgets come in a number of types,
  314 including integers (e.g. 10), floats (e.g. 3.14), dataset names
  315 (<cite>mydata</cite>), expressions (<cite>x+y</cite>), text (<cite>hi there!</cite>), distances (see
  316 above), options (<cite>horizontal</cite> or <cite>vertical</cite> for axes).</p>
  317 <p>Veusz performs type checks on these parameters. If they
  318 are in the wrong format the control to edit the setting will
  319 turn red. In the command line, a TypeError exception is
  320 thrown.</p>
  321 <p>In the GUI, the current page is replotted if a setting
  322 is changed when enter is pressed or the user moves to another
  323 setting.</p>
  324 <p>The settings are split up into formatting settings,
  325 controlling the appearance of the plot, or properties,
  326 controlling what is plotted and how it is plotted.</p>
  327 <p>Default settings, including the default font and line
  328 style, and the default settings for any graph widget, can be
  329 modified in the “Default styles” dialog box under the “Edit”
  330 menu. Default settings are set on a per-document basis, but
  331 can be saved into a separate file and loaded. A default
  332 default settings file can be given to use for new documents
  333 (set in the preferences dialog).</p>
  334 </div>
  335 <div class="section" id="datasets">
  336 <h3>Datasets<a class="headerlink" href="#datasets" title="Permalink to this headline"></a></h3>
  337 <p>Data are imported into Veusz as a dataset. A dataset is
  338 imported from a file, entered manually, set via the command
  339 line, or linked to other datasets via an expression or
  340 dataset plugin. Each dataset has a unique name in the
  341 document. They can be seen in the dataset browser panel, or
  342 in the Data, Edit dialog box.  To choose the data to be
  343 plotted, the user usually selects the dataset in the
  344 appropriate setting of a widget.</p>
  345 <p>Veusz supports one-dimensional (1D) datasets, which are a
  346 list of values with optional error bars. Error bars can
  347 either be symmetric or asymmetric. Veusz also supports
  348 two-dimensional (2D) data. A 2D dataset is a grid of values,
  349 with either a fixed spacing in coordinates, or with
  350 arbitrary pixel sizes. An n-dimensional (nD) dataset is an
  351 arbitrary matrix of values. These cannot be plotted
  352 directly, but subsets can be plotted using python slice
  353 syntax to convert to 1D or 2D datasets.</p>
  354 <p>In addition to simple numeric datasets, Veusz also supports
  355 date-time datasets. For details see the sections on reading
  356 data. Also supported are text datasets, which are lists of
  357 text strings.</p>
  358 <p>Datasets can either be plain lists of values which are
  359 stored within the document, or they can be linked to a file,
  360 so that the values update if the file is reloaded, or they
  361 can be linked to other datasets via expressions or dataset
  362 plugins.</p>
  363 </div>
  364 <div class="section" id="text">
  365 <span id="textfonts"></span><h3>Text<a class="headerlink" href="#text" title="Permalink to this headline"></a></h3>
  366 <p>Veusz understands a limited set of LaTeX-like formatting
  367 for text. There are some differences (for example, <cite>10^23</cite>
  368 puts the 2 and 3 into superscript), but it is fairly
  369 similar. You should also leave out the dollar signs. Veusz
  370 supports superscripts (<cite>^</cite>), subscripts (<cite>_</cite>), brackets for
  371 grouping attributes are <cite>{</cite> and <cite>}</cite>.</p>
  372 <p>Supported LaTeX symbols include: \AA, \Alpha, \Beta,
  373 \Chi, \Delta, \Epsilon, \Eta, \Gamma, \Iota, \Kappa, \Lambda, \Mu,
  374 \Nu, \Omega, \Omicron, \Phi, \Pi, \Psi, \Rho, \Sigma, \Tau, \Theta,
  375 \Upsilon, \Xi, \Zeta, \alpha, \approx, \ast, \asymp, \beta, \bowtie,
  376 \bullet, \cap, \chi, \circ, \cup, \dagger, \dashv, \ddagger, \deg,
  377 \delta, \diamond, \divide, \doteq, \downarrow, \epsilon, \equiv,
  378 \eta, \gamma, \ge, \gg, \hat, \in, \infty, \int, \iota, \kappa, \lambda,
  379 \le, \leftarrow, \lhd, \ll, \models, \mp, \mu, \neq, \ni, \nu, \odot,
  380 \omega, \omicron, \ominus, \oplus, \oslash, \otimes, \parallel,
  381 \perp, \phi, \pi, \pm, \prec, \preceq, \propto, \psi, \rhd, \rho,
  382 \rightarrow, \sigma, \sim, \simeq, \sqrt, \sqsubset, \sqsubseteq,
  383 \sqsupset, \sqsupseteq, \star, \stigma, \subset, \subseteq, \succ,
  384 \succeq, \supset, \supseteq, \tau, \theta, \times, \umid, \unlhd,
  385 \unrhd, \uparrow, \uplus, \upsilon, \vdash, \vee, \wedge, \xi, \zeta.
  386 Please request additional characters if they are required (and exist
  387 in the unicode character set). Special symbols can be included
  388 directly from a character map.</p>
  389 <p>Other LaTeX commands are supported. <cite>\</cite> breaks a
  390 line. This can be used for simple tables. For example <cite>{a\b}
  391 {c\d}</cite> shows <cite>a c</cite> over <cite>b d</cite>. The command <cite>\frac{a}{b}</cite>
  392 shows a vertical fraction a/b.</p>
  393 <p>Also supported are commands to change font. The command
  394 <cite>\font{name}{text}</cite> changes the font text is written in to
  395 name. This may be useful if a symbol is missing from the
  396 current font, e.g. <cite>\font{symbol}{g}</cite> should produce a
  397 gamma. You can increase, decrease, or set the size of the font
  398 with <cite>\size{+2}{text}</cite>, <cite>\size{-2}{text}</cite>, or
  399 <cite>\size{20}{text}</cite>. Numbers are in points.</p>
  400 <p>Various font attributes can be changed: for example,
  401 <cite>\italic{some italic text}</cite> (or use <cite>\textit</cite> or <cite>\emph</cite>),
  402 <cite>\bold{some bold text}</cite> (or use <cite>\textbf</cite>) and <cite>\underline{some
  403 underlined text}</cite>.</p>
  404 <p>Example text could include <cite>Area / \pi (10^{-23}
  405 cm^{-2})</cite>, or <cite>\pi\bold{g}</cite>.</p>
  406 <p>Veusz plots these symbols with Qt’s unicode support. You
  407 can also include special characters directly, by copying and
  408 pasting from a character map application. If your current font
  409 does not contain these symbols then you may get a box
  410 character.</p>
  411 <p>Veusz also supports the evaluation of a Python
  412 expression when text is written to the page. Python code is
  413 written inside the brackets <strong class="command">%{{ }}%</strong>. Note
  414 that the Python evaluation happens before the LaTeX expansion
  415 is done. The return value of the expression is converted to
  416 text using the Python <strong class="command">str()</strong> function. For
  417 example, the expression <strong class="command">%{{2+2}}%</strong> would
  418 write <strong class="command">4</strong>. Custom functions and constants are
  419 supported when evaluation, in addition to the usual numpy
  420 functions. In addition, Veusz defines the following useful
  421 functions and values.</p>
  422 <ol class="arabic simple">
  423 <li><strong class="command">ENVIRON</strong> is the
  424 <strong class="command">os.environ</strong> dict of environment
  425 variables. <strong class="command">%{{ENVIRON['USER']}}%</strong>
  426 would show the current user in unix.</li>
  427 <li><strong class="command">DATE([fmt])</strong> returns the current
  428 date, by default in ISO format. fmt is an optional
  429 format specifier using
  430 <strong class="command">datetime.date.strftime</strong> format
  431 specifiers.</li>
  432 <li><strong class="command">TIME([fmt])</strong> returns the current
  433 date/time, by default in ISO format. fmt is an optional
  434 format specifier using
  435 <strong class="command">datetime.datetime.strftime</strong> format
  436 specifiers.</li>
  437 <li><strong class="command">DATA(name[, part])</strong> returns the Veusz
  438 dataset with given name. For numeric datasets this is a
  439 numpy array. For numeric datasets with errors, part
  440 specifies the dataset part to return, i.e. ‘data’,
  441 ‘serr’, ‘perr’, ‘nerr’. For example, the mean value of
  442 a dataset could be shown using
  443 <strong class="command">%{{mean(DATA('x'))}}%</strong>.</li>
  444 <li><strong class="command">FILENAME()</strong> - returns the current
  445 document filename. This can include the
  446 directory/folder of the file. Note that the filename is
  447 escaped with ESCAPE() so that LaTeX symbols are not
  448 expanded when shown.</li>
  449 <li><strong class="command">BASENAME()</strong> - returns the current
  450 document filename, removing the directory or folder
  451 name Note that the filename is escaped with ESCAPE() so
  452 that LaTeX symbols are not expanded when shown.</li>
  453 <li><strong class="command">ESCAPE(x)</strong> - escapes any LaTeX
  454 symbols in x so that they are not interpreted as
  455 LaTeX.</li>
  456 <li><strong class="command">SETTING(path)</strong> - return the value of
  457 the Veusz setting given by the full path,
  458 e.g. <strong class="command">%{{SETTING('/page1/width')}}%</strong>.</li>
  459 <li><strong class="command">LANG(mapping)</strong> - mapping is a dictionary which maps
  460 language names to strings. This returns the string corresponding to
  461 the current language. The keys come from the locale names which are
  462 the two-letter language codes (e.g. <cite>en</cite> or <cite>fr</cite>), or the full code
  463 (e.g. <cite>en_GB</cite> or <cite>de_AT</cite>). The <cite>default</cite> key is used if the
  464 language code is not found. An example is <strong class="command">%{{
  465 LANG({'de':'Druck','default':'Pressure'}) }}%</strong>.</li>
  466 </ol>
  467 </div>
  468 <div class="section" id="measurements">
  469 <h3>Measurements<a class="headerlink" href="#measurements" title="Permalink to this headline"></a></h3>
  470 <p>Distances, widths and lengths in Veusz can be specified in a number of
  471 different ways. These include absolute distances specified in physical
  472 units, e.g. 1cm, 0.05m, 10mm, 5in and 10pt, and relative units, which
  473 are relative to the largest dimension of the page, including 5%, 1/20,
  474 0.05.</p>
  475 </div>
  476 <div class="section" id="color-theme">
  477 <h3>Color theme<a class="headerlink" href="#color-theme" title="Permalink to this headline"></a></h3>
  478 <p>From version 1.26, widgets are colored automatically using the color
  479 theme. This theme is specified in the main document widget
  480 settings. Widgets are given the colors in order given the order in a
  481 graph widget. The default theme can be specified in the preferences
  482 dialog box.</p>
  483 <p>To override a theme, the user can manually specify the individual
  484 colors in the custom definitions dialog box. Color <cite>theme1</cite> is used as
  485 the first theme color, then <cite>theme2</cite>, etc.</p>
  486 </div>
  487 <div class="section" id="axis-numeric-scales">
  488 <h3>Axis numeric scales<a class="headerlink" href="#axis-numeric-scales" title="Permalink to this headline"></a></h3>
  489 <p>The way in which numbers are formatted in axis scales is chosen
  490 automatically. For standard numerical axes, values are shown with the
  491 <cite>%Vg</cite> formatting (see below). For date axes, an appropriate date
  492 formatting is used so that the interval shown is correct. A format can
  493 be given for an axis in the axis number formatting panel can be given
  494 to explicitly choose a format. Some examples are given in the drop
  495 down axis menu. Hold the mouse over the example for detail.</p>
  496 <p>C-style number formatting is used with a few Veusz specific
  497 extensions. Text can be mixed with format specifiers, which start with
  498 a <cite>%</cite> sign. Examples of C-style formatting include: <cite>%.2f</cite> (decimal
  499 number with two decimal places, e.g. 2.01), <cite>%.3e</cite> (scientific
  500 formatting with three decimal places, e.g. 2.123e-02), <cite>%g</cite> (general
  501 formatting, switching between <cite>%f</cite> and <cite>%e</cite> as appropriate). See
  502 <a class="reference external" href="http://opengroup.org/onlinepubs/007908799/xsh/fprintf.html">http://opengroup.org/onlinepubs/007908799/xsh/fprintf.html</a> for
  503 details.</p>
  504 <p>Veusz extensions include <cite>%Ve</cite>, which is like <cite>%e</cite> except it displays
  505 scientific notation as written, e.g. 1.2x10^23, rather than
  506 1.2e+23. <cite>%Vg</cite> switches between standard numbers and Veusz scientific
  507 notation for large and small numbers. <cite>%VE</cite> using engineering SI
  508 suffixes to represent large or small numbers (e.g. 1000 is 1k).</p>
  509 <p>Veusz allows dates and times to be formatted using <cite>%VDX</cite> where <cite>X</cite> is
  510 one of the formatting characters for strftime (see
  511 <a class="reference external" href="http://opengroup.org/onlinepubs/007908799/xsh/strftime.html">http://opengroup.org/onlinepubs/007908799/xsh/strftime.html</a> for
  512 details). These include <cite>a</cite> for an abbreviated weekday name, <cite>A</cite> for
  513 full weekday name, <cite>b</cite> for abbreviated month name, <cite>B</cite> for full month
  514 name, <cite>c</cite> date and time representation, <cite>d</cite> day of month 01..31, <cite>H</cite>
  515 hour as 00..23, <cite>I</cite> hour as 01..12, <cite>j</cite> as day of year 001..366, <cite>m</cite>
  516 as month 01..12, <cite>M</cite> minute as 00..59, <cite>p</cite> AM/PM, <cite>S</cite> second 00..61,
  517 <cite>U</cite> week number of year 00..53 (Sunday as first day of week), <cite>w</cite>
  518 weekday as decimal number 0..6, <cite>W</cite> week number of year (Monday as
  519 first day of week), <cite>x</cite> date representation, <cite>X</cite> time representation,
  520 <cite>y</cite> year without century 00..99 and <cite>Y</cite> year. <cite>%VDVS</cite> is a special
  521 Veusz addon format which shows seconds and fractions of seconds
  522 (e.g. 12.2).</p>
  523 </div>
  524 <div class="section" id="three-dimensional-3d-plots">
  525 <h3>Three dimensional (3D) plots<a class="headerlink" href="#three-dimensional-3d-plots" title="Permalink to this headline"></a></h3>
  526 <p>When drawing in three dimensions, Veusz builds up a 3D “scene” for the
  527 graph from the various plotting widgets, made up of triangles, line
  528 segments, points and text. Veusz does not use a standard (e.g. OpenGL)
  529 drawing method, but renders the scene itself. The advantage of this is
  530 that it can produce vector rather than bitmap or raster
  531 output. OpenGL, for example, is based around bitmaps.</p>
  532 <p>Veusz applies lighting to the scene. The lighting depends on enabled
  533 light sources, which are set in the scene3d widget. Light sources have
  534 a color, intensity and position. Note that only the angle of the light
  535 to a surface affects its lighting, not its distance. The position of
  536 the light is relative to the viewer (camera), not the graph. Positive
  537 light coordinates are towards the graph (z), upwards (y) and
  538 rightwards (x). Normally each solid surface has an intrinsic color,
  539 which can be seen without any lighting. If a light source is enabled,
  540 the color of the light is added to the surface color, depending on the
  541 reflectivity of the surface. Each surface also has a transparency
  542 setting.</p>
  543 <p>By default, Veusz uses a naive Painter’s Algorithm to draw the
  544 scene. It draws from the back of scene to the front. The main problem
  545 with this algorithm is that shapes and lines overlapping in depth can
  546 be confused as the depth of each object is calculated at only one
  547 point. In addition objects may intersect, which is not properly
  548 treated. In the scene3d object, the user can switch to a different
  549 rendering mode called BSP. In this accurate BSP mode, the objects are
  550 split so that they never overlap from any viewing angle. The
  551 disadvantage of this mode is that it is slow, uses a lot of memory and
  552 produces large output files. We plan in future to add another mode
  553 which handles overlaps better and does not unnecessarily split
  554 objects.</p>
  555 <p>The plot is affected by the viewing angle, which is specified in the
  556 scene3d widget settings. The rotation is given be three rotations
  557 around lines in X, Y and Z directions (note that these are not the
  558 same directions as the X, Y and Z axes!). The X axis runs horizontally
  559 on the screen, the Y axis runs vertically, and the Z axis runs along
  560 the line of sight.</p>
  561 <p>There is also a distance setting, which moves graphs closer to or away
  562 from the viewer. At larger distances the effect of perspective
  563 reduces, meaning that parts of the plot closer to the viewer are not
  564 larger than if they were at the farthest side. At large distances, a
  565 plot tends towards being isometric. At small distances, shapes are
  566 more distorted (note by default the size of the graph is 1 in these
  567 distance units). It is currently possible to place graphs inside the
  568 camera leading to strange output.</p>
  569 <p>By default, Veusz enlarges the 3D rendered scene to fill the bounds of
  570 the 3D scene widget, so distance has no effect on the size of the
  571 plot. This scaling can be switched off by modifying the Size setting
  572 from “Auto” to a fixed number. A fixed size is useful if the user
  573 wants a graph to be the same size for any rotation. With this setting
  574 the size of the plot is affected by their distance.</p>
  575 <p>By default, a 3D graph has dimensions of 1 along the X, Y and Z
  576 axes. The size can be adjusted using the size settings in the graph3d
  577 widget. Care should be taken that the graph size does not lead to
  578 points being at negative viewing distances. The default position of
  579 the plot is at the origin 0,0,0. If the user wants to plot multiple
  580 graph3d widgets, the positions should be adjusted to prevent overlap.</p>
  581 <p>Normally in Veusz, sizes of objects (e.g. plot markers) are given in
  582 physical units. This makes less sense for a 3D plot as sizes can
  583 depend on distance. In a 3D graph sizes of plotting markers and line
  584 widths are given in 1/1000 of the graph bounding box maximum
  585 dimension.</p>
  586 </div>
  587 </div>
  588 <div class="section" id="the-main-window">
  589 <h2>The main window<a class="headerlink" href="#the-main-window" title="Permalink to this headline"></a></h2>
  590 <p>You should see the main window when you run Veusz (you can just type
  591 the veusz command in Unix).</p>
  592 <img alt="_images/mainwindow.png" src="_images/mainwindow.png" />
  593 <p>The Veusz window is split into several sections. At the top is the
  594 menu bar and tool bar. These work in the usual way to other
  595 applications. Sometimes options are disabled (greyed out) if they do
  596 not make sense to be used. If you hold your mouse over a button for a
  597 few seconds, you will usually get an explanation for what it does
  598 called a “tool tip”.</p>
  599 <p>Below the main toolbar is a second toolbar for constructing the graph
  600 by adding widgets (on the left), and some editing buttons. The add
  601 widget buttons add the request widget to the currently selected widget
  602 in the selection window. The widgets are arranged in a tree-like
  603 structure.</p>
  604 <p>Below these toolbars and to the right is the plot window. This is
  605 where the current page of the current document is shown. You can
  606 adjust the size of the plot on the screen (the zoom factor) using the
  607 “View” menu or the zoom tool bar button (the magnifying
  608 glass). Initially you will not see a plot in the plot window, but you
  609 will see the Veusz logo. At the moment you cannot do much else with
  610 the window. In the future you will be able to click on items in the
  611 plot to modify them.</p>
  612 <p>To the left of the plot window is the selection window, and the
  613 properties and formatting windows. The properties window lets you edit
  614 various aspects of the selected widget (such as the minimum and
  615 maximum values on an axis). Changing these values should update the
  616 plot. The formatting lets you modify the appearance of the selected
  617 widget. There are a series of tabs for choosing what aspect to modify.</p>
  618 <p>The various windows can be “dragged” from the main window to “float”
  619 by themselves on the screen.</p>
  620 <p>To the bottom of the window is the console. This window is not shown
  621 by default, but can be enabled in the View menu. The console is a
  622 Veusz and Python command line console. To read about the commands
  623 available see <a class="reference internal" href="api.html#commands"><span class="std std-ref">Commands</span></a>. As this is a Python console,
  624 you can enter mathematical expressions (e.g. <cite>1+2.0*cos(pi/4)</cite>) here
  625 and they will be evaluated when you press Enter. The usual special
  626 functions and the operators are supported. You can also assign results
  627 to variables (e.g. <cite>a=1+2</cite>) for use later. The console also supports
  628 command history like many Unix shells. Press the up and down cursor
  629 keys to browse through the history. Command line completion is not
  630 available yet!</p>
  631 <p>There also exists a dataset browsing window, by default to the right
  632 of the screen. This window allows you to view the datasets currently
  633 loaded, their dimensions and type. Hovering a mouse over the size of
  634 the dataset will give you a preview of the data.</p>
  635 </div>
  636 <div class="section" id="my-first-plot">
  637 <h2>My first plot<a class="headerlink" href="#my-first-plot" title="Permalink to this headline"></a></h2>
  638 <p>After opening Veusz, on the left of the main window, you will see a
  639 Document, containing a Page, which contains a Graph with its axes. The
  640 Graph is selected in the selection window. The toolbar above adds a
  641 new widget to the selected widget. If a widget cannot be added to a
  642 selected widget it is disabled. On opening a new document Veusz
  643 automatically adds a new Page and Graph (with axes) to the document.</p>
  644 <p>You will see something like this:</p>
  645 <img alt="_images/winwithgraph.png" src="_images/winwithgraph.png" />
  646 <p>Select the x axis which has been added to the document (click on <cite>x</cite>
  647 in the selection window). In the properties window you will see a
  648 variety of different properties you can modify. For instance you can
  649 enter a label for the axis by writing <cite>Area (cm^{2})</cite> in the box next
  650 to label and pressing enter. Veusz supports text in LaTeX-like form
  651 (without the dollar signs). Other important parameters is the <cite>log</cite>
  652 switch which switches between linear and logarithmic axes, and <cite>min</cite>
  653 and <cite>max</cite> which allow the user to specify the minimum and maximum
  654 values on the axes.</p>
  655 <p>The formatting dialog lets you edit various aspects of the graph
  656 appearance. For instance the “Line” tab allows you to edit the line of
  657 the axis. Click on “Line”, then you can then modify its colour. Enter
  658 “green” instead of “black” and press enter. Try making the axis label
  659 bold.</p>
  660 <p>Now you can try plotting a function on the graph. If the graph, or its
  661 children are selected, you will then be able to click the “function”
  662 button at the top (a red curve on a graph). You will see a straight
  663 line (y=x) added to the plot. If you select “function1”, you will be
  664 able to edit the functional form plotted and the style of its
  665 line. Change the function to <cite>x**2</cite> (x-squared).</p>
  666 <p>We will now try plotting data on the graph. Go to your
  667 favourite text editor and save the following data as
  668 test.dat:</p>
  669 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">1</span>     <span class="mf">0.1</span>   <span class="o">-</span><span class="mf">0.12</span>   <span class="mf">1.1</span>    <span class="mf">0.1</span>
  670 <span class="mf">2.05</span>  <span class="mf">0.12</span>  <span class="o">-</span><span class="mf">0.14</span>   <span class="mf">4.08</span>   <span class="mf">0.12</span>
  671 <span class="mf">2.98</span>  <span class="mf">0.08</span>  <span class="o">-</span><span class="mf">0.1</span>    <span class="mf">2.9</span>    <span class="mf">0.11</span>
  672 <span class="mf">4.02</span>  <span class="mf">0.04</span>  <span class="o">-</span><span class="mf">0.1</span>    <span class="mf">15.3</span>   <span class="mf">1.0</span>
  673 </pre></div>
  674 </div>
  675 <p>The first three columns are the x data to plot plus its asymmetric
  676 errors. The final two columns are the y data plus its symmetric
  677 errors. In Veusz, go to the “Data” menu and select “Import”. Type the
  678 filename into the filename box, or use the “Browse…” button to
  679 search for the file. You will see a preview of the data pop up in the
  680 box below. Enter <cite>x,+,- y,+-</cite> into the descriptors edit box (note that
  681 commas and spaces in the descriptor are almost interchangeable in
  682 Veusz 1.6 or newer). This describes the format of the data which
  683 describes dataset “x” plus its asymmetric errors, and “y” with its
  684 symmetric errors. If you now click “Import”, you will see it has
  685 imported datasets <cite>x</cite> and <cite>y</cite>.</p>
  686 <p>To plot the data you should now click on <cite>graph1</cite> in the tree
  687 window. You are now able to click on the “xy” button (which looks like
  688 points plotted on a graph). You will see your data plotted on the
  689 graph. Veusz plots datasets <cite>x</cite> and <cite>y</cite> by default, but you can change
  690 these in the properties of the “xy” plotter.</p>
  691 <p>You are able to choose from a variety of markers to plot. You can
  692 remove the plot line by choosing the “Plot Line” subsetting, and
  693 clicking on the “hide” option. You can change the colour of the marker
  694 by going to the “Marker Fill” subsetting, and entering a new colour
  695 (e.g. red), into the colour property.</p>
  696 </div>
  697 </div>
  700           </div>
  701         </div>
  702       </div>
  703       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
  704         <div class="sphinxsidebarwrapper">
  705 <h1 class="logo"><a href="index.html">Veusz</a></h1>
  714 <h3>Navigation</h3>
  715 <ul class="current">
  716 <li class="toctree-l1 current"><a class="current reference internal" href="#">Introduction</a><ul>
  717 <li class="toctree-l2"><a class="reference internal" href="#veusz">Veusz</a></li>
  718 <li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a></li>
  719 <li class="toctree-l2"><a class="reference internal" href="#getting-started">Getting started</a></li>
  720 <li class="toctree-l2"><a class="reference internal" href="#terminology">Terminology</a><ul>
  721 <li class="toctree-l3"><a class="reference internal" href="#widget">Widget</a></li>
  722 <li class="toctree-l3"><a class="reference internal" href="#settings-properties-and-formatting">Settings: properties and formatting</a></li>
  723 <li class="toctree-l3"><a class="reference internal" href="#datasets">Datasets</a></li>
  724 <li class="toctree-l3"><a class="reference internal" href="#text">Text</a></li>
  725 <li class="toctree-l3"><a class="reference internal" href="#measurements">Measurements</a></li>
  726 <li class="toctree-l3"><a class="reference internal" href="#color-theme">Color theme</a></li>
  727 <li class="toctree-l3"><a class="reference internal" href="#axis-numeric-scales">Axis numeric scales</a></li>
  728 <li class="toctree-l3"><a class="reference internal" href="#three-dimensional-3d-plots">Three dimensional (3D) plots</a></li>
  729 </ul>
  730 </li>
  731 <li class="toctree-l2"><a class="reference internal" href="#the-main-window">The main window</a></li>
  732 <li class="toctree-l2"><a class="reference internal" href="#my-first-plot">My first plot</a></li>
  733 </ul>
  734 </li>
  735 <li class="toctree-l1"><a class="reference internal" href="datasets.html">Reading data</a></li>
  736 <li class="toctree-l1"><a class="reference internal" href="datasets.html#manipulating-datasets">Manipulating datasets</a></li>
  737 <li class="toctree-l1"><a class="reference internal" href="datasets.html#capturing-data">Capturing data</a></li>
  738 <li class="toctree-l1"><a class="reference internal" href="api.html">Veusz command line and embedding interface (API)</a></li>
  739 </ul>
  741 <div class="relations">
  742 <h3>Related Topics</h3>
  743 <ul>
  744   <li><a href="index.html">Documentation overview</a><ul>
  745       <li>Previous: <a href="index.html" title="previous chapter">Veusz documentation</a></li>
  746       <li>Next: <a href="datasets.html" title="next chapter">Reading data</a></li>
  747   </ul></li>
  748 </ul>
  749 </div>
  750 <div id="searchbox" style="display: none" role="search">
  751   <h3>Quick search</h3>
  752     <div class="searchformwrapper">
  753     <form class="search" action="search.html" method="get">
  754       <input type="text" name="q" />
  755       <input type="submit" value="Go" />
  756       <input type="hidden" name="check_keywords" value="yes" />
  757       <input type="hidden" name="area" value="default" />
  758     </form>
  759     </div>
  760 </div>
  761 <script type="text/javascript">$('#searchbox').show(0);</script>
  762         </div>
  763       </div>
  764       <div class="clearer"></div>
  765     </div>
  766     <div class="footer">
  767       &copy;2003-2019, Jeremy Sanders.
  769       |
  770       Powered by <a href="http://sphinx-doc.org/">Sphinx 1.8.5</a>
  771       &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
  773       |
  774       <a href="_sources/introduction.rst.txt"
  775           rel="nofollow">Page source</a>
  776     </div>
  781   </body>
  782 </html>