4.4 Module `graph.data`: Data

The following classes provide data for the plot() method of a graph. The classes are implemented in graph.data.

class file( filename, commentpattern=defaultcommentpattern, columnpattern=defaultcolumnpattern, stringpattern=defaultstringpattern, skiphead=0, skiptail=0, every=1, title=notitle, context={}, copy=1, replacedollar=1, columncallback="__column__", **columns)

This class reads data from a file and makes them available to the graph system. filename is the name of the file to be read. The data should be organized in columns.

The arguments commentpattern, columnpattern, and stringpattern are responsible for identifying the data in each line of the file. Lines matching commentpattern are ignored except for the column name search of the last non-empty comment line before the data. By default a line starting with one of the characters "#", "%", or "!" as well as an empty line is treated as a comment.

A non-comment line is analysed by repeatedly matching stringpattern and, whenever the stringpattern does not match, by columnpattern. When the stringpattern matches, the result is taken as the value for the next column without further transformations. When columnpattern matches, it is tried to convert the result to a float. When this fails the result is taken as a string as well. By default, you can write strings with spaces surrounded by """ immediately surrounded by spaces or begin/end of line in the data file. Otherwise """ is not taken to be special.

skiphead and skiptail are numbers of data lines to be ignored at the beginning and end of the file while every selects only every every line from the data.

title is the title of the data to be used in the graph key. A default title is constructed out of filename and **columns. You may set title to None to disable the title.

Finally, columns define columns out of the existing columns from the file by a column number or a mathematical expression (see below). When copy is set the names of the columns in the file (file column names) and the freshly created columns having the names of the dictionary key (data column names) are passed as data to the graph styles. The data columns may hide file columns when names are equal. For unset copy the file columns are not available to the graph styles.

File column names occur when the data file contains a comment line immediately in front of the data (except for empty or empty comment lines). This line will be parsed skipping the matched comment identifier as if the line would be regular data, but it will not be converted to floats even if it would be possible to convert the items. The result is taken as file column names, i.e. a string representation for the columns in the file.

The values of **columns can refer to column numbers in the file starting at 1. The column 0 is also available and contains the line number starting from 1 not counting comment lines, but lines skipped by skiphead, skiptail, and every. Furthermore values of **columns can be strings: file column names or complex mathematical expressions. To refer to columns within mathematical expressions you can also use file column names when they are valid variable identifiers. Equal named items in context will then be hidden. Alternatively columns can be access by the syntax $<number> when replacedollar is set. They will be translated into function calls to columncallback, which is a function to access column data by index or name.

context allows for accessing external variables and functions when evaluating mathematical expressions for columns. Additionally to the identifiers in context, the file column names, the columncallback function and the functions shown in the table ``builtins in math expressions'' at the end of the section are available.

Example:

graph.data.file("test.dat", a=1, b="B", c="2*B+$3")

with test.dat looking like:

# A   B C
1.234 1 2
5.678 3 4

The columns with name "a", "b", "c" will become "[1.234, 5.678]", "[1.0, 3.0]", and

"[4.0,
  10.0]"

, respectively. The columns "A", "B", "C" will be available as well, since copy is enabled by default.

When creating several data instances accessing the same file, the file is read only once. There is an inherent caching of the file contents.

For the sake of completeness we list the default patterns:

defaultcommentpattern: re.compile(r"(#+|!+|%+)\s*")

defaultcolumnpattern: re.compile(r"\"(.*?)\"(\s+|$)")

defaultstringpattern: re.compile(r"(.*?)(\s+|$)")

class function( expression, title=notitle, min=None, max=None, points=100, context={})

This class creates graph data from a function. expression is the mathematical expression of the function. It must also contain the result variable name including the variable the function depends on by assignment. A typical example looks like "y(x)=sin(x)".

title is the title of the data to be used in the graph key. By default expression is used. You may set title to None to disable the title.

min and max give the range of the variable. If not set, the range spans the whole axis range. The axis range might be set explicitly or implicitly by ranges of other data. points is the number of points for which the function is calculated. The points are choosen linearly in terms of graph coordinates.

context allows for accessing external variables and functions. Additionally to the identifiers in context, the variable name and the functions shown in the table ``builtins in math expressions'' at the end of the section are available.

class paramfunction( varname, min, max, expression, title=notitle, points=100, context={})

This class creates graph data from a parametric function. varname is the parameter of the function. min and max give the range for that variable. points is the number of points for which the function is calculated. The points are choosen lineary in terms of the parameter.

expression is the mathematical expression for the parametric function. It contains an assignment of a tuple of functions to a tuple of variables. A typical example looks like "x, y = cos(k), sin(k)".

title is the title of the data to be used in the graph key. By default expression is used. You may set title to None to disable the title.

context allows for accessing external variables and functions. Additionally to the identifiers in context, varname and the functions shown in the table ``builtins in math expressions'' at the end of the section are available.

class values( title="user provided values", **columns): This class creates graph data from externally provided data. Each column is a list of values to be used for that column.
title is the title of the data to be used in the graph key.

class points( data, title="user provided points", addlinenumbers=1, **columns)

This class creates graph data from externally provided data. data is a list of lines, where each line is a list of data values for the columns.

title is the title of the data to be used in the graph key.

The keywords of **columns become the data column names. The values are the column numbers starting from one, when addlinenumbers is turned on (the zeroth column is added to contain a line number in that case), while the column numbers starts from zero, when addlinenumbers is switched off.

class data( data, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns): This class provides graph data out of other graph data. data is the source of the data. All other parameters work like the equally called parameters in graph.data.file. Indeed, the latter is built on top of this class by reading the file and caching its contents in a graph.data.list instance.

class conffile( filename, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns): This class reads data from a config file with the file name filename. The format of a config file is described within the documentation of the ConfigParser module of the Python Standard Library.
Each section of the config file becomes a data line. The options in a section are the columns. The name of the options will be used as file column names. All other parameters work as in graph.data.file and graph.data.data since they all use the same code.

class cbdfile( filename, minrank=None, maxrank=None, title=notitle, context=, copy=1, replacedollar=1, columncallback="__column__", **columns): This is an experimental class to read map data from cbd-files. See http://sepwww.stanford.edu/ftp/World_Map/ for some world-map data.

The builtins in math expressions are listed in the following table: neg&lambda x: -x
abs&lambda x: x < 0 and -x or x
sgn&lambda x: x < 0 and -1 or 1
sqrt&math.sqrt
exp&math.exp
log&math.log
sin&math.sin
cos&math.cos
tan&math.tan
asin&math.asin
acos&math.acos
atan&math.atan
sind&lambda x: math.sin(math.pi/180*x)
cosd&lambda x: math.cos(math.pi/180*x)
tand&lambda x: math.tan(math.pi/180*x)
asind&lambda x: 180/math.pi*math.asin(x)
acosd&lambda x: 180/math.pi*math.acos(x)
atand&lambda x: 180/math.pi*math.atan(x)
norm&lambda x, y: math.hypot(x, y)
splitatvalue&see the splitatvalue description below
pi&math.pi
e&math.e

name value

math refers to Pythons math module. The splitatvalue function is defined as:

splitatvalue( value, *splitpoints): This method returns a tuple (section, value). The section is calculated by comparing value with the values of splitpoints. If splitpoints contains only a single item, section is 0 when value is lower or equal this item and 1 else. For multiple splitpoints, section is 0 when its lower or equal the first item, None when its bigger than the first item but lower or equal the second item, 1 when its even bigger the second item, but lower or equal the third item. It continues to alter between None and 2, 3, etc.

4.4 Module graph.data: Data

4.4 Module `graph.data`: Data