"Fossies" - the Fresh Open Source Software Archive

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


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

    1 <title>Scripting</title>
    2 <indexterm><primary>Scripting</primary></indexterm>
    3 
    4   <para>&appname; supports different interpreters
    5   for evaluating mathematical expressions and for executing scripts.</para>
    6 
    7   <sect1 id="sec-muParser">
    8     <title>muParser</title>
    9     <indexterm><primary>Scripting</primary><secondary>MuParser</secondary></indexterm>
   10     <para>The constants _e=e=E and _pi=pi=PI=Pi are defined, as well as the
   11          operators and functions listed below. muParser is purely a parser for mathematical
   12          expressions and as such does not support executing complex scripts. However,
   13          you can make formulas easier to read and modify by assigning sub-expressions to
   14          variables and inserting comments.
   15      </para>
   16      <para><emphasis>Variable assignments</emphasis> evaluate to the assigned value, so
   17          they can be used in the middle of a formula. They can also stand on a line of
   18          their own, or separated from other parts of the formula by a semicolon (;).
   19          The result of evaluating the last line of a multi-line formula is taken as the
   20          result of the whole formula.
   21      </para>
   22      <para><emphasis>Comments</emphasis> start with a hash mark (#) and run till the end
   23          of the line.</para>
   24      <para>It is important to note that the muParser commands listed in this section are 
   25         intended to be used to work inside the <emphasis>Formula</emphasis> tab of 
   26         a <emphasis>Table</emphasis>, i.e. most of them will not work as a 
   27         <emphasis>script</emphasis> in a <emphasis>Note</emphasis>. Of course, if
   28         one try to execute something like 'a=cos(pi*pi)' in a <emphasis>Note</emphasis>, 
   29         it will run without errors, but the 'a' value will not be known by the user.
   30      </para>
   31 
   32     <table frame="sides" pgwide="1" tocentry="1">
   33       <title>Supported Mathematical Operators</title>
   34 
   35       <tgroup cols="2">
   36         <colspec align="left" colname="name" colwidth="1*" />
   37 
   38         <colspec align="justify" colname="description" colwidth="10*" />
   39 
   40         <thead>
   41           <row>
   42             <entry>Name</entry>
   43 
   44             <entry>Description</entry>
   45           </row>
   46         </thead>
   47 
   48         <tbody>
   49           <row>
   50             <entry>+</entry>
   51 
   52             <entry>Addition</entry>
   53           </row>
   54 
   55           <row>
   56             <entry>-</entry>
   57 
   58             <entry>Subtraction</entry>
   59           </row>
   60 
   61           <row>
   62             <entry>*</entry>
   63 
   64             <entry>Multiplication</entry>
   65           </row>
   66 
   67           <row>
   68             <entry>/</entry>
   69 
   70             <entry>Division</entry>
   71           </row>
   72 
   73           <row>
   74             <entry>^</entry>
   75 
   76             <entry>Exponentiation (raise a to the power of b)</entry>
   77           </row>
   78 
   79           <row>
   80             <entry>and</entry>
   81 
   82             <entry>logical and (returns 0 or 1) - works only if SciDAVis is built using muParser 1.x versions</entry>
   83           </row>
   84 
   85           <row>
   86             <entry>&amp;&amp;</entry>
   87 
   88             <entry>logical and (returns 0 or 1) - works only if SciDAVis is built using muParser &gt;= 2.0.0</entry>
   89           </row>
   90 
   91           <row>
   92             <entry>or</entry>
   93 
   94             <entry>logical or (returns 0 or 1) - works only if SciDAVis is built using muParser 1.x versions</entry>
   95           </row>
   96 
   97           <row>
   98             <entry>||</entry>
   99 
  100             <entry>logical or (returns 0 or 1) - works only if SciDAVis is built using muParser &gt;= 2.0.0</entry>
  101           </row>
  102 
  103           <row>
  104             <entry>xor</entry>
  105 
  106         <entry>logical exclusive or (returns 0 or 1) - works only if SciDAVis is built using muParser 1.x versions; there are no equivalent operator for muParser &gt;= 2.0.0</entry>
  107           </row>
  108 
  109           <row>
  110             <entry>&lt;</entry>
  111 
  112             <entry>less then (returns 0 or 1)</entry>
  113           </row>
  114 
  115           <row>
  116             <entry>&lt;=</entry>
  117 
  118             <entry>less then or equal (returns 0 or 1)</entry>
  119           </row>
  120 
  121           <row>
  122             <entry>==</entry>
  123 
  124             <entry>equal (returns 0 or 1)</entry>
  125           </row>
  126 
  127           <row>
  128             <entry>&gt;=</entry>
  129 
  130             <entry>greater then or equal (returns 0 or 1)</entry>
  131           </row>
  132 
  133           <row>
  134             <entry>&gt;</entry>
  135 
  136             <entry>greater then (returns 0 or 1)</entry>
  137           </row>
  138 
  139           <row>
  140             <entry>!=</entry>
  141 
  142             <entry>not equal (returns 0 or 1)</entry>
  143           </row>
  144         </tbody>
  145       </tgroup>
  146     </table>
  147 
  148       <table frame="sides" pgwide="1" tocentry="1">
  149         <title>Mathematical Functions</title>
  150 
  151         <tgroup cols="2">
  152           <colspec align="left" colname="name" colwidth="1*" />
  153 
  154           <colspec align="justify" colname="description" colwidth="10*" />
  155 
  156           <thead>
  157             <row>
  158               <entry>Name</entry>
  159 
  160               <entry>Description</entry>
  161             </row>
  162           </thead>
  163 
  164           <tbody>
  165             <row>
  166               <entry>abs(x)</entry>
  167 
  168               <entry>absolute value of x</entry>
  169             </row>
  170 
  171             <row>
  172               <entry>acos(x)</entry>
  173 
  174               <entry>inverse cosine</entry>
  175             </row>
  176 
  177             <row>
  178               <entry>acosh(x)</entry>
  179 
  180               <entry>inverse hyperbolic cosine</entry>
  181             </row>
  182 
  183             <row>
  184               <entry>asin(x)</entry>
  185 
  186               <entry>inverse sine</entry>
  187             </row>
  188 
  189             <row>
  190               <entry>asinh(x)</entry>
  191 
  192               <entry>inverse hyperbolic sine</entry>
  193             </row>
  194 
  195             <row>
  196               <entry>atan(x)</entry>
  197 
  198               <entry>inverse tangent</entry>
  199             </row>
  200 
  201             <row>
  202               <entry>atanh(x)</entry>
  203 
  204               <entry>inverse hyperbolic tangent</entry>
  205             </row>
  206 
  207             <row>
  208               <entry>avg(x1,x2,x3,...)</entry>
  209 
  210               <entry>average value, this command accept a list of arguments
  211               separated by commas</entry>
  212             </row>
  213 
  214             <row>
  215               <entry>bessel_j0(x)</entry>
  216 
  217               <entry>Regular cylindrical Bessel function of zeroth order,
  218               J<subscript>0</subscript>(x).</entry>
  219             </row>
  220 
  221             <row>
  222               <entry>bessel_j1(x)</entry>
  223 
  224               <entry>Regular cylindrical Bessel function of first order,
  225               J<subscript>1</subscript>(x).</entry>
  226             </row>
  227 
  228             <row>
  229               <entry>bessel_jn(x,n)</entry>
  230 
  231               <entry>Regular cylindrical Bessel function of
  232               n<superscript>th</superscript> order,
  233               J<subscript>n</subscript>(x).</entry>
  234             </row>
  235 
  236                 <row>
  237                     <entry>bessel_jn_zero(n, s)</entry>
  238                     <entry>s<superscript>th</superscript> zero of regular cylindrical Bessel function
  239                         of n<superscript>th</superscript> order,
  240                         J<subscript>n</subscript>(bessel_jn_zero(n,s))=0
  241                     </entry>
  242                 </row>
  243 
  244             <row>
  245               <entry>bessel_y0(x)</entry>
  246 
  247               <entry>Irregular cylindrical Bessel function of zeroth order,
  248               Y<subscript>0</subscript>(x) for x&gt;0.</entry>
  249             </row>
  250 
  251             <row>
  252               <entry>bessel_y1(x)</entry>
  253 
  254               <entry>Irregular cylindrical Bessel function of first order,
  255               Y<subscript>1</subscript>(x) for x&gt;0.</entry>
  256             </row>
  257 
  258             <row>
  259               <entry>bessel_yn(x,n)</entry>
  260 
  261               <entry>Irregular cylindrical Bessel function of
  262               n<superscript>th</superscript> order,
  263               Y<subscript>n</subscript>(x) for x&gt;0.</entry>
  264             </row>
  265 
  266             <row>
  267               <entry>beta (a,b)</entry>
  268 
  269               <entry>Computes the Beta Function, B(a,b) =
  270               Gamma(a)*Gamma(b)/Gamma(a+b) for a &gt; 0 and b &gt; 0.</entry>
  271             </row>
  272 
  273             <row>
  274               <entry>ceil(x)</entry>
  275 
  276               <entry>ceiling; smallest integer greater or equal to x</entry>
  277             </row>
  278 
  279             <row>
  280               <entry>cos(x)</entry>
  281 
  282               <entry>cosine of x</entry>
  283             </row>
  284 
  285             <row>
  286               <entry>cosh(x)</entry>
  287 
  288               <entry>hyperbolic cosine of x</entry>
  289             </row>
  290 
  291             <row>
  292               <entry>erf(x)</entry>
  293 
  294               <entry>error function of x</entry>
  295             </row>
  296 
  297             <row>
  298               <entry>erfc(x)</entry>
  299 
  300               <entry>Complementary error function erfc(x) = 1 -
  301               erf(x).</entry>
  302             </row>
  303 
  304             <row>
  305               <entry>erfz(x)</entry>
  306 
  307               <entry>The Gaussian probability density function Z(x).</entry>
  308             </row>
  309 
  310             <row>
  311               <entry>erfq(x)</entry>
  312 
  313               <entry>The upper tail of the Gaussian probability function
  314               Q(x).</entry>
  315             </row>
  316 
  317             <row>
  318               <entry>exp(x)</entry>
  319 
  320               <entry>Exponential function: e raised to the power of x.</entry>
  321             </row>
  322 
  323             <row>
  324               <entry>floor(x)</entry>
  325 
  326               <entry>floor; largest integer less than or equal to x</entry>
  327             </row>
  328 
  329             <row>
  330               <entry>gamma(x)</entry>
  331 
  332               <entry>Computes the Gamma function, subject to x not being a
  333               negative integer</entry>
  334             </row>
  335 
  336             <row>
  337               <entry>gammaln(x)</entry>
  338 
  339               <entry>Computes the logarithm of the Gamma function, subject to
  340               x not a being negative integer. For x&lt;0, log(|Gamma(x)|) is
  341               returned.</entry>
  342             </row>
  343 
  344             <row>
  345               <entry>hazard(x)</entry>
  346 
  347               <entry>Computes the hazard function for the normal distribution
  348               h(x) = erfz(x)/erfq(x).</entry>
  349             </row>
  350 
  351             <row>
  352               <entry>ln(x)</entry>
  353 
  354               <entry>natural logarithm of x</entry>
  355             </row>
  356 
  357             <row>
  358               <entry>log(x)</entry>
  359 
  360               <entry>decimal logarithm of x</entry>
  361             </row>
  362 
  363             <row>
  364               <entry>log2(x)</entry>
  365 
  366               <entry>base 2 logarithm of x</entry>
  367             </row>
  368 
  369                 <row>
  370                     <entry>w0(x)</entry>
  371                     <entry>Principal branch of Lambert's W function, W<subscript>0</subscript>(x).
  372                         W<subscript>0</subscript> is defined as a solution to the equation
  373                         W<subscript>0</subscript>(x)*exp(W<subscript>0</subscript>(x))=x.
  374                         For x&lt;0, there are tow real-valued branches; this function computes the one where
  375                         W&gt;-1 for x&lt;0 (compare w1(x)).
  376                     </entry>
  377                 </row>
  378 
  379                 <row>
  380                     <entry>w1(x)</entry>
  381                     <entry>Secondary branch of Lambert's W function, W<subscript>-1</subscript>(x).
  382                         W<subscript>-1</subscript> is defined as a solution to the equation
  383                         W<subscript>-1</subscript>(x)*exp(W<subscript>-1</subscript>(x))=x.
  384                         For x&lt;0, there are tow real-valued branches; this function computes the one where
  385                         W&lt;-1 for x&lt;0 (compare w0(x)).
  386                     </entry>
  387                 </row>
  388 
  389             <row>
  390               <entry>min(x1,x2,x3,...)</entry>
  391 
  392               <entry>Minimum of the list of arguments</entry>
  393             </row>
  394 
  395             <row>
  396               <entry>max(x1,x2,x3,...)</entry>
  397 
  398               <entry>Maximum of the list of arguments</entry>
  399             </row>
  400 
  401                 <row>
  402                     <entry>mod(x,y)</entry>
  403                     <entry>x modulo y; remainder of integer division x/y</entry>
  404                 </row>
  405 
  406                 <row>
  407                     <entry>pow(x,y)</entry>
  408                     <entry>x to the power of y, x^y</entry>
  409                 </row>
  410 
  411             <row>
  412               <entry>rint(x)</entry>
  413 
  414               <entry>Round to nearest integer.</entry>
  415             </row>
  416 
  417             <row>
  418               <entry>sign(x)</entry>
  419 
  420               <entry>Sign function: -1 if x&lt;0; 1 if x&gt;0.</entry>
  421             </row>
  422 
  423             <row>
  424               <entry>sin(x)</entry>
  425 
  426               <entry>sine of x</entry>
  427             </row>
  428 
  429             <row>
  430               <entry>sinh(x)</entry>
  431 
  432               <entry>hyperbolic sine of x</entry>
  433             </row>
  434 
  435             <row>
  436               <entry>sqrt(x)</entry>
  437 
  438               <entry>square root of x</entry>
  439             </row>
  440 
  441             <row>
  442               <entry>tan(x)</entry>
  443 
  444               <entry>tangent of x</entry>
  445             </row>
  446 
  447             <row>
  448               <entry>tanh(x)</entry>
  449 
  450               <entry>hyperbolic tangent of x</entry>
  451             </row>
  452           </tbody>
  453         </tgroup>
  454       </table>
  455 
  456       <table frame="sides" pgwide="1" tocentry="1">
  457         <title>Non-Mathematical Functions</title>
  458 
  459         <tgroup cols="2">
  460           <colspec align="left" colname="name" colwidth="1*" />
  461 
  462           <colspec align="justify" colname="description" colwidth="10*" />
  463 
  464           <thead>
  465             <row>
  466               <entry>Name</entry>
  467 
  468               <entry>Description</entry>
  469             </row>
  470           </thead>
  471 
  472           <tbody>
  473             <row>
  474               <entry>cell(a,b)</entry>
  475 
  476                   <entry>In the context of a matrix, returns the value at row a and column b.
  477                       In the context of a table, returns the value at column a and row b (remember that tables use column logic).
  478                       Everywhere else, this function is undefined.
  479 
  480                       In the case of tables, the column is specified as a path string; see the
  481                       documentation of column() for supported path formats.
  482                   </entry>
  483             </row>
  484 
  485                 <row>
  486                     <entry>cell_(column, row)</entry>
  487                     <entry>
  488                         In the context of a table, return the value of a cell specified using 1-based indexes.
  489                         Wherever possible, you should use cell() instead, because inserting/removing/moving
  490                         columns will break formulas using cell_().
  491                     </entry>
  492                 </row>
  493 
  494             <row>
  495               <entry>col(c)</entry>
  496 
  497                   <entry>
  498                       DEPRECATED; use column() or cell() instead.
  499                       Note that the user interface still uses col() until a proper language-specific mechanism
  500                       is implemented.
  501                   </entry>
  502             </row>
  503 
  504                 <row>
  505                     <entry>column("path")</entry>
  506                     <entry>
  507                         In a column formula, returns the value in the given column and current row (i).
  508                         The column path can either be the name of column in the current table, more
  509                         generally a relative path to a column in another table (e.g. "../otherTable/col")
  510                         or an absolute path (i.e., relative to the project root; e.g.
  511                         "/folder/otherTable/col"). Searching for a table anywhere in the project using
  512                         "otherTable/col" (without leading slash) is supported for backwards-compatibility
  513                         reasons, but is strongly discouraged - a future release will drop the requirement
  514                         of project-wide unique table names, at which point this usage will cease to be
  515                         well-defined.
  516                     </entry>
  517                 </row>
  518 
  519                 <row>
  520                     <entry>column_(index)</entry>
  521                     <entry>In a column formula, returns the value in the column given by 1-based index
  522                         and current row (i). You should use column() wherever possible, because inserting/
  523                         removing/moving columns will break formulas using column_().
  524                     </entry>
  525                 </row>
  526 
  527             <row>
  528               <entry>if(e1,e2,e3)</entry>
  529 
  530               <entry>if e1 is true, e2 is executed else e3 is
  531         executed (works only if SciDAVis is built using muParser 1.x versions).</entry>
  532             </row>
  533 
  534         <row>
  535               <entry>e1?e2:e3</entry>
  536 
  537               <entry>if e1 is true, e2 is executed else e3 is
  538         executed (C++ style syntax; works only if SciDAVis is built using muParser &gt;= 2.0.0).</entry>
  539             </row>
  540         
  541             <row>
  542               <entry>tablecol(t,c)</entry>
  543 
  544                   <entry>
  545                       DEPRECATED; use column() instead.
  546                   </entry>
  547             </row>
  548           </tbody>
  549         </tgroup>
  550       </table>
  551   </sect1>
  552 
  553   <sect1 id="sec-python">
  554     <title>Python</title>
  555     <indexterm><primary>Scripting</primary><secondary>Python</secondary></indexterm>
  556 
  557     <para>This module provides bindings to the <ulink
  558     url="https://www.python.org">Python</ulink> programming language. Basic
  559     usage in the context of &appname; will be discussed below, but for more
  560     in-depth information on the language itself, please refer to its excellent
  561     <ulink url="https://www.python.org/doc">documentation</ulink>.</para>
  562 
  563     <sect2>
  564          <title>Getting Started</title>
  565 
  566          <para>Make sure your current project uses Python as its interpreter by
  567              selecting the menu point Scripting->Scripting Language and
  568              double-clicking on "Python" in the resulting dialog (if the dialog
  569              appears, but does not contain the "Python" item, your installation
  570              of &appname; has been compiled without Python support).
  571              Next, open a Notes window and enter
  572              <userinput>print "Hello World!"</userinput>. Position the cursor
  573              anywhere on this line and press Ctrl+J, or select "Execute" from
  574              the context menu. The string "Hello World!" should appear below the
  575              line you entered. Congratulations, you've made contact with Python!
  576              You can also enter more complex code fragments, such as function or
  577              class definitions, in which case you have to select the whole code
  578              block before executing it.</para>
  579 
  580          <para>You can also use Notes windows as a handy calculator. Enter a
  581              mathematical expression on a line of its own - say,
  582              <userinput>5*sin(pi/2)</userinput>. Press Ctr+Enter, or select
  583              "Evaluate" from the context menu. You are rewarded by a new line,
  584              stating (to general astonishment), that the result of evaluating
  585              your expression is <computeroutput>#&gt; 5</computeroutput>. If
  586              you have <ulink url="https://www.scipy.org">SciPy</ulink> and/or
  587              <ulink url="http://pygsl.sourceforge.net">PyGSL</ulink> installed, you
  588              will have immediate access to a huge number of interesting
  589              functions, browseable via the sub-menu "Functions" of the context
  590              menu. Pressing Shift+F1 while in this menu will give you a short
  591              description of the current function. The advantage of only
  592              executing/evaluating single lines or selections on request is that
  593              you can freely mix text and calculations within a Notes window.</para>
  594 
  595          <para>Another particularly handy place for using Python code are
  596              column formulas. These work just like evaluating expressions
  597              in Note windows, with the additional advantage of some pre-defined
  598              variables: i (the row currently being computed), j (the column
  599              number), sr (start row), er (end row) and self (the table to which the
  600              column being computed belongs; see below for what you can do with it).
  601          </para>
  602 
  603          <para>If you are already familiar with Python, you might ask yourself at
  604              this point if you can use more complicated column formulas than just
  605              single expressions (for instance, if:/else: decisions based on the
  606              current row number). The answer is: yes, you can. For the benefit of
  607              those not familiar with Python, we will give a short introduction to
  608              the language before discussing how to do this.</para>
  609      </sect2>
  610 
  611     <sect2>
  612       <title>Python Basics</title>
  613 
  614         <sect3>
  615             <title>Expressions</title>
  616 
  617             <para>Mathematical expressions work largely as expected. However,
  618                 there's one caveat, especially when switching from muParser:
  619                 <userinput>a^b</userinput> does not mean "raise a to the power of b" but
  620                 rather "bitwise exclusive or of a and b"; Python's power operator is **.
  621                 Thus: <screen width="40">
  622 <userinput>2^3 # read: 10 xor 11 = 01</userinput>
  623 <computeroutput>#&gt; 1</computeroutput>
  624 <userinput>2**3</userinput>
  625 <computeroutput>#&gt; 8</computeroutput>
  626             </screen></para>
  627         </sect3>
  628 
  629         <sect3>
  630             <title>Statements</title>
  631 
  632             <para>One thing you have to know when working with Python is that
  633                 indentation is very important. It is used for grouping (most other
  634                 languages use either braces or keywords like
  635                 <userinput>do...end</userinput> for this). For example, executing the
  636                 following: <programlisting
  637                     width="40">
  638 x=23
  639 for i in (1,4,5):
  640     x=i**2
  641     print(x)
  642                 </programlisting> will do what you would expect: it prints out the numbers 1, 16 and
  643                 25; each on a line of its own. Deleting just a bit of space will change
  644                 the functionality of your program: <programlisting width="40">
  645 x=23
  646 for i in (1,4,5):
  647     x=i**2
  648 print(x)
  649             </programlisting> will print out only one number - no, not 23, but rather 25. This
  650                 example was designed to also teach you something about variable scoping:
  651                 There are no block-local variables in Python.</para>
  652 
  653                 <para>There are two different variable scopes to be aware of: local and
  654                 global variables. Unless specified otherwise, variables are local to the
  655                 context in which they were defined. Thus, the variable
  656                 <varname>x</varname> can have three different values in, say, two
  657                 different Note windows and a column formula. Global variables on the
  658                 other hand can be accessed from everywhere within your project. A
  659                 variable <varname>x</varname> is declared global by executing the
  660                 statement <userinput>global x</userinput>. You have to do this before
  661                 assigning a value to <varname>x</varname>, but you have to do it only
  662                 once within the project (no need to "import" the variable before using
  663                 it). Note that there is a slight twist to these rules when you
  664                 define your own functions.</para>
  665 
  666                 <para>The basic syntax for defining a function (for use within one
  667                 particular note, for example) is <programlisting width="40">
  668 def answer():
  669     return 42
  670             </programlisting> If you want your function to be accessible from the rest of your
  671                 project, you have to declare it global before the definition: <programlisting
  672       width="40">
  673 global answer
  674 def answer():
  675     return 42
  676             </programlisting> You can add your own function to &appname;'s function list. We'll
  677                 also provide a documentation string that will show up, for example, in
  678                 the "set column values" dialog: <programlisting width="40">
  679 global answer
  680 def answer():
  681     "Return the answer to the ultimate question about life, the universe and everything."
  682     return 42
  683 &python-pref;.mathFunctions["answer"] = answer
  684             </programlisting> If you want to remove a function from the list,
  685             execute <programlisting
  686       width="40">
  687 del &python-pref;.mathFunctions["answer"]
  688     </programlisting></para>
  689 
  690                 <para>Note that functions have their own local scope. That means that if
  691                 you enter a function definition in a Notes window, you will not be able to
  692                 access (neither reading nor writing) Notes-local variables from within
  693                 the function. However, you can access global variables as usual.</para>
  694 
  695                 <para>If-then-else decisions are entered as follows: <programlisting width="40">
  696 if x&gt;23:
  697     print(x)
  698 else:
  699     print("The value is too small.")
  700             </programlisting></para>
  701 
  702                 <para>You can do loops, too: <programlisting width="40">
  703         for i in range(1, 11):
  704             print(i)
  705             </programlisting> This will print out the numbers between 1 and 10 inclusively (the
  706                 upper limit does not belong to the range, while the lower limit
  707                 does).</para>
  708         </sect3>
  709         <sect3>
  710             <title>Hints on Python 2 vs Python 3 usage</title>
  711               <para>In version 1.23 of &appname; it was added Python 3 support for scripting. Then, in addition to the differences between Python version 2 and 3 <ulink
  712     url="https://docs.python.org/3.0/whatsnew/3.0.html">listed here</ulink>, there are some small tips for users that use non-ASCII characters in python scripts.</para>
  713               <para>When &appname; is built against Python 3, it is required to specify the character encoding in the scripting note (at the beginning, preferably) using: <programlisting width="40">
  714         # coding=&lt;encoding name&gt; </programlisting> E. g.: to use the UTF-8 character encoding, add <programlisting width="40">
  715         # coding=utf8 </programlisting> to the note.</para>
  716         <para>When &appname; is built against Python 2, it is required to specify the character encoding <emphasis>each time</emphasis> you use a non-ASCII character inside a command in the following way: <programlisting width="40">
  717         command(unicode("&lt;string to be used&gt;","utf8")) </programlisting> Some examples are:</para>
  718           <para>- To use the print statement:<programlisting width="40">
  719         print(unicode("&lt;string to be used&gt;","utf8"))  </programlisting>
  720           - To modify X axis title on a graph:<programlisting width="40">
  721         g = graph("Graph1")
  722         l = g.activeLayer()
  723         l.setXTitle(unicode("&lt;desired X title&gt;","utf8"))</programlisting>
  724           - To access a graph whose window name has a non-ASCII character:<programlisting width="40">
  725         g = graph(unicode("&lt;literal window name&gt;","utf8"))  </programlisting></para>
  726         </sect3>
  727         </sect2>
  728 
  729         <sect2>
  730             <title>Evaluation Reloaded</title>
  731 
  732             <para>As we've already mentioned above, there's a bit more to evaluation
  733                 than just expressions. Note that Python itself can indeed only
  734                 evaluate expressions; the following describes a feature of &appname;
  735                 added on top of Python in order to support more interesting column
  736                 formulas.</para>
  737 
  738             <para>If you use statements (e.g. variable assignments or control
  739                 structures) in a formula, &appname; will assume it to be the body of a
  740                 function. That is, the following code will not work:
  741                 <programlisting width="40">
  742 a=1
  743 a+a
  744 </programlisting>
  745                 The statement in the first line means that the formula cannot
  746                 be evaluated as a single expression. Instead, the above code assigns
  747                 every row in the column the return value of the following function:
  748                 <programlisting width="40">
  749 def f():
  750     a=1
  751     a+a
  752 </programlisting>
  753                 However, since Python does not implicitly interpret expressions as
  754                 something to return, this evaluates to nothing. The correct way
  755                 to enter formulas with statements in them is to explicitly return
  756                 something: <programlisting width="40">
  757 a=1
  758 return a+a
  759 </programlisting></para>
  760 
  761         <para>There is a slight catch associated with this strategy. In a Notes
  762             window, &appname; will allow you to <emphasis>evaluate</emphasis>
  763             variable assignments like <userinput>ee=1.6021773e-19</userinput>
  764             without complaining - but this will not lead to the result presumably
  765             intended, i.e. introducing a shortcut for the elementary charge to be
  766             used within the notes window. What actually happens is this: &appname;
  767             evaluates the function <programlisting width="40">
  768 def f():
  769     ee=1.6021773e-19
  770 </programlisting>
  771             As mentioned in the Python introduction above, the function f has its
  772             own variable scope and (unless it happens to be declared global) the
  773             variable ee will only be visible within this scope (instead of the
  774             Notes window's scope). The solution is simple: always
  775             <emphasis>execute</emphasis> things like assignments and function
  776             definitions, never <emphasis>evaluate</emphasis> them.</para>
  777      </sect2>
  778 
  779     <sect2 id="Python-functions">
  780       <title>Mathematical Functions</title>
  781     <indexterm><primary>Scripting</primary><secondary>Python</secondary><tertiary>Mathematical functions</tertiary></indexterm>
  782 
  783       <para>Python comes with some basic mathematical functions that are
  784       automatically imported (if you use the <link
  785       linkend="Python-init">initialization file</link> shipped with &appname;).
  786       Along with them, the constants e (Euler's number) and pi (the one and
  787       only) are defined. Many, many more functions can be obtained by installing
  788         <ulink url="https://www.scipy.org">SciPy</ulink> and/or
  789         <ulink url="http://pygsl.sourceforge.net">PyGSL</ulink>.</para>
  790 
  791       <table frame="sides" pgwide="1" tocentry="1">
  792         <title>Supported Mathematical Functions</title>
  793 
  794         <tgroup cols="2">
  795           <colspec align="left" colname="name" colwidth="1*" />
  796 
  797           <colspec align="justify" colname="description" colwidth="10*" />
  798 
  799           <thead>
  800             <row>
  801               <entry>Name</entry>
  802 
  803               <entry>Description</entry>
  804             </row>
  805           </thead>
  806 
  807           <tbody>
  808             <row>
  809               <entry>acos(x)</entry>
  810 
  811               <entry>inverse cosine</entry>
  812             </row>
  813 
  814             <row>
  815               <entry>asin(x)</entry>
  816 
  817               <entry>inverse sine</entry>
  818             </row>
  819 
  820             <row>
  821               <entry>atan(x)</entry>
  822 
  823               <entry>inverse tangent</entry>
  824             </row>
  825 
  826             <row>
  827               <entry>atan2(y,x)</entry>
  828 
  829               <entry>equivalent to atan(y/x), but more efficient</entry>
  830             </row>
  831 
  832             <row>
  833               <entry>ceil(x)</entry>
  834 
  835               <entry>ceiling; smallest integer greater or equal to x</entry>
  836             </row>
  837 
  838             <row>
  839               <entry>cos(x)</entry>
  840 
  841               <entry>cosine of x</entry>
  842             </row>
  843 
  844             <row>
  845               <entry>cosh(x)</entry>
  846 
  847               <entry>hyperbolic cosine of x</entry>
  848             </row>
  849 
  850             <row>
  851               <entry>degrees(x)</entry>
  852 
  853               <entry>convert angle from radians to degrees</entry>
  854             </row>
  855 
  856             <row>
  857               <entry>exp(x)</entry>
  858 
  859               <entry>Exponential function: e raised to the power of x.</entry>
  860             </row>
  861 
  862             <row>
  863               <entry>fabs(x)</entry>
  864 
  865               <entry>absolute value of x</entry>
  866             </row>
  867 
  868             <row>
  869               <entry>floor(x)</entry>
  870 
  871               <entry>largest integer smaller or equal to x</entry>
  872             </row>
  873 
  874             <row>
  875               <entry>fmod(x,y)</entry>
  876 
  877               <entry>remainder of integer division x/y</entry>
  878             </row>
  879 
  880             <row>
  881               <entry>frexp(x)</entry>
  882 
  883               <entry>Returns the tuple (mantissa,exponent) such that
  884               x=mantissa*(2**exponent) where exponent is an integer and 0.5
  885               &lt;=abs(m)&lt;1.0</entry>
  886             </row>
  887 
  888             <row>
  889               <entry>hypot(x,y)</entry>
  890 
  891               <entry>equivalent to sqrt(x*x+y*y)</entry>
  892             </row>
  893 
  894             <row>
  895               <entry>ldexp(x,y)</entry>
  896 
  897               <entry>equivalent to x*(2**y)</entry>
  898             </row>
  899 
  900             <row>
  901               <entry>log(x)</entry>
  902 
  903               <entry>natural (base e) logarithm of x</entry>
  904             </row>
  905 
  906             <row>
  907               <entry>log10(x)</entry>
  908 
  909               <entry>decimal (base 10) logarithm of x</entry>
  910             </row>
  911 
  912             <row>
  913               <entry>modf(x)</entry>
  914 
  915               <entry>return fractional and integer part of x as a
  916               tuple</entry>
  917             </row>
  918 
  919             <row>
  920               <entry>pow(x,y)</entry>
  921 
  922               <entry>x to the power of y; equivalent to x**y</entry>
  923             </row>
  924 
  925             <row>
  926               <entry>radians(x)</entry>
  927 
  928               <entry>convert angle from degrees to radians</entry>
  929             </row>
  930 
  931             <row>
  932               <entry>sin(x)</entry>
  933 
  934               <entry>sine of x</entry>
  935             </row>
  936 
  937             <row>
  938               <entry>sinh(x)</entry>
  939 
  940               <entry>hyperbolic sine of x</entry>
  941             </row>
  942 
  943             <row>
  944               <entry>sqrt(x)</entry>
  945 
  946               <entry>square root of x</entry>
  947             </row>
  948 
  949             <row>
  950               <entry>tan(x)</entry>
  951 
  952               <entry>tangent of x</entry>
  953             </row>
  954 
  955             <row>
  956               <entry>tanh(x)</entry>
  957 
  958               <entry>hyperbolic tangent of x</entry>
  959             </row>
  960           </tbody>
  961         </tgroup>
  962       </table>
  963     </sect2>
  964 
  965     <sect2 id="Python-API-Intro">
  966       <title>Accessing &appname;'s functions from Python</title>
  967 
  968       <para>We will assume that you are using the <link
  969       linkend="Python-init">initialization file</link> shipped with
  970       &appname;.</para>
  971 
  972       <sect3>
  973         <title>Establishing contact</title>
  974 
  975         <para>Accessing the objects in your project is straight-forward,
  976         <programlisting width="40">
  977 t = table("Table1")
  978 m = matrix("Matrix1")
  979 g = graph("Graph1")
  980 n = note("Notes1")
  981       </programlisting> as is creating new objects: <programlisting width="40">
  982 # create an empty table named "tony" with 5 rows and 2 columns:
  983 t = newTable("tony", 5, 2)
  984 # use defaults
  985 t = newTable()
  986 # create an empty matrix named "gina" with 42 rows and 23 columns:
  987 m = newMatrix("gina", 42, 23)
  988 # use defaults
  989 m = newMatrix()
  990 # create an empty graph window
  991 g = newGraph()
  992 # create an empty note named "momo"
  993 n = newNote("momo")
  994 # use defaults
  995 n = newNote()
  996       </programlisting></para>
  997       <para>
  998         New objects will always be added to the active folder.
  999         The functions table, matrix, graph and note will start searching in the active folder and, failing this, continue with a depth-first recursive search of the project's root folder.
 1000         In order to access other folders, there are the functions
 1001         <programlisting width="40">
 1002 f = activeFolder()
 1003 # and
 1004 f = rootFolder()
 1005 </programlisting>
 1006         which can be used to access subfolders and windows:
 1007         <programlisting width="40">
 1008 f2 = f.folders()[number]
 1009 f2 = f.folder(name, caseSensitive=True, partialMatch=False)
 1010 t = f.table(name, recursive=False)
 1011 m = f.matrix(name, recursive=False)
 1012 g = f.graph(name, recursive=False)
 1013 n = f.note(name, recursive=False)
 1014 </programlisting>
 1015             If you supply True for the recursive argument, a depth-first recursive search of all sub-folders will be performed and the first match returned.</para>
 1016 
 1017 
 1018         <para>Also, every piece of code is executed in the context of an
 1019       object which you can access via the <varname>self</varname> variable. For example,
 1020         entering <userinput>self.cell("t",i)</userinput> as a column formula
 1021         is equivalent to the convenience function
 1022         <userinput>col("t")</userinput>.</para>
 1023       </sect3>
 1024 
 1025       <sect3>
 1026         <title>Working with Tables</title>
 1027 
 1028         <para>We'll assume that you have assigned some table to the variable
 1029         <varname>t</varname>. You can access its numeric cell values with
 1030         <programlisting width="40">
 1031 t.cell(col, row)
 1032 # and
 1033 t.setCell(col, row, value)
 1034       </programlisting> Whenever you have to specify a column, you can use either the
 1035         column name (as a string) or the consecutive column number (starting
 1036         with 1). Row numbers also start with 1, just as they are displayed. If
 1037         you want to work with arbitrary texts or the textual representations
 1038         of numeric values, you can use <programlisting width="40">
 1039 t.text(col, row)
 1040 # and
 1041 t.setText(col, row, string)
 1042       </programlisting> The number of columns and rows is accessed via <programlisting
 1043         width="40">
 1044 t.numRows()
 1045 t.numCols()
 1046 t.setNumRows(number)
 1047 t.setNumCols(number)
 1048       </programlisting> Column names can be read and written with <programlisting width="40">
 1049 t.colName(number)
 1050 t.setColName(col, newName)
 1051       </programlisting> Normalize a single or all columns: <programlisting width="40">
 1052 t.normalize(col)
 1053 t.normalize()
 1054       </programlisting> Import values from <varname>file</varname>, using
 1055         <varname>sep</varname> as separator char and ignoring
 1056         <varname>ignore</varname> lines at the head of the file. The flags
 1057         should be self-explanatory. <programlisting width="40">
 1058 t.importASCII(file, sep="\t", ignore=0, renameCols=False, stripSpaces=True, simplifySpace=False, newTable=False)
 1059       </programlisting> After having changed some table values from a script, you will
 1060         likely want to update dependent Graphs: <programlisting width="40">
 1061 t.notifyChanges()
 1062       </programlisting></para>
 1063 
 1064         <para>As a simple example, let's set some column values without using
 1065         the dialog. <programlisting width="40">
 1066 t = table("table1")
 1067 for i in range(1, t.numRows()+1):
 1068     t.setCell(1, i, i**2)
 1069 t.notifyChanges()
 1070       </programlisting></para>
 1071       </sect3>
 1072 
 1073       <sect3>
 1074         <title>Working with Matrices</title>
 1075 
 1076         <para>We'll assume that you have assigned some matrix to the variable
 1077         <varname>m</varname>. Accessing cell values is very similar to Table,
 1078         but since Matrix doesn't use column logic, row arguments are specified
 1079         before columns and obviously you can't use column name. <programlisting
 1080         width="40">
 1081 m.cell(row, col)
 1082 m.setCell(row, col, value)
 1083 m.text(row, col)
 1084 m.setText(row, col, string)
 1085       </programlisting> Also like with tables, there's <programlisting width="40">
 1086 m.numRows()
 1087 # and
 1088 m.numCols()
 1089       </programlisting></para>
 1090       </sect3>
 1091 
 1092       <sect3>
 1093         <title>Plotting and Working with Graphs</title>
 1094 
 1095         <para>If you want to create a new Graph window for some data in table
 1096         table1, you can use the plot command: <programlisting width="40">
 1097 g = plot(table, column, type)
 1098       </programlisting> <varname>type</varname> is a number between 0 and 10 and
 1099         specifies the desired plot type: <variablelist spacing="compact">
 1100             <varlistentry>
 1101               <term>0.</term>
 1102 
 1103               <listitem>
 1104                 <para>Line</para>
 1105               </listitem>
 1106             </varlistentry>
 1107 
 1108             <varlistentry>
 1109               <term>1.</term>
 1110 
 1111               <listitem>
 1112                 <para>Symbols</para>
 1113               </listitem>
 1114             </varlistentry>
 1115 
 1116             <varlistentry>
 1117               <term>2.</term>
 1118 
 1119               <listitem>
 1120                 <para>Line and Symbols</para>
 1121               </listitem>
 1122             </varlistentry>
 1123 
 1124             <varlistentry>
 1125               <term>3.</term>
 1126 
 1127               <listitem>
 1128                 <para>Columns</para>
 1129               </listitem>
 1130             </varlistentry>
 1131 
 1132             <varlistentry>
 1133               <term>4.</term>
 1134 
 1135               <listitem>
 1136                 <para>Area</para>
 1137               </listitem>
 1138             </varlistentry>
 1139 
 1140             <varlistentry>
 1141               <term>5.</term>
 1142 
 1143               <listitem>
 1144                 <para>Pie</para>
 1145               </listitem>
 1146             </varlistentry>
 1147 
 1148             <varlistentry>
 1149               <term>6.</term>
 1150 
 1151               <listitem>
 1152                 <para>Vertical drop lines</para>
 1153               </listitem>
 1154             </varlistentry>
 1155 
 1156             <varlistentry>
 1157               <term>7.</term>
 1158 
 1159               <listitem>
 1160                 <para>Splines and Symbols</para>
 1161               </listitem>
 1162             </varlistentry>
 1163 
 1164             <varlistentry>
 1165               <term>8.</term>
 1166 
 1167               <listitem>
 1168                 <para>Vertical steps</para>
 1169               </listitem>
 1170             </varlistentry>
 1171 
 1172             <varlistentry>
 1173               <term>9.</term>
 1174 
 1175               <listitem>
 1176                 <para>Histogram</para>
 1177               </listitem>
 1178             </varlistentry>
 1179 
 1180             <varlistentry>
 1181               <term>10.</term>
 1182 
 1183               <listitem>
 1184                 <para>Rows</para>
 1185               </listitem>
 1186             </varlistentry>
 1187           </variablelist> You can plot more than one column at once by giving
 1188         a Python tuple (see the <ulink url="https://docs.python.org/3/tutorial/index.html">Python
 1189         Tutorial</ulink>) as an argument: <programlisting width="40">
 1190 g = plot(table("table1"), (2,4,7), 2)
 1191       </programlisting></para>
 1192 
 1193         <para>If you want to add a curve to an existing Graph window, you have
 1194         to choose the destination layer. Usually, <programlisting width="40">
 1195 l = g.activeLayer()
 1196       </programlisting> will do the trick, but you can also select a layer by its number:
 1197         <programlisting width="40">
 1198 l = g.layer(num)
 1199       </programlisting> You can then add or remove curves to or from this layer: <programlisting
 1200         width="40">
 1201 l.insertCurve(table, column, type=1)
 1202 l.insertCurve(table, Xcolumn, Ycolumn, type=1)
 1203 l.removeCurve(curveName)
 1204 l.removeCurve(curveNumber)
 1205 l.deleteFitCurves()
 1206       </programlisting> In case you need the number of curves on a layer, you can get it
 1207         with <programlisting width="40">
 1208 l.numCurves()
 1209       </programlisting></para>
 1210 
 1211       <para>Use the following functions to change the axis attachment of a curve:
 1212     <programlisting width="40">
 1213 
 1214 c = l.curve(number)
 1215 l.setCurveAxes(number, x-axis, y-axis)
 1216 c.setXAxis(x-axis)
 1217 c.setYAxis(y-axis)
 1218       </programlisting> where <varname>number</varname> is curve's index, <varname>x-axis</varname> is either <varname>Layer.Bottom</varname> or <varname>Layer.Top</varname> and <varname>y-axis</varname> is either <varname>Layer.Left</varname> or <varname>Layer.Right</varname> <programlisting width="40">
 1219 l.setCurveAxes(0, Layer.Top, Layer.Right)  # modify the first curve in the layer (curve index is 0)
 1220 c.setXAxis(Layer.Bottom)
 1221 c.setYAxis(Layer.Right)  # attach curve c to the right Y axis
 1222     </programlisting></para>
 1223       
 1224         <para>Layers and whole Graphs can be printed and exported from within
 1225         Python. Before you do this, you would probably want to change layer and axis
 1226         titles as well as legend texts: <programlisting width="40">
 1227 l.setTitle(title)
 1228 l.setXTitle(Xtitle)
 1229 l.setYTitle(Ytitle)
 1230 l.setLegend(text)
 1231       </programlisting> You can also customize the scales of the different axes using: <programlisting width="40">
 1232 l.setScale(int axis, double start, double end, double step=0.0, int majorTicks=5, int minorTicks=5, int type=0, bool inverted=False);
 1233 </programlisting>
 1234       where <varname>axis</varname> is one of <varname>Layer.Left</varname>, <varname>Layer.Right</varname>, <varname>Layer.Bottom</varname>, <varname>Layer.Top</varname>,
 1235 type specifies the desired scale type: <varname>0</varname> for <varname>Linear</varname> or <varname>1</varname> for <varname>Log10</varname>
 1236 and <varname>step</varname> defines the size of the interval between the major scale ticks. If not specified (default value is 0.0), the step size is calculated automatically. The other flags should be self-explanatory.</para>
 1237       <para>Now, here is how you can export a layer <programlisting width="40">
 1238 l.print()
 1239 l.exportToSVG(filename)
 1240 l.exportToEPS(filename)
 1241 l.exportImage(filename, filetype="PNG", quality=100, transparent=False)
 1242       </programlisting> and a graph <programlisting width="40">
 1243 g.print()
 1244 g.exportToSVG(filename)
 1245 g.exportToEPS(filename)
 1246       </programlisting></para>
 1247       </sect3>
 1248 
 1249       <sect3>
 1250         <title>Fitting</title>
 1251 
 1252         <para>Assuming you have a Graph named "graph1" with a curve entitled
 1253         "table1_2" (on its active layer), a minimal Fit example would be:
 1254         <programlisting width="40">
 1255 f = GaussFit(graph("graph1").activeLayer(), "table1_2")
 1256 f.guessInitialValues()
 1257 f.fit()
 1258       </programlisting> This creates a new GaussFit object on the curve, lets it guess
 1259         the start parameters and does the fit. The following fit types are
 1260         supported: <itemizedlist>
 1261             <listitem>
 1262               <para>LinearFit(layer, curve)</para>
 1263             </listitem>
 1264 
 1265             <listitem>
 1266               <para>PolynomialFit(layer, curve, degree=2, legend=False)</para>
 1267             </listitem>
 1268 
 1269             <listitem>
 1270               <para>ExponentialFit(layer, curve, growth=False)</para>
 1271             </listitem>
 1272 
 1273             <listitem>
 1274               <para>TwoExpFit(layer, curve)</para>
 1275             </listitem>
 1276 
 1277             <listitem>
 1278               <para>ThreeExpFit(layer, curve)</para>
 1279             </listitem>
 1280 
 1281             <listitem>
 1282               <para>GaussFit(layer, curve)</para>
 1283             </listitem>
 1284 
 1285             <listitem>
 1286               <para>GaussAmpFit(layer, curve)</para>
 1287             </listitem>
 1288 
 1289             <listitem>
 1290               <para>LorentzFit(layer,curve)</para>
 1291             </listitem>
 1292 
 1293             <listitem>
 1294               <para>SigmoidalFit(layer, curve)</para>
 1295             </listitem>
 1296 
 1297             <listitem>
 1298               <para>NonLinearFit(layer, curve)</para>
 1299             <programlisting width="40">
 1300 f = NonLinearFit(layer, curve)
 1301 f.setParameters(name1, ...)
 1302 f.setFormula(formula_string)
 1303             </programlisting>
 1304             </listitem>
 1305 
 1306             <listitem>
 1307             <para>PluginFit(layer, curve)</para>
 1308             <programlisting width="40">
 1309 f = PluginFit(layer, curve)
 1310 f.load(pluginName)
 1311             </programlisting>
 1312             </listitem>
 1313           </itemizedlist> For each of these, you can optionally restrict the X
 1314         range that will be used for the fit, like in <programlisting width="40">
 1315 f = LinearFit(graph("graph1").activeLayer(), "table1_2", 2, 7)
 1316 f.fit()
 1317       </programlisting></para>
 1318 
 1319         <para>After creating the Fit object and before calling its fit()
 1320         method, you can set a number of parameters that influence the fit:
 1321         <programlisting width="80">
 1322 f.setDataFromCurve(curve)           <lineannotation>change data source</lineannotation>
 1323 f.setDataFromCurve(curve, graph)        <lineannotation>change data source</lineannotation>
 1324 f.setDataFromCurve(curve, from, to)     <lineannotation>change data source</lineannotation>
 1325 f.setDataFromCurve(curve, from, to, graph)  <lineannotation>change data source</lineannotation>
 1326 f.setInterval(from, to)             <lineannotation>change data range</lineannotation>
 1327 f.setInitialValue(number, value)
 1328 f.setInitialValues(value1, ...)
 1329 f.guessInitialValues()
 1330 f.setAlgorithm(algo) # algo = Fit.ScaledLevenbergMarquardt, Fit.UnscaledLevenbergMarquardt, Fit.NelderMeadSimplex
 1331 <!-- f.setWeightingData(method, colname) # method = Fit.NoWeighting, Fit.Instrumental, Fit.Statistical, Fit.Dataset -->
 1332 <!-- setWeightingData was replaced by setYErrorSource at some version -->
 1333 f.setYErrorSource(ErrorSource, colname) # ErrorSource can be: 0 / Fit.UnknownErrors, 1 / Fit.AssociatedErrors,
 1334 2 / Fit.PoissonErrors, or 3 / Fit.CustomErrors
 1335 f.setTolerance(tolerance)
 1336 f.setOutputPrecision(precision)
 1337 f.setMaximumIterations(number)
 1338 f.scaleErrors(yes = True)
 1339 f.setColor(qt.QColor("green"))          <lineannotation>change the color of the result fit curve to green (default color is red)</lineannotation>
 1340       </programlisting></para>
 1341 
 1342         <para>After you've called fit(), you have a number of possibilities
 1343         for extracting the results: <programlisting width="40">
 1344 f.results()
 1345 f.errors()
 1346 f.chiSquare()
 1347 f.rSquare()
 1348 f.dataSize()
 1349 f.numParameters()
 1350 f.parametersTable("params")
 1351 f.covarianceMatrix("cov")
 1352       </programlisting></para>
 1353       </sect3>
 1354     </sect2>
 1355 
 1356      <sect2 id="Python-API">
 1357          <title>API documentation</title>
 1358          <para>Classes mentioned below that start with "Q" mostly belong to Qt and can be used via
 1359              PyQt (with the exception of classes starting with "Qwt", which belong to Qwt).
 1360              If you want to know what you can do with such classes (e.g. QIcon or QDateTime), see the
 1361              <ulink url="http://pyqt.sourceforge.net/Docs/PyQt4/classes.html">PyQt
 1362                  reference documentation</ulink>. It's also useful to know that you can call any QWidget
 1363              method exported by PyQt on instances of MDIWindow (and thus Table, Graph, Matrix and
 1364              Note).
 1365          </para>
 1366          <sect3><title>class AbstractAspect (inherits QObject)</title>
 1367              <para>A base class for content of a project. While currently the only AbstractAspect
 1368                  accessible to you is Column, a future release will make more extensive usage of this;
 1369                  probably with some revisions in the design, so only some basic functions are documented
 1370                  (and supported) for now.</para>
 1371              <programlisting width="80">
 1372 col = newTable("my-table",2,30).column("1")
 1373 col.setName("abc")
 1374 table("my-table").column("2").remove()
 1375              </programlisting>
 1376              <variablelist spacing="compact">
 1377                  <varlistentry>
 1378                      <term>index()</term>
 1379                      <listitem>Return the 0-based index of the Aspect in its sibling list.</listitem>
 1380                  </varlistentry>
 1381                  <varlistentry>
 1382                      <term>name()</term>
 1383                      <listitem>Return the Aspect's name.</listitem>
 1384                  </varlistentry>
 1385                  <varlistentry>
 1386                      <term>setName(string)</term>
 1387                      <listitem>Change the Aspect's name.</listitem>
 1388                  </varlistentry>
 1389                  <varlistentry>
 1390                      <term>comment()</term>
 1391                      <listitem>Return comment attached to the Aspect.</listitem>
 1392                  </varlistentry>
 1393                  <varlistentry>
 1394                      <term>setComment(string)</term>
 1395                      <listitem>Change the comment attached to the Aspect.</listitem>
 1396                  </varlistentry>
 1397                  <varlistentry>
 1398                      <term>icon()</term>
 1399                      <listitem>Return the icon (a QIcon) used to designate the Aspect's type; for columns,
 1400                          this is the data type icon in the table header.</listitem>
 1401                  </varlistentry>
 1402                  <varlistentry>
 1403                      <term>creationTime()</term>
 1404                      <listitem>Return point in time the Aspect was created by the user (as a QDateTime).</listitem>
 1405                  </varlistentry>
 1406                  <varlistentry>
 1407                      <term>remove()</term>
 1408                      <listitem>Remove Aspect from the project (can be undone using Edit-&gt;Undo menu).</listitem>
 1409                  </varlistentry>
 1410                  <varlistentry>
 1411                      <term>signal void aspectDescriptionAboutToChange(const AbstractAspect*)</term>
 1412                      <listitem>Emitted before the description (name or comment) is changed.</listitem>
 1413                  </varlistentry>
 1414                  <varlistentry>
 1415                      <term>signal void aspectDescriptionChanged(const AbstractAspect*)</term>
 1416                      <listitem>Emitted after the description (name or comment) has changed.</listitem>
 1417                  </varlistentry>
 1418                  <varlistentry>
 1419                      <term>signal void aspectAboutToBeRemoved(const AbstractAspect*)</term>
 1420                      <listitem>Emitted before the Aspect is removed.</listitem>
 1421                  </varlistentry>
 1422              </variablelist>
 1423          </sect3>
 1424          <sect3><title>class Column (inherits AbstractAspect)</title>
 1425              <para>Represents a column in a table.</para>
 1426              <para>In addition to the valueAt()/setValueAt() interface described below, starting with
 1427                  &appname; 0.2.4, Y columns support
 1428                  getting/setting row values via the values in the corresponding X column. This is done
 1429                  using Python's item access notation for sequence types (as in col["abc"]).</para>
 1430              <programlisting width="80">
 1431 # basic access
 1432 tab = newTable("tabula1",2,20)
 1433 col = tab.column("1")
 1434 col.setValueAt(1, 123.0)
 1435 print col.valueAt(1)
 1436 # replacing multiple values at once is more efficient than setting them one at a time
 1437 col.replaceValues(5, [11.2, 12.3, 23.4, 34.5, 45.6])
 1438 # set a value in the second column based on the content of the first one
 1439 # (needs &appname; >= 0.2.4)
 1440 tab.column("2")[23.4] = 46.8
 1441 dest = table("tabula1").column("2")
 1442 # also, copying from another column can be done in one go:
 1443 dest.copy(col, 5, 2, 10)
 1444              </programlisting>
 1445              <variablelist spacing="compact">
 1446                  <varlistentry>
 1447                      <term>columnMode()</term>
 1448                      <listitem>A string designating the data type; one of "Numeric", "Text", "Month",
 1449                          "Day" or "DateTime".</listitem>
 1450                  </varlistentry>
 1451                  <varlistentry>
 1452                      <term>setColumnMode(string)</term>
 1453                      <listitem>Change the column's data type; argument must be one of "Numeric", "Text",
 1454                          "Month", "Day" or "DateTime".</listitem>
 1455                  </varlistentry>
 1456                  <varlistentry>
 1457                      <term>copy(Column)</term>
 1458                      <listitem>Copy complete content of other column, which must have the same data type (mode).
 1459                      Returns a boolean indicating success or failure.</listitem>
 1460                  </varlistentry>
 1461                  <varlistentry>
 1462                      <term>copy(Column,int,int,int)</term>
 1463                      <listitem>copy(source, source_start, dest_start, num_rows) copies num_rows values from source,
 1464                          starting to read at row source_start and to write at row dest_start.</listitem>
 1465                  </varlistentry>
 1466                  <varlistentry>
 1467                      <term>rowCount()</term>
 1468                      <listitem>Number of rows in the column.</listitem>
 1469                  </varlistentry>
 1470                  <varlistentry>
 1471                      <term>insertRows(int, int)</term>
 1472                      <listitem>insertRows(before, count) insert count empty rows before row numbered before</listitem>
 1473                  </varlistentry>
 1474                  <varlistentry>
 1475                      <term>removeRows(int, int)</term>
 1476                      <listitem>removeRows(first, count) removes count rows starting with row numbered first</listitem>
 1477                  </varlistentry>
 1478                  <varlistentry>
 1479                      <term>plotDesignation()</term>
 1480                      <listitem>Return a string representing the plot designation of the column; one of "noDesignation", "X", "Y", "Z", "xErr" or "yErr".</listitem>
 1481                  </varlistentry>
 1482                  <varlistentry>
 1483                      <term>setPlotDesignation(string)</term>
 1484                      <listitem>Set the plot designation. The argument must be one of "noDesignation", "X", "Y", "Z", "xErr" or "yErr".</listitem>
 1485                  </varlistentry>
 1486                  <varlistentry>
 1487                      <term>clear()</term>
 1488                      <listitem>Clear content of all cells in the column, marking them as empty/invalid.</listitem>
 1489                  </varlistentry>
 1490                  <varlistentry>
 1491                      <term>isInvalid(int)</term>
 1492                      <listitem>Returns boolean indicating whether the given row is marked as empty/invalid.</listitem>
 1493                  </varlistentry>
 1494                  <varlistentry>
 1495                      <term>formula(int)</term>
 1496                      <listitem>Return formula used to compute the cell value in the given row.</listitem>
 1497                  </varlistentry>
 1498                  <varlistentry>
 1499                      <term>setFormula(int, string)</term>
 1500                      <listitem>Sets formula for the given row to string.</listitem>
 1501                  </varlistentry>
 1502                  <varlistentry>
 1503                      <term>clearFormulas()</term>
 1504                      <listitem>Discard all formulas associated with cells.</listitem>
 1505                  </varlistentry>
 1506                  <varlistentry>
 1507                      <term>valueAt(int)</term>
 1508                      <listitem>Retrieve value of the specified cell (given by 0-based index), assuming that the column has columnMode() == "Numeric".</listitem>
 1509                  </varlistentry>
 1510                  <varlistentry>
 1511                      <term>setValueAt(int, double)</term>
 1512                      <listitem>Set value of specified cell (given by 0-based index), assuming that the column has columnMode() == "Numeric".</listitem>
 1513                  </varlistentry>
 1514                  <varlistentry>
 1515                      <term>replaceValues(int, list of double values)</term>
 1516                      <listitem>Mass-update cells starting at the indicated row, assuming that the column's columnMode() is one of "Numeric". Compared with setValueAt(), this has the advantage of being much more efficient; particularly if the column has dependant plots.</listitem>
 1517                  </varlistentry>
 1518                  <varlistentry>
 1519                      <term>textAt(int)</term>
 1520                      <listitem>Retrieve value of the specified cell (given by 0-based index), assuming that the column has columnMode() == "Text".</listitem>
 1521                  </varlistentry>
 1522                  <varlistentry>
 1523                      <term>setTextAt(int, string)</term>
 1524                      <listitem>Set value of specified cell (given by 0-based index), assuming that the column has columnMode() == "Text".</listitem>
 1525                  </varlistentry>
 1526                  <varlistentry>
 1527                      <term>replaceTexts(int, list of strings)</term>
 1528                      <listitem>Mass-update cells starting at the indicated row, assuming that the column has columnMode() == "Text". Compared with setTextAt(), this has the advantage of being much more efficient; particularly if the column has dependant plots.</listitem>
 1529                  </varlistentry>
 1530                  <varlistentry>
 1531                      <term>dateAt(int)</term>
 1532                      <listitem>Retrieve value of the specified cell (given by 0-based index), assuming that the column's columnMode() is one of "Month", "Day", "DateTime".</listitem>
 1533                  </varlistentry>
 1534                  <varlistentry>
 1535                      <term>setDateAt(int, QDate)</term>
 1536                      <listitem>Set value of specified cell (given by 0-based index), assuming that the column's columnMode() is one of "Month", "Day", "DateTime".</listitem>
 1537                  </varlistentry>
 1538                  <varlistentry>
 1539                      <term>timeAt(int)</term>
 1540                      <listitem>Retrieve value of the specified cell (given by 0-based index), assuming that the column has columnMode() == "DateTime".</listitem>
 1541                  </varlistentry>
 1542                  <varlistentry>
 1543                      <term>setTimeAt(int, QTime)</term>
 1544                      <listitem>Set value of specified cell (given by 0-based index), assuming that the column has columnMode() == "DateTime".</listitem>
 1545                  </varlistentry>
 1546                  <varlistentry>
 1547                      <term>dateTimeAt(int)</term>
 1548                      <listitem>Retrieve value of the specified cell (given by 0-based index), assuming that the column's columnMode() is one of "Month", "Day", "DateTime".</listitem>
 1549                  </varlistentry>
 1550                  <varlistentry>
 1551                      <term>setDateTimeAt(int, QDateTime)</term>
 1552                      <listitem>Set value of specified cell (given by 0-based index), assuming that the column's columnMode() is one of "Month", "Day", "DateTime".</listitem>
 1553                  </varlistentry>
 1554                  <varlistentry>
 1555                      <term>replaceDateTimes(int, list of QDateTime values)</term>
 1556                      <listitem>Mass-update cells starting at the indicated row, assuming that the column's columnMode() is one of "Month", "Day", "DateTime". Compared with setDateTimeAt(), this has the advantage of being much more efficient; particularly if the column has dependant plots.</listitem>
 1557                  </varlistentry>
 1558                  <varlistentry>
 1559                      <term>x()</term>
 1560                      <listitem>Returns the X Column associated with this (Y, xErr or yErr) column.</listitem>
 1561                  </varlistentry>
 1562                  <varlistentry>
 1563                      <term>y()</term>
 1564                      <listitem>Returns the Y Column associated with this (xErr or yErr) column, or the first Y column associated with this X column.</listitem>
 1565                  </varlistentry>
 1566              </variablelist>
 1567          </sect3>
 1568          <sect3><title>class MDIWindow (inherits QWidget)</title>
 1569              <para>Base class of Table, Matrix, Graph and Note. A redesigned analogue under the name of "Part" (inheriting from AbstractAspect) is under development; it should be possible to provide a backwards-compatible interface, though.</para>
 1570              <programlisting width="80">
 1571 tmp = newTable("temp1", 2, 10)
 1572 tmp.setWindowLabel("a temporary table")
 1573 tmp.setCaptionPolicy(MDIWindow.Label)
 1574 # ...
 1575 tmp.confirmClose(False)
 1576 tmp.close()
 1577              </programlisting>
 1578              <variablelist spacing="compact">
 1579                  <varlistentry>
 1580                      <term>name()</term>
 1581                      <listitem>Return the window's name (added in &appname; 0.2.3).</listitem>
 1582                  </varlistentry>
 1583                  <varlistentry>
 1584                      <term>setName(string)</term>
 1585                      <listitem>Set window's name. IMPORTANT: This was added in &appname; 0.2.3, but unfortunately is BROKEN in this release. Usable starting with &appname; 0.2.4.</listitem>
 1586                  </varlistentry>
 1587                  <varlistentry>
 1588                      <term>windowLabel()</term>
 1589                      <listitem>Returns the comment associated with the window (yes, the confusing name will be fixed in a future release).</listitem>
 1590                  </varlistentry>
 1591                  <varlistentry>
 1592                      <term>setWindowLabel(string)</term>
 1593                      <listitem>Set comment associated with the window (yes, the confusing name will be fixed in a future release).</listitem>
 1594                  </varlistentry>
 1595                  <varlistentry>
 1596                      <term>captionPolicy()</term>
 1597                      <listitem>Return caption policy (i.e., what to display in the title bar). One of the integer constants MDIWindow.Name, MDIWindow.Label or MDIWindow.Both.</listitem>
 1598                  </varlistentry>
 1599                  <varlistentry>
 1600                      <term>setCaptionPolicy(int)</term>
 1601                      <listitem>Set caption policy (i.e., what to display in the title bar). Must be one of the integer constants MDIWindow.Name, MDIWindow.Label or MDIWindow.Both.</listitem>
 1602                  </varlistentry>
 1603                  <varlistentry>
 1604                      <term>folder()</term>
 1605                      <listitem>Return the folder this window belongs to (an object of class Folder).</listitem>
 1606                  </varlistentry>
 1607                  <varlistentry>
 1608                      <term>confirmClose(boolean)</term>
 1609                      <listitem>Set a flag indicating whether the user should be given the opportunity to cancel removing the window or minimize it instead when trying to close it. When False, close() will remove the window without asking for confirmation, which is useful for temporary objects created by a script.</listitem>
 1610                  </varlistentry>
 1611                  <varlistentry>
 1612                      <term>clone()</term>
 1613                      <listitem>Returns a copy of this window.
 1614                          Added in &appname; 0.2.4.
 1615                      </listitem>
 1616                  </varlistentry>
 1617              </variablelist>
 1618          </sect3>
 1619          <sect3><title>class Table (inherits MDIWindow)</title>
 1620              <para>Class of table (spreadsheet) windows.</para>
 1621              <programlisting width="80">
 1622 tab = newTable("tabula",2,10)
 1623 for j in range(0, tab.numCols()):
 1624     for i in range(0, tab.numRows()):
 1625         tab.column(j).setValueAt(i,i*j) 
 1626 tab.normalize()
 1627              </programlisting>
 1628              <variablelist spacing="compact">
 1629                  <varlistentry>
 1630                      <term>numRows()</term>
 1631                      <listitem>Returns the number of rows of the table.</listitem>
 1632                  </varlistentry>
 1633                  <varlistentry>
 1634                      <term>numCols()</term>
 1635                      <listitem>Returns the number of columns of the table.</listitem>
 1636                  </varlistentry>
 1637                  <varlistentry>
 1638                      <term>setNumRows(int)</term>
 1639                      <listitem>Sets the number of rows of the table.</listitem>
 1640                  </varlistentry>
 1641                  <varlistentry>
 1642                      <term>setNumCols(int)</term>
 1643                      <listitem>Sets the number of columns of the table.</listitem>
 1644                  </varlistentry>
 1645                  <varlistentry>
 1646                      <term>column(string or int)</term>
 1647                      <listitem>Returns Column indicated by name (preferred) or 0-based index. For the
 1648                          latter form, keep in mind that inserting, removing or moving columns will break
 1649                          scripts which refer to a specific column by index.
 1650                          Starting with &appname; 0.2.4, columns may also be accessed using the []
 1651                          operator, i.e. using table("table name")[column name or index].
 1652                      </listitem>
 1653                  </varlistentry>
 1654                  <varlistentry>
 1655                      <term>text(string or int, int)</term>
 1656                      <listitem>DEPRECATED. Use column(col).textAt(row) or str(column(col).valueAt(row)) instead (depending on the column's mode).
 1657                      CAVEAT: text() indexes are 1-based, while column() and textAt() use more conventional 0-based indexes!</listitem>
 1658                  </varlistentry>
 1659                  <varlistentry>
 1660                      <term>cell(string or int, int)</term>
 1661                      <listitem>DEPRECATED. Use column(col).valueAt(row) instead.
 1662                      CAVEAT: cell() indexes are 1-based, while column() and valueAt() use more conventional 0-based indexes!</listitem>
 1663                  </varlistentry>
 1664                  <varlistentry>
 1665                      <term>setText(string or int, int, string</term>
 1666                      <listitem>DEPRECATED. Use column(col).setTextAt(row,value) instead.
 1667                      CAVEAT: setText() indexes are 1-based, while column() and setTextAt() use more conventional 0-based indexes!</listitem>
 1668                  </varlistentry>
 1669                  <varlistentry>
 1670                      <term>setCell(string or int, int, double</term>
 1671                      <listitem>DEPRECATED. Use column(col).setValueAt(row,value) instead.
 1672                      CAVEAT: setCell() indexes are 1-based, while column() and setValueAt() use more conventional 0-based indexes!</listitem>
 1673                  </varlistentry>
 1674                  <varlistentry>
 1675                      <term>colName(int)</term>
 1676                      <listitem>DEPRECATED. Use column(col).name() instead.</listitem>
 1677                  </varlistentry>
 1678                  <varlistentry>
 1679                      <term>setColName(int,string)</term>
 1680                      <listitem>DEPRECATED. Use column(col).setName(name) instead.</listitem>
 1681                  </varlistentry>
 1682                  <varlistentry>
 1683                      <term>setComment(int,string)</term>
 1684                      <listitem>DEPRECATED. Use column(col).setComment(text) instead.</listitem>
 1685                  </varlistentry>
 1686                  <varlistentry>
 1687                      <term>setCommand(string or int, string)</term>
 1688                      <listitem>Set formula indicated by first argument to the text given in the second argument.</listitem>
 1689                  </varlistentry>
 1690                  <varlistentry>
 1691                      <term>notifyChanges()</term>
 1692                      <listitem>DEPRECATED. Update notifications are now done automatically.</listitem>
 1693                  </varlistentry>
 1694                  <varlistentry>
 1695                      <term>importASCII(string, string, int, bool, bool, bool)</term>
 1696                      <listitem>importASCII(file, separator=&quot;\t&quot;, ignored_lines=0, rename_cols=False, strip_spaces=True, simplify_spaces=False)
 1697                          imports file into this table, skipping ignored_lines lines at the beginning and
 1698                          splitting the rest into columns according to the given separator and flags.</listitem>
 1699                  </varlistentry>
 1700                  <varlistentry>
 1701                      <term>exportASCII(string, string, bool, bool)</term>
 1702                      <listitem>exportASCII(file, separator=&quot;\t&quot;, with_comments=False, selection_only=False)
 1703                          exports this table to the given file with the column separator given in the second argument;
 1704                          optionally including column comments and optionally exporting only selected cells.</listitem>
 1705                  </varlistentry>
 1706                  <varlistentry>
 1707                      <term>normalize(string or int)</term>
 1708                      <listitem>Normalize specified column to a maximum cell value of one.</listitem>
 1709                  </varlistentry>
 1710                  <varlistentry>
 1711                      <term>normalize()</term>
 1712                      <listitem>Normalize all columns in table to a maximum cell value of one.</listitem>
 1713                  </varlistentry>
 1714                  <varlistentry>
 1715                      <term>sortColumn(string or int, int=0)</term>
 1716                      <listitem>Sort column indicated in the first argument. The second argument selects
 1717                          the sorting order; 0 means ascending, 1 means descending.</listitem>
 1718                  </varlistentry>
 1719                  <varlistentry>
 1720                      <term>sort(int=0, int=0, string="")</term>
 1721                      <listitem>sort(type, order, leading_column) sorts all columns in the table either separately
 1722                          (type=0) or together (type=1) with the leading column given by name. The second argument selects
 1723                          the sorting order; 0 means ascending, 1 means descending.</listitem>
 1724                  </varlistentry>
 1725                  <varlistentry>
 1726                      <term>sortColumns(list of strings, int, int, string)</term>
 1727                      <listitem>sortColumns(columns, type=0, order=0, leading_column="") sorts columns given as a tuple of
 1728                          names either separately (type=0) or together (type=1) with the leading column given by name.
 1729                          The third argument selects the sorting order; 0 means ascending, 1 means descending.</listitem>
 1730                  </varlistentry>
 1731              </variablelist>
 1732          </sect3>
 1733          <sect3><title>class Matrix (inherits MDIWindow)</title>
 1734              <para>Class of matrix windows.</para>
 1735              <programlisting width="80">
 1736 mat = newMatrix("mat", 10, 20)
 1737 mat.setCoordinates(100,2000,100,1000)
 1738 mat.setFormula("i*j")
 1739 mat.recalculate()
 1740              </programlisting>
 1741              <variablelist spacing="compact">
 1742                  <varlistentry>
 1743                      <term>numRows()</term>
 1744                      <listitem>Returns the number of rows in the matrix.</listitem>
 1745                  </varlistentry>
 1746                  <varlistentry>
 1747                      <term>numCols()</term>
 1748                      <listitem>Returns the number of columns in the matrix.</listitem>
 1749                  </varlistentry>
 1750                  <varlistentry>
 1751                      <term>setNumRows(int)</term>
 1752                      <listitem>Changes the number of rows in the matrix.</listitem>
 1753                  </varlistentry>
 1754                  <varlistentry>
 1755                      <term>setNumCols(int)</term>
 1756                      <listitem>Changes the number of columns in the matrix.</listitem>
 1757                  </varlistentry>
 1758                  <varlistentry>
 1759                      <term>setDimensions(int,int)</term>
 1760                      <listitem>setDimensions(rows, cols) changes the number of rows and columns simultaneously.</listitem>
 1761                  </varlistentry>
 1762                  <varlistentry>
 1763                      <term>cell(int,int)</term>
 1764                      <listitem>cell(row,column) returns the content of the indicated cell as a number.</listitem>
 1765                  </varlistentry>
 1766                  <varlistentry>
 1767                      <term>text(int,int)</term>
 1768                      <listitem>text(row,column) returns the content of the indicated cell as its textual representation.</listitem>
 1769                  </varlistentry>
 1770                  <varlistentry>
 1771                      <term>setCell(int,int,double)</term>
 1772                      <listitem>setCell(row,column,value) changes the content of the indicated cell to the indicated numeric value.</listitem>
 1773                  </varlistentry>
 1774                  <varlistentry>
 1775                      <term>setText(int,int,string)</term>
 1776                      <listitem>setText(row,column,value) interprets the string value according to the numeric format of the matrix
 1777                          and changes the content of the indicated cell accordingly.</listitem>
 1778                  </varlistentry>
 1779                  <varlistentry>
 1780                      <term>xStart()</term>
 1781                      <listitem>Returns logical X coordinate of the first column.</listitem>
 1782                  </varlistentry>
 1783                  <varlistentry>
 1784                      <term>xEnd()</term>
 1785                      <listitem>Returns logical X coordinate of the last column.</listitem>
 1786                  </varlistentry>
 1787                  <varlistentry>
 1788                      <term>yStart()</term>
 1789                      <listitem>Returns logical Y coordinate of the first row.</listitem>
 1790                  </varlistentry>
 1791                  <varlistentry>
 1792                      <term>yEnd()</term>
 1793                      <listitem>Returns logical Y coordinate of the last row.</listitem>
 1794                  </varlistentry>
 1795                  <varlistentry>
 1796                      <term>setCoordinates(double,double,double,double)</term>
 1797                      <listitem>setCoordinates(x_start, x_end, y_start, y_end) changes the logical
 1798                          coordinate system associated with the matrix.</listitem>
 1799                  </varlistentry>
 1800                  <varlistentry>
 1801                      <term>setFormula(string)</term>
 1802                      <listitem>Changes the formula used to (re)calculate cell values of the matrix.</listitem>
 1803                  </varlistentry>
 1804                  <varlistentry>
 1805                      <term>recalculate()</term>
 1806                      <listitem>Recalculate all cell values from the currently set formula. Returns boolean
 1807                          indicating success or failure. Added in &appname; 0.2.4.</listitem>
 1808                  </varlistentry>
 1809                  <varlistentry>
 1810                      <term>setNumericPrecision(int)</term>
 1811                      <listitem>Changes the number of decimal digits being displayed.</listitem>
 1812                  </varlistentry>
 1813                  <varlistentry>
 1814                      <term>transpose()</term>
 1815                      <listitem>Mirror matrix at main diagonal (aka matrix transposition).</listitem>
 1816                  </varlistentry>
 1817                  <varlistentry>
 1818                      <term>invert()</term>
 1819                      <listitem>Replace the content of the matrix by its inverse (with respect to matrix multiplication).</listitem>
 1820                  </varlistentry>
 1821                  <varlistentry>
 1822                      <term>determinant()</term>
 1823                      <listitem>Returns determinant of the matrix.</listitem>
 1824                  </varlistentry>
 1825              </variablelist>
 1826          </sect3>
 1827          <sect3><title>class ArrowMarker</title>
 1828              <para>A line or an arrow displayed on a graph.</para>
 1829              <programlisting width="80">
 1830 arrow = ArrowMarker()
 1831 arrow.setStart(50,200)
 1832 arrow.setEnd(400,400)
 1833 arrow.setWidth(2)
 1834 arrow.drawStartArrow(False)
 1835 arrow.drawEndArrow(True)
 1836 arrow.setColor(Qt.green)
 1837 
 1838 layer = newGraph().activeLayer()
 1839 layer.addArrow(arrow)
 1840 layer.replot()
 1841              </programlisting>
 1842              <variablelist spacing="compact">
 1843                  <varlistentry>
 1844                      <term>ArrowMarker()</term>
 1845                      <listitem>Creates a new arrow marker. You can then set various attributes (see below) and hand
 1846                          it to Layer.addArrow().</listitem>
 1847                  </varlistentry>
 1848                  <varlistentry>
 1849                      <term>setStart(double, double)</term>
 1850                      <listitem>setStart(x,y) sets the line's start point in plot coordinates (i.e., as
 1851                          displayed on the axes).</listitem>
 1852                  </varlistentry>
 1853                  <varlistentry>
 1854                      <term>setEnd(double,double)</term>
 1855                      <listitem>setEnd(x,y) sets the line's end point in plot coordinates (i.e., as
 1856                          displayed on the axes).</listitem>
 1857                  </varlistentry>
 1858                  <varlistentry>
 1859                      <term>setStyle(Qt.PenStyle)</term>
 1860                      <listitem>Sets pen style used to draw the line and arrow heads. One of Qt.NoPen,
 1861                          Qt.SolidLine, Qt.DashLine, Qt.DotLine, Qt.DashDotLine, Qt.DashDotDotLine.</listitem>
 1862                  </varlistentry>
 1863                  <varlistentry>
 1864                      <term>setColor(QColor)</term>
 1865                      <listitem>Sets the line/arrow head color. Most commonly, the argument will be either
 1866                          a basic color (Qt.white, Qt.black, Qt.red, Qt.darkRed etc. - see Qt.GlobalColor
 1867                          for details) or a RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with
 1868                          channels given as integers in the range [0,255] (see QColor for details).</listitem>
 1869                  </varlistentry>
 1870                  <varlistentry>
 1871                      <term>setWidth(int)</term>
 1872                      <listitem>Sets the pen width used to draw line and arrow heads.</listitem>
 1873                  </varlistentry>
 1874                  <varlistentry>
 1875                      <term>drawStartArrow(bool=True)</term>
 1876                      <listitem>Sets whether an arrow head is drawn at the line's start.</listitem>
 1877                  </varlistentry>
 1878                  <varlistentry>
 1879                      <term>drawEndArrow(bool=True)</term>
 1880                      <listitem>Sets whether an arrow head is drawn at the line's end.</listitem>
 1881                  </varlistentry>
 1882                  <varlistentry>
 1883                      <term>setHeadLength(int)</term>
 1884                      <listitem>Sets the length of the arrow heads.</listitem>
 1885                  </varlistentry>
 1886                  <varlistentry>
 1887                      <term>setHeadAngle(int)</term>
 1888                      <listitem>Sets the angle defining the &quot;sharpness&quot; of the arrow heads.</listitem>
 1889                  </varlistentry>
 1890                  <varlistentry>
 1891                      <term>fillArrowHead(bool)</term>
 1892                      <listitem>Sets whether arrow heads are to be filled out.</listitem>
 1893                  </varlistentry>
 1894              </variablelist>
 1895          </sect3>
 1896          <sect3><title>class ImageMarker</title>
 1897              <para>An image to be displayed on a graph.</para>
 1898              <programlisting width="80">
 1899 layer = newGraph().activeLayer()
 1900 image = layer.addImage("/usr/share/icons/hicolor/128x128/apps/scidavis.png")
 1901 image.setCoordinates(200,800,700,300)
 1902 layer.replot()
 1903           </programlisting>
 1904              <variablelist spacing="compact">
 1905                  <varlistentry>
 1906                      <term>ImageMarker(string)</term>
 1907                      <listitem>Creates a new image marker displaying the content of the specified image file.</listitem>
 1908                  </varlistentry>
 1909                  <varlistentry>
 1910                      <term>fileName()</term>
 1911                      <listitem>Returns the name of the file the image marker refers to.</listitem>
 1912                  </varlistentry>
 1913                  <varlistentry>
 1914                      <term>size()</term>
 1915                      <listitem>Returns the size the image takes up in paint (pixel) coordinates as a QSize.</listitem>
 1916                  </varlistentry>
 1917                  <varlistentry>
 1918                      <term>setSize(int,int)</term>
 1919                      <listitem>Sets the size the image takes up in paint (pixel) coordinates.</listitem>
 1920                  </varlistentry>
 1921                  <varlistentry>
 1922                      <term>setCoordinates(double,double,double,double)</term>
 1923                      <listitem>setCoordinates(left, top, right, bottom) changes position and size of the
 1924                          image marker in plot coordinates.</listitem>
 1925                  </varlistentry>
 1926              </variablelist>
 1927          </sect3>
 1928          <sect3><title>class Legend</title>
 1929              <para>Text boxes displayed on a graph. While this is also used for legends, a better
 1930                  (since more general) name would probably be TextMarker.</para>
 1931              <programlisting width="80">
 1932 layer = newGraph().activeLayer()
 1933 legend = layer.newLegend("hello world")
 1934 legend.setBackgroundColor(Qt.green)
 1935 legend.setTextColor(Qt.darkBlue)
 1936 legend.setFont(QtGui.QFont("Arial",14,QtGui.QFont.Bold))
 1937 layer.replot()
 1938 </programlisting>
 1939              <variablelist spacing="compact">
 1940                  <varlistentry>
 1941                      <term>setText(string)</term>
 1942                      <listitem>Changes the legend's content.</listitem>
 1943                  </varlistentry>
 1944                  <varlistentry>
 1945                      <term>setTextColor(QColor)</term>
 1946                      <listitem>Changes the text color. Most commonly, the argument will be either
 1947                          a basic color (Qt.white, Qt.black, Qt.red, Qt.darkRed etc. - see Qt.GlobalColor
 1948                          for details) or a RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with
 1949                          channels given as integers in the range [0,255] (see QColor for details).</listitem>
 1950                  </varlistentry>
 1951                  <varlistentry>
 1952                      <term>setFrameStyle(int)</term>
 1953                      <listitem>Sets the style of frame drawn around the text. 0 for none, 1 for line or
 1954                          2 for line with shadow.</listitem>
 1955                  </varlistentry>
 1956                  <varlistentry>
 1957                      <term>setBackgroundColor(QColor)</term>
 1958                      <listitem>Changes the background color. Most commonly, the argument will be either
 1959                          a basic color (Qt.white, Qt.black, Qt.red, Qt.darkRed etc. - see Qt.GlobalColor
 1960                          for details) or a RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with
 1961                          channels given as integers in the range [0,255] (see QColor for details).</listitem>
 1962                  </varlistentry>
 1963                  <varlistentry>
 1964                      <term>setFont(QFont)</term>
 1965                      <listitem>Sets the font used to render the text. See QFont documentation for how
 1966                          to construct a valid argument.</listitem>
 1967                  </varlistentry>
 1968                  <varlistentry>
 1969                      <term>setOriginCoord(double,double)</term>
 1970                      <listitem>setOriginCoord(x,y) sets the position of the top-left corner in plot coordinates.</listitem>
 1971                  </varlistentry>
 1972              </variablelist>
 1973          </sect3>
 1974          <sect3><title>class QwtSymbol</title>
 1975              <para>Represents a type of symbol on a scatter plot (ellipse, rectangle etc.) together
 1976                  with attributes determining parameters like color, size etc. This class is part of the
 1977                  Qwt library, but exported and documented as part of &appname;'s API for simplicity. Also,
 1978                  convenience methods for setting outline/fill colors are added on top of Qwt.</para>
 1979              <programlisting width="80">
 1980 symbol = QwtSymbol()
 1981 symbol.setStyle(QwtSymbol.Triangle)
 1982 symbol.setOutlineColor(QtGui.QColor(Qt.red))
 1983 symbol.setFillColor(QtGui.QColor(Qt.green))
 1984 symbol.setSize(20)
 1985 # assuming Graph1 exists and contains a plot
 1986 layer = graph("Graph1").activeLayer()
 1987 layer.curve(0).setSymbol(symbol)
 1988 layer.replot()
 1989              </programlisting>
 1990              <variablelist spacing="compact">
 1991                  <varlistentry>
 1992                      <term>QwtSymbol()</term>
 1993                      <listitem>Construct new symbol with default settings (= no symbol).</listitem>
 1994                  </varlistentry>
 1995                  <varlistentry>
 1996                      <term>QwtSymbol(Style, QBrush, QPen, QSize)</term>
 1997                      <listitem>Construct new symbol, with the four properties set as if given to setStyle(),
 1998                          setBrush(), setPen() and setSize(), respectively.</listitem>
 1999                  </varlistentry>
 2000                  <varlistentry>
 2001                      <term>setColor(QColor)</term>
 2002                      <listitem>Simultaneously sets color for filling and drawing the outline. Modifies
 2003                          pen() and brush(). Note that due to the setColor(int) overload, and unlike other
 2004                          methods accepting QColor arguments, basic colors need to be explicitly specified
 2005                          as QtGui.QColor(Qt.white) etc. instead of just Qt.white.
 2006                          As usual, it's also possible to give an RGBA spec in the form
 2007                          QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range
 2008                          [0,255] (see QColor for details).</listitem>
 2009                  </varlistentry>
 2010                  <varlistentry>
 2011                      <term>setColor(int)</term>
 2012                      <listitem>Convenience overload of setColor(QColor) choosing the color to be set from
 2013                          the palette used by &appname; for automatically assigning colors to new curves.</listitem>
 2014                  </varlistentry>
 2015                  <varlistentry>
 2016                      <term>setOutlineColor(QColor)</term>
 2017                      <listitem>Sets the color used for drawing the outline of the symbol. Modifies pen().
 2018                          Note that due to the setOutlineColor(int) overload, and unlike other
 2019                          methods accepting QColor arguments, basic colors need to be explicitly specified
 2020                          as QtGui.QColor(Qt.white) etc. instead of just Qt.white.
 2021                          As usual, it's also possible to give an RGBA spec in the form
 2022                          QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range
 2023                          [0,255] (see QColor for details).</listitem>
 2024                  </varlistentry>
 2025                  <varlistentry>
 2026                      <term>setOutlineColor(int)</term>
 2027                      <listitem>Convenience overload of setOutlineColor(QColor) choosing the color to be set from
 2028                          the palette used by &appname; for automatically assigning colors to new curves.</listitem>
 2029                  </varlistentry>
 2030                  <varlistentry>
 2031                      <term>setFillColor(QColor)</term>
 2032                      <listitem>Sets the color used for filling the interior of the symbol. Modifies brush().
 2033                          Note that due to the setFillColor(int) overload, and unlike other
 2034                          methods accepting QColor arguments, basic colors need to be explicitly specified
 2035                          as QtGui.QColor(Qt.white) etc. instead of just Qt.white.
 2036                          As usual, it's also possible to give an RGBA spec in the form
 2037                          QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range
 2038                          [0,255] (see QColor for details).</listitem>
 2039                  </varlistentry>
 2040                  <varlistentry>
 2041                      <term>setFillColor(int)</term>
 2042                      <listitem>Convenience overload of setFillColor(QColor) choosing the color to be set from
 2043                          the palette used by &appname; for automatically assigning colors to new curves.</listitem>
 2044                  </varlistentry>
 2045                  <varlistentry>
 2046                      <term>clone()</term>
 2047                      <listitem>Returns an independent copy of the symbol object.</listitem>
 2048                  </varlistentry>
 2049                  <varlistentry>
 2050                      <term>setSize(QSize)</term>
 2051                      <listitem>Sets size of the symbol in paint (pixel) coordinates.</listitem>
 2052                  </varlistentry>
 2053                  <varlistentry>
 2054                      <term>setSize(int,int=-1)</term>
 2055                      <listitem>setSize(width,height) sets the size of the symbol in paint (pixel) coordinates.
 2056                          If height=-1 (default), it is set to equal to width.</listitem>
 2057                  </varlistentry>
 2058                  <varlistentry>
 2059                      <term>setBrush(QBrush)</term>
 2060                      <listitem>Sets the brush used to fill the interior of the symbol. See PyQt documentation
 2061                          for how to construct a QBrush.</listitem>
 2062                  </varlistentry>
 2063                  <varlistentry>
 2064                      <term>setPen(QPen)</term>
 2065                      <listitem>Sets the pen used to draw the border of the symbol. See PyQt documentation
 2066                          for how to construct a QPen.</listitem>
 2067                  </varlistentry>
 2068                  <varlistentry>
 2069                      <term>setStyle(Style)</term>
 2070                      <listitem>Sets the type of symbol to draw. The argument needs to be one of the
 2071                          integer constants
 2072                          QwtSymbol.NoSymbol, QwtSymbol.Ellipse, QwtSymbol.Rect, QwtSymbol.Diamond,
 2073                          QwtSymbol.Triangle, QwtSymbol.DTriangle, QwtSymbol.UTriangle, QwtSymbol.LTriangle, 
 2074                          QwtSymbol.RTriangle, QwtSymbol.Cross, QwtSymbol.XCross, QwtSymbol.HLine,
 2075                          QwtSymbol.VLine, QwtSymbol.Star1, QwtSymbol.Star2, QwtSymbol.Hexagon.
 2076                      </listitem>
 2077                  </varlistentry>
 2078                  <varlistentry>
 2079                      <term>brush()</term>
 2080                      <listitem>Returns the currently set brush (a QBrush) for filling the interior of the symbol.
 2081                          Due to a design limitation of Qwt, setting attributes of the brush directly has no effect.
 2082                          You need to create a copy of the brush, change its attributes and hand it again to setBrush().
 2083                      </listitem>
 2084                  </varlistentry>
 2085                  <varlistentry>
 2086                      <term>pen()</term>
 2087                      <listitem>Returns the currently set pen (a QPen) for drawing the border of the symbol.
 2088                          Due to a design limitation of Qwt, setting attributes of the pen directly has no effect.
 2089                          You need to create a copy of the pen, change its attributes and hand it again to setPen().
 2090                      </listitem>
 2091                  </varlistentry>
 2092                  <varlistentry>
 2093                      <term>size()</term>
 2094                      <listitem>Returns the currently set size (a QSize) in paint (pixel) coordinates for drawing the symbol.
 2095                          Due to a design limitation of Qwt, setting attributes of the QSize directly has no effect.
 2096                          You need to create a copy of the size, change its attributes and hand it again to setSize().
 2097                      </listitem>
 2098                  </varlistentry>
 2099                  <varlistentry>
 2100                      <term>style()</term>
 2101                      <listitem>Returns an integer denoting the currently set type of symbol. See setStyle() for possible
 2102                          values.</listitem>
 2103                  </varlistentry>
 2104              </variablelist>
 2105          </sect3>
 2106          <sect3><title>class QwtPlotCurve</title>
 2107              <para>Represents a curve with symbols and/or lines on a graph.
 2108                  This class is part of the Qwt library, but exported and documented as part of
 2109                  &appname;'s API for simplicity. Also, convenience methods for setting outline/fill
 2110                  colors and fill style are added on top of Qwt.</para>
 2111              <programlisting width="80">
 2112 # assuming Graph1 exists and contains a lines plot
 2113 layer = graph("Graph1").activeLayer()
 2114 curve = layer.curve(0)
 2115 curve.setOutlineColor(QtGui.QColor(Qt.red))
 2116 curve.setFillColor(QtGui.QColor(Qt.green))
 2117 curve.setFillStyle(Qt.CrossPattern)
 2118 layer.replot()
 2119              </programlisting>
 2120              <variablelist spacing="compact">
 2121                  <varlistentry>
 2122                      <term>dataSize()</term>
 2123                      <listitem>Returns the number of points in the curve.</listitem>
 2124                  </varlistentry>
 2125                  <varlistentry>
 2126                      <term>x(int)</term>
 2127                      <listitem>Returns X coordinate of indicated point.</listitem>
 2128                  </varlistentry>
 2129                  <varlistentry>
 2130                      <term>y(int)</term>
 2131                      <listitem>Returns Y coordinate of indicated point.</listitem>
 2132                  </varlistentry>
 2133                  <varlistentry>
 2134                      <term>minXValue()</term>
 2135                      <listitem>Return smallest X value of the curve's points.</listitem>
 2136                  </varlistentry>
 2137                  <varlistentry>
 2138                      <term>maxXValue()</term>
 2139                      <listitem>Return largest X value of the curve's points.</listitem>
 2140                  </varlistentry>
 2141                  <varlistentry>
 2142                      <term>minYValue()</term>
 2143                      <listitem>Return smallest Y value of the curve's points.</listitem>
 2144                  </varlistentry>
 2145                  <varlistentry>
 2146                      <term>maxYValue()</term>
 2147                      <listitem>Return largest Y value of the curve's points.</listitem>
 2148                  </varlistentry>
 2149                  <varlistentry>
 2150                      <term>setXAxis(x-axis)</term>
 2151                      <listitem>Set the x-axis to which the curve is attached. x-axis is Layer.Bottom or Layer.Top.</listitem>
 2152                      <listitem>See also: setCurveAxes.</listitem>
 2153                  </varlistentry>
 2154                  <varlistentry>
 2155                      <term>setYAxis(y-axis)</term>
 2156                      <listitem>Set the x-axis to which the curve is attached. y-axis is Layer.Left or Layer.Right.</listitem>
 2157                      <listitem>See also: setCurveAxes.</listitem>
 2158                  </varlistentry>
 2159                  <varlistentry>
 2160                      <term>setPen(QPen)</term>
 2161                      <listitem>Sets the pen used to draw the lines of the curve. See PyQt documentation
 2162                          for how to construct a QPen.</listitem>
 2163                  </varlistentry>
 2164                  <varlistentry>
 2165                      <term>pen()</term>
 2166                      <listitem>Returns the currently set pen (a QPen) for drawing the lines of the curve.
 2167                          Due to a design limitation of Qwt, setting attributes of the pen directly has no effect.
 2168                          You need to create a copy of the pen, change its attributes and hand it again to setPen().
 2169                      </listitem>
 2170                  </varlistentry>
 2171                  <varlistentry>
 2172                      <term>setBrush(QBrush)</term>
 2173                      <listitem>Sets the brush used to fill the area under the curve. See PyQt documentation
 2174                          for how to construct a QBrush.</listitem>
 2175                  </varlistentry>
 2176                  <varlistentry>
 2177                      <term>brush()</term>
 2178                      <listitem>Returns the currently set brush (a QBrush) for filling the area under the curve.
 2179                          Due to a design limitation of Qwt, setting attributes of the brush directly has no effect.
 2180                          You need to create a copy of the brush, change its attributes and hand it again to setBrush().
 2181                      </listitem>
 2182                  </varlistentry>
 2183                  <varlistentry>
 2184                      <term>setSymbol(QwtSymbol)</term>
 2185                      <listitem>Specifies whether and how symbols are drawn. See class QwtSymbol.</listitem>
 2186                  </varlistentry>
 2187                  <varlistentry>
 2188                      <term>symbol()</term>
 2189                      <listitem>Returns symbol parameters currently in effect. See class QwtSymbol.
 2190                          Due to a design limitation of Qwt, setting attributes of the symbol directly has no effect.
 2191                          You need to create a copy of the symbol, change its attributes and hand it again to setSymbol().
 2192                      </listitem>
 2193                  </varlistentry>
 2194                  <varlistentry>
 2195                      <term>setColor(QColor)</term>
 2196                      <listitem>Simultaneously sets color for drawing lines and filling the area under the
 2197                          curve. Modifies
 2198                          pen() and brush(). Note that due to the setColor(int) overload, and unlike other
 2199                          methods accepting QColor arguments, basic colors need to be explicitly specified
 2200                          as QtGui.QColor(Qt.white) etc. instead of just Qt.white.
 2201                          As usual, it's also possible to give an RGBA spec in the form
 2202                          QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range
 2203                          [0,255] (see QColor for details).</listitem>
 2204                  </varlistentry>
 2205                  <varlistentry>
 2206                      <term>setColor(int)</term>
 2207                      <listitem>Convenience overload of setColor(QColor) choosing the color to be set from
 2208                          the palette used by &appname; for automatically assigning colors to new curves.</listitem>
 2209                  </varlistentry>
 2210                  <varlistentry>
 2211                      <term>setOutlineColor(QColor)</term>
 2212                      <listitem>Sets the color used for drawing the lines of the curve. Modifies pen().
 2213                          Note that due to the setOutlineColor(int) overload, and unlike other
 2214                          methods accepting QColor arguments, basic colors need to be explicitly specified
 2215                          as QtGui.QColor(Qt.white) etc. instead of just Qt.white.
 2216                          As usual, it's also possible to give an RGBA spec in the form
 2217                          QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range
 2218                          [0,255] (see QColor for details).</listitem>
 2219                  </varlistentry>
 2220                  <varlistentry>
 2221                      <term>setOutlineColor(int)</term>
 2222                      <listitem>Convenience overload of setOutlineColor(QColor) choosing the color to be set from
 2223                          the palette used by &appname; for automatically assigning colors to new curves.</listitem>
 2224                  </varlistentry>
 2225                  <varlistentry>
 2226                      <term>setFillColor(QColor)</term>
 2227                      <listitem>Sets the color used for filling the area under the curve. Modifies brush().
 2228                          Note that due to the setFillColor(int) overload, and unlike other
 2229                          methods accepting QColor arguments, basic colors need to be explicitly specified
 2230                          as QtGui.QColor(Qt.white) etc. instead of just Qt.white.
 2231                          As usual, it's also possible to give an RGBA spec in the form
 2232                          QtGui.QColor(red, green, yellow, alpha) with channels given as integers in the range
 2233                          [0,255] (see QColor for details).</listitem>
 2234                  </varlistentry>
 2235                  <varlistentry>
 2236                      <term>setFillColor(int)</term>
 2237                      <listitem>Convenience overload of setFillColor(QColor) choosing the color to be set from
 2238                          the palette used by &appname; for automatically assigning colors to new curves.</listitem>
 2239                  </varlistentry>
 2240                  <varlistentry>
 2241                      <term>setFillStyle(Qt.BrushStyle)</term>
 2242                      <listitem>Set pattern used for filling the area under the curve. Argument must be one of
 2243                          Qt.SolidPattern, Qt.Dense1Pattern, Qt.Dense2Pattern, Qt.Dense3Pattern, Qt.Dense4Pattern,
 2244                          Qt.Dense5Pattern, Qt.Dense6Pattern, Qt.Dense7Pattern, Qt.NoBrush, Qt.HorPattern,
 2245                          Qt.VerPattern, Qt.CrossPattern, Qt.BDiagPattern, Qt.FDiagPattern, Qt.DiagCrossPattern,
 2246                          Qt.LinearGradientPattern, Qt.RadialGradientPattern, Qt.ConicalGradientPattern.
 2247                          See PyQt documentation for visual overview and more information.
 2248                      </listitem>
 2249                  </varlistentry>
 2250              </variablelist>
 2251          </sect3>
 2252          <sect3><title>class Grid</title>
 2253              <para>Handles options related to the grid drawn on a Layer. Added in &appname; 0.2.4.</para>
 2254              <programlisting width="80">
 2255 layer = newGraph().activeLayer()
 2256 layer.showGrid()
 2257 layer.grid().setMajorPen(QtGui.QColor(Qt.black))
 2258 layer.replot()
 2259              </programlisting>
 2260              <variablelist spacing="compact">
 2261                  <varlistentry>
 2262                      <term>setMajor(bool)</term>
 2263                      <listitem>Enables/disables drawing of major grid lines for both axes.</listitem>
 2264                  </varlistentry>
 2265                  <varlistentry>
 2266                      <term>setXMajor(bool)</term>
 2267                      <listitem>Enables/disables drawing of major grid lines for X axis.</listitem>
 2268                  </varlistentry>
 2269                  <varlistentry>
 2270                      <term>setYMajor(bool)</term>
 2271                      <listitem>Enables/disables drawing of major grid lines for Y axis.</listitem>
 2272                  </varlistentry>
 2273                  <varlistentry>
 2274                      <term>xMajor()</term>
 2275                      <listitem>Boolean indicating whether major grid lines for X axis are enabled.</listitem>
 2276                  </varlistentry>
 2277                  <varlistentry>
 2278                      <term>yMajor()</term>
 2279                      <listitem>Boolean indicating whether major grid lines for Y axis are enabled.</listitem>
 2280                  </varlistentry>
 2281                  <varlistentry>
 2282                      <term>setMinor(bool)</term>
 2283                      <listitem>Enables/disables drawing of minor grid lines for both axes.</listitem>
 2284                  </varlistentry>
 2285                  <varlistentry>
 2286                      <term>setXMinor(bool)</term>
 2287                      <listitem>Enables/disables drawing of minor grid lines for X axis.</listitem>
 2288                  </varlistentry>
 2289                  <varlistentry>
 2290                      <term>setYMinor(bool)</term>
 2291                      <listitem>Enables/disables drawing of minor grid lines for Y axis.</listitem>
 2292                  </varlistentry>
 2293                  <varlistentry>
 2294                      <term>xMinor()</term>
 2295                      <listitem>Boolean indicating whether minor grid lines for X axis are enabled.</listitem>
 2296                  </varlistentry>
 2297                  <varlistentry>
 2298                      <term>yMinor()</term>
 2299                      <listitem>Boolean indicating whether minor grid lines for Y axis are enabled.</listitem>
 2300                  </varlistentry>
 2301                  <varlistentry>
 2302                      <term>setXZeroLine(bool)</term>
 2303                      <listitem>Enables/disables drawing of line at X=0.</listitem>
 2304                  </varlistentry>
 2305                  <varlistentry>
 2306                      <term>xZeroLine()</term>
 2307                      <listitem>Boolean indicating whether a line is drawn at X=0.</listitem>
 2308                  </varlistentry>
 2309                  <varlistentry>
 2310                      <term>setYZeroLine(bool)</term>
 2311                      <listitem>Enables/disables drawing of line at Y=0.</listitem>
 2312                  </varlistentry>
 2313                  <varlistentry>
 2314                      <term>yZeroLine()</term>
 2315                      <listitem>Boolean indicating whether a line is drawn at Y=0.</listitem>
 2316                  </varlistentry>
 2317                  <varlistentry>
 2318                      <term>setMajorPen(QPen)</term>
 2319                      <listitem>Sets color, line width, line style etc. of major grid lines. See PyQt
 2320                          reference for class QPen.</listitem>
 2321                  </varlistentry>
 2322                  <varlistentry>
 2323                      <term>setXMajorPen(QPen)</term>
 2324                      <listitem>Sets color, line width, line style etc. of major grid lines for X axis.
 2325                          See PyQt reference for class QPen.</listitem>
 2326                  </varlistentry>
 2327                  <varlistentry>
 2328                      <term>setYMajorPen(QPen)</term>
 2329                      <listitem>Sets color, line width, line style etc. of major grid lines for Y axis.
 2330                          See PyQt reference for class QPen.</listitem>
 2331                  </varlistentry>
 2332                  <varlistentry>
 2333                      <term>xMajorPen()</term>
 2334                      <listitem>Returns QPen used for drawing major grid lines for X axis.
 2335                          See PyQt reference for class QPen.</listitem>
 2336                  </varlistentry>
 2337                  <varlistentry>
 2338                      <term>yMajorPen()</term>
 2339                      <listitem>Returns QPen used for drawing major grid lines for Y axis.
 2340                          See PyQt reference for class QPen.</listitem>
 2341                  </varlistentry>
 2342                  <varlistentry>
 2343                      <term>setMinorPen(QPen)</term>
 2344                      <listitem>Sets color, line width, line style etc. of minor grid lines. See PyQt
 2345                          reference for class QPen.</listitem>
 2346                  </varlistentry>
 2347                  <varlistentry>
 2348                      <term>setXMinorPen(QPen)</term>
 2349                      <listitem>Sets color, line width, line style etc. of minor grid lines for X axis.
 2350                          See PyQt reference for class QPen.</listitem>
 2351                  </varlistentry>
 2352                  <varlistentry>
 2353                      <term>setYMinorPen(QPen)</term>
 2354                      <listitem>Sets color, line width, line style etc. of minor grid lines for Y axis.
 2355                          See PyQt reference for class QPen.</listitem>
 2356                  </varlistentry>
 2357                  <varlistentry>
 2358                      <term>xMinorPen()</term>
 2359                      <listitem>Returns QPen used for drawing minor grid lines for X axis.
 2360                          See PyQt reference for class QPen.</listitem>
 2361                  </varlistentry>
 2362                  <varlistentry>
 2363                      <term>yMinorPen()</term>
 2364                      <listitem>Returns QPen used for drawing minor grid lines for Y axis.
 2365                          See PyQt reference for class QPen.</listitem>
 2366                  </varlistentry>
 2367              </variablelist>
 2368          </sect3>
 2369          <sect3><title>class Layer (inherits QWidget)</title>
 2370              <para>A layer on a graph. All elements in a graph are organized in layers, so whenever
 2371                  you're working with graphs, you're also dealing with layers. Note that many changes
 2372                  do not show up until you call replot() - if you're changing many options on a complex
 2373                  layer, this is faster than automatically updating the layer on every change.</para>
 2374              <programlisting width="80">
 2375 layer = newGraph().activeLayer()
 2376 layer.setTitle("Murphy Certainty Principle")
 2377 layer.setXTitle("time")
 2378 layer.setYTitle("motivation")
 2379 layer.insertFunctionCurve("1/x", 0, 10)
 2380 # the constants QwtPlot.xBottom (=2) and QwtPlot.yLeft (=0) were added in &appname; 0.2.4
 2381 layer.setScale(QwtPlot.xBottom, 0, 10)
 2382 layer.setScale(QwtPlot.yLeft, 0, 10)
 2383 layer.setBackgroundColor(QtGui.QColor(18,161,0))
 2384 layer.setCanvasColor(QtGui.QColor(161,120,50))
 2385 layer.curve(0).setPen(QtGui.QPen(Qt.yellow, 3))
 2386 layer.removeLegend()
 2387 layer.replot()
 2388              </programlisting>
 2389              <variablelist spacing="compact">
 2390                  <varlistentry>
 2391                      <term>isPiePlot()</term>
 2392                      <listitem>Boolean indicating whether this layer is a pie plot. Pie plots are
 2393                          always on a separate layer.</listitem>
 2394                  </varlistentry>
 2395                  <varlistentry>
 2396                      <term>pieLegend()</term>
 2397                      <listitem>Returns content of legend, assuming this layer is a pie plot.
 2398                          See isPiePlot().</listitem>
 2399                  </varlistentry>
 2400                  <varlistentry>
 2401                      <term>insertCurve(Table, string, int, int)</term>
 2402                      <listitem>insertCurve(table, column, style=1, color=-1) plots the data of the
 2403                          specified Y column and the corresponding designated X column, optionally
 2404                          specifying style and color, and returning a boolean indicating success or
 2405                          failure. Color is an index in the palette used by &appname;
 2406                          for automatically assigning colors to new curves. Style is one of the following
 2407                          codes:
 2408                          <variablelist spacing="compact">
 2409                              <varlistentry>
 2410                                  <term>0</term><listitem>Line</listitem>
 2411                              </varlistentry>
 2412                              <varlistentry>
 2413                                  <term>1</term><listitem>Symbols</listitem>
 2414                              </varlistentry>
 2415                              <varlistentry>
 2416                                  <term>2</term><listitem>Line and Symbols</listitem>
 2417                              </varlistentry>
 2418                              <varlistentry>
 2419                                  <term>3</term><listitem>Columns</listitem>
 2420                              </varlistentry>
 2421                              <varlistentry>
 2422                                  <term>4</term><listitem>Area</listitem>
 2423                              </varlistentry>
 2424                              <varlistentry>
 2425                                  <term>5</term><listitem>Pie</listitem>
 2426                              </varlistentry>
 2427                              <varlistentry>
 2428                                  <term>6</term><listitem>Vertical drop lines</listitem>
 2429                              </varlistentry>
 2430                              <varlistentry>
 2431                                  <term>7</term><listitem>Splines and Symbols</listitem>
 2432                              </varlistentry>
 2433                              <varlistentry>
 2434                                  <term>8</term><listitem>Vertical steps</listitem>
 2435                              </varlistentry>
 2436                              <varlistentry>
 2437                                  <term>9</term><listitem>Histogram</listitem>
 2438                              </varlistentry>
 2439                              <varlistentry>
 2440                                  <term>10</term><listitem>Rows</listitem>
 2441                              </varlistentry>
 2442                          </variablelist>
 2443                      </listitem>
 2444                  </varlistentry>
 2445                  <varlistentry>
 2446                      <term>insertCurve(Table, string, string int, int)</term>
 2447                      <listitem>insertCurve(table, x_column, y_column style=1, color=-1) works like the
 2448                          other insertCurve() variant above, but allows you to explicitly specify the
 2449                          X column you want to plot against instead of determining it by designation.
 2450                      </listitem>
 2451                  </varlistentry>
 2452                  <varlistentry>
 2453                      <term>insertFunctionCurve(string, double=0, double=1, int=100, string=QtCore.QString())</term>
 2454                      <listitem>insertFunctionCurve(formula, start, end, points, title) inserts a function
 2455                          curve specified by formula, which is evaluated using muParser with abscissa "x", and
 2456                          returns a boolean indicating success or failure.
 2457                          Optionally, the interval [start,end] for the evaluation, the number of points
 2458                          where the function will be evaluated and the curve title can be given.
 2459                          Added in &appname; 0.2.4.
 2460                      </listitem>
 2461                  </varlistentry>
 2462                  <varlistentry>
 2463                      <term>insertPolarCurve(string, string, double=0, double=2*pi, string=&quot;t&quot;, int=100,
 2464                          string=QtCore.QString())</term>
 2465                      <listitem>insertPolarCurve(radial, angular, start, end, parameter, points, title)
 2466                          inserts a function curve specified by formulas for the radial and angular
 2467                          components in polar coordinates, both of which are evaluated using muParser
 2468                          with given parameter (&quot;t&quot; by default), and returns a boolean indicating
 2469                          success or failure. Optionally, the interval [start,end]
 2470                          covered by the free parameter, the number of points where the function will be
 2471                          evaluated and the curve title can be overridden.
 2472                          Added in &appname; 0.2.4.
 2473                      </listitem>
 2474                  </varlistentry>
 2475                  <varlistentry>
 2476                      <term>insertParametricCurve(string, string, double=0, double=1,
 2477                          string=&quot;t&quot;, int=100, string=QtCore.QString())</term>
 2478                      <listitem>insertParametricCurve(x_formula, y_formula, from, to, parameter, points, title)
 2479                          insert a function curve specified by formulas for the abscissa and ordinate
 2480                          components in cartesian coordinates, both of which are evaluated using muParser
 2481                          with given parameter (&quot;t&quot; by default), and returns a boolean indicating
 2482                          success or failure. Optionally, the interval [start,end]
 2483                          covered by the free parameter, the number of points where the function will be
 2484                          evaluated and the curve title can be overridden.
 2485                          Added in &appname; 0.2.4.
 2486                      </listitem>
 2487                  </varlistentry>
 2488                  <varlistentry>
 2489                      <term>addErrorBars(string, Table, string, int=1, int=1, int=8,
 2490                          QColor=QColor(Qt.black), bool=True, bool=True, bool=True)</term>
 2491                      <listitem>addErrorBars(curve, table, err_col_name, orientation, width, cap_length, color,
 2492                          through, minus, plus) adds error bars to the curve specified by its name (as
 2493                          displayed in the add/remove curve dialog and the curves' context menu). Data
 2494                          for the error bars is taken from the given table and column. Optionally, you can
 2495                          override the orientation (default is 1 for vertical, 0 means horizontal), the
 2496                          width of the pen used to draw the error bars, the length of the caps in pixels,
 2497                          the color of the pen used to draw the error bars, and flags indicating whether
 2498                          the error bars' line strikes through the underlying curve, and whether the minus
 2499                          and plus side of the error bars are to be drawn.
 2500                      </listitem>
 2501                  </varlistentry>
 2502                  <varlistentry>
 2503                      <term>removeCurve(int or string)</term>
 2504                      <listitem>Remove curve specified by index (in the range [0,numCurves()-1]) or title.</listitem>
 2505                  </varlistentry>
 2506                  <varlistentry>
 2507                      <term>deleteFitCurves()</term>
 2508                      <listitem>Remove all curves that show the result of a fit operation.</listitem>
 2509                  </varlistentry>
 2510                  <varlistentry>
 2511                      <term>numCurves()</term>
 2512                      <listitem>Returns the number of curves plotted on this layer.</listitem>
 2513                  </varlistentry>
 2514                  <varlistentry>
 2515                      <term>showCurve(int,bool)</term>
 2516                      <listitem>Show/hide the curve specified by its index (in the range [0,numCurves()-1]).
 2517                          Hidden curves are not plotted, but otherwise remain part of the Layer; they keep
 2518                          their legend item, count as part of numCurves(), can be accessed by curve() etc.
 2519                      </listitem>
 2520                  </varlistentry>
 2521                  <varlistentry>
 2522                      <term>curve(int or string)</term>
 2523                      <listitem>Access curve (as QwtPlotCurve instance) specified by its title (as displayed
 2524                          in the add/remove curves dialog and the curve's context menu) or index (integer
 2525                          in the range [0,numCurves()-1].</listitem>
 2526                  </varlistentry>
 2527                  <varlistentry>
 2528                      <term>curves()</term>
 2529                      <listitem>Returns a list of all curves in the layer. Added in &appname; 0.2.4.</listitem>
 2530                  </varlistentry>
 2531                  <varlistentry>
 2532                      <term>addArrow(ArrowMarker)</term>
 2533                      <listitem>Add the indicated arrow/line marker to the layer. See class ArrowMarker.
 2534                      </listitem>
 2535                  </varlistentry>
 2536                  <varlistentry>
 2537                      <term>addImage(ImageMarker or string)</term>
 2538                      <listitem>Add an image marker to the layer. For convenience, you can simply specify
 2539                          the path of the file containing the image in place of an ImageMarker object. In
 2540                          any case, the added ImageMarker is returned.</listitem>
 2541                  </varlistentry>
 2542                  <varlistentry>
 2543                      <term>setTitle(string)</term>
 2544                      <listitem>Change the layer's title string.</listitem>
 2545                  </varlistentry>
 2546                  <varlistentry>
 2547                      <term>newLegend()</term>
 2548                      <listitem>Return a new, empty Legend (text marker) object after adding it to this
 2549                          layer.</listitem>
 2550                  </varlistentry>
 2551                  <varlistentry>
 2552                      <term>newLegend(string)</term>
 2553                      <listitem>Return a new Legend (text marker) object initialized with the given
 2554                          string, after adding it to the layer.</listitem>
 2555                  </varlistentry>
 2556                  <varlistentry>
 2557                      <term>setLegend(string)</term>
 2558                      <listitem>Set the name of the main legend (i.e., the <emphasis>real</emphasis>
 2559                          legend, as opposed to other texts placed on the layer).</listitem>
 2560                  </varlistentry>
 2561                  <varlistentry>
 2562                      <term>legend()</term>
 2563                      <listitem>Returns the Legend object representing the <emphasis>real</emphasis>
 2564                          legend, as opposed to other texts placed on the layer.</listitem>
 2565                  </varlistentry>
 2566                  <varlistentry>
 2567                      <term>removeLegend()</term>
 2568                      <listitem>Remove the legend (i.e., the object returned by legend()), if one
 2569                          currently exists.</listitem>
 2570                  </varlistentry>
 2571                  <varlistentry>
 2572                      <term>addTimeStamp</term>
 2573                      <listitem>Add a text marker containing the current date and time.</listitem>
 2574                  </varlistentry>
 2575                  <varlistentry>
 2576                      <term>enableAxis(int,bool)</term>
 2577                      <listitem>Enable/disable drawing of the indicating axis, which must be one of the
 2578                          integer constants QwtPlot.yLeft (=0), QwtPlot.yRight (=1), QwtPlot.xBottom (=2)
 2579                          or QwtPlot.xTop (=3). The descriptive names were added in &appname; 0.2.4; for
 2580                          prior versions, you need to specify the indicated integer values.</listitem>
 2581                  </varlistentry>
 2582                  <varlistentry>
 2583                      <term>setXTitle(string)</term>
 2584                      <listitem>Set the title displayed for the (bottom) X axis. The axis title can be
 2585                          disabled by setting it to an empty string.</listitem>
 2586                  </varlistentry>
 2587                  <varlistentry>
 2588                      <term>setYTitle(string)</term>
 2589                      <listitem>Set the title displayed for the (left) Y axis. The axis title can be
 2590                          disabled by setting it to an empty string.</listitem>
 2591                  </varlistentry>
 2592                  <varlistentry>
 2593                      <term>setRightTitle(string)</term>
 2594                      <listitem>Set the title displayed for the right Y axis. The axis title can be
 2595                          disabled by setting it to an empty string. Added in &appname; 0.2.4.</listitem>
 2596                  </varlistentry>
 2597                  <varlistentry>
 2598                      <term>setTopTitle(string)</term>
 2599                      <listitem>Set the title displayed for the top X axis. The axis title can be
 2600                          disabled by setting it to an empty string. Added in &appname; 0.2.4.</listitem>
 2601                  </varlistentry>
 2602                  <varlistentry>
 2603                      <term>setAxisNumericFormat(int, int, int=6, string=QString())</term>
 2604                      <listitem>setAxisNumericFormat(axis, format, precision, formula) sets the numeric
 2605                          format used for drawing the axis labels on the specified axis (see enableAxis()
 2606                          for possible arguments). Format must be one of 0 (automatic), 1 (decimal),
 2607                          2 (scientific) or 3 (superscripts). Precision is the number of digits displayed.
 2608                          If a formula is given, it is evaluated with muParser for every label and the
 2609                          result is used in place of the input value for displaying the label.</listitem>
 2610                  </varlistentry>
 2611                  <varlistentry>
 2612                      <term>setScale(int, double, double, double=0, int=5, int=5, int=0, bool=False)</term>
 2613                      <listitem>setScale(axis, start, end, step, major_ticks, minor_ticks, type, inverted)
 2614                          sets various options related to the scale of the indicated axis (see enableAxis()
 2615                          for possible arguments); most notably the start and end values of the displayed
 2616                          data range. Step indicates the distance between major tick marks (the default of
 2617                          0 means to automatically determine a sensible value); alternatively, a target
 2618                          number of major tick marks (and minor tick marks per major tick) can be specified,
 2619                          but due to limitations of Qwt, this is only taken as a hint, not as a strictly
 2620                          followed setting. Type is either 0 (linear scale, default) or 1 (logarithmic
 2621                          scale). The last flag can be set to have the axis inverted, i.e. numbered right
 2622                          to left or top-down.</listitem>
 2623                  </varlistentry>
 2624                  <varlistentry>
 2625                      <term>setMargin(int)</term>
 2626                      <listitem>Change the margin (i.e., the spacing around the complete content) of the
 2627                          layer.</listitem>
 2628                  </varlistentry>
 2629                  <varlistentry>
 2630                      <term>setFrame(int=1, QColor=QColor(Qt.black))</term>
 2631                      <listitem>setFrame(width, color) draws a frame around the complete content (including
 2632                          margin) of the layer; with the indicated line width and color.</listitem>
 2633                  </varlistentry>
 2634                  <varlistentry>
 2635                      <term>setBackgroundColor(QColor)</term>
 2636                      <listitem>Changes the background color of the layer. Note that this excludes the
 2637                          background of the canvas area containing the curves and markers, which is set
 2638                          separately (see setCanvasColor()). Most commonly, the argument will be either
 2639                          a basic color (Qt.white, Qt.black, Qt.red, Qt.darkRed etc. - see Qt.GlobalColor
 2640                          for details) or a RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with
 2641                          channels given as integers in the range [0,255] (see QColor for details).</listitem>
 2642                  </varlistentry>
 2643                  <varlistentry>
 2644                      <term>setCanvasColor(QColor)</term>
 2645                      <listitem>Changes the background color of the canvas area containing the curves and
 2646                          markers. Most commonly, the argument will be either
 2647                          a basic color (Qt.white, Qt.black, Qt.red, Qt.darkRed etc. - see Qt.GlobalColor
 2648                          for details) or a RGBA spec in the form QtGui.QColor(red, green, yellow, alpha) with
 2649                          channels given as integers in the range [0,255] (see QColor for details).</listitem>
 2650                  </varlistentry>
 2651                  <varlistentry>
 2652                      <term>showGrid(int)</term>
 2653                      <listitem>Toggle drawing of major and minor grid associated with the given axis.
 2654                          See enableAxis() for possible arguments.</listitem>
 2655                  </varlistentry>
 2656                  <varlistentry>
 2657                      <term>showGrid()</term>
 2658                      <listitem>Toggle drawing of all grid lines.</listitem>
 2659                  </varlistentry>
 2660                  <varlistentry>
 2661                      <term>grid()</term>
 2662                      <listitem>Returns the Grid object for this layer, which holds various grid-related
 2663                          settings. See class Grid. Added in &appname; 0.2.4.</listitem>
 2664                  </varlistentry>
 2665                  <varlistentry>
 2666                      <term>replot()</term>
 2667                      <listitem>Makes sure that any changes you've applied to the layer are displayed on
 2668                          screen. It is often necessary to call this method after making script-driven
 2669                          changes to a layer, like changing the style of a curve. It is also a good idea
 2670                          to call this before export to a file, although it's not technically required for
 2671                          all file formats.</listitem>
 2672                  </varlistentry>
 2673                  <varlistentry>
 2674                      <term>printDialog()</term>
 2675                      <listitem>Display dialog for printing out this layer. Added in &appname; 0.2.4.</listitem>
 2676                  </varlistentry>
 2677                  <varlistentry>
 2678                      <term>exportImage(string, int=100, bool=False)</term>
 2679                      <listitem>exportImage(filename, quality, transparent) exports the layer to a bitmap
 2680                          image format with the indicated quality level, optionally making the background
 2681                          transparent (if supported by the file format). The file format is determined by
 2682                          the extension of the indicated file name; the list of supported formats depends
 2683                          on your installation of Qt and can be viewed by invoking the export dialog from
 2684                          the GUI and looking through the &quot;file type&quot; box.</listitem>
 2685                  </varlistentry>
 2686                  <varlistentry>
 2687                      <term>exportVector(string, int=0, bool=True, bool=True,
 2688                          QPrinter.PageSize=QtGui.QPrinter.Custom)</term>
 2689                      <listitem>exportVector(filename, resolution, color, keep_aspect, page_size) exports
 2690                          the layer to a vector-based file format. You can override the default resolution
 2691                          (in dpi), toggle printing in color/monochrome, toggle whether to keep the
 2692                          width/height aspect when rescaling and select a standard page size as described
 2693                          in the PyQt documentation for QtGui.QPrinter.PageSize.</listitem>
 2694                  </varlistentry>
 2695                  <varlistentry>
 2696                      <term>export(string)</term>
 2697                      <listitem>Quickly export layer to the indicated file, without bothering about the
 2698                          exportImage()/exportVector() distinction and related options. The file format
 2699                          is determined automatically by looking at the extension of the specified file
 2700                          name; supported formats depend on your installation of Qt and can be viewed by
 2701                          invoking the export dialog from the GUI and looking through the
 2702                          &quot;file type&quot; box.</listitem>
 2703                  </varlistentry>
 2704                  <varlistentry>
 2705                      <term>enableAutoscaling(bool=True)</term>
 2706                      <listitem>Set automatic updating of the scale settings (see setScale()) when data
 2707                          is added to or changed on the layer.</listitem>
 2708                  </varlistentry>
 2709                  <varlistentry>
 2710                      <term>setIgnoreResize(bool=True)</term>
 2711                      <listitem>Sets whether to keep the layer's geometry fixed when resizing its graph.
 2712                      </listitem>
 2713                  </varlistentry>
 2714                  <varlistentry>
 2715                      <term>setAutoscaleFonts(bool=True)</term>
 2716                      <listitem>Sets whether to scale font sizes together with the rest of the layer
 2717                          when its graph is resized (and resizes aren't ignored, see setIgnoreResize()).
 2718                      </listitem>
 2719                  </varlistentry>
 2720                  <varlistentry>
 2721                      <term>setAntialiasing(bool=True, bool=True)</term>
 2722                      <listitem>setAntialiasing(antialias, update) specifies whether antialiasing should
 2723                          be used for drawing elements added to the layer after the call to
 2724                          setAntialiasing(). If the update flag is True (default), the antialiasing setting
 2725                          of existing elements is updated as well.</listitem>
 2726                  </varlistentry>
 2727                  <varlistentry>
 2728                      <term>setCurveAxes(number, x-axis, y-axis)</term>
 2729                      <listitem>Note: when using this method the involved axes are autoscaled.</listitem>
 2730                      <listitem>See also: setXAxis, setYAxis</listitem>
 2731                  </varlistentry>
 2732                  <varlistentry>
 2733                      <term>canvas()</term>
 2734                      <listitem>Gives access to the QtGui.QWidget acting as a canvas, i.e it contains all
 2735                          curves and markers on the layer (but not axes and title).</listitem>
 2736                  </varlistentry>
 2737                  <varlistentry>
 2738                      <term>pickPoint()</term>
 2739                      <listitem>Let the user pick a point on a curve (as with the Data Reader tool) and
 2740                          return the coordinates of the selected point as a QPointF (coordinates can be
 2741                          extracted from the result using QPointF.x() and QPointF.y()).
 2742                          Added in &appname; 0.2.4.
 2743                      </listitem>
 2744                  </varlistentry>
 2745              </variablelist>
 2746          </sect3>
 2747          <sect3><title>class Graph (inherits MDIWindow)</title>
 2748              <para>A graph window, consisting of layers, which in turn contain plot curves and markers.
 2749              </para>
 2750              <programlisting width="80">
 2751 g = newGraph()
 2752 layer1 = g.activeLayer()
 2753 layer2 = g.addLayer()
 2754 g.setMargins(40,40,40,40)
 2755 g.arrangeLayers()
 2756              </programlisting>
 2757              <variablelist spacing="compact">
 2758                  <varlistentry>
 2759                      <term>activeLayer()</term>
 2760                      <listitem>Returns the Layer currently marked as active (as indicated by the
 2761                          layer buttons at the top of the graph). If there is only one layer, it is
 2762                          always the active one.</listitem>
 2763                  </varlistentry>
 2764                  <varlistentry>
 2765                      <term>setActiveLayer(Layer)</term>
 2766                      <listitem>Make the indicated layer the active one.</listitem>
 2767                  </varlistentry>
 2768                  <varlistentry>
 2769                      <term>numLayers()</term>
 2770                      <listitem>Returns the total number of layers contained in the graph.</listitem>
 2771                  </varlistentry>
 2772                  <varlistentry>
 2773                      <term>layer(int)</term>
 2774                      <listitem>Returns the Layer specified by index (integer in the range
 2775                          [1,numLayers()]).</listitem>
 2776                  </varlistentry>
 2777                  <varlistentry>
 2778                      <term>layers()</term>
 2779                      <listitem>Returns a list of all layers in the graph. Added in &appname; 0.2.4.</listitem>
 2780                  </varlistentry>
 2781                  <varlistentry>
 2782                      <term>addLayer(int=0,int=0,int=0,int=0)</term>
 2783                      <listitem>addLayer(x,y,width,height) adds a new layer at the given position and
 2784                          with the given size. Returns the newly created Layer object.</listitem>
 2785                  </varlistentry>
 2786                  <varlistentry>
 2787                      <term>setCols(int)</term>
 2788                      <listitem>Set the number of columns to use when arranging layers automatically.
 2789                          Doesn't take effect until a re-arrangement is requested by calling
 2790                          arrangeLayers().</listitem>
 2791                  </varlistentry>
 2792                  <varlistentry>
 2793                      <term>setRows(int)</term>
 2794                      <listitem>Set the number of rows to use when arranging layers automatically.
 2795                          Doesn't take effect until a re-arrangement is requested by calling
 2796                          arrangeLayers().</listitem>
 2797                  </varlistentry>
 2798                  <varlistentry>
 2799                      <term>setSpacing(int,int)</term>
 2800                      <listitem>setSpacing(row_gap, column_gap) sets the spacing to use between
 2801                          rows and columns when arranging layers automatically.
 2802                          Doesn't take effect until a re-arrangement is requested by calling
 2803                          arrangeLayers().</listitem>
 2804                  </varlistentry>
 2805                  <varlistentry>
 2806                      <term>setMargins(int,int,int,int)</term>
 2807                      <listitem>setMargins(left,right,top,bottom) sets the outer margins to use
 2808                          when arranging layers automatically.
 2809                          Doesn't take effect until a re-arrangement is requested by calling
 2810                          arrangeLayers().</listitem>
 2811                  </varlistentry>
 2812                  <varlistentry>
 2813                      <term>setLayerCanvasSize(int, int)</term>
 2814                      <listitem>setLayerCanvasSize(width,height) Resizes all layers as indicated and
 2815                          arranges them automatically.</listitem>
 2816                  </varlistentry>
 2817                  <varlistentry>
 2818                      <term>setAlignment(int, int)</term>
 2819                      <listitem>setAlignment(horizontal, vertical) sets the alignement of layers in their
 2820                          respective columns and rows. Arguments can be 0 For center, 1 for left/top and 2
 2821                          for right/bottom. Added in &appname; 0.2.4.</listitem>
 2822                  </varlistentry>
 2823                  <varlistentry>
 2824                      <term>arrangeLayers(bool)</term>
 2825                      <listitem>Automatically arranges the layers on the graph, subject to built-in
 2826                          defaults or settings made previously using setCols(), setRows(), setSpacing(),
 2827                          setMargins() and setAlignment().</listitem>
 2828                  </varlistentry>
 2829                  <varlistentry>
 2830                      <term>exportImage(string, int=100, bool=False)</term>
 2831                      <listitem>exportImage(filename, quality, transparent) exports the graph to a bitmap
 2832                          image format with the indicated quality level, optionally making the background
 2833                          transparent (if supported by the file format). The file format is determined by
 2834                          the extension of the indicated file name; the list of supported formats depends
 2835                          on your installation of Qt and can be viewed by invoking the export dialog from
 2836                          the GUI and looking through the &quot;file type&quot; box.</listitem>
 2837                  </varlistentry>
 2838                  <varlistentry>
 2839                      <term>exportVector(string, int=0, bool=True, bool=True,
 2840                          QPrinter.PageSize=QtGui.QPrinter.Custom)</term>
 2841                      <listitem>exportVector(filename, resolution, color, keep_aspect, page_size) exports
 2842                          the graph to a vector-based file format. You can override the default resolution
 2843                          (in dpi), toggle printing in color/monochrome, toggle whether to keep the
 2844                          width/height aspect when rescaling and select a standard page size as described
 2845                          in the PyQt documentation for QtGui.QPrinter.PageSize.</listitem>
 2846                  </varlistentry>
 2847                  <varlistentry>
 2848                      <term>export(string)</term>
 2849                      <listitem>Quickly export graph to the indicated file, without bothering about the
 2850                          exportImage()/exportVector() distinction and related options. The file format
 2851                          is determined automatically by looking at the extension of the specified file
 2852                          name; supported formats depend on your installation of Qt and can be viewed by
 2853                          invoking the export dialog from the GUI and looking through the
 2854                          &quot;file type&quot; box.</listitem>
 2855                  </varlistentry>
 2856                  <varlistentry>
 2857                      <term>printDialog()</term>
 2858                      <listitem>Display dialog for printing out this layer. Added in &appname; 0.2.4.</listitem>
 2859                  </varlistentry>
 2860              </variablelist>
 2861          </sect3>
 2862          <sect3><title>class Note (inherits MDIWidget)</title>
 2863              <para>A note/script window containing arbitrary text, all or parts of which can be executed
 2864                  as Python code. Triggering executing of code in a Note currently doesn't work reliably,
 2865                  but this can essentially be circumvented using exec(str(note.text())).</para>
 2866              <programlisting width="80">
 2867 n = newNote()
 2868 n.setText("Hello World")
 2869 n.exportASCII("output.txt")
 2870              </programlisting>
 2871              <variablelist spacing="compact">
 2872                  <varlistentry>
 2873                      <term>autoexec()</term>
 2874                      <listitem>Boolean indicating whether the content of Note is automatically executed
 2875                          when loading the project.</listitem>
 2876                  </varlistentry>
 2877                  <varlistentry>
 2878                      <term>setAutoexec(bool)</term>
 2879                      <listitem>Sets whether to automatically executed the content of the Note when loading
 2880                          the project.</listitem>
 2881                  </varlistentry>
 2882                  <varlistentry>
 2883                      <term>text()</term>
 2884                      <listitem>Returns the content of the note as a QString.</listitem>
 2885                  </varlistentry>
 2886                  <varlistentry>
 2887                      <term>setText(string)</term>
 2888                      <listitem>Sets the content of the note.</listitem>
 2889                  </varlistentry>
 2890                  <varlistentry>
 2891                      <term>exportASCII(string)</term>
 2892                      <listitem>Writes the content of the note to the indicated file.</listitem>
 2893                  </varlistentry>
 2894                  <varlistentry>
 2895                      <term>importASCII(string)</term>
 2896                      <listitem>Prepends the content of the note by the content of the indicated file.
 2897                      </listitem>
 2898                  </varlistentry>
 2899              </variablelist>
 2900          </sect3>
 2901          <sect3><title>class ApplicationWindow (inherits QMainWindow)</title>
 2902              <para>Manages the current project. The project from which a piece of Python code is
 2903                  executed is accessible via the module attribute <varname>scidavis.app</varname>.
 2904                  However, most of the time, this instance is used implicitly via methods copied to the
 2905                  global namespace by the default scidavisrc.py configuration file.</para>
 2906              <programlisting width="80">
 2907 for win in app.windows():
 2908     print win.name()
 2909 app.activeFolder().save("subproject.sciprj")
 2910              </programlisting>
 2911              <variablelist spacing="compact">
 2912                  <varlistentry>
 2913                      <term>table(string)</term>
 2914                      <listitem>Returns the table with the given name, or None if no such table exists.
 2915                      </listitem>
 2916                  </varlistentry>
 2917                  <varlistentry>
 2918                      <term>newTable()</term>
 2919                      <listitem>Creates a new table with default settings (as if done using the menu) and
 2920                          returns it.</listitem>
 2921                  </varlistentry>
 2922                  <varlistentry>
 2923                      <term>newTable(string, int=2, int=30)</term>
 2924                      <listitem>newTable(name, columns, rows) creates a new table with the given name and
 2925                          (optionally) numbers of columns and rows, and returns it. If the specified name
 2926                          is already in use, it is changed automatically to a unique name by appending a
 2927                          number to the requested name.</listitem>
 2928                  </varlistentry>
 2929                  <varlistentry>
 2930                      <term>matrix(string)</term>
 2931                      <listitem>Returns the matrix with the given name, or None if no such matrix exists.
 2932                      </listitem>
 2933                  </varlistentry>
 2934                  <varlistentry>
 2935                      <term>newMatrix()</term>
 2936                      <listitem>Creates a new matrix with default settings (as if done using the menu) and
 2937                          returns it.</listitem>
 2938                  </varlistentry>
 2939                  <varlistentry>
 2940                      <term>newMatrix(string, int=32, int=32)</term>
 2941                      <listitem>newMatrix(name, rows, columns) creates a new matrix with the given name and
 2942                          (optionally) numbers of columns and rows, and returns it. If the specified name
 2943                          is already in use, it is changed automatically to a unique name by appending a
 2944                          number to the requested name.</listitem>
 2945                  </varlistentry>
 2946                  <varlistentry>
 2947                      <term>graph(string)</term>
 2948                      <listitem>Returns the graph with the given name, or None if no such graph exists.
 2949                      </listitem>
 2950                  </varlistentry>
 2951                  <varlistentry>
 2952                      <term>newGraph()</term>
 2953                      <listitem>Creates a new graph containing one empty layer (as if done using the menu) and
 2954                          returns it.</listitem>
 2955                  </varlistentry>
 2956                  <varlistentry>
 2957                      <term>newGraph(string)</term>
 2958                      <listitem>newGraph(name) creates a new graph with the given name containing one empty
 2959                          layer (as if done using the menu) and returns it. If the specified name
 2960                          is already in use, it is changed automatically to a unique name by appending a
 2961                          number to the requsted name. Added in &appname; 0.2.4.</listitem>
 2962                  </varlistentry>
 2963                  <varlistentry>
 2964                      <term>note(string)</term>
 2965                      <listitem>Returns the note window with the given name, or None if no such note exists.
 2966                      </listitem>
 2967                  </varlistentry>
 2968                  <varlistentry>
 2969                      <term>newNote()</term>
 2970                      <listitem>Creates a new empty note and returns it.</listitem>
 2971                  </varlistentry>
 2972                  <varlistentry>
 2973                      <term>newNote(string)</term>
 2974                      <listitem>newNote(name) creates a new empty note with the given name and returns it.
 2975                          If the specified name is already in use, it is changed automatically to a unique
 2976                          name by generating a default name like &quot;Notes1&quot;. This is inconsistent
 2977                          with newTable(), newMatrix and newGraph() (which generate a unique name by
 2978                          appending a number to the <emphasis>requested</emphasis> name) and will probably
 2979                          change in a future release.
 2980                      </listitem>
 2981                  </varlistentry>
 2982                  <varlistentry>
 2983                      <term>plot(Table, string, int=1, int=-1)</term>
 2984                      <listitem>plot(table, column, style, color) plots the named column of the given
 2985                          table. A new graph is created containing one layer, to which the curve is
 2986                          added. The new graph is returned. Optionally, style and color of the curve
 2987                          can be set, where color is an index in the palette used by &appname;
 2988                          for automatically assigning colors to new curves and style is one of the
 2989                          following codes:
 2990                          <variablelist spacing="compact">
 2991                              <varlistentry>
 2992                                  <term>0</term><listitem>Line</listitem>
 2993                              </varlistentry>
 2994                              <varlistentry>
 2995                                  <term>1</term><listitem>Symbols</listitem>
 2996                              </varlistentry>
 2997                              <varlistentry>
 2998                                  <term>2</term><listitem>Line and Symbols</listitem>
 2999                              </varlistentry>
 3000                              <varlistentry>
 3001                                  <term>3</term><listitem>Columns</listitem>
 3002                              </varlistentry>
 3003                              <varlistentry>
 3004                                  <term>4</term><listitem>Area</listitem>
 3005                              </varlistentry>
 3006                              <varlistentry>
 3007                                  <term>5</term><listitem>Pie</listitem>
 3008                              </varlistentry>
 3009                              <varlistentry>
 3010                                  <term>6</term><listitem>Vertical drop lines</listitem>
 3011                              </varlistentry>
 3012                              <varlistentry>
 3013                                  <term>7</term><listitem>Splines and Symbols</listitem>
 3014                              </varlistentry>
 3015                              <varlistentry>
 3016                                  <term>8</term><listitem>Vertical steps</listitem>
 3017                              </varlistentry>
 3018                              <varlistentry>
 3019                                  <term>9</term><listitem>Histogram</listitem>
 3020                              </varlistentry>
 3021                              <varlistentry>
 3022                                  <term>10</term><listitem>Rows</listitem>
 3023                              </varlistentry>
 3024                          </variablelist>
 3025                      </listitem>
 3026                  </varlistentry>
 3027                  <varlistentry>
 3028                      <term>plot(Table, tuple of strings, int=1, int=-1)</term>
 3029                      <listitem>plot(table, (column1, column2, ...), style, color) works just like the
 3030                          plot method described above, but plots multiple columns together on the same
 3031                          layer.</listitem>
 3032                  </varlistentry>
 3033                  <varlistentry>
 3034                      <term>importImage(string)</term>
 3035                      <listitem>Reads an image from the specified file and returns a newly created matrix
 3036                          containing the gray-scale values (brightness) of the image's pixels.</listitem>
 3037                  </varlistentry>
 3038                  <varlistentry>
 3039                      <term>importImage()</term>
 3040                      <listitem>Ask the user to select an image file and imports it to a newly created
 3041                          matrix as described above. Returns the matrix.</listitem>
 3042                  </varlistentry>
 3043                  <varlistentry>
 3044                      <term>plotContour(Matrix)</term>
 3045                      <listitem>Makes a contour plot from the given matrix in a newly created graph.
 3046                          Returns the graph.</listitem>
 3047                  </varlistentry>
 3048                  <varlistentry>
 3049                      <term>plotColorMap(Matrix)</term>
 3050                      <listitem>Makes a contour plot from the given matrix, filling contour areas with
 3051                          colors of the default color map. Returns the newly created graph.</listitem>
 3052                  </varlistentry>
 3053                  <varlistentry>
 3054                      <term>plotGrayScale(Matrix)</term>
 3055                      <listitem>Makes a gray scale plot from the given matrix in a newly created graph.
 3056                          Returns the graph.</listitem>
 3057                  </varlistentry>
 3058                  <varlistentry>
 3059                      <term>windows()</term>
 3060                      <listitem>Returns a list of all MDIWindow instances in the project.</listitem>
 3061                  </varlistentry>
 3062                  <varlistentry>
 3063                      <term>results</term>
 3064                      <listitem>The QTextEdit which holds the results log. Can be used to output custom
 3065                          results from your script, although the recommended way of doing this is to
 3066                          create a Note and set its text to what you want to output.</listitem>
 3067                  </varlistentry>
 3068                  <varlistentry>
 3069                      <term>activeFolder()</term>
 3070                      <listitem>Returns the folder which is currently being displayed.</listitem>
 3071                  </varlistentry>
 3072                  <varlistentry>
 3073                      <term>setActiveFolder(folder)</term>
 3074                      <listitem>Given a Folder object, changes the active folder to it.
 3075                          Since MDIWindows are always added to the active folder, this is necessary for
 3076                          script-driven creation of objects in specific sub-folders. Added in &appname; 0.2.5.
 3077                      </listitem>
 3078                  </varlistentry>
 3079                  <varlistentry>
 3080                      <term>rootFolder()</term>
 3081                      <listitem>Returns the root folder of the project.</listitem>
 3082                  </varlistentry>
 3083                  <varlistentry>
 3084                      <term>saveFolder(Folder, string)</term>
 3085                      <listitem>DEPRECATED. &appname; 0.2.4 introduces the new method Folder.save(), which is the
 3086                          recommended way of saving folders to a new project file; unless you need the
 3087                          code to run on previous versions.</listitem>
 3088                  </varlistentry>
 3089                  <varlistentry>
 3090                      <term>renameWindow(MDIWindow, string)</term>
 3091                      <listitem>DEPRECATED. &appname; 0.2.4 introduces the new method MDIWindow.setName(),
 3092                          which is the recommended way of renaming windows; unless you need the code to run
 3093                          on previous versions.</listitem>
 3094                  </varlistentry>
 3095                  <varlistentry>
 3096                      <term>clone(MDIWindow)</term>
 3097                      <listitem>DEPRECATED. &appname; 0.2.4 introduces the new method MDIWindow.clone(),
 3098                          which is the recommended way of cloning windows; unless you need the code to run
 3099                          on previous versions.</listitem>
 3100                  </varlistentry>
 3101                  <varlistentry>
 3102                      <term>setPreferences(Layer)</term>
 3103                      <listitem>DEPRECATED. Prior to &appname; 0.2.4, it was necessary to call this on a
 3104                          layer created using Graph.addLayer() if you wanted the layer to be initialized
 3105                          correctly. This is now done automatically as part of addLayer(); doing so again
 3106                          doesn't hurt, but is not necessary any more. 
 3107                      </listitem>
 3108                  </varlistentry>
 3109              </variablelist>
 3110          </sect3>
 3111          <sect3><title>class Fit (inherits QObject)</title>
 3112              <para>This is the abstract base class of the various models that can be used for
 3113                  least-squares parameter fitting; in other words, you can only create instances of
 3114                  subclasses of this class, but the methods described here are common to all of these
 3115                  classes (ExponentialFit, SigmoidalFit etc.).</para>
 3116              <programlisting width="80">
 3117              </programlisting>
 3118              <variablelist spacing="compact">
 3119                  <varlistentry>
 3120                      <term>Fit(ApplicationWindow, Layer, string)</term>
 3121                      <listitem>Constructor, taking the ApplicationWindow instance to which the Fit will belong,
 3122                          the Layer containing data to be fitted (and receiving the result curve) and a name
 3123                          for the fitter. Mainly interesting if you want to implement a custom fitter as a
 3124                          subclass of Fit.</listitem>
 3125                  </varlistentry>
 3126                  <varlistentry>
 3127                      <term>fit()</term>
 3128                      <listitem>Executes the fit (after setting data and parameters). Must be reimplemented by
 3129                          subclasses.</listitem>
 3130                  </varlistentry>
 3131                  <varlistentry>
 3132                      <term>setYErrorSource(ErrorSource, string="")</term>
 3133                      <listitem>Specify the standard errors of the Y values (compare setDataFromCurve()).
 3134                          ErrorSource is one of Fit.UnknownErrors (no weighting is done and errors are
 3135                          estimated from the variance of the input values), Fit.AssociatedErrors (the yErr
 3136                          column associated with the source column is used), Fit.PoissonErrors (input
 3137                          values are Poisson distributed, i.e. errors are equal to the square root of the
 3138                          values) or Fit.CustomErrors (the name of the column containing the errors is
 3139                          given as the second parameter).</listitem>
 3140                  </varlistentry>
 3141                  <varlistentry>
 3142                      <term>setDataFromCurve(string, Layer)</term>
 3143                      <listitem>Use the curve (given by name) on the given layer as the fit data.
 3144                          Returns a boolean indicating success (True) or failure (False).</listitem>
 3145                  </varlistentry>
 3146                  <varlistentry>
 3147                      <term>setDataFromCurve(string, double, double, Layer)</term>
 3148                      <listitem>DEPRECATED. Use the variant above followed by setInterval() instead.</listitem>
 3149                  </varlistentry>
 3150                  <varlistentry>
 3151                      <term>setInterval(double, double)</term>
 3152                      <listitem>setInterval(from,to) restricts the X interval of the data points included
 3153                          in the fit to [from,to].</listitem>
 3154                  </varlistentry>
 3155                  <varlistentry>
 3156                      <term>formula()</term>
 3157                      <listitem>Returns the formula of the fit model (in a format suitable for evaluation
 3158                          with muParser).</listitem>
 3159                  </varlistentry>
 3160                  <varlistentry>
 3161                      <term>numParameters()</term>
 3162                      <listitem>Returns the number of free parameters in the fit.</listitem>
 3163                  </varlistentry>
 3164                  <varlistentry>
 3165                      <term>setInitialValue(int, double)</term>
 3166                      <listitem>setInitialValue(index, value) specifies the initial value for the parameter
 3167                          given by index.</listitem>
 3168                  </varlistentry>
 3169                  <varlistentry>
 3170                      <term>setInitialValues(sequence)</term>
 3171                      <listitem>Set initial values of all parameters at once.</listitem>
 3172                  </varlistentry>
 3173                  <varlistentry>
 3174                      <term>guessInitialValues()</term>
 3175                      <listitem>Try to determine sensible initial values for the parameters automatically.
 3176                          Can be reimplemented by subclasses if they want to support this feature;
 3177                          currently, only SigmoidalFit and MultiPeakFit can do this trick.</listitem>
 3178                  </varlistentry>
 3179                  <varlistentry>
 3180                      <term>setAlgorithm(Algorithm)</term>
 3181                      <listitem>Set the fitting algorithm; one of Fit.ScaledLevenbergMarquardt,
 3182                          Fit.UnscaledLevenbergMarquardt or Fit.NelderMeadSimplex.</listitem>
 3183                  </varlistentry>
 3184                  <varlistentry>
 3185                      <term>setTolerance(double)</term>
 3186                      <listitem>Set the tolerance up to which the result has to be determined. The Fit
 3187                          algorithm is iterated until either the desired tolerance or the maximum number of
 3188                          iterations (see setMaximumIterations()) is reached; in the latter case, it aborts
 3189                          with a failure notice.</listitem>
 3190                  </varlistentry>
 3191                  <varlistentry>
 3192                      <term>setColor(int)</term>
 3193                      <listitem>Set the color of the generated fit curve from the palette used by &appname;
 3194                          for automatically assigning colors to new curves. (Specifying a color by name is
 3195                          DEPRECATED, because its counter-intuitive behaviour was more likely to cause
 3196                          trouble than to make things easier.)</listitem>
 3197                  </varlistentry>
 3198                  <varlistentry>
 3199                      <term>setOutputPrecision(int)</term>
 3200                      <listitem>Set the number of decimal places to use when formatting numbers for output
 3201                          to the results log or to a graph.</listitem>
 3202                  </varlistentry>
 3203                  <varlistentry>
 3204                      <term>generateFunction(bool, int=100)</term>
 3205                      <listitem>By default, fit results are pasted into the target graph layer as a function
 3206                          curve. Calling generateFunction(False, num_points) causes the fit results to be
 3207                          written into a hidden table (with num_points data points) and plotted from there.
 3208                          This may be useful if you want to use fit results for further calculations.
 3209                      </listitem>
 3210                  </varlistentry>
 3211                  <varlistentry>
 3212                      <term>setMaximumIterations(int)</term>
 3213                      <listitem>Sets the maximum number of times to iterate the fitting algorithm before
 3214                          giving up and declaring the fit to have failed.
 3215                      </listitem>
 3216                  </varlistentry>
 3217                  <varlistentry>
 3218                      <term>showLegend()</term>
 3219                      <listitem>
 3220                          Insert information on the fit into the target graph layer.
 3221                      </listitem>
 3222                  </varlistentry>
 3223                  <varlistentry>
 3224                      <term>legendInfo()</term>
 3225                      <listitem>
 3226                          Return the information inserted by showLegend() as a string. Can be overridden by
 3227                          subclasses in order to customize it.
 3228                      </listitem>
 3229                  </varlistentry>
 3230                  <varlistentry>
 3231                      <term>scaleErrors(bool)</term>
 3232                      <listitem>
 3233                          Set flag indicating whether to multiply standard errors of final parameters by
 3234                          &chi;<superscript>2</superscript>/(degrees of freedom). Defaults to False.
 3235                      </listitem>
 3236                  </varlistentry>
 3237                  <varlistentry>
 3238                      <term>results()</term>
 3239                      <listitem>
 3240                          Returns the final parameters as a tuple of floats.
 3241                      </listitem>
 3242                  </varlistentry>
 3243                  <varlistentry>
 3244                      <term>errors()</term>
 3245                      <listitem>
 3246                          Returns standard errors of final parameters as a tuple of floats.
 3247                      </listitem>
 3248                  </varlistentry>
 3249                  <varlistentry>
 3250                      <term>chiSquare()</term>
 3251                      <listitem>
 3252                          Returns the sum of squares of the residuals from the best-fit line.
 3253                      </listitem>
 3254                  </varlistentry>
 3255                  <varlistentry>
 3256                      <term>rSquare()</term>
 3257                      <listitem>
 3258                          Returns the coefficient of determination of the best-fit line.
 3259                      </listitem>
 3260                  </varlistentry>
 3261                  <varlistentry>
 3262                      <term>parametersTable(string)</term>
 3263                      <listitem>
 3264                          Creates a Table with the given name and fills it with the final parameter values.
 3265                          Returns a reference to the Table window.
 3266                      </listitem>
 3267                  </varlistentry>
 3268                  <varlistentry>
 3269                      <term>covarianceMatrix(string)</term>
 3270                      <listitem>
 3271                          Creates a Matrix with the given name and fills it with the covariance matrix of
 3272                          the final parameter values. Returns a reference to the Matrix window.
 3273                      </listitem>
 3274                  </varlistentry>
 3275              </variablelist>
 3276          </sect3>
 3277          <sect3>
 3278              <title>class Folder (inherits QObject)</title>
 3279              <variablelist spacing="compact">
 3280                  <varlistentry>
 3281                      <term>Folder(name)</term>
 3282                      <listitem>Construct a new folder with the given name. You can add it as a subfolder
 3283                          to an existing one using addChild() (see below).
 3284                      </listitem>
 3285                  </varlistentry>
 3286                  <varlistentry>
 3287                      <term>windows()</term>
 3288                      <listitem>
 3289                          Returns the list of MDIWindows contained in this folder.
 3290                      </listitem>
 3291                  </varlistentry>
 3292                  <varlistentry>
 3293                      <term>name()</term>
 3294                      <listitem>Returns the name of this folder (a string).</listitem>
 3295                  </varlistentry>
 3296                  <varlistentry>
 3297                      <term>path()</term>
 3298                      <listitem>Returns the absolute path of this folder within its project (a string).</listitem>
 3299                  </varlistentry>
 3300                  <varlistentry>
 3301                      <term>folders()</term>
 3302                      <listitem>Returns the list of sub-folders.</listitem>
 3303                  </varlistentry>
 3304                  <varlistentry>
 3305                      <term>folder(string, bool=True, bool=False)</term>
 3306                      <listitem>
 3307                          folder(name, case_sensitive, partial_match) returns the first subfolder matching
 3308                          the given name. A subfolders is considered to match if its name equals the name
 3309                          argument; if partial_match is True, it is also considered to match if its name
 3310                          starts with the name argument. Matching can be made case-insensitive by setting
 3311                          the case_sensitive argument to False.
 3312                      </listitem>
 3313                  </varlistentry>
 3314                  <varlistentry>
 3315                      <term>findWindow(string, bool=True, bool=True, bool=False, bool=True)</term>
 3316                      <listitem>findWindow(str, match_name, match_label, case_sensitive, partial_match)
 3317                          returns the first MDI window whose name (if match_name is True) or label (if
 3318                          match_label is True) matches the given string. A name or label is considered to
 3319                          match if it equals the string argument; if partial_match is True, it is also
 3320                          considered to match if its name starts with the name argument. Matching can be
 3321                          made case-sensitive by setting the case_sensitive argument to True.
 3322                      </listitem>
 3323                  </varlistentry>
 3324                  <varlistentry>
 3325                      <term>table(string, bool=False)</term>
 3326                      <listitem>table(name, recursive) returns the table of the given name in this folder;
 3327                          if no such table exists and recursive is True, sub-folders are searched as well.
 3328                      </listitem>
 3329                  </varlistentry>
 3330                  <varlistentry>
 3331                      <term>matrix(string, bool=False)</term>
 3332                      <listitem>matrix(name, recursive) returns the matrix of the given name in this folder;
 3333                          if no such matrix exists and recursive is True, sub-folders are searched as well.
 3334                      </listitem>
 3335                  </varlistentry>
 3336                  <varlistentry>
 3337                      <term>graph(string, bool=False)</term>
 3338                      <listitem>graph(name, recursive) returns the graph of the given name in this folder;
 3339                          if no such graph exists and recursive is True, sub-folders are searched as well.
 3340                      </listitem>
 3341                  </varlistentry>
 3342                  <varlistentry>
 3343                      <term>note(string, bool=False)</term>
 3344                      <listitem>note(name, recursive) returns the note of the given name in this folder;
 3345                          if no such note exists and recursive is True, sub-folders are searched as well.
 3346                      </listitem>
 3347                  </varlistentry>
 3348                  <varlistentry>
 3349                      <term>rootFolder()</term>
 3350                      <listitem>Returns the root folder of the project this folder belongs to.
 3351                      </listitem>
 3352                  </varlistentry>
 3353                  <varlistentry>
 3354                      <term>save(string)></term>
 3355                      <listitem>Given a file name, saves the content of this folder as a project file.
 3356                          Added in &appname; 0.2.4.</listitem>
 3357                  </varlistentry>
 3358                  <varlistentry>
 3359                      <term>addChild(folder)</term>
 3360                      <listitem>Adds another folder as a sub-folders to this one.
 3361                          Added in &appname; 0.2.5.</listitem>
 3362                  </varlistentry>
 3363              </variablelist>
 3364          </sect3>
 3365      </sect2>
 3366 
 3367     <sect2 id="Python-init">
 3368       <title>The Initialization File</title>
 3369 
 3370       <para>This file allows you to customize the Python environment, import
 3371       modules and define functions and classes that will be available in all
 3372       of your projects. The default initialization file shipped with &appname;
 3373       imports Python's <link linkend="Python-functions">standard math
 3374       functions</link> as well as special functions from <ulink
 3375         url="https://www.scipy.org">SciPy</ulink> and <ulink
 3376         url="http://pygsl.sourceforge.net">PyGSL</ulink>(if available). Also, it
 3377       creates some handy shortcuts, like
 3378       <userinput>table("table1")</userinput> for
 3379       <userinput>&python-pref;.app.table("table1")</userinput>.</para>
 3380 
 3381       <para>When activating Python support, &appname; searches the following
 3382       places, executing the first file it can find:</para>
 3383 
 3384       <orderedlist>
 3385         <listitem>
 3386           <para>~/.&python-rc;[c]</para>
 3387         </listitem>
 3388 
 3389         <listitem>
 3390           <para>/etc/&python-rc;[c]</para>
 3391         </listitem>
 3392 
 3393         <listitem>
 3394           <para>./&python-rc;[c]</para>
 3395         </listitem>
 3396       </orderedlist>
 3397 
 3398       <para>Files ending in .pyc are compiled versions of the .py source files
 3399       and therefore load a bit faster. The compiled version will be used if
 3400       the source file is older or nonexistent. Otherwise, &appname; will try to
 3401       compile the source file (if you've got write permissions for the output
 3402       file).</para>
 3403 
 3404         <sect3>
 3405             <title>Recommended approach to per-user configuration</title>
 3406 
 3407             <para>
 3408                 In order to give you full control over the process of setting up the
 3409                 Python environment within &appname;, a per-user configuration file
 3410                 (.&python-rc;) will supersede any system-wide configuration file. That
 3411                 is, GSL and SciPy functions as well as many &appname;-specific
 3412                 functions (like table(), newTable(), plot(), etc.) will be missing,
 3413                 unless you explicitly import them into the global namespace. In order
 3414                 to keep the overview over their customizations and profit from updates
 3415                 to the global configuration files (e.g. with new versions of
 3416                 &appname;), most users will want to import the global configuration
 3417                 file from within their custom one. Here's how to do this:
 3418             </para>
 3419 
 3420             <programlisting width="40">
 3421 import sys 
 3422 sys.path.append("/etc") 
 3423 import scidavisrc 
 3424 # your custom stuff
 3425 </programlisting>
 3426         </sect3>
 3427     </sect2>
 3428 
 3429   </sect1>