                     Veusz - a scientific plotting package

  Jeremy Sanders

   Copyright © 2011

     This document is licensed under the GNU General Public License, version
   2 or greater. Please see the file COPYING for details, or see
   [1]http://www.gnu.org/licenses/gpl-2.0.html.

   --------------------------------------------------------------------------

   Table of Contents

   [2]Introduction

                [3]Veusz

                [4]Terminology

                             [5]Widget

                             [6]Measurements

                             [7]Settings

                             Text

                             [8]Axis numbers

                [9]Installation

                [10]The main window

                [11]My first plot

   [12]Reading data

                Descriptors

                [13]Reading CSV files

                [14]Reading FITS files

                [15]Reading other data formats

                [16]Manipulating datasets

                             [17]Using dataset plugins

                             [18]Using expressions to create new datasets

                             [19]Linking datasets to expressions

                             [20]Splitting data

                             [21]Defining new constants or functions

                             [22]Dataset plugins

   Command line interface

                [23]Introduction

                [24]Commands

                             Action

                             Add

                             AddCustom

                             AddImportPath

                             CloneWidget

                             Close

                             CreateHistogram

                             DatasetPlugin

                             EnableToolbar

                             Export

                             ForceUpdate

                             Get

                             GetChildren

                             GetClick

                             GetData

                             GetDatasets

                             GPL

                             ImportFile

                             ImportFile2D

                             ImportFileCSV

                             ImportFilePlugin

                             ImportFITSFile

                             ImportString

                             ImportString2D

                             IsClosed

                             List

                             Load

                             MoveToPage

                             ReloadData

                             Rename

                             Remove

                             ResizeWindow

                             Save

                             Set

                             SetAntiAliasing

                             SetData

                             SetDataExpression

                             SetDataRange

                             SetData2D

                             SetData2DExpression

                             SetData2DExpressionXYZ

                             SetData2DXYFunc

                             SetDataText

                             SetToReference

                             SetUpdateInterval

                             SetVerbose

                             StartSecondView

                             To

                             Quit

                             WaitForClose

                             Zoom

                [25]Security

   [26]Using Veusz from other programs

                [27]Non-Qt Python programs

                [28]PyQt4 programs

                [29]Non Python programs

                [30]C, C++ and Fortran

   --------------------------------------------------------------------------

                                  Introduction

Veusz

   Veusz is a scientific plotting package. It was written as I was
   dissatisfied with existing plotting packages as they were either old and
   unmaintained (like pgplot and qdp, which does not support postscript
   fonts), not free (like IDL or Matlab), or had user interfaces I do not
   appreciate (like gnuplot).

   Veusz is designed to be easily extensible, and is written in Python, a
   high level language (in the future it may be necessary to write some parts
   in another language for speed, but this will be kept to an absolute
   minimum). It is also designed in an object oriented fashion, where a
   document is built up by a number of parts in a hierarchy. The advantage of
   using Python is that is is easy to allow the user to script Veusz using
   Python as a very powerful scripting language. Indeed, the saved file
   format is a Python script.

   The technologies behind Veusz include PyQt (a very easy to use Python
   interface to Qt, which is used for rendering and the graphical user
   interface, GUI) and numpy (a package for Python which makes the handling
   of large datasets easy).

   Veusz has two user interfaces: a graphical one which gives the user a
   relatively shallow learning curve, and a command line interface. The
   command line interface is also used by scripting and in the saved file
   format.

   Furthermore, Veusz can be embedded within other Python programs, with
   plots in their own windows, or it can be controlled from any other
   application.

   --------------------------------------------------------------------------

