From df613ab82974bcbc00bb4e466065bc96db276d6f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Andr=C3=A9=20Wobst?= Date: Fri, 17 Jan 2003 10:15:30 +0000 Subject: [PATCH] documentation: extern variables, minior updates git-svn-id: https://pyx.svn.sourceforge.net/svnroot/pyx/trunk/pyx@606 069f4177-920e-0410-937b-c2a4a81bcd90 --- manual/{datafile.tex => data.tex} | 141 ++++++++++++++++++++------------------ manual/graph.tex | 74 ++++++++++---------- 2 files changed, 108 insertions(+), 107 deletions(-) rename manual/{datafile.tex => data.tex} (65%) diff --git a/manual/datafile.tex b/manual/data.tex similarity index 65% rename from manual/datafile.tex rename to manual/data.tex index 3502ce12..9b78d73c 100644 --- a/manual/datafile.tex +++ b/manual/data.tex @@ -1,5 +1,4 @@ -% $Header$ -\chapter{Module datafile: reading a datafile} +\chapter{Module data} \label{datafile} \section{Reading a table from a file} @@ -78,10 +77,13 @@ expression. When the expression contains an equal sign (\verb|=|), everything left to the last equal sign will become the title of the new column. If no equal sign is found, the title will be set to \verb|None|. The part right to the last equal sign is interpreted as -an mathematical expression. A list of functions and operators can be -found in appendix~\ref{mathtree}. The expression might contain -variable names. The interpretation of this names is done in the -following way: +an mathematical expression. A list of functions, predefined variables +and operators can be found in appendix~\ref{mathtree}. The list of +available functions and predefined variables can be extended by a +dictionary passed as the argument \verb|extern| to the constructor. + +The expression might contain variable names. The interpretation of +this names is done in the following way: \begin{itemize} \item The names can be a column title, but this is only allowed for column titles which are valid variable names (e.g. they should start @@ -95,78 +97,81 @@ parameter should be a valid parameter of the \verb|getcolumnno| method. \item A variable name can start with the dollar symbol (\verb|$|) and the following integer number will directly refer to a column number. -To implement this third possibility, the mathematical expression -parser is extended within the datafile module (cf. section -\ref{datafile:cumulate}). \end{itemize} The data referenced by variables in the expression need to be floats, otherwise the result for that data line will be \verb|None|. Examples are \verb|addcolumn("av=(min+max)/2")|, \verb|addcolumn("av=(a+b+$3)/2", a=1, b="max")|. -\section{Dirty tricks for mathematics on columns} -\label{datafile:cumulate} - -I want to present a solution for cumulating data in a new column. -As told in the title of this section, it is considered to be a dirty -trick, because it relies on side effects in the calculation of the new -column, namely it sums up the result in a hidden variable. While -that is wanted, it is nothing I would ever consider to do officially -(don't expect the following lines to become part of \PyX{} in the -future). On the other hand, nothing could be told about using this -tick and I don't expect that this feature will break in future -versions. Somehow, it is needed and the possibility to implement this -trick has to stay. - -What we want to do is to add another function within the allowed -expression syntax for doing mathematics on columns. We supply a class -which we can hook it into the mathematical expression parser later on: - -\begin{quote} -\begin{verbatim} -from pyx import mathtree - -class Cumulate(mathtree.MathTreeFunc1): - - def __init__(self, *args): - mathtree.MathTreeFunc1.__init__(self, "cumulate", *args) - self.sum = 0 - - def Calc(self, VarDict): - self.sum += self.ArgV[0].Calc(VarDict) - return self.sum - -MyFuncs = mathtree.DefaultMathTreeFuncs + (Cumulate,) -\end{verbatim} -\end{quote} - -Please note, that you explicitly have to import \verb|mathtree|, -because its not usually needed in \PyX{} applications and thus it is -not imported by \verb|from pyx import *|. - -To finally use \verb|cumulate|, you have to supply a new parser to the -datafile, where the new generated list of available functions is -placed in: - -\begin{quote} -\begin{verbatim} -df = datafile.datafile("mydata", - parser=mathtree.parser( - MathTreeFuncs=MyFuncs, - MathTreeVals=datafile.MathTreeValsWithCol)) -df.addcolumn("sum=cumulate(costs)") -\end{verbatim} -\end{quote} - -The explicit setting of \verb|MathTreeVals| is needed in order to keep -column variables working. Variables starting with the dollar symbol -(\verb|$|) are not allowed within the original mathtree. +% \section{Dirty tricks for mathematics on columns} +% \label{datafile:cumulate} +% +% I want to present a solution for cumulating data in a new column. +% As told in the title of this section, it is considered to be a dirty +% trick, because it relies on side effects in the calculation of the new +% column, namely it sums up the result in a hidden variable. While +% that is wanted, it is nothing I would ever consider to do officially +% (don't expect the following lines to become part of \PyX{} in the +% future). On the other hand, nothing could be told about using this +% tick and I don't expect that this feature will break in future +% versions. Somehow, it is needed and the possibility to implement this +% trick has to stay. +% +% What we want to do is to add another function within the allowed +% expression syntax for doing mathematics on columns. We supply a class +% which we can hook it into the mathematical expression parser later on: +% +% \begin{quote} +% \begin{verbatim} +% from pyx import mathtree +% +% class Cumulate(mathtree.MathTreeFunc1): +% +% def __init__(self, *args): +% mathtree.MathTreeFunc1.__init__(self, "cumulate", *args) +% self.sum = 0 +% +% def Calc(self, VarDict): +% self.sum += self.ArgV[0].Calc(VarDict) +% return self.sum +% +% MyFuncs = mathtree.DefaultMathTreeFuncs + (Cumulate,) +% \end{verbatim} +% \end{quote} +% +% Please note, that you explicitly have to import \verb|mathtree|, +% because its not usually needed in \PyX{} applications and thus it is +% not imported by \verb|from pyx import *|. +% +% To finally use \verb|cumulate|, you have to supply a new parser to the +% datafile, where the new generated list of available functions is +% placed in: +% +% \begin{quote} +% \begin{verbatim} +% df = datafile.datafile("mydata", +% parser=mathtree.parser( +% MathTreeFuncs=MyFuncs, +% MathTreeVals=datafile.MathTreeValsWithCol)) +% df.addcolumn("sum=cumulate(costs)") +% \end{verbatim} +% \end{quote} +% +% The explicit setting of \verb|MathTreeVals| is needed in order to keep +% column variables working. Variables starting with the dollar symbol +% (\verb|$|) are not allowed within the original mathtree. + +\section{reading data from a sectioned config file} + +The class \verb|sectionfile| provides a reader for files in the +ConfigFile format (see \verb|ConfigFile| from the pyx standard +library). \section{Own datafile readers} The development of other datafile readers should be based on the -helper class \verb|_datafile| by inheritance. When doing so, the -methods \verb|getcolumnno|, \verb|getcolumn|, and \verb|addcolumn| are +helper class \verb|data| by inheritance. When doing so, the methods +\verb|getcolumnno|, \verb|getcolumn|, and \verb|addcolumn| are immediately available and the cooperation with other parts of \PyX{} is assured. All what has to be done, is a call to the inherited constructor supplying the title list and a list of data points. A data diff --git a/manual/graph.tex b/manual/graph.tex index a9ffc3d5..7db43ead 100644 --- a/manual/graph.tex +++ b/manual/graph.tex @@ -499,7 +499,7 @@ default. \subsection{List of points} Instances of the class \verb|data| link a \verb|datafile| and a -\verb|style| (see below; default is \verb|mark|). The link object is +\verb|style| (see below; default is \verb|symbol|). The link object is needed in order to be able to plot several data from a singe file without reading the file several times which would just be a bad design. However, for easy usage, it is possible to provide a filename @@ -539,9 +539,9 @@ parameter. The expression must be a string with exactly one equal sign (\verb|=|). At the left side the result axis identifier must be placed and at the right side the expression must depend on exactly one variable axis identifier. Hence, a valid expression looks like -\verb|"y=sin(x)"|. You may use the string format syntax to insert -external parameters, \textit{e.g.} \verb|"y=sin(%f*x)" % a| where -\verb|a| is a float variable. +\verb|"y=sin(x)"|. You can access own variables and functions by +providing them as a dictionary to the constructors \verb|extern| +argument. Additional named parameters of the constructor are: @@ -553,6 +553,7 @@ argument name&default&description\\ \texttt{max}&\texttt{None}&as above, but for the maximum\\ \texttt{points}&\texttt{100}&number of points to be calculated\\ \texttt{parser}&\texttt{mathtree.parser()}&parser for the mathematical expression\\ +\texttt{extern}&\texttt{None}&dictionary of extern variables and functions\\ \end{tabularx} \medskip @@ -574,26 +575,21 @@ expression assigning functions to the axis identifiers in a quite pythonic tuple notation. As an example, such an expression could look like \verb|"x, y = sin(k), cos(3*k)"|. -Additionally, the two named parameters \verb|points| and \verb|parser| -behave like their equally named counterparts in \verb|function|. +Additionally, the named parameters \verb|points|, \verb|parser|, and +\verb|extern| behave like their equally named counterparts in +\verb|function|. \section{Styles} \label{graph:styles} Styles are used to draw data at a graph. A style determines what is painted and how it is painted. Due to this powerfull approach there -are already some different marker types available and the possibility -to introduce other styles opens even more prospects. +are already some different styles available and the possibility to +introduce other styles opens even more prospects. -On the other hand there is not yet any support for bar graphs. This is -due to the fact that it might be better implemented together with some -specialized axes. It will be shown in the future, what solution will -arise out of that idea instead of an disposable implementation right -now. +\subsection{Symbols} -\subsection{Marks} - -The class \verb|mark| can be used to plot markers, errorbars and lines +The class \verb|symbol| can be used to plot symbols, errorbars and lines configurable by parameters of the constructor. Providing \verb|None| to attributes hides the according component. @@ -601,21 +597,21 @@ to attributes hides the according component. \begin{tabularx}{\linewidth}{ll>{\raggedright\arraybackslash}X} argument name&default&description\\ \hline -\texttt{mark}&\texttt{changemark.cross()}&marker to be used (see below)\\ -\texttt{size}&\texttt{"0.2 cm"}&size of the marker (visual length)\\ -\texttt{markattrs}&\texttt{canvas.stroked()}&draw attributes for the marker\\ -\texttt{errorscale}&\texttt{0.5}&size of the errorbar caps (relative to the marker size)\\ +\texttt{symbol}&\texttt{changesymbol.cross()}&symbol to be used (see below)\\ +\texttt{size}&\texttt{"0.2 cm"}&size of the symbol (visual length)\\ +\texttt{symbolattrs}&\texttt{canvas.stroked()}&draw attributes for the symbol\\ +\texttt{errorscale}&\texttt{0.5}&size of the errorbar caps (relative to the symbol size)\\ \texttt{errorbarattrs}&\texttt{()}&stroke attributes for the errorbars\\ \texttt{lineattrs}&\texttt{None}&stroke attributes for the line\\ \end{tabularx} \medskip -The parameter \verb|mark| has to be a routine, which returns a path to +The parameter \verb|symbol| has to be a routine, which returns a path to be drawn (e.g. stoked or filled). There are several those routines -already available in the class \verb|mark|, namely \verb|cross|, +already available in the class \verb|symbol|, namely \verb|cross|, \verb|plus|, \verb|square|, \verb|triangle|, \verb|circle|, and \verb|diamond|. Furthermore, changeable attributes might be used here -(like the default value \verb|changemark.cross|), see +(like the default value \verb|changesymbol.cross|), see section~\ref{graph:changeattrs} for details. The attributes are available as class variables after plotting the @@ -623,7 +619,7 @@ style for outside usage. Additionally, the variable \verb|path| contains the path of the line (even when it wasn't plotted), which might be used to get crossing points, fill areas, etc. -Valid data names to be used when providing data to markers are listed +Valid data names to be used when providing data to symbols are listed in the following table. The character \verb|X| stands for axis names like \verb|x|, \verb|x2|, \verb|y|, etc. @@ -631,7 +627,7 @@ like \verb|x|, \verb|x2|, \verb|y|, etc. \begin{tabular}{ll} data name&description\\ \hline -\texttt{X}&position of the marker\\ +\texttt{X}&position of the symbol\\ \texttt{Xmin}&minimum for the errorbar\\ \texttt{Xmax}&maximum for the errorbar\\ \texttt{dX}&relative size of the errorbar: \texttt{Xmin, Xmax = X-dX, X+Xd}\\ @@ -642,19 +638,19 @@ data name&description\\ \subsection{Lines} -The class \verb|line| is inherited from \verb|mark| and is restricted +The class \verb|line| is inherited from \verb|symbol| and is restricted to line drawing. The constructor takes only \verb|lineattrs| and its default is set to \verb|changelinestyle()|. The other features of the -mark style are turned off. +symbol style are turned off. \subsection{Rectangles} The class \verb|rect| draws filled rectangles into a graph. The size and the position of the rectangles to be plotted can be provided by -the same data names like for the errorbars of the class \verb|mark|. -Indeed, the class \verb|mark| reuses most of the marker code by +the same data names like for the errorbars of the class \verb|symbol|. +Indeed, the class \verb|symbol| reuses most of the symbol code by inheritance, while modifying the errorbar look into a colored filled -rectangle and turing off the marker itself. +rectangle and turing off the symbol itself. The color to be used for the filling of the rectangles is taken from a gradient provided to the constructor by the named parameter @@ -664,15 +660,15 @@ name \verb|color| is used to select the color out of this gradient. \subsection{Texts} Another style to be used within graphs is the class \verb|text|, which -adds the output of text to the class \verb|mark|. The text -position relative to the markers is defined by the two named +adds the output of text to the class \verb|symbol|. The text +position relative to the symbol is defined by the two named parameters \verb|textdx| and \verb|textdy| having a default of \verb|"0 cm"| and \verb|"0.3 cm"|, respectively, which are by default interpreted as visual length. A further named parameter \verb|textattrs| may contain a sequence of text attributes (or just a single attribute). The default for this parameter is \verb|tex.halign.center|. Furthermore the constructor of this class -allows all other attributes of the class \verb|mark|. +allows all other attributes of the class \verb|symbol|. \subsection{Arrows} @@ -692,7 +688,7 @@ argument name&default&description\\ \end{tabularx} \medskip -The arrow allows for data names like the mark and introduces +The arrow allows for data names like the symbol and introduces additionally the data names \verb|size| for the arrow size (as an multiplicator for the sizes provided to the constructor) and \verb|angle| for the arrow direction (in degree). @@ -748,15 +744,15 @@ attribute changer&description\\ \end{tabular} \end{center} -The class \verb|changemark| can be used to cycle throu markers and it +The class \verb|changesymbol| can be used to cycle throu symbols and it provides already various specialized classes as class variables. To -loop over all available markers (cross, plus, square, triangle, +loop over all available symbols (cross, plus, square, triangle, circle, and diamond) the equal named class variables can be used. They -start at that marker they are named of. Thus \verb|changemark.cross()| -cycles throu the sequence starting at the cross marker. Furthermore +start at that symbol they are named of. Thus \verb|changesymbol.cross()| +cycles throu the sequence starting at the cross symbol. Furthermore there are four class variables called \verb|squaretwice|, \verb|triangletwice|, \verb|circletwice|, and \verb|diamondtwice|. -They cycle throu the four fillable markers, but returning the markers +They cycle throu the four fillable symbols, but returning the symbols twice before they go on to the next one. They are intented to be used in combination with \verb|changestrokedfilled| and \verb|changefilledstroked|. -- 2.11.4.GIT