Terminology

   Here I define some terminology for future use.

   --------------------------------------------------------------------------

  Widget

   A document and its graphs are built up from widgets. These widgets can
   often by placed within each other, depending on the type of the widget. A
   widget has children, those widgets placed within it, and its parent. The
   widgets have a number of different settings which modify their behaviour.
   These include the font to be used, the line thickness, and whether an axis
   is logarithmic. In addition they have actions, which perform some sort of
   activity on the widget or its children, like "fit" for a fit widget.

   Widgets are specified with a "path", like a file in Unix or Windows. These
   can be relative to the current widget (do not start with a slash), or
   absolute (do not start with a slash). Examples of paths include,
   "/page1/graph1/x", "x" and ".".

   The widget types include

    1. document - representing a complete document. A document can contain
       pages. In addition it contains a setting giving the page size for the
       document.

    2. page - representing a page in a document. One or more graphs can be
       placed on a page, or a grid.

    3. graph - defining an actual graph. A graph can be placed on a page or
       within a grid. Contained within the graph are its axes and plotters. A
       graph can be given a background fill and a border if required. It also
       has a margin, which specifies how far away from the edge of its parent
       widget to plot the body of the graph.

       A graph can contain several axes, at any position on the plot. In
       addition a graph can use axes defined in parent widgets, shared with
       other graphs.

       More than one graph can be placed within in a page. The margins can be
       adjusted so that they lie within or besides each other.

    4. grid - containing one or more graphs. A grid plots graphs in a
       gridlike fashion. You can specify the number of rows and columns, and
       the plots are automatically replotted in the chosen arrangement. A
       grid can contain graphs or axes. If an axis is placed in a grid, it
       can be shared by the graphs in the grid.

    5. axis - giving the scale for plotting data. An axis translates the
       coordinates of the data to the screen. An axis can be linear or
       logarithmic, it can have fixed endpoints, or can automatically get
       them from the plotted data. It also has settings for the axis labels
       and lines, tick labels, and major and minor tick marks.

       An axis may be "horizontal" or "vertical" and can appear anywhere on
       its parent graph or grid.

       If an axis appears within a grid, then it can be shared by all the
       graphs which are contained within the grid.

    6. plotters - types of widgets which plot data or add other things on a
       graph. There is no actual plotter widget which can be added, but
       several types of plotters listed below. Plotters typically take an
       axis as a setting, which is the axis used to plot the data on the
       graph (default x and y).

         a. function - a plotter which plots a function on the graph.
            Functions can be functions of x or y (parametric functions are
            not done yet!), and are defined in Python expression syntax,
            which is very close to most other languages. For example "3*x**2
            + 2*x - 4". A number of functions are available (e.g. sin, cos,
            tan, exp, log...). Technically, Veusz imports the numpy package
            when evaluating, so numpy functions are available.

            As well as the function setting, also settable is the line type
            to plot the function, and the number of steps to evaluate the
            function when plotting. Filling is supported
            above/below/left/right of the function.

         b. xy - a plotter which plots scatter, line, or stepped plots. This
            versatile plotter takes an x and y dataset, and plots (optional)
            points, in a chosen marker and colour, connecting them with
            (optional) lines, and plotting (optional) error bars. An xy
            plotter can also plot a stepped line, allowing histograms to be
            plotted (note that it doesn't yet do the binning of the data).

            The settings for the xy widget are the various attibutes for the
            points, line and error bars, the datasets to plot, and the axes
            to plot on.

            The xy plotter can plot a label next to each dataset, which is
            either the same for each point or taken from a text dataset.

            If you wish to leave gaps in a plot, the input value "nan" can be
            specified in the numeric dataset.

         c. fit - fit a function to data. This plotter is a like the function
            plotter, but allows fitting of the function to data. This is
            achived by clicking on a "fit" button, or using the "fit" action
            of the widget. The fitter takes a function to fit containing the
            unknowns, e.g. "a*x**2 + b*x + c", and initial values for the
            variables (here a, b and c). It then fits the data (note that at
            the moment, the fit plotter fits all the data, not just the data
            that can be seen on the graph) by minimising the chi-squared.

            In order to fit properly, the y data (or x, if fitting as a
            function of x) must have a properly defined, preferably symmetric
            error. If there is none, Veusz assumes the same fractional error
            everywhere, or symmetrises asymmetric errors.

            Note that more work is required in this widget, as if a parameter
            is not well defined by the data, the matrix inversion in the fit
            will fail. In addition Veusz does not supply estimates for the
            errors or the final chi-squared in a machine readable way.

            If the fitting parameters vary significantly from 1, then it is
            worth "normalizing" them by adding in a factor in the fit
            equation to bring them to of the order of 1.

         d. bar - a bar chart which plots sets of data as horizontal or
            vertical bars. Multiple datasets are supported. In "grouped" mode
            the bars are placed side-by-side for each dataset. In "stacked"
            mode the bars are placed on top of each other (in the appropriate
            direction according to the sign of the dataset). Bars are placed
            on coordinates given, or in integer values from 1 upward if none
            are given. Error bars are plotted for each of the datasets.

            Different fill styles can be given for each dataset given. A
            separate key value can be given for each dataset.

         e. key - a box which describes the data plotted. If a key is added
            to a plot, the key looks for "key" settings of the other data
            plotted within a graph. If there any it builds up a box
            containing the symbol and line for the plotter, and the text in
            the "key" setting of the widget. This allows a key to be very
            easily added to a plot.

            The key may be placed in any of the corners of the plot, in the
            centre, or manually placed. Depending on the ordering of the
            widgets, the key will be placed behind or on top of the widget.
            The key can be filled and surrounded by a box, or not filled or
            surrounded.

         f. label - a text label places on a graph. The alignment can be
            adjusted and the font changed. The position of the label can be
            specified in fractional terms of the current graph, or using axis
            coordinates.

         g. rect, ellipse - these draw a rectangle or ellipse, respectively,
            of size and rotation given. These widgets can be placed directly
            on the page or on a graph. The centre can be given in axis
            coordinates or fractional coordinates.

         h. imagefile - draw an external graphs file on the graph or page,
            with size and rotation given. The centre can be given in axis
            coordinates or fractional coordinates.

         i. line - draw a line with optional arrowheads on the graph or page.
            One end can be given in axis coordinates or fractional
            coordinates.

         j. contour - plot contours of a 2D dataset on the graph. Contours
            are automatically calculated between the minimum and maximum
            values of the graph or chosen manually. The line style of the
            contours can be chosen individually and the region between
            contours can be filled with shading or color.

            2D datasets currently consist of a regular grid of values between
            minimum and maximum positions in x and y. They can be constructed
            from three 1D datasets of x, y and z if they form a regular x, y
            grid.

         k. image - plot a 2D dataset as a colored image. Different color
            schemes can be chosen. The scaling between the values and the
            image can be specified as linear, logarithmic, square-root or
            square.

         l. polygon - plot x and y points from datasets as a polygon. The
            polygon can be placed directly on the page or within a graph.
            Coordinates are either plotted using the axis or as fractions of
            the width and height of the containing widget.

         m. boxplot - plot distribution of points in a dataset.

         n. polar - plot polar data or functions. This is a non-orthogonal
            plot and is placed directly on the page rather than in a graph.

         o. ternary - plot data of three variables which add up to 100 per
            cent.This is a non-orthogonal plot and is placed directly on the
            page rather than in a graph.

   --------------------------------------------------------------------------

  Measurements

   Distances, widths and lengths in Veusz can be specified in a number of
   different ways. These include absolute distances specified in physical
   units, e.g. 1cm, 0.05m, 10mm, 5in and 10pt, and relative units, which are
   relative to the largest dimension of the page, including 5%, 1/20, 0.05.

   --------------------------------------------------------------------------

  Settings

   The various settings of the widgets come in a number of types, including
   integers (e.g. 10), floats (e.g. 3.14), text ("hi there!"), distances (see
   above), options ("horizontal" or "vertical" for axes).

   Veusz performs type checks on these parameters. If they are in the wrong
   format the control to edit the setting will turn red. In the command line,
   a TypeError exception is thrown.

   In the GUI, the current page is replotted if a setting is changed when
   enter is pressed or the user moves to another setting.

   The settings are split up into formatting settings, controlling the
   appearance of the plot, or properties, controlling what is plotted and how
   it is plotted.

   Default settings, including the default font and line style, and the
   default settings for any graph widget, can be modified in the "Default
   styles" dialog box under the "Edit" menu. Default settings are set on a
   per-document basis, but can be saved into a separate file and loaded. A
   default default settings file can be given to use for new documents (set
   in the preferences dialog).

   --------------------------------------------------------------------------

  Text

   Veusz understands a limited set of LaTeX-like formatting for text. There
   are some differences (for example, "10^23" puts the 2 and 3 into
   superscript), but it is fairly similar. You should also leave out the
   dollar signs. Veusz supports superscripts ("^"), subscripts ("_"),
   brackets for grouping attributes are "{" and "}".

   Supported LaTeX symbols include: \AA, \Alpha, \Beta, \Chi, \Delta,
   \Epsilon, \Eta, \Gamma, \Iota, \Kappa, \Lambda, \Mu, \Nu, \Omega,
   \Omicron, \Phi, \Pi, \Psi, \Rho, \Sigma, \Tau, \Theta, \Upsilon, \Xi,
   \Zeta, \alpha, \approx, \ast, \asymp, \beta, \bowtie, \bullet, \cap, \chi,
   \circ, \cup, \dagger, \dashv, \ddagger, \deg, \delta, \diamond, \divide,
   \doteq, \downarrow, \epsilon, \equiv, \eta, \gamma, \ge, \gg, \in, \infty,
   \int, \iota, \kappa, \lambda, \le, \leftarrow, \lhd, \ll, \models, \mp,
   \mu, \neq, \ni, \nu, \odot, \omega, \omicron, \ominus, \oplus, \oslash,
   \otimes, \parallel, \perp, \phi, \pi, \pm, \prec, \preceq, \propto, \psi,
   \rhd, \rho, \rightarrow, \sigma, \sim, \simeq, \sqrt, \sqsubset,
   \sqsubseteq, \sqsupset, \sqsupseteq, \star, \stigma, \subset, \subseteq,
   \succ, \succeq, \supset, \supseteq, \tau, \theta, \times, \umid, \unlhd,
   \unrhd, \uparrow, \uplus, \upsilon, \vdash, \vee, \wedge, \xi, \zeta.
   Please request additional characters if they are required (and exist in
   the unicode character set). Special symbols can be included directly from
   a character map.

   Other LaTeX commands are supported. "\\" breaks a line. This can be used
   for simple tables. For example "{a\\b} {c\\d}" shows "a c" over "b d". The
   command "\frac{a}{b}" shows a vertical fraction a/b.

   Also supported are commands to change font. The command
   "\font{name}{text}" changes the font text is written in to name. This may
   be useful if a symbol is missing from the current font, e.g.
   "\font{symbol}{g}" should produce a gamma. You can increase, decrease, or
   set the size of the font with "\size{+2}{text}", "\size{-2}{text}", or
   "\size{20}{text}". Numbers are in points.

   Various font attributes can be changed: for example, "\italic{some italic
   text}" (or use "\textit" or "\emph"), "\bold{some bold text}" (or use
   "\textbf") and "\underline{some underlined text}".

   Example text could include "Area / \pi (10^{-23} cm^{-2})", or
   "\pi\bold{g}".

   Veusz plots these symbols with Qt's unicode support. If your current font
   does not contain these symbols then you may get messy results. If you find
   this is the case, I highly recommend you to down load Microsoft's
   Corefonts (see [31]http://corefonts.sourceforge.net/).

   --------------------------------------------------------------------------

  Axis numbers

   The way numbers are shown on axes is chosen automatically. For standard
   numerical axes, values are shown with the "%Vg" formatting (see below).
   For date axes, an appropriate date formatting is used so that the interval
   shown is correct. A format can be given for an axis in the axis number
   formatting panel can be given to explicitly choose a format. Some examples
   are given in the drop down axis menu. Hold the mouse over the example for
   detail.

   C-style number formatting is used with a few Veusz specific extensions.
   Text can be mixed with format specifiers, which start with a "%" sign.
   Examples of C-style formatting include: "%.2f" (decimal number with two
   decimal places, e.g. 2.01), "%.3e" (scientific formatting with three
   decimal places, e.g. 2.123e-02), "%g" (general formatting, switching
   between "%f" and "%e" as appropriate). See
   [32]http://opengroup.org/onlinepubs/007908799/xsh/fprintf.html for
   details.

   Veusz extensions include "%Ve", which is like "%e" except it displays
   scientific notation as written, e.g. 1.2x10^23, rather than 1.2e+23. "%Vg"
   switches between standard numbers and Veusz scientific notation for large
   and small numbers. "%VE" using engineering SI suffixes to represent large
   or small numbers (e.g. 1000 is 1k).

   Veusz allows dates and times to be formatted using "%VDX" where "X" is one
   of the formatting characters for strftime (see
   [33]http://opengroup.org/onlinepubs/007908799/xsh/strftime.html for
   details). These include "a" for an abbreviated weekday name, "A" for full
   weekday name, "b" for abbreviated month name, "B" for full month name, "c"
   date and time representaiton, "d" day of month 01..31, "H" hour as 00..23,
   "I" hour as 01..12, "j" as day of year 001..366, "m" as month 01..12, "M"
   minute as 00..59, "p" AM/PM, "S" second 00..61, "U" week number of year
   00..53 (Sunday as first day of week), "w" weekday as decimal number 0..6,
   "W" week number of year (Monday as first day of week), "x" date
   representation, "X" time representation, "y" year without century 00..99
   and "Y" year. "%VDVS" is a special Veusz addon format which shows seconds
   and fractions of seconds (e.g. 12.2).

   --------------------------------------------------------------------------

Installation

   Please look at the Installation notes (INSTALL) for details on installing
   Veusz.

   --------------------------------------------------------------------------

The main window

   You should see the main window when you run Veusz (you can just type the
   veusz command in Unix).

   The Veusz window is split into several sections. At the top is the menu
   bar and tool bar. These work in the usual way to other applications.
   Sometimes options are disabled (greyed out) if they do not make sense to
   be used. If you hold your mouse over a button for a few seconds, you will
   usually get an explanation for what it does called a "tool tip".

   Below the main toolbar is a second toolbar for constructing the graph by
   adding widgets (on the left), and some editing buttons. The add widget
   buttons add the request widget to the currently selected widget in the
   selection window. The widgets are arranged in a tree-like structure.

   Below these toolbars and to the right is the plot window. This is where
   the current page of the current document is shown. You can adjust the size
   of the plot on the screen (the zoom factor) using the "View" menu or the
   zoom tool bar button (the magnifying glass). Initially you will not see a
   plot in the plot window, but you will see the Veusz logo. At the moment
   you cannot do much else with the window. In the future you will be able to
   click on items in the plot to modify them.

   To the left of the plot window is the selection window, and the properties
   and formatting windows. The properties window lets you edit various
   aspects of the selected widget (such as the minimum and maximum values on
   an axis). Changing these values should update the plot. The formatting
   lets you modify the appearance of the selected widget. There are a series
   of tabs for choosing what aspect to modify.

   The various windows can be "dragged" from the main window to "float" by
   themselves on the screen.

   To the bottom of the window is the console. This window is not shown by
   default, but can be enabled in the View menu. The console is a Veusz and
   Python command line console. To read about the commands available see
   [34]Commands. As this is a Python console, you can enter mathematical
   expressions (e.g. "1+2.0*cos(pi/4)") here and they will be evaluated when
   you press Enter. The usual special functions and the operators are
   supported. You can also assign results to variables (e.g. "a=1+2") for use
   later. The console also supports command history like many Unix shells.
   Press the up and down cursor keys to browse through the history. Command
   line completion is not available yet!

   In recent versions there also exists a dataset browsing window, by default
   to the right of the screen. This window allows you to view the datasets
   currently loaded, their dimensions and type. Hovering a mouse over the
   size of the dataset will give you a preview of the data.

   --------------------------------------------------------------------------

My first plot

   After opening Veusz, on the left of the main window, you will see a
   Document, containing a Page, which contains a Graph with its axes. The
   Graph is selected in the selection window. The toolbar above adds a new
   widget to the selected widget. If a widget cannot be added to a selected
   widget it is disabled. On opening a new document Veusz automatically adds
   a new Page and Graph (with axes) to the document.

   You will see something like this:

   Select the x axis which has been added to the document (click on "x" in
   the selection window). In the properties window you will see a variety of
   different properties you can modify. For instance you can enter a label
   for the axis by writing "Area (cm^{2})" in the box next to label and
   pressing enter. Veusz supports text in LaTeX-like form (without the dollar
   signs). Other important parameters is the "log" switch which switches
   between linear and logarithmic axes, and "min" and "max" which allow the
   user to specify the minimum and maximum values on the axes.

   The formatting dialog lets you edit various aspects of the graph
   appearance. For instance the "Line" tab allows you to edit the line of the
   axis. Click on "Line", then you can then modify its colour. Enter "green"
   instead of "black" and press enter. Try making the axis label bold.

   Now you can try plotting a function on the graph. If the graph, or its
   children are selected, you will then be able to click the "function"
   button at the top (a red curve on a graph). You will see a straight line
   (y=x) added to the plot. If you select "function1", you will be able to
   edit the functional form plotted and the style of its line. Change the
   function to "x**2" (x-squared).

   We will now try plotting data on the graph. Go to your favourite text
   editor and save the following data as test.dat:

   1     0.1   -0.12   1.1    0.1
   2.05  0.12  -0.14   4.08   0.12
   2.98  0.08  -0.1    2.9    0.11
   4.02  0.04  -0.1    15.3   1.0

   The first three columns are the x data to plot plus its asymmetric errors.
   The final two columns are the y data plus its symmetric errors. In Veusz,
   go to the "Data" menu and select "Import". Type the filename into the
   filename box, or use the "Browse..." button to search for the file. You
   will see a preview of the data pop up in the box below. Enter "x,+,- y,+-"
   into the descriptors edit box (note that commas and spaces in the
   descriptor are almost interchangeable in Veusz 1.6 or newer). This
   describes the format of the data which describes dataset "x" plus its
   asymmetric errors, and "y" with its symmetric errors. If you now click
   "Import", you will see it has imported datasets "x" and "y".

   To plot the data you should now click on "graph1" in the tree window. You
   are now able to click on the "xy" button (which looks like points plotted
   on a graph). You will see your data plotted on the graph. Veusz plots
   datasets "x" and "y" by default, but you can change these in the
   properties of the "xy" plotter.

   You are able to choose from a variety of markers to plot. You can remove
   the plot line by choosing the "Plot Line" subsetting, and clicking on the
   "hide" option. You can change the colour of the marker by going to the
   "Marker Fill" subsetting, and entering a new colour (e.g. red), into the
   colour property.

   --------------------------------------------------------------------------

                                  Reading data

   Currently Veusz supports reading data from a text file, FITS format files,
   CSV files, QDP files, binary files and NPY/NPZ files. Reading data is
   supported using the "Data, Import" dialog, or using the [35]ImportFile and
   [36]ImportString commands which read data from files or an existing Python
   string (allowing data to be embedded in a Python script). In addition, the
   user can load or write plugins in Python which load data into Veusz in an
   arbitrary format. At the moment QDP, binary and NPY/NPZ files are
   supported with this method.

   CSV files are intuitive to use and are described below.

   In addition data may also be read in from FITS files if the PyFITS Python
   module is installed. FITS is a widespread astronomical data format. FITS
   files are read using the FITS tab on the import dialog or using the
   [37]ImportFITSFile command.

   Two dimensional data are also supported using the 2D tab on the Import
   dialog box, [38]ImportFile2D and [39]ImportString2D commands.

   --------------------------------------------------------------------------

Descriptors

   The "Data, Import" dialog box, [40]ImportFile and [41]ImportString
   commands use a "Descriptor", or list of dataset names, to describe how the
   data are formatted in the import file. The descriptor at its simplest is a
   list of the names of the datasets to import (which are columns in the
   file). Additionally modifiers are added if error bars are also read in.
   Examples of descriptors are below:

    1. x y two columns are present in the file, they will be read in as
       datasets "x" and "y".

    2. x,+- y,+,- or x +- y + - two datasets are in the file. Dataset "x"
       consists of the first two columns. The first column are the values and
       the second are the symmetric errors. "y" consists of three columns
       (note the comma between + and -). The first column are the values, the
       second positive asymmetric errors, and the third negative asymmetric
       errors.

       Suppose the input file contains:

       1.0  0.3  2   0.1  -0.2
       1.5  0.2  2.3 2e-2 -0.3E0
       2.19 0.02 5    0.1 -0.1

       Then x will contain "1+-0.3", "1.5+-0.2", "2.19+-0.02". y will contain
       "2 +0.1 -0.2", "2.3 +0.02 -0.3", "5 +0.1 -0.1".

    3. x[1:2] y[:] the first column is the data "x_1", the second "x_2".
       Subsequent columns are read as "y[1]" to "y[n]".

    4. y[:]+- read each pair of columns as a dataset and its symmetric error,
       calling them "y[1]" to "y[n]".

    5. foo,,+- read the first column as the foo dataset, skip a column, and
       read the third column as its symmetric error.

   The dataset names given here x and y, are just representative. Dataset
   names can contain virtually any character, even unicode characters. If the
   name contains non alpha-numeric characters (characters outside of A-Z, a-z
   and 0-9), then the dataset name should be contained within back-tick
   characters. An example descriptor is `length data (m)`,+- `speed
   (mps)`,+,-, for two datasets with spaces and brackets in their names.

   The special names +-, + or - specify that the datasets before are followed
   by columns containing symmetric, positive or negative errors. The signs on
   positive or negative errors are automatically set to be correct.

   If a descriptor is left blank, Veusz will automatically create dataset
   names. If the prefix and suffix settings are blank, they are assigned
   names col1, col2, etc. If prefix and suffix are not blank, the datasets
   are called prefix+number+suffix.

   When reading in data, Veusz treats any whitespace as separating columns.
   The columns do not actually need to be in columns! Furthermore a "\"
   symbol can be placed at the end of a line to mark a continuation. Veusz
   will read the next line as if it were placed at the end of the current
   line. In addition comments and blank lines are ignored. Comments start
   with a "#", ";", "!" or "%", and continue until the end of the line. The
   special value "nan" can be used to specify a break in a dataset.

   Veusz supports reading in other types of data. The type of data can be
   added in round brackets after the name. Veusz will try to guess the type
   of data based on the first value, so you should specify it if there is any
   form of ambiguity (e.g. is 3 text or a number). Supported types are
   numbers (use numeric in brackets) and text (use text in brackets). An
   example descriptor would be "x(numeric) +- y(numeric) + - label(text)" for
   an x dataset followed by its symmetric errors, a y dataset followed by two
   columns of asymmetric errors, and a final column of text for the label
   dataset.

   A text column does not need quotation unless it contains space characters
   or escape characters. However make sure you deselect the "ignore text"
   option in the import dialog. This ignores lines of text to ease the import
   of data from other applications. Quotation marks are recommended around
   text if you wish to avoid ambiguity. Text is quoted according to the
   Python rules for text. Double or single quotation marks can be used, e.g.
   "A 'test'", 'A second "test"'. Quotes can be escaped by prefixing them
   with a backslash, e.g. "A new \"test\"". If the data are generated from a
   Python script, the repr function provides the text in a suitable form.

   Dates and times are also supported with the syntax "dataset(date)". Dates
   must be in ISO format YYYY-MM-DD. Times are in 24 hour format hh:mm:ss.ss.
   Dates with times are written YYYY-MM-DDThh:mm:ss.ss (this is a standard
   ISO format, see [42]http://www.w3.org/TR/NOTE-datetime). Dates are stored
   within Veusz as a number which is the number of seconds since the start of
   January 1st 2009. Veusz also supports dates and times in the local format,
   though take note that the same file and data may not work on a system in a
   different location.

   Data may be optionally split into "blocks" of data separated by blank
   lines (or the word "no" on a line, for obscure reasons). The name of each
   read in dataset has an underscore and the number of the block (starting
   from 1) added. This is specified by clicking the blocks checkbox in the
   import dialog, or by using the useblocks=True option on the [43]ImportFile
   or [44]ImportString commands.

   Instead of specifying the descriptor in the import dialog, the descriptor
   can be placed in the data file using a descriptor statement on a separate
   line, consisting of "descriptor" followed by the descriptor. Multiple
   descriptors can be placed in a single file, for example:

   # here is one section
   descriptor x,+- y,+,-
   1 0.5  2 0.1 -0.1
   2 0.3  4 0.2 -0.1

   # my next block
   descriptor alpha beta gamma
   1 2 3
   4 5 6
   7 8 9

   # etc...

   If data are imported from a file, Veusz will normally save the data in its
   saved document format. If the data are changing, quite often one wants to
   reread the data from the input file. This can be achieved using the
   "linked=True" option on the ImportFile command, or by clicking the "Link"
   checkbox in the import dialog.

   --------------------------------------------------------------------------

Reading CSV files

   CVS (comma separated variable) files are often written from other
   programs, such as spreadsheets, including Excel and Gnumeric. Veusz
   supports reading from these files.

   In the import dialog choose "CSV", then choose a filename to import from.
   In the CSV file the user should place the data in either rows or columns.
   Veusz will use a name above a column or to the left of a row to specify
   what the dataset name should be. The user can use new names further down
   in columns or right in rows to specify a different dataset name. Names do
   not have to be used, and Veusz will assign default "col" and "row" names
   if not given. You can also specify a prefix which is prepended to each
   dataset name read from the file.

   To specify symmetric errors for a column, put "+-" as the dataset name in
   the next column or row. Asymmetric errors can be stated with "+" and "-"
   in the columns.

   The data can be linked with the CSV file so that it can be updated when
   the file changes. See the example CSV import for details.

   The data type in CSV files are automatically detected unless specified.
   The data type can be given in brackets after the column name, e.g. "name
   (text)", where the data type is "date", "numeric" or "text". Explicit data
   types are needed if the data look like a different data type (e.g. a text
   item of "1.23"). The date format in CSV files can be specified in the
   import dialog box - see the examples given. In addition CSV files support
   numbers in European format (e.g. 2,34 rather than 2.34), depending on the
   setting in the dialog box.

   --------------------------------------------------------------------------

Reading FITS files

     1D or 2D data can be read from FITS files. 1D data, with optional errors
   bars, can be read from table extensions, and 2D data from image or primary
   extensions.

   --------------------------------------------------------------------------

Reading other data formats

   As mentioned above, a user may write some Python code to read a data file
   or set of data files. To write a plugin which is incorportated into Veusz,
   see [45]http://barmag.net/veusz-wiki/ImportPlugins

   You can also include Python code in an input file to read data, which we
   describe here. Suppose an input file "in.dat" contains the following data:

   1   2
   2   4
   3   9
   4   16

   Of course this data could be read using the [46]ImportFile command.
   However, you could also read it with the following Veusz script (which
   could be saved to a file and loaded with execfile or [47]Load. The script
   also places symmetric errors of 0.1 on the x dataset.

   x = []
   y = []
   for line in open("in.dat"):
       parts = [float(i) for i in line.split()]
       x.append(parts[0])
       y.append(parts[1])

   SetData('x', x, symerr=0.1)
   SetData('y', y)

   --------------------------------------------------------------------------

Manipulating datasets

   Imported datasets can easily be modified in the Edit data dialog box, by
   clicking on a value and entering a new one. What is probably more
   interesting is using the Create dialog box to make new datasets from
   scratch or based on other datasets.

   New datasets can be made by entering a name, and choosing whether to make
   a dataset consisting of a single value or over a range, from expressions
   based on a parametric expression, or from expressions based on existing
   datasets.

   --------------------------------------------------------------------------

  Using dataset plugins

   Dataset plugins can be used to perform arbitrary manipulation of datasets.
   Veusz includes several plugins for mathematical operation of data and
   other dataset manipulations, such as concatenation or splitting. If you
   wish to write your own plugins look at
   [48]http://barmag.net/veusz-wiki/DatasetPlugins.

   --------------------------------------------------------------------------

  Using expressions to create new datasets

   For instance, if the user has already imported dataset d, then they can
   create d2 which consists of d**2. Expressions are in Python numpy syntax
   and can include the usual mathematical functions.

   Expressions for error bars can also be given. By appending _data, _serr,
   _perr or _nerr to the name of the dataset in the expression, the user can
   base their expression on particular parts of the given dataset (the main
   data, symmetric errors, positive errors or negative errors). Otherwise the
   program uses the same parts as is currently being specified.

   If a dataset name contains non alphanumeric characters, its name should be
   quoted in the expression in back-tick characters, e.g. `length (cm)`*2.

   --------------------------------------------------------------------------

  Linking datasets to expressions

   A particularly useful feature is to be able to link a dataset to an
   expression, so if the expression changes the dataset changes with it, like
   in a spreadsheet.

   --------------------------------------------------------------------------

  Splitting data

   Data can also be chopped in this method, for example using the expression
   x[10:20], which makes a dataset based on the 11th to 20th item in the x
   dataset (the ranges are Python syntax, and are zero-based). Negative
   indices count backwards from the end of the dataset. Data can be skipped
   using expressions such as data[::2], which skips every other element

   --------------------------------------------------------------------------

  Defining new constants or functions

   User defined constants or functions can be defined in the "Custom
   definitions" dialog box under the edit menu. Functions can also be
   imported from external python modules.

   Custom definitions are defined on a per-document basis, but can be saved
   or loaded into a file. A default custom definitions file can be set in the
   preferences dialog box.

   --------------------------------------------------------------------------

  Dataset plugins

   In addition to creating datasets based on expressions, a variety of
   dataset plugins exist, which make certain operations on datasets much more
   convenient. See the Data, Operations menu for a list of the default
   plugins. The user can easily create new plugins. See
   [49]http://barmag.net/veusz-wiki/DatasetPlugins for details.

   --------------------------------------------------------------------------

                             Command line interface

Introduction

   An alternative way to control Veusz is via its command line interface. As
   Veusz is a a Python application it uses Python as its scripting language.
   Therefore you can freely mix Veusz and Python commands on the command
   line. Veusz can also read in Python scripts from files (see the [50]Load
   command).

   When commands are entered in the command prompt in the Veusz window, Veusz
   supports a simplified command syntax, where brackets following commands
   names, and commas, can replaced by spaces in Veusz commands (not Python
   commands). For example, Add('graph', name='foo'), may be entered as Add
   'graph' name='foo'.

   The numpy package is already imported into the command line interface (as
   "*"), so you do not need to import it first.

   The command prompt supports history (use the up and down cursor keys to
   recall previous commands).

   Most of the commands listed below can be used in the in-program command
   line interface, using the embedding interface or using veusz_listen.
   Commands specific to particular modes are documented as such.

   Veusz also includes a new object-oriented version of the interface, which
   is documented at [51]http://barmag.net/veusz-wiki/EmbeddingPython.

   --------------------------------------------------------------------------

Commands

   We list the allowed set of commands below

   --------------------------------------------------------------------------

  Action

   Action('actionname', componentpath='.')

   Initiates the specified action on the widget (component) given the action
   name. Actions perform certain automated routines. These include "fit" on a
   fit widget, and "zeroMargins" on grids.

   --------------------------------------------------------------------------

  Add

   Add('widgettype', name='nameforwidget', autoadd=True, optionalargs)

   The Add command adds a graph into the current widget (See the [52]To
   command to change the current position).

   The first argument is the type of widget to add. These include "graph",
   "page", "axis", "xy" and "grid". name is the name of the new widget (if
   not given, it will be generated from the type of the widget plus a
   number). The autoadd parameter if set, constructs the default sub-widgets
   this widget has (for example, axes in a graph).

   Optionally, default values for the graph settings may be given, for
   example Add('axis', name='y', direction='vertical').

   Subsettings may be set by using double underscores, for example Add('xy',
   MarkerFill__color='red', ErrorBarLine__hide=True).

   Returns: Name of widget added.

   --------------------------------------------------------------------------

  AddCustom

   AddCustom(type, name, value)

   Add a custom definition for evaluation of expressions. This can define a
   constant (can be in terms of other constants), a function of 1 or more
   variables, or a function imported from an external python module.

   ctype is "constant", "function" or "import".

   name is name of constant, or "function(x, y, ...)" or module name.

   val is definition for constant or function (both are _strings_), or is a
   list of symbols for a module (comma separated items in a string).

   If mode is 'appendalways', the custom value is appended to the end of the
   list even if there is one with the same name. If mode is 'replace', it
   replaces any existing definition in the same place in the list or is
   appended otherwise. If mode is 'append', then an existing definition is
   deleted, and the new one appended to the end.

   --------------------------------------------------------------------------

  AddImportPath

   AddImportPath(directory)

   Add a directory to the list of directories to try to import data from.

   --------------------------------------------------------------------------

  CloneWidget

   CloneWidget(widget, newparent, newname=None)

   Clone the widget given, placing the copy in newparent and the name given.
   newname is an optional new name to give it Returns new widget path.

   --------------------------------------------------------------------------

  Close

   Close()

   Closes the plotwindow. This is only supported in embedded mode.

   --------------------------------------------------------------------------

  CreateHistogram

   CreateHistogram(inexpr, outbinsds, outvalsds, binparams=None,
   binmanual=None, method='counts', cumulative = 'none', errors=False)

     Histogram an input expression. inexpr is input expression. outbinds is
   the name of the dataset to create giving bin positions. outvalsds is name
   of dataset for bin values. binparams is None or (numbins, minval, maxval,
   islogbins). binmanual is None or a list of bin values. method is 'counts',
   'density', or 'fractions'. cumulative is to calculate cumulative
   distributions which is 'none', 'smalltolarge' or 'largetosmall'. errors is
   to calculate Poisson error bars.

   --------------------------------------------------------------------------

  DatasetPlugin

   DatasetPlugin(pluginname, fields, datasetnames={})>

     Use a dataset plugin. pluginname: name of plugin to use fields: dict of
   input values to plugin datasetnames: dict mapping old names to new names
   of datasets if they are renamed. The new name None means dataset is
   deleted

   --------------------------------------------------------------------------

  EnableToolbar

   EnableToolbar(enable=True)

   Enable/disable the zooming toolbar in the plotwindow. This command is only
   supported in embedded mode or from veusz_listen.

   --------------------------------------------------------------------------

  Export

   Export(filename, color=True, page=0 dpi=100, antialias=True, quality=85,
   backcolor='#ffffff00', pdfdpi=150)

   Export the page given to the filename given. The filename must end with
   the correct extension to get the right sort of output file. Currrenly
   supported extensions are '.eps', '.pdf', '.svg', '.jpg', '.jpeg', '.bmp'
   and '.png'. If color is True, then the output is in colour, else
   greyscale. page is the page number of the document to export (starting
   from 0 for the first page!). dpi is the number of dots per inch for bitmap
   output files. antialias - antialiases output if True. quality is a quality
   parameter for jpeg output. backcolor is the background color for bitmap
   files, which is a name or a #RRGGBBAA value (red, green, blue, alpha).
   pdfdpi is the dpi to use when exporting EPS or PDF files.

   --------------------------------------------------------------------------

  ForceUpdate

   ForceUpdate()

   Force the window to be updated to reflect the current state of the
   document. Often used when periodic updates have been disabled (see
   SetUpdateInterval). This command is only supported in embedded mode or
   from veusz_listen.

   --------------------------------------------------------------------------

  Get

   Get('settingpath')

   Returns: The value of the setting given by the path.

   >>> Get('/page1/graph1/x/min')
   'Auto'

   --------------------------------------------------------------------------

  GetChildren

   GetChildren(where='.')

   Returns: The names of the widgets which are children of the path given

   --------------------------------------------------------------------------

  GetClick

   GetClick()

   Waits for the user to click on a graph and returns the position of the
   click on appropriate axes. Command only works in embedded mode.

   Returns: A list containing tuples of the form (axispath, val) for each
   axis for which the click was in range. The value is the value on the axis
   for the click.

   --------------------------------------------------------------------------

  GetData

   GetData(name)

   Returns: A tuple containing the dataset with the name given. If name
   refers to numpy array data, the tuple is (data, symerr, negerr, poserr),
   with each a numpy array of the same size or None. data are the values of
   the dataset, symerr are the symmetric errors (if set), negerr and poserr
   and negative and positive asymmetric errors (if set). If name refers to a
   text dataset, a list of text elements is returned.

   data = GetData('x')
   SetData('x', data[0]*0.1, *data[1:])

   --------------------------------------------------------------------------

  GetDatasets

   GetDatasets()

   Returns: The names of the datasets in the current document.

   --------------------------------------------------------------------------

  GPL

   GPL()

   Print out the GNU Public Licence, which Veusz is licenced under.

   --------------------------------------------------------------------------

  ImportFile

   ImportFile('filename', 'descriptor', linked=False, prefix='', suffix='',
   encoding='utf_8')

   Imports data from a file. The arguments are the filename to load data from
   and the descriptor.

   The format of the descriptor is a list of variable names representing the
   columns of the data. For more information see [53]Descriptors.

   If the linked parameter is set to True, if the document is saved, the data
   imported will not be saved with the document, but will be reread from the
   filename given the next time the document is opened. The linked parameter
   is optional.

   If prefix and/or suffix are set, then the prefix and suffix are added to
   each dataset name.

   Returns: A tuple containing a list of the imported datasets and the number
   of conversions which failed for a dataset.

   Changed in version 0.5: A tuple is returned rather than just the number of
   imported variables.

   --------------------------------------------------------------------------

  ImportFile2D

   ImportFile2D('filename', datasets, xrange=(a,b), yrange=(c,d),
   invertrows=True/False, invertcols=True/False, transpose=True/False,
   prefix='', suffix='', linked=False, encoding='utf8')

   Imports two-dimensional data from a file. The required arguments are the
   filename to load data from and the dataset name, or a list of names to
   use.

   filename is a string which contains the filename to use. datasets is
   either a string (for a single dataset), or a list of strings (for multiple
   datasets).

   The xrange parameter is a tuple which contains the range of the X-axis
   along the two-dimensional dataset, for example (-1., 1.) represents an
   inclusive range of -1 to 1. The yrange parameter specifies the range of
   the Y-axis similarly. If they are not specified, (0, N) is the default,
   where N is the number of datapoints along a particular axis.

   invertrows and invertcols if set to True, invert the rows and columns
   respectively after they are read by Veusz. transpose swaps the rows and
   columns.

   If prefix and/or suffix are set, they are prepended or appended to
   imported dataset names.

   If the linked parameter is True, then the datasets are linked to the
   imported file, and are not saved within a saved document.

   The file format this command accepts is a two-dimensional matrix of
   numbers, with the columns separated by spaces or tabs, and the rows
   separated by new lines. The X-coordinate is taken to be in the direction
   of the columns. Comments are supported (use "#", "!" or "%"), as are
   continuation characters ("\"). Separate datasets are deliminated by using
   blank lines.

   In addition to the matrix of numbers, the various optional parameters this
   command takes can also be specified in the data file. These commands
   should be given on separate lines before the matrix of numbers. They are:

    1. xrange A B

    2. yrange C D

    3. invertrows

    4. invertcols

    5. transpose

   --------------------------------------------------------------------------

  ImportFileCSV

   ImportFileCSV('filename', readrows=False, dsprefix='', dssuffix='',
   linked=False, encoding='utf_8')

   This command imports data from a CSV format file. Data are read from the
   file using the dataset names given at the top of the files in columns.
   Please see the reading data section of this manual for more information.
   dsprefix is prepended to each dataset name and dssuffix is added (the
   prefix option is deprecated and also addeds an underscore to the dataset
   name). linked specifies whether the data will be linked to the file.

   --------------------------------------------------------------------------

  ImportFilePlugin

   ImportFilePlugin('pluginname', 'filename', **pluginargs, linked=False,
   encoding='utf_8', prefix='', suffix='')

     Import data from file using import plugin 'pluginname'. The arguments to
   the plugin are given, plus optionally a text encoding, and prefix and
   suffix to prepend or append to dataset names.

   --------------------------------------------------------------------------

  ImportFITSFile

   ImportFITSFile(datasetname, filename, hdu, datacol='A', symerrcol='B',
   poserrcol='C', negerrcol='D', linked=True/False)

   This command does a simple import from a FITS file. The FITS format is
   used within the astronomical community to transport binary data. For a
   more powerful FITS interface, you can use PyFITS within your scripts.

   The datasetname is the name of the dataset to import, the filename is the
   name of the FITS file to import from. The hdu parameter specifies the HDU
   to import data from (numerical or a name).

   If the HDU specified is a primary HDU or image extension, then a
   two-dimensional dataset is loaded from the file. The optional parameters
   (other than linked) are ignored. Any WCS information within the HDU are
   used to provide a suitable xrange and yrange.

   If the HDU is a table, then the datacol parameter must be specified (and
   optionally symerrcol, poserrcol and negerrcol). The dataset is read in
   from the named column in the table. Any errors are read in from the other
   specified columns.

   If linked is True, then the dataset is not saved with a saved document,
   but is reread from the data file each time the document is loaded.

   --------------------------------------------------------------------------

  ImportString

   ImportString('descriptor', 'data')

   Like, [54]ImportFile, but loads the data from the specfied string rather
   than a file. This allows data to be easily embedded within a document. The
   data string is usually a multi-line Python string.

   Returns: A tuple containing a list of the imported datasets and the number
   of conversions which failed for a dataset.

   Changed in version 0.5: A tuple is returned rather than just the number of
   imported variables.

   ImportString('x y', '''
   1   2
   2   5
   3   10
   ''')

   --------------------------------------------------------------------------

  ImportString2D

   ImportString2D(datasets, string)

   Imports a two-dimensional dataset from the string given. This is similar
   to the [55]ImportFile2D command, with the same dataset format within the
   string. This command, however, does not currently take any optional
   parameters. The various controlling parameters can be set within the
   string. See the [56]ImportFile2D section for details.

   --------------------------------------------------------------------------

  IsClosed

   IsClosed()

   Returns a boolean value telling the caller whether the plotting window has
   been closed.

   Note: this command is only supported in the embedding interface.

   --------------------------------------------------------------------------

  List

   List(where='.')

   List the widgets which are contained within the widget with the path
   given, the type of widgets, and a brief description.

   --------------------------------------------------------------------------

  Load

   Load('filename.vsz')

   Loads the veusz script file given. The script file can be any Python code.
   The code is executed using the Veusz interpreter.

   Note: this command is only supported at the command line and not in a
   script. Scripts may use the python execfile function instead.

   --------------------------------------------------------------------------

  MoveToPage

   MoveToPage(pagenum)

   Updates window to show the page number given of the document.

   Note: this command is only supported in the embedding interface or
   veusz_listen.

   --------------------------------------------------------------------------

  ReloadData

   ReloadData()

   Reload any datasets which have been linked to files.

   Returns: A tuple containing a list of the imported datasets and the number
   of conversions which failed for a dataset.

   --------------------------------------------------------------------------

  Rename

   Remove('widgetpath', 'newname')

   Rename the widget at the path given to a new name. This command does not
   move widgets. See [57]To for a description of the path syntax. '.' can be
   used to select the current widget.

   --------------------------------------------------------------------------

  Remove

   Remove('widgetpath')

   Remove the widget selected using the path. See [58]To for a description of
   the path syntax.

   --------------------------------------------------------------------------

  ResizeWindow

   ResizeWindow(width, height)

   Resizes window to be width by height pixels.

   Note: this command is only supported in the embedding interface or
   veusz_listen.

   --------------------------------------------------------------------------

  Save

   Save('filename.vsz')

   Save the current document under the filename given.

   --------------------------------------------------------------------------

  Set

   Set('settingpath', val)

   Set the setting given by the path to the value given. If the type of val
   is incorrect, an InvalidType exception is thrown. The path to the setting
   is the optional path to the widget the setting is contained within, an
   optional subsetting specifier, and the setting itself.

   Set('page1/graph1/x/min', -10.)

   --------------------------------------------------------------------------

  SetAntiAliasing

   SetAntiAliasing(on)

   Enable or disable anti aliasing in the plot window, replotting the image.

   --------------------------------------------------------------------------

  SetData

   SetData(name, val, symerr=None, negerr=None, poserr=None)

   Set the dataset name with the values given. If None is given for an item,
   it will be left blank. val is the actual data, symerr are the symmetric
   errors, negerr and poserr and the getative and positive asymmetric errors.
   The data can be given as lists or numpys.

   --------------------------------------------------------------------------

  SetDataExpression

   SetDataExpression(name, val, symerr=None, negerr=None, poserr=None,
   linked=False, parametric=None)

   Create a new dataset based on the expressions given. The expressions are
   Python syntax expressions based on existing datasets.

   If linked is True, the dataset will change as the datasets in the
   expressions change.

   Parametric can be set to a tuple of (minval, maxval, numitems). t in the
   expression will iterate from minval to maxval in numitems values.

   --------------------------------------------------------------------------

  SetDataRange

   SetDataRange(name, numsteps, val, symerr=None, negerr=None, poserr=None,
   linked=False)

   Set dataset to be a range of values with numsteps steps. val is tuple made
   up of (minimum value, maximum value). symerr, negerr and poserr are
   optional tuples for the error bars.

   If linked is True, the dataset can be saved in a document as a
   SetDataRange, otherwise it is expanded to the values which would make it
   up.

   --------------------------------------------------------------------------

  SetData2D

   SetData2D('name', val, xrange=(A,B), yrange=(C,D))

   Creates a two-dimensional dataset with the name given. val is either a
   two-dimensional numpy array, or is a list of lists, with each list in the
   list representing a row.

   xrange and yrange are optional tuples giving the inclusive range of the X
   and Y coordinates of the data.

   --------------------------------------------------------------------------

  SetData2DExpression

   SetData2D('name', expr, linked=False)

   Create a 2D dataset based on expressions. name is the new dataset name
   expr is an expression which should return a 2D array linked specifies
   whether to permanently link the dataset to the expressions.

   --------------------------------------------------------------------------

  SetData2DExpressionXYZ

   SetData2DExpressionXYZ('name', 'xexpr', 'yexpr', 'zexpr', linked=False)

   Create a 2D dataset based on three 1D expressions. The x, y expressions
   need to evaluate to a grid of x, y points, with the z expression as the 2D
   value at that point. Currently only linear fixed grids are supported. This
   function is intended to convert calculations or measurements at fixed
   points into a 2D dataset easily. Missing values are filled with NaN.

   --------------------------------------------------------------------------

  SetData2DXYFunc

   SetData2DXYFunc('name', xstep, ystep, 'expr', linked=False)

   Construct a 2D dataset using a mathematical expression of "x" and "y". The
   x values are specified as (min, max, step) in xstep as a tuple, the y
   values similarly. If linked remains as False, then a real 2D dataset is
   created, where values can be modified and the data are stored in the saved
   file.

   --------------------------------------------------------------------------

  SetDataText

   SetDataText(name, val)

   Set the text dataset name with the values given. val must be a type that
   can be converted into a Python list.

   SetDataText('mylabel', ['oranges', 'apples', 'pears', 'spam'])

   --------------------------------------------------------------------------

  SetToReference

   SetToReference(setting, refval)

   Set setting to match other setting refval always..

   --------------------------------------------------------------------------

  SetUpdateInterval

   SetUpdateInterval(interval)

   Tells window to update every interval milliseconds at most. The value 0
   disables updates until this function is called with a non-zero. The value
   -1 tells Veusz to update the window every time the document has changed.
   This will make things slow if repeated changes are made to the document.
   Disabling updates and using the ForceUpdate command will allow the user to
   control updates directly.

   Note: this command is only supported in the embedding interface or
   veusz_listen.

   --------------------------------------------------------------------------

  SetVerbose

   SetVerbose(v=True)

   If v is True, then extra information is printed out by commands.

   --------------------------------------------------------------------------

  StartSecondView

   StartSecondView(name = 'window title')

   In the embedding interface, this method will open a new Embedding
   interface onto the same document, returning the object. This new window
   provides a second view onto the document. It can, for instance, show a
   different page to the primary view. name is a window title for the new
   window.

   Note: this command is only supported in the embedding interface.

   --------------------------------------------------------------------------

  To

   To('widgetpath')

   The To command takes a path to a widget and moves to that widget. For
   example, this may be "/", the root widget, "graph1", "/page1/graph1/x",
   "../x". The syntax is designed to mimic Unix paths for files. "/"
   represents the base widget (where the pages reside), and ".." represents
   the widget next up the tree.

   --------------------------------------------------------------------------

  Quit

   Quit()

   Quits Veusz. This is only supported in veusz_listen.

   --------------------------------------------------------------------------

  WaitForClose

   WaitForClose()

   Wait until the plotting window has been closed.

   Note: this command is only supported in the embedding interface.

   --------------------------------------------------------------------------

  Zoom

   Zoom(factor)

   Sets the plot zoom factor, relative to a 1:1 scaling. factor can also be
   "width", "height" or "page", to zoom to the page width, height or page,
   respectively.

   This is only supported in embedded mode or veusz_listen.

   --------------------------------------------------------------------------

Security

   With the 1.0 release of Veusz, input scripts and expressions are checked
   for possible security risks. Only a limited subset of Python functionality
   is allowed, or a dialog box is opened allowing the user to cancel the
   operation. Specifically you cannot import modules, get attributes of
   Python objects, access globals() or locals() or do any sort of file
   reading or manipulation. Basically anything which might break in Veusz or
   modify a system is not supported. In addition internal Veusz functions
   which can modify a system are also warned against, specifically Print(),
   Save() and Export().

   If you are running your own scripts and do not want to be bothered by
   these dialogs, you can run veusz with the --unsafe-mode option.

   --------------------------------------------------------------------------

                        Using Veusz from other programs

Non-Qt Python programs

   Veusz supports being embedded within other Python programs. The calling
   program can open up any number of plot windows, and manipulate the graphs
   using the Veusz scripting commands, which are exposed as methods of graph
   objects.

   Using the embedding interface, a Python program can create multiple Veusz
   plot windows showing the same or different documents. The standard Veusz
   operations are supported with the addition of a few specific commands.

   The embedding interface runs Veusz in a second process, sending the
   commands over a pipe.

   Veusz must be installed in the PYTHONPATH for embedding to work. This can
   be done with the setup.py distutils script. An example embedding program
   is in examples/embedexample.py.

   An example Python program embedding Veusz is below:

   import time
   import numpy
   import veusz.embed as veusz

   g = veusz.Embedded('new window title')
   g.To( g.Add('page') )
   g.To( g.Add('graph') )
   g.SetData('x', numpy.arange(20))
   g.SetData('y', numpy.arange(20)**2)
   g.Add('xy')
   g.Zoom(0.5)

   # wait 20 seconds
   time.sleep(20)

   win2 = veusz.Embedded('second window example')
   win2.To( win2.Add('page') )
   win2.To( win2.Add('graph') )
   win2.Add('function', function='x**2')
   win2.Set('x/label', 'An example axis \\emph{label}')

   time.sleep(20)

   g.Close()

   The supported commands are the same as in [59]Commands, with the addition
   of: Close, EnableToolbar, MoveToPage, ResizeWindow, SetUpdateInterval,
   StartSecondView and Zoom.

   --------------------------------------------------------------------------

PyQt4 programs

   There is no direct PyQt4 interface. The standard embedding interface
   should work, however.

   --------------------------------------------------------------------------

Non Python programs

   Support for non Python programs is available in a limited form. External
   programs may execute the veusz_listen executable or veusz_listen.py Python
   module. Veusz will read its input from the standard input, and write
   output to standard output. This is a full Python execution environment,
   and supports all the scripting commands mentioned in [60]Commands, a
   Quit() command, the EnableToolbar() and the Zoom(factor) command listed
   above. Only one window is supported at once, but many veusz_listen
   programs may be started.

   veusz_listen may be used from the shell command line by doing something
   like:

   veusz_listen < in.vsz

   where in.vsz contains:

   To(Add('page') )
   To(Add('graph') )
   SetData('x', arange(20))
   SetData('y', arange(20)**2)
   Add('xy')
   Zoom(0.5)
   Export("foo.eps")
   Quit()

   A program may interface with Veusz in this way by using the popen C Unix
   function, which allows a program to be started having control of its
   standard input and output. Veusz can then be controlled by writing
   commands to an input pipe.

   --------------------------------------------------------------------------

C, C++ and Fortran

   A callable library interface to Veusz is on my todo list for C, C++ and
   Fortran. Please tell me if you would be interested in this option.

References

   Visible links
   1. http://www.gnu.org/licenses/gpl-2.0.html
   2. file:///tmp/html-aDqnAR#AEN13
   3. file:///tmp/html-aDqnAR#AEN15
   4. file:///tmp/html-aDqnAR#AEN22
   5. file:///tmp/html-aDqnAR#AEN25
   6. file:///tmp/html-aDqnAR#AEN108
   7. file:///tmp/html-aDqnAR#AEN111
   8. file:///tmp/html-aDqnAR#AEN129
   9. file:///tmp/html-aDqnAR#AEN137
  10. file:///tmp/html-aDqnAR#AEN140
  11. file:///tmp/html-aDqnAR#AEN154
  12. file:///tmp/html-aDqnAR#AEN170
  13. file:///tmp/html-aDqnAR#AEN230
  14. file:///tmp/html-aDqnAR#AEN237
  15. file:///tmp/html-aDqnAR#AEN240
  16. file:///tmp/html-aDqnAR#AEN253
  17. file:///tmp/html-aDqnAR#AEN257
  18. file:///tmp/html-aDqnAR#AEN261
  19. file:///tmp/html-aDqnAR#AEN274
  20. file:///tmp/html-aDqnAR#AEN277
  21. file:///tmp/html-aDqnAR#AEN282
  22. file:///tmp/html-aDqnAR#AEN289
  23. file:///tmp/html-aDqnAR#AEN296
  24. file:///tmp/html-aDqnAR#AEN309
  25. file:///tmp/html-aDqnAR#AEN707
  26. file:///tmp/html-aDqnAR#AEN712
  27. file:///tmp/html-aDqnAR#AEN714
  28. file:///tmp/html-aDqnAR#AEN727
  29. file:///tmp/html-aDqnAR#AEN730
  30. file:///tmp/html-aDqnAR#AEN750
  31. http://corefonts.sourceforge.net/
  32. http://opengroup.org/onlinepubs/007908799/xsh/fprintf.html
  33. http://opengroup.org/onlinepubs/007908799/xsh/strftime.html
  34. file:///tmp/html-aDqnAR#Commands
  35. file:///tmp/html-aDqnAR#Command.ImportFile
  36. file:///tmp/html-aDqnAR#Command.ImportString
  37. file:///tmp/html-aDqnAR#Command.ImportFITSFile
  38. file:///tmp/html-aDqnAR#Command.ImportFile2D
  39. file:///tmp/html-aDqnAR#Command.ImportString2D
  40. file:///tmp/html-aDqnAR#Command.ImportFile
  41. file:///tmp/html-aDqnAR#Command.ImportString
  42. http://www.w3.org/TR/NOTE-datetime
  43. file:///tmp/html-aDqnAR#Command.ImportFile
  44. file:///tmp/html-aDqnAR#Command.ImportString
  45. http://barmag.net/veusz-wiki/ImportPlugins
  46. file:///tmp/html-aDqnAR#Command.ImportFile
  47. file:///tmp/html-aDqnAR#Command.Load
  48. http://barmag.net/veusz-wiki/DatasetPlugins
  49. http://barmag.net/veusz-wiki/DatasetPlugins
  50. file:///tmp/html-aDqnAR#Command.Load
  51. http://barmag.net/veusz-wiki/EmbeddingPython
  52. file:///tmp/html-aDqnAR#Command.To
  53. file:///tmp/html-aDqnAR#Descriptors
  54. file:///tmp/html-aDqnAR#Command.ImportFile
  55. file:///tmp/html-aDqnAR#Command.ImportFile2D
  56. file:///tmp/html-aDqnAR#Command.ImportFile2D
  57. file:///tmp/html-aDqnAR#Command.To
  58. file:///tmp/html-aDqnAR#Command.To
  59. file:///tmp/html-aDqnAR#Commands
  60. file:///tmp/html-aDqnAR#Commands